Skip to content

設定參考 ​

sourceLocale ​

來源語言的 BCP-47 代碼(例如 "en-GB"、"pt-BR" 或 "ja")。任何語言皆可。範例中出現英文是因為許多專案都從英文開始。此語區不會產生翻譯檔案——鍵字串本身就是來源文字。

必須符合 從您的執行階段 i18n 設定檔(src/i18n.ts / src/i18n.js)匯出的 SOURCE_LOCALE。


targetLocales ​

要翻譯成的 BCP-47 語系代碼陣列(例如 ["de", "fr", "es", "pt-BR"])。

targetLocales 是 UI 翻譯的主要語系清單,也是文件區塊的預設語系清單。使用 generate-ui-languages 從 sourceLocale + targetLocales 建構 ui-languages.json 資訊清單。


uiLanguage (選用) ​

工具自身介面語言(CLI 說明、日誌/摘要,以及翻譯儀表板)的 BCP-47 代碼。它獨立於 sourceLocale / targetLocales,並會被 -L / --ui-lang 旗標與 AI_I18N_LANG 環境變數覆寫。未知值會優雅降級為來源地區設定(en-GB)——沒有嚴格的驗證。請參閱工具介面語言。


languagesManifestPath(選用) ​

根層級的選填字串。文件語言切換器會讀取此路徑。若省略,則預設為第一個 UI 區塊的資訊清單:該區塊的 languagesManifestPath 或 {flatOutputDir}/ui-languages.json。每個 UI 區塊都可以設定自己的 languagesManifestPath;當區塊省略自己的路徑時,區塊 0 會使用此根路徑。

在以下情况下使用此选项:

  • 資訊清單應置於 ui.flatOutputDir 之外(例如放在 src/i18n/ 下的應用程式輔助程式旁)。
  • 您希望語言切換器後處理(languageListBlock)從專案資訊清單建構地區標籤,而非僅使用內建的主目錄。

includeUiLanguageEnglishNames 不會讀取此檔案——它使用內建的主目錄(詳見下文 ui.uiExtractor)。

舊版: 載入設定檔時仍接受根層級的 uiLanguagesPath,並自動改寫為 languagesManifestPath。


concurrency(可选) ​

同時翻譯的目標語系數量上限 (translate-ui、translate-docs、translate-svg,以及sync內部的對應步驟)。如果省略,CLI 會將 4 用於 UI 翻譯,並將 3 用於文件翻譯 (內建預設值)。可透過 -j / --concurrency 在每次執行時覆寫。


batchConcurrency(可选) ​

translate-docs、translate-svg 與 translate-json(以及 sync 內對應的步驟):每個檔案的最大並行 LLM 批次請求數(每個批次可包含多個區段)。省略時預設為 4。不適用於 translate-ui——請改用 uiBatchConcurrency。可用 -b / --batch-concurrency 覆寫。


uiBatchConcurrency(選用) ​

translate-ui、sync-ui 與 sync 的 UI 步驟:單一語系內的最大並行 LLM 批次請求數(先處理 50 個純字串區塊,再處理複數群組)。省略時預設為 2。與 concurrency(並行目標語系)和 batchConcurrency(docs/JSON/SVG)互不相關。無 CLI 旗標;請在設定檔中設定,或將 uiBatchConcurrency 傳遞給程式化介面的 runTranslateUI。

範例:

json
{
  "uiBatchConcurrency": 2
}

在預設語系並行數 4 的情況下,這表示最多可有 8 個進行中的 UI API 呼叫。翻譯單一大型語系(-l de)時可提高此值;若供應商有速率限制則保持較低的值。


fileConcurrency(選填) ​

在單一地區內,於 translate-docs 和 sync 期間可同時處理的檔案數目。當設定為大於 1 的值時,同一地區內的檔案會使用訊號量(semaphore)來控制記憶體使用量,並以平行方式處理。預設值為 1(循序處理),若省略則使用預設值。較高的值可顯著提高 I/O 繫結操作的輸送量,特別是當所有區段都已快取(無需 API 呼叫)時。

範例:

json
{
  "fileConcurrency": 4
}

使用案例: 執行 sync --force-update 時,將此設定為 2-4,以達到 100% 快取命中率,從而減少總處理時間。此改善對於處理大量小型檔案時最為顯著。


batchSize / maxBatchChars(選填) ​

translate-docs、translate-svg 和 translate-json 的區段批次處理:每個 API 請求的區段數和字元上限。預設值:20 個區段,4096 個字元(省略時)。


requestTimeout / requestTimeoutMs(選填) ​

每個 LLM 請求對每個供應商的最大等待時間。requestTimeout 是整數秒;requestTimeoutMs 是毫秒。預設值:當兩者都省略時為 120 秒。僅設定其中一個。設定任一欄位的供應商將改用該值,且僅適用於該供應商。


provider 和 providers ​

provider(頂層,選填)從 providers 中選取作用中的提供者金鑰。當僅設定一個提供者時為選填;當設定多個提供者時為必要。

providers(頂層)將提供者金鑰對應至其區塊。內建金鑰(請參閱下方的預設表格)僅需要 translationModels;任何其他金鑰都定義了一個自訂的 OpenAI 相容端點,並需要 baseUrl(以及 apiKeyEnv,除非該端點不需要金鑰)。

