JSON

专为将 UI 文本保存在每个区域设置的嵌套 JSON 文件（例如 src/i18n/en/translation.json）而不是源代码中的 t("…") 的项目而设计。CLI 会遍历这些文件中的字符串值，通过活动的 LLM 提供程序翻译它们，并使用 json[].outputPathTemplate 写入每个区域设置的输出。它使用与 translate-docs 和 translate-svg (cacheDir) 相同的 SQLite 缓存。

此管道不运行 extract — 没有 strings.json 目录。使用 features.translateJson 和顶级 json[] 中的一个或多个条目来启用它。

每个区域模型覆盖

translate-json 解析模型 按目标区域设置：首先使用 localeModels(locale)，如果已配置，则使用 translationModels。在某些区域设置中，使用专用模型可以带来更好的效果，例如 zh-Hans / zh-Hant 主题文件。请参阅 提供程序和模型。

步骤 1：初始化嵌套 JSON

ai-i18n-tools init -t ui-json-bundles [-P <provider>]

该模板会设置 features.translateJson: true，禁用 UI 提取和文档翻译，并搭建一个指向 src/i18n/en/translation.json、输出为 src/i18n/{llocale}/translation.json 的单个 json[] 块。它还包含一个默认的 provider / providers 块（除非你传递 -P <provider>，否则为 openrouter）——在运行 translate-json 或 sync 之前，请设置相应的 API 密钥（或使用本地 Ollama）；参见提供商与 API 密钥。请根据你的仓库布局编辑 sourceLocale、targetLocales、contentPaths 和 outputPathTemplate。

步骤 2：配置 json[]

每个 json[] 块描述一个管道：

• contentPaths — 一个或多个 .json 文件、目录或 glob（例如 "src/i18n/en/translation.json" 或 "src/i18n/en/overrides/*.json"）。路径从项目根目录解析。
• outputPathTemplate — 必需。写入每个目标区域设置文件的位置。占位符：{locale}、{LOCALE}、{llocale}（小写区域设置，适用于 Astro 路由文件夹）、{stem}、{basename}、{extension}、{relativeToSourceRoot}。
• targetLocales（可选）— 仅用于此块的子集；否则应用根 targetLocales。
• keyPolicy — 哪些 JSON 键包含可翻译的文本，哪些是稳定标识符（见下文）。
• description（可选）— 显示在 CLI 标题和 status 输出中。

示例（多个源文件，小写区域设置文件夹）：

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "pt-BR"],
  "features": {
    "translateJson": true
  },
  "cacheDir": ".translation-cache",
  "json": [
    {
      "description": "App UI bundle",
      "contentPaths": [
        "src/i18n/en/translation.json",
        "src/i18n/en/overrides/*.json"
      ],
      "outputPathTemplate": "src/i18n/{llocale}/{basename}",
      "keyPolicy": {
        "mode": "denylist",
        "skipKeys": ["id", "slug", "href", "url", "key", "code"],
        "translateKeys": []
      }
    }
  ]
}

keyPolicy

mode	行为
allowlist	仅翻译与 translateKeys（点路径；minimatch glob）匹配的键。
denylist	翻译所有字符串值，除了与 skipKeys 匹配的键。
both	先应用 translateKeys，然后从 skipKeys 中删除匹配项。

路径使用点表示法（nav.home.label）。像 slug 这样的裸名称匹配任何深度的最终键段。

步骤 3：翻译 JSON 包

ai-i18n-tools translate-json

可选标志（与 translate-docs 的理念相同）：-l / --locale 用于指定一部分目标，-p / --path 用于限制文件，--dry-run，--force（清除匹配文件的文件跟踪和分段缓存），--force-update（当文件哈希匹配时重新处理；分段缓存仍然适用），--check-cache（即使文件跟踪匹配，也重新验证具有强制原生脚本的区域设置的缓存分段），-b / --batch-concurrency，--prompt-format（xml | json-array | json-object）。

仅 JSON 项目可以运行：

ai-i18n-tools sync --no-ui --no-svg --no-docs

当同时启用 UI 和文档时，sync 会在 translate-docs 之后运行 translate-json（除非 --no-json）。使用 --no-json 跳过 JSON。

检查每个文件和区域设置的覆盖率：

ai-i18n-tools status

当 translateJson 运行时，status 会打印一个 json[] 部分（✓ 最新，● 过时或缺失）。

JSON 与其他管道

情况	用途
JS/TS/Astro 中的 UI 字符串位于 t("…") / i18n.t("…") 中	UI 字符串 — extract + translate-ui
Docusaurus write-translations 目录 ({ "key": { "message": "…", "description": "…" } })	文档 — docs[].docusaurusCatalogDir + translate-docs，不是 json[]
VitePress 主题/导航/侧边栏字符串	文档 — docsOutput.vitepressThemeCatalog + translate-docs；不要使用 json[] — 参见 VitePress 集成
Nextra _meta.ts 标签和主题字典 .ts	文档 — translate-docs（当 style: "nextra" 时自动 _meta，可选 nextraDictionaryPath）；不要使用 json[] — 参见 Nextra 集成
Fumadocs meta.json 标签和 UI 覆盖目录	文档 — translate-docs（当 style: "fumadocs" 时自动 meta.json，可选 fumadocsUiCatalog）；不要使用 json[] — 参见 Fumadocs 集成
独立嵌套区域设置 JSON（ZenBrowser 风格的 translation.json 树）	JSON — json[] + translate-json
i18next 命名空间文件（public/locales/en/common.json、{{name}} 标记、key_one / key_other 后缀）	JSON — json[] + translate-json（参见 i18next 命名空间文件）
Intlayer *.content.ts 字典 + useIntlayer	从 Intlayer 迁移 — migrate-intlayer，然后是 UI 字符串
带有 <text> / <title> / <desc> 的图示 .svg 文件	features.translateSVG + svg + translate-svg（可选；不是三个主要管道之一）

字段参考：配置参考 中的 json。用于清理的缓存键在 file_tracking 中使用 json-block:{blockIndex}:{projectRelPath}。

i18next 命名空间文件

JSON 管道涵盖典型的 i18next 键/值区域设置文件：嵌套对象、字符串数组、值中的 {{name}} 插值，以及独立的复数后缀键（welcome_one、welcome_other）。它不会重写 t("some.key") 调用点——这些调用点仍保持基于键的方式。要将项目迁移到 ai-i18n-tools 的英文源字符串 t() 架构，请将调用点更改为 t("English text")（或当源为 Intlayer .content.ts 时运行 migrate-intlayer）。

示例（源英文命名空间位于 public/locales/en/ 下）：

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "pt-BR"],
  "features": { "translateJson": true },
  "json": [
    {
      "description": "i18next namespaces",
      "contentPaths": ["public/locales/en/*.json"],
      "outputPathTemplate": "public/locales/{locale}/{basename}"
    }
  ]
}

key_one / key_other / key_zero（以及其他 CLDR 后缀）被翻译为独立的叶子节点。这足以让 i18next 继续通过后缀解析复数形式；管道不会将它们重新组合为单个目录行。