国际化

版本 1.1 新增。

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

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。假设你有存储在 usage.po 中的西班牙语翻译 [2] ——为了翻译你的构建，你需要遵循这些说明

• 将你的消息目录编译到区域设置目录，例如 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 进行翻译的简易方法。

1. 安装 sphinx-intl。

   $ pip install sphinx-intl
   

2. 向 conf.py 添加配置。

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

   此案例研究假设 BUILDDIR 设置为 _build，locale_dirs 设置为 locale/，gettext_compact 设置为 False （Sphinx 文档已如此配置）。

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

   $ make gettext
   

   生成的 pot 文件将放置在 _build/gettext 目录中。如果你想自定义输出，超出可以通过 国际化选项 完成的范围，则 默认 pot 文件模板 可以替换为自定义的 message.pot.jinja 文件，该文件放置在 templates_path 中列出的任何目录中。

4. 生成 po 文件。

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

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

   完成后，生成的 po 文件将放置在以下目录中

   • ./locale/de/LC_MESSAGES/

   • ./locale/ja/LC_MESSAGES/

5. 翻译 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 编辑器都会帮助你做到这一点。

6. 构建翻译后的文档。

   你需要在 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 的命令行客户端，可以轻松地获取和推送翻译。

1. 安装 Transifex CLI 工具。

   你需要 tx 命令行工具来上传资源（pot 文件）。官方安装过程将 tx 二进制文件放置在当前目录中， साथ ही README 和 LICENSE 文件，并将当前目录添加到 $PATH。

   $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
   

   另请参阅

   Transifex 客户端文档

2. 创建你的 Transifex 帐户，并为你的文档创建一个新项目和一个组织。

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

   例如

   组织 ID:

   sphinx-document

   项目 ID:

   sphinx-document-test_1_0

   项目 URL:

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

3. 创建一个 API 令牌，用于命令行。

   转到你的 Transifex API 令牌 页面并生成一个令牌。立即复制生成的令牌，因为之后你将无法再次看到它。

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

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

5. 或者，你可以将你的 Transifex API 令牌存储为环境变量 TX_TOKEN，tx 可以识别并使用它。

   $ export TX_TOKEN=paste_your_api_token_here
   

6. 为 tx 命令创建项目的配置文件。

   此过程将在当前目录中创建 .tx/config。

   $ cd /your/document/root
   $ tx init
   
   Successful creation of '.tx/config' file
   

7. 将 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
   

8. 在 Transifex 上转发翻译。

9. 拉取翻译后的 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 翻译页面。

1. 登录 Transifex 服务。

2. 转到 sphinx 翻译页面。

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

4. 等待 Transifex sphinx 翻译维护者的接受。

5. （接受后）在 Transifex 上翻译。

详细信息在此处：https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

翻译进度和统计

版本 7.1.0 新增。

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

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

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

脚注

[1]

有关该软件包的详细信息，请参阅 GNU gettext 实用程序。

[2]

因为没有人期待西班牙宗教裁判所！

上一页

HTML 主题

下一页

Sphinx Web 支持