+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
+* 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.