設定參考

`sourceLocale`

來源語言的 BCP-47 代碼（例如 "en-GB"、"en"、"pt-BR"）。此語系不會產生翻譯檔案——鍵值字串本身即為來源文字。

必須符合 從您的執行階段 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 之下）。extract 與 generate-ui-languages 寫入 ui-languages.json 資訊清單的路徑，CLI 亦從此路徑讀取以取得顯示名稱及進行語言列表後處理。省略時，預設為 ui.flatOutputDir/ui-languages.json，於設定載入時生效。

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

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

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

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

`concurrency`（可选）

同時翻譯的最大目標語系數量（translate-ui、translate-docs、translate-svg，以及 sync 內對應的步驟）。若省略，CLI 會在 UI 翻譯時使用 4，在文件翻譯時使用 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 為毫秒。預設值：當兩者皆省略時為 45 秒。僅設定其中一項。若供應商設定了其中任一欄位，則僅對該供應商使用該值。

`provider` 和 `providers`

provider（頂層，選填）從 providers 中選取作用中的提供者金鑰。當僅設定一個提供者時為選填；當設定多個提供者時為必要。

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

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

translationModels 模型 ID 的首選有序列表（純上游 ID，無 provider/ 前綴；OpenRouter ID 保留其原生 vendor/model 形式）。第一個優先嘗試；後續條目在出錯時作為備用。這是每個管道的全局預設鏈，當沒有更具體的層級適用時。
uiModels (可選) 用於 translate-ui、複數生成（步驟 0 和階段 B）和 proofread-ui 的僅限 UI 的有序模型列表。在目標語言環境的任何匹配 localeModels 條目之後，translationModels 之前嘗試。
localeModels (可選) 所有翻譯管道的每個語言環境覆寫。{ "locale": "<BCP-47>", "models": ["…"] } 物件陣列。語言環境標籤不區分大小寫匹配（pt-br = pt-BR）。每個語言環境的列表僅針對該語言環境優先嘗試，然後是管道特定的層級（UI 為 uiModels）和 translationModels。在配置載入時拒絕重複的標準化語言環境鍵。
baseUrl 與 OpenAI 相容的基礎 URL。覆寫預設的基礎 URL；非預設提供者需要此項。
apiKeyEnv 儲存 API 金鑰的環境變數。覆寫預設的環境變數。
headers 每次向此提供者發送請求時傳送的額外 HTTP 標頭。
maxTokens 每個請求的最大完成權杖數。預設值：8192。
temperature 取樣溫度。預設值：0.2。
requestTimeout 向此供應商發送每個請求時等待的最長時間（以秒為單位）。覆寫頂層 requestTimeout / requestTimeoutMs。若此供應商與頂層設定皆未設定逾時，預設為 45 秒。在同一物件上僅能設定 requestTimeout 或 requestTimeoutMs 其中之一。
requestTimeoutMs 向此供應商發送每個請求時等待的最長時間（以毫秒為單位）。覆寫頂層 requestTimeout / requestTimeoutMs。若此供應商與頂層設定皆未設定逾時，預設為 45000（45 秒）。在同一物件上僅能設定 requestTimeout 或 requestTimeoutMs 其中之一。
pricing（選用）供應商層級每 1,000,000 個 token 的美元費用：{ "inputPerMTokens": 0.15, "outputPerMTokens": 0.6 }。當計費呼叫沒有供應商回報的 usage.cost 時（OpenRouter 以外的大多數供應商），此費率將套用至該呼叫的輸入與輸出 token。此金額會包含在翻譯摘要中，並儲存在 api_calls 列。相符的 modelPricing 項目會覆寫此預設值。供應商回報的成本絕不會被取代。儲存時未包含成本的列，稍後仍可透過 usage 與使用量與成本進行估算。
modelPricing（選用）每個模型每 1,000,000 個 token 的美元費用：{ "<model-id>": { "inputPerMTokens": 2.5, "outputPerMTokens": 10 } }。覆寫該模型 ID 的 pricing。當供應商省略 usage.cost 時，會在呼叫時套用，並與該呼叫一起儲存。

內建提供者預設值（金鑰 — 基本 URL — API 金鑰環境變數）：

提供者	基本 URL	API 金鑰環境變數
`openrouter`	`https://openrouter.ai/api/v1`	`OPENROUTER_API_KEY`
`openai`	`https://api.openai.com/v1`	`OPENAI_API_KEY`
`anthropic`	`https://api.anthropic.com/v1`	`ANTHROPIC_API_KEY`
`gemini`	`https://generativelanguage.googleapis.com/v1beta/openai`	`GOOGLE_API_KEY`
`deepseek`	`https://api.deepseek.com`	`DEEPSEEK_API_KEY`
`cerebras`	`https://api.cerebras.ai/v1`	`CEREBRAS_API_KEY`
`groq`	`https://api.groq.com/openai/v1`	`GROQ_API_KEY`
`mistral`	`https://api.mistral.ai/v1`	`MISTRAL_API_KEY`
`xai`	`https://api.x.ai/v1`	`XAI_API_KEY`
`nvidia`	`https://integrate.api.nvidia.com/v1`	`NVIDIA_API_KEY`
`alibaba`	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	`ALIBABA_API_KEY`
`apifun`	`https://api.apikey.fun/v1`	`APIFUN_API_KEY`
`ollama`	`http://localhost:11434/v1`	(無)

舊版頂層 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 可以嘗試下一個模型。

將以下列表視為您可以擴展的基準：如果特定語言環境的翻譯品質不佳或不成功，請研究哪些模型能有效支援該語言或文字（參考線上資源或您的提供者文件），並將這些模型 ID 添加為進一步的替代方案。

這些模型 ID 在 -P openrouter（預設值）時符合 ai-i18n-tools init [-P <provider>]。其他預設集從 init -P <provider> 取得原生模型 ID——請參閱內建提供者。

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

範例 translationModels（與 ai-i18n-tools init [-P <provider>] 相同的預設值）：

預設翻譯模型備用列表

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`

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

翻譯 SVG 檔案，當 features.translateSVG 為 true 且設定了頂層 svg 區塊時，使用 translate-svg。sync 命令會在兩者都設定時執行該步驟（除非設定了 --no-svg）。

`ui`

sourceRoots
掃描 t("…") 呼叫的目錄或全域模式（相對於目前工作目錄）。支援 src/ 或 ["src/**/*.ts"] 等模式。
stringsJson
主目錄檔案的路徑。由 extract 更新。
flatOutputDir
寫入每個語言環境 JSON 檔案的目錄（de.json 等）。
uiExtractor.funcNames（或舊版 reactExtractor.funcNames）
要掃描的其他函數名稱（預設值：["t", "i18n.t"]）。
uiExtractor.extensions（或舊版 reactExtractor.extensions）
要包含的檔案副檔名（預設值：[".js", ".jsx", ".ts", ".tsx"]）。為 Astro 前置內容和模板表達式新增 .astro。
uiExtractor.includePackageDescription（或舊版 reactExtractor.includePackageDescription）
當 true（預設）時，extract 也會將 package.json description 作為 UI 字串包含在內（如果存在）。
uiExtractor.packageJsonPath（或舊版 reactExtractor.packageJsonPath）
用於該可選描述提取的 package.json 檔案的自訂路徑。
uiExtractor.includeUiLanguageEnglishNames（或舊版 reactExtractor.includeUiLanguageEnglishNames）

當 true（預設 false）時，extract 亦會將內建 ui-languages 主目錄（由 sourceLocale + targetLocales 建構）中的每個 englishName 加入 strings.json，前提是來源掃描中尚未存在該項（使用相同雜湊鍵）。不會讀取 languagesManifestPath。

`cacheDir`

cacheDir SQLite 快取目錄（所有 docs 區塊共用）。預設 .translation-cache。跨執行重複使用。如果您正在從自訂文件翻譯快取遷移，請封存或刪除它 — cacheDir 會建立自己的 SQLite 資料庫，並且與其他架構不相容。

git 排除的最佳實踐：

排除翻譯快取資料夾的內容（例如，使用 .gitignore 或 .git/info/exclude），以防止提交臨時快取偽影。
保留 cache.db（不要例行刪除它），因為保留 SQLite 快取可以防止重新翻譯未變更的區段。這在更新或修改使用 ai-i18n-tools 的軟體時，可以節省執行時間和 API 成本。
排除臨時檔案和日誌檔案，以避免提交備份和除錯相關檔案。

範例：

gitignore

# Translation cache directory
.translation-cache/*

# Keep SQLite cache for reuse
!.translation-cache/cache.db

# Temporary and log files
*.tmp
*.log

`docs`

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

舊版金鑰	目前金鑰 / 行為
`documentations`	`docs`
`markdownOutput`	`docs[].docsOutput`
`jsonSource`	`docs[].docusaurusCatalogDir`
頂層 `openrouter`	`providers.openrouter` + `provider: "openrouter"`
`features.translateMarkdown`	`features.translateDocs`
`features.translateJSON`	已移除（使用 `docs[].docusaurusCatalogDir` 或 `json[]`）
`features.extractUIStrings`	已移除（`extract` 在 UI 翻譯之前執行）
`glossary.uiGlossaryFromStringsJson`	`glossary.uiGlossary`
`ui.reactExtractor`	`ui.uiExtractor`（別名仍可接受）
`svg.svgExtractor.forceLowercase`	`svg.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）。

