Edgewall Software

Version 3 (modified by cmlenz, 13 years ago) (diff)




Utilities for internationalization and localization of templates.


Can extract and translate localizable strings from markup streams and templates.

For example, assume the followng template:

>>> from genshi.template import MarkupTemplate
>>> tmpl = MarkupTemplate('''<html xmlns:py="http://genshi.edgewall.org/">
...   <head>
...     <title>Example</title>
...   </head>
...   <body>
...     <h1>Example</h1>
...     <p>${_("Hello, %(name)s") % dict(name=username)}</p>
...   </body>
... </html>''', filename='example.html')

For demonstration, we define a dummy gettext-style function with a hard-coded translation table, and pass that to the Translator initializer:

>>> def pseudo_gettext(string):
...     return {
...         'Example': 'Beispiel',
...         'Hello, %(name)s': 'Hallo, %(name)s'
...     }[string]
>>> translator = Translator(pseudo_gettext)

Next, the translator needs to be prepended to any already defined filters on the template:

>>> tmpl.filters.insert(0, translator)

When generating the template output, our hard-coded translations should be applied as expected:

>>> print tmpl.generate(username='Hans', _=pseudo_gettext)
    <p>Hallo, Hans</p>

Note that elements defining xml:lang attributes that do not contain variable expressions are ignored by this filter. That can be used to exclude specific parts of a template from being extracted and translated.

extract(self, stream, gettext_functions=GETTEXT_FUNCTIONS, search_text=True)

Extract localizable strings from the given template stream.

For every string found, this function yields a (lineno, function, message) tuple, where:

  • lineno is the number of the line on which the string was found,
  • function is the name of the gettext function used (if the string was extracted from embedded Python code), and
  • message is the string itself (a unicode object, or a tuple of unicode objects for functions with multiple string arguments).
>>> from genshi.template import MarkupTemplate
>>> tmpl = MarkupTemplate('''<html xmlns:py="http://genshi.edgewall.org/">
...   <head>
...     <title>Example</title>
...   </head>
...   <body>
...     <h1>Example</h1>
...     <p>${_("Hello, %(name)s") % dict(name=username)}</p>
...     <p>${ngettext("You have %d item", "You have %d items", num)}</p>
...   </body>
... </html>''', filename='example.html')
>>> for lineno, funcname, message in Translator().extract(tmpl.stream):
...    print "%d, %r, %r" % (lineno, funcname, message)
3, None, u'Example'
6, None, u'Example'
7, '_', u'Hello, %(name)s'
8, 'ngettext', (u'You have %d item', u'You have %d items')
param stream:the event stream to extract strings from; can be a regular stream or a template stream
param gettext_functions:
 a sequence of function names that should be treated as gettext-style localization functions
param search_text:
 whether the content of text nodes should be extracted (used internally)
note:Changed in 0.4.1: For a function with multiple string arguments (such as ngettext), a single item with a tuple of strings is yielded, instead an item for each string argument.

extract(fileobj, keywords, comment_tags, options)

Babel extraction method for Genshi templates.

param fileobj:the file-like object the messages should be extracted from
param keywords:a list of keywords (i.e. function names) that should be recognized as translation functions
param comment_tags:
 a list of translator tags to search for and include in the results
param options:a dictionary of additional options (optional)
return:an iterator over (lineno, funcname, message, comments) tuples

See ApiDocs/0.4.x, Documentation, Stream filters