cmlenz@4: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@4: 
cmlenz@4: =============================
cmlenz@4: Working with Message Catalogs
cmlenz@4: =============================
cmlenz@4: 
cmlenz@4: .. contents:: Contents
cmlenz@4:    :depth: 2
cmlenz@4: .. sectnum::
cmlenz@4: 
cmlenz@4: 
cmlenz@4: Introduction
cmlenz@4: ============
cmlenz@4: 
cmlenz@4: The ``gettext`` translation system enables you to mark any strings used in your
cmlenz@4: application as subject to localization, by wrapping them in functions such as
cmlenz@4: ``gettext(str)`` and ``ngettext(singular, plural, num)``. For brevity, the
cmlenz@42: ``gettext`` function is often aliased to ``_(str)``, so you can write:
cmlenz@42: 
cmlenz@42: .. code-block:: python
cmlenz@4: 
cmlenz@4:     print _("Hello")
cmlenz@4: 
cmlenz@42: instead of just:
cmlenz@42: 
cmlenz@42: .. code-block:: python
cmlenz@4: 
cmlenz@4:     print "Hello"
cmlenz@4: 
cmlenz@4: to make the string "Hello" localizable.
cmlenz@4: 
cmlenz@4: Message catalogs are collections of translations for such localizable messages
cmlenz@4: used in an application. They are commonly stored in PO (Portable Object) and MO
cmlenz@4: (Machine Object) files, the formats of which are defined by the GNU `gettext`_
cmlenz@4: tools and the GNU `translation project`_.
cmlenz@4: 
cmlenz@4:  .. _`gettext`: http://www.gnu.org/software/gettext/
cmlenz@4:  .. _`translation project`: http://sourceforge.net/projects/translation
cmlenz@4: 
cmlenz@4: The general procedure for building message catalogs looks something like this:
cmlenz@4: 
cmlenz@4:  * use a tool (such as ``xgettext``) to extract localizable strings from the
cmlenz@4:    code base and write them to a POT (PO Template) file.
cmlenz@4:  * make a copy of the POT file for a specific locale (for example, "en_US")
cmlenz@4:    and start translating the messages
cmlenz@4:  * use a tool such as ``msgfmt`` to compile the locale PO file into an binary
cmlenz@4:    MO file
cmlenz@4:  * later, when code changes make it necessary to update the translations, you
cmlenz@4:    regenerate the POT file and merge the changes into the various
cmlenz@4:    locale-specific PO files, for example using ``msgmerge``
cmlenz@4: 
cmlenz@4: Python provides the `gettext module`_ as part of the standard library, which
cmlenz@4: enables applications to work with appropriately generated MO files.
cmlenz@4: 
cmlenz@4:  .. _`gettext module`: http://docs.python.org/lib/module-gettext.html
cmlenz@4: 
cmlenz@4: As ``gettext`` provides a solid and well supported foundation for translating
cmlenz@4: application messages, Babel does not reinvent the wheel, but rather reuses this
cmlenz@4: infrastructure, and makes it easier to build message catalogs for Python
cmlenz@4: applications.
cmlenz@4: 
cmlenz@4: 
cmlenz@4: Message Extraction
cmlenz@4: ==================
cmlenz@4: 
cmlenz@4: Babel provides functionality similar to that of the ``xgettext`` program,
cmlenz@4: except that only extraction from Python source files is built-in, while support
cmlenz@4: for other file formats can be added using a simple extension mechanism.
cmlenz@4: 
cmlenz@4: (TODO: more)
cmlenz@4: 
cmlenz@4: 
cmlenz@4: --------------------------
cmlenz@4: Writing Extraction Methods
cmlenz@4: --------------------------
cmlenz@4: 
cmlenz@4: (TODO: write)
cmlenz@4: 
cmlenz@4: ---------------------
cmlenz@4: ``setup.py`` Commands
cmlenz@4: ---------------------
cmlenz@4: 
cmlenz@4: (TODO: overview)
cmlenz@4: 
cmlenz@4: See `Distutils/Setuptools Integration <setup.html>`_ for more information.
cmlenz@4: 
cmlenz@4: -------------------
cmlenz@4: Command-line script
cmlenz@4: -------------------
cmlenz@4: 
cmlenz@4: (TODO: overview)
cmlenz@4: 
cmlenz@4: See `Command-Line Interface <cmdline.html>`_ for more information.
cmlenz@4: 
cmlenz@4: 
cmlenz@4: Extended ``Translations`` Class
cmlenz@4: ===============================
cmlenz@4: 
cmlenz@4: Many web-based applications are composed of a variety of different components
cmlenz@4: (possibly using some kind of plugin system), and some of those components may
cmlenz@4: provide their own message catalogs that need to be integrated into the larger
cmlenz@4: system.
cmlenz@4: 
cmlenz@4: To support this usage pattern, Babel provides a ``Translations`` class that is
cmlenz@4: derived from the ``GNUTranslations`` class in the ``gettext`` module. This
cmlenz@4: class adds a ``merge()`` method that takes another ``Translations`` instance,
cmlenz@4: and merges its contents into the catalog::
cmlenz@4: 
cmlenz@42: .. code-block:: python
cmlenz@42: 
cmlenz@4:     translations = Translations.load('main')
cmlenz@4:     translations.merge(Translations.load('plugin1'))