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