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.