設定參考
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。
範例:
{
"uiBatchConcurrency": 2
}在預設語系並行數 4 的情況下,這表示最多可有 8 個進行中的 UI API 呼叫。翻譯單一大型語系(-l de)時可提高此值;若供應商有速率限制則保持較低的值。
fileConcurrency(選填)
在單一地區內,於 translate-docs 和 sync 期間可同時處理的檔案數目。當設定為大於 1 的值時,同一地區內的檔案會使用訊號量(semaphore)來控制記憶體使用量,並以平行方式處理。預設值為 1(循序處理),若省略則使用預設值。較高的值可顯著提高 I/O 繫結操作的輸送量,特別是當所有區段都已快取(無需 API 呼叫)時。
範例:
{
"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列。
費用來源依此順序解析:
- 匹配的
modelPricing項目 (覆寫此提供者預設值); - 提供者報告的費用 (永不取代);
- 此
pricing費率; - 該模型 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 金鑰環境變數):
| 供應商 | 基礎 URL | API 金鑰環境變數 |
|---|---|---|
alibaba | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 | ALIBABA_API_KEY |
anthropic | https://api.anthropic.com/v1 | ANTHROPIC_API_KEY |
apikeyfan | https://api.apikey.fan/v1 | APIKEYFAN_API_KEY |
cerebras | https://api.cerebras.ai/v1 | CEREBRAS_API_KEY |
cheaperinference | https://api.cheaperinference.com/v1 | CHEAPERINFERENCE_API_KEY |
deepseek | https://api.deepseek.com | DEEPSEEK_API_KEY |
gemini | https://generativelanguage.googleapis.com/v1beta/openai | GOOGLE_API_KEY |
groq | https://api.groq.com/openai/v1 | GROQ_API_KEY |
mistral | https://api.mistral.ai/v1 | MISTRAL_API_KEY |
nvidia | https://integrate.api.nvidia.com/v1 | NVIDIA_API_KEY |
ollama | http://localhost:11434/v1 | (無) |
openai | https://api.openai.com/v1 | OPENAI_API_KEY |
openrouter | https://openrouter.ai/api/v1 | OPENROUTER_API_KEY |
xai | https://api.x.ai/v1 | XAI_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 翻譯模型清單
"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
"uiModels": [
"~anthropic/claude-sonnet-latest",
"z-ai/glm-5.2"
]亞洲語言的建議 localeModels: 日文、韓文與中文地區通常受益於針對這些文字調整過的模型。新增按地區的覆寫設定,當目標地區相符時,會優先嘗試(在 uiModels / translationModels 之前):
用於 ja、ko、zh-Hans、zh-Hant 的建議 localeModels
"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 / .html / .htm 頁面;已設定 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 區塊)。 |
當鍵被省略時,每個旗標預設為 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.jsondescription作為 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.excludeMinimatch 模式,相對於專案根目錄,在掃描後捨棄。bin、obj、.vs、TestResults和packages已依目錄名稱跳過。ui-dotnet和ui-dotnet-resx範本會排除**/Tests/**、**/*.Tests/**和**/TrExtension.cs。
不再接受 glossary.uiGlossary 和 glossary.uiGlossaryFromStringsJson。設定載入會失敗,且錯誤會說明取代方式:刪除該索引鍵。提示現在來自每個區塊的 uiGlossary 旗標(預設 true)。
cacheDir
cacheDirSQLite 快取目錄(由所有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。
# Cache
.translation-cache/*
!.translation-cache/cache.db
benchmark-scores.json
# Environment
.env
.env.local
.env.*.local
# Temporary files
*.tmp
*.backup.*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.uiGlossary 與 glossary.uiGlossaryFromStringsJson | 已移除;設定載入失敗。請使用 ui[].uiGlossary(布林值,預設為 true) |
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)。
docsOutput
此區塊的輸出佈局。
outputDir此區塊翻譯輸出的根目錄。docsOutput.style"nested"(預設)、"flat"、"doc-system",或別名"docusaurus"/"astro-starlight"/"vitepress"/"nextra"。docsOutput.localeSubpath{locale}/與{relativeToDocsRoot}之間用於doc-system的路徑區段(直接使用style: "doc-system"時為必填;使用別名時為預設值)。使用""處理 Starlight 風格的地區資料夾。docsOutput.docsRootDocusaurus 版面配置的來源文件根目錄(例如"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.jsi18n的語系中立網站路由 (/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在 Fumadocsmeta.json中翻譯其字串值的屬性名稱(預設值:title、description)。docsOutput.localizedAssets當存在語系檔案時,選擇性重新命名已翻譯 HTML 中的圖片與圖示 URL。欄位:include(預設img/**)、pattern(預設{stem}-{locale}{ext})、onlyIfExists(預設true)、assetRoot(用於測試根相對 URL 的目錄;預設為 HTML 檔案的目錄)。預留位置:{stem}、{ext}、{basename}、{locale}、{llocale}、{LOCALE}。CSSurl()不會被改寫。請參閱 HTML 頁面。docsOutput.htmlHTML 文件的選擇性語言清單與 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覆寫。rtlLocalesBCP-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,以及適用的TabItemvalue)。
- Markdown/Astro 區段翻譯期間的 MDX 佔位符提取(
範例:"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)
"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 時將翻譯後的文字轉為小寫。對於依賴全小寫標籤的設計很有用。 |
modelSuggestion(選用)
ChrF 和 Arena 權重,以及一個可選的品質下限,適用於 suggest-models 和 儀表板的「模型」分頁。索引僅限於品質。省略此區塊,或省略其中一個設定檔,該設定檔將保留內建權重。此區塊不會被 --apply 或 更新設定 重寫;這些只會寫入模型 ID。當載入設定時,設定檔上的舊版 price 權重將會移除。
quality— 預設 ChrF0.55、Arena0.45、品質下限0.7price— 預設 ChrF0.55、Arena0.45、品質下限0.6
每個設定檔物件都需要 chrf 和 arena。每個值都是有限的,且至少為 0,且至少有一個大於 0。它們會被正規化,使其總和為 1,因此 55 和 45 會符合預設值。qualityFloor 是可選的,範圍為 (0, 1],並且是候選池中最佳 ChrF 的分數。低於下限的模型,包括任何沒有 ChrF 測量的模型,會排在清除下限的模型之後。這兩個設定檔共用相同的預設組合;它們在排序順序(--quality 依索引,--price 依帕累托前沿)和下限上有所不同。
"modelSuggestion": {
"quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
"price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}glossary
| 欄位 | 說明 |
|---|---|
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)。超出部分會被截斷並發出警告。 |
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 會重新翻譯帶有旗標的列以及所有其他區段。
範例:
{
"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:
ai-i18n-tools glossary-generate若要從儲存庫草擬 contextFiles,請使用 透過 AI 代理程式產生上下文檔案 中的複製貼上代理程式提示。如需了解如何套用術語列與上下文檔案,請參閱 術語表。