| 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 |
Translation depends on the target language, and formatting usually depends on |
| 32 |
the target country. This information is provided by browsers in the |
| 33 |
``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: https://www.w3.org/International/questions/qa-i18n |
| 52 |
.. _GNU gettext documentation: https://www.gnu.org/software/gettext/manual/gettext.html#Concepts |
| 53 |
.. _Wikipedia article: https://en.wikipedia.org/wiki/Internationalization_and_localization |
| 54 |
|
| 55 |
.. warning:: |
| 56 |
|
| 57 |
Translation is controlled by the :setting:`USE_I18N` setting. However, it |
| 58 |
involves internationalization and localization. The name of the setting is |
| 59 |
an unfortunate result of Django's history. |
| 60 |
|
| 61 |
Here are some other terms that will help us to handle a common language: |
| 62 |
|
| 63 |
.. glossary:: |
| 64 |
|
| 65 |
locale name |
| 66 |
A locale name, either a language specification of the form ``ll`` or a |
| 67 |
combined language and country specification of the form ``ll_CC``. |
| 68 |
Examples: ``it``, ``de_AT``, ``es``, ``pt_BR``, ``sr_Latn``. The language |
| 69 |
part is always in lowercase. The country part is in titlecase if it has |
| 70 |
more than 2 characters, otherwise it's in uppercase. The separator is an |
| 71 |
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``. Language codes |
| 77 |
are generally represented in lowercase, but the HTTP ``Accept-Language`` |
| 78 |
header is case-insensitive. The separator is a dash. |
| 79 |
|
| 80 |
message file |
| 81 |
A message file is a plain-text file, representing a single language, |
| 82 |
that contains all available :term:`translation strings |
| 83 |
<translation string>` and how they should be represented in the given |
| 84 |
language. Message files have a ``.po`` file extension. |
| 85 |
|
| 86 |
translation string |
| 87 |
A literal that can be translated. |
| 88 |
|
| 89 |
format file |
| 90 |
A format file is a Python module that defines the data formats for a given |
| 91 |
locale. |