国际化¶

Added in version 1.1.

除了为 Sphinx 生成的消息（如导航栏）提供翻译外，Sphinx 还提供了促进文档翻译的机制。有关配置的详细信息，请参阅国际化选项。

../../_images/translation.svg — Sphinx 中翻译的工作流程可视化。（该图由 plantuml 创建。）¶

Sphinx 国际化详情 ¶

gettext [1] 是国际化和本地化的既定标准。它简单地将程序中的消息映射到翻译后的字符串。Sphinx 使用这些功能来翻译整个文档。

最初，项目维护者需要收集所有可翻译的字符串（也称为消息 (messages)），以便让翻译人员了解它们。Sphinx 通过调用 sphinx-build -M gettext 来提取这些字符串。

文档树中的每个元素最终都会成为一条消息，这导致列表被均等地分割成不同的块，而大段落则保持与原始文档中一样粗粒度。这使得文档更新无缝进行，同时仍为翻译人员提供了一些自由文本段落的上下文。维护者的任务是将过大的段落分割开，因为没有合理的自动化方法可以做到这一点。

在 Sphinx 成功运行 MessageCatalogBuilder 后，您将在输出目录中找到一组 .pot 文件。这些是 目录模板 (catalog templates)，仅包含原始语言的消息。

它们可以交付给翻译人员，翻译人员会将其转换为 .po 文件——即所谓的 消息目录 (message catalogs )——其中包含从原始消息到外语字符串的映射。

出于效率原因，gettext 通过 msgfmt 将它们编译为称为 二进制目录 (binary catalogs) 的二进制格式。如果您通过 locale_dirs 使这些文件对您的 language 可发现，Sphinx 将自动获取它们。

示例：您的 Sphinx 项目中有文档 usage.rst。gettext 构建器会将其消息放入 usage.pot。假设您有西班牙语翻译 [2] 存储在 usage.po 中——为了让您的构建被翻译，您需要遵循以下说明：

将您的消息目录编译到本地化目录，例如 locale，使其最终位于源目录中的 ./locale/es/LC_MESSAGES/usage.mo （其中 es 是西班牙语的语言代码）:
```
msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
```
将 locale_dirs 设置为 ["locale/"]。
将 language 设置为 es （也可以通过 -D 设置）。
运行您所需的构建。

为了防止错误，如果翻译段落中的交叉引用与原始段落中的不匹配，则会发出警告。可以使用 suppress_warnings 配置变量全局关闭此警告。或者，要仅为一条消息关闭它，请在消息末尾添加 #noqa，如下所示:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

（如果您希望在文本中字面显示 "#noqa"，请写 \#noqa。这不适用于代码块，因为代码块中不包含引用，#noqa 会被忽略。）

Added in version 4.5: #noqa 机制。

使用 sphinx-intl 进行翻译 ¶

快速指南 ¶

sphinx-intl 是用于处理 Sphinx 翻译流程的有用工具。本节介绍使用 sphinx-intl 进行翻译的简单方法。

安装 sphinx-intl 。
```
$ pip install sphinx-intl
```
将配置添加到 conf.py。
```
locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.
```
本案例研究假设 BUILDDIR 设置为 _build，locale_dirs 设置为 locale/，并且 gettext_compact 设置为 False （Sphinx 文档已如此配置）。
将可翻译的消息提取到 pot 文件中。
```
$ make gettext
```
生成的 pot 文件将放置在 _build/gettext 目录中。如果您想自定义输出，而不仅仅是使用国际化选项中的选项，可以将 默认的 pot 文件模板 替换为放置在 templates_path 中列出的任何目录中的自定义 message.pot.jinja 文件。
生成 po 文件。

将使用上述步骤中生成的 pot 文件。
```
$ sphinx-intl update -p _build/gettext -l de -l ja
```
完成后，生成的 po 文件将放置在以下目录中：
- ./locale/de/LC_MESSAGES/
- ./locale/ja/LC_MESSAGES/

翻译 po 文件。

如上所述，这些文件位于 ./locale/<lang>/LC_MESSAGES 目录中。下面给出了来自 Sphinx 的示例文件 builders.po。

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

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

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

请注意不要破坏 reStructuredText 符号。大多数 po 编辑器会帮助您做到这一点。

构建翻译后的文档。

您需要在 conf.py 中设置 language 参数，或者也可以在命令行中指定该参数。

对于 BSD/GNU make，运行：
```
$ make -e SPHINXOPTS="-D language='de'" html
```
对于 Windows cmd.exe，运行：
```
> set SPHINXOPTS=-D language=de
> .\make.bat html
```
对于 PowerShell，运行：
```
PS> Set-Item env:SPHINXOPTS "-D language=de"
PS> .\make.bat html
```

恭喜！您已在 _build/html 目录中获得翻译后的文档。

Added in version 1.3: 由 make 命令调用的 sphinx-build 会将 po 文件构建为 mo 文件。

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

翻译 ¶

使用新的 pot 文件更新您的 po 文件 ¶

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

$ sphinx-intl update -p _build/gettext

使用 Transifex 服务进行团队翻译 ¶

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
```
See also

Transifex Client documentation
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 and SPHINXINTL_TRANSIFEX_PROJECT_NAME environment variables instead of the respective command line arguments.

使用 Weblate 服务进行团队翻译 ¶

更多信息请参阅 Weblate 的文档。

为 Sphinx 参考翻译做出贡献 ¶

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

Sphinx（主分支）文档有 sphinx 翻译页面。

登录 Transifex 服务。
转到 sphinx 翻译页面。
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.

Footnotes