Internationalization
====================
Manila uses `gettext <http://docs.python.org/library/gettext.html>`_ so that
user-facing strings appear in the appropriate language in different locales.

Beginning with the Pike series, OpenStack no longer supports log translation.
It is not useful to add translation instructions to new code, and the
instructions can be removed from old code.

Other user-facing strings, e.g. in exception messages, should be translated.

To use gettext, make sure that the strings passed to the logger are wrapped
in a ``_()`` function call. For example::

    msg = _("Share group %s not found.") % share_group_id
    raise exc.HTTPNotFound(explanation=msg)

Do not use ``locals()`` for formatting messages because:
1. It is not as clear as using explicit dicts.
2. It could produce hidden errors during refactoring.
3. Changing the name of a variable causes a change in the message.
4. It creates a lot of otherwise unused variables.

If you do not follow the project conventions, your code may cause the
LocalizationTestCase.test_multiple_positional_format_placeholders test to fail
in manila/tests/test_localization.py.

The ``_()`` function is brought into the global scope by doing::

    from manila.openstack.common import gettextutils
    gettextutils.install("manila")

These lines are needed in any toplevel script before any manila modules are
imported. If this code is missing, it may result in an error that looks like::

    NameError: name '_' is not defined