国际化

1.1 新版功能.

作为对 Sphinx 生成的信息（如导航条）的翻译的补充，Sphinx 提供了促进文件翻译的机制。关于配置的细节，请看 Options for internationalization。

../../_images/translation.svg

Sphinx 翻译工作流程的可视化。（该图是由 plantuml 创建的。）

Sphinx 国际化的细节

gettext 1 是国际化和本地化的一个既定标准。它自然地将程序中的信息映射到一个已经翻译的字符串。Sphinx 使用这些工具来翻译整个文档。

最初，项目维护人员必须收集所有可翻译字符串（也称为 消息）以使翻译人员知道需要翻译的信息。Sphinx 通过调用 sphinx-build -b gettext 来提取这些内容。

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

在 Sphinx 成功运行 MessageCatalogBuilder 之后，您将在输出目录中找到一组 .pot 文件。这些是 目录模板，只包含您的原始语言的消息。

它们可以被传递给翻译程序，并将其转换成 .po 文件，即所谓的 消息目录，其中包含从原始消息到外语字符串的映射。

为了提高效率，gettext 将它们编译成一种被称为 二进制目录 的二进制格式 msgfmt。如果您使用 locale_dirs 为您的 language 设置这些文件的可发现性，Sphinx 将自动提取它们。

一个例子：在你的 Sphinx 项目中，你有一个文件 usage.rst。gettext 构建器将把它的信息放到 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 设置）。

  • 运行你想要的构建。

使用 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 目录中。

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

    请注意不要破坏 reST 的记号。大多数 po-editors 会帮助你。

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

    > Set-Item env:SPHINXOPTS "-D language=de"
> .\make.bat html

祝贺你！你在 _build/html 目录下得到了翻译好的文档。

1.3 新版功能: sphinx-build 由 make 命令调用，将构建 po 文件变成 mo 文件。

如果你使用 1.2.x 或更早的版本，请在 sphinx-intl build 命令之前调用 make 命令。

翻译中

通过新的 pot 文件更新你的 po 文件

如果一个文件被更新，有必要生成更新的 pot 文件，并将差异应用于翻译的 po 文件。为了将 pot 文件的更新，请使用 sphinx-intl update 命令。

$ sphinx-intl update -p _build/gettext

使用 Transifex 服务进行团队翻译

Transifex 是几个允许通过网络界面进行协作翻译的服务之一。它有一个灵巧的基于 Python 的命令行客户端，使它很容易获取和推送译文。

  1. 安装 transifex-client。

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

    $ pip install transifex-client

    参见

    Transifex 客户端文档

  2. 创建你的 transifex 账户并为你的文件创建新的项目。

    目前，transifex 不允许一个翻译项目有多个版本，所以你最好在你的项目名称中包括一个版本号。

    例如：

    项目 ID

    sphinx-document-test_1_0

    项目 URL

    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 文件上传到 transifex 服务。

    在 .tx/config 文件中注册 pot 文件：

    $ 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. 转发 transifex 上的译文。

  6. 拉取翻译好的 po 文件，并制作翻译好的 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）：

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

这就是全部！

小技巧

在本地和 Transifex 上进行翻译。

如果你想推送所有语言的 po 文件，你可以通过使用 tx push -t 命令来完成。注意! 这个操作会覆盖 transifex 中的翻译。

换句话说，如果你在服务和本地 po 中分别更新了文件，就会花费很多时间和精力来整合它们。

为 Sphinx 参考翻译做贡献

建议新的贡献者翻译 Sphinx 参考资料的方式是加入 Transifex 的翻译团队。

有一个 Sphinx 翻译页面，用于翻译 Sphinx（master）文档。

  1. 登录 transifex 服务。

  2. 转到 Sphinx 翻译页面

  3. 点击 Request language 并填写表单

  4. 等待 transifex sphinx 翻译维护者的验收。

  5. (接受后）在 transifex 上翻译。

细节见：https://docs.transifex.com/getting-started-1/translators

脚注

1

见 GNU gettext 实用工具 了解该软件套件的详情。

2

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