Skip to content

文件 ​

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 Starlightinit -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:初始化文件 ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai

適用於 Astro Starlight 文件網站:

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference

對於 VitePress 文件網站:

bash
ai-i18n-tools init -t ui-vitepress -P anthropic

為導覽/側邊欄/頁尾字串設定 docsOutput.vitepressThemeCatalog — 請參閱VitePress 整合。

對於 Nextra 文件網站:

bash
ai-i18n-tools init -t ui-nextra -P gemini

為主題字典字串設定 docs[].nextraDictionaryPath — 請參閱Nextra 整合。側邊欄 _meta.ts 標籤會自動收集。

對於 Fumadocs 文件網站:

bash
ai-i18n-tools init -t ui-fumadocs -P groq

為 UI 覆寫設定 docsOutput.fumadocsUiCatalog — 請參閱Fumadocs 整合。側邊欄 meta.json 標籤會自動收集。

適用於純 Astro 網站 UI(無 Starlight):

bash
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:翻譯文件 ​

bash
ai-i18n-tools translate-docs

這會將每個 docs[] 區塊的 contentPaths 中的所有檔案(以及在設定 docusaurusCatalogDir 時的 Docusaurus 目錄 JSON)翻譯為所有有效的文件語系。已翻譯的段落會從 SQLite 快取提供 - 只有新增或變更的段落才會傳送至 LLM。

翻譯單一地區設定:

bash
ai-i18n-tools translate-docs --locale de

檢查需要翻譯的內容:

bash
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。

若要查看哪些區段失敗、失敗頻率以及儲存的品質/錯誤訊息,請使用翻譯儀表板的失敗分頁 (翻譯儀表板 → 失敗)。

採用 MIT 授權條款釋出。