Skip to content

配置参考 ​

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。

示例:

json
{
  "uiBatchConcurrency": 2
}

在默认语言环境并发数为 4 的情况下,最多可有 8 个正在进行的 UI API 调用。在翻译一个大型语言环境时调高此值 (-l de);如果提供商有速率限制则保持较低值。


fileConcurrency(可选) ​

在 translate-docs 和 sync 期间,并发处理单个区域设置内文件的最大数量 within a single locale。当设置为大于 1 的值时,同一区域设置内的文件将使用信号量并行处理以控制内存使用。省略时默认为 1(顺序处理)。更高的值可以显著提高 I/O 密集型操作的吞吐量,尤其是在所有片段都已缓存(无需 API 调用)的情况下。

示例:

json
{
  "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 行。

成本来源按以下顺序解析:

  1. 匹配的 modelPricing 条目(覆盖此提供者默认值);
  2. 提供者报告的成本(从不替换);
  3. 此 pricing 费率;
  4. 该模型 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 密钥环境变量):

提供商基础 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 条目),报告缺失或已过 expiration_date 的 ID,列出有效模型,并在任何已配置的 ID 无效时以非零状态退出。当提供商返回定价信息时(例如 OpenRouter),它还会显示估算的输入/输出价格(每 100 万 token 的美元费用)。

要在实际翻译任务中比较已配置的模型,请运行 ai-i18n-tools bench-models。它会通过将一个样本分别独立翻译(并行执行,受 concurrency 限制)来对 translationModels、uiModels 和 localeModels 中的每个唯一模型 ID 进行基准测试,并打印每个模型的输入/输出 token 数、实际耗时和美元成本,以便你在确定模型列表之前权衡速度与价格。


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 和源代码 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.json description 作为 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.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。
  • 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.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 值会被保留)。在片段重组和链接重写(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 覆盖。
  • 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"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 — 默认 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 ​

字段描述
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 会重新翻译带有标志的行以及所有其他分段。

示例:

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 许可证发布。