cmlenz@528: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@528:
cmlenz@528: =====================================
cmlenz@528: Internationalization and Localization
cmlenz@528: =====================================
cmlenz@528:
cmlenz@886: Genshi provides comprehensive supporting infrastructure for internationalizing
cmlenz@885: and localizing templates. That includes functionality for extracting
cmlenz@890: localizable strings from templates, as well as a template filter and special
cmlenz@890: directives that can apply translations to templates as they get rendered.
cmlenz@528:
cmlenz@528: This support is based on `gettext`_ message catalogs and the `gettext Python
cmlenz@885: module`_. The extraction process can be used from the API level, or through
cmlenz@885: the front-ends implemented by the `Babel`_ project, for which Genshi provides
cmlenz@885: a 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@885: all localizable strings in a ``gettext()`` function call (which is often
cmlenz@885: aliased to ``_()`` for brevity). In that case, no extra template filter is
cmlenz@885: required.
cmlenz@528:
cmlenz@528: .. code-block:: genshi
cmlenz@528:
cmlenz@528: ${_("Hello, world!")}
cmlenz@528:
cmlenz@885: 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@890: explicit `gettext`_ function calls, so you can (often) just continue to 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@885: .. note:: For parameterized or pluralizable messages, you need to use the
cmlenz@885: special `template directives`_ described below, or use the
cmlenz@885: corresponding ``gettext`` function in embedded Python expressions.
cmlenz@528:
cmlenz@885: 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 ``