每個 providers.<name> 區塊接受:

  • translationModels 首選的模型 ID 有序列表(純粹的上游 ID,沒有 provider/ 前綴;OpenRouter ID 保留其原生的 vendor/model 形式)。第一個會優先嘗試;後面的項目在出錯時作為備用。當沒有更具體的層級適用時,這是每個管線的全局預設鏈。
  • uiModels (選用) 僅限 UI 的模型有序列表,用於 translate-ui、複數生成(步驟 0 和階段 B)以及 proofread-ui。在目標語言環境的任何匹配 localeModels 項目之後,translationModels 之前嘗試。
  • localeModels (選用) 每個語言環境的覆寫,用於 所有翻譯管線。{ "locale": "<BCP-47>", "models": ["…"] } 物件的陣列。語言環境標籤不區分大小寫匹配(pt-br = pt-BR)。每個語言環境的列表僅針對該語言環境優先嘗試,然後是管線特定的層級(uiModels 用於 UI)和 translationModels。在配置載入時拒絕重複的標準化語言環境鍵。
  • baseUrl 與 OpenAI 相容的基礎 URL。覆寫預設的基礎 URL;非預設提供者需要。
  • apiKeyEnv 儲存 API 金鑰的環境變數。覆寫預設的環境變數。
  • headers 每次向此提供者發送請求時傳送的額外 HTTP 標頭。
  • maxTokens 每個請求的最大完成權杖數。預設值:8192。
  • temperature 取樣溫度。預設值:0.2。
  • requestTimeout 等待此供應商每個請求的最大時間(以秒為單位)。覆寫頂層的 requestTimeout / requestTimeoutMs。當此供應商和頂層設定均未設定逾時時,預設值為 120 秒。在同一物件上僅設定 requestTimeout 和 requestTimeoutMs 的其中一個。
  • requestTimeoutMs 等待此供應商每個請求的最大時間(以毫秒為單位)。覆寫頂層的 requestTimeout / requestTimeoutMs。當此供應商和頂層設定均未設定逾時時,預設值為 120000 (120 秒)。在同一物件上僅設定 requestTimeout 和 requestTimeoutMs 的其中一個。
  • pricing (選用) 供應商範圍內每 100 萬個權杖的美元費用:{ "inputPerMTokens": 0.15, "outputPerMTokens": 0.6 }。當計費呼叫沒有供應商報告的 usage.cost (大多數供應商,OpenRouter 和 Cheaper Inference 除外) 時,此費率將套用於該呼叫的輸入和輸出權杖。該金額會包含在翻譯摘要中,並儲存在 api_calls 列。

費用來源依此順序解析:

  1. 匹配的 modelPricing 項目 (覆寫此提供者預設值);
  2. 提供者報告的費用 (永不取代);
  3. 此 pricing 費率;
  4. 該模型 ID 在 models.dev 上的標價 (輸入和輸出每 1M 權杖的美元費用)。

未儲存費用的列仍可透過 usage 和 使用量與費用 稍後估算。如果這些來源都不適用,費用將保持未知 (—),絕不會是 $0.00。

  • modelPricing (選用) 每個模型每 1M 權杖的美元費用:{ "<model-id>": { "inputPerMTokens": 2.5, "outputPerMTokens": 10 } }。覆寫該模型 ID 的 pricing。當提供者省略 usage.cost 時,在呼叫時應用,並隨呼叫儲存。
  • zeroDataRetention (選用,僅限 providers.cheaperinference) 當 true 時,聊天請求會傳送 "zdr": true 和 list-models,check-models 和 suggest-models 會載入 GET /v1/models?zdr=true。省略表示關閉。請參閱 零資料保留。

內建提供者預設值(金鑰 — 基本 URL — API 金鑰環境變數):

供應商基礎 URLAPI 金鑰環境變數
alibabahttps://dashscope-intl.aliyuncs.com/compatible-mode/v1ALIBABA_API_KEY
anthropichttps://api.anthropic.com/v1ANTHROPIC_API_KEY
apikeyfanhttps://api.apikey.fan/v1APIKEYFAN_API_KEY
cerebrashttps://api.cerebras.ai/v1CEREBRAS_API_KEY
cheaperinferencehttps://api.cheaperinference.com/v1CHEAPERINFERENCE_API_KEY
deepseekhttps://api.deepseek.comDEEPSEEK_API_KEY
geminihttps://generativelanguage.googleapis.com/v1beta/openaiGOOGLE_API_KEY
groqhttps://api.groq.com/openai/v1GROQ_API_KEY
mistralhttps://api.mistral.ai/v1MISTRAL_API_KEY
nvidiahttps://integrate.api.nvidia.com/v1NVIDIA_API_KEY
ollamahttp://localhost:11434/v1(無)
openaihttps://api.openai.com/v1OPENAI_API_KEY
openrouterhttps://openrouter.ai/api/v1OPENROUTER_API_KEY
xaihttps://api.x.ai/v1XAI_API_KEY

apifun 預設已重新命名為 apikeyfan。請更新現有組態中的 provider 和 providers 鍵;APIFUN_API_KEY 仍是 APIKEYFAN_API_KEY 的別名。

舊版頂層 openrouter 區塊(包含 baseUrl、translationModels、defaultModel、fallbackModel、maxTokens、temperature、requestTimeout、requestTimeoutMs)仍受支援,並會在載入時自動遷移至 providers.openrouter(包含 provider: "openrouter");defaultModel / fallbackModel 會摺疊進 translationModels。

如需在一個設定中配置多個供應商並透過 -P 在其間切換的可執行範例,請參閱 examples/multi-provider(同一文件中的 openai、anthropic、openrouter 與 deepseek)。

為何要使用多個模型: 不同的供應商和模型有不同的成本,且在不同語言和地區設定中提供的品質水準也不同。將 translationModels 設定為一個有序的備援鏈,這樣一來,如果請求失敗,CLI 就能嘗試下一個模型。建立該列表的指南是 AI 模型。

請將下方的列表視為一個 基準。使用 AI 模型 上的基準測試排名來取代它。如果特定地區設定的翻譯品質仍然不佳,請為該語言或文字新增一個 localeModels 項目,或從供應商的目錄中新增更多 ID。

