文件
主要為透過 docs[] 設定區塊管理的 Markdown、MDX 和 .astro 文件而設計。每個區塊的 contentPaths 欄位列出了要翻譯的檔案或資料夾。
在 Docusaurus 網站上，也請將 docusaurusCatalogDir 設定為您的 write-translations 目錄資料夾（例如 docs-site/i18n/en）。接著 translate-docs 也會包含 shell JSON — 導導覽列、頁尾及主題字串。
在 VitePress 網站上，頁面主體使用相同的 docs[] 管線。導覽、側邊欄及頁尾標籤位於 docsOutput.vitepressThemeCatalog — translate-docs 會啟動英文目錄並與頁面一同翻譯，無需單獨的管線。
在 Nextra 網站上，頁面主體使用與 docsOutput.style: "nextra" 相同的 docs[] 管線。_meta.ts 側邊欄標籤由 translate-docs 自動收集並翻譯；主題字典字串透過 docs[].nextraDictionaryPath 在相同管線中翻譯。
在 Fumadocs 網站上，頁面主體使用 docsOutput.style: "fumadocs" 搭配 fumadocsParser "dot"（預設）或 "dir"。meta.json 側邊欄標籤會自動收集；UI 覆寫透過 docsOutput.fumadocsUiCatalog 翻譯。
在 Astro Starlight 網站上，頁面主體使用 docsOutput.style: "astro-starlight"，並將 docsRoot 設定為您的 Starlight 內容根目錄（通常是 src/content/docs/）。translate-docs 會在英文檔案樹旁的 src/content/docs/<locale>/ 下寫入本地化的 markdown/MDX。Starlight 內建了多種語系的內建 UI 字串 — 無需單獨的主題目錄管線；可選的 UI 覆寫可在 src/content/i18n/en.json 的 docs[] 區塊上使用 jsonPathTemplate。
對於嵌入在 Markdown 中的 PNG 和其他點陣圖影像，請參閱影像與螢幕截圖。translate-docs 僅翻譯替代文字；它不複製點陣圖檔案。
若要在 README 或文件中加入選用的 語言切換器 區塊，請將 docsOutput.style 設定為 "flat" — 請參閱語言切換器。
SVG 檔案會在啟用 features.translateSVG 時透過 translate-svg 翻譯 — 而非透過 docs[] / contentPaths。
與文件框架的殼層/主題字串無關的任意巢狀 UI JSON 套件應屬於 JSON 管線，而非 docs[]。
為了讓 UI 與文件之間術語一致，請將 glossary.uiGlossary 設定為您的 strings.json 路徑 — 當片段中出現相符的術語時，translate-docs 會將現有的 UI 翻譯作為提示重複用於 LLM 提示詞中。選用的 glossary.userGlossary 可為產品術語新增 CSV 覆寫（與 translate-ui 及 proofread-ui 共用）。使用 glossary-generate 產生起始 CSV，在翻譯儀表板的 詞彙表 分頁中編輯列，或參閱設定 — glossary及詞彙表。
每個地區模型覆蓋
translate-docs 及 sync 的文件步驟會按目標語系解析模型：若已設定則優先使用 localeModels(locale)，其次為供應商的全域 translationModels 鏈。當特定語言需要與預設後備清單不同的模型時可使用此功能 — 例如，當全域鏈難以處理葡萄牙文時，偏好為 pt-BR 文件使用 Gemini。請參閱供應商與模型及設定 - localeModels。
閱讀哪份指南
| 您的設定 | 從此開始 |
|---|---|
| Docusaurus 網站 | init -t ui-docusaurus、docsOutput.style = "docusaurus" - Docusaurus |
| VitePress 網站 | init -t ui-vitepress + vitepressThemeCatalog 用於主題 - VitePress |
| Nextra 網站 | init -t ui-nextra + nextraDictionaryPath 用於字典（側邊欄 _meta.ts 為自動） - Nextra |
| Fumadocs 網站 | init -t ui-fumadocs + fumadocsUiCatalog 用於 UI（側邊欄 meta.json 為自動） - Fumadocs |
| Astro Starlight | init -t ui-starlight - Astro Starlight |
| 扁平文件（README、變更日誌等） | docsOutput.style = "flat" - 輸出佈局、選用語言切換器 |
| 翻譯檔案的存放位置 | 輸出佈局 |
跨頁面 #anchor 連結 | 錨點連結 |
連結和資產 URL 重寫 (regexAdjustments) | 連結重寫 |
| 文件中的螢幕截圖 | 影像與螢幕截圖 |
| 產品術語與 UI/文件一致性 | 設定 — glossary、詞彙表 |
translate-docs 旗標和快取 | CLI 選項 |
步驟 1：初始化文件
ai-i18n-tools init -t ui-docusaurus [-P <provider>]適用於 Astro Starlight 文件網站：
ai-i18n-tools init -t ui-starlight [-P <provider>]對於 VitePress 文件網站：
ai-i18n-tools init -t ui-vitepress [-P <provider>]為導覽/側邊欄/頁尾字串設定 docsOutput.vitepressThemeCatalog — 請參閱VitePress 整合。
對於 Nextra 文件網站：
ai-i18n-tools init -t ui-nextra [-P <provider>]為主題字典字串設定 docs[].nextraDictionaryPath — 請參閱Nextra 整合。側邊欄 _meta.ts 標籤會自動收集。
對於 Fumadocs 文件網站：
ai-i18n-tools init -t ui-fumadocs [-P <provider>]為 UI 覆寫設定 docsOutput.fumadocsUiCatalog — 請參閱Fumadocs 整合。側邊欄 meta.json 標籤會自動收集。
適用於純 Astro 網站 UI（無 Starlight）：
ai-i18n-tools init -t ui-astro-website [-P <provider>]該範本僅啟用 UI 提取。對於頁面 HTML 翻譯，還需設定 features.translateDocs 並新增一個 docs[] 區塊（請參閱 Astro 網站頁面（解析與替換））。examples/astro-website 設定顯示了兩個管道。
編輯產生的 ai-i18n-tools.config.json：
provider及providers—init會建立預設的供應商區塊（除非您傳入-P <provider>，否則為openrouter）；在執行translate-docs或sync之前，請至少設定一個供應商並設定其 API 金鑰（Ollama 無需金鑰）。請參閱供應商與 API 金鑰及LLM 供應商與模型。sourceLocale- 來源語言（必須與docusaurus.config.js中的defaultLocale相符）。targetLocales- BCP-47 語系代碼陣列（例如["de", "fr", "es"]）。cacheDir- 所有管線共用的 SQLite 快取目錄（同時為--write-logs的預設日誌目錄）。docs- 文件區塊陣列。每個區塊包含可選的description、contentPaths（字串或陣列；檔案、目錄或萬用字元模式）、outputDir、可選的docusaurusCatalogDir、docsOutput、可選的segmentSplitting、translateFrontmatterFields、protectAttributes、protectKeys、targetLocales、addFrontmatter等。docs[].description- 給維護者的可選簡短備註。設定後，會顯示在translate-docs標題與status區塊標頭中。docs[].contentPaths- markdown/MDX/.astro來源（以及 Docusaurus shell JSON 的可選docusaurusCatalogDir）。docs[].outputDir- 該區塊的翻譯輸出根目錄。docs[].docsOutput.style-"nested"（預設）、"flat"、"doc-system"，或別名"docusaurus"/"astro-starlight"/"vitepress"/"nextra"/"fumadocs"（請參閱輸出佈局）。glossary.uiGlossary-strings.json的路徑，讓文件片段能從您的 UI 目錄取得術語提示（請參閱設定 —glossary）。glossary.userGlossary- 選用的 CSV，用於固定的產品術語翻譯；同時供 UI 管線使用，並可在詞彙表儀表板分頁中編輯。
主要與補充： 專注於 contentPaths 以進行本地化頁面。當您也需要來自 write-translations 的 Docusaurus shell JSON 時，請設定 docusaurusCatalogDir。如果您只翻譯頁面，請省略 docusaurusCatalogDir。
步驟 2：翻譯文件
ai-i18n-tools translate-docs這會將每個 docs[] 區塊的 contentPaths 中的所有檔案（以及在設定 docusaurusCatalogDir 時的 Docusaurus 目錄 JSON）翻譯為所有有效的文件語系。已翻譯的段落會從 SQLite 快取提供 - 只有新增或變更的段落才會傳送至 LLM。
翻譯單一地區設定：
ai-i18n-tools translate-docs --locale de檢查需要翻譯的內容：
ai-i18n-tools status有關旗標、快取行為和批次提示格式，請參閱CLI 選項。
複雜的 Markdown 和失敗的品質檢查
translate-docs 會檢查每個翻譯段落是否保留了 Markdown 結構（包括從文件中解析出的強調格式）。當段落中堆疊了許多 bold 區塊、在 `inline code` 周圍嵌套反引號、將反引號置於粗體內（例如範本字面值如 `fetch(\`/locales/${code}.json\`)`），或在一個長句中交錯使用粗體與程式碼時，這種結構相當脆弱：某些語系需要不同的詞序，這可能導致翻譯後 ** 和 ` 的對應錯亂，進而觸發 CLI 錯誤，例如 AST mismatch。
如果您遇到此類驗證失敗，請優先簡化來源語言文字 - 分割段落、將範例移至圍欄程式碼區塊中，或使用較少層層堆疊的粗體/程式碼配對來描述相同概念 - 而非期望每個模型和語系都能完美重現密集的行內標記。
當所有設定的模型在同一段落上都因 AST mismatch 失敗時，translate-docs 可自動將該段落拆分為更小的部分（優先從清單中點拆分，然後是單個清單項目或較短的段落片段），從第一個模型開始重試每一部分，並在原始段落的快取鍵下重新合併結果。此功能預設啟用（segmentSplitting.qualityRetrySplit）；設定為 false 可在模型全部嘗試失敗後停止。執行摘要會在啟用此備援機制時報告 Quality split retries。
若要查看哪些區段失敗、失敗頻率以及儲存的品質/錯誤訊息，請使用翻譯儀表板的失敗分頁 (翻譯儀表板 → 失敗)。