Django-1.2.1/docs/topics/i18n/index.txt

   1 .. _topics-i18n:
   2
   3 =====================================
   4 Internationalization and localization
   5 =====================================
   6
   7 Overview
   8 ========
   9
  10 Django has full support for internationalization of text in code and
  11 templates, and format localization of dates and numbers. Here's how it works.
  12
  13 Essentially, Django does two things:
  14
  15     * It allows developers and template authors to specify which parts of
  16       their apps should be translatable.
  17     * It uses these hooks to translate Web apps for particular users according
  18       to their language preferences.
  19
  20 The complete process can be seen as divided in three stages. It is also possible
  21 to identify an identical number of roles with very well defined responsibilities
  22 associated with each of these tasks (although it's perfectly normal if you
  23 find yourself performing more than one of these roles):
  24
  25     * For application authors wishing to make sure their Django apps can be
  26       used in different locales: :ref:`topics-i18n-internationalization`.
  27     * For translators wanting to translate Django apps: :ref:`topics-i18n-localization`.
  28     * For system administrators/final users setting up internationalized apps or
  29       developers integrating third party apps: :ref:`topics-i18n-deployment`.
  30
  31 .. toctree::
  32    :hidden:
  33    :maxdepth: 1
  34
  35    internationalization
  36    localization
  37    deployment
  38
  39 .. _ seealso::
  40
  41 For more general information about the topic, see the `GNU gettext documentation`_
  42 and the `Wikipedia article`_.
  43
  44 .. _GNU gettext documentation: http://www.gnu.org/software/gettext/manual/gettext.html#Concepts
  45 .. _Wikipedia article: http://en.wikipedia.org/wiki/Internationalization_and_localization
  46
  47 Glossary
  48 ========
  49
  50 First lets define some terms that will help us to handle a common language:
  51
  52 .. glossary::
  53
  54     locale name
  55       A locale name, either a language specification of the form ``ll`` or a
  56       combined language and country specification of the form ``ll_CC``.
  57       Examples: ``it``, ``de_AT``, ``es``, ``pt_BR``. Note the underscore in
  58       some of them and the case of the part located to its right.
  59
  60     language code
  61       Represents the name of a language. Browsers send the names of the
  62       languages they accept in the ``Accept-Language`` HTTP header using this
  63       format. Examples: ``it``, ``de-at``, ``es``, ``pt-br``. Note the ``-``
  64       separator.
  65
  66     message file
  67       A message file is a plain-text file, representing a single language,
  68       that contains all available :term:`translation strings
  69       <translation string>` and how they should be represented in the given
  70       language. Message files have a ``.po`` file extension.
  71
  72     translation string
  73       A literal that can be translated.
  74
  75 .. _specialties-of-django-i18n:
  76
  77 Specialties of Django translation
  78 =================================
  79
  80 Django's translation machinery uses the standard ``gettext`` module that comes
  81 with Python. If you know ``gettext``, you might note these specialties in the
  82 way Django does translation:
  83
  84     * The string domain is ``django`` or ``djangojs``. This string domain is
  85       used to differentiate between different programs that store their data
  86       in a common message-file library (usually ``/usr/share/locale/``). The
  87       ``django`` domain is used for python and template translation strings
  88       and is loaded into the global translation catalogs. The ``djangojs``
  89       domain is only used for JavaScript translation catalogs to make sure
  90       that those are as small as possible.
  91     * Django doesn't use ``xgettext`` alone. It uses Python wrappers around
  92       ``xgettext`` and ``msgfmt``. This is mostly for convenience.
  93
  94 .. _technical-messages:
  95
  96 Django technical message IDs
  97 ----------------------------
  98
  99 .. versionchanged:: 1.2
 100     Starting with Django 1.2, technical message IDs are being replaced by :ref:`format-localization`
 101
 102 Django uses technical message IDs to translate date formats and time formats.
 103 Technical message IDs are :term:`translation strings <translation string>` and
 104 can be easily recognized; they're all upper case. You don't translate the
 105 message ID as with other translation strings, you provide the correct local
 106 variant on the provided English value. The format is identical to the format
 107 strings used by the ``now`` template tag.
 108
 109 For example, with ``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``),
 110 this would be the format string that you want to use in your language. A Django
 111 contributor localizing it to Spanish probably would provide a ``"j N Y P"``
 112 "translation" for it in the relevant ``django.po`` file::
 113
 114     msgid "DATETIME_FORMAT"
 115     msgstr "j N Y P"