國際化

版本 1.1 新增。

除了為 Sphinx 產生的訊息（例如導覽列）提供的翻譯之外，Sphinx 還提供機制來協助翻譯文件。有關設定的詳細資訊，請參閱國際化選項。

../../_images/translation.svg

Sphinx 翻譯工作流程視覺化。（該圖由 plantuml 建立。）

Sphinx 國際化詳細資訊

gettext [1] 是國際化和本地化的既定標準。它將程式中的訊息簡單地對應到翻譯後的字串。Sphinx 使用這些工具來翻譯整個文件。

最初，專案維護者必須收集所有可翻譯的字串（也稱為訊息），以便讓翻譯人員知道。Sphinx 透過呼叫 sphinx-build -M gettext 來提取這些字串。

doctree 中的每個單一元素都將最終成為單一訊息，這導致列表被同樣地分割成不同的區塊，而大段落將保持與原始文件中一樣粗略的粒度。這在提供自由文本段落中翻譯人員少許上下文的同時，也保證了文件的無縫更新。將過大的段落分割開是維護者的任務，因為沒有合理的自動化方法可以做到這一點。

在 Sphinx 成功執行 MessageCatalogBuilder 之後，您將在輸出目錄中找到 .pot 檔案的集合。這些是目錄範本，僅包含您的原始語言的訊息。

它們可以交付給翻譯人員，翻譯人員會將它們轉換為 .po 檔案——稱為訊息目錄——其中包含從原始訊息到外語字串的映射。

gettext 基於效率考量，透過 msgfmt 將它們編譯成稱為 二進制目錄 的二進制格式。如果您使用 locale_dirs 為您的 language 使這些檔案可被發現，Sphinx 將自動選取它們。

一個範例：您的 Sphinx 專案中有名為 usage.rst 的文件。gettext 建構器將其訊息放入 usage.pot。假設您有西班牙語翻譯 [2] 儲存在 usage.po 中——為了讓您的建構版本被翻譯，您需要遵循以下指示

  • 將您的訊息目錄編譯到語言環境目錄，例如 locale，使其最終位於來源目錄的 ./locale/es/LC_MESSAGES/usage.mo 中（其中 es 是西班牙語的語言代碼。）

    msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"

  • 將 locale_dirs 設定為 ["locale/"]。

  • 將 language 設定為 es（也可以透過 -D）。

  • 執行您想要的建構。

為了防止錯誤，如果翻譯段落中的交叉參照與原始段落中的交叉參照不符，則會發出警告。可以使用 suppress_warnings 設定變數全域關閉此功能。或者，若要僅針對一則訊息關閉它，請在訊息末尾加上 #noqa，如下所示

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
risus tortor, luctus id ultrices at. #noqa

（如果您想在文本中逐字顯示“#noqa”，請寫入 \#noqa。這不適用於程式碼區塊，因為程式碼區塊中不包含任何參照，因此會忽略 #noqa。）

版本 4.5 新增: #noqa 機制。

使用 sphinx-intl 翻譯

快速指南

sphinx-intl 是一個用於處理 Sphinx 翻譯流程的實用工具。本節介紹使用 sphinx-intl 進行翻譯的簡單方法。

  1. 安裝 sphinx-intl。

    $ pip install sphinx-intl

  2. 將設定新增到 conf.py。

    locale_dirs = ['locale/']   # path is example but recommended.
gettext_compact = False     # optional.

    本案例研究假設 BUILDDIR 設定為 _build，locale_dirs 設定為 locale/，且 gettext_compact 設定為 False（Sphinx 文件已如此設定）。

  3. 將可翻譯訊息提取到 pot 檔案中。

    $ make gettext

    產生的 pot 檔案將放置在 _build/gettext 目錄中。如果您想自訂超出 國際化選項 所能完成的輸出，則可以使用自訂的 message.pot.jinja 檔案取代 預設 pot 檔案範本，該檔案放置在 templates_path 中列出的任何目錄中。

  4. 產生 po 檔案。

    我們將使用在上一步中產生的 pot 檔案。

    $ sphinx-intl update -p _build/gettext -l de -l ja

    完成後，產生的 po 檔案將放置在以下目錄中

    • ./locale/de/LC_MESSAGES/

    • ./locale/ja/LC_MESSAGES/

  5. 翻譯 po 檔案。

    如上所述，這些檔案位於 ./locale/<lang>/LC_MESSAGES 目錄中。以下給出一個來自 Sphinx 的此類檔案的範例，builders.po。

    # a5600c3d2e3d48fc8c261ea0284db79b
#: ../../builders.rst:4
msgid "Available builders"
msgstr "<FILL HERE BY TARGET LANGUAGE>"

    另一個案例，msgid 是多行文字，並且包含 reStructuredText 語法

    # 302558364e1d41c69b3277277e34b184
#: ../../builders.rst:9
msgid ""
"These are the built-in Sphinx builders. More builders can be added by "
":ref:`extensions <extensions>`."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."

    請小心不要破壞 reStructuredText 標記法。大多數 po 編輯器都會在這方面幫助您。

  6. 建構翻譯後的文件。

    您需要在 conf.py 中設定 language 參數，或者您也可以在命令列中指定該參數。

    對於 BSD/GNU make，執行

    $ make -e SPHINXOPTS="-D language='de'" html

    對於 Windows cmd.exe，執行

    > set SPHINXOPTS=-D language=de
