国际化

Added in version 1.1.

作为对Sphinx生成的消息（如导航栏）提供的翻译的补充，Sphinx提供了一些机制来促进 文件 . 见 国际化的选择 有关配置的详细信息。

../../_images/translation.svg

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

Sphinx国际化细节

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

最初，项目维护人员必须收集所有可翻译的字符串(也称为 messages )以使翻译人员了解这些信息。Sphinx通过调用 sphinx-build -M gettext 。

doctree中的每一个元素都将以一条消息结束，这将导致列表被等分为不同的块，而大的段落将像原始文档中一样粗粒度。这允许无缝的文档更新，同时仍然为自由文本段落中的翻译人员提供一点上下文。由于没有健全的自动化方法，维护人员的任务是分割太大的段落。

在Sphinx成功运行后 MessageCatalogBuilder 你会发现 .pot 输出目录中的文件。这些是 目录模板 包含原始语言的邮件 only .

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

获取文本 将它们编译成一种称为 二进制目录 通过 msgfmt 出于效率考虑。如果你能发现这些文件 locale_dirs 为了你 language Sphinx会自动把它们捡起来。

例如：您有一个文档 usage.rst 在你的Sphinx项目中。这个 获取文本 建设者将把它的消息放入 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国际语翻译

快速指南

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 目录。

  4. 生成采购订单文件。

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

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

    完成后，生成的采购订单文件将放在以下目录中：

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. 翻译采购订单文件。

    如上所述，它们位于 ./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."

    请注意不要破坏 reST 符号。大多数 po文件编辑器 都会帮助处理。

  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，运行：

    > Set-Item env:SPHINXOPTS "-D language=de"
> .\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文件，并将差异应用于已翻译的采购订单文件。要将pot文件中的更新应用于po文件，请使用 sphinx-intl update 命令。

$ sphinx-intl update -p _build/gettext

使用Transifex服务进行团队翻译

Transifex 是允许通过Web界面进行协作翻译的几种服务之一。它有一个漂亮的基于python的命令行客户机，可以方便地获取和推送翻译。

  1. 安装 transifex-client .

    你需要 tx 上传资源（pot文件）的命令。

    $ pip install transifex-client

    参见

    Transifex Client documentation

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

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

    例如：

    项目标识:

    sphinx-document-test_1_0

    项目网址:

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

  3. 为创建配置文件 tx 命令。

    此过程将创建 .tx/config 在当前目录中，以及 ~/.transifexrc 包含身份验证信息的文件。

    $ tx init
Creating .tx folder...
Transifex instance [https://www.transifex.com]:
...
Please enter your transifex username: <transifex-username>
Password: <transifex-password>
...
Done.

  4. 将POT文件上载到Tamerfex服务。

    将pot文件注册到 .tx/config 文件：

    $ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
  --transifex-project-name sphinx-document-test_1_0

    上传pot文件：

    $ tx push -s
Pushing translations for resource sphinx-document-test_1_0.builders:
Pushing source file (locale/pot/builders.pot)
Resource does not exist.  Creating...
...
Done.

  5. 将翻译转发到Tamerfex上。

  6. 提取已翻译的采购订单文件并生成已翻译的HTML。

    获取已翻译的目录并生成mo文件。例如，要为德语（de）生成mo文件，请执行以下操作：

    $ cd /your/document/root
$ tx pull -l de
Pulling translations for resource sphinx-document-test_1_0.builders (...)
 -> de: locale/de/LC_MESSAGES/builders.po
...
Done.

    援引 make html （对于BSD/GNU品牌）：

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

这就是全部！

小技巧

本地和Transifex上的转换

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

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

使用Weblate服务进行团队翻译

阅读更多信息 Weblate's documentation 。

有助于Sphinx参考翻译

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

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

  1. 登录到 Transifex 服务。

  2. 去 sphinx translation page .

  3. 点击 Request language 填写表格。

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

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

详情请点击此处：https://docs.transifex.com/getting-started-1/translators

翻译进度和统计

Added in version 7.1.0.

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

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

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

脚注