Fixed #5494, #10765, #14924 -- Modified the order in which translations are...

"""

Internationalization support.

"""

from os import path

from django.utils.encoding import force_unicode

from django.utils.functional import lazy, curry

from django.utils.functional import lazy

from django.utils.importlib import import_module

__all__ = ['gettext', 'gettext_noop', 'gettext_lazy', 'ngettext',

    performance effect, as access to the function goes the normal path,

    instead of using __getattr__.

    """

    def __getattr__(self, real_name):

        from django.conf import settings

        if settings.USE_I18N:

            from django.utils.translation import trans_real as trans

            if settings.SETTINGS_MODULE is not None:

                import warnings

                parts = settings.SETTINGS_MODULE.split('.')

                project = import_module(parts[0])

                if path.isdir(path.join(path.dirname(project.__file__), 'locale')):

                    warnings.warn(

                        "Translations in the project directory aren't supported anymore. Use the LOCALE_PATHS setting instead.",

                        PendingDeprecationWarning

                    )

        else:

            from django.utils.translation import trans_null as trans

        setattr(self, real_name, getattr(trans, real_name))

        global _translations

        loc = to_locale(lang)

        res = _translations.get(lang, None)

        if res is not None:

            return res

        loc = to_locale(lang)

        def _translation(path):

            try:

                t = gettext_module.translation('django', path, [loc], DjangoTranslation)

                    res.merge(t)

            return res

        for localepath in settings.LOCALE_PATHS:

            if os.path.isdir(localepath):

                res = _merge(localepath)

        for appname in settings.INSTALLED_APPS:

        for appname in reversed(settings.INSTALLED_APPS):

            app = import_module(appname)

            apppath = os.path.join(os.path.dirname(app.__file__), 'locale')

        if projectpath and os.path.isdir(projectpath):

            res = _merge(projectpath)

        for localepath in reversed(settings.LOCALE_PATHS):

            if os.path.isdir(localepath):

                res = _merge(localepath)

        if res is None:

            if fallback is not None:

                res = fallback

    paths = []

    en_selected = locale.startswith('en')

    en_catalog_missing = True

    # first load all english languages files for defaults

    # paths of requested packages

    for package in packages:

        p = importlib.import_module(package)

        path = os.path.join(os.path.dirname(p.__file__), 'locale')

        paths.append(path)

    # add the filesystem paths listed in the LOCALE_PATHS setting

    paths.extend(list(reversed(settings.LOCALE_PATHS)))

    # first load all english languages files for defaults

    for path in paths:

        try:

            catalog = gettext_module.translation(domain, path, ['en'])

            t.update(catalog._catalog)

    src.append(LibFormatFoot)

    src = ''.join(src)

    return http.HttpResponse(src, 'text/javascript')

Using internationalization in your own projects

===============================================

At runtime, Django looks for translations by following this algorithm:

    * 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``.

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``,

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::

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>`

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.

A tuple of directories where Django looks for translation files.

See :ref:`using-translations-in-your-own-projects`.

Example::

    LOCALE_PATHS = (

        '/home/www/project/common_files/locale',

        '/var/local/translations/locale'

    )

Note that in the paths you add to the value of this setting, if you have the

typical ``/path/to/locale/xx/LC_MESSAGES`` hierarchy, you should use the path to

the ``locale`` directory (i.e. ``'/path/to/locale'``).

.. setting:: LOGGING

LOGGING