使用 Sphinx 翻譯文檔

Sphinx 是創建優美文檔的工具。它使用了簡單的 reStructuredText 語法,並以多種格式輸出。如果要找個示例,那麼本文檔也是用它來構建的。使用 Sphinx 的非常有用的伴侶是 Read the Docs 服務,它會免費構建並出版您的文檔。

我不會聚焦在撰寫文檔本身,如果您需要指導的話,只需要按照 Sphinx 網站上的指示即可。一旦準備好文檔,將其翻譯是非常容易地,因為 Sphinx 帶有對此的支持,並且在其 Internationalization 中覆蓋得很好。這只不過是一些配置指令並調用 sphinx-intl 工具的事。

如果使用 Read the Docs 服務,那麼可以在 Read the Docs 上開始構建翻譯的文檔。它們的 Localization of Documentation 幾乎覆蓋了您需要的每一件事——創建另一個項目,設置其語言以及從主項目上鍊接它作為翻譯。

Now all you need is translating the documentation content. Sphinx generates PO file for each directory or top level file, what 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 file

翻譯旗標

rst-text

Component discovery configuration

用來比對出翻譯檔的正則表達式

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"

使用這種方法可以發現正在翻譯的幾個文檔項目: