genshi.filters.i18n.Translator

Package genshi :: Package filters :: Module i18n :: Class Translator |

# Class Translator

    object --+
             |
            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.

Instance Methods
__init__(self, translate=<function gettext at 0x6484f0>, ignore_tags=`frozenset([`QName(u'script')`,` QName(u'style')`,` QName(u'http://w`...`, include_attrs=`frozenset([``'``abbr``'``,` `'``alt``'``,` `'``label``'``,` `'``prompt``'``,` `'``standby``'``,` `'``summa``...`, extract_text=True) Initialize the translator. |
__call__(self, stream, ctxt=None, search_text=True, msgbuf=None) Translate any localizable strings in the given stream. |
extract(self, stream, gettext_functions=`(``'``_``'``,` `'``gettext``'``,` `'``ngettext``'``,` `'``dgettext``'``,` `'``dngettext``'``,` `'``ugettex``...`, search_text=True, msgbuf=None) Extract localizable strings from the given template stream. |
Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__str__`

Class Variables
| IGNORE_TAGS = ``frozenset([`QName(u'script')`,` QName(u'style')`,` QN`...``
| INCLUDE_ATTRS = ``frozenset([``'``abbr``'``,` `'``alt``'``,` `'``label``'``,` `'``prompt``'``,` `'``...``
| GETTEXT_FUNCTIONS = ``(``'``_``'``,` `'``gettext``'``,` `'``ngettext``'``,` `'``dgettext``'``,` `'``...``

Properties
Inherited from `object`: `__class__`

Method Details

### __init__(self, translate=<function gettext at 0x6484f0>, ignore_tags=`frozenset([`QName(u'script')`,` QName(u'style')`,` QName(u'http://w`...`, include_attrs=`frozenset([``'``abbr``'``,` `'``alt``'``,` `'``label``'``,` `'``prompt``'``,` `'``standby``'``,` `'``summa``...`, extract_text=True) (Constructor) |
Initialize the translator. Parameters: `translate` - the translation function, for example `gettext` or `ugettext`. `ignore_tags` - a set of tag names that should not be localized `include_attrs` - a set of attribute names should be localized `extract_text` - whether the content of text nodes should be extracted, or only text in explicit `gettext` function calls Overrides: object.__init__

### __call__(self, stream, ctxt=None, search_text=True, msgbuf=None) (Call operator) |
Translate any localizable strings in the given stream. This function shouldn't be called directly. Instead, an instance of the Translator class should be registered as a filter with the Template or the TemplateLoader, or applied as a regular stream filter. If used as a template filter, it should be inserted in front of all the default filters. Parameters: `stream` - the markup event stream `ctxt` - the template context (not used) `search_text` - whether text nodes should be translated (used internally) `msgbuf` - a MessageBuffer object or `None` (used internally) Returns: the localized stream

### extract(self, stream, gettext_functions=`(``'``_``'``,` `'``gettext``'``,` `'``ngettext``'``,` `'``dgettext``'``,` `'``dngettext``'``,` `'``ugettex``...`, 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)
Parameters: `stream` - the event stream to extract strings from; can be a regular stream or a template stream `gettext_functions` - a sequence of function names that should be treated as gettext-style localization functions `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.

Class Variable Details

  ### IGNORE_TAGS Value:
      frozenset([QName(u'script'),
                 QName(u'style'),
                 QName(u'http://www.w3.org/1999/xhtml}script'),
                 QName(u'http://www.w3.org/1999/xhtml}style')])

  ### INCLUDE_ATTRS Value:
      frozenset(['abbr',
                 'alt',
                 'label',
                 'prompt',
                 'standby',
                 'summary',
                 'title'])

  ### GETTEXT_FUNCTIONS Value:
      ('_',
       'gettext',
       'ngettext',
       'dgettext',
       'dngettext',
       'ugettext',
       'ungettext')