PageRenderTime 5ms CodeModel.GetById 1ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/howto/i18n.txt

https://code.google.com/p/mango-py/
Plain Text | 121 lines | 99 code | 22 blank | 0 comment | 0 complexity | 0c81c9fcac7f22b61a511f042ee32a52 MD5 | raw file
  1.. _using-translations-in-your-own-projects:
  2
  3===============================================
  4Using internationalization in your own projects
  5===============================================
  6
  7At runtime, Django builds an in-memory unified catalog of literals-translations.
  8To achieve this it looks for translations by following this algorithm regarding
  9the order in which it examines the different file paths to load the compiled
 10:term:`message files <message file>` (``.mo``) and the precedence of multiple
 11translations for the same literal:
 12
 13    1. The directories listed in :setting:`LOCALE_PATHS` have the highest
 14       precedence, with the ones appearing first having higher precedence than
 15       the ones appearing later.
 16    2. Then, it looks for and uses if it exists a ``locale`` directory in each
 17       of the installed apps listed in :setting:`INSTALLED_APPS`.  The ones
 18       appearing first have higher precedence than the ones appearing later.
 19    3. Then, it looks for a ``locale`` directory in the project directory, or
 20       more accurately, in the directory containing your settings file.
 21    4. Finally, the Django-provided base translation in ``django/conf/locale``
 22       is used as a fallback.
 23
 24.. deprecated:: 1.3
 25    Lookup in the ``locale`` subdirectory of the directory containing your
 26    settings file (item 3 above) is deprecated since the 1.3 release and will be
 27    removed in Django 1.5. You can use the :setting:`LOCALE_PATHS` setting
 28    instead, by listing the absolute filesystem path of such ``locale``
 29    directory in the setting value.
 30
 31.. seealso::
 32
 33    The translations for literals included in JavaScript assets are looked up
 34    following a similar but not identical algorithm. See the
 35    :ref:`javascript_catalog view documentation <javascript_catalog-view>` for
 36    more details.
 37
 38In all cases the name of the directory containing the translation is expected to
 39be named using :term:`locale name` notation. E.g. ``de``, ``pt_BR``, ``es_AR``,
 40etc.
 41
 42This way, you can write applications that include their own translations, and
 43you can override base translations in your project path. Or, you can just build
 44a big project out of several apps and put all translations into one big common
 45message file specific to the project you are composing. The choice is yours.
 46
 47.. note::
 48
 49    If you're using manually configured settings, as described in
 50    :ref:`settings-without-django-settings-module`, the ``locale`` directory in
 51    the project directory will not be examined, since Django loses the ability
 52    to work out the location of the project directory. (Django normally uses the
 53    location of the settings file to determine this, and a settings file doesn't
 54    exist if you're manually configuring your settings.)
 55
 56All message file repositories are structured the same way. They are:
 57
 58    * All paths listed in :setting:`LOCALE_PATHS` in your settings file are
 59      searched for ``<language>/LC_MESSAGES/django.(po|mo)``
 60    * ``$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)`` --
 61      deprecated, see above.
 62    * ``$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)``
 63    * ``$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)``
 64
 65To create message files, you use the :djadmin:`django-admin.py makemessages <makemessages>`
 66tool. You only need to be in the same directory where the ``locale/`` directory
 67is located. And you use :djadmin:`django-admin.py compilemessages <compilemessages>`
 68to produce the binary ``.mo`` files that are used by ``gettext``. Read the
 69:doc:`/topics/i18n/localization` document for more details.
 70
 71You can also run ``django-admin.py compilemessages --settings=path.to.settings``
 72to make the compiler process all the directories in your :setting:`LOCALE_PATHS`
 73setting.
 74
 75Finally, you should give some thought to the structure of your translation
 76files. If your applications need to be delivered to other users and will
 77be used in other projects, you might want to use app-specific translations.
 78But using app-specific translations and project-specific translations could
 79produce weird problems with ``makemessages``: It will traverse all directories
 80below the current path and so might put message IDs into a unified, common
 81message file for the current project that are already in application message
 82files.
 83
 84The easiest way out is to store applications that are not part of the project
 85(and so carry their own translations) outside the project tree. That way,
 86``django-admin.py makemessages``, when ran on a project level will only extract
 87strings that are connected to your explicit project and not strings that are
 88distributed independently.
 89
 90Using translations outside views and templates
 91==============================================
 92
 93While Django provides a rich set of i18n tools for use in views and templates,
 94it does not restrict the usage to Django-specific code. The Django translation
 95mechanisms can be used to translate arbitrary texts to any language that is
 96supported by Django (as long as an appropriate translation catalog exists, of
 97course). You can load a translation catalog, activate it and translate text to
 98language of your choice, but remember to switch back to original language, as
 99activating a translation catalog is done on per-thread basis and such change
100will affect code running in the same thread.
101
102For example::
103
104    from django.utils import translation
105    def welcome_translated(language):
106        cur_language = translation.get_language()
107        try:
108            translation.activate(language)
109            text = translation.ugettext('welcome')
110        finally:
111            translation.activate(cur_language)
112        return text
113
114Calling this function with the value 'de' will give you ``"Willkommen"``,
115regardless of :setting:`LANGUAGE_CODE` and language set by middleware.
116
117Functions of particular interest are ``django.utils.translation.get_language()``
118which returns the language used in the current thread,
119``django.utils.translation.activate()`` which activates a translation catalog
120for the current thread, and ``django.utils.translation.check_for_language()``
121which checks if the given language is supported by Django.