国际化

Added in version 1.1.

作为对Sphinx生成的消息(如导航栏)提供的翻译的补充，Sphinx提供了促进 documents 。请参阅 国际化的选择 有关配置的详细信息。

../../_images/translation.svg

在Sphinx中实现翻译的工作流可视化。(该图由 plantuml 。)

Sphinx国际化详情

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

最初项目维护者必须收集所有可翻译的字符串（也称为 messages ）让翻译人员了解它们。 Sphinx通过调用 sphinx-build -M gettext .

文档树中的每个元素都将以一条消息结束，这将导致列表被平均分割为不同的块，而大段将保持与原始文档中一样的粗粒度。这实现了无缝的文档更新，同时仍然为自由文本段落中的翻译人员提供了一些上下文。维护人员的任务是拆分太大的段落，因为没有合理的自动方法来做到这一点。

在Sphinx成功运行 MessageCatalogBuilder 您将找到一系列 .pot 您的输出目录中的文件。这些是 catalog templates 并包含以您的原始语言编写的邮件 only 。

它们可以被传递给翻译人员，从而将它们转换为 .po 文件-所谓的 message catalogs -包含从原始消息到外语字符串的映射。

gettext 将它们编译成称为 binary catalogs 穿过 msgfmt 出于效率的原因。如果使用以下命令使这些文件可供查找 locale_dirs 为了你的 language ，Sphinx会自动取走它们。

一个例子：您有一个文档 usage.rst 在您的狮身星项目中。 的 gettext builder会把它的消息放到 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 。

  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 目录.如果您想自定义输出，超出通过 国际化的选择 ， default pot file template 可以被定制取代 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是多行文本，并包含reStrufredText语法：

    # 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符号。大多数编辑都会帮助您做到这一点。

  6. 生成已翻译的文档。

    你需要一个 language 参数 conf.py 也可以在命令行中指定参数。

    对于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: 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

在团队翻译中使用TRANSPEX服务

Transifex 是允许通过网络界面进行协作翻译的几种服务之一。 它有一个漂亮的基于Go的命令行客户端，可以轻松获取和推送翻译。

  1. 安装 Transifex CLI tool .

    你需要 tx 用于上传资源（pot文件）的命令行工具。官方安装过程将 tx 当前目录中的二进制文件以及REAUTE和LICENSE文件，并将当前目录添加到 $PATH .

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

    参见

    Transifex Client documentation

  2. 创建您 Transifex 帐户并为您的文档创建新项目和组织。

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

    例如：

    组织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 token 页面并生成令牌。立即复制生成的令牌，因为您稍后将无法再次看到它。

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

    [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文件上载到Tamerfex服务。

    注册锅文件以 .tx/config 文件使用 sphinx-intl update-txconfig-resources 、调整 --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 documentation _

    并上传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. 将翻译转发到Tamerfex上。

  9. 拉取翻译后的PO文件，制作翻译后的超文本标记语言。

    获取翻译后的目录并构建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 (for BSD/GNU make）传递语言代码：

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

就这样!

小技巧

在本地和在TRANSPEX上翻译

如果您想推送所有语言的po文件，可以使用 tx push -t 指挥部。小心!此操作将覆盖Transffex中的转换。

换句话说，如果您已经更新了服务和本地po文件中的每一个，那么集成它们将需要花费大量的时间和精力。

使用Weblate服务进行团队翻译

阅读更多信息 Weblate's documentation 。

对Sphinx参考翻译的贡献

建议新投稿人翻译Sphinx参考资料的方式是加入Transformfex上的翻译团队。

有一个 sphinx translation page 用于Sphinx(主)文档。

  1. 登录到 Transifex 服务。

  2. 去 sphinx translation page 。

  3. 单击 Request language 并填写表格。

  4. 等待TamerfexSphinx翻译维护人员的接受。

  5. (在接受后)在传递轴上平移。

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

翻译进度和统计

Added in version 7.1.0.

在呈现过程中，Sphinx使用 translated 属性，指示是否为该节点中的文本找到了翻译。

这个 translation_progress_classes 配置值可用于向每个元素添加一个类，具体取决于 translated 属性。

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

脚注