用 gettext 与 sphinx-intl 维护多语言文档-未完纪

来源： Internationalization — Sphinx documentation
作者： 原文未注明个人作者；来源记录标注为 Sphinx 官方文档
版本信息： 当前 master 文档；相关能力分别标注于 Sphinx 1.1、1.3 和 4.5 起
范围： 介绍本地 gettext 与 sphinx-intl 的提取、翻译、更新和构建流程，不包括 Transifex、Weblate 等远程翻译服务

Sphinx 除了翻译导航栏等由 Sphinx 生成的界面消息，也支持将文档内容本身交给 gettext 工作流翻译。基本过程是：从文档树提取原文消息，生成 .pot 模板；为目标语言生成并维护 .po 目录；完成翻译后让构建过程加载相应的 .mo 文件，输出目标语言 HTML。

消息粒度与维护原则

Sphinx 会把文档树中的每个元素提取为一个消息。列表中的各项会拆成不同消息，但较大的段落仍以原文的段落粒度保留，不会自动拆成更小的翻译片段。维护者需要把过长、难以翻译的段落拆分成合适的小段。

生成的 .pot 文件只包含原文字符串；译者将消息填入 .po 文件，形成从原文到目标语言文本的映射。gettext 可以把翻译目录编译成二进制 .mo 文件供构建加载。译文应保留 reStructuredText 标记，例如交叉引用语法，避免翻译后引用结构损坏。

1. 安装并配置项目

在 Sphinx 项目环境安装 sphinx-intl：

pip install sphinx-intl

在 conf.py 中配置翻译目录；示例还关闭 gettext_compact，使模板目录按文档组织：

locale_dirs = ['locale/']
gettext_compact = False

locale_dirs 的路径相对于 Sphinx 源目录。本文后续示例假设构建目录 BUILDDIR 为 _build、翻译目录为 locale/，并且 gettext_compact 为 False。

2. 提取原文模板

在 Sphinx 项目目录运行：

make gettext

提取出的 .pot 文件写入 _build/gettext。每个文件包含待翻译的原文消息，作为后续生成语言目录的输入。

3. 为目标语言生成 PO 文件

把刚生成的模板交给 sphinx-intl，例如生成德语和日语目录：

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

命令会在以下目录生成或更新 .po 文件：

locale/de/LC_MESSAGES/
locale/ja/LC_MESSAGES/

在 PO 文件中，msgid 是原文，msgstr 是目标语言。例如：

#: ../../builders.rst:4
msgid "Available builders"
msgstr "译文写在这里"

实际翻译时，应根据目标语言填写 msgstr。若原文是多行 reStructuredText 内容，msgstr 也可能由多行字符串组成。保留像 :ref: extensions 这样的引用标记；Sphinx 会在译文中的交叉引用与原文不匹配时给出警告。

如果确实需要对某条消息单独屏蔽这种警告，可在该消息末尾添加 #noqa。#noqa 机制从 Sphinx 4.5 起提供。要在译文里显示字面量 #noqa，需要写成 #noqa。也可以通过 suppress_warnings 配置全局抑制警告，但应先确认引用问题已妥善处理，避免掩盖真正的失配。

4. 选择目标语言构建 HTML

构建时需要让 Sphinx 知道目标语言。可以在 conf.py 的 language 配置中指定，也可以在命令行传入覆盖值。原文给出以下操作方式。

在 BSD/GNU make 中，传入德语语言参数：

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

在 Windows 命令提示符中：

set SPHINXOPTS=-D language=de
.\make.bat html

在 PowerShell 中：

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

完成后，译文 HTML 会写入 _build/html。Windows 和 Unix-like 系统的 make 启动方式不同，应按实际终端选用相应命令。

5. 手动编译 MO 文件的兼容说明

若要手动编译 gettext 目录，可将 PO 文件编译到匹配 locale_dirs、language 和文档路径的 MO 目标位置。例如，西班牙语的 usage.rst 可对应：

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

随后将 locale_dirs 设为 [“locale/”]，并将 language 设为 es，再运行所需构建。此例中的 es 是西班牙语代码；换成其他语言时，目录名和 language 值要相应改变。

版本行为需要区分：从 Sphinx 1.3 起，通过 make 调用的 sphinx-build 会把 PO 文件构建成 MO 文件；若使用 Sphinx 1.2.x 或更早版本，需先运行 sphinx-intl build，再执行 make。

6. 源文档更新后合并翻译

源文档更新后，先重新提取 POT，再把新模板的差异合并到已有 PO：

make gettext
sphinx-intl update -p _build/gettext

这样可以更新消息目录，同时保留已有翻译。应持续检查新增、变更和待翻译消息，再重新构建目标语言文档。

维护检查点

按翻译需要控制段落粒度；过长的段落不会由 Sphinx 自动拆解。
翻译时保留 reStructuredText 标记，尤其是交叉引用；看到引用警告时先检查标记是否一致。
每次原文变更后先更新 POT，再更新现有 PO，避免丢失已有译文。
确认 locale_dirs、目标语言代码和 MO 目标路径彼此对应。
核对使用的 Sphinx 版本：1.3 起的构建行为与 1.2.x 及更早版本不同。

来源信息

原文标题： Internationalization
来源： Sphinx 官方文档
作者： 原文未注明个人作者

文章版权归作者所有，未经允许请勿转载。

THE END

技术译文

用 gettext 与 sphinx-intl 维护多语言文档