New in version 1.1.
Complementary to translations provided for Sphinx-generated messages such as navigation bars, Sphinx provides mechanisms facilitating document translations in itself. See the Options for internationalization for details on configuration.
gettext  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
.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
— 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
locale_dirs for your
language, Sphinx will pick them
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  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.moin your source directory (where
esis the language code for Spanish.)
msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
Run your desired build.
sphinx-intl is a useful tool to work with Sphinx translation flow. This section describe a easy way to translate with sphinx-intl.
Install sphinx-intl by pip install sphinx-intl or easy_install sphinx-intl.
Add configurations to your conf.py:
locale_dirs = ['locale/'] # path is example but recommended. gettext_compact = False # optional.
Extract document’s translatable messages into pot files:
$ make gettext
As a result, many pot files are generated under
Setup/Update your locale_dir:
$ sphinx-intl update -p _build/locale -l de -l ja
Done. You got these directories that contain po files:
Translate your po files under ./locale/<lang>/LC_MESSAGES/.
make translated document.
You need a
conf.pyor you may also specify the parameter on the command line:
$ make -e SPHINXOPTS="-D language='de'" html
Congratulations! You got the translated documentation in the
New in version 1.3: sphinx-build that is invoked by make command will build po files into mo files.
If you are using 1.2.x or earlier, please invoke
sphinx-intl build command
before make command.
Translate po file under
The case of builders.po file for sphinx document:
# a5600c3d2e3d48fc8c261ea0284db79b #: ../../builders.rst:4 msgid "Available builders" msgstr "<FILL HERE BY TARGET LANGUAGE>"
Another case, msgid is multi-line text and contains reStructuredText syntax:
# 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."
Please be careful not to break reST notation. Most po-editors will help you with that.
If a document is updated, it is necessary to generate updated pot files and to apply differences to translated po files. In order to apply the updating difference of a pot file to po file, use the sphinx-intl update command.
$ sphinx-intl update -p _build/locale
Transifex is one of several services that allow collaborative translation via a web interface. It has a nifty Python-based command line client that makes it easy to fetch and push translations.
You need tx command to upload resources (pot files).
$ pip install transifex-client
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 the document, so you’d better include a version number in your project name.
Create config files for tx command
This process will create
.tx/configin the current directory, as well as a
~/.transifexrcfile that includes auth information.
$ tx init Creating .tx folder... Transifex instance [https://www.transifex.com]: ... Please enter your transifex username: <transifex-username> Password: <transifex-password> ... Done.
Upload pot files to transifex service
Register pot files to
$ 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.
Forward the translation on transifex
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.
Invoke make html:
$ make -e SPHINXOPTS="-D language='de'" html
Translating locally and on Transifex
If you want to push all language’s po files, you can be done by using tx push -t command. Watch out! This operation overwrites translations in transifex.
In other words, if you have updated each in the service and local po files, it would take much time and effort to integrate them.
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.3 documentation.
- Login to transifex service.
- Go to sphinx translation page.
Request languageand fill form.
- Wait acceptance by transifex sphinx translation maintainers.
- (after acceptance) translate on transifex.
|||See the GNU gettext utilities for details on that software suite.|
|||Because nobody expects the Spanish Inquisition!|