PageRenderTime 106ms CodeModel.GetById 55ms app.highlight 1ms RepoModel.GetById 49ms app.codeStats 0ms

/docs/topics/i18n/index.txt

https://code.google.com/p/mango-py/
Plain Text | 113 lines | 85 code | 28 blank | 0 comment | 0 complexity | 39b2f328d378c317b56e340e6de1373c MD5 | raw file
  1=====================================
  2Internationalization and localization
  3=====================================
  4
  5Overview
  6========
  7
  8Django has full support for internationalization of text in code and
  9templates, and format localization of dates and numbers. Here's how it works.
 10
 11Essentially, 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
 18The complete process can be seen as divided in three stages. It is also possible
 19to identify an identical number of roles with very well defined responsibilities
 20associated with each of these tasks (although it's perfectly normal if you
 21find 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
 39For more general information about the topic, see the `GNU gettext documentation`_
 40and 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
 45Glossary
 46========
 47
 48First 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
 75Specialties of Django translation
 76=================================
 77
 78Django's translation machinery uses the standard ``gettext`` module that comes
 79with Python. If you know ``gettext``, you might note these specialties in the
 80way 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
 94Django 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
100Django uses technical message IDs to translate date formats and time formats.
101Technical message IDs are :term:`translation strings <translation string>` and
102can be easily recognized; they're all upper case. You don't translate the
103message ID as with other translation strings, you provide the correct local
104variant on the provided English value. The format is identical to the format
105strings used by the ``now`` template tag.
106
107For example, with ``DATETIME_FORMAT`` (or ``DATE_FORMAT`` or ``TIME_FORMAT``),
108this would be the format string that you want to use in your language. A Django
109contributor 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"