locale.rst 4.3 KB

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