国际化¶

版本 1.1 新增。

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

../../_images/translation.svg — Sphinx 中翻译的工作流可视化。(此图由 plantuml 创建。)¶

Sphinx 国际化详情 ¶

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

最初，项目维护者必须收集所有可翻译的字符串（也称为消息），以便翻译人员知晓。Sphinx 通过调用 sphinx-build -M gettext 来提取这些字符串。

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

在 Sphinx 成功运行 MessageCatalogBuilder 之后，你会在输出目录中找到一系列 .pot 文件。这些是目录模板，只包含原始语言的消息。

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

gettext 出于效率原因，通过 msgfmt 将它们编译成二进制格式，即二进制目录。如果你通过 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 在其中被忽略。）

在 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 目录中获得了翻译好的文档。

在 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 是少数几个允许通过 Web 界面进行协作翻译的服务之一。它有一个基于 Go 的精巧命令行客户端，可以轻松地获取和推送翻译。

安装 Transifex CLI 工具。

您需要 tx 命令行工具来上传资源（pot 文件）。官方安装过程将 tx 二进制文件放置在当前目录中，以及一个 README 和一个 LICENSE 文件，并将当前目录添加到 $PATH。
```
$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
```
另请参阅

Transifex 客户端文档
创建您的 Transifex 帐户，并为您的文档创建一个新项目和组织。

目前，Transifex 不允许一个翻译项目有多个版本的文档，所以你最好在项目名称中包含版本号。

例如

组织 ID:

sphinx-document

项目 ID:

sphinx-document-test_1_0

项目 URL:

https://www.transifex.com/projects/p/sphinx-document-test_1_0/
创建一个用于命令行的 API 令牌。

前往您的 Transifex API 令牌页面并生成一个令牌。立即复制生成的令牌，因为之后将无法再次查看。

在用户配置文件 $HOME/.transifexrc 中设置您的 Transifex API 令牌。

[https://app.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = paste_your_api_token_here

或者，您可以将 Transifex API 令牌存储为环境变量 TX_TOKEN，该变量会被 tx 识别并使用。
```
$ export TX_TOKEN=paste_your_api_token_here
```
为 tx 命令创建项目配置文件。

此过程将在当前目录中创建 .tx/config。
```
$ cd /your/document/root
$ tx init

Successful creation of '.tx/config' file
```

上传 pot 文件到 Transifex 服务。

使用 sphinx-intl update-txconfig-resources 命令将 pot 文件注册到 .tx/config 文件，并调整 --pot-dir 的值为你项目的 pot 文件目录

$ 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

您可以使用 SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME 和 SPHINXINTL_TRANSIFEX_PROJECT_NAME 环境变量，而不是相应的命令行参数。

另请参阅

sphinx-intl update-txconfig-resources 文档

并上传 pot 文件

$ 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

在 Transifex 上推进翻译。

拉取翻译后的 po 文件并生成翻译后的 HTML。

获取翻译目录并构建 mo 文件。例如，为德语 (de) 构建 mo 文件

$ 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

调用 make html（对于 BSD/GNU make），并传递语言代码

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

仅此而已！

提示

在本地和 Transifex 上翻译

如果你想推送所有语言的 po 文件，可以使用 tx push -t 命令完成。注意！此操作会覆盖 Transifex 中的翻译。

换句话说，如果您同时更新了服务和本地 po 文件，整合它们将耗费大量时间和精力。

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

请参阅 Weblate 文档以了解更多信息。

为 Sphinx 参考翻译贡献 ¶

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

Sphinx (master) 文档有一个 Sphinx 翻译页面。

登录 Transifex 服务。
前往 “Sphinx 文档”翻译项目。
点击 请求语言 并填写表格。
等待 Transifex Sphinx 翻译维护者的接受。
（接受后）在 Transifex 上进行翻译。

详情请见：https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

翻译进度和统计 ¶

在 7.1.0 版本中新增。

在渲染过程中，Sphinx 会用 translated 属性标记每个可翻译节点，表示该节点中的文本是否找到了翻译。

translation_progress_classes 配置值可用于根据 translated 属性的值向每个元素添加一个类。

|translation progress| 替换可以用来显示每个文档中已翻译节点的百分比。

脚注