支援文件翻譯#
我們支援並鼓勵將 Jupyter 文件翻譯成其他語言，以此作為使我們的社群更具包容性和多樣性的一種方式。我們正在努力建立一個基於 Python 和 Django 社群先前工作，在 Jupyter 專案中翻譯 Sphinx 文件的一致模型。本專案 (https://docs.jupyter.tw) 和 Jupyter Docker Stacks 專案是早期採用者，旨在驗證本頁描述的工作流程。
概述#
專案初始設定後，Sphinx 文件及其翻譯的更改遵循持續整合 (CI) 和持續部署 (CD)，與專案原始碼類似。
誰參與文件翻譯#
歡迎任何人透過參與下面描述的工作流程來編寫和翻譯 Jupyter 文件。此工作流程涉及一些參與者和元件
修改英文專案文件的人員
將英文文件中的文字片段翻譯成另一種語言（區域設定）的人員
用於源文件語言（例如，美國英語，
en-US）和其他區域設定（例如，巴西葡萄牙語，pt-BR；摩洛哥阿拉伯語，ar-MA）的可移植物件檔案 (.po)持續整合系統，如 TravisCI、CircleCI 或 GitHub Actions，負責
ReadTheDocs，我們首選的文件構建和託管服務
Transifex，一個為開源專案提供免費計劃的本地化平臺，具有友好的 Web 介面，並支援
.po檔案
翻譯過程#
使用者建立或編輯用美國英語編寫的 reStructuredText (
.rst) 或 Markdown (.md) 文件。使用者在 GitHub 上提交拉取請求。
專案維護者審閱併合並拉取請求。
ReadTheDocs 執行 Sphinx 將美國英語源文件轉換為 HTML（例如，https://docs.jupyter.tw/en/latest/architecture/how_jupyter_ipython_work.html）
同時，CI 服務執行 Sphinx 命令，從美國英語文件中提取可翻譯的*訊息*到
en-US可移植物件 (.po) 檔案中。例如
# 5164fcd91a8a4700ac734562245773ad
#: ../../source/architecture/how_jupyter_ipython_work.rst:13
#: f68a21b0bc884dad9021c276e6490e6d
msgid ""
"The IPython kernel that provides computation and communication with the "
"frontend interfaces, like the notebook"
msgstr ""
CI 服務將英文
.po檔案提交到 GitHub 上的專案。（例如，https://github.com/jupyter/jupyter/commit/1330bc409842d8b8a7bbb3a1c63259c34a543be0）Transifex 使英文
.po檔案中的訊息可用於所有配置語言的翻譯。隨著時間的推移，翻譯團隊使用 Transifex Web 應用程式建立、審閱和更新這些語言的翻譯（例如，https://docs.transifex.com/translation/translating-with-the-web-editor）
當所有英文訊息都被翻譯（並且可選地經過審閱）為給定語言時，Transifex 會向 GitHub 專案提交一個包含本地化
.po檔案的拉取請求（例如，https://github.com/jupyter/jupyter/pull/485）。例如
# 5164fcd91a8a4700ac734562245773ad
#: ../../source/architecture/how_jupyter_ipython_work.rst:13
msgid ""
"The IPython kernel that provides computation and communication with the "
"frontend interfaces, like the notebook"
msgstr ""
"The IPython kernel que fornece o cálculo e a comunicação com as interfaces "
"de frontend como o notebook"
專案維護者審閱併合並拉取請求。
ReadTheDocs 再次執行 Sphinx 將美國英語源文件轉換為 HTML。
ReadTheDocs 還執行 Sphinx 載入本地化的
.po檔案，將翻譯替換到原始英文文字中，並將這些翻譯的文件轉換為 HTML（例如，https://docs.jupyter.tw/pt_BR/latest/architecture/how_jupyter_ipython_work.html）
注意：我們認識到此流程假設文件最初是用美國英語編寫的。如果這成為新貢獻的重大障礙，我們將來應考慮消除此假設。
社群翻譯人員工作流程#
當 Jupyter 社群的成員想要幫助翻譯文件時，我們感到很高興。我們使用 Transifex 以友好的 Web 介面來培訓翻譯人員，而無需他們瞭解 git、GitHub、Sphinx 或其他軟體開發人員工具。
建立翻譯#
作為翻譯員入門 是一個針對 Transifex 新使用者的優秀入門指南。按照說明建立賬戶。當提示加入團隊時，查詢 *jupyter-meta-documentation* 開始為本文件站點貢獻翻譯。或者，在建立賬戶後訪問 https://www.transifex.com/project-jupyter/jupyter-meta-documentation/ 並請求加入專案。專案維護者或語言團隊協調員將審閱並批准您的請求。
審閱翻譯#
Transifex 支援審閱翻譯，即由語言團隊成員進行的同行審閱，以確保翻譯質量。專案維護者可以選擇 Transifex 是在文件中所有文字的翻譯可用時立即傳送拉取請求，還是延遲提交拉取請求，直到所有這些翻譯也經過審閱後（此專案的當前設定）。
協調翻譯團隊#
專案維護者還可以授予 Transifex 團隊成員 語言協調員 角色。語言協調員有權邀請使用者加入語言團隊、批准或拒絕加入請求、分配語言團隊角色，併為特定專案語言執行其他管理操作。授權社群中值得信賴的成員作為協調員可以幫助壯大翻譯團隊，而無需軟體開發人員的參與。
管理員工作流程#
上述翻譯 CI/CD 工作流程需要在 GitHub 和 Transifex 中進行配置才能正常執行。專案維護者可以按照以下說明為其 Sphinx 文件啟用翻譯。
建立 Transifex 組織#
Transifex 將翻譯專案組織在與其在 GitHub 上的組織和倉庫對應的組織下。目前，只有 https://github.com/jupyter 組織在 Transifex 上有一個對應的組織 (https://www.transifex.com/project-jupyter/public/)，具有以下組織管理員
@choldgraf
@parente
@willingc
具有在 GitHub 組織中安裝應用程式許可權的 GitHub 使用者可以按照這些說明建立新的 Transifex-GitHub 組織連結（例如，對於 https://github.com/jupyterhub，https://github.com/jupyterlab）。
在 https://transifex.com 建立一個新使用者賬戶。
完成註冊嚮導。
建立並命名一個新組織。
點選 Transifex 儀表板頁面右上角的組織下拉選單，選擇 組織設定。
點選左側邊欄中的 詳細資訊。
點選 管理 部分中的 邀請管理員，以向 Transifex 組織新增更多管理員。
點選左側邊欄中的 管理整合。
點選 GitHub 部分中的 安裝 Transifex 應用程式。
選擇要與新 Transifex 組織關聯的 GitHub 組織。
選擇 Transifex 有權訪問的儲存庫。
返回您點選 安裝 Transifex 應用程式 的選項卡，然後點選 GitHub 部分中的 授權 Transifex。
在彈出對話方塊中選擇您剛剛配置的 GitHub 組織。
請注意，您可以隨時透過訪問 https://github.com/settings/installations 來修改 GitHub-Transifex 整合。
建立 Transifex 專案#
Transifex 組織管理員可以按照以下說明為 GitHub 組織中與 Transifex 上的專案對應的 GitHub 專案配置新的翻譯專案。
訪問 https://www.transifex.com。
使用組織相應的管理員使用者賬戶登入。
點選 Transifex 儀表板頁面右上角的組織下拉選單，選擇 組織設定。
點選左下側邊欄中的 建立新專案。
根據 GitHub 上的專案命名翻譯專案。
選擇 公開 作為隱私型別，表明專案是開源的，並提供倉庫的 GitHub URL。
選擇基於檔案的專案。
為專案建立一個新團隊。
選擇 英語 (en) 作為源語言。
選擇已知目標語言。（您也可以稍後新增這些語言。）
點選 建立專案。
點選左側邊欄專案名稱下的 設定。
點選 維護者 選項卡。
邀請其他專案維護者，通常是負責維護持續整合和引導語言團隊的軟體開發人員。
配置語言和團隊#
Transifex 組織管理員和專案經理可以向專案新增翻譯語言。
訪問 https://www.transifex.com。
使用組織相應的管理員使用者賬戶登入。
點選左側邊欄專案名稱下的 語言。
點選 編輯語言。
新增或刪除目標翻譯語言。
點選 應用。
組織管理員、專案維護者和團隊經理可以向翻譯團隊新增使用者，並賦予語言協調員、審閱者或翻譯員的角色。
點選頂部導航欄中的 團隊。
點選右上角的 邀請協作者 按鈕。
輸入要新增到專案的人員的使用者名稱、電子郵件地址或全名。請注意，此欄位中的自動完成功能並不總是顯示您希望邀請的使用者的彈出視窗。確認您輸入了正確的值，然後繼續。
選擇要分配給使用者的角色。
如果角色適用於特定團隊，請選擇團隊。
如果角色適用於特定語言，請選擇語言。
點選 邀請更多 以輸入其他使用者或 傳送邀請。
配置 Transifex-GitHub 整合#
在 Transifex 上配置組織和專案資源後，專案開發人員可以
配置 Sphinx 以生成源語言的
.po檔案並讀取包含翻譯的.po檔案配置 Transifex 監視源語言
.po檔案的更改配置專案 CI 服務，以便在貢獻者更改源文件時更新源語言
.po檔案
本節中的說明假定 git 倉庫已包含以下目錄結構中的 Sphinx 文件
my-project/
docs/
build/ # built sphinx artifacts go here
source/ # documentation source is in here
conf.py # sphinx config file
index.rst # root of the documentation
requirements.txt # sphinx, sphinx-intl, etc.
專案開發人員可以執行以下操作，配置 Sphinx 以種子源 .po 檔案並識別翻譯 .po 檔案。
如果您的 Sphinx 專案
requirements.txt或environment.yaml中尚不存在，請新增sphinx-intl。在
docs/目錄中執行sphinx-intl create-txconfig。將以下內容新增到 Sphinx
source/conf.py檔案中。
# -- Translation -------------------------------------------------------------
gettext_uuid = True
locale_dirs = ["locale/"]
執行
make gettext以從英文源文件中提取所有字串。執行
sphinx-intl update -l en以生成英文源.po檔案。提交、審閱併合幷包含更改和生成的
.po檔案的拉取請求。
合併拉取請求後，將 Transifex 專案連結到 GitHub 儲存庫。
訪問 https://www.transifex.com。
點選左側邊欄專案名稱下的 設定。
點選 整合 選項卡。
點選 GitHub 部分中的 連結儲存庫。
選擇相應的 GitHub 儲存庫和整合分支。然後點選 下一步。
將以下配置複製並貼上到對話方塊中，根據需要調整註釋值，然後點選 下一步。
filters:
- filter_type: dir
file_format: PO
source_file_extension: po
# Change this if you selected a different source language during project setup
source_language: en
# The path in the GitHub repository where the source .po files reside
source_file_dir: "docs/source/locale/en/LC_MESSAGES"
# The path in the GitHub repository where translation .po files reside
translation_files_expression: "docs/source/locale/<lang>/LC_MESSAGES"
選擇 Transifex 何時將翻譯提交回儲存庫。然後點選 儲存並同步。
點選 關閉。
觀察同步狀態進度。
點選左側邊欄中的 資源。
點選其中一個
.po檔案，檢視按語言劃分的翻譯進度。點選其中一種語言以檢視翻譯進度的詳細資訊、翻譯文字和審閱翻譯。有關詳細資訊，請參閱上面的社群翻譯工作流程部分。
在確認最初的英文 .po 檔案已送達 Transifex 後，設定持續整合以確保每當英文文件更改時，Transifex 中的源字串都會保持最新。實現此目的的步驟因 CI 提供商而異。以下描述了使用 GitHub Actions 時應如何操作。
在專案中建立一個新的 GitHub actions 工作流程檔案
.github/workflows/gettext.yml。將以下內容新增到檔案中。請注意，
secrets.GITHUB_TOKEN是一個內建秘密，您無需提前配置。
name: Extract Translatable Strings
# Run on all branch pushes
on:
push:
paths:
- "docs/source/**"
- "!docs/source/locale/**"
- ".github/workflows/gettext.yml"
jobs:
gettext:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@master
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: "3.x"
- name: Install dependencies
working-directory: docs
run: pip install -r requirements.txt
- name: Extract source strings
working-directory: docs
run: |
make gettext
sphinx-intl update -l en
- name: Push to master
# Only commit changes to master if master just changed
if: github.ref == 'refs/heads/master'
uses: mikeal/publish-to-github-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
提交、審閱併合幷包含工作流程 YAML 的拉取請求。
完成本節中的步驟後，主分支上源英文文件的任何更改都將被拉入 Transifex 進行翻譯。同樣，Transifex 上完成的任何翻譯都將作為拉取請求提交回 GitHub 上的專案。
在 ReadTheDocs 上託管翻譯#
ReadTheDocs 支援從單個 GitHub 專案及其翻譯構建 HTML 文件站點。ReadTheDocs 上源語言文件專案的管理員可以按照這些說明啟用其他語言的構建。
訪問 https://readthedocs.org/dashboard/
記下包含源語言的現有 ReadTheDocs 專案名稱（例如，
jupyter）。點選
匯入專案。點選
手動匯入。輸入您上面記下的專案名稱，並附加目標語言區域設定（例如，
jupyter-es，jupyter-pt-br）。輸入專案的 GitHub URL。
勾選 編輯高階專案選項。
點選 下一步。
從 語言 下拉選單中選擇目標語言名稱（例如，
es-> 西班牙語，es-mx-> 墨西哥西班牙語，pt-br-> 巴西葡萄牙語）。點選
完成。返回 https://readthedocs.org/dashboard/ 的專案列表
點選包含源語言的專案。
點選 管理。
點選 翻譯。
從 專案 下拉選單中選擇在步驟 5 中建立的翻譯專案名稱。
點選 新增。
對專案支援的所有其他語言重複這些步驟。
現在，每當您合併來自 Transifex 的包含 .po 翻譯檔案更新的拉取請求時，ReadTheDocs 將構建源文件站點以及所有支援語言的站點。ReadTheDocs 將這些站點相互關聯，並透過彈出視窗中的語言連結使其可訪問。
參考#
https://github.com/parente/helloworld-transifex-rtd 是一個配置為支援本文件中描述的整個工作流程的迷你專案。