這些模型 ID 是 ai-i18n-tools init -P openrouter 所寫入的。其他預設會從 init -P <provider> 取得原生模型 ID — 請參閱 內建提供者。

此列表經過測試,涵蓋了廣泛的地區,適用於一個包含 36 個目標地區的大型文件專案;它是一個實用的預設值,但不能保證對每個地區都有良好的表現。

translationModels 範例(來自 ai-i18n-tools init -P openrouter 的 OpenRouter 清單):

OpenRouter 翻譯模型清單
json
"translationModels": [
  "google/gemini-2.5-flash",
  "meta-llama/llama-3.3-70b-instruct",
  "openai/gpt-4o-mini",
  "google/gemma-4-26b-a4b-it",
  "~anthropic/claude-haiku-latest",
  "z-ai/glm-5.2",
  "google/gemini-3.5-flash",
  "~anthropic/claude-sonnet-latest"
  // … add more fallback models as needed
]

建議的 uiModels: UI 字串簡短但顯眼——高階模型通常能改善語氣、複數形式與一致性。選用的 uiModels 會在任何相符的 localeModels 項目之後、translationModels 之前嘗試(請參閱上方的欄位列表)。範例:

用於 UI 翻譯的建議 uiModels
json
"uiModels": [
  "~anthropic/claude-sonnet-latest",
  "z-ai/glm-5.2"
]

亞洲語言的建議 localeModels: 日文、韓文與中文地區通常受益於針對這些文字調整過的模型。新增按地區的覆寫設定,當目標地區相符時,會優先嘗試(在 uiModels / translationModels 之前):

用於 ja、ko、zh-Hans、zh-Hant 的建議 localeModels
json
"localeModels": [
  { "locale": "ja",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "ko",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hans", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hant", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] }
]

在您的環境或 .env 檔案中設定作用中提供者的 API 金鑰環境變數(請參閱預設集表格)。

在變更模型清單之前,執行 ai-i18n-tools check-models。對於任何提供者,它會根據該提供者的即時模型清單 (GET /models) 驗證每個已設定的模型 ID(translationModels、uiModels 及所有 localeModels 項目),回報缺失或已過時的 ID (expiration_date),列出有效模型,並在任一已設定的 ID 無效時以非零值結束。當提供者傳回定價(例如 OpenRouter)時,它也會顯示預估的輸入/輸出定價(每百萬權杖的美元計價)。

若要比較真實翻譯工作中的已設定模型,執行 ai-i18n-tools bench-models。它會對 translationModels、uiModels 和 localeModels 中的每個唯一模型 ID 進行基準測試,方式是隔離翻譯一個範例(平行執行,受限於 concurrency),並輸出每模型的輸入/輸出權杖數、牆上時鐘時間和美元成本,讓您在決定模型清單前能權衡速度與價格。


features ​

欄位管道說明
translateUIStrings1將 t("…") / i18n.t("…") 提取到 strings.json 中,然後翻譯條目並寫入每個地區設定的平面 JSON(提取自動執行;使用獨立的 extract 僅重新整理目錄)。
translateDocs2翻譯 .md / .mdx / .astro / .html / .htm 頁面;已設定 docs[].docusaurusCatalogDir 時的 Docusaurus shell JSON;已設定時的 Nextra _meta / 字典;已設定 docsOutput.vitepressThemeCatalog 時的 VitePress 主題;當 docsOutput.style 為 "fumadocs" 時的 Fumadocs meta.json / UI 目錄。
translateJson3json[](translate-json)下的任意巢狀 JSON。
translateSVG—翻譯 .svg 檔案(需要頂層的 svg 區塊)。

當鍵被省略時,每個旗標預設為 true。其行為如下:

  • 如果省略 true 且沒有任何內容可翻譯,則會跳過:沒有 UI 區塊包含 sourceRoots,沒有文件區塊包含 contentPaths 或 docusaurusCatalogDir,json[] 沒有 contentPaths,或者 svg 未設定。
  • 當該管線沒有工作時,將旗標寫為 true 是一個組態錯誤。
  • 即使來源存在,寫入 false 也會針對 sync 關閉該管線。
  • --no-ui、--no-docs、--no-json 和 --no-svg 會在單次執行中跳過該步驟。

當 features.translateSVG 為 true 且已設定頂層 svg 區塊時,使用 translate-svg 翻譯 SVG 檔案。當旗標開啟且已設定 svg 時,sync 命令會執行該步驟(除非 --no-svg)。


ui ​

一個目錄物件,或一個目錄區塊陣列(與 docs[] 的概念相同)。載入時接受單一物件並將其包裝為單元素陣列;不會重新寫入磁碟上的檔案。剖析後,config.ui 一律為陣列。

extract、translate-ui、sync-ui、sync 的 UI 階段、proofread-ui、export-ui-xliff、generate-ui-languages 和 purge-locale 會遍歷每個具有 sourceRoots 的區塊。傳遞具有以零為起始之索引的 --ui-block、區塊的 description 或其 stringsJson 路徑,以執行單一區塊。status 和 statistics 會列出每個具有來源或現有目錄的區塊。翻譯儀表板會列出所有此類目錄,並在有多個目錄時顯示選取器。

