mirror of
https://github.com/django/django.git
synced 2024-12-25 10:35:48 +00:00
f6e38f3800
This is slightly backward-incompatible (could result in changed final translations for literals appearing multiple times in different .po files but with different translations). Translations are now read in the following order (from lower to higher priority): For the 'django' gettext domain: * Django translations * INSTALLED_APPS apps translations (with the ones listed first having higher priority) * settings/project path translations (deprecated, see below) * LOCALE_PATHS translations (with the ones listed first having higher priority) For the 'djangojs' gettext domain: * Python modules whose names are passed to the javascript_catalog view * LOCALE_PATHS translations (with the ones listed first having higher priority, previously they weren't included) Also, automatic loading of translations from the 'locale' subdir of the settings/project path is now deprecated. Thanks to vanschelven, vbmendes and an anonymous user for reporting issues, to vanschelven, Claude Paroz and an anonymous contributor for their initial work on fixes and to Jannis Leidel and Claude for review and discussion. git-svn-id: http://code.djangoproject.com/svn/django/trunk@15441 bcc190cf-cafb-0310-a4f2-bffc1f526a37
122 lines
6.0 KiB
Plaintext
122 lines
6.0 KiB
Plaintext
.. _using-translations-in-your-own-projects:
|
|
|
|
===============================================
|
|
Using internationalization in your own projects
|
|
===============================================
|
|
|
|
At runtime, Django builds an in-memory unified catalog of literals-translations.
|
|
To achieve this it looks for translations by following this algorithm regarding
|
|
the order in which it examines the different file paths to load the compiled
|
|
:term:`message files <message file>` (``.mo``) and the precedence of multiple
|
|
translations for the same literal:
|
|
|
|
1. The directories listed in :setting:`LOCALE_PATHS` have the highest
|
|
precedence, with the ones appearing first having higher precedence than
|
|
the ones appearing later.
|
|
2. Then, it looks for and uses if it exists a ``locale`` directory in each
|
|
of the installed apps listed in :setting:`INSTALLED_APPS`. The ones
|
|
appearing first have higher precedence than the ones appearing later.
|
|
3. Then, it looks for a ``locale`` directory in the project directory, or
|
|
more accurately, in the directory containing your settings file.
|
|
4. Finally, the Django-provided base translation in ``django/conf/locale``
|
|
is used as a fallback.
|
|
|
|
.. deprecated:: 1.3
|
|
Lookup in the ``locale`` subdirectory of the directory containing your
|
|
settings file (item 3 above) is deprecated since the 1.3 release and will be
|
|
removed in Django 1.5. You can use the :setting:`LOCALE_PATHS` setting
|
|
instead, by listing the absolute filesystem path of such ``locale``
|
|
directory in the setting value.
|
|
|
|
.. seealso::
|
|
|
|
The translations for literals included in JavaScript assets are looked up
|
|
following a similar but not identical algorithm. See the
|
|
:ref:`javascript_catalog view documentation <javascript_catalog-view>` for
|
|
more details.
|
|
|
|
In all cases the name of the directory containing the translation is expected to
|
|
be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
|
|
etc.
|
|
|
|
This way, you can write applications that include their own translations, and
|
|
you can override base translations in your project path. Or, you can just build
|
|
a big project out of several apps and put all translations into one big common
|
|
message file specific to the project you are composing. The choice is yours.
|
|
|
|
.. note::
|
|
|
|
If you're using manually configured settings, as described in
|
|
:ref:`settings-without-django-settings-module`, the ``locale`` directory in
|
|
the project directory will not be examined, since Django loses the ability
|
|
to work out the location of the project directory. (Django normally uses the
|
|
location of the settings file to determine this, and a settings file doesn't
|
|
exist if you're manually configuring your settings.)
|
|
|
|
All message file repositories are structured the same way. They are:
|
|
|
|
* All paths listed in ``LOCALE_PATHS`` in your settings file are
|
|
searched for ``<language>/LC_MESSAGES/django.(po|mo)``
|
|
* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` --
|
|
deprecated, see above.
|
|
* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
|
|
* ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
|
|
|
|
To create message files, you use the :djadmin:`django-admin.py makemessages <makemessages>`
|
|
tool. You only need to be in the same directory where the ``locale/`` directory
|
|
is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
|
|
to produce the binary ``.mo`` files that are used by ``gettext``. Read the
|
|
:doc:`/topics/i18n/localization` document for more details.
|
|
|
|
You can also run ``django-admin.py compilemessages --settings=path.to.settings``
|
|
to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
|
|
setting.
|
|
|
|
Finally, you should give some thought to the structure of your translation
|
|
files. If your applications need to be delivered to other users and will
|
|
be used in other projects, you might want to use app-specific translations.
|
|
But using app-specific translations and project-specific translations could
|
|
produce weird problems with ``makemessages``: It will traverse all directories
|
|
below the current path and so might put message IDs into a unified, common
|
|
message file for the current project that are already in application message
|
|
files.
|
|
|
|
The easiest way out is to store applications that are not part of the project
|
|
(and so carry their own translations) outside the project tree. That way,
|
|
``django-admin.py makemessages``, when ran on a project level will only extract
|
|
strings that are connected to your explicit project and not strings that are
|
|
distributed independently.
|
|
|
|
Using translations outside views and templates
|
|
==============================================
|
|
|
|
While Django provides a rich set of i18n tools for use in views and templates,
|
|
it does not restrict the usage to Django-specific code. The Django translation
|
|
mechanisms can be used to translate arbitrary texts to any language that is
|
|
supported by Django (as long as an appropriate translation catalog exists, of
|
|
course). You can load a translation catalog, activate it and translate text to
|
|
language of your choice, but remember to switch back to original language, as
|
|
activating a translation catalog is done on per-thread basis and such change
|
|
will affect code running in the same thread.
|
|
|
|
For example::
|
|
|
|
from django.utils import translation
|
|
def welcome_translated(language):
|
|
cur_language = translation.get_language()
|
|
try:
|
|
translation.activate(language)
|
|
text = translation.ugettext('welcome')
|
|
finally:
|
|
translation.activate(cur_language)
|
|
return text
|
|
|
|
Calling this function with the value 'de' will give you ``"Willkommen"``,
|
|
regardless of :setting:`LANGUAGE_CODE` and language set by middleware.
|
|
|
|
Functions of particular interest are ``django.utils.translation.get_language()``
|
|
which returns the language used in the current thread,
|
|
``django.utils.translation.activate()`` which activates a translation catalog
|
|
for the current thread, and ``django.utils.translation.check_for_language()``
|
|
which checks if the given language is supported by Django.
|