Edgewall Software

  1. Translator
    1. extract
  2. MessageBuffer
    1. append
    2. format
    3. translate
  3. parse_msg
  4. extract_from_code
  5. extract

genshi.filters.i18n

Utilities for internationalization and localization of templates.

since:version 0.4

Translator

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)
<html>
  <head>
    <title>Beispiel</title>
  </head>
  <body>
    <h1>Beispiel</h1>
    <p>Hallo, Hans</p>
  </body>
</html>

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, msgbuf=None)

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', None)
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.

MessageBuffer

Helper class for managing internationalized mixed content.

since:version 0.5

append(self, kind, data, pos)

Append a stream event to the buffer.

param kind:the stream event kind
param data:the event data
param pos:the position of the event in the source

format(self)

Return a message identifier representing the content in the buffer.

translate(self, string, regex=recompile%\((\w+)\)s)

Interpolate the given message translation with the events in the buffer and return the translated stream.

param string:the translated message string

parse_msg(string, regex=recompile(?:\[(\d+)\:)|\])

Parse a translated message using Genshi mixed content message formatting.

>>> parse_msg("See [1:Help].")
[(0, 'See '), (1, 'Help'), (0, '.')]

>>> parse_msg("See [1:our [2:Help] page] for details.")
[(0, 'See '), (1, 'our '), (2, 'Help'), (1, ' page'), (0, ' for details.')]

>>> parse_msg("[2:Details] finden Sie in [1:Hilfe].")
[(2, 'Details'), (0, ' finden Sie in '), (1, 'Hilfe'), (0, '.')]

>>> parse_msg("[1:] Bilder pro Seite anzeigen.")
[(1, ''), (0, ' Bilder pro Seite anzeigen.')]
param string:the translated message string
return:a list of (order, string) tuples
rtype:list

extract_from_code(code, gettext_functions)

Extract strings from Python bytecode.

>>> from genshi.template.eval import Expression

>>> expr = Expression('_("Hello")')
>>> list(extract_from_code(expr, Translator.GETTEXT_FUNCTIONS))
[('_', u'Hello')]

>>> expr = Expression('ngettext("You have %(num)s item", '
...                            '"You have %(num)s items", num)')
>>> list(extract_from_code(expr, Translator.GETTEXT_FUNCTIONS))
[('ngettext', (u'You have %(num)s item', u'You have %(num)s items', None))]
param code:the Code object
type code:genshi.template.eval.Code
param gettext_functions:
 a sequence of function names
since:version 0.5

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
rtype:iterator

See Internationalization and Localization, ApiDocs/0.5.x, Documentation

Last modified 9 years ago Last modified on Dec 10, 2015, 6:15:05 AM