i18n.json 配置

i18n.json 是控制 Lingo.dev CLI 和 CI/CD 集成的配置文件。它定义了要翻译哪些语言、可翻译内容位于何处，以及使用哪个翻译后端。

最小示例#

json

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

$schema 字段可启用 IDE 自动补全与校验；version 字段用于跟踪 schema 版本，确保自动迁移兼容。

Locale#

locale 部分用于定义源语言和目标语言：

json

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

字段	说明
`locale.source`	源内容所使用的语言。所有翻译都以该 locale 为起点。
`locale.targets`	目标语言数组。根据 bucket 格式的不同，每个目标语言都会生成一个独立文件（或一个独立分区）。

语言代码遵循 BCP 47 标准，支持 en、en-US、es-ES、zh-Hans，以及 Android 的 en-rUS 等平台特定格式。

如需查看可用的 locale 代码：

bash

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

Buckets#

Bucket 用于定义文件发现模式和处理规则。每个 bucket 键对应一种文件格式，其值则用于配置要包含或排除哪些文件：

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

字段	说明
`include`	包含 `[locale]` 占位符的文件模式数组。支持 glob 通配符（`*`）。
`exclude`	可选。处理过程中需要跳过的模式数组。
`lockedKeys`	可选。其值会直接从源内容复制、不会被翻译的键。参见 Key Locking。
`ignoredKeys`	可选。完全排除在翻译之外的键——它们不会出现在目标文件中。参见 Key Ignoring。
`preservedKeys`	可选。仅在首次从源内容初始化，之后会受到保护、不再自动更新的键。参见 Key Preserving。
`injectLocale`	可选。会自动注入目标 locale 代码的键。

包含模式#

包含模式使用 [locale] 占位符，运行时会解析为你配置的 locale 代码：

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

不支持递归 glob 模式（**/*.json）。请改用显式目录路径。

自定义 locale 分隔符#

默认情况下，文件名中的 locale 代码使用连字符（-）分隔：en-US.json。如果想改用下划线，请传入一个包含 delimiter 字段的对象：

json

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

这样会生成 legacy/en_US.json，而不是 legacy/en-US.json。

键路径表示法#

lockedKeys、ignoredKeys 和 preservedKeys 数组对嵌套键使用正斜杠（/）表示法，并用星号（*）表示通配符：

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

如需查看所有支持的 bucket 类型，请参见 Supported Formats。

Provider#

provider 部分用于配置原始 LLM provider 进行翻译。该部分为可选项——如果省略，CLI 会使用 Lingo.dev 上的 localization engine。

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

字段	说明
`provider.id`	Provider 标识符：`openai`、`anthropic`、`google`、`mistral`、`openrouter` 或 `ollama`。
`provider.model`	该 provider 提供的模型名称（例如 `gpt-4o-mini`、`claude-3-haiku`）。
`provider.prompt`	系统提示词。`{source}` 和 `{target}` 会在运行时替换为 locale 代码。
`provider.baseUrl`	可选。自定义 API 端点（Ollama 必填：`http://localhost:11434`）。

Engine 连接#

如需通过指定的 localization engine 路由翻译，请添加 engineId 字段：

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

设置 engineId 后，每次翻译请求都会自动应用你的 engine 的 brand voice、glossary、instructions 和 model configuration。如果省略该字段且设置了 LINGO_API_KEY，CLI 会使用你所在组织中的默认 engine。

完整配置指南请参见 Connect Your Engine。

环境变量#

变量	必填	说明
`LINGO_API_KEY`	用于 Lingo.dev Engine	你的 Lingo.dev API 密钥。
`LINGO_API_URL`	否	自定义 API 基础 URL（用于自托管或预发布环境）。
`OPENAI_API_KEY`	用于 OpenAI provider	OpenAI API 密钥。
`ANTHROPIC_API_KEY`	用于 Anthropic provider	Anthropic API 密钥。
`GOOGLE_API_KEY`	用于 Google provider	Google API 密钥。
`MISTRAL_API_KEY`	用于 Mistral provider	Mistral API 密钥。
`OPENROUTER_API_KEY`	用于 OpenRouter provider	OpenRouter API 密钥。

完整示例#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

版本迁移#

CLI 会自动将旧版 i18n.json 配置迁移到最新 schema 版本。它会先为当前文件创建备份，再更新 schema，同时保留所有设置，全程无需手动干预。

下一步#

通过你的 localization engine 路由翻译

Setup

安装 CLI 并快速开始

i18n.json 是控制 Lingo.dev CLI 和 CI/CD 集成的配置文件。它定义了要翻译哪些语言、可翻译内容位于何处，以及使用哪个翻译后端。

最小示例#

json

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

$schema 字段可启用 IDE 自动补全与校验；version 字段用于跟踪 schema 版本，确保自动迁移兼容。

Locale#

locale 部分用于定义源语言和目标语言：

json

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

字段	说明
`locale.source`	源内容所使用的语言。所有翻译都以该 locale 为起点。
`locale.targets`	目标语言数组。根据 bucket 格式的不同，每个目标语言都会生成一个独立文件（或一个独立分区）。

语言代码遵循 BCP 47 标准，支持 en、en-US、es-ES、zh-Hans，以及 Android 的 en-rUS 等平台特定格式。

如需查看可用的 locale 代码：

bash

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

Buckets#

Bucket 用于定义文件发现模式和处理规则。每个 bucket 键对应一种文件格式，其值则用于配置要包含或排除哪些文件：

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

字段	说明
`include`	包含 `[locale]` 占位符的文件模式数组。支持 glob 通配符（`*`）。
`exclude`	可选。处理过程中需要跳过的模式数组。
`lockedKeys`	可选。其值会直接从源内容复制、不会被翻译的键。参见 Key Locking。
`ignoredKeys`	可选。完全排除在翻译之外的键——它们不会出现在目标文件中。参见 Key Ignoring。
`preservedKeys`	可选。仅在首次从源内容初始化，之后会受到保护、不再自动更新的键。参见 Key Preserving。
`injectLocale`	可选。会自动注入目标 locale 代码的键。

包含模式#

包含模式使用 [locale] 占位符，运行时会解析为你配置的 locale 代码：

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

不支持递归 glob 模式（**/*.json）。请改用显式目录路径。

