django-parler 0.9.1

Configuration

Add the following settings:

INSTALLED_APPS += (
    'parler',
)

By default, the fallback language is the same as LANGUAGE_CODE. The fallback language can be changed in the settings:

PARLER_DEFAULT_LANGUAGE_CODE = 'en'

Optionally, the admin tabs can be configured too:

PARLER_LANGUAGES = {
    # Global site
    1: (
        {'code': 'en',},
        {'code': 'en-us',},
        {'code': 'it',},
        {'code': 'nl',},
    ),
    # US site
    2: (
        {'code': 'en-us',},
        {'code': 'en',},
    ),
    # IT site
    3: (
        {'code': 'it',},
        {'code': 'en',},
    ),
    # NL site
    3: (
        {'code': 'nl',},
        {'code': 'en',},
    ),
    'default': {
        'fallback': 'en',  # defaults to PARLER_DEFAULT_LANGUAGE_CODE
    }
}

Basic example

Extend the model class:

from django.db import models
from parler.models import TranslatableModel, TranslatedFields


class MyModel(TranslatableModel):
    translations = TranslatedFields(
        title = models.CharField(_("Title"), max_length=200)
    )

    class Meta:
        verbose_name = _("MyModel")

    def __unicode__(self):
        return self.title

Now, the title field is translated.

Using translated fields

Translated fields can be accessed directly:

>>> from django.utils import translation
>>> translation.activate('en')

>>> object = MyModel.objects.all()[0]
>>> object.get_current_language()
'en'
>>> object.title
u'cheese omelet'

>>> object.set_current_language('fr')       # Only switches
>>> object.title = "omelette du fromage"    # Translation is created on demand.
>>> object.save()

>>> objects = MyModel.objects.language('fr').all()
>>> objects[0].title
u'omelette du fromage'

When an attribute is not translated yet, the default language (set by PARLER_DEFAULT_LANGUAGE_CODE or PARLER_DEFAULT_LANGUAGE_CODE['default']['fallback']) will be retured.

Querying translated attributes

Currently, this package doesn’t improve the QuerySet API to access translated fields. Hence, simply access the translated fields like any normal relation:

object = MyObject.objects.filter(translations__title='omelette')

translation1 = myobject.translations.all()[0]

Note that due to the Django ORM design, the query for translated attributes should typically occur within a single .filter(..) call. When using .filter(..).filter(..), the ORM turns that into 2 separate joins on the translations table. See the ORM documentation for more details.

Advanced example

The translated model can be constructed manually too:

from django.db import models
from parler.models import TranslatableModel, TranslatedFieldsModel
from parler.managers import TranslatedManager
from parler.fields import TranslatedField


class MyModel(TranslatableModel):
    title = TranslatedField()  # Optional, explicitly mention the field

    objects = TranslatedManager()

    class Meta:
        verbose_name = _("MyModel")

    def __unicode__(self):
        return self.title


class MyModel_Translations(TranslatedFieldsModel):
    master = models.ForeignKey(MyModel, related_name='translations', null=True)
    title = models.CharField(_("Title"), max_length=200)

    class Meta:
        verbose_name = _("MyModel translation")

TODO

• Unittests and documentation on RTD.

• ModelAdmin.prepopulated_fields doesn’t work yet (you can use get_prepopulated_fields() as workaround).

• The admin forms use the standard form widgets instead of the admin overrides.

• The list code currently performs one query per object. This needs to be reduced.

• Preferably, the TranslatedField proxy on the model should behave like a RelatedField, if that would nicely with the ORM too.