Add a section about updating locales to the devguide.

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/devguide.rst b/doc/devguide.rst
index ab4bc740..cc3c8248 100644
--- a/doc/devguide.rst
+++ b/doc/devguide.rst
@@ -168,6 +168,39 @@ The following are some general guidelines for core developers:
   encouraged.
 
 
+Locale updates
+~~~~~~~~~~~~~~
+
+The parts of messages in Sphinx that go into builds are translated into several
+locales.  The translations are kept as gettext ``.po`` files translated from the
+master template ``sphinx/locale/sphinx.pot``.
+
+Sphinx uses `Babel <http://babel.edgewall.org>`_ to extract messages and
+maintain the catalog files.  It is integrated in ``setup.py``:
+
+* Use ``python setup.py extract_messages`` to update the ``.pot`` template.
+* Use ``python setup.py update_catalog`` to update all existing language
+  catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the
+  template file.
+* Use ``python setup.py compile_catalog`` to compile the ``.po`` files to binary
+  ``.mo`` files and ``.js`` files.
+
+When an updated ``.po`` file is submitted, run compile_catalog to commit both
+the source and the compiled catalogs.
+
+When a new locale is submitted, add a new directory with the ISO 639-1 language
+identifier and put ``sphinx.po`` in there.  Don't forget to update the possible
+values for :confval:`language` in ``doc/config.rst``.
+
+The Sphinx core messages can also be translated on `Transifex
+<http://transifex.com>`_.  There exists a client tool named ``tx`` in the Python
+package "transifex_client", which can be used to pull translations in ``.po``
+format from Transifex.  To do this, go to ``sphinx/locale`` and then run
+``tx pull -f -l LANG`` where LANG is an existing language identifier.  It is
+good practice to run ``python setup.py update_catalog`` afterwards to make sure
+the ``.po`` file has the canonical Babel formatting.
+
+
 Coding Guide
 ------------