mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 19:08:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Fixed #5494, #10765, #14924 -- Modified the order in which translations are read when composing the final translation to offer at runtime.

Browse source 
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
This commit is contained in:
Ramiro Morales 2011-02-07 18:48:40 +00:00
parent 5718a678e5
commit f6e38f3800
16 changed files with 272 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

64
docs/howto/i18n.txt
View file

@ -4,15 +4,36 @@
Using internationalization in your own projects
===============================================
At runtime, Django looks for translations by following this algorithm:
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:
* First, it looks for a ``locale`` directory in the directory containing
your settings file.
* Second, it looks for a ``locale`` directory in the project directory.
* Third, it looks for a ``locale`` directory in each of the installed apps.
It does this in the reverse order of INSTALLED_APPS
* Finally, it checks the Django-provided base translation in
``django/conf/locale``.
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``,
@ -20,8 +41,8 @@ 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 project
message file. The choice is yours.
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::
@ -34,10 +55,11 @@ message file. The choice is yours.
All message file repositories are structured the same way. They are:
* ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
* ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
* All paths listed in ``LOCALE_PATHS`` in your settings file are
searched in that order for ``<language>/LC_MESSAGES/django.(po|mo)``
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>`
@ -50,22 +72,18 @@ 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.
Application message files are a bit complicated to discover -- they need the
:class:`~django.middleware.locale.LocaleMiddleware`. If you don't use the
middleware, only the Django message files and project message files will be
installed and available at runtime.
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 translations could produce
weird problems with ``makemessages``: It will traverse all directories below
the current path and so might put message IDs into the project message file
that are already in application message files.
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`` on the project level will only translate
``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.