已解析的 stringsJson、flatOutputDir 和資訊清單路徑在各區塊間必須是唯一的。設定 description 值時必須是唯一的,因為 --ui-block 會精確比對它們。

  • description 供閱讀設定的人員使用的選填備註(不會傳送至模型)。在命令標頭、status、statistics 和儀表板中顯示為 ui[i] — description。
  • sourceRoots 掃描 t("…") 呼叫的目錄或 glob 模式(相對於 cwd)。支援類似 src/ 或 ["src/**/*.ts"] 的模式。除非 --ui-block 指定具有空清單的區塊(這屬於錯誤),否則會跳過該區塊。
  • stringsJson 此區塊之主目錄檔案的路徑。由 extract 更新。
  • flatOutputDir 寫入此區塊各語言環境 JSON 檔案的目錄(de.json 等)。
  • flatOutput 當 true 時(預設值),translate-ui 會為每個地區設定寫入一個扁平的 JSON 檔案。設定 false 以僅輸出 gettext 或 resx。包含 flatOutput: false 的區塊必須設定 gettext 或 resx。
  • resx 選用的 .NET .resx 輸出。outputDir(預設值 Resources)和 baseName(預設值 SharedResource)會寫入 {baseName}.resx 以及 {baseName}.{culture}.resx。writeNeutral(預設為 true)會將原始文字放入中性檔案中,以便 ResourceManager 可以回溯。localeFormat 是 bcp47(預設值,pt-BR)或 posix(pt_BR)。ingestExistingResx(預設為 true)會在 extract 期間讀取附屬檔案。neutralFile 會透過中性值映射舊版命名鍵,例如 LoginButton。上下文鍵使用 U+2404。複數形式是名為 {singular}[{form}] 的獨立條目。包含 flatOutput: false 的區塊必須設定 gettext 或 resx。
  • gettext 此區塊的選用 GNU gettext 輸出。outputDir(預設值 ./locales)會接收 <locale>/LC_MESSAGES/<domain>.po,並且當 compileMo 為 true 時(預設值),接收匹配的 .mo。domain 預設為 messages。potPath 是範本目錄。ingestExistingPo(預設值 true)會在 extract 期間從非模糊的 msgstr 值填補空的 strings.json 槽位,並且不會取代非空或使用者編輯的翻譯。localeFormat 是 posix(預設值,pt_BR)或 bcp47(pt-BR)。上下文行使用 gettext \u0004 分隔符。相同來源語言字串在兩個不同上下文中不共用目錄 ID。
  • targetLocales 此區塊的選用地區設定清單。當省略或為空時,此區塊使用根 targetLocales。
  • languagesManifestPathextract 和 generate-ui-languages 寫入此區塊 ui-languages.json 的選用路徑。當省略時,區塊 0 使用根 languagesManifestPath(其本身預設為此區塊的 {flatOutputDir}/ui-languages.json)。後續區塊預設為 {flatOutputDir}/ui-languages.json。
  • uiGlossary 當 true 時(預設值),此區塊的 strings.json 是 translate-docs、translate-json 和 translate-svg 的詞彙表提示來源。translate-ui、proofread-ui 和原始碼檢查僅使用 glossary.userGlossary。設定 false 以將目錄排除在這些提示之外(例如,不應引導文件說明的 CLI 字串目錄)。
  • uiExtractor.funcNames (或舊版 reactExtractor.funcNames) 要掃描的其他函數名稱(預設值:["t", "i18n.t"])。
  • uiExtractor.extensions (或舊版 reactExtractor.extensions) 要包含的檔案副檔名(預設值:[".js", ".jsx", ".ts", ".tsx"])。為 Astro frontmatter 和範本表達式新增 .astro。
  • uiExtractor.includePackageDescription (或舊版 reactExtractor.includePackageDescription) 當 true 時(預設值),extract 也會將 package.json description 作為 UI 字串包含在內(如果存在)。在額外區塊上設定 false,這樣相同的描述就不會被提取到每個目錄中。
  • uiExtractor.packageJsonPath (或舊版 reactExtractor.packageJsonPath) 用於該選用描述提取的 package.json 檔案的自訂路徑。
  • uiExtractor.includeUiLanguageEnglishNames (或舊版 reactExtractor.includeUiLanguageEnglishNames)

當 true (預設值 false),extract 也會將每個 englishName 從隨附的 UI 語言主目錄 (根據 sourceLocale + 區塊的有效 targetLocales 建置) 新增到 strings.json,如果來源掃描中尚未存在 (相同的雜湊金鑰)。不會讀取 languagesManifestPath。

  • uiExtractor.placeholderStyledefault (mustache、Python 格式欄位和 printf) 或 dotnet (僅限 {0}、{0,-10}、{0:format})。在 dotnet 樣式中,百分比符號是常值文字,雙大括號是常值大括號。ui-dotnet 範本會設定 dotnet。
  • uiExtractor.exclude Minimatch 模式,相對於專案根目錄,在掃描後捨棄。bin、obj、.vs、TestResults 和 packages 已依目錄名稱跳過。ui-dotnet 和 ui-dotnet-resx 範本會排除 **/Tests/**、**/*.Tests/** 和 **/TrExtension.cs。

不再接受 glossary.uiGlossary 和 glossary.uiGlossaryFromStringsJson。設定載入會失敗,且錯誤會說明取代方式:刪除該索引鍵。提示現在來自每個區塊的 uiGlossary 旗標(預設 true)。


cacheDir ​

  • cacheDir SQLite 快取目錄(由所有 docs 區塊共用)。預設值 .translation-cache。跨執行重複使用。如果您正在從自訂文件翻譯快取遷移,請封存或刪除它 — cacheDir 會建立自己的 SQLite 資料庫,並且與其他架構不相容。suggest-models 也會將基準測試彙總儲存在 <cacheDir>/benchmark-scores.json 中。該檔案是一個快取,就像目錄的其餘部分一樣,並且不屬於已發布套件的一部分。

