网页 综合 更新时间 2026-11-17 02:11:28

Internationalization — Sphinx documentation

自动蜘蛛 www.sphinx-doc.org 正文约 4558 字
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.
Workflow visualization of translations in Sphinx. (The figure is created by plantuml.)¶
Sphinx internationalization details
Translating with sphinx-intl
Update your po files by new pot files
Using Transifex service for team translation
Using Weblate service for team translation
Contributing to Sphinx reference translation
Translation progress and statistics
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 (where es is the language code for Spanish.)
Set locale_dirs to ["locale/"].
Set language to es (also possible via -D).
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:
(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.
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.
Add configurations to conf.py.
This case-study assumes that BUILDDIR is set to _build, locale_dirs is set to locale/ and gettext_compact is set to False (the Sphinx document is already configured as such).
Extract translatable messages into pot files.
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, the default pot file template can be replaced by a custom message.pot.jinja file placed in any directory listed in templates_path.
We’ll use the pot files generated in the above step.
Once completed, the generated po files will be placed in the below directories:
./locale/de/LC_MESSAGES/
./locale/ja/LC_MESSAGES/
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.
Another case, msgid is multi-line text and contains reStructuredText syntax:
Please be careful not to break reStructuredText notation. Most po-editors will help you with that.
Build translated document.
You need a language parameter in conf.py or you may also specify the parameter on the command line.
For BSD/GNU make, run:
访问原文 返回搜索 https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。