From b9c5c978d904bc3494dfc2922a505073f42c1e5c Mon Sep 17 00:00:00 2001 From: Sean McGinnis Date: Sat, 23 Jul 2016 20:37:58 -0500 Subject: [PATCH] Docs: Correct i18n information 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 --- doc/source/devref/i18n.rst | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/doc/source/devref/i18n.rst b/doc/source/devref/i18n.rst index 68416e182a5..a829fe2ade2 100644 --- a/doc/source/devref/i18n.rst +++ b/doc/source/devref/i18n.rst @@ -1,23 +1,37 @@ Internationalization ==================== -cinder uses `gettext `_ so that + +For internationalization guidelines, see the +`oslo.i18n documention `_. +The information below can be used to get started. + +Cinder uses `gettext `_ 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 +