Edgewall Software

ApiDocs/genshi.filters.i18n

  1. CommentDirective
    1. attach
  2. MsgDirective
    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

CommentDirective

(Not documented)

attach(cls, template, stream, value, namespaces, pos)

(Not documented)

MsgDirective

(Not documented)

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, comments) 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).
  • comments is a list of comments related to the message, extracted from i18n:comment attributes found in the markup
>>> 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 line, func, msg, comments in Translator().extract(tmpl.stream):
...    print "%d, %r, %r" % (line, func, msg)
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.
note:Changed in 0.6: The returned tuples now include a 4th element, which is a list of comments for the translator

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 ApiDocs, Documentation