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