Quick start guide

Installing django-parler

The package can be installed using:

pip install django-parler

Add the following settings:

INSTALLED_APPS += (
    'parler',
)

A brief overview

Creating models

Using the TranslatedFields wrapper, model fields can be marked as translatable:

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

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

    def __unicode__(self):
        return self.title

Accessing fields

Translatable fields can be used like regular fields:

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

Internally, django-parler stores the translated fields in a separate model, with one row per language.

Filtering translations

To query translated fields, use the translated() method:

MyObject.objects.translated(title='cheese omelet')

To access objects in both the current and the configured fallback languages, use:

MyObject.objects.active_translations(title='cheese omelet')

This returns objects in the languages which are considered “active”, which are:

  • The current language
  • The fallback languages when hide_untranslated=False in the PARLER_LANGUAGES setting.

Note

Due to ORM restrictions the query should be performed in a single translated() or active_translations() call.

The active_translations() method typically needs to include a distinct() call to avoid duplicate results of the same object.

Changing the language

The queryset can be instructed to return objects in a specific language:

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

This only sets the language of the object. By default, the current Django language is used.

Use get_current_language() and set_current_language() to change the language on individual objects. There is a context manager to do this temporary:

from parler.utils.context import switch_language

with switch_language(model, 'fr'):
    print model.title

And a function to query just a specific field:

model.safe_translation_getter('title', language_code='fr')

Configuration

By default, the fallback languages are 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': {
        'fallbacks': ['en'],          # defaults to PARLER_DEFAULT_LANGUAGE_CODE
        'hide_untranslated': False,   # the default; let .active_translations() return fallbacks too.
    }
}

Replace None with the SITE_ID when you run a multi-site project with the sites framework. Each SITE_ID can be added as additional entry in the dictionary.