==============
The translator
==============

The translator is a wrapper around Python's standard gettext module, but it
handles unicodes better and reduces the need to duplicate translation
substitution keys.

The translator requires a 'catalog' object which just implements the
.ugettext() method and the .charset() method.

    >>> class Catalog:
    ...     def __init__(self):
    ...         self.translation = None
    ...     def ugettext(self, original):
    ...         return self.translation
    ...     def charset(self):
    ...         # The default is ascii.
    ...         return None

Create a translator.  The translator is not an exported interface.

    >>> from flufl.i18n._translator import Translator
    >>> catalog = Catalog()
    >>> translator = Translator(catalog)

The translator pulls in locals and globals as the substitution keys.

    >>> aqua = 'aardvarks'
    >>> blue = 'badgers'
    >>> cyan = 'cats'
    >>> catalog.translation = '$blue and $cyan and $aqua'

    >>> print translator.translate('anything')
    badgers and cats and aardvarks

Extra substitutions can also be passed in, which override the locals and
globals.

    >>> print translator.translate('anything', dict(blue='bats'))
    bats and cats and aardvarks

The empty string is always translated as the empty string.

    >>> print len(translator.translate(''))
    0

The translated string is always a unicode.

    >>> type(translator.translate('anything'))
    <type 'unicode'>

By default the translated string is dedented.

    >>> catalog.translation = """\
    ...     These are the $blue
    ...     These are the $cyan
    ...     These are the $aqua"""
    >>> for line in translator.translate('anything').splitlines():
    ...     print '--->%s<---' % line[:4]
    --->Thes<---
    --->Thes<---
    --->Thes<---

But you can optionally choose to not dedent the translated string.

    >>> translator = Translator(catalog, dedent=False)
    >>> for line in translator.translate('anything').splitlines():
    ...     print '--->%s<---' % line[:4]
    --->    <---
    --->    <---
    --->    <---
