文件
translate-docs 的參考文件,此為處理 docs[] 設定區塊中所列 Markdown、MDX、.astro 及純 HTML 頁面的管線。每個區塊的 contentPaths 欄位會列出要翻譯的檔案或資料夾。這些檔案是以 sourceLocale 編寫,可以是任何語言。範例中的英文僅為示例。首次為網站新增語言嗎?請從 為網站或文件網站新增 i18n 開始。儲存庫 README 和其他 Markdown 檔案,通常位於應用程式旁:為您的 README 和 Markdown 文件新增 i18n。純 HTML 頁面(每個語系一個檔案)的說明請見 HTML 頁面。
框架外殼字串(導覽列、側邊欄、主題)會在同一次執行中翻譯,而非透過獨立的管線。下表中的框架指南說明了各框架的作法:Docusaurus 使用 docusaurusCatalogDir、VitePress 使用 docsOutput.vitepressThemeCatalog、Nextra 使用 docs[].nextraDictionaryPath,而 Fumadocs 使用 docsOutput.fumadocsUiCatalog。Nextra _meta.ts 和 Fumadocs meta.json 的側邊欄標籤會自動收集。Astro Starlight 隨附許多語系的內建 UI 字串,而可選的覆寫可以在 docs[] 區塊上使用 jsonPathTemplate。
對於嵌入在 Markdown 中的 PNG 和其他點陣圖影像,請參閱影像與螢幕截圖。translate-docs 僅翻譯替代文字;它不複製點陣圖檔案。
若要在 README 或文件中加入選用的 語言切換器 區塊,請將 docsOutput.style 設定為 "flat" — 請參閱語言切換器。
SVG 檔案會在啟用 features.translateSVG 時透過 translate-svg 翻譯 — 而非透過 docs[] / contentPaths。
與文件框架的殼層/主題字串無關的任意巢狀 UI JSON 套件應屬於 JSON 管線,而非 docs[]。
每個 UI 區塊預設會將其 strings.json 作為文件的術語表提示(uiGlossary,預設為 true)。當區段中出現相符的術語時,translate-docs 會將這些翻譯重複用作 LLM 提示詞中的提示。對於不應納入文件提示詞的目錄,請將 uiGlossary 設定為 false。選用的 glossary.userGlossary 可新增產品術語的 CSV 覆寫(與 translate-ui 和 proofread-ui 共用)。為適應窄欄位而使用的精簡 UI 標籤縮寫(例如 Size → Tam)仍可用於 UI 翻譯,但會從文件術語表提示中省略。使用 glossary-generate 產生初始 CSV,在翻譯儀表板的 術語表 索引標籤中編輯列,或參閱 設定 — glossary 與 術語表。
每個地區模型覆蓋
translate-docs 和 sync 的 docs 步驟會依目標語系解析模型:若有設定,會先使用 localeModels(locale),接著是供應商的全域 translationModels 鏈。當特定語言需要的模型與您的預設備援清單不同時,請使用此功能——例如,當全域鏈結難以處理葡萄牙文時,為 pt-BR 文件偏好使用 Gemini。請參閱 AI 模型 和 設定 - 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 |
| 純 HTML 頁面 | init -t docs-plain-html - HTML 頁面 |
| 扁平文件(README、變更記錄等) | 為您的 README 和 Markdown 文件新增 i18n — init -t docs-markdown 或 --with-readme。版面配置:輸出版面配置、語言切換器 |
| 翻譯檔案的存放位置 | 輸出佈局 |
跨頁面 #anchor 連結 | 錨點連結 |
連結和資產 URL 重寫 (regexAdjustments) | 連結重寫 |
| 文件中的螢幕截圖 | 影像與螢幕截圖 |
| 產品術語與 UI/文件一致性 | 設定 — glossary、術語庫 |
translate-docs 旗標和快取 | CLI 選項 |
步驟 1:初始化文件
ai-i18n-tools init -t ui-docusaurus -P openai適用於 Astro Starlight 文件網站:
ai-i18n-tools init -t ui-starlight -P cheaperinference對於 VitePress 文件網站:
ai-i18n-tools init -t ui-vitepress -P anthropic為導覽/側邊欄/頁尾字串設定 docsOutput.vitepressThemeCatalog — 請參閱VitePress 整合。
對於 Nextra 文件網站:
ai-i18n-tools init -t ui-nextra -P gemini為主題字典字串設定 docs[].nextraDictionaryPath — 請參閱Nextra 整合。側邊欄 _meta.ts 標籤會自動收集。
對於 Fumadocs 文件網站:
ai-i18n-tools init -t ui-fumadocs -P groq為 UI 覆寫設定 docsOutput.fumadocsUiCatalog — 請參閱Fumadocs 整合。側邊欄 meta.json 標籤會自動收集。
適用於純 Astro 網站 UI(無 Starlight):
ai-i18n-tools init -t ui-astro-website -P ollama該範本僅啟用 UI 擷取。若要翻譯頁面 HTML,也請設定 features.translateDocs 並新增一個 docs[] 區塊(請參閱 Astro 網站頁面 (剖析並取代))。examples/astro-website 設定會同時顯示這兩個管線。
編輯產生的 ai-i18n-tools.config.json:
provider和providers—init -P <provider>會建立該預設的鷹架;在translate-docs或sync之前設定其 API 金鑰 (Ollama 不需要金鑰)。請參閱 供應商與 API 金鑰、LLM 供應商 和 AI 模型。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"(請參閱 輸出配置)。ui[].uiGlossary- 當為true(預設值)時,該區塊的strings.json會提供文件區段的術語提示(請參閱 設定 —ui)。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 結構(包括從文件中解析出的強調標記),以及內部佔位符標記是否正確還原。在 `inline code` 周圍堆疊多個 bold 跨度、在粗體內嵌套反引號(例如範本字面值如 `fetch(\`/locales/${code}.json\`)`),或在長句中交織粗體與程式碼的段落非常脆弱:某些語言環境需要不同的語序,這可能會改變 ** 和 ` 在翻譯後的對齊方式,並觸發如 AST mismatch 的 CLI 錯誤。
還原後,translate-docs 亦會拒絕以下段落:HTML 標籤佔位符被重複使用或丟棄(導致還原後的標籤不再與來源映射相符),或模型捏造了來源中不存在的多餘雙花括號權杖(例如虛構的詞彙表風格權杖)。還原前檢查要求相同的 {{…}} 權杖多重集,以及相同的結構權杖有序子序列({{HTM_N}},提示標記);內容權杖如 {{ILC_N}}、{{URL_N}},以及強調標記如 {{SE}} 可隨自然語序移動,前提是每個 id / 類型的計數仍相符。這些失敗情況使用與多餘官方內部權杖相同的模型回退路徑。
如果您遇到此類驗證失敗,請優先簡化來源語言文字 - 分割段落、將範例移至圍欄程式碼區塊中,或使用較少層層堆疊的粗體/程式碼配對來描述相同概念 - 而非期望每個模型和語系都能完美重現密集的行內標記。
當為某個區段嘗試的模型以 AST mismatch 失敗時,translate-docs 可以自動將該區段分割成較小的部分(先從列表中間分割,然後是單個列表項目或較短的段落區塊),從第一個模型重試每個部分,並在原始區段快取鍵下重新組合結果。相同的品質錯誤發生三次會提前停止模型列表;不同的錯誤則會繼續。此功能預設為開啟 (segmentSplitting.qualityRetrySplit);將其設定為 false 以在模型列表結束後停止。當此備用機制執行時,執行摘要會報告 Quality split retries。
若要查看哪些區段失敗、失敗頻率以及儲存的品質/錯誤訊息,請使用翻譯儀表板的失敗分頁 (翻譯儀表板 → 失敗)。