i18n.json 配置

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

i18n.json 实现了一种基于模式的配置，将语言设置、文件发现模式和 AI 翻译引擎配置分为不同的部分。因此，开发者可以通过阅读配置文件，清楚地了解其本地化工作流程的运行方式。

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

版本

version 字段指定配置模式的版本：

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

配置元素：

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

Lingo.dev CLI 使用此字段在发布新模式版本时自动进行配置迁移。

语言环境配置

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  # 可用的源语言
npx lingo.dev@latest show locale targets  # 可用的目标语言

如果您的语言环境代码不受支持，请 提交一个拉取请求 来添加它！

配置元素：

  • 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 引擎设置自动选择模型和提示。

配置元素：

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

存储桶配置

存储桶定义了文件发现模式和处理规则。每个存储桶表示具有特定包含/排除模式的文件格式。

{
  "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] — 特定文件格式存储桶的配置组。
    • buckets.[bucket-type].include — 文件发现模式数组。可以包含字符串或对象。
      • buckets.[bucket-type].include.[string] — 带有 [locale] 占位符的简单文件路径模式。
      • buckets.[bucket-type].include.[object] — 具有以下属性的高级模式配置：
        • path — 带有 [locale] 占位符的文件路径模式。
        • delimiter — 用于语言代码的分隔符。默认为 -（短横线），可以覆盖为 _（下划线）。覆盖来自语言配置的分隔符。
    • 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 字符串目录文件
  • 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.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Monorepo 配置

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "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. 保留所有设置 包括自定义提供程序、存储桶配置和锁定的键
  4. 更新版本字段 以匹配当前的模式

迁移行为：

迁移会在任何读取配置文件的 CLI 操作中自动触发。 无需手动干预，您的翻译工作流程将继续不间断。

此迁移系统确保 i18n.json 配置与 Lingo.dev CLI 更新保持兼容，同时保持对现有项目的向后兼容性。