Fixed #10260 - Refactored internationalization documentation. Thanks, Ramiro Morales.

.. _howto-i18n:

.. _using-translations-in-your-own-projects:

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

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 application directory

      of the view that's being called. If it finds a translation for the

      selected language, the translation will be installed.

    * Next, it looks for a ``locale`` directory in the project directory. If it

      finds a translation, the translation will be installed.

    * Finally, it checks the Django-provided base translation in

      ``django/conf/locale``.

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 project

message file. 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:

    * ``$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)``

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

:ref:`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.

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.

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

strings that are connected to your explicit project and not strings that are

distributed independently.

   deployment/index

   error-reporting

   initial-data

   i18n

   jython

   legacy-databases

   outputting-csv

    * Join the `Django i18n mailing list`_ and introduce yourself.

    * Make sure you read the notes about :ref:`specialties-of-django-i18n`.

    * Create translations using the methods described in the

      :ref:`i18n documentation <topics-i18n>`. For this you will use the

      ``django-admin.py makemessages`` tool. In this particular case it should

      be run from the top-level ``django`` directory of the Django source tree.

      :ref:`localization documentation <topics-i18n-localization>`. For this

      you will use the ``django-admin.py makemessages`` tool. In this

      particular case it should be run from the top-level ``django`` directory

      of the Django source tree.

      The script runs over the entire Django source tree and pulls out all

      strings marked for translation. It creates (or updates) a message file in

      the directory ``conf/locale`` (for example for ``pt-BR``, the file will be

      ``conf/locale/pt-br/LC_MESSAGES/django.po``).

      the directory ``conf/locale`` (for example for ``pt_BR``, the file will be

      ``conf/locale/pt_BR/LC_MESSAGES/django.po``).

    * Make sure that ``django-admin.py compilemessages -l <lang>`` runs without

      producing any warnings.

      ``-d djangojs`` command line option to the ``django-admin.py``

      invocations).

    * Create a diff of the ``.po`` file(s) against the current Subversion trunk.

    * Optionally, review and update the ``conf/locale/<locale>/formats.py``

      file to describe the date, time and numbers formatting particularities of

      your locale. See :ref:`format-localization` for details.

    * Create a diff against the current Subversion trunk.

    * Open a ticket in Django's ticket system, set its ``Component`` field to

      ``Translations``, and attach the patch to it.

Default: ``'en-us'``

A string representing the language code for this installation. This should be in

standard language format. For example, U.S. English is ``"en-us"``. See

:ref:`topics-i18n`.

standard :term:`language format<language code>`. For example, U.S. English is

``"en-us"``. See :ref:`topics-i18n`.

.. setting:: LANGUAGE_COOKIE_NAME

.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py

The list is a tuple of two-tuples in the format (language code, language

name) -- for example, ``('ja', 'Japanese')``. This specifies which languages

are available for language selection. See :ref:`topics-i18n`.

The list is a tuple of two-tuples in the format ``(language code, language

name)``, the ``language code`` part should be a

:term:`language name<language code>` -- for example, ``('ja', 'Japanese')``.

This specifies which languages are available for language selection. See

:ref:`topics-i18n`.

Generally, the default value should suffice. Only set this setting if you want

to restrict language selection to a subset of the Django-provided languages.

Default: ``()`` (Empty tuple)

A tuple of directories where Django looks for translation files.

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

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

.. setting:: LOGIN_REDIRECT_URL

.. _RSS best practices: http://www.rssboard.org/rss-profile

Technical message IDs

---------------------

Up to version 1.1 Django used :ref:`technical message IDs<technical-messages>`

to provide localizers the possibility to translate date and time formats. They

were translatable :term:`translation strings <translation string>` that could

be recognized because they were all upper case (for example

``DATETIME_FORMAT``, ``DATE_FORMAT``, ``TIME_FORMAT``). They have been

deprecated in favor of the new :ref:`Format localization

<format-localization>` infrastructure that allows localizers to specify that

information in a ``formats.py`` file in the corresponding

``django/conf/locale/<locale name>/`` directory.

What's new in Django 1.2

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