Metadata-Version: 1.1
Name: modeltranslation
Version: 0.25
Summary: Modeltranslation is an utility to translate Django model fields.
Home-page: https://github.com/intelligenia/modeltranslation
Author: intelligenia S.L.
Author-email: diego@intelligenia.es
License: MIT
Description: modeltranslation
        ================
        
        Versión en español en `README.es.md <README.es.md>`__
        
        Introduction
        ------------
        
        This application allows you use
        `Django <https://www.djangoproject.com/>`__ model translations easily.
        Everything is based on FieldTranslation, a class that stores the
        translation of each field of your application models.
        
        All the process is transparent and the entries are created when save is
        called.
        
        You will not have to modify FieldTranslation, but you can read the code.
        
        All code in in the github repository:
        https://github.com/intelligenia/modeltranslation
        
        Instructions
        ------------
        
        Installation
        ~~~~~~~~~~~~
        
        This application depends on
        `django-cuser <https://pypi.python.org/pypi/django-cuser>`__ and
        `TinyMCE <https://pypi.python.org/pypi/django-tinymce>`__, so you will
        need to install it and put it in the list of INSTALLED\_APPS before
        modeltranslation.
        
        You are encouraged to use pip to install django-cuser.
        
        The easiest way to install modeltranslation is by installing it from
        `pipy <https://pypi.python.org/pypi/modeltranslation>`__:
        
        .. code:: sh
        
            pip install modeltranslation
        
        Once you've done this, you can install modeltranslation in settings.py:
        
        INSTALLED\_APPS = ( "tinymce", "cuser", "modeltranslation" )
        
        Add IS\_MONOLINGUAL to settings.py
        ----------------------------------
        
        You'll have to include a new setting in settings.py
        IS\_MONOLINGUAL=False. IS\_MONOLINGUAL acts as a switch for
        modeltranslation:
        
        .. code:: python
        
            # modeltranslation only works when IS_MONOLINGUAL is False
            IS_MONOLINGUAL=False
        
        Add TRANSLATABLE\_MODEL\_MODULES to settings.py
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Add file setting TRANSLATABLE\_MODEL\_MODULES to settings.py.
        TRANSLATABLE\_MODEL\_MODULES contains a list of module paths that will
        be translated. For example:
        
        .. code:: python
        
            TRANSLATABLE_MODEL_MODULES = ["app1.models", "app2.models", "fees.models", "menus.models", ...]
        
        Import addtranslations
        ----------------------
        
        Import **addtranslations** if each of your models.py files:
        
        .. code:: python
        
            from modeltranslation.translation import addtranslations
        
        After that, you'll have to call **addtranslations** at the end of this
        file:
        
        .. code:: python
        
            addtranslations(__name__)
        
        This call adds an observer that saves translations when **save** model
        method is executed.
        
        Add translatable\_fields to your models
        ---------------------------------------
        
        Modify your models including a meta field "translatable\_fields". This
        field is a list with the fields you want to translate.
        
        For example:
        
        .. code:: python
        
            from django.db import models
        
            class Event(models.Model):
                
                name = models.CharField(blank=False, max_length=150, verbose_name=u"Name", help_text=u"Name of the event.")
                description = models.TextField(blank=False, verbose_name=u"Description", help_text=u"Long description of the event.")
                short_description = models.CharField(blank=False, max_length=150, verbose_name=u"Short description", help_text=u"Short description of the event.")
        
                #...
        
                ## Event Meta
                class Meta:
                    verbose_name = "event"
                    verbose_name_plural = "events"
                    translatable_fields = ("name", "description", "short_description")
        
        And that's all!
        ~~~~~~~~~~~~~~~
        
        Now you have everything configurated and can use modeltranslation
        translations.
        
        How to use translations in ModelForms
        -------------------------------------
        
        Make your ModelForm object inherits of TranslatableModelForm. This will
        include automatically the extra fields for each language you have in
        your website.
        
        .. code:: python
        
            from modeltranslation.forms import TranslatableModelForm
        
            class EventForm(TranslatableModelForm):
                pass
        
        If you need to modify any of the fields in **init** method (for example
        by changing the widget of one field), you'll have to call
        \_add\_translation\_form\_fields after your changes.
        
        For example:
        
        .. code:: python
        
                # EventForm __init__ 
                def __init__(self, event, *args, **kwargs):
                    super(EventForm, self).__init__(*args, **kwargs)
                    
                    # Adds TinyMCE editor but we also want this editor in other
                    # languages' description fields
                    self.fields["description"].widget = TinyMCE()
                    
                    # Manually adition of translation fields
                    self._add_translation_form_fields()
        
        Dynamic translations in Django templates
        ----------------------------------------
        
        1. Include modeltranslation filters in each template you wan to use this
           special filters.
        
        .. code:: django
        
            {% load modeltranslation_tags %}
        
        2. Use filter "\_" with the object and one of its fields. This filter
           will return the translation of that field in the current language.
        
        For example:
        
        .. code:: django
        
            {{ event|_:"name" }} {# Translates event name #}
            {{ event.area|_:"name" }} {# Translates area name #}
        
        Dynamic translations in code
        ----------------------------
        
        This application injects a new method to each translatable model:
        **get\_trans\_attr**. This method returns the translation of the
        attribute in the current language (if it exists), otherwise returns the
        default value for this attribute:
        
        For example:
        
        .. code:: python
        
        
            # Original event name
            original_event_name event.name
        
            # Translated event name
            translated_event_name event.get_trans_attr("name")
        
        Contact and suggestions
        -----------------------
        
        -  Create a new issue in this repository.
        -  Email me at diegoREMOVE\_THIS@intelligeniaREMOVE\_THIS.com
        
Keywords: modeltranslation translations
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: MIT License
