使用 Sphinx 翻译文档¶
Sphinx 是创建优美文档的工具。它使用了简单的 reStructuredText 语法,并以多种格式输出。如果要找个示例,那么本文档也是用它来构建的。使用 Sphinx 的非常有用的伴侣是 Read the Docs 服务,它会免费构建并出版您的文档。
我不会聚焦在撰写文档本身,如果您需要指导的话,只需要按照 Sphinx 网站上的指示即可。一旦准备好文档,将其翻译是非常容易地,因为 Sphinx 带有对此的支持,并且在其 Internationalization 中覆盖得很好。这只不过是一些配置指令并调用 sphinx-intl
工具的事。
如果使用 Read the Docs 服务,那么可以在 Read the Docs 上开始构建翻译的文档。它们的 Localization of Documentation 几乎覆盖了您需要的每一件事——创建另一个项目,设置其语言以及从主项目上链接它作为翻译。
现在所有需要的是翻译文档内容。Sphinx 为每个目录或顶层文件生成 PO 文件,这导致需要翻译非常多的文件(依赖于 gettext_compact
设置)。可以将 index.po
导入 Weblate 作为初始组件,然后配置 组件发现 插件,来自动发现所有其它的。
|
|
|
|
|
|
gettext PO 文件 |
|
|
用于匹配翻译文件的正则表达式 |
|
自定义组件名称 |
|
为新的翻译条目指定译文模版文件 |
|
提示
您希望 Sphinx 生成只是单一的 PO 文件吗?从 Sphinx 3.3.0 开始可以实现,使用:
gettext_compact = "docs"
使用这种方法可以发现正在翻译的几个文档项目: