Lingo.dev Spec 包深度解析：i18n 配置 Schema 与本地化工程规范的全景演化

Lingo.dev Spec 包深度解析：i18n 配置 Schema 与本地化工程规范的全景演化

【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica

@lingo.dev/_spec是 Lingo.dev 开源本地化工程体系的“规格中枢”，它以一套版本化的 TypeScript 配置 Schema（zod 定义）、标准化的 locale 代码校验逻辑与 35 种 bucket 格式清单，统一驱动 CLI、SDK 与 Compiler 的翻译流程。本文以 packages/spec/CHANGELOG.md 为核心脉络，结合 packages/spec 的源码与测试，带你逐层理解i18n.json配置从 v0 到 v1.15 的演进史、每个配置项的精确语义，以及这套“开放规格”如何在实际仓库中落地为可复制的工程能力。

一、Spec 包在项目中的定位：一份可执行的开放规格

@lingo.dev/_spec的包描述是 “Lingo.dev open specification”（见 packages/spec/package.json），它的职责不是翻译本身，而是回答三个工程问题：

• “支持哪些 locale？”—— 由 packages/spec/src/locales.ts 维护语言地图与校验规则；
• “支持哪些文件格式（bucket）？”—— 由 packages/spec/src/formats.ts 枚举 bucket 类型；
• “i18n.json长什么样、如何升级？”—— 由 packages/spec/src/config.ts 定义版本化 Schema 与自动迁移链。

三者通过 packages/spec/src/index.ts 统一导出，被 CLI、SDK、Compiler 等上层包引用，保证整个工具链对配置的理解始终一致。从 CHANGELOG 开篇（0.1.0）可以看出它的最初定位：“intro a@replexica/specpackage containing common definitions, constants, schemas, and types”，即把公共定义、常量、Schema 与类型集中到单一包中，并在此后一路演进为“framework-agnostic i18n support”（框架无关的 i18n 支持）。

使用方式非常轻量：npm i lingo.dev后import {} from 'lingo.dev/spec'，即可获得parseI18nConfig、defaultConfig、LATEST_CONFIG_DEFINITION、localeCodeSchema、bucketTypeSchema等核心能力。

二、配置 Schema 的版本化设计：v0 → v1.15 的迁移链

Spec 包最有代表性的设计是配置模式的版本化与自动升级。在 packages/spec/src/config.ts 中，每一代配置都由createConfigDefinition/extendConfigDefinition两个工厂函数串联成链：

export const LATEST_CONFIG_DEFINITION = configV1_15Definition; export type I18nConfig = Z.infer<(typeof LATEST_CONFIG_DEFINITION)["schema"]>; export function parseI18nConfig(rawConfig: unknown) { try { const result = LATEST_CONFIG_DEFINITION.parse(rawConfig); return result; } catch (error: any) { throw new Error(`Failed to parse config: ${error.message}`); } }

每个版本定义包含三要素：

• schema：当前版本的 zod 对象；
• defaultValue：当前版本的默认配置；
• parse：先按当前 Schema 校验，失败时检查是否存在 “Invalid locale code” 类问题（给出更友好的Unsupported locale: xxx错误），否则递归调用上一版本的parse拿到基础配置后执行createUpgrader升级。

这套机制带来的直接收益是：任何历史版本的i18n.json都能被透明升级到最新 Schema。从源码与测试可见完整的版本演变脉络：

其中 v1.15 的升级器值得单独说明：它读取旧配置中的vNext，若存在且未显式设置engineId，则自动engineId: vNext，随后移除vNext字段——这正是 CHANGELOG 0.49.0 所描述的“SDK 与 CLI 统一迁移到api.lingo.dev+X-API-Key认证，新增engineId（从vNext自动迁移）”在 Schema 层的落地。

版本升级的实测行为

packages/spec/src/config.spec.ts 用一组测试锁定了这些行为：

