1.. -*- mode: rst; encoding: utf-8 -*-
2
3.. _locale-data:
4
5===========
6Locale Data
7===========
8
9While :ref:`message catalogs <messages>` allow you to localize any
10messages in your application, there are a number of strings that are used
11in many applications for which translations are readily available.
12
13Imagine for example you have a list of countries that users can choose from,
14and you'd like to display the names of those countries in the language the
15user prefers. Instead of translating all those country names yourself in your
16application, you can make use of the translations provided by the locale data
17included with Babel, which is based on the `Common Locale Data Repository
18(CLDR) <https://unicode.org/cldr/>`_ developed and maintained by the `Unicode
19Consortium <https://unicode.org/>`_.
20
21
22The ``Locale`` Class
23====================
24
25You normally access such locale data through the
26:class:`~babel.core.Locale` class provided by Babel:
27
28.. code-block:: pycon
29
30    >>> from babel import Locale
31    >>> locale = Locale('en', 'US')
32    >>> locale.territories['US']
33    u'United States'
34    >>> locale = Locale('es', 'MX')
35    >>> locale.territories['US']
36    u'Estados Unidos'
37
38In addition to country/territory names, the locale data also provides access to
39names of languages, scripts, variants, time zones, and more. Some of the data
40is closely related to number and date formatting.
41
42Most of the corresponding ``Locale`` properties return dictionaries, where the
43key is a code such as the ISO country and language codes. Consult the API
44documentation for references to the relevant specifications.
45
46
47Likely Subtags
48==============
49
50When dealing with locales you can run into the situation where a locale
51tag is not fully descriptive.  For instance people commonly refer to
52``zh_TW`` but that identifier does not resolve to a locale that the CLDR
53covers.  Babel's locale identifier parser in that case will attempt to
54resolve the most likely subtag to end up with the intended locale:
55
56.. code-block:: pycon
57
58    >>> from babel import Locale
59    >>> Locale.parse('zh_TW')
60    Locale('zh', territory='TW', script='Hant')
61
62This can also be used to find the most appropriate locale for a territory.
63In that case the territory code needs to be prefixed with ``und`` (unknown
64language identifier):
65
66.. code-block:: pycon
67
68    >>> Locale.parse('und_AZ')
69    Locale('az', territory='AZ', script='Latn')
70    >>> Locale.parse('und_DE')
71    Locale('de', territory='DE')
72
73Babel currently cannot deal with fuzzy locales (a locale not fully backed
74by data files) so we only accept locales that are fully backed by CLDR
75data.  This will change in the future, but for the time being this
76restriction is in place.
77
78
79Locale Display Names
80====================
81
82Locales itself can be used to describe the locale itself or other locales.
83This mainly means that given a locale object you can ask it for its
84canonical display name, the name of the language and other things.  Since
85the locales cross-reference each other you can ask for locale names in any
86language supported by the CLDR:
87
88.. code-block:: pycon
89
90    >>> l = Locale.parse('de_DE')
91    >>> l.get_display_name('en_US')
92    u'German (Germany)'
93    >>> l.get_display_name('fr_FR')
94    u'allemand (Allemagne)'
95
96Display names include all the information to uniquely identify a locale
97(language, territory, script and variant) which is often not what you
98want.  You can also ask for the information in parts:
99
100.. code-block:: pycon
101
102    >>> l.get_language_name('de_DE')
103    u'Deutsch'
104    >>> l.get_language_name('it_IT')
105    u'tedesco'
106    >>> l.get_territory_name('it_IT')
107    u'Germania'
108    >>> l.get_territory_name('pt_PT')
109    u'Alemanha'
110
111
112Calendar Display Names
113======================
114
115The :class:`~babel.core.Locale` class provides access to many locale
116display names related to calendar display, such as the names of weekdays
117or months.
118
119These display names are of course used for date formatting, but can also be
120used, for example, to show a list of months to the user in their preferred
121language:
122
123.. code-block:: pycon
124
125    >>> locale = Locale('es')
126    >>> month_names = locale.months['format']['wide'].items()
127    >>> for idx, name in sorted(month_names):
128    ...     print name
129    enero
130    febrero
131    marzo
132    abril
133    mayo
134    junio
135    julio
136    agosto
137    septiembre
138    octubre
139    noviembre
140    diciembre
141