.. -*- mode: rst; encoding: utf-8 -*-
=====================================
Internationalization and Localization
=====================================
Genshi provides comprehensive supporting infrastructure for internationalizing
and localizing templates. That includes functionality for extracting
localizable strings from templates, as well as a template filter and special
directives 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 (often) just continue to 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 use the
special `template directives`_ described below, or use the
corresponding ``gettext`` function in embedded Python expressions.
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 ``