mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-09-26 12:09:19 +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

38
docs/topics/i18n/deployment.txt
View file

@ -171,16 +171,36 @@ in ``request.LANGUAGE_CODE``.
How Django discovers translations
---------------------------------
As described in :ref:`using-translations-in-your-own-projects`,
at runtime, Django looks for translations by following this algorithm:
As described in :ref:`using-translations-in-your-own-projects`, Django 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``,

35
docs/topics/i18n/internationalization.txt
View file

@ -348,8 +348,6 @@ translation method!
Working with lazy translation objects
-------------------------------------
.. highlightlang:: python
Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
and utility functions is a common operation. When you're working with these
objects elsewhere in your code, you should ensure that you don't accidentally
@ -633,6 +631,8 @@ There are also simple filters available for convenience:
Specifying translation strings: In JavaScript code
==================================================
.. highlightlang:: python
Adding translations to JavaScript poses some problems:
* JavaScript code doesn't have access to a ``gettext`` implementation.
@ -647,6 +647,8 @@ Django provides an integrated solution for these problems: It passes the
translations into JavaScript, so you can call ``gettext``, etc., from within
JavaScript.
.. _javascript_catalog-view:
The ``javascript_catalog`` view
-------------------------------
@ -657,8 +659,9 @@ The ``javascript_catalog`` view
The main solution to these problems is the :meth:`django.views.i18n.javascript_catalog`
view, which sends out a JavaScript code library with functions that mimic the
``gettext`` interface, plus an array of translation strings. Those translation
strings are taken from the application, project or Django core, according to what
you specify in either the info_dict or the URL.
strings are taken from applications or Django core, according to what you
specify in either the info_dict or the URL. Paths listed in
:setting:`LOCALE_PATHS` are also included.
You hook it up like this::
@ -676,6 +679,11 @@ that contains a ``locale`` directory. If you specify multiple packages, all
those catalogs are merged into one catalog. This is useful if you have
JavaScript that uses strings from different applications.
The precedence of translations is such that the packages appearing later in the
``packages`` argument have higher precedence than the ones appearing at the
beginning, this is important in the case of clashing translations for the same
literal.
By default, the view uses the ``djangojs`` gettext domain. This can be
changed by altering the ``domain`` argument.
@ -691,10 +699,25 @@ different apps and this changes often and you don't want to pull in one big
catalog file. As a security measure, these values can only be either
``django.conf`` or any package from the :setting:`INSTALLED_APPS` setting.
The JavaScript translations found in the paths listed in the
:setting:`LOCALE_PATHS` setting are also always included. To keep consistency
with the translations lookup order algorithm used for Python and templates, the
directories listed in :setting:`LOCALE_PATHS` have the highest precedence with
the ones appearing first having higher precedence than the ones appearing
later.
.. versionchanged:: 1.3
Directories listed in ``LOCALE_PATHS`` weren't included in the lookup
algorithm until version 1.3.
Using the JavaScript translation catalog
----------------------------------------
To use the catalog, just pull in the dynamically generated script like this::
.. highlightlang:: javascript
To use the catalog, just pull in the dynamically generated script like this:
.. code-block:: html+django
<script type="text/javascript" src="{% url django.views.i18n.javascript_catalog %}"></script>
@ -751,6 +774,8 @@ to produce proper pluralizations).
The ``set_language`` redirect view
==================================
.. highlightlang:: python
.. function:: set_language(request)
As a convenience, Django comes with a view, :meth:`django.views.i18n.set_language`,