國際化與機器翻譯¶
文件將英文和簡體中文視為經過審閱的規範來源。所有其他已啟用語言都是自動生成的
派生產物。語言註冊表、來源路由、模型配置和 API 限制均位於
i18n/config.toml。
1. 語言覆蓋與來源路由¶
註冊表有意將覆蓋範圍收斂為 12 種站點語言。其中包含聯合國六種官方語言： 阿拉伯語、中文、英語、法語、俄語和西班牙語；東亞地區另外包含日語、韓語與 繁體中文，歐洲地區另外包含德語、義大利語與葡萄牙語。英文和簡體中文屬於 規範來源，因此共有 10 種語言由機器翻譯。
日語、韓語和繁體中文以簡體中文為來源；其他所有派生語言均以英文為來源。 每個語言的來源均在配置中明確指定，翻譯器不會根據語言名稱或文件字符進行猜測。
新增語言時，必須同時更新 i18n/config.toml 和 MkDocs i18n 語言列表。文件
審計會拒絕兩個註冊表不一致的狀態。
2. 規範文件契約¶
每個 MkDocs 頁面都必須同時具有英文文件和 .zh-CN.md 文件。Pull request、
向 main 的推送或手動觸發的品質檢查如果修改了其中一個規範版本，就必須在
受檢查的提交範圍內包含另一版本。品質工作流會檢查：
- 規範文件配對以及變更配對；
- 標題層級與程式碼圍欄的一致性；
- 本地連結與原始碼引用；
- fixture 和測試清單；
- 所有已配置語言的嚴格建置。
規範內容可以由人工編寫，也可以藉助 AI，但必須作為普通原始碼提交和審閱。 Pull request 工作流絕不會呼叫翻譯 API。
3. 標題編號與片段連結穩定性¶
Markdown 原始文件只儲存描述性標題文字，不儲存大綱序號。每次 MkDocs 建置時，
scripts/mkdocs_heading_numbers.py 會為 H2–H6 添加頁面內編號。使用指南頁面
的 H2 使用小寫字母（a.、b.），更深層級使用字母加十進位（a.1、
a.1.1）；其他頁面仍採用十進位頁面大綱。左側使用指南導航則單獨使用
1.1 一類層級十進位編號。H1 頁面標題與頂層導航欄目不編號。生成序號屬於
展示元資料：移動章節會改變可見序號，但不會改變片段識別碼。
建置鉤子會先固定每個標題的顯式識別碼，再添加可見序號。
i18n/legacy-heading-anchors.json 保留移除手寫序號之前已經發布過的片段別名。
不要隨意編輯這份生成的相容映射，也不要在規範或派生 Markdown 中重新加入手寫
大綱序號；文件審計會拒絕這種內容。
4. 派生文件契約¶
生成頁面採用 MkDocs 後綴模式，例如 index.fr.md 或
guide/configuration.ja.md。每個頁面都包含確定性的 front matter，記錄：
- 規範來源語言和路徑；
- 來源檔案的 SHA-256 摘要；
- 實際使用的模型與提示詞版本；
- 該頁面屬於機器翻譯。
i18n/manifest.json 還會記錄輸出摘要和翻譯輸入指紋。當來源、詞彙表、提示詞、
模型或生成輸出發生變化時，頁面即被視為過期。除非明確要求完整重建，翻譯器只
請求過期單元。
翻譯後的標題保留本地化的自然 slug，同時獲得規範來源 slug 的隱藏別名。由於 Markdown 連結目標在其他情況下會受到保護、不允許模型修改，這些別名可以保證 同頁和跨頁片段連結在每種語言中都有效。別名可以離線重新整理，無需再次呼叫翻譯 API。
生成檔案不得手工編輯。主分支翻譯工作流會重新生成這些檔案，並在每種語言完成後
把該語言作為一個批次提交到由品質檢查精確 SHA 派生的 generated-only 分支。
後續執行會先驗證再複用該分支，因此中斷時只會丟失仍在處理的那一種語言。工作流
完成派生語言審計、完整測試套件與所有語言的嚴格建置之前，main 保持不變。
驗證全部通過後，工作流再次確認 main 未前進，再用一次 fast-forward 推送提升
checkpoint，並部署同一份已經驗證的站點成品。
5. Markdown 保護與提示詞契約¶
發送 API 請求前，翻譯器會把 front matter、圍欄程式碼、行內程式碼、連結目標、 HTML 標籤和裸 URL 替換為不可變佔位符。任何佔位符缺失、重複、憑空出現或無法 按契約還原，回應都會被拒絕。
提示詞還要求標題層級和程式碼圍欄語言保持一致。實作會在恢復受保護內容後獨立驗證 這些屬性。翻譯輸出必須是 JSON 物件；JSON 外的說明文字、空內容、異常結束原因 或不兼容的資料結構都屬於失敗。
Markdown 與導航目錄提示詞在 i18n/prompts/ 中單獨版本化；
i18n/glossary.json 儲存穩定的產品名和命令術語。
6. 模型配置與憑證¶
預設模型配置為 deepseek-v4-flash。實作不會針對該名稱編寫條件分支。以後更換
模型時，只需修改 i18n/config.toml、傳入 --model，或設定
DEEPSEEK_TRANSLATION_MODEL 工作流變數。最終解析出的模型會記錄在每個生成
頁面和 manifest 條目中。
GitHub Actions 只從名為 DEEKSEEK_API_KEY 的 repository secret 讀取 API
憑證。只有離線計畫顯示存在待處理的 API 翻譯單元時，生成步驟才會獲得該
secret；不可信的 pull request 程式碼以及無需 API 的規劃、清理和驗證步驟均無法
獲得。認證值絕不會寫入日誌、生成檔案、artifact 或 manifest。
7. 頁面提示與語言偏好¶
機器生成頁面會在渲染時獲得本地化警告。該警告說明頁面由 AI 翻譯，連結到權威的 英文或簡體中文原文，並連結到預填內容的翻譯問題報告。提示不屬於翻譯後的 Markdown，也不會生成目錄條目。
訪客首次開啟站點根頁面時，網站會把 navigator.languages 與已經配置的語言
備選項進行比較，並在存在兼容項時選擇對應語言。使用者手動選擇的語言會儲存在
本地，並在以後訪問時優先生效。
8. 維護命令¶
在不發起網路請求的情況下檢視待翻譯單元數量：
uv run python scripts/translate_docs.py --plan
驗證所有生成頁面和目錄翻譯均為最新狀態：
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
在不呼叫 API 的情況下重新整理穩定的來源標題別名：
uv run python scripts/translate_docs.py --refresh-heading-anchors
使用明確模型強制完整重建：
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash
自動工作流會使用 repository secret，而不是把金鑰放在命令列中。