1 =====================================

     2 Internationalization and localization

     3 =====================================

     4 

     5 Overview

     6 ========

     7 

     8 Django has full support for internationalization of text in code and

     9 templates, and format localization of dates and numbers. Here's how it works.

    10 

    11 Essentially, Django does two things:

    12 

    13     * It allows developers and template authors to specify which parts of

    14       their apps should be translatable.

    15     * It uses these hooks to translate Web apps for particular users according

    16       to their language preferences.

    17 

    18 The complete process can be seen as divided in three stages. It is also possible

    19 to identify an identical number of roles with very well defined responsibilities

    20 associated with each of these tasks (although it's perfectly normal if you

    21 find yourself performing more than one of these roles):

    22 

    23     * For application authors wishing to make sure their Django apps can be

    24       used in different locales: :doc:`/topics/i18n/internationalization`.

    25     * For translators wanting to translate Django apps: :doc:`/topics/i18n/localization`.

    26     * For system administrators/final users setting up internationalized apps or

    27       developers integrating third party apps: :doc:`/topics/i18n/deployment`.

    28 

    29 .. toctree::

    30    :hidden:

    31    :maxdepth: 1

    32 

    33    internationalization

    34    localization

    35    deployment

    36 

    37 .. _ seealso::

    38 

    39 For more general information about the topic, see the `GNU gettext documentation`_

    40 and the `Wikipedia article`_.

    41 

    42 .. _GNU gettext documentation: http://www.gnu.org/software/gettext/manual/gettext.html#Concepts

    43 .. _Wikipedia article: http://en.wikipedia.org/wiki/Internationalization_and_localization

    44 

    45 Glossary

    46 ========

    47 

    48 First lets define some terms that will help us to handle a common language:

    49 

    50 .. glossary::

    51 

    52     locale name

    53       A locale name, either a language specification of the form ``ll`` or a

    54       combined language and country specification of the form ``ll_CC``.

    55       Examples: ``it``, ``de_AT``, ``es``, ``pt_BR``. Note the underscore in

    56       some of them and the case of the part located to its right.

    57 

    58     language code

    59       Represents the name of a language. Browsers send the names of the

    60       languages they accept in the ``Accept-Language`` HTTP header using this

    61       format. Examples: ``it``, ``de-at``, ``es``, ``pt-br``. Note the ``-``

    62       separator.

    63 

    64     message file

    65       A message file is a plain-text file, representing a single language,

    66       that contains all available :term:`translation strings

    67       <translation string>` and how they should be represented in the given

    68       language. Message files have a ``.po`` file extension.

    69 

    70     translation string

    71       A literal that can be translated.

    72 

    73 .. _specialties-of-django-i18n:

    74 

    75 Specialties of Django translation

    76 =================================

    77 

    78 Django's translation machinery uses the standard ``gettext`` module that comes

    79 with Python. If you know ``gettext``, you might note these specialties in the

    80 way Django does translation:

    81 

    82     * The string domain is ``django`` or ``djangojs``. This string domain is

    83       used to differentiate between different programs that store their data

    84       in a common message-file library (usually ``/usr/share/locale/``). The

    85       ``django`` domain is used for python and template translation strings

    86       and is loaded into the global translation catalogs. The ``djangojs``

    87       domain is only used for JavaScript translation catalogs to make sure

    88       that those are as small as possible.

    89     * Django doesn't use ``xgettext`` alone. It uses Python wrappers around

    90       ``xgettext`` and ``msgfmt``. This is mostly for convenience.

    91 

    92 .. _technical-messages:

    93 

    94 Django technical message IDs

    95 ----------------------------

    96 

    97 .. versionchanged:: 1.2

    98     Starting with Django 1.2, technical message IDs are being replaced by :ref:`format-localization`

    99 

   100 Django uses technical message IDs to translate date formats and time formats.

   101 Technical message IDs are :term:`translation strings <translation string>` and

   102 can be easily recognized; they're all upper case. You don't translate the

   103 message ID as with other translation strings, you provide the correct local

   104 variant on the provided English value. The format is identical to the format

   105 strings used by the ``now`` template tag.

   106 

   107 For example, with ``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``),

   108 this would be the format string that you want to use in your language. A Django

   109 contributor localizing it to Spanish probably would provide a ``"j N Y P"``

   110 "translation" for it in the relevant ``django.po`` file::

   111 

   112     msgid "DATETIME_FORMAT"

   113     msgstr "j N Y P"