国际化¶
在 1.1 版本加入.
作为对Sphinx生成的消息（如导航栏）提供的翻译的补充，Sphinx提供了促进 文档 翻译的机制。有关配置的详细信息，请参阅 用于国际化的选项。
Sphinx国际化细节¶
gettext [1] 是国际化和本地化的既定标准。它简单地将程序中的消息映射到翻译后的字符串。Sphinx使用这些工具翻译整个文件。
最初，项目维护人员必须收集所有可翻译的字符串（也称为 消息 ）以使其为翻译人员所知。Sphinx通过调用 sphinx-build -M gettext 来提取这些字符串。
doctree中的每个元素都将以一条消息结束，这将导致列表被平均地分成不同的块，而大的段落将保持与原始文档中一样的粗粒度。这就允许无缝的文档更新，同时仍然为自由文本段中的翻译人员提供一点上下文。维护人员的任务是分割太大的段落，因为没有一种合理的自动化方法来分割这些段落。
在Sphinx成功运行 MessageCatalogBuilder 后，您将在输出目录中找到一组 .pot 文件。这些是 catalog templates ， 只 包含您的原始语言的消息。
它们可以被传递给翻译程序，翻译程序会将它们转换成 .po 文件，即所谓的 消息目录，其中包含从原始消息到外语字符串的映射。
为了提高效率，gettext 使用 msgfmt 将它们编译成一种称为 binary catalogs 的二进制格式。如果您使用 locale_dirs 为您 language 设置这些文件的可发现性，Sphinx将自动提取它们。
一个例子：您在Sphinx项目中有一个文档 usage.rst 。 gettext 构建器将把它的消息放入 usage.pot 。假设您有存储在 usage.po 中的西班牙语翻译 [2] --- 要进行翻译的构建，您需要遵循以下说明：
将您的消息目录编译到一个区域目录中，比如
locale，这样它最终会出现在您的源目录中的./locale/es/LC_MESSAGES/usage.mo中（其中es是西班牙语的语言代码）。:msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
Set
locale_dirsto["locale/"].运行所需的构建。
为了防止错误，如果翻译段落中的交叉引用与原始段落中的不匹配，则会发出警告。这可以使用配置变量 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目录中。如果您想自定义输出，超出 用于国际化的选项 可以完成的范围，可以通过放置在templates_path列表中的任何目录中的自定义message.pot.jinja文件来替换default pot file template。生成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是多行文本，并包含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."
请注意不要破坏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 版本加入: sphinx-build 被make命令调用，将po文件编译成mo文件。
如果您使用的是1.2.x或更早版本，请在 sphinx-intl build 命令之前调用 make 命令。
翻译¶
用新的pot文件更新你的po文件¶
如果更新了文档，则需要生成更新的pot文件，并将差异应用于已翻译的po文件。要将pot文件中的更新应用于po文件，请使用 sphinx-intl update 命令。
$ sphinx-intl update -p _build/gettext
使用Transifex服务进行团队翻译¶
Transifex 是几种允许通过Web界面进行协作翻译的服务之一。它有一个巧妙的基于Go的命令行客户端，使获取和推送翻译变得容易。
-
为了上传资源（pot文件），您需要 tx 命令行工具。官方安装过程将
tx二进制文件放在当前目录中，以及一个README和一个LICENSE文件，并将当前目录添加到$PATH中。$ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
创建您的 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 token页面并生成一个令牌。现在复制生成的令牌，因为您以后将无法再次看到它。
在用户配置文件
$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环境变量来代替各自的命令行参数。以及上传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's documentation。
对 Sphinx参考翻译 做贡献¶
新贡献者翻译sphinx参考文献的推荐方式是加入Transifex上的翻译团队。
Sphinx（master）文档有一个 Sphinx translation page 。
登录到 Transifex 服务。
单击
Request language并填写表单。等待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| 替换来显示每个文档中已翻译节点的百分比。
脚注