.. -*- mode: rst; encoding: utf-8 -*-
=====================================
Internationalization and Localization
=====================================
Genshi provides basic supporting infrastructure for internationalizing
and localizing templates. That includes functionality for extracting localizable
strings from templates, as well as a template filter that can apply translations
to templates as they get rendered.
This support is based on `gettext`_ message catalogs and the `gettext Python
module`_. The extraction process can be used from the API level, or through the
front-ends implemented by the `Babel`_ project, for which Genshi provides a
plugin.
.. _`gettext`: http://www.gnu.org/software/gettext/
.. _`gettext python module`: http://docs.python.org/lib/module-gettext.html
.. _`babel`: http://babel.edgewall.org/
.. contents:: Contents
:depth: 2
.. sectnum::
Basics
======
The simplest way to internationalize and translate templates would be to wrap
all localizable strings in a ``gettext()`` function call (which is often aliased
to ``_()`` for brevity). In that case, no extra template filter is required.
.. code-block:: genshi
${_("Hello, world!")}
However, this approach results in significant “character noise” in templates,
making them harder to read and preview.
The ``genshi.filters.Translator`` filter allows you to get rid of the
explicit `gettext`_ function calls, so you can continue to just write:
.. code-block:: genshi
Hello, world!
This text will still be extracted and translated as if you had wrapped it in a
``_()`` call.
.. note:: For parameterized or pluralizable messages, you need to continue using
the appropriate ``gettext`` functions.
You can control which tags should be ignored by this process; for example, it
doesn't really make sense to translate the content of the HTML
```` element. Both ``