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