国际化¶
版本 1.1 中新增。
除了为 Sphinx 生成的消息（如导航栏）提供的翻译外，Sphinx 还提供了有助于翻译文档的机制。有关配置详细信息，请参阅国际化选项。
Sphinx 国际化细节¶
gettext [1] 是国际化和本地化的既定标准。它简单地将程序中的消息映射到翻译后的字符串。Sphinx 使用这些功能来翻译整个文档。
最初，项目维护人员必须收集所有可翻译的字符串（也称为消息），以使翻译人员了解这些字符串。Sphinx 通过调用sphinx-build -M gettext来提取这些字符串。
doctree 中的每个元素最终都将成为一条消息，这会导致列表被均匀地拆分为不同的块，而较大的段落将保持与原始文档一样粗粒度。这使得文档更新变得无缝，同时仍然为自由文本段落中的翻译人员提供了一些上下文。将过大的段落拆分是维护人员的任务，因为没有合理的方法可以自动执行此操作。
在 Sphinx 成功运行MessageCatalogBuilder后，您将在输出目录中找到一系列.pot文件。这些是目录模板，仅包含您原始语言中的消息。
它们可以交付给翻译人员，翻译人员会将其转换为.po文件——即所谓的消息目录——其中包含从原始消息到外语字符串的映射。
出于效率原因，gettext会通过msgfmt将其编译成称为二进制目录的二进制格式。如果您使用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"
将
locale_dirs设置为["locale/"]。运行您所需的构建。
为了防止出错，如果翻译后的段落中的交叉引用与原始段落中的交叉引用不匹配，则会发出警告。可以使用suppress_warnings配置变量全局关闭此功能。或者，要仅关闭一条消息的警告，请在消息末尾添加#noqa，如下所示
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #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目录中。如果您想自定义超出国际化选项所能实现的内容的输出，则可以使用自定义message.pot.jinja文件替换默认 pot 文件 模板，该文件放置在templates_path中列出的任何目录中。生成 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 的简洁命令行客户端，可以轻松地获取和推送翻译。
-
您需要tx命令行工具来上传资源（pot 文件）。官方安装过程会将
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 令牌页面并生成一个令牌。立即复制生成的令牌，因为您以后将无法再次看到它。
在用户配置文件
$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 文档。
为 Sphinx 参考翻译做出贡献¶
建议新贡献者加入 Transifex 上的翻译团队来翻译 Sphinx 参考文档。
Sphinx（主版本）文档有一个 Sphinx 翻译页面。
登录 Transifex 服务。
转到 Sphinx 翻译页面。
点击
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| 替换可以用于显示每个文档已翻译节点的百分比。
脚注