diff options
| -rw-r--r-- | doc/devguide.rst | 33 |
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 ------------ |