語言
主題翻譯指南。
MkDocs隨附的內建主題提供翻譯支援。這是翻譯人員的指南，記載了新增翻譯或更新現有翻譯的流程。如需修改現有主題的指導方針，請參閱貢獻指南。若要啟用特定翻譯，請參閱使用者指南，瞭解您使用之特定主題的文件。如需叫第三方主題的翻譯，請參閱這些主題的文件。第三方主題若要使用MkDocs的翻譯工具和方法，必須適當地設定這些工具，才能使用。
注意
翻譯僅適用於包含在主題範本中的文字，例如「下一頁」和「上一頁」連結。頁面的Markdown內容並未翻譯。如果您想建立多國語言文件，您需要將主題翻譯與第三方國際化/語言化外掛程式結合使用。
翻譯工具的前提條件
主題翻譯使用babel專案產生和編譯語言檔案。您需要從本地端電腦上的git工作樹執行作業，才能使用翻譯指令。
請參閱貢獻指南，了解如何安裝開發版本以及提交拉取請求。本文件中的說明假設您是在適當地設定開發環境下執行作業。
請確定翻譯需求已安裝到您的環境中
pip install 'mkdocs[i18n]'將語言翻譯新增到主題
如果您的首選語言目前尚不受內建主題（mkdocs和readthedocs）支援，您只需執行以下步驟，就能輕鬆地貢獻翻譯。
以下將簡要摘要您需要執行的步驟
- 分叉並複製MkDocs存放庫，然後安裝開發用的MkDocs，以新增和測試翻譯。
- 初始化您的新語言翻譯目錄（如果您的語言已有翻譯，請遵循更新主題翻譯檔案的說明）。
- 新增翻譯，插入每個翻譯目錄中的文字暫存器。
- 本地端提供服務並測試您的語言翻譯主題。
- 更新文件，記載每個已翻譯主題所支援的翻譯。
- 透過拉取請求貢獻您的翻譯。
注意
翻譯語言通常使用 ISO-639-1（2 個字母）語言代碼進行識別。雖然也支援地區/地域/縣別代碼，但僅在完成一般語言翻譯且地區方言需要使用與一般語言翻譯不同的術語時，才應加入特定位置的翻譯。
分岔並複製 MkDocs 存放庫
在下列步驟中，你會使用 MkDocs 存放庫的分岔。按照 分岔和複製 MkDocs 存放庫 中的說明進行操作。
若要測試翻譯，你也需要從你的分岔 安裝用於開發的 MkDocs。
初始化在地化目錄
每個佈景的主題範本包含已被擷取出為可攜式物件範本（messages.pot）檔案的文字佔位符，此檔案存在於每個佈景資料夾中。
初始化目錄包括執行一個命令，此命令會為你想要的語言建立目錄結構，並準備一個衍生自佈景 pot 檔案的可攜式物件（messages.po）檔案。
對每個佈景目錄使用 `init_catalog` 命令，並提供適當的語言代碼（-l <language>）。
語言代碼幾乎總是兩個小寫字母，例如 sv，但在某些情況下需要進一步消除歧義。
參閱
特別地，判斷語言 pt 應消除歧義為 pt_PT 和 pt_BR 的方法是，若在 語言次標籤註冊 頁面中搜尋，包含 pt- 。假設 sv 應該僅保留 sv，因為該頁面不包含 sv-。
因此，假設我們選擇 es（西班牙語）作為範例語言代碼，若要為兩個內建佈景加入翻譯，請執行下列命令
pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es
pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es上述命令會建立一個如下列所示的檔案結構
mkdocs/themes/mkdocs/locales
├── es
│ └── LC_MESSAGES
│ └── messages.po現在你可以繼續執行下一步，並為在地化目錄中的每個文字佔位符 加入翻譯。
更新佈景翻譯
假設自上次為你的語言設定更新 messages.po 之後，佈景的 messages.pot 範本檔案已 更新，請按照下列步驟更新佈景的 messages.po 檔案
- 更新佈景的翻譯目錄，以更新每個佈景的可翻譯文字佔位符。
- 翻譯你能力所及的每個
messages.po目錄檔語言中新加入的可翻譯文字佔位符。 - 本地端提供服務並測試您的語言翻譯主題。
- 透過拉取請求貢獻您的翻譯。
更新翻譯目錄
在為你願意協助翻譯的每個語言更新佈景範本後，應完成此步驟。
若要更新兩個內建佈景的 fr 翻譯目錄，請使用下列命令
pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr
pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l fr現在你可以繼續執行下一步，並為在地化目錄中的每個已更新文字佔位符 加入翻譯。
翻譯 MkDocs 佈景
現在由於在地化的 messages.po 檔案已準備完成，你只需要為檔案中的每個 msgid 項目在每個 msgstr 項目中加入翻譯。
msgid "Next"
msgstr "Siguiente"警告
不要修改 msgid，因為它在所有翻譯中都是通用的。僅在 msgstr 項目中加入其翻譯。
完成翻譯 po 檔案中列出的所有術語後，您會想要測試您在地化的主題。
測試主題的翻譯
要測試含翻譯的主題，您需要先編譯主題的 messages.po 檔案成 messages.mo 檔案。以下命令會編譯內建主題的 es 翻譯
pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es
pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -l es上述命令會產生以下的檔案結構
mkdocs/themes/mkdocs/locales
├── es
│ └── LC_MESSAGES
│ ├── messages.mo
│ └── messages.po請注意，編譯產出的 messages.mo 檔案是透過您剛編輯過的 messages.po 檔案產生。
接著修改專案根目錄的 mkdocs.yml 檔案，以測試新的或已更新的區域設定
theme:
name: mkdocs
locale: es最後，執行 mkdocs serve 以查看您在地化的主題新版本。
注意
組建和發佈流程會編譯並分發所有區域設定給最終使用者，因此您僅須負責提供實際文字翻譯的 messages.po 檔案（其餘的會由 git 忽略）。
完成測試您的工作後，務必取消 mkdocs.yml 檔案中對 locale 設定的變更，再提交變更。
更新主題文件
選擇您的主題頁面會針對所有可用的區域設定選項自動更新。
提供翻譯
現在是您為專案提供您的優秀作品的時候了。謝謝您！