使用 Sphinx 翻译文档

Sphinx 是创建优美文档的工具。它使用了简单的 reStructuredText 语法,并以多种格式输出。如果要找个示例,那么本文档也是用它来构建的。使用 Sphinx 的非常有用的伴侣是 Read the Docs 服务,它会免费构建并出版您的文档。

我不会把重心放在撰写文档本身,如果您需要指导的话,只需要按照 Sphinx 网站上的指示即可。一旦准备好文档,将其翻译是非常容易地,因为 Sphinx 带有对此的支持,并且在其 国际化 中覆盖得很好。这只不过是一些配置指令并调用 sphinx-intl 工具的事。

如果使用 Read the Docs 服务,那么可以在 Read the Docs 上开始构建翻译的文档。它们的 文档本地化 几乎覆盖了您需要的每一件事——创建另一个项目,设置其语言以及从主项目上链接它作为翻译。

现在您只需要翻译文档内容。Sphinx 会为每个目录或顶层文件生成 PO 文件,这导致需要翻译非常多的文件(取决于 gettext_compact 设置)。您可以将 index.po 导入 Weblate 作为初始部件,然后配置 部件发现 附加组件,来自动发现所有其它部件。

部件配置

部件名

文档

文件掩码

docs/locales/*/LC_MESSAGES/index.po

新翻译的译文模版

docs/locales/index.pot

文件格式

gettext PO 文件

翻译标记

rst-text

部件发现配置

用于匹配翻译文件的正则表达式

docs/locales/(?P<language>[^/.]*)/LC_MESSAGES/(?P<component>[^/]*)\.po

自定义部件名称

Documentation: {{ component|title }}

为新的翻译条目指定译文模版文件

docs/locales/{{ component }}.pot

提示

您希望 Sphinx 生成只是单一的 PO 文件吗?从 Sphinx 3.3.0 开始可以实现,使用:

gettext_compact = "docs"

你可以发现有几个文档项目就在使用这种方法进行自身的本地化翻译工作: