Sphinx中的国际化

7.4. Sphinx中的国际化#

7.4.1. Sphinx internationalization details#

gettext 是国际化和本地化的既定标准。 它将程序中的消息映射到翻译后的字符串。 Sphinx使用这些工具翻译整个文档。

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

文档树中的每个元素最终都会出现在一条消息中，这会导致列表被平均分割成不同的块，而大段落将保持与原始文档中一样粗粒度。 这允许无缝的文档更新，同时仍然为自由文本段落中的译者提供了一点上下文。 维护人员的任务是分割太大的段落，因为没有健全的自动化方法来做到这一点。

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

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

出于效率原因，Gettext通过msgfmt将它们编译成二进制格式，称为二进制目录。 如果您使用您的语言的locale_dirs使这些文件可被发现，Sphinx将自动获取它们。

一个例子：您的Sphinx项目中有一个document usage.rst 。 gettext生成器将把它的消息放入 usage.po t中。 想象一下，在 usage.po 中，你手头有西班牙语翻译[2]——要翻译你的构建，你需要遵循以下说明：

  • 将您的消息目录编译到一个区域设置目录，比如locale，这样它最终就会存储在 locale/LC_MESSAGES/usage.po

  • 设置 locale_dirs ，如 ["locale/"]

  • 设置 language 为 es ；或者通过命令中的 -D 传递参数

  • 进行构建

msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

7.4.2. Translating with sphinx-intl#

Quick guide

sphinx intl是一个使用sphinx翻译流的有用工具。 本节描述了一种使用sphinx-intl进行翻译的简单方法。

Install sphinx-intl by

pip3 install sphinx-intl

需要在项目的 conf.py 中进行设置。

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

从文本中提取要可翻译信息，结果会在 _build/locale 目录中生成 .pot 文件。

make gettext

或者使用 Sphinx 命令运行：

sphinx-build -b gettext . _build/locale

设置、更新 locale_dir ：

sphinx-intl update -p _build/locale -l de -l ja

7.4.3. 编译#

用Makefile 的情况下：

make -e SPHINXOPTS="-D language='zh'" html

不使用 make 工具：

sphinx-build -b html -D language='{}' . _build/html

7.4.4. 示例#

翻译成中文的命令：

::

sphinx-build -b gettext ./source _build/locale sphinx-intl update -p _build/locale -l zh -d source/locales make -e SPHINXOPTS="-D language='zh'" html

翻译成英文的命令：

sphinx-build -b gettext . _build/locale
sphinx-intl update -p _build/locale  -l en
make -e SPHINXOPTS="-D language='zh'" html
目录