• 空配置{}解析后等于defaultConfig（{version: "1.15", locale: {source: "en", targets: ["es"]}, buckets: {}, ...}）；
• v0 配置升级后补齐$schema、默认 locale 与空 buckets；
• v1 的“路径→类型”buckets 会被自动转换为 v1.1 的“类型→include 列表”结构；
• 配置中的多余字段会被忽略（not.toHaveProperty("extraField")）；
• 非法 locale（如source: "bbbb"、targets: ["aaaa"]）抛出Unsupported locale: bbbb / aaaa的可读错误。

三、Locale 校验与规范化：从 ISO 标准到 Android 方言

CHANGELOG 0.42.0 / 0.43.0 明确记录了一项重要决策：校验不再依赖硬编码语言列表，而是接受任何符合 ISO 639-1、ISO 15924、ISO 3166-1 与 UN M.49 标准的 locale 代码。在源码中，这一能力由@lingo.dev/_locales的isValidLocale承担（见 packages/spec/src/locales.ts）：

export const localeCodeSchema = Z.string().refine( (value) => { const normalized = normalizeLocale(value); return isValidLocale(normalized); }, { message: "Invalid locale code" }, );

四种可接受的写法

localeCodeSchema对同一语言同时接受四种形态（测试见 packages/spec/src/locales.spec.ts）：

1. 短代码：en、fr、es；
2. BCP 47 连字符格式：en-US、zh-Hans-CN、sr-Latn-RS；
3. 下划线格式（Java/Android 习惯）：en_US、pt_BR、zh_Hans_CN；
4. Android-r显式区域格式：en-rUS、fr-rCA、zh-rCN。

normalizeLocale负责在验证前统一形态：下划线替换为连字符，并去掉-r前缀（en_US→en-US，fr-rCA→fr-CA）。测试还覆盖了拒绝场景：xx-US、en-FAKE、en-ZZ、zh-Fake-CN均被判定非法。

语言地图与解析工具

packages/spec/src/locales.ts 同时维护了一张“短代码 → 完整地区变体”的映射表（localeMap），覆盖 60+ 语言，并导出：

• resolveLocaleCode(value)：短代码解析为第一个完整变体（en→en-US，zh→zh-CN），已是完整代码则原样返回，非法则抛错；
• getLocaleCodeDelimiter(locale)：识别-、_或null；
• resolveOverriddenLocale(locale, delimiter?)：重写分隔符（en-US→en_US），对应 CHANGELOG 0.24.0 的“locale delimiter override”；
• normalizeLocale(locale)：上文所述的统一规范化入口。

有趣的是 CHANGELOG 还记录了一系列语言扩展：塞尔维亚语 Latin/Cyrillic 修饰符（0.19.0）、Kinyarwanda 与 Kiswahili（0.26.1）、Telugu（0.21.1）、Icelandicis-IS（0.39.1）、Malayalam / Armenian / Macedonian（0.40.4）、el-CYen-IEfr-LU（0.40.2）、Georgianka-GE（0.33.3）、Kazakh（0.26.0）、Welsh（0.27.0）等——这些在localeMap中均有对应条目，例如el: ["el-GR", "el-CY"]、sr: ["sr-RS", "sr-Latn-RS", "sr-Cyrl-RS"]。

四、Bucket 类型全景：35 种格式的翻译载体

“bucket” 是 Lingo.dev 对“一类文件格式”的抽象：每种 bucket 对应一套 loader（解析/回写逻辑）与一种翻译单元拆分方式。packages/spec/src/formats.ts 以bucketTypeSchema枚举了全部受支持类型：

ail / android / csv / ejs / flutter / html / json / json5 / jsonc / markdown / markdoc / mdx / mjml / twig / xcode-strings / xcode-stringsdict / xcode-xcstrings / xcode-xcstrings-v2 / yaml / yaml-root-key / properties / po / xliff / xml / srt / dato / compiler / vtt / php / vue-json / typescript / txt / json-dictionary / csv-per-locale