> .\make.bat html

    對於 PowerShell，執行

    PS> Set-Item env:SPHINXOPTS "-D language=de"
PS> .\make.bat html

恭喜！您已在 _build/html 目錄中取得翻譯後的文件。

版本 1.3 新增: make 命令調用的 sphinx-build 將會把 po 檔案建構成 mo 檔案。

如果您使用的是 1.2.x 或更早版本，請在 make 命令之前調用 sphinx-intl build 命令。

翻譯

使用新的 pot 檔案更新您的 po 檔案

如果文件已更新，則有必要產生更新的 pot 檔案，並將差異應用於翻譯後的 po 檔案。為了將 pot 檔案的更新應用於 po 檔案，請使用 sphinx-intl update 命令。

$ sphinx-intl update -p _build/gettext

使用 Transifex 服務進行團隊翻譯

Transifex 是幾個允許透過網頁介面進行協作翻譯的服務之一。它有一個基於 Go 的漂亮命令列客戶端，可以輕鬆地提取和推送翻譯。

  1. 安裝 Transifex CLI 工具。

    您需要 tx 命令列工具來上傳資源（pot 檔案）。官方安裝程序將 tx 二進制檔案放置在當前目錄中，以及 README 和 LICENSE 檔案，並將當前目錄新增到 $PATH。

    $ curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

    另請參閱

    Transifex Client 文件

  2. 建立您的 Transifex 帳戶，並為您的文件建立新的專案和組織。

    目前，Transifex 不允許翻譯專案有多個文件版本，因此您最好在專案名稱中包含版本號。

    例如

    組織 ID:

    sphinx-document

    專案 ID:

    sphinx-document-test_1_0

    專案 URL:

    https://www.transifex.com/projects/p/sphinx-document-test_1_0/

  3. 建立要在命令列中使用的 API 令牌。

    前往您的 Transifex API 令牌 頁面並產生令牌。立即複製產生的令牌，因為您之後將無法再次看到它。

  4. 在使用者設定檔 $HOME/.transifexrc 中設定您的 Transifex API 令牌。

    [https://app.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = paste_your_api_token_here

  5. 或者，您可以將您的 Transifex API 令牌儲存為環境變數 TX_TOKEN，tx 會識別並使用它。

    $ export TX_TOKEN=paste_your_api_token_here

  6. 為 tx 命令建立專案的設定檔。

    此過程將在目前目錄中建立 .tx/config。

    $ cd /your/document/root
$ tx init

Successful creation of '.tx/config' file

  7. 將 pot 檔案上傳到 Transifex 服務。

    使用 sphinx-intl update-txconfig-resources 將 pot 檔案註冊到 .tx/config 檔案，調整 --pot-dir 值以符合您專案的 pot 檔案目錄

    $ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
  --transifex-organization-name=sphinx-document \
  --transifex-project-name=sphinx-document-test_1_0

    您可以使用 SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME 和 SPHINXINTL_TRANSIFEX_PROJECT_NAME 環境變數，而不是各自的命令列引數。

    另請參閱

    sphinx-intl update-txconfig-resources 文件

    並上傳 pot 檔案

    $ tx push -s
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pushing source files

sphinx-document-test_1_0.builders - Uploading file
sphinx-document-test_1_0.builders - Done

  8. 在 Transifex 上轉發翻譯。

  9. 提取翻譯後的 po 檔案並製作翻譯後的 HTML。

    取得翻譯後的目錄並建構 mo 檔案。例如，要為德語 (de) 建構 mo 檔案

    $ cd /your/document/root
$ tx pull -l de
# Getting info about resources

sphinx-document-test_1_0.builders - Getting info
sphinx-document-test_1_0.builders - Done

# Pulling files

sphinx-document-test_1_0.builders [de] - Pulling file
sphinx-document-test_1_0.builders [de] - Creating download job
sphinx-document-test_1_0.builders [de] - Done

    調用 make html (對於 BSD/GNU make) 並傳遞語言代碼

    $ make -e SPHINXOPTS="-D language='de'" html

就這樣！

提示

在本機和 Transifex 上翻譯

如果您想推送所有語言的 po 檔案，可以使用 tx push -t 命令來完成。注意！此操作會覆寫 Transifex 中的翻譯。

換句話說，如果您已在服務和本機 po 檔案中各自更新，則整合它們將會花費大量時間和精力。

使用 Weblate 服務進行團隊翻譯

在 Weblate 的文件 中閱讀更多內容。

貢獻 Sphinx 參考翻譯

對於新的貢獻者來說，翻譯 Sphinx 參考文件的建議方式是加入 Transifex 上的翻譯團隊。

有一個用於 Sphinx (master) 文件的 sphinx 翻譯頁面。

  1. 登入 Transifex 服務。

  2. 前往 sphinx 翻譯頁面。

  3. 點擊 請求語言 並填寫表格。

  4. 等待 Transifex sphinx 翻譯維護者接受。

  5. （接受後）在 Transifex 上翻譯。

詳細資訊在這裡： https://help.transifex.com/en/articles/6248698-getting-started-as-a-translator

翻譯進度和統計

版本 7.1.0 新增。

在渲染過程中，Sphinx 會使用 translated 屬性標記每個可翻譯節點，指示是否為該節點中的文字找到了翻譯。

translation_progress_classes 設定值可用於為每個元素新增類別，具體取決於 translated 屬性的值。

|translation progress| 替換可以用於顯示每個文件中已翻譯節點的百分比。

腳註