django-parler 1.0b1

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 = {
    None: (
        {'code': 'en',},
        {'code': 'en-us',},
        {'code': 'it',},
        {'code': 'nl',},
    ),
    'default': {
        'fallback': 'en',             # defaults to PARLER_DEFAULT_LANGUAGE_CODE
        'hide_untranslated': False,   # the default; let .active_translations() return fallbacks too.
    }
}

When using settings.SITE_ID which is a setting of the sites framework (django.contrib.sites) the PARLER_LANGUAGES dict can contain site specific settings and the special None key is no longer used:

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
        'hide_untranslated': False,   # the default; let .active_translations() return fallbacks too.
    }
}

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.

from parler.utils import get_active_language_choices

MyObject.objects.filter(
    translations__language_code__in=get_active_language_choices(),
    translations__slug='omelette'
)

MyObject.objects.translated(get_active_language_choices(), slug='omelette')

MyObject.objects.active_translations(slug='omelette')

Advanced example

The translated model can be constructed manually too:

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


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

    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")

Missing translation fallbacks

When a translation is missing, the fallback language is used. However, when an object only exists in a different language, this still fails.

This package provides 3 solutions to this problem:

1. Declare the translated attribute explicitly with any_language=True:

   class MyModel(TranslatableModel):
       title = TranslatedField(any_language=True)

   Now, the title will try to fetch one of the existing languages from the database.

2. Use model.safe_translation_getter("fieldname", any_language=True) on attributes which don’t have an any_language=True setting.

3. Use a try .. catch TranslationDoesNotExist block for custom handling. Because this exception inherits from AttibuteError, templates typically display empty values by default.

4. Avoid fetching those objects using something like: queryset.active_translations() or queryset.filter(translations__language_code__in=('nl', 'en')).distinct(). Note that the same ORM restrictions apply here.

Django 1.4 note

When using Django 1.4, there is a small tweak you’ll have to make in the admin. Instead of using fieldsets = .., use declared_fieldsets = .. on the ModelAdmin definition. The Django 1.4 admin validation doesn’t actualy check the form fields, but only checks whether the fields exist in the model - which they obviously don’t. Using declared_fieldsets instead of fieldsets circumvents this check.