diff options
author | Jenkins <jenkins@review.openstack.org> | 2016-11-09 18:29:47 +0000 |
---|---|---|
committer | Gerrit Code Review <review@openstack.org> | 2016-11-09 18:29:47 +0000 |
commit | c3682ff30354b42a2513ea5c3b9e53fe6f77ed41 (patch) | |
tree | 7bd54e46fdd00c97d740033f1bf328d563d81f99 | |
parent | e6900d29c6ee66d52bc3be26723b422e4c09b3cd (diff) | |
parent | ccc357e0a202c374229cd9c43a4361c52a74836e (diff) | |
download | oslo-i18n-c3682ff30354b42a2513ea5c3b9e53fe6f77ed41.tar.gz |
Merge "Add docs on how to display translated strings in your app"
-rw-r--r-- | doc/source/usage.rst | 41 |
1 files changed, 41 insertions, 0 deletions
diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 14c0b35..1c92fdd 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -216,3 +216,44 @@ module provides a domain defined specific function. .. seealso:: * :doc:`guidelines` + +Displaying translated messages +============================== + +Several preparations are required to display translated messages in your +running application. + +Preferred language + You need to specify your preferred language through an environment variable. + The preferred language can be specified by ``LANGUAGE``, ``LC_ALL``, + ``LC_MESSAGES``, or ``LANGUAGE`` (A former one has a priority). + + ``oslo_i18n.translate()`` can be used to translate a string to override the + preferred language. + + .. note:: + + You need to use ``enable_lazy()`` to override the preferred language + by using ``oslo_i18n.translate()``. + +Locale directory + Python ``gettext`` looks for binary ``mo`` files for the given domain + using the path ``<localedir>/<language>/LC_MESSAGES/<domain>.mo``. + The default locale directory varies on distributions, + and it is ``/usr/share/locale`` in most cases. + + If you store message catalogs in a different location, + you need to specify the location via an environment variable + named ``<DOMAIN>_LOCALEDIR`` where ``<DOMAIN>`` is an upper-case + domain name with replacing ``_`` and ``.`` with ``-``. + For example, ``NEUTRON_LOCALEDIR`` for a domain ``neutron`` and + ``OSLO_I18N_LOCALEDIR`` for a domain ``oslo_i18n``. + + .. note:: + + When you specify locale directories via ``<DOMAIN>_LOCALEDIR`` + environment variables, you need to specify an environment variable per + domain. More concretely, if your application using a domain ``myapp` + uses oslo.policy, you need to specify both ``MYAPP_LOCALEDIR`` and + ``OSLO_POLICY_LOCALEDIR`` to ensure that translation messages from + both your application and oslo.policy are displayed. |