对照 CHANGELOG，可以还原这份清单的扩张轨迹，每一个新增类型都有对应 PR：

• 基础格式：.strings/.stringsdict/ Flutter.arb（0.14.0）、.properties（0.13.0）、CSV（0.15.0）、.po（0.17.0）、SRT 字幕（0.18.0）、XLIFF（0.21.0）、Android 资源（0.6.0）、PHP（0.25.0）、.vue的<i18n>块（0.25.3）、JSON 字典（0.39.3）、TXT（0.39.0，用于 fastlane App Store 元数据）；
• 模板与文档：EJS（0.37.0）、Markdoc（0.41.0）、MJML（0.44.1）、Twig（0.44.2）、AIL（0.44.3）、MDX 高级支持（0.29.0 / 0.30.0）；
• Xcode 系：xcode-xcstrings-v2支持 CLDR 复数规则（0.41.1）；
• TypeScript 系：.tsloader 提取 default export 中的字符串字面量，支持嵌套字段与数组（0.32.0 / 0.33.0）；
• 多源本地化：csv-per-locale（0.46.0）、multisource localization（0.10.0）。

在实际仓库中，每个 bucket 都有配套 demo：例如 packages/cli/demo/csv、packages/cli/demo/mdx、packages/cli/demo/xcode-xcstrings-v2 等，内含i18n.json与i18n.lock（lockfile 自 0.5.0 起引入，用于提升 AI 本地化性能与一致性），可直接作为配置模板参考。

五、Bucket 级配置项详解：精细控制翻译边界

在 packages/spec/src/config.ts 中，bucket 配置项从 v1.3 到 v1.13 逐代累积，最终形成如下完整集合：

这五个“Keys 家族”配置对应了 CHANGELOG 中反复出现的三类工程诉求：锁定（lockedKeys/lockedPatterns）、忽略（ignoredKeys）、保留-定制（preservedKeys）与强制翻译（localizableKeys），是 AI 本地化场景下控制“哪些内容能动、哪些不能动”的关键开关。

一个包含多类配置的完整 bucket 示例：

{ "version": "1.15", "$schema": "https://lingo.dev/schema/i18n.json", "locale": { "source": "en", "targets": ["es", "pt-BR", "zh-Hans"] }, "buckets": { "json": { "include": ["src/locales/[locale]/messages.json"], "exclude": ["src/locales/[locale]/internal.json"], "lockedKeys": ["app.name", "brand.url"], "ignoredKeys": ["meta.keywords"], "localizableKeys": ["meta.legacyIds"], "preservedKeys": ["contact.email"] }, "csv": { "include": [{ "path": "i18n/[locale].csv", "delimiter": "_" }], "keyColumn": "id" }, "mdx": { "include": ["content/docs/[locale]/*.mdx"], "lockedPatterns": ["^!params$", "^!! .*$"] } }, "provider": { "id": "openai", "model": "gpt-4o", "settings": { "temperature": 0.2 } }, "formatter": "prettier", "dev": { "usePseudotranslator": true } }

注意：include/exclude中的路径必须包含[locale]占位符（见bucketItemSchema的 path 描述），配合delimiter控制占位符替换形式；仓库根目录的 i18n.json 展示了真实仓库自身的配置：source 为en、27 个 target、一个mdxbucket 指向readme/[locale].md，并带$schema声明。

六、Provider 配置：多模型翻译后端

从 v1.5 起配置支持顶层provider，v1.10 起扩展出settings。providerSchemaV1_10的完整结构为：

