From 809a71822cd4f77c329c32cbc64b35e222da4cfc Mon Sep 17 00:00:00 2001
From: Lorin Hochstein <lorin@isi.edu>
Date: Tue, 15 Nov 2011 22:28:31 -0500
Subject: [PATCH] Added RST docs on how to use gettext.

Added a page to the RST documentation about gettext usage
for internationalization.

Change-Id: I2b3b25ad3ab5f3d41b5298f6bad18b216644eeed
---
 doc/source/devref/il8n.rst  | 34 ++++++++++++++++++++++++++++++++++
 doc/source/devref/index.rst |  1 +
 2 files changed, 35 insertions(+)
 create mode 100644 doc/source/devref/il8n.rst

diff --git a/doc/source/devref/il8n.rst b/doc/source/devref/il8n.rst
new file mode 100644
index 0000000000..2264630bef
--- /dev/null
+++ b/doc/source/devref/il8n.rst
@@ -0,0 +1,34 @@
+Internationalization
+====================
+nova 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::
+
+    LOG.debug(_("block_device_mapping %s"), block_device_mapping)
+
+If you have multiple arguments, the convention is to use named parameters.
+It's common to use the ``locals()`` dict (which contains the names and values
+of the local variables in the current scope) to do the string interpolation.
+For example::
+
+    label = ...
+    sr_ref = ...
+    LOG.debug(_('Introduced %(label)s as %(sr_ref)s.') % locals())
+
+If you do not follow the project conventions, your code may cause the
+LocalizationTestCase.test_multiple_positional_format_placeholders test to fail
+in nova/tests/test_localization.py.
+
+The ``_()`` function is brought into the global scope by doing::
+
+    import gettext
+    gettext.install("nova", unicode=1)
+
+In general, you shouldn't need to add these to any nova files, since the lines
+are present in ``nova/__init__.py``. However, if this code is missing, it may
+result in an error that looks like like::
+
+    NameError: name '_' is not defined
diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index 6a22b0e740..be1188b782 100644
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -36,6 +36,7 @@ Background Concepts for Nova
    :maxdepth: 3
 
    threading
+   il8n
    distributed_scheduler
    multinic
    zone