Django-multilingual-DS9 is a branch of django-multilingual, forked from django-multilingual-ng, with restructured core.
Compatibility:
- Django 1.3
- Django 1.4
Django-multilingual-ds9 does not have to be fully compatible with django-multilingual-ng, but basic features should not differ.
- Use only language codes from
LANGUAGES
setting. - Model structure
FIELD_NAME
returns translation of field for current language orNone
if no translation exists.FIELD_NAME_any
returns translation of field for current language or fallback language or default language orNone
if neither translation exists. Fallback language codes are only those with two letters and are used only if available inLANGUAGES
setting.FIELD_NAME_language
returns translation of field for the language orNone
if translation does not exist.RELATED_NAME
(default: translations) returns manager for translation model with filter to master object.
- Queries
get/filter/exclude(FIELD_NAME)
creates LEFT OUTER JOIN to translation table with condition for current language and required filter. Take care if you are usingFIELD_NAME__isnull=True
lookup, because this query returns both objects with missing translations and objects with missing field in translation.get/filter/exclude(FIELD_NAME_lanaguge)
creates LEFT OUTER JOIN to translation table with condition for the language and required filter.order_by/values/values_list(FIELD_NAME)
works same as filter-like queries. Remember that these will keep objects with no translation in result set unless you manually remove them.order_by/values/values_list(FIELD_NAME_language)
same as above.select_related(RELATED_NAME)
works as expected, tries to cache translation in other query.get/filter/exclude(RELATED_NAME)
selection by existence and parameters of whole translation object.
- Administration
search_fields
does not handleFIELD_NAME_LANGCODE
, you need to use regular foreign key lookupRELATED_NAME__FIELD_NAME
- Django admin validation is rigid and does not handle customized models, especially virtual fields which are used here. Thus it the supported solution is to write your own form for ModelAdmins if you want to do some changes and not to use ModelAdmin attributes for form customizing.
You may see tests for more specific usage
from django import models
from multilingual import MultilingualModel
class Example(MultilingualModel):
some_field = models.IntegerField()
class Translation:
trans_field = models.CharField(max_length=20)
e = Example.objects.create()
# get translation for current language
e.trans_field
# get translation with fallback
e.trans_field_any
# returns all translation objects
e.translations.all()
# Filter objects by translation field
qs = Example.objects.filter(trans_field='some')
#!! This will return objects with no translation and objects with missing trans_field translation
qs = Example.objects.filter(trans_field__isnull=True)
#!! This also may contain several None objects if translations are missing
qs = Example.objects.values_list('trans_field', flat=True)
# Get object with translation in one query
Example.objects.select_related('translations').get(pk=1)
# Get objects with missing translation
Example.objects.filter(translation__isnull=True)
# Change current language
from django.utils.translation import activate
activate('cs')
# Force usage of specific language in multilingual code
from multilingual import language
language.lock('cs')
language.release()
To run tests for multilingual just set
TEST_RUNNER = 'multilingual.tests.MultilingualTestSuiteRunner'
in your settings. And run in your project
python manage.py test multilingual