国际化

Added in version 1.1.

作为对Sphinx生成的消息（如导航栏）提供的翻译的补充，Sphinx提供了促进*文档*翻译的机制。有关配置的详细信息，请参阅：ref:intl options。

../../_images/translation.svg

Sphinx翻译的工作流可视化（图形由 plantuml 创建）。

sphinx国际化细节

**gettext**[1]u是国际化和本地化的既定标准。它天真地将程序中的消息映射到翻译后的字符串。斯芬克斯使用这些工具翻译整个文件。

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.

doctree中的每个元素都将以一条消息结束，这将导致列表被平均地分成不同的块，而大的段落将保持与原始文档中一样的粗粒度。这就允许无缝的文档更新，同时仍然为自由文本段中的翻译人员提供一点上下文。维护人员的任务是分割太大的段落，因为没有一种合理的自动化方法来分割这些段落。

在Sphinx成功运行：类之后：`~sphinx.builders.gettext.MessageCatalogBuilder`您将在输出目录中找到一组“.pot”文件。这些是**目录模板**，只包含您的原始语言*的消息*。

它们可以被传递给翻译程序，翻译程序会将它们转换成`.po``文件，即所谓的**消息目录**，其中包含从原始消息到外语字符串的映射。

*为了提高效率，gettext*将它们编译成一种称为**二进制目录**的二进制格式：program:`msgfmt’。如果您使用：confval:`locale_dirs`为您的：confval:`language`设置这些文件的可发现性，Sphinx将自动提取它们。

例如：你有一份文件``usage.rst``在你的Sphinx项目中。gettext*生成器将把它的消息放入``usage.pot``. 假设您在中存储了西班牙语翻译[2]``usage.po``需要按照以下说明进行编译：

  • 将您的消息目录编译到一个locale目录中，比如“locale”，这样它就以`./locale/es/LC峎MESSAGES结束/用法.mo``在源目录中（其中“es”是西班牙语的语言代码）：

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

  • Set locale_dirs to ["locale/"].

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

  • 运行所需的构建。

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.

用sphinx国际翻译

快速指南

`sphinx intl`是一个使用sphinx转换流的有用工具。本节介绍一种使用*sphinx intl*进行翻译的简单方法。

  1. 安装`sphinx-intl`_.

    $ pip install sphinx-intl

  2. 将配置添加到``conf.py``.

    locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.

    这个案例研究假设BUILDDIR被设置为’u build``，：confval:`locale_dirs`被设置为``locale/``并且：confval:`gettext_compact`被设置为`False``（Sphinx文档已经这样配置）。

  3. 将可翻译的消息提取到pot文件中。

    $ make gettext

    生成的pot文件将被放在``u build/gettext``目录中。

  4. 生成采购订单文件。

    我们将使用上述步骤中生成的pot文件。

    $ sphinx-intl update -p _build/gettext -l de -l ja

    完成后，生成的采购订单文件将放在以下目录中：

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. 翻译采购订单文件。

    如上所述，它们位于 ./locale/<lang>/LC_MESSAGES 目录中。一个这样的文件的例子，来自sphinx，builders.po，如下所示。

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

    另一种情况是，msgid是多行文本，并包含restructedText语法：

    # 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."

    请注意不要破坏reST符号。大多数po编辑都会帮你。

  6. 生成翻译文档。

    您需要一个：confval:`language`参数``conf.py``也可以在命令行中指定参数。

    For BSD/GNU make, run:

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

    对于Windows:命令：命令提示符，运行：

    > set SPHINXOPTS=-D language=de
> .\make.bat html

    为PowerShell运行：

    > Set-Item env:SPHINXOPTS "-D language=de"
> .\make.bat html

祝贺你！翻译后的文档在``u build/html``目录下。

Added in version 1.3: ：程序：make命令调用的“sphinx build”将把po文件生成mo文件。

如果您使用的是1.2.x或更早版本，请在命令之前调用：command:`sphinx intl build`命令：command:`make`command。

翻译

用新的pot文件更新你的po文件

如果更新了文档，则需要生成更新的pot文件，并将差异应用于已翻译的po文件。要将pot文件中的更新应用于po文件，请使用：命令：`sphinx intl update`命令。

$ sphinx-intl update -p _build/gettext

使用Transifex服务进行团队翻译

Transifex_x是允许通过web界面进行协作翻译的几种服务之一。它有一个漂亮的基于Python的命令行客户机，使得获取和推送翻译变得很容易。

  1. 安装 transifex-client.

    您需要：command:`tx`命令来上载资源（pot文件）。

    $ pip install transifex-client

    参见

    Transifex Client 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 the document, so you’d better include a version number in your project name.

    例如：

    项目ID:

    sphinx-document-test_1_0

    项目URL:

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

  3. 为：command:`tx`command创建配置文件。

    此进程将在当前目录中创建“.tx/config”，以及包含身份验证信息的“~/.transifexrc”文件。

    $ tx init
Creating .tx folder...
Transifex instance [https://www.transifex.com]:
...
Please enter your transifex username: <transifex-username>
Password: <transifex-password>
...
Done.

  4. Upload pot files to Transifex service.

    将pot文件注册到“.tx/config”文件：

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

    以及上传pot文件

    $ 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. 拉翻译后的采购订单文件，并制作翻译的HTML。

    获取翻译的目录并生成mo文件。例如，要为德语（de）生成mo文件：

    $ 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`（对于BSD/GNU make）：

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

到此为止

小技巧

本地和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.

换句话说，如果您已经更新了服务和本地po文件中的每一个文件，那么集成它们将花费大量的时间和精力。

Using Weblate service for team translation

Read more in Weblate’s documentation.

有助于sphinx参考翻译

新贡献者翻译sphinx参考文献的推荐方式是加入Transifex上的翻译团队。

Sphinx (master) 文档有 sphinx translation page。

  1. Login to Transifex service.

  2. 去sphinx翻译页面

  3. 单击“请求语言”并填写表单。

  4. Wait acceptance by Transifex sphinx translation maintainers.

  5. (After acceptance) Translate on Transifex.

细节位于： https://docs.transifex.com/getting-started-1/translators

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.

脚注