配置参考
sourceLocale
源语言的 BCP-47 代码(例如 "en-GB"、"pt-BR" 或 "ja")。任何语言都有效。示例中出现英语是因为许多项目都从英语开始。不会为此区域设置生成翻译文件——键字符串本身就是源文本。
必须匹配从您的运行时 i18n 设置文件(SOURCE_LOCALE / src/i18n.ts)导出的 src/i18n.js。
targetLocales
要翻译的 BCP-47 区域设置代码数组(例如 ["de", "fr", "es", "pt-BR"])。
targetLocales 是 UI 翻译的主要区域设置列表,也是文档块的默认区域设置列表。使用 generate-ui-languages 从 ui-languages.json + sourceLocale 构建 targetLocales 清单。
uiLanguage (可选)
工具自身 UI 语言(CLI 帮助、日志/摘要和翻译仪表板)的 BCP-47 代码。它独立于 sourceLocale / targetLocales,并会被 -L / --ui-lang 标志和 AI_I18N_LANG 环境变量覆盖。未知值会平滑降级到源区域设置(en-GB)——没有严格的验证。参见工具 UI 语言。
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 对 UI 翻译使用 4,对文档翻译使用 3(内置默认值)。每次运行可通过 -j / --concurrency 覆盖。
batchConcurrency(可选)
translate-docs、translate-svg 和 translate-json(以及 sync 中的匹配步骤):每个文件的最大并行 LLM batch 请求(每个批次可包含多个片段)。省略时默认为 4。不适用于 translate-ui —— 请改用 uiBatchConcurrency。使用 -b / --batch-concurrency 覆盖。
uiBatchConcurrency(可选)
translate-ui、sync-ui 和 sync 的 UI 步骤:在单个语言环境内的最大并行 LLM batch 请求(50 个纯字符串块,然后是复数组)。省略时默认为 2。独立于 concurrency(并行目标语言环境)和 batchConcurrency(文档/JSON/SVG)。无 CLI 标志;在配置中设置或向编程式 runTranslateUI 传递 uiBatchConcurrency。
示例:
{
"uiBatchConcurrency": 2
}在默认语言环境并发数为 4 的情况下,最多可有 8 个正在进行的 UI API 调用。在翻译一个大型语言环境时调高此值 (-l de);如果提供商有速率限制则保持较低值。
fileConcurrency(可选)
在 translate-docs 和 sync 期间,并发处理单个区域设置内文件的最大数量 within a single locale。当设置为大于 1 的值时,同一区域设置内的文件将使用信号量并行处理以控制内存使用。省略时默认为 1(顺序处理)。更高的值可以显著提高 I/O 密集型操作的吞吐量,尤其是在所有片段都已缓存(无需 API 调用)的情况下。
示例:
{
"fileConcurrency": 4
}用例: 当 sync --force-update 以 100% 缓存命中率运行时,将此值设置为 2-4 以减少总处理时间。当文件数量很多且较小时,效果最明显。
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(可选) 用于translate-ui、复数生成(步骤 0 和 Pass 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。当此提供商和顶层配置均未设置超时时,默认值为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 列表价格(输入和输出每百万令牌美元价格)。
存储时没有成本的记录稍后可以通过 usage 和 使用情况和成本 估算。如果这些来源都不适用,则成本保持未知(—),绝不会是 $0.00。
modelPricing(可选) 每模型每百万令牌美元价格:{ "<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 条目),报告缺失或已过 expiration_date 的 ID,列出有效模型,并在任何已配置的 ID 无效时以非零状态退出。当提供商返回定价信息时(例如 OpenRouter),它还会显示估算的输入/输出价格(每 100 万 token 的美元费用)。
要在实际翻译任务中比较已配置的模型,请运行 ai-i18n-tools bench-models。它会通过将一个样本分别独立翻译(并行执行,受 concurrency 限制)来对 translationModels、uiModels 和 localeModels 中的每个唯一模型 ID 进行基准测试,并打印每个模型的输入/输出 token 数、实际耗时和美元成本,以便你在确定模型列表之前权衡速度与价格。
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和源代码 linting 仅使用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 还会将捆绑的 ui-languages 主目录 (由 sourceLocale + 块的有效 targetLocales 构建) 中的每个 englishName 添加到 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。nextraMetaGlobdocsRoot下 Nextra_meta.ts/_meta.tsx/_meta.js的可选 glob。当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.localeSubpathdoc-system的{locale}/和{relativeToDocsRoot}之间的路径段(直接使用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 值会被保留)。在片段重组和链接重写(flat 或 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设置为保持整个 front matter 块不变;传递一个字符串数组以限制为特定的点路径。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 | "flat" 或 "nested"(当 pathTemplate 未设置时)。 |
pathTemplate | 自定义 SVG 输出路径。占位符:"{outputDir}"、"{locale}"、"{LOCALE}"、"{llocale}"、"{relPath}"、"{stem}"、"{basename}"、"{extension}"、"{relativeToSourceRoot}"。 |
localePathLowercase | 当 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(相对于当前工作目录的 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 智能体生成上下文文件 中的复制粘贴智能体提示词。有关如何应用术语行和上下文文件,请参阅术语表。