git 排除的最佳實踐: ​

  • 排除翻譯快取資料夾的內容(例如,使用 .gitignore 或 .git/info/exclude),以避免提交暫時的快取成品。
  • 保留 cache.db(請勿例行性地刪除它),因為保留 SQLite 快取可避免重新翻譯未變更的區段。這在更新或修改使用 ai-i18n-tools 的軟體時,可節省執行時間和 API 成本。
  • 排除環境檔案和暫存檔案,以避免提交機密和備份。

範例:

init 為預設的 cacheDir 寫入此區塊。當 cacheDir 不同時,這兩行快取會使用該目錄,例如 .i18n-cache/* 和 !.i18n-cache/cache.db。

gitignore
# Cache
.translation-cache/*
!.translation-cache/cache.db
benchmark-scores.json

# Environment
.env
.env.local
.env.*.local

# Temporary files
*.tmp
*.backup.*

docs ​

文件管線區塊陣列。translate-docs 和 sync 的文件階段會依序處理每個區塊。舊版金鑰在載入時仍可接受,並在設定檔可寫入時重新寫入;在新設定中請優先使用目前的名稱。

舊版金鑰目前金鑰 / 行為
documentationsdocs
markdownOutputdocs[].docsOutput
jsonSourcedocs[].docusaurusCatalogDir
頂層 openrouterproviders.openrouter + provider: "openrouter"
features.translateMarkdownfeatures.translateDocs
features.translateJSON已移除(使用 docs[].docusaurusCatalogDir 或 json[])
features.extractUIStrings已移除(extract 在 UI 翻譯之前執行)
glossary.uiGlossary 與 glossary.uiGlossaryFromStringsJson已移除;設定載入失敗。請使用 ui[].uiGlossary(布林值,預設為 true)
ui.reactExtractorui.uiExtractor(別名仍可接受)
svg.svgExtractor.forceLowercasesvg.forceLowercase

內容來源

  • description 此區塊的可選人類可讀註記 (不適用於翻譯)。若已設定,則會加上前綴顯示於 translate-docs 🌐 標題;也會顯示於 status 區段標題。
  • contentPaths 要翻譯的 Markdown/MDX 頁面內文和 .astro 範本 (translate-docs 會掃描這些以尋找 .md、.mdx 和 .astro)。支援 目錄路徑或 glob 模式 (例如 "docs/**/*.md"、"guides/*.mdx"、"src/pages/index.astro")。這就是本地化文件內文的來源。
  • sourceFiles 載入時合併到 contentPaths 的可選別名。
  • targetLocales 此區塊的可選地區設定子集 (否則使用根目錄 targetLocales)。有效的地區設定是跨區塊的聯集。
  • docusaurusCatalogDir 選用。此區塊的 Docusaurus JSON 標籤目錄來源目錄(例如來自 docusaurus write-translations 的 "i18n/en")。頁面內容一律來自 contentPaths;docusaurusCatalogDir 僅提供殼層/UI JSON,不提供 MDX。
  • nextraMetaGlob 選用的萬用字元(glob),用於 docsRoot 下的 Nextra _meta.ts / _meta.tsx / _meta.js。當 docsOutput.style 為 "nextra" 且省略此項時,docsRoot 下的所有 _meta 檔案會自動收集。
  • nextraMetaTranslatableKeys 選用的屬性名稱,其字串值會在 Nextra _meta 物件中翻譯(預設:title、display、breadcrumb)。
  • nextraDictionaryPath 選用的英文 Nextra 主題字典模組(例如 "app/_dictionaries/en.ts")。在 translate-docs 期間翻譯為 {dir}/{locale}.ts。
  • nextraDictionaryOutputTemplate 選用的地區字典模組輸出地區字典模組輸出範本(預設:相對於字典目錄的 {dir}/{locale}.ts)。

docsOutput ​

此區塊的輸出佈局。

  • outputDir 此區塊翻譯輸出的根目錄。
  • docsOutput.style"nested"(預設)、"flat"、"doc-system",或別名 "docusaurus" / "astro-starlight" / "vitepress" / "nextra"。
  • docsOutput.localeSubpath{locale}/ 與 {relativeToDocsRoot} 之間用於 doc-system 的路徑區段(直接使用 style: "doc-system" 時為必填;使用別名時為預設值)。使用 "" 處理 Starlight 風格的地區資料夾。
  • docsOutput.docsRoot Docusaurus 版面配置的來源文件根目錄(例如 "docs")。省略時預設為 "docs"。
  • docsOutput.pathTemplate 自訂 Markdown 輸出路徑。佔位符:"{outputDir}"、"{locale}"、"{LOCALE}"、"{llocale}"、"{relPath}"、"{stem}"、"{basename}"、"{extension}"、"{docsRoot}"、"{relativeToDocsRoot}"。
  • docsOutput.jsonPathTemplate 標籤檔案的自訂 JSON 輸出路徑。支援與 pathTemplate 相同的佔位符。
  • docsOutput.localePathLowercase 當 true 時,內建輸出佈局(nested、flat、doc-system 不含 pathTemplate)在路徑中使用小寫語言環境區段。預設 false;astro-starlight 和 doc-system 在設定載入時,若 localeSubpath 為空,則預設為 true。
  • docsOutput.flatPreserveRelativeDir 當 docsOutput.style = "flat" 時,保留來源子目錄,以便具有相同基本名稱的檔案不會衝突。預設 false。
  • docsOutput.rewriteRelativeLinks 翻譯後重寫相對連結(當 docsOutput.style = "flat" 且沒有自訂 pathTemplate 時自動啟用)。
  • docsOutput.linkRewriteDocsRoot 計算平面連結重寫前綴時使用的儲存庫根目錄。通常將其保留為 ".",除非您的翻譯文件位於不同的專案根目錄下。
  • docsOutput.rewriteVitepressLinks 當 true 時,在翻譯後執行 VitePress 連結正規化器。當 docsOutput.style 為 "vitepress" 時,預設為啟用。適用於任何 doc-system 版面配置,其中語系資料夾位於 docsRoot 下的來源語系檔案旁邊。來源語言是 sourceLocale,可以是任何語言。將 README 樣式的 docs/guide/… 路徑重寫為網站路由 (/guide/…) 和語系相關的 ../guide/… 連結。對於指向 VitePress 樹外部儲存庫檔案 (LICENSE、examples/) 的連結,請在來源語系檔案中使用完整 URL — 請參閱 VitePress 整合 — README 作為文件首頁。
  • docsOutput.rewriteNextraLinks 當 true 時,在翻譯後執行 Nextra 連結正規化器。當 docsOutput.style 為 "nextra" 時,預設為啟用。將 content/en/… 和相對 .mdx 路徑重寫為 Next.js i18n 的語系中立網站路由 (/guide/…)。請參閱 Nextra 整合 — 連結慣例。
  • docsOutput.fumadocsParser"dot"(預設)或 "dir"。點(dot)將 stem.{locale}.mdx 寫在來源語系檔案旁邊;目錄(dir)則像 Nextra 一樣寫入語系資料夾。來源語言是 sourceLocale,可以是任何語言。請參閱 Fumadocs 整合 — 頁面版面配置。
  • docsOutput.rewriteFumadocsLinks 當 true 時,在翻譯後執行 Fumadocs 連結正規化器。當 docsOutput.style 為 "fumadocs" 時,預設為啟用。將內容路徑和相對 .mdx 連結重寫為 /docs/… 路由。
  • docsOutput.fumadocsUiCatalog 選用。Fumadocs UI 覆寫目錄引導 + translate-docs 內的翻譯。欄位:sourcePath(例如 lib/layout.shared.ts)、catalogPath(生成的英文 JSON)、選用 outputPathTemplate(預設:ui.{locale}.json 位於 catalogPath 旁邊)。
  • docs[].fumadocsMetaGlob 當 docsOutput.style 為 "fumadocs" 時,用於 meta.json 集合的選用 glob 模式。預設:docsOutput.docsRoot 下的遞迴 meta.json。
  • docs[].fumadocsMetaTranslatableKeys 在 Fumadocs meta.json 中翻譯其字串值的屬性名稱(預設值:title、description)。
  • docsOutput.localizedAssets 當存在語系檔案時,選擇性重新命名已翻譯 HTML 中的圖片與圖示 URL。欄位:include(預設 img/**)、pattern(預設 {stem}-{locale}{ext})、onlyIfExists(預設 true)、assetRoot(用於測試根相對 URL 的目錄;預設為 HTML 檔案的目錄)。預留位置:{stem}、{ext}、{basename}、{locale}、{llocale}、{LOCALE}。CSS url() 不會被改寫。請參閱 HTML 頁面。
  • docsOutput.html HTML 文件的選擇性語言清單與 hreflang。預設註解為 <!-- ai-i18n:lang-list --> … <!-- /ai-i18n:lang-list --> 與 <!-- ai-i18n:hreflang --> … <!-- /ai-i18n:hreflang -->。languageList.format 為 links 或 select。languageList.label 為 local、english 或 both。hreflang.siteUrl 為替代連結加上前綴;若省略,則連結為相對路徑並會記錄警告。hreflang.xDefault 預設為 sourceLocale。hreflang.stripIndexHtml 會將 index.html 轉換為目錄 URL。對於 HTML,在新增語系資料夾前會先移除 docsRoot(當 docsRoot 為 site 時,site/index.html → site/{locale}/index.html)。請參閱 HTML 頁面。
  • docsOutput.vitepressThemeCatalog 選擇性。VitePress 主題/導覽/側邊欄目錄初始化 + translate-docs 內的翻譯。欄位:configPath(包含主題字串的 VitePress 設定)、catalogPath(產生的英文巢狀 JSON)、選擇性 outputPathTemplate(預設值:catalogPath 旁的 theme.{locale}.json)。

後處理

  • docsOutput.postProcessing 對已翻譯的markdown 內文進行選用轉換(YAML 鍵與非散文式 front matter 值會保留)。於段落重組與連結改寫(平面或 VitePress)之後、addFrontmatter 之前執行。
  • docsOutput.postProcessing.regexAdjustments{ "description"?, "search", "replace" } 的有序列表。search 為正規表示式模式(純字串使用旗標 g,或 /pattern/flags)。replace 支援預留位置,例如 ${translatedLocale}、${sourceLocale}、${sourceFullPath}、${translatedFullPath}、${sourceFilename}、${translatedFilename}、${sourceBasedir}、${translatedBasedir}。
  • docsOutput.postProcessing.languageListBlock{ "start", "end", "separator", "label"? } —— 在來源與已翻譯的 markdown 中重新產生有界的「以其他語言閱讀」連結列。當 label: "local" 時,需要 languagesManifestPath(或位於 ui.flatOutputDir/ui-languages.json 的資訊清單)以提供內名標籤。

行為與中繼資料

  • translateFrontmatterFields 與 docsOutput 位於同一層級(依據 docs[] 區塊)。預設 true:翻譯 Starlight/Docusaurus 的使用者介面 YAML 散文(title、description、sidebar.label、sidebar_label、keywords、hero.title、hero.tagline、hero.image.alt、hero.actions[].text、pagination_label、prev/next 標籤)。設定 false 以保持整個前言區塊不變;傳遞字串陣列以限制為特定的點路徑。
  • segmentSplitting 與 docsOutput 位於同一層級(依據 docs[] 區塊)。用於 translate-docs 提取的選用更細粒度區段:{ "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }。當 enabled 為 true 時(segmentSplitting 省略時的預設值),密集段落、GFM 管道表格(第一個區塊包含標頭、分隔符號和第一個資料列)和長清單會被分割;子部分會以單一換行符號(tightJoinPrevious)重新連接。設定 "enabled": false 以僅使用每個以空白行分隔的主體區塊的一個區段。當 qualityRetrySplit 為 true 時(預設值),在模型清單停止後 AST 驗證失敗的 Markdown 區段會逐步分割並從第一個模型重試。當相同的品質錯誤發生三次時,清單會提前停止。maxQualityRetrySplitDepth(預設 3)限制遞迴分割。
  • warnMarkdownSourceIssues 當 true 時(省略時的預設值),每次 translate-docs 執行都會重新掃描 Markdown 區段,以查找危險的分隔符號/未閉合的行內程式碼,列印終端警告,並替換該檔案快取檔案路徑的 markdown_source_issues 列。設定 false 以跳過此區塊的警告和 SQLite 更新。
  • addFrontmatter 當 true 時(省略時的預設值),翻譯的 Markdown 檔案會包含 YAML 鍵:translation_last_updated、source_file_mtime、source_file_hash、translation_language、source_file_path,並且當至少一個區段具有模型中繼資料時,還會包含 translation_models(來自活動提供者的模型 ID 排序清單)。設定為 false 以跳過。
  • emphasisPlaceholders 每個 docs[] 區塊。當 true 時,在翻譯前將 markdown 強調分隔符遮罩為佔位符。對於 CJK 語言環境(zh、ja、ko)和 rtlLocales 中列出的語言環境,預設為 true;否則預設為 false。可透過 CLI --emphasis-placeholders / --no-emphasis-placeholders 覆寫。
  • rtlLocales BCP-47 代碼的可選陣列,被視為 RTL 以用於強調佔位符預設值(與內建 RTL 偵測合併)。

  • protectAttributes 可選。額外的 JSX/HTML 屬性名稱,其 引用的字串值不得發送給翻譯器。與內建預設值合併(class、id、style、src、href、type、data-*、大多數 aria-* 等)。不區分大小寫。適用於:

  • .astro 的解析替換提取(靜態 HTML 標籤和 attr= 後的字串文字,位於 {expression} 區塊內)。

    • Markdown/Astro 區段翻譯期間的 MDX 佔位符提取(label、tooltip 和大寫 JSX 標籤上的 aria-label,以及適用的 TabItem value)。

範例:"protectAttributes": ["variant", "size"] 在不同地區設定下保持 variant="primary" 在 {items.map(...)} 中不變。

您也可以列出正常翻譯的屬性(例如 "title" 或 "aria-label"),當您希望這些值從英文逐字複製時。

  • protectKeys 可選。額外的 物件屬性名稱,其引用的字串值在模板 {expression} 區塊和 MDX 物件文字(例如 label: 在 <Tabs values={[ … ]}> 中)內不得翻譯。與內建預設值合併(class、key、id、href、src 等)。不區分大小寫。

範例:"protectKeys": ["slug", "code"] 跳過 { slug: 'getting-started', title: 'Getting started' } → 當 slug 被保護時,只有 title 會被翻譯。


範例(docsOutput.style = "flat" — 螢幕截圖路徑 + 可選語言列表包裝器):

平面佈局後處理範例(螢幕截圖 + languageListBlock)
json
"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ],
    "languageListBlock": {
      "start": "<small id=\"lang-list\">",
      "end": "</small>",
      "separator": " · ",
      "label": "local"
    }
  }
}

json ​

巢狀 JSON 翻譯管道的頂層陣列。僅在 features.translateJson 為 true 時使用(translate-json 或 sync 的 JSON 階段)。請參閱 JSON。

欄位描述
descriptionCLI / status 的可選註釋(不翻譯)。
contentPaths專案根目錄下的來源 .json 檔案、目錄或 glob 模式。支援典型的 i18next 命名空間檔案(public/locales/en/*.json):巢狀物件、陣列、字串值中的 {{var}} 插值,以及獨立的複數後綴鍵(key_one、key_other)。
outputPathTemplate每個目標地區設定必需的輸出路徑。佔位符:{locale}、{LOCALE}、{llocale}、{stem}、{basename}、{extension}、{relativeToSourceRoot}。
targetLocales此區塊的可選子集;否則為根目錄的 targetLocales。
keyPolicy.modeallowlist、denylist 或 both。
keyPolicy.translateKeys模式為 allowlist 或 both 時要包含的點路徑 / glob 模式。
keyPolicy.skipKeys要排除的點路徑 / glob 模式(預設拒絕列表包含 id、slug、href、url、key、code)。

svg ​

SVG 檔案的頂層路徑和佈局。僅當 features.translateSVG 為 true 時(透過 translate-svg 或 sync 的 SVG 階段)執行翻譯。

欄位說明
sourcePath一個或多個目錄 或 glob 模式(例如 "images/*.svg"、"**/icons/*.svg")。模式相對於專案根目錄解析,並遞迴掃描以尋找 .svg 檔案。
outputDir已翻譯 SVG 輸出的根目錄。
style當 pathTemplate 未設定時為 "flat" 或 "nested"。
pathTemplate自訂 SVG 輸出路徑。佔位符:"{outputDir}"、"{locale}"、"{LOCALE}"、"{llocale}"、"{relPath}"、"{stem}"、"{basename}"、"{extension}"、"{relativeToSourceRoot}"。
localePathLowercase當 true 為 true 時,內建的 flat / nested SVG 佈局會使用小寫的地區設定區段。自訂 pathTemplate 值保持不變;請使用 {llocale} 來進行小寫區段。
forceLowercase在重新組合 SVG 時將翻譯後的文字轉為小寫。對於依賴全小寫標籤的設計很有用。

modelSuggestion(選用) ​

ChrF 和 Arena 權重,以及一個可選的品質下限,適用於 suggest-models 和 儀表板的「模型」分頁。索引僅限於品質。省略此區塊,或省略其中一個設定檔,該設定檔將保留內建權重。此區塊不會被 --apply 或 更新設定 重寫;這些只會寫入模型 ID。當載入設定時,設定檔上的舊版 price 權重將會移除。

  • quality — 預設 ChrF 0.55、Arena 0.45、品質下限 0.7
  • price — 預設 ChrF 0.55、Arena 0.45、品質下限 0.6

每個設定檔物件都需要 chrf 和 arena。每個值都是有限的,且至少為 0,且至少有一個大於 0。它們會被正規化,使其總和為 1,因此 55 和 45 會符合預設值。qualityFloor 是可選的,範圍為 (0, 1],並且是候選池中最佳 ChrF 的分數。低於下限的模型,包括任何沒有 ChrF 測量的模型,會排在清除下限的模型之後。這兩個設定檔共用相同的預設組合;它們在排序順序(--quality 依索引,--price 依帕累托前沿)和下限上有所不同。

json
"modelSuggestion": {
  "quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
  "price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}

glossary ​

欄位說明
userGlossaryCSV 檔案的路徑,該檔案包含 Original language string(或 en)、locale、Translation、選用的 Force 及選用的 Context 欄位 - 每個來源詞彙與目標地區設定各佔一行(對於所有目標,locale 可為 *)。
autoAddUserEditedToGlossary當 true 時,對 UI 字串的儀表板編輯可以自動附加到使用者詞彙表中。
contextFiles選填的、相對於 cwd 的 Markdown 或純文字檔案(.md、.markdown、.txt),包含產品或功能說明。於指令啟動時載入,並注入至 UI、文件、JSON、SVG 及校對提示詞中。除非您也希望翻譯這些檔案,否則請勿將其置於 docs[].contentPaths。URL 會被拒絕。完整文字會傳送至已配置的 LLM 供應商,並可能出現在 --debug-failed 日誌中 — 請勿包含機密資訊或個人識別資訊(PII)。
contextMaxChars傳送至模型的串接上下文檔案文字之最大字元數(預設 12000,上限 100000)。超出部分會被截斷並發出警告。
labelCheckSkips要跳過的鎖定 UI 標籤檢查的選用清單。每個條目包含 term(英文詞彙表術語)、locales(目標代碼,或 * 代表每個地區設定;預設 *)、選用 files(cwd 相對 glob 模式),以及選用 note。該術語仍作為提示線索。下一次 translate-docs 執行時會應用跳過。

translate-docs、translate-json 和 translate-svg 也會從 uiGlossary 為 true(預設值)的每個 UI 區塊取得提示。這會重複使用已儲存在該區塊 strings.json 中的翻譯。在區塊上將 uiGlossary 設為 false 即可將其排除。translate-ui 和 proofread-ui 不會使用這些目錄作為提示。精簡的 UI 標籤縮寫(例如 Alm. 等尾端帶點格式,或 Size → Tam 等簡短單詞元壓縮格式)會被略過,以免文件提示被引導至虛構的 {{…}} 詞元。完整的產品詞彙與未縮寫的 UI 翻譯仍會作為提示。

選用 Context CSV 欄位是該術語的來源語言使用指南(定義、語法用途、產品含義)。僅當該術語與當前批次匹配時才包含它。更改術語的 Context 備註或任何 contextFiles 內容會使匹配地區設定的快取區段和檔案追蹤列在下次執行時失效,因此翻譯會自動重新整理。僅更改非強制列上的首選 Translation 仍會使用現有快取,除非您傳遞 --force / --force-update。當儲存的文字尚未包含強制翻譯時,Force 列只會遺漏其來源包含該術語的區段。儀表板使用者編輯的快取列會被保留。當共享的多詞前綴是首字母大寫的標籤(至少兩個內容詞)且共享翻譯是沒有佔位符的短語時,UI 目錄也會將其作為自己的術語。當來源將其引用為整個粗體或行內程式碼範圍、標題或僅為該標籤的行時,Markdown 翻譯需要一個二到五個詞的 UI 標籤來保留其目錄翻譯。僅包含該術語的較長粗體短語是一個提示。句子中的標題大小寫是一個提示,因此翻譯可以變形(印地語 Cursor account 可能會變成 कर्सर खाते 而不是字典形式 कर्सर खाता)。帶有單個內容詞的標籤,例如 Sign in,仍是一個提示。該檢查會忽略大小寫。它仍然要求目錄措辭作為子字串,因此語法變形可能會失敗。該失敗是一個警告:該區段會被寫入,以詞彙表標籤旗標快取,並在執行結束時列在 glossary-review-*.md 的 cacheDir 下。審閱後,新增一個 labelCheckSkips 條目,或傳遞 --recheck-glossary-warnings。--force 會重新翻譯帶有旗標的列以及所有其他區段。

範例:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md", "i18n/billing-feature.md"],
    "contextMaxChars": 12000,
    "labelCheckSkips": [
      {
        "term": "Target language",
        "locales": ["uk"],
        "files": ["website/src/content/docs/docs/transform.md"],
        "note": "Inflected inside a bold phrase"
      }
    ]
  }
}

產生一個空的詞彙表 CSV:

bash
ai-i18n-tools glossary-generate

若要從儲存庫草擬 contextFiles,請使用 透過 AI 代理程式產生上下文檔案 中的複製貼上代理程式提示。如需了解如何套用術語列與上下文檔案,請參閱 術語表。

採用 MIT 授權條款釋出。