{ id: "openai" | "anthropic" | "google" | "ollama" | "openrouter" | "mistral", model: string, // 翻译使用的模型名 prompt: string, // 请求翻译时使用的提示词模板 baseUrl?: string, // 自定义 API 地址（可选，如自建网关） settings?: { temperature?: number // 0=确定性输出，2=非常随机；部分模型（如 GPT-5）要求 temperature=1 } }

对照 CHANGELOG 可还原 provider 支持的时间线：基础 translators（0.27.0）→ Google AI（0.35.0）→ Ollama 作为 CLI/Compiler provider + OpenRouter AIS 支持（0.36.0）→ Mistral AI（0.38.0，配置方式为环境变量MISTRAL_API_KEY或npx lingo.dev@latest config set llm.mistralApiKey <key>）→ provider settings（0.41.0）→ zod 4.4.3 以兼容@openrouter/ai-sdk-provider的 peer 依赖（0.49.2）。

七、开发辅助与工程化配套

dev.usePseudotranslator：零 API 调用的本地化自测

CHANGELOG 0.48.1 将dev.usePseudotranslator加入配置 Schema 并接入 CLI 初始化流程。其语义在 packages/spec/src/config.ts 中有明确定义：“Use pseudotranslator instead of real translation provider. Useful for testing i18n without API calls.”——即用伪翻译（pseudo-localization）替代真实模型调用，用于在没有 API Key 的情况下验证 i18n 管线；配套的伪翻译实现与测试位于 packages/cli/src/utils/pseudo-localize.ts。

JSON Schema 与文档自动生成

Spec 包不仅能校验配置，还能产出标准 JSON Schema。CHANGELOG 0.25.2 引入“build json schema for config”，0.40.1 进一步引入“automated config documentation generator for i18n.json schema”。相关实现：

• packages/spec/src/json-schema.ts：基于 zod 的toJSONSchema(LATEST_CONFIG_DEFINITION.schema)生成i18n.schema.json；
• scripts/docs/src/generate-config-docs.ts：由 Schema 自动渲染配置文档，保证文档与代码永不脱节。

供应链安全与依赖治理

CHANGELOG 末尾的几条记录体现了工程治理层面的严谨：0.44.0 将所有依赖锁定为精确版本（去除^/~），以降低供应链攻击面；0.49.3 集中添加了 picomatch、qs、postcss、ajv、js-yaml、joi、launch-editor、@unhead/vue等依赖的 override 以修补漏洞。从 packages/spec/package.json 可以看到当前依赖已收敛为zod@4.4.3与 workspace 内的@lingo.dev/_locales，并配置了sideEffects: false与 ESM/CJS 双格式产物（build/index.mjs/build/index.cjs）。

八、如何在你自己的项目中使用

1. 安装：npm i lingo.dev（或仓库内使用 pnpm workspace 引用@lingo.dev/_spec）；
2. 创建配置：编写i18n.json，最低只需version+locale.source+locale.targets+buckets，也可以完全省略（parseI18nConfig({})会返回带默认值的最新版本配置）；
3. 接入解析：在工具脚本中import { parseI18nConfig } from 'lingo.dev/spec'，历史版本配置会被自动升级到 v1.15；
4. 选择 bucket：参考 packages/cli/demo 下 35 种格式的示例文件与配套i18n.json/i18n.lock，为你的文件类型选择 loader；
5. 精细化控制：用lockedKeys/lockedPatterns/ignoredKeys/preservedKeys/localizableKeys/keyColumn精确约束每次翻译的边界；
6. 配置 provider：按需选择 openai / anthropic / google / ollama / openrouter / mistral，本地自测时开启dev.usePseudotranslator即可不消耗 API 额度完成管线验证。

结语

从 v0 到 v1.15，@lingo.dev/_spec的每一次版本跃迁都对应一个真实的本地化工程痛点：排除模式、键锁定、正则锁定、保留键、强制翻译、伪翻译、引擎切换与供应链加固。它证明了一件事：一套版本化、可自动升级、带标准 JSON Schema 输出的开放规格，是支撑大规模 AI 本地化工具链稳定演进的基石。理解这份规格，等于同时理解了 Lingo.dev CLI、SDK 与 Compiler 的配置契约与设计哲学。

【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica