cmlenz@4: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@4: 
cmlenz@4: =====
cmlenz@4: Babel
cmlenz@4: =====
cmlenz@4: 
cmlenz@16: .. image:: logo_small.png
cmlenz@16:    :width: 158
cmlenz@16:    :height: 85
cmlenz@16:    :align: center
cmlenz@16:    :alt: Babel
cmlenz@16:    :class: logo
cmlenz@4: 
cmlenz@4: ---------------------------------------------------
cmlenz@4: Simple Internationalization for Python Applications
cmlenz@4: ---------------------------------------------------
cmlenz@4: 
cmlenz@4: Babel is an integrated collection of utilities that assist in
cmlenz@4: internationalizing and localizing Python applications, with an
cmlenz@4: emphasis on web-based applications.
cmlenz@4: 
cmlenz@4: * `Working with Message Catalogs <catalogs.html>`_
cmlenz@4: * `Locale Display Names <display.html>`_
cmlenz@4: * `Number and Date Formatting <formatting.html>`_
cmlenz@4: * `Command-Line Interface <cmdline.html>`_
cmlenz@4: * `Distutils/Setuptools Integration <setup.html>`_
cmlenz@4: * `Generated API Documentation <api/index.html>`_
cmlenz@4: 
cmlenz@4: Introduction
cmlenz@4: ------------
cmlenz@4: 
cmlenz@4: The functionality Babel provides for internationalization (I18n) and
cmlenz@4: localization (L10N) can be separated into two different aspects:
cmlenz@4: 
cmlenz@4:  * tools to build and work with ``gettext`` message catalogs, and
cmlenz@4:  * a Python interface to the CLDR (Common Locale Data Repository), providing
cmlenz@4:    access to various locale display names, localized number and date
cmlenz@4:    formatting, etc.
cmlenz@4: 
cmlenz@4: While the Python standard library includes a
cmlenz@4: `gettext <http://docs.python.org/lib/module-gettext.html>`_ module that enables
cmlenz@4: applications to use message catalogs, it requires developers to build these
cmlenz@4: catalogs using GNU tools such as ``xgettext``, ``msgmerge``, and ``msgfmt``.
cmlenz@4: And while ``xgettext`` does have support for extracting messages from Python
cmlenz@4: files, it does not know how to deal with other kinds of files commonly found
cmlenz@4: in Python web-applications, such as templates, nor does it provide an easy
cmlenz@4: extensibility mechanism to add such support.
cmlenz@4: 
cmlenz@4: Babel addresses this by providing a framework where various extraction methods
cmlenz@4: can be plugged in to a larger message extraction framework, and also removes
cmlenz@4: the dependency on the GNU ``gettext`` tools for common tasks, as these aren't
cmlenz@4: necessarily available on all platforms. See `Working with Message Catalogs`_
cmlenz@4: for details on this aspect of Babel.
cmlenz@4: 
cmlenz@4: Furthermore, while the Python standard library does include support for basic
cmlenz@4: localization with respect to the formatting of numbers and dates (the
cmlenz@4: `locale <http://docs.python.org/lib/module-locale.html>`_ module, among others),
cmlenz@4: this support is based on the assumption that there will be only one specific
cmlenz@4: locale used per process (at least simultaneously.) Also, it doesn't provide
cmlenz@4: access to other kinds of locale data, such as the localized names of countries,
cmlenz@40: languages, or time-zones, which are frequently needed in web-based applications.
cmlenz@4: 
cmlenz@4: For these requirements, Babel includes data extracted from the `Common Locale
cmlenz@4: Data Repository (CLDR) <http://unicode.org/cldr/>`_, and provides a number of
cmlenz@4: convenient methods for accessing and using this data. See `Locale Display
cmlenz@4: Names`_ and `Number and Date Formatting`_ for more information on this aspect
cmlenz@4: of Babel.
cmlenz@4: