# HG changeset patch # User cmlenz # Date 1271708932 0 # Node ID d30ceea3eadd18563802092c3c3982bf0ffc1429 # Parent 963ffe1ce6679a65c8378c6bef6fe7be63c3071b More doc tweaks. diff --git a/doc/i18n.txt b/doc/i18n.txt --- a/doc/i18n.txt +++ b/doc/i18n.txt @@ -6,8 +6,8 @@ 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 that can -apply translations to templates as they get rendered. +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 @@ -40,7 +40,7 @@ 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: +explicit `gettext`_ function calls, so you can (often) just continue to write: .. code-block:: genshi @@ -100,9 +100,10 @@ In those cases the simple text extraction and translation process described above is not sufficient. You could just use ``gettext`` API functions in -embedded Python expressions for parameters and pluralization, but Genshi also -provides special template directives for internationalization that attempt to -provide a comprehensive solution for this problem space. +embedded Python expressions for parameters and pluralization, but that does +not help when messages contain embedded markup. Genshi provides special +template directives for internationalization that attempt to provide a +comprehensive solution for this problem space. To enable these directives, you'll need to register them with the templates they are used in. You can do this by adding them manually via the @@ -112,11 +113,27 @@ class method, which both registers the directives and adds the translation filter. +After the directives have been registered with the template engine on the +Python side of your application, you need to declare the corresponding +directive namespace in all markup templates that use them. For example: + +.. code-block:: genshi + + + … + + +These directives only make sense in the context of `markup templates`_. For +`text templates`_, you can just use the corresponding ``gettext`` API calls as needed. + .. note:: The internationalization directives are still somewhat experimental and have some known issues. However, the attribute language they implement should be stable and is not subject to change substantially in future versions. +.. _`markup templates`: xml-templates.html +.. _`text templates`: text-templates.html -------- Messages @@ -405,9 +422,10 @@ the ``include_attrs`` list are extracted. If this option is disabled, only strings in ``gettext`` function calls are extracted. -.. note:: If you disable this option, it's not necessary to add the translation - filter as described above. You only need to make sure that the - template has access to the ``gettext`` functions it uses. +.. note:: If you disable this option, and do not make use of the + internationalization directives, it's not necessary to add the + translation filter as described above. You only need to make sure + that the template has access to the ``gettext`` functions it uses. Translation @@ -432,22 +450,24 @@ template = MarkupTemplate("...") template.filters.insert(0, Translator(translations.ugettext)) -If you're using `TemplateLoader`, you should specify a callback function in -which you add the filter: +The ``Translator`` class also provides the convenience method ``setup()``, +which will both add the filter and register the i18n directives: .. code-block:: python from genshi.filters import Translator - from genshi.template import TemplateLoader - - def template_loaded(template): - Translator(translations.ugettext).setup(template) + from genshi.template import MarkupTemplate - loader = TemplateLoader('templates', callback=template_loaded) - template = loader.load('test.html') + template = MarkupTemplate("...") + translator = Translator(translations.ugettext) + translator.setup(template) -This approach ensures that the filter is not added everytime the template is -loaded, and thus being applied multiple times. +.. warning:: If you're using ``TemplateLoader``, you should specify a + `callback function`_ in which you add the filter. That ensures + that the filter is not added everytime the template is rendered, + thereby being applied multiple times. + +.. _`callback function`: loader.html#callback-interface Related Considerations diff --git a/doc/loader.txt b/doc/loader.txt --- a/doc/loader.txt +++ b/doc/loader.txt @@ -241,9 +241,9 @@ the signature ``load(filename, relative_to=None, cls=None)``. In addition, templates currently check for the existence and value of a boolean -``auto_reload`` property. If the property exists and evaluates to a non-truth -value, inlining of included templates is disabled. Inlining is a small -optimization that removes some overhead in the processing of includes. +``auto_reload`` property. If the property does not exist or evaluates to a +non-truth value, inlining of included templates is disabled. Inlining is a +small optimization that removes some overhead in the processing of includes. Subclassing ``TemplateLoader`` ==============================