国际化¶

1.1 新版功能.

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

Sphinx中翻译的工作流可视化。 (棒图来源于 XKCD漫画。)

Sphinx国际化细节
用sphinx-intl翻译
使用Transifex服务进行团队翻译
有助于Sphinx参考翻译

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 进行翻译的简便方法。

安装 sphinx-intl .
```
$ pip install sphinx-intl
```
添加配置 conf.py .
```
locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.
```
本案例研究假设 locale_dirs 设置为 locale/ 并且 gettext_compact 设置为 False (Sphinx文档已经配置为这样)。
将可翻译的消息提取到pot文件中。
```
$ make gettext
```
生成的pot文件将放在 _build/gettext 目录中。
生成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."

请注意不要破坏reST表示法。大多数编辑都会帮助你。

构建翻译文档。

你需要在 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 新版功能: 由make命令调用的 sphinx-build 会将po文件构建到mo文件中。

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

翻译 ¶

通过新的pot文件更新您的po文件 ¶

如果文档已更新，则需要生成更新的pot文件并将差异应用于已翻译的po文件。要将更新从pot文件应用到po文件，请使用 sphinx-intl update 命令。

$ sphinx-intl update -p _build/locale

使用Transifex服务进行团队翻译 ¶

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

安装 transifex-client.

你需要 tx 命令来上传资源(pot文件)。
```
$ pip install transifex-client
```
参见

Transifex Client documentation
创建 transifex 帐户并为您的文档创建新项目。

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

例如:

项目ID: sphinx-document-test_1_0

项目网址: https://www.transifex.com/projects/p/sphinx-document-test_1_0/

为 tx 命令创建配置文件.

这个过程将在当前目录中创建 .tx/config ，以及包含auth信息的 〜/.transifexrc 文件。

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

将pot文件上传到transifex服务。

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

转发transifex的翻译。

拉出翻译的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.

Invoke make html (对于BSD/GNU make):

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

就这样！

小技巧

在本地和Transifex上进行翻译

如果要推送所有语言的po文件，可以使用 tx push -t 命令完成。小心！此操作会覆盖transifex中的翻译。

换句话说，如果您更新了服务和本地po文件中的每一个，则需要花费很多时间和精力来集成它们。

有助于Sphinx参考翻译 ¶

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

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

登录 transifex 服务。
去 sphinx translation page .
点击 Request language and fill form.
等待transifex sphinx翻译维护者的接受。
(接受后)翻译transifex。

脚注

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

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

Table of Contents

上一个主题

下一个主题

本页