Internationalization¶
Added in version 1.1.
Complementary to translations provided for Sphinx-generated messages such as navigation bars, Sphinx provides mechanisms facilitating the translation of documents. See the Options for internationalisation for details on configuration.
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 -M 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] stored 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 (wherees
is the language code for Spanish.)msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
Set
locale_dirs
to["locale/"]
.Run your desired build.
In order to protect against mistakes, a warning is emitted if
cross-references in the translated paragraph do not match those from the
original. This can be turned off globally using the
suppress_warnings
configuration variable. Alternatively, to
turn it off for one message only, end the message with #noqa
like
this:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa
(Write \#noqa
in case you want to have „#noqa“ literally in the
text. This does not apply to code blocks, where #noqa
is ignored
because code blocks do not contain references anyway.)
Added in version 4.5: The #noqa
mechanism.
Translating with sphinx-intl¶
Quick guide¶
sphinx-intl is a useful tool to work with Sphinx translation flow. This section describe an easy way to translate with sphinx-intl.
Install sphinx-intl.
$ pip install sphinx-intl
Add configurations to
conf.py
.locale_dirs = ['locale/'] # path is example but recommended. gettext_compact = False # optional.
This case-study assumes that BUILDDIR is set to
_build
,locale_dirs
is set tolocale/
andgettext_compact
is set toFalse
(the Sphinx document is already configured as such).Extract translatable messages into pot files.
$ make gettext
The generated pot files will be placed in the
_build/gettext
directory. If you want to customize the output beyond what can be done via the Options for internationalisation, thedefault pot file template
can be replaced by a custommessage.pot.jinja
file placed in any directory listed intemplates_path
.Generate po files.
We’ll use the pot files generated in the above step.
$ sphinx-intl update -p _build/gettext -l de -l ja
Once completed, the generated po files will be placed in the below directories:
./locale/de/LC_MESSAGES/
./locale/ja/LC_MESSAGES/
Translate po files.
As noted above, these are located in the
./locale/<lang>/LC_MESSAGES
directory. An example of one such file, from Sphinx,builders.po
, is given below.# 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 reStructuredText notation. Most po-editors will help you with that.
Build translated document.
You need a
language
parameter inconf.py
or you may also specify the parameter on the command line.For BSD/GNU make, run:
$ make -e SPHINXOPTS="-D language='de'" html
For Windows cmd.exe, run:
> set SPHINXOPTS=-D language=de > .\make.bat html
For PowerShell, run:
PS> Set-Item env:SPHINXOPTS "-D language=de" PS> .\make.bat html
Congratulations! You got the translated documentation in the _build/html
directory.
Added 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.
Translating¶
Update your po files by new pot files¶
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 updates from a pot file to the po file, use the sphinx-intl update command.
$ sphinx-intl update -p _build/gettext
Using Transifex service for team translation¶
Transifex is one of several services that allow collaborative translation via a web interface. It has a nifty Go-based command line client that makes it easy to fetch and push translations.
Install the Transifex CLI tool.
You need the tx command line tool for uploading resources (pot files). The official installation process place the
tx
binary file in the current directory along with a README and a LICENSE file, and adds the current directory to$PATH
.$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
Siehe auch
Create your Transifex account and create a new project and an organization 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.
For example:
- Organization ID:
sphinx-document
- Project ID:
sphinx-document-test_1_0
- Project URL:
https://www.transifex.com/projects/p/sphinx-document-test_1_0/
Create an API token to be used in the command-line.
Go to your Transifex API token page and generate a token. Copy the generated token now, as you will not be able to see it again later.
Set your Transifex API token in the user configuration file
$HOME/.transifexrc
.[https://app.transifex.com] rest_hostname = https://rest.api.transifex.com token = paste_your_api_token_here
Alternatively, you can store your Transifex API token as the environment variable
TX_TOKEN
, which is recognized and used by tx.$ export TX_TOKEN=paste_your_api_token_here
Create the project’s config file for tx command.
This process will create
.tx/config
in the current directory.$ cd /your/document/root $ tx init Successful creation of '.tx/config' file
Upload pot files to Transifex service.
Register pot files to
.tx/config
file using sphinx-intl update-txconfig-resources, adjusting--pot-dir
value to your project’s pot files‘ directory:$ cd /your/document/root $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \ --transifex-organization-name=sphinx-document \ --transifex-project-name=sphinx-document-test_1_0
You can use the
SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME
andSPHINXINTL_TRANSIFEX_PROJECT_NAME
environment variables instead of the respective command line arguments.and upload pot files:
$ tx push -s # Getting info about resources sphinx-document-test_1_0.builders - Getting info sphinx-document-test_1_0.builders - Done # Pushing source files sphinx-document-test_1_0.builders - Uploading file sphinx-document-test_1_0.builders - Done
Forward the translation on Transifex.
Pull translated po files and make translated HTML.
Get translated catalogs and build mo files. For example, to build mo files for German (de):
$ cd /your/document/root $ tx pull -l de # Getting info about resources sphinx-document-test_1_0.builders - Getting info sphinx-document-test_1_0.builders - Done # Pulling files sphinx-document-test_1_0.builders [de] - Pulling file sphinx-document-test_1_0.builders [de] - Creating download job sphinx-document-test_1_0.builders [de] - Done
Invoke make html (for BSD/GNU make) passing the language code:
$ make -e SPHINXOPTS="-D language='de'" html
That’s all!
Tipp
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.
Using Weblate service for team translation¶
Read more in Weblate’s documentation.
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 a sphinx translation page for Sphinx (master) documentation.
Login to Transifex service.
Go to sphinx translation page.
Click
Request language
and fill form.Wait acceptance by Transifex sphinx translation maintainers.
(After acceptance) Translate on Transifex.
Detail is here: https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator
Translation progress and statistics¶
Added in version 7.1.0.
During the rendering process,
Sphinx marks each translatable node with a translated
attribute,
indicating if a translation was found for the text in that node.
The translation_progress_classes
configuration value
can be used to add a class to each element,
depending on the value of the translated
attribute.
The |translation progress|
substitution can be used to display the
percentage of nodes that have been translated on a per-document basis.
Fußnoten