From: Armin Ronacher Date: Fri, 26 Jul 2013 14:34:28 +0000 (+0200) Subject: More documentation updates X-Git-Tag: 1.0~15 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=97f49099cc6ef6210f72667b1b79d67434dd8c9e;p=thirdparty%2Fbabel.git More documentation updates --- diff --git a/docs/index.rst b/docs/index.rst index 474a10c9..88a0458a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,7 +17,7 @@ some information about how it can be used. :maxdepth: 1 intro - display + locale dates numbers messages diff --git a/docs/intro.rst b/docs/intro.rst index 25e00699..db36f32d 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -45,5 +45,5 @@ time-zones, which are frequently needed in web-based applications. For these requirements, Babel includes data extracted from the `Common Locale Data Repository (CLDR) `_, and provides a number of convenient methods for accessing and using this data. See -:ref:`display-names`, :ref:`date-and-time`, and :ref:`numbers` for more +:ref:`locale-data`, :ref:`date-and-time`, and :ref:`numbers` for more information on this aspect of Babel. diff --git a/docs/display.rst b/docs/locale.rst similarity index 52% rename from docs/display.rst rename to docs/locale.rst index 06901a28..f30e2fe8 100644 --- a/docs/display.rst +++ b/docs/locale.rst @@ -1,14 +1,10 @@ .. -*- mode: rst; encoding: utf-8 -*- -.. _display-names: - -==================== -Locale Display Names -==================== +.. _locale-data: - -Introduction -============ +=========== +Locale Data +=========== While :ref:`message catalogs ` allow you to localize any messages in your application, there are a number of strings that are used @@ -48,6 +44,71 @@ key is a code such as the ISO country and language codes. Consult the API documentation for references to the relevant specifications. +Likely Subtags +============== + +When dealing with locales you can run into the situation where a locale +tag is not fully descriptive. For instance people commonly refer to +``zh_TW`` but that identifier does not resolve to a locale that the CLDR +covers. Babel's locale identifier parser in that case will attempt to +resolve the most likely subtag to end up with the intended locale: + +.. code-block:: pycon + + >>> from babel import Locale + >>> Locale.parse('zh_TW') + Locale('zh', territory='TW', script='Hant') + +This can also be used to find the most appropriate locale for a territory. +In that case the territory code needs to be prefixed with ``und`` (unknown +language identifier): + +.. code-block:: pycon + + >>> Locale.parse('und_AZ') + Locale('az', territory='AZ', script='Latn') + >>> Locale.parse('und_DE') + Locale('de', territory='DE') + +Babel currently cannot deal with fuzzy locales (a locale not fully backed +by data files) so we only accept locales that are fully backed by CLDR +data. This will change in the future, but for the time being this +restriction is in place. + + +Locale Display Names +==================== + +Locales itself can be used to describe the locale itself or other locales. +This mainly means that given a locale object you can ask it for it's +canonical display name, the name of the language and other things. Since +the locales cross reference each other you can ask for locale names in any +language supported by the CLDR: + +.. code-block:: pycon + + >>> l = Locale.parse('de_DE') + >>> l.get_display_name('en_US') + u'German (Germany)' + >>> l.get_display_name('fr_FR') + u'allemand (Allemagne)' + +Display names include all the information to uniquely identify a locale +(language, territory, script and variant) which is often not what you +want. You can also ask for the information in parts: + +.. code-block:: pycon + + >>> l.get_language_name('de_DE') + u'Deutsch' + >>> l.get_language_name('it_IT') + u'tedesco' + >>> l.get_territory_name('it_IT') + u'Germania' + >>> l.get_territory_name('pt_PT') + u'Alemanha' + + Calender Display Names ======================