自定义 locale 分隔符#

默认情况下，文件名中的 locale 代码使用连字符（-）分隔：en-US.json。如果想改用下划线，请传入一个包含 delimiter 字段的对象：

json

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

这样会生成 legacy/en_US.json，而不是 legacy/en-US.json。

键路径表示法#

lockedKeys、ignoredKeys 和 preservedKeys 数组对嵌套键使用正斜杠（/）表示法，并用星号（*）表示通配符：

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

如需查看所有支持的 bucket 类型，请参见 Supported Formats。

Provider#

provider 部分用于配置原始 LLM provider 进行翻译。该部分为可选项——如果省略，CLI 会使用 Lingo.dev 上的 localization engine。

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

字段	说明
`provider.id`	Provider 标识符：`openai`、`anthropic`、`google`、`mistral`、`openrouter` 或 `ollama`。
`provider.model`	该 provider 提供的模型名称（例如 `gpt-4o-mini`、`claude-3-haiku`）。
`provider.prompt`	系统提示词。`{source}` 和 `{target}` 会在运行时替换为 locale 代码。
`provider.baseUrl`	可选。自定义 API 端点（Ollama 必填：`http://localhost:11434`）。

Engine 连接#

如需通过指定的 localization engine 路由翻译，请添加 engineId 字段：

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

完整配置指南请参见 Connect Your Engine。

环境变量#

变量	必填	说明
`LINGO_API_KEY`	用于 Lingo.dev Engine	你的 Lingo.dev API 密钥。
`LINGO_API_URL`	否	自定义 API 基础 URL（用于自托管或预发布环境）。
`OPENAI_API_KEY`	用于 OpenAI provider	OpenAI API 密钥。
`ANTHROPIC_API_KEY`	用于 Anthropic provider	Anthropic API 密钥。
`GOOGLE_API_KEY`	用于 Google provider	Google API 密钥。
`MISTRAL_API_KEY`	用于 Mistral provider	Mistral API 密钥。
`OPENROUTER_API_KEY`	用于 OpenRouter provider	OpenRouter API 密钥。

完整示例#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

版本迁移#

CLI 会自动将旧版 i18n.json 配置迁移到最新 schema 版本。它会先为当前文件创建备份，再更新 schema，同时保留所有设置，全程无需手动干预。

下一步#

通过你的 localization engine 路由翻译

Setup

安装 CLI 并快速开始