Edgewall Software

Changeset 1113 for trunk


Ignore:
Timestamp:
Apr 19, 2010, 10:28:52 PM (13 years ago)
Author:
cmlenz
Message:

More doc tweaks.

Location:
trunk/doc
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/i18n.txt

    r1112 r1113  
    77Genshi provides comprehensive supporting infrastructure for internationalizing
    88and localizing templates. That includes functionality for extracting
    9 localizable strings from templates, as well as a template filter that can
    10 apply translations to templates as they get rendered.
     9localizable strings from templates, as well as a template filter and special
     10directives that can apply translations to templates as they get rendered.
    1111
    1212This support is based on `gettext`_ message catalogs and the `gettext Python
    … …  
    4141
    4242The ``genshi.filters.Translator`` filter allows you to get rid of the
    43 explicit `gettext`_ function calls, so you can continue to just write:
     43explicit `gettext`_ function calls, so you can (often) just continue to write:
    4444
    4545.. code-block:: genshi
    … …  
    101101In those cases the simple text extraction and translation process described
    102102above is not sufficient. You could just use ``gettext`` API functions in
    103 embedded Python expressions for parameters and pluralization, but Genshi also
    104 provides special template directives for internationalization that attempt to
    105 provide a comprehensive solution for this problem space.
     103embedded Python expressions for parameters and pluralization, but that does
     104not help when messages contain embedded markup. Genshi provides special
     105template directives for internationalization that attempt to provide a
     106comprehensive solution for this problem space.
    106107
    107108To enable these directives, you'll need to register them with the templates
    … …  
    113114filter.
    114115
     116After the directives have been registered with the template engine on the
     117Python side of your application, you need to declare the corresponding
     118directive namespace in all markup templates that use them. For example:
     119
     120.. code-block:: genshi
     121
     122  <html xmlns:py="http://genshi.edgewall.org/"
     123        xmlns:i18n="http://genshi.edgewall.org/i18n/">
     124    …
     125  </html>
     126
     127These directives only make sense in the context of `markup templates`_. For
     128`text templates`_, you can just use the corresponding ``gettext`` API calls as needed.
     129
    115130.. note:: The internationalization directives are still somewhat experimental
    116131          and have some known issues. However, the attribute language they
    … …  
    118133          substantially in future versions.
    119134
     135.. _`markup templates`: xml-templates.html
     136.. _`text templates`: text-templates.html
    120137
    121138--------
    … …  
    406423strings in ``gettext`` function calls are extracted.
    407424
    408 .. note:: If you disable this option, it's not necessary to add the translation
    409           filter as described above. You only need to make sure that the
    410           template has access to the ``gettext`` functions it uses.
     425.. note:: If you disable this option, and do not make use of the
     426          internationalization directives, it's not necessary to add the
     427          translation filter as described above. You only need to make sure
     428          that the template has access to the ``gettext`` functions it uses.
    411429
    412430
    … …  
    433451  template.filters.insert(0, Translator(translations.ugettext))
    434452
    435 If you're using `TemplateLoader`, you should specify a callback function in
    436 which you add the filter:
     453The ``Translator`` class also provides the convenience method ``setup()``,
     454which will both add the filter and register the i18n directives:
    437455
    438456.. code-block:: python
    439457
    440458  from genshi.filters import Translator
    441   from genshi.template import TemplateLoader
     459  from genshi.template import MarkupTemplate
    442460 
    443   def template_loaded(template):
    444       Translator(translations.ugettext).setup(template)
    445  
    446   loader = TemplateLoader('templates', callback=template_loaded)
    447   template = loader.load('test.html')
    448 
    449 This approach ensures that the filter is not added everytime the template is
    450 loaded, and thus being applied multiple times.
     461  template = MarkupTemplate("...")
     462  translator = Translator(translations.ugettext)
     463  translator.setup(template)
     464
     465.. warning:: If you're using ``TemplateLoader``, you should specify a
     466            `callback function`_ in which you add the filter. That ensures
     467            that the filter is not added everytime the template is rendered,
     468            thereby being applied multiple times.
     469
     470.. _`callback function`: loader.html#callback-interface
    451471
    452472

  • trunk/doc/loader.txt

    r1109 r1113  
    242242
    243243In addition, templates currently check for the existence and value of a boolean
    244 ``auto_reload`` property. If the property exists and evaluates to a non-truth
    245 value, inlining of included templates is disabled. Inlining is a small
    246 optimization that removes some overhead in the processing of includes.
     244``auto_reload`` property. If the property does not exist or evaluates to a
     245non-truth value, inlining of included templates is disabled. Inlining is a
     246small optimization that removes some overhead in the processing of includes.
    247247
    248248Subclassing ``TemplateLoader``
Note: See TracChangeset for help on using the changeset viewer.