More documentation updates

diff --git a/docs/index.rst b/docs/index.rst
index 474a10c91392e7dd12da3d0e9ee5f3aa7815c513..88a0458a40449e87558f48043fc2425a5aecc6b3 100644 (file)
--- 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 25e006997a35d36c4293fa69bba6318dc613de89..db36f32d30155e389c6755a21cee32b6de3562d8 100644 (file)
--- 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) <http://unicode.org/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 06901a28b08cdaaf25d20d8a2e610fb891031c48..f30e2fe871b51f52716fdf935dfa2dfbbbf1847c 100644 (file)
--- 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 <messages>` 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
 ======================