Installation¶
Requirements¶
Modeltranslation | Python | Django |
---|---|---|
>=0.4 | 2.5 - 2-7 | 1.3 - 1.4 |
<=0.3 | 2.4 - 2.7 | 1.0 - 1.4 |
Using Pip¶
$ pip install django-modeltranslation
Using the Source¶
Get a source tarball from github or pypi, unpack, then install with:
$ python setup.py install
Note
As an alternative, if you don’t want to mess with any packaging tool,
unpack the tarball and copy/move the modeltranslation directory
to a path listed in your PYTHONPATH
environment variable.
Setup¶
To setup the application please follow these steps. Each step is described in detail in the following sections:
- Add the
modeltranslation
app to theINSTALLED_APPS
variable of your project’ssettings.py
. - Configure your
LANGUAGES
insettings.py
. - Create a
translation.py
in your app directory and registerTranslationOptions
for every model you want to translate. - Sync the database using
manage.py syncdb
(note that this only applies if the models registered in thetranslations.py
did not have been synced to the database before. If they did - read further down what to do in that case.
Configure the Project’s settings.py
¶
Required Settings¶
The following variables have to be added to or edited in the project’s
settings.py
:
INSTALLED_APPS
¶
Make sure that the modeltranslation
app is listed in your
INSTALLED_APPS
variable:
INSTALLED_APPS = (
...
'modeltranslation',
....
)
Note
Also make sure that the app can be found on a path contained in your
PYTHONPATH
environment variable.
LANGUAGES
¶
The LANGUAGES
variable must contain all languages used for translation. The
first language is treated as the default language.
The modeltranslation application uses the list of languages to add localized
fields to the models registered for translation. To use the languages de
and en
in your project, set the LANGUAGES
variable like this (where
de
is the default language):
gettext = lambda s: s
LANGUAGES = (
('de', gettext('German')),
('en', gettext('English')),
)
Note
The gettext
lambda function is not a feature of modeltranslation, but
rather required for Django to be able to (statically) translate the verbose
names of the languages using the standard i18n
solution.
Advanced Settings¶
Modeltranslation also has some advanced settings to customize its behaviour:
MODELTRANSLATION_DEFAULT_LANGUAGE
¶
New in version 0.3.
Default: None
To override the default language as described in LANGUAGES,
you can define a language in MODELTRANSLATION_DEFAULT_LANGUAGE
. Note that
the value has to be in settings.LANGUAGES
, otherwise an
ImproperlyConfigured
exception will be raised.
Example:
MODELTRANSLATION_DEFAULT_LANGUAGE = 'en'
MODELTRANSLATION_TRANSLATION_FILES
¶
New in version 0.4.
Default: ()
(empty tuple)
Modeltranslation uses an autoregister feature similiar to the one in Django’s
admin. The autoregistration process will look for a translation.py
file in the root directory of each application that is in INSTALLED_APPS
.
A setting MODELTRANSLATION_TRANSLATION_FILES
is provided to limit or extend
the modules that are taken into account.
Syntax:
MODELTRANSLATION_TRANSLATION_FILES = (
'<APP1_MODULE>.translation',
'<APP2_MODULE>.translation',
)
Example:
MODELTRANSLATION_TRANSLATION_FILES = (
'news.translation',
'projects.translation',
)
Note
Modeltranslation up to version 0.3 used a single project wide
registration file which was defined through
MODELTRANSLATION_TRANSLATION_REGISTRY = '<PROJECT_MODULE>.translation'
.
For backwards compatibiliy the module defined through this setting is
automatically added to MODELTRANSLATION_TRANSLATION_FILES
. A
DeprecationWarning
is issued in this case.
MODELTRANSLATION_CUSTOM_FIELDS
¶
Default: ()
(empty tuple)
New in version 0.3.
Modeltranslation
officially supports CharField
and TextField
.
New in version 0.4.
Support for FileField
and ImageField
.
In most cases subclasses of the supported fields will work fine, too. Other
fields aren’t supported and will throw an ImproperlyConfigured
exception.
The list of supported fields can be extended by defining a tuple of field
names in your settings.py
.
Example:
MODELTRANSLATION_CUSTOM_FIELDS = ('MyField', 'MyOtherField',)
Warning
This just prevents modeltranslation from throwing an
ImproperlyConfigured
exception. Any non text-like field will most
likely fail in one way or another. The feature is considered experimental
and might be replaced by a more sophisticated mechanism in future versions.
MODELTRANSLATION_DEBUG
¶
Default: settings.DEBUG
New in version 0.4.
Used for modeltranslation related debug output. Currently setting it to
False
will just prevent Django’s development server from printing the
Registered xx models for translation
message to stdout.