python/lib/django_1_4/docs/topics/i18n/index.txt

   1 =====================================
   2 Internationalization and localization
   3 =====================================
   4
   5 .. toctree::
   6    :hidden:
   7    :maxdepth: 1
   8
   9    translation
  10    formatting
  11    timezones
  12
  13 Overview
  14 ========
  15
  16 The goal of internationalization and localization is to allow a single Web
  17 application to offer its content in languages and formats tailored to the
  18 audience.
  19
  20 Django has full support for :doc:`translation of text
  21 </topics/i18n/translation>`, :doc:`formatting of dates, times and numbers
  22 </topics/i18n/formatting>`, and :doc:`time zones </topics/i18n/timezones>`.
  23
  24 Essentially, Django does two things:
  25
  26 * It allows developers and template authors to specify which parts of their apps
  27   should be translated or formatted for local languages and cultures.
  28 * It uses these hooks to localize Web apps for particular users according to
  29   their preferences.
  30
  31 Obviously, translation depends on the target language, and formatting usually
  32 depends on the target country. These informations are provided by browsers in
  33 the ``Accept-Language`` header. However, the time zone isn't readily available.
  34
  35 Definitions
  36 ===========
  37
  38 The words "internationalization" and "localization" often cause confusion;
  39 here's a simplified definition:
  40
  41 .. glossary::
  42
  43     internationalization
  44       Preparing the software for localization. Usually done by developers.
  45
  46     localization
  47       Writing the translations and local formats. Usually done by translators.
  48
  49 More details can be found in the `W3C Web Internationalization FAQ`_, the `Wikipedia article`_ or the `GNU gettext documentation`_.
  50
  51 .. _W3C Web Internationalization FAQ: http://www.w3.org/International/questions/qa-i18n
  52 .. _GNU gettext documentation: http://www.gnu.org/software/gettext/manual/gettext.html#Concepts
  53 .. _Wikipedia article: http://en.wikipedia.org/wiki/Internationalization_and_localization
  54
  55 .. warning::
  56
  57     Translation and formatting are controlled by :setting:`USE_I18N` and
  58     :setting:`USE_L10N` settings respectively. However, both features involve
  59     internationalization and localization. The names of the settings are an
  60     unfortunate result of Django's history.
  61
  62 Here are some other terms that will help us to handle a common language:
  63
  64 .. glossary::
  65
  66     locale name
  67       A locale name, either a language specification of the form ``ll`` or a
  68       combined language and country specification of the form ``ll_CC``.
  69       Examples: ``it``, ``de_AT``, ``es``, ``pt_BR``. The language part is
  70       always is lower case and the country part in upper case. The separator
  71       is an underscore.
  72
  73     language code
  74       Represents the name of a language. Browsers send the names of the
  75       languages they accept in the ``Accept-Language`` HTTP header using this
  76       format. Examples: ``it``, ``de-at``, ``es``, ``pt-br``. Both the language
  77       and the country parts are in lower case. The separator is a dash.
  78
  79     message file
  80       A message file is a plain-text file, representing a single language,
  81       that contains all available :term:`translation strings
  82       <translation string>` and how they should be represented in the given
  83       language. Message files have a ``.po`` file extension.
  84
  85     translation string
  86       A literal that can be translated.
  87
  88     format file
  89       A format file is a Python module that defines the data formats for a given
  90       locale.