openstack/cinder
Code Issues Proposed changes

Docs: Correct i18n information

Browse Source 
The internationalization devref information was out of date from our current
practices. Updated to show the correct translation markers to use and fix
example showing bad practice of mismatches marker and pre-formatting of
message string.

Change-Id: I16c34704c338979bafc7f04474d6f3d427276bed
This commit is contained in:
Sean McGinnis 2016-07-23 20:37:58 -05:00
parent 99c362bb77
commit b9c5c978d9
1 changed files with 24 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/source/devref/i18n.rst
View File

@ -1,23 +1,37 @@
Internationalization
====================
cinder uses `gettext <http://docs.python.org/library/gettext.html>`_ so that
For internationalization guidelines, see the
`oslo.i18n documention <http://docs.openstack.org/developer/oslo.i18n/guidelines.html>`_.
The information below can be used to get started.
Cinder uses `gettext <http://docs.python.org/library/gettext.html>`_ so that
user-facing strings such as log messages appear in the appropriate
language in different locales.
To use gettext, make sure that the strings passed to the logger are wrapped
in a ``_()`` function call. For example::
in a ``_Lx()`` function call. For example::
LOG.info(_("block_device_mapping %s") % block_device_mapping)
LOG.info(_LI("block_device_mapping %s"), block_device_mapping)
There are a few different _() translation markers, depending on the logging
level of the text:
- _LI() - Used for INFO level log messages
- _LW() - Used for WARNING level log messages
- _LE() - Used for ERROR level log messages (this includes LOG.exception)
- _() - Used for any exception messages, including strings used for both
logging and exceptions.
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 cinder/tests/test_localization.py.
If you do not follow the project conventions, your code may cause pep8 hacking
check failures.
For translation to work properly, the top level scripts for Cinder need
to first do the following before any Cinder modules are imported::
@ -25,6 +39,9 @@ to first do the following before any Cinder modules are imported::
from cinder import i18n
i18n.enable_lazy()
Note: this should _only_ be called from top level scripts - no library code
or common modules should call this method.
Any files that use the _() for translation then must have the following
lines::
@ -34,3 +51,4 @@ If the above code is missing, it may result in an error that looks
like::
NameError: name '_' is not defined