輸出佈局

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 之下。會將 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 的語系資料夾。請參閱 Fumadocs 整合 — 頁面佈局。
docsOutput.rewriteFumadocsLinks 當 true 時，在翻譯後執行 Fumadocs 連結正規化工具。當 docsOutput.style 為 "fumadocs" 時預設為啟用。將內容路徑和相對 .mdx 連結重寫為 /docs/… 路由。
docsOutput.fumadocsUiCatalog 選用。在 translate-docs 內進行 Fumadocs UI 覆寫目錄啟動程序 + 翻譯。欄位：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.vitepressThemeCatalog 選填。在 translate-docs 內的 VitePress 主題/導覽/側邊欄目錄啟動程序 + 翻譯。欄位：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。

欄位	描述
`description`	CLI / `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.mode`	`allowlist`、`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 時將翻譯後的文字轉為小寫。對於依賴全小寫標籤的設計很有用。

`glossary`

欄位	說明
`uiGlossary`	指向 `strings.json` 的路徑 - 會從現有翻譯自動建構詞彙表。
`userGlossary`	CSV 檔案路徑，包含欄位 `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`）。超出部分會被截斷並發出警告。

translate-docs 使用相同的詞彙表來提供術語提示，但會跳過精簡的 UI 標籤縮寫（帶有結尾句點的形式，例如 Alm.，或是簡短的單一標記壓縮，例如 Size → Tam），以免文件提示被引導至虛構的 {{…}} 標記。完整的產品術語與非縮寫的 UI 翻譯仍會提供提示。

選填的 Context CSV 欄位為該詞彙的來源語言用法指引（定義、語法用途、產品含義）。僅在詞彙符合目前批次時才會納入。變更詞彙的 Context 註記或任何 contextFiles 內容，會使下一次執行時相符地區的快取區段與檔案追蹤列失效，因此翻譯會自動重新整理。僅變更偏好的 Translation 仍會使用現有快取，除非您傳入 --force / --force-update。儀表板中使用者編輯過的快取列會予以保留。

範例：

json

{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md", "i18n/billing-feature.md"],
    "contextMaxChars": 12000
  }
}

產生一個空的詞彙表 CSV：

bash

ai-i18n-tools glossary-generate

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

翻譯類型

UI 字串

文件

SVG

整合

圖片與螢幕截圖

翻譯儀表板

CLI 指令

設定參考

`sourceLocale`

`targetLocales`

`uiLanguage` (選用)

`languagesManifestPath`（選用）

`concurrency`（可选）

`batchConcurrency`（可选）

`uiBatchConcurrency`（選用）

`fileConcurrency`（選填）

`batchSize` / `maxBatchChars`（選填）

`requestTimeout` / `requestTimeoutMs`（選填）

`provider` 和 `providers`

`features`

`ui`

`cacheDir`

git 排除的最佳實踐：

`docs`

`json`

`svg`

`glossary`

UI 字串

文件

SVG

設定參考 ​

sourceLocale ​

targetLocales ​

uiLanguage (選用) ​

languagesManifestPath（選用） ​

concurrency（可选） ​

batchConcurrency（可选） ​

uiBatchConcurrency（選用） ​

fileConcurrency（選填） ​

batchSize / maxBatchChars（選填） ​

requestTimeout / requestTimeoutMs（選填） ​

provider 和 providers ​

features ​

ui ​

cacheDir ​

git 排除的最佳實踐： ​

docs ​

json ​

svg ​

glossary ​

設定參考

`sourceLocale`

`targetLocales`

`uiLanguage` (選用)

`languagesManifestPath`（選用）

`concurrency`（可选）

`batchConcurrency`（可选）

`uiBatchConcurrency`（選用）

`fileConcurrency`（選填）

`batchSize` / `maxBatchChars`（選填）

`requestTimeout` / `requestTimeoutMs`（選填）

`provider` 和 `providers`

`features`

`ui`

`cacheDir`

git 排除的最佳實踐：

`docs`

`json`

`svg`

`glossary`