.. -*- mode: rst; encoding: utf-8 -*-
+.. _display-names:
+
====================
Locale Display Names
====================
Introduction
============
-While `message catalogs <messages.html>`_ allow you to localize any messages
-in your application, there are a number of strings that are used in many
-applications for which translations are readily available.
+While :ref:`message catalogs <messages>` allow you to localize any
+messages in your application, there are a number of strings that are used
+in many applications for which translations are readily available.
Imagine for example you have a list of countries that users can choose from,
and you'd like to display the names of those countries in the language the
>>> locale = Locale('es')
>>> month_names = locale.months['format']['wide'].items()
- >>> month_names.sort()
- >>> for idx, name in month_names:
+ >>> for idx, name in sorted(month_names):
... print name
enero
febrero
Message Catalogs
================
-While the Python standard library includes a
-`gettext <http://docs.python.org/lib/module-gettext.html>`_ module that enables
-applications to use message catalogs, it requires developers to build these
-catalogs using GNU tools such as ``xgettext``, ``msgmerge``, and ``msgfmt``.
-And while ``xgettext`` does have support for extracting messages from Python
-files, it does not know how to deal with other kinds of files commonly found
-in Python web-applications, such as templates, nor does it provide an easy
-extensibility mechanism to add such support.
+While the Python standard library includes a :mod:`gettext` module that
+enables applications to use message catalogs, it requires developers to
+build these catalogs using GNU tools such as ``xgettext``, ``msgmerge``,
+and ``msgfmt``. And while ``xgettext`` does have support for extracting
+messages from Python files, it does not know how to deal with other kinds
+of files commonly found in Python web-applications, such as templates, nor
+does it provide an easy extensibility mechanism to add such support.
-Babel addresses this by providing a framework where various extraction methods
-can be plugged in to a larger message extraction framework, and also removes
-the dependency on the GNU ``gettext`` tools for common tasks, as these aren't
-necessarily available on all platforms. See `Working with Message Catalogs`_
-for details on this aspect of Babel.
-
-.. _`Working with Message Catalogs`: messages.html
+Babel addresses this by providing a framework where various extraction
+methods can be plugged in to a larger message extraction framework, and
+also removes the dependency on the GNU ``gettext`` tools for common tasks,
+as these aren't necessarily available on all platforms. See
+:ref:`messages` for details on this aspect of Babel.
Locale Data
===========
-Furthermore, while the Python standard library does include support for basic
-localization with respect to the formatting of numbers and dates (the
-`locale <http://docs.python.org/lib/module-locale.html>`_ module, among others),
-this support is based on the assumption that there will be only one specific
-locale used per process (at least simultaneously.) Also, it doesn't provide
-access to other kinds of locale data, such as the localized names of countries,
-languages, or 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 `Locale Display
-Names`_, `Date Formatting`_, and `Number Formatting`_ for more information on
-this aspect of Babel.
-
-
-.. _`Locale Display Names`: display.html
-.. _`Date Formatting`: dates.html
-.. _`Number Formatting`: numbers.html
+Furthermore, while the Python standard library does include support for
+basic localization with respect to the formatting of numbers and dates
+(the :mod:`locale` module, among others), this support is based on the
+assumption that there will be only one specific locale used per process
+(at least simultaneously.) Also, it doesn't provide access to other kinds
+of locale data, such as the localized names of countries, languages, or
+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
+information on this aspect of Babel.
.. -*- mode: rst; encoding: utf-8 -*-
+.. _messages:
+
=============================
Working with Message Catalogs
=============================
regenerate the POT file and merge the changes into the various
locale-specific PO files, for example using ``msgmerge``
-Python provides the `gettext module`_ as part of the standard library, which
-enables applications to work with appropriately generated MO files.
-
- .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
+Python provides the :mod:`gettext` module as part of the standard library,
+which enables applications to work with appropriately generated MO files.
As ``gettext`` provides a solid and well supported foundation for translating
application messages, Babel does not reinvent the wheel, but rather reuses this
there needs to be a way to configure which files should be treated in which
manner. For example, while many projects may contain ``.html`` files, some of
those files may be static HTML files that don't contain localizable message,
-while others may be `Django`_ templates, and still others may contain `Genshi`_
+while others may be `Jinja2`_ templates, and still others may contain `Genshi`_
markup templates. Some projects may even mix HTML files for different templates
languages (for whatever reason). Therefore the way in which messages are
extracted from source files can not only depend on the file extension, but
needs to be controllable in a precise manner.
-.. _`Django`: http://www.djangoproject.com/
+.. _`Jinja2`: http://jinja.pocoo.org/
.. _`Genshi`: http://genshi.edgewall.org/
Babel accepts a configuration file to specify this mapping of files to
.. note:: if you're performing message extraction using the command Babel
provides for integration into ``setup.py`` scripts, you can also
provide this configuration in a different way, namely as a keyword
- argument to the ``setup()`` function. See `Distutils/Setuptools
- Integration`_ for more information.
-
-.. _`distutils/setuptools integration`: setup.html
+ argument to the ``setup()`` function. See
+ :ref:`setup-integration` for more information.
Default Extraction Methods
projects / thirdparty / babel.git / commitdiff
