openstack/cinder
Code Issues Proposed changes
cinder/doc/source/contributor/i18n.rst
Jay S. Bryant 1423480fb6 Make doc/source directory compliant with design in spec 
The following spec defines what each project's doc/source
directory is supposed to look like:

https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

I had not yet moved existing content to follow this design.
This patch does that, moving the devref to the
'contributor' directory.  It also moves the CLI
related documentation into the 'cli' directory.  I have
updated the autodoc generation to now create the api
documentation in 'doc/source/contributor/api'.

This patch also creates a template for future documentation
contribution.  I have created all of the directories
recommended by the spec and have included documentation
as to what should go in each directory.

The index file is updated to point at the new locations for
existing content.

'doc/.gitignore' is updated so that it won't complain about the
automatically generated 'doc/contributor/api' directory.

Change-Id: I55c50fa0b7c1d06c91e40dbcfd11b1c8e8378aa6
2017-07-19 15:59:02 -05:00

2.4 KiB
Raw Blame History

Internationalization

For internationalization guidelines, see the oslo.i18n documentation. 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 _Lx() function call. For example:

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.

Note

Starting with the Pike series, OpenStack no longer supports log translation markers like _Lx(), only _() should still be used for exceptions that could be user facing. It is not necessary to add _Lx() translation instructions to new code, and the instructions can be removed from old code. Refer to the email thread understanding log domain change on the openstack-dev mailing list for more details.

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 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:

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:

from cinder.i18n import _

If the above code is missing, it may result in an error that looks like:

NameError: name '_' is not defined