==================
Catalog strategies
==================

The way flufl.i18n finds its catalog for an application is extensible.  These
are called 'strategies'.  flufl.i18n comes with a couple of fairly simple
strategies.  The first locates catalog files from within a package's
namespace.


Python package strategies
=========================

For example, to use the catalog in flufl.i18n's testing package, you would use
the `PackageStrategy`.

    >>> from flufl.i18n import PackageStrategy
    >>> import flufl.i18n.testing.messages

By setting the $LANG environment variable, we can specify that the application
translates into that language automatically.

    # The testing 'xx' language rot13's the source string.
    >>> import os
    >>> os.environ['LANG'] = 'xx'

The first argument is the application name, which must be unique among all
registered strategies. The second argument is the package in which to search.

    >>> strategy = PackageStrategy('flufl', flufl.i18n.testing.messages)

Once you have the desired strategy, register this with the global registry.
The registration process returns an application object which can be used to
look up language codes.

    >>> from flufl.i18n import registry
    >>> application = registry.register(strategy)

The application object keeps track of a current translation catalog, and
exports a method which you can bind to the 'underscore' function in your
module globals for convenient gettext usage.

    >>> _ = application._

By doing so, at run time, _() will always translate the string argument to the
current catalog's language.

    >>> print _('A test message')
    N grfg zrffntr


Simple strategy
===============

There is also a simpler strategy that uses both the $LANG environment
variable, and the $LOCPATH environment variable to set things up.

    >>> os.environ['LOCPATH'] = os.path.dirname(
    ...     flufl.i18n.testing.messages.__file__)

    # Hack to unregister the previous strategy.
    >>> registry._registry.clear()

    >>> from flufl.i18n import SimpleStrategy
    >>> strategy = SimpleStrategy('flufl')
    >>> application = registry.register(strategy)

    >>> _ = application._
    >>> print _('A test message')
    N grfg zrffntr


Calling with zero arguments
===========================

Strategies should be prepared to accept zero arguments when called, to produce
a 'default' translation (usually the `gettext.NullTranslator`).

    >>> print SimpleStrategy('example')().ugettext('A test message')
    A test message

    >>> print PackageStrategy(
    ...     'example', flufl.i18n.testing.messages)().ugettext(
    ...     'A test message')
    A test message
