Debian Codegraph @

docs/topics/i18n/index.txt

raw
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.