i18n.json 配置

i18n.json 是一个标准配置文件，用于控制 Lingo.dev CLI 及 Lingo.dev CI/CD 集成 的行为。

i18n.json 采用基于 schema 的配置方式，将语言设置、文件发现模式和 AI 翻译引擎配置分为不同部分。因此，开发者只需阅读配置文件即可准确了解本地化工作流的运行方式。

本指南假设你已安装 Lingo.dev CLI 并正在配置翻译工作流。完成后，你将全面了解 i18n.json 的结构、配置选项，以及每个部分如何控制翻译行为。

版本

version 字段指定配置 schema 的版本：

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10"
}

配置元素：

  • $schema — 指向 JSON schema 定义，用于 IDE 自动补全和校验。该 schema 通过内联文档和类型检查，帮助及早发现配置错误。
  • version — 用于迁移兼容性的配置 schema 版本。

Lingo.dev CLI 在发布新 schema 版本时，会利用该字段自动迁移配置。

语言环境配置

locale 部分定义了 Lingo.dev CLI 需要处理的语言：

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja", "de"]
  }
}

语言代码遵循 BCP 47 标准，包含 ISO 639 的语言代码和可选的 ISO 3166-1 区域代码。例如 en、en-US、es-ES 和 zh-Hans。

Lingo.dev CLI 还支持如 Android 的 en-rUS 资源目录约定等平台专用语言环境格式。要获取支持的全部语言代码列表，请运行：

npx lingo.dev@latest show locale sources  # Available source languages
npx lingo.dev@latest show locale targets  # Available target languages

如果你的语言代码未被支持，请 提交 pull request 进行添加！

配置元素：

  • locale.source — 源语言代码，标识哪些文件包含权威内容。所有翻译均从源语言流向目标语言。
  • locale.targets — 目标语言代码数组，代表你的目标市场。每个代码对应一个独立文件或文件内的分区，具体取决于格式。

语言验证命令：

提供商配置

provider 部分用于指定 Lingo.dev CLI 使用的 AI 翻译服务。该部分为可选项，若省略则默认使用 Lingo.dev 的 AI 翻译引擎。

用于原始 LLM API 访问：

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

用于 Lingo.dev 引擎：

如需使用 Lingo.dev 引擎，请完全省略 provider 部分。引擎会根据优化研究和您的 Lingo.dev Engine 设置，自动选择模型和提示。

配置元素：

  • provider.id — AI 翻译服务标识符（如 "openai" 或 "anthropic"）。
  • provider.model — AI 翻译模型名称（如 OpenAI 的 "gpt-4o-mini" 或 Anthropic 的 "claude-3-haiku"）。
  • provider.prompt — 指导翻译行为的系统提示。{source} 和 {target} 占位符将在运行时替换为实际语言代码。

Buckets 配置

Buckets 用于定义文件发现模式和处理规则。每个 bucket 代表一种文件格式，并包含特定的包含/排除模式。

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings/language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

配置元素：

  • buckets.[bucket-type] — 针对特定文件格式 bucket 的配置组。
    • buckets.[bucket-type].include — 文件发现模式数组。可包含字符串或对象。
      • buckets.[bucket-type].include.[string] — 带有 [locale] 占位符的简单文件路径模式。
      • buckets.[bucket-type].include.[object] — 具有以下属性的高级模式配置：
        • path — 带有 [locale] 占位符的文件路径模式。
        • delimiter — 用于语言区域代码的分隔符。默认为 -（短横线），可覆盖为 _（下划线）。会覆盖 locale 配置中的分隔符。
    • buckets.[bucket-type].exclude — 处理时需要跳过的文件排除模式数组。
    • buckets.[bucket-type].lockedKeys — 不应翻译的键名数组。嵌套键使用正斜杠 / 作为分隔符。使用星号 * 匹配多个键。
    • buckets.[bucket-type].ignoredKeys — 翻译时应忽略的键名数组。嵌套键使用正斜杠 / 作为分隔符。使用星号 * 匹配多个键。
    • buckets.[bucket-type].injectLocale — 需要自动注入语言区域代码的键名数组。嵌套键使用正斜杠 / 作为分隔符。使用星号 * 匹配多个键。

基本模式结构

包含模式 使用类似 glob 的语法，并带有特殊的 [locale] 占位符：

  • locales/[locale].json → locales/en.json，locales/es.json
  • docs/[locale]/*.md → docs/en/*.md，docs/es/*.md

排除模式 用于阻止包含模式下特定文件的处理。

高级模式选项

自定义本地化分隔符，适用于不同的文件名格式：

{
  "include": [
    "standard/[locale].json",
    {
      "path": "underscore/[locale].json",
      "delimiter": "_"
    }
  ]
}

可用分隔符：

  • -（短横线）：en-US.json
  • _（下划线）：en_US.json

提示：此设置用于控制文件名中的分隔符，因此可在 monorepo 场景下，不同项目采用不同分隔符规范时使用。

支持的存储桶类型

Lingo.dev CLI 支持以下不同文件格式的存储桶类型：

  • android — Android XML 资源文件
  • csv — 每种目标语言单独文件的 CSV 文件
  • flutter — Flutter ARB 文件
  • html — 每种目标语言单独文件的 HTML 文件
  • json — 每种目标语言单独文件的 JSON 文件
  • markdown — 每种目标语言单独文件的 Markdown 文件
  • mdx — 每种目标语言单独文件的 MDX 文件
  • xcode-strings — 传统 Xcode .strings 文件
  • xcode-stringsdict — 用于复数的 Xcode .stringsdict 文件
  • xcode-xcstrings — Xcode strings catalog 文件
  • yaml — 每种目标语言单独文件的 YAML 文件
  • yaml-root-key — 以本地化为根键的 YAML 文件
  • properties — Java .properties 文件
  • po — GNU gettext .po 文件
  • xml — 每种目标语言单独文件的通用 XML 文件
  • php — PHP 数组文件
  • vue-json — Vue.js i18n JSON 文件
  • typescript — 每种目标语言单独文件的 TypeScript 文件

配置示例

基础配置

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Monorepo 配置

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

版本迁移

i18n.json 实现了智能版本迁移，可在保留所有用户设置的同时，自动将配置更新到最新的模式版本。

当 Lingo.dev CLI 检测到配置版本较旧时，将会：

  1. 创建当前 i18n.json 文件的备份
  2. 迁移配置 到最新的模式版本
  3. 保留所有设置，包括自定义 provider、bucket 配置和锁定的 key
  4. 更新 version 字段 以匹配当前的模式

迁移行为说明：

迁移会在任何 CLI 操作读取配置文件时自动触发。 无需手动干预，您的翻译流程可无缝继续。

此迁移系统确保 i18n.json 配置在与 Lingo.dev CLI 升级时保持兼容，同时也能向现有项目提供向后兼容性。