使用 Sphinx 翻译文档

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

I will not focus on writing documentation itself, if you need guidance with that, just follow instructions on the Sphinx website. Once you have documentation ready, translating it is quite easy as Sphinx comes with support for this and it is quite nicely covered in their 国际化. It's matter of a few configuration directives and invoking the sphinx-intl tool.

If you are using Read the Docs service, you can start building translated documentation on Read the Docs. Their Localization and Internationalization covers pretty much everything you need - creating another project, setting its language, and linking it from the main project as a translation.

Now all you need is translating the documentation content. Sphinx generates PO file for each directory or top-level file, which can lead to quite a lot of files to translate (depending on gettext_compact settings). You can import the index.po into Weblate as an initial component and then configure 部件发现 add-on to automatically discover all others.

部件配置

部件名称	Documentation
文件掩码	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"

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

• Weblate 文档（您现在就在阅读这个文档）

• Godot 引擎文档

• Gallette 文档

• phpMyAdmin 文档