New in version 1.1.

Workflow visualization of translations in Sphinx. (The stick-figure is taken from an XKCD comic.)

Sphinx internationalization details

gettext [1] is an established standard for internationalization and localization. It naively maps messages in a program to a translated string. Sphinx uses these facilities to translate whole documents.

Initially project maintainers have to collect all translatable strings (also referred to as messages) to make them known to translators. Sphinx extracts these through invocation of sphinx-build -b gettext.

Every single element in the doctree will end up in a single message which results in lists being equally split into different chunks while large paragraphs will remain as coarsely-grained as they were in the original document. This grants seamless document updates while still providing a little bit of context for translators in free-text passages. It is the maintainer’s task to split up paragraphs which are too large as there is no sane automated way to do that.

After Sphinx successfully ran the MessageCatalogBuilder you will find a collection of .pot files in your output directory. These are catalog templates and contain messages in your original language only.

They can be delivered to translators which will transform them to .po files — so called message catalogs — containing a mapping from the original messages to foreign-language strings.

Gettext compiles them into a binary format known as binary catalogs through msgfmt for efficiency reasons. If you make these files discoverable with locale_dirs for your language, Sphinx will pick them up automatically.

An example: you have a document usage.rst in your Sphinx project. The gettext builder will put its messages into usage.pot. Imagine you have Spanish translations [2] on your hands in usage.po — for your builds to be translated you need to follow these instructions:

• Compile your message catalog to a locale directory, say locale, so it ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory (where es is the language code for Spanish.)

  msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

• Set locale_dirs to ["locale/"].

• Set language to es (also possible via -D).

• Run your desired build.

Translating with sphinx-intl

# a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

# 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

$ sphinx-intl update -p _build/locale

Using Transifex service for team translation

1. Install transifex-client

   You need tx command to upload resources (pot files).

   $ pip install transifex-client
   

   See also

   Transifex Client v0.8 — Transifex documentation

2. Create your transifex account and create new project for your document

   Currently, transifex does not allow for a translation project to have more than one version of document, so you’d better include a version number in your project name.

   For example:

   Project ID:	sphinx-document-test_1_0
   Project URL:	https://www.transifex.com/projects/p/sphinx-document-test_1_0/

3. Create config files for tx command

   This process will create .tx/config in the current directory, as well as ~/.transifexrc file that includes auth information.

   $ tx init --user=<transifex-username> --pass=<transifex-password>
   Creating .tx folder...
   Transifex instance [https://www.transifex.com]:
   ...
   Done.
   

4. Upload pot files to transifex service

   Register pot files to .tx/config file:

   $ cd /your/document/root
   $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
     --transifex-project-name sphinx-document-test_1_0
   

   and upload pot files:

   $ tx push -s
   Pushing translations for resource sphinx-document-test_1_0.builders:
   Pushing source file (locale/pot/builders.pot)
   Resource does not exist.  Creating...
   ...
   Done.
   

5. Forward the translation on transifex

6. Pull translated po files and make translated html

   Get translated catalogs and build mo files (ex. for ‘de’):

   $ cd /your/document/root
   $ tx pull -l de
   Pulling translations for resource sphinx-document-test_1_0.builders (...)
    -> de: locale/de/LC_MESSAGES/builders.po
   ...
   Done.
   

   Build po files into mo and make html:

   $ sphinx-intl build
   $ make -e SPHINXOPTS="-D language='de'" html

That’s all!

Contributing to Sphinx reference translation

The recommended way for new contributors to translate Sphinx reference is to join the translation team on Transifex.

There is sphinx translation page for Sphinx-1.2 document.

1. Login to transifex service.
2. Go to sphinx translation page.
3. Click Request language and fill form.
4. Wait acceptance by transifex sphinx translation maintainers.
5. (after acceptance) translate on transifex.

Footnotes