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/replexicalingo.dev/_spec是 Lingo.dev 开源本地化工程体系的“规格中枢”它以一套版本化的 TypeScript 配置 Schemazod 定义、标准化的 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 areplexica/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。从源码与测试可见完整的版本演变脉络版本引入的核心变更源码依据packages/spec/src/config.tsv0仅有version字段的占位 SchemaconfigV0Schemav1引入localesource/targets与buckets路径→类型的映射configV1Definitionv1.1bucket 重构为按类型聚合支持include/exclude排除模式configV1_1Definitionv1.2locale.extraSource可选回退源语言configV1_2Definitionv1.3bucket 的 include/exclude 支持{path, delimiter}对象新增injectLocale、keyColumnbucketValueSchemaV1_3v1.4顶层$schema字段指向https://lingo.dev/schema/i18n.jsonconfigV1_4Definitionv1.5顶层providerid/model/prompt/baseUrlproviderSchemav1.6bucket 新增lockedKeysbucketValueSchemaV1_6v1.7bucket 新增lockedPatterns正则锁定bucketValueSchemaV1_7v1.8bucket 新增ignoredKeysbucketValueSchemaV1_8v1.9顶层formatterprettier / biomeconfigV1_9Definitionv1.10provider 新增settings.temperatureproviderSchemaV1_10v1.11顶层vNext字段vNext 引擎configV1_11Definitionv1.12bucket 新增preservedKeysbucketValueSchemaV1_12v1.13bucket 新增localizableKeysbucketValueSchemaV1_13v1.14顶层dev.usePseudotranslatorconfigV1_14Definitionv1.15顶层engineId并自动将旧vNext迁移为engineIdconfigV1_15Definition其中 v1.15 的升级器值得单独说明它读取旧配置中的vNext若存在且未显式设置engineId则自动engineId: vNext随后移除vNext字段——这正是 CHANGELOG 0.49.0 所描述的“SDK 与 CLI 统一迁移到api.lingo.devX-API-Key认证新增engineId从vNext自动迁移”在 Schema 层的落地。版本升级的实测行为packages/spec/src/config.spec.ts 用一组测试锁定了这些行为空配置{}解析后等于defaultConfig{version: 1.15, locale: {source: en, targets: [es]}, buckets: {}, ...}v0 配置升级后补齐$schema、默认 locale 与空 bucketsv1 的“路径→类型”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.tsexport const localeCodeSchema Z.string().refine( (value) { const normalized normalizeLocale(value); return isValidLocale(normalized); }, { message: Invalid locale code }, );四种可接受的写法localeCodeSchema对同一语言同时接受四种形态测试见 packages/spec/src/locales.spec.ts短代码en、fr、esBCP 47 连字符格式en-US、zh-Hans-CN、sr-Latn-RS下划线格式Java/Android 习惯en_US、pt_BR、zh_Hans_CNAndroid-r显式区域格式en-rUS、fr-rCA、zh-rCN。normalizeLocale负责在验证前统一形态下划线替换为连字符并去掉-r前缀en_US→en-USfr-rCA→fr-CA。测试还覆盖了拒绝场景xx-US、en-FAKE、en-ZZ、zh-Fake-CN均被判定非法。语言地图与解析工具packages/spec/src/locales.ts 同时维护了一张“短代码 → 完整地区变体”的映射表localeMap覆盖 60 语言并导出resolveLocaleCode(value)短代码解析为第一个完整变体en→en-USzh→zh-CN已是完整代码则原样返回非法则抛错getLocaleCodeDelimiter(locale)识别-、_或nullresolveOverriddenLocale(locale, delimiter?)重写分隔符en-US→en_US对应 CHANGELOG 0.24.0 的“locale delimiter override”normalizeLocale(locale)上文所述的统一规范化入口。有趣的是 CHANGELOG 还记录了一系列语言扩展塞尔维亚语 Latin/Cyrillic 修饰符0.19.0、Kinyarwanda 与 Kiswahili0.26.1、Telugu0.21.1、Icelandicis-IS0.39.1、Malayalam / Armenian / Macedonian0.40.4、el-CYen-IEfr-LU0.40.2、Georgianka-GE0.33.3、Kazakh0.26.0、Welsh0.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.arb0.14.0、.properties0.13.0、CSV0.15.0、.po0.17.0、SRT 字幕0.18.0、XLIFF0.21.0、Android 资源0.6.0、PHP0.25.0、.vue的i18n块0.25.3、JSON 字典0.39.3、TXT0.39.0用于 fastlane App Store 元数据模板与文档EJS0.37.0、Markdoc0.41.0、MJML0.44.1、Twig0.44.2、AIL0.44.3、MDX 高级支持0.29.0 / 0.30.0Xcode 系xcode-xcstrings-v2支持 CLDR 复数规则0.41.1TypeScript 系.tsloader 提取 default export 中的字符串字面量支持嵌套字段与数组0.32.0 / 0.33.0多源本地化csv-per-locale0.46.0、multisource localization0.10.0。在实际仓库中每个 bucket 都有配套 demo例如 packages/cli/demo/csv、packages/cli/demo/mdx、packages/cli/demo/xcode-xcstrings-v2 等内含i18n.json与i18n.locklockfile 自 0.5.0 起引入用于提升 AI 本地化性能与一致性可直接作为配置模板参考。五、Bucket 级配置项详解精细控制翻译边界在 packages/spec/src/config.ts 中bucket 配置项从 v1.3 到 v1.13 逐代累积最终形成如下完整集合配置项版本引入语义includev1.1 / v1.3纳入该 bucket 的路径或 glob支持**递归匹配v1.3 起元素可为{path, delimiter}对象excludev1.1 / v1.3从 bucket 中排除的路径或 globdelimiterv1.3-、_或null替换路径中[locale]占位符使用的分隔符默认无分隔符injectLocalev1.3需要注入/移除当前 locale 的键注入机制见 CHANGELOG 0.26.6keyColumnv1.30.49.1 完善仅 CSV作为唯一行标识的列名默认取表头第一列同时校验键唯一性防止重复键导致静默丢数据lockedKeysv1.6翻译过程中绝不被覆盖的键lockedPatternsv1.7正则模式命中的内容在翻译期间保持锁定MDX 中!params、!! heading、!type、!required、!values等模式即由此保护ignoredKeysv1.80.46.0 起支持 CSV完全跳过、不参与翻译的键preservedKeysv1.120.47.1以源值为占位符加入目标文件一旦存在就永不被 CLI 覆盖——适用于 URL、邮箱等“先复制再按地区定制”的值localizableKeysv1.130.48.0强制翻译本会被“不可翻译过滤器”跳过的值纯数字、URL、ISO 日期等用于有自定义术语规则时强制翻译这五个“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 起配置支持顶层providerv1.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要求 temperature1 } }对照 CHANGELOG 可还原 provider 支持的时间线基础 translators0.27.0→ Google AI0.35.0→ Ollama 作为 CLI/Compiler provider OpenRouter AIS 支持0.36.0→ Mistral AI0.38.0配置方式为环境变量MISTRAL_API_KEY或npx lingo.devlatest config set llm.mistralApiKey key→ provider settings0.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.jsonscripts/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 可以看到当前依赖已收敛为zod4.4.3与 workspace 内的lingo.dev/_locales并配置了sideEffects: false与 ESM/CJS 双格式产物build/index.mjs/build/index.cjs。八、如何在你自己的项目中使用安装npm i lingo.dev或仓库内使用 pnpm workspace 引用lingo.dev/_spec创建配置编写i18n.json最低只需versionlocale.sourcelocale.targetsbuckets也可以完全省略parseI18nConfig({})会返回带默认值的最新版本配置接入解析在工具脚本中import { parseI18nConfig } from lingo.dev/spec历史版本配置会被自动升级到 v1.15选择 bucket参考 packages/cli/demo 下 35 种格式的示例文件与配套i18n.json/i18n.lock为你的文件类型选择 loader精细化控制用lockedKeys/lockedPatterns/ignoredKeys/preservedKeys/localizableKeys/keyColumn精确约束每次翻译的边界配置 provider按需选择 openai / anthropic / google / ollama / openrouter / mistral本地自测时开启dev.usePseudotranslator即可不消耗 API 额度完成管线验证。结语从 v0 到 v1.15lingo.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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/replexicalingo.dev/_spec是 Lingo.dev 开源本地化工程体系的“规格中枢”它以一套版本化的 TypeScript 配置 Schemazod 定义、标准化的 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 areplexica/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。从源码与测试可见完整的版本演变脉络版本引入的核心变更源码依据packages/spec/src/config.tsv0仅有version字段的占位 SchemaconfigV0Schemav1引入localesource/targets与buckets路径→类型的映射configV1Definitionv1.1bucket 重构为按类型聚合支持include/exclude排除模式configV1_1Definitionv1.2locale.extraSource可选回退源语言configV1_2Definitionv1.3bucket 的 include/exclude 支持{path, delimiter}对象新增injectLocale、keyColumnbucketValueSchemaV1_3v1.4顶层$schema字段指向https://lingo.dev/schema/i18n.jsonconfigV1_4Definitionv1.5顶层providerid/model/prompt/baseUrlproviderSchemav1.6bucket 新增lockedKeysbucketValueSchemaV1_6v1.7bucket 新增lockedPatterns正则锁定bucketValueSchemaV1_7v1.8bucket 新增ignoredKeysbucketValueSchemaV1_8v1.9顶层formatterprettier / biomeconfigV1_9Definitionv1.10provider 新增settings.temperatureproviderSchemaV1_10v1.11顶层vNext字段vNext 引擎configV1_11Definitionv1.12bucket 新增preservedKeysbucketValueSchemaV1_12v1.13bucket 新增localizableKeysbucketValueSchemaV1_13v1.14顶层dev.usePseudotranslatorconfigV1_14Definitionv1.15顶层engineId并自动将旧vNext迁移为engineIdconfigV1_15Definition其中 v1.15 的升级器值得单独说明它读取旧配置中的vNext若存在且未显式设置engineId则自动engineId: vNext随后移除vNext字段——这正是 CHANGELOG 0.49.0 所描述的“SDK 与 CLI 统一迁移到api.lingo.devX-API-Key认证新增engineId从vNext自动迁移”在 Schema 层的落地。版本升级的实测行为packages/spec/src/config.spec.ts 用一组测试锁定了这些行为空配置{}解析后等于defaultConfig{version: 1.15, locale: {source: en, targets: [es]}, buckets: {}, ...}v0 配置升级后补齐$schema、默认 locale 与空 bucketsv1 的“路径→类型”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.tsexport const localeCodeSchema Z.string().refine( (value) { const normalized normalizeLocale(value); return isValidLocale(normalized); }, { message: Invalid locale code }, );四种可接受的写法localeCodeSchema对同一语言同时接受四种形态测试见 packages/spec/src/locales.spec.ts短代码en、fr、esBCP 47 连字符格式en-US、zh-Hans-CN、sr-Latn-RS下划线格式Java/Android 习惯en_US、pt_BR、zh_Hans_CNAndroid-r显式区域格式en-rUS、fr-rCA、zh-rCN。normalizeLocale负责在验证前统一形态下划线替换为连字符并去掉-r前缀en_US→en-USfr-rCA→fr-CA。测试还覆盖了拒绝场景xx-US、en-FAKE、en-ZZ、zh-Fake-CN均被判定非法。语言地图与解析工具packages/spec/src/locales.ts 同时维护了一张“短代码 → 完整地区变体”的映射表localeMap覆盖 60 语言并导出resolveLocaleCode(value)短代码解析为第一个完整变体en→en-USzh→zh-CN已是完整代码则原样返回非法则抛错getLocaleCodeDelimiter(locale)识别-、_或nullresolveOverriddenLocale(locale, delimiter?)重写分隔符en-US→en_US对应 CHANGELOG 0.24.0 的“locale delimiter override”normalizeLocale(locale)上文所述的统一规范化入口。有趣的是 CHANGELOG 还记录了一系列语言扩展塞尔维亚语 Latin/Cyrillic 修饰符0.19.0、Kinyarwanda 与 Kiswahili0.26.1、Telugu0.21.1、Icelandicis-IS0.39.1、Malayalam / Armenian / Macedonian0.40.4、el-CYen-IEfr-LU0.40.2、Georgianka-GE0.33.3、Kazakh0.26.0、Welsh0.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.arb0.14.0、.properties0.13.0、CSV0.15.0、.po0.17.0、SRT 字幕0.18.0、XLIFF0.21.0、Android 资源0.6.0、PHP0.25.0、.vue的i18n块0.25.3、JSON 字典0.39.3、TXT0.39.0用于 fastlane App Store 元数据模板与文档EJS0.37.0、Markdoc0.41.0、MJML0.44.1、Twig0.44.2、AIL0.44.3、MDX 高级支持0.29.0 / 0.30.0Xcode 系xcode-xcstrings-v2支持 CLDR 复数规则0.41.1TypeScript 系.tsloader 提取 default export 中的字符串字面量支持嵌套字段与数组0.32.0 / 0.33.0多源本地化csv-per-locale0.46.0、multisource localization0.10.0。在实际仓库中每个 bucket 都有配套 demo例如 packages/cli/demo/csv、packages/cli/demo/mdx、packages/cli/demo/xcode-xcstrings-v2 等内含i18n.json与i18n.locklockfile 自 0.5.0 起引入用于提升 AI 本地化性能与一致性可直接作为配置模板参考。五、Bucket 级配置项详解精细控制翻译边界在 packages/spec/src/config.ts 中bucket 配置项从 v1.3 到 v1.13 逐代累积最终形成如下完整集合配置项版本引入语义includev1.1 / v1.3纳入该 bucket 的路径或 glob支持**递归匹配v1.3 起元素可为{path, delimiter}对象excludev1.1 / v1.3从 bucket 中排除的路径或 globdelimiterv1.3-、_或null替换路径中[locale]占位符使用的分隔符默认无分隔符injectLocalev1.3需要注入/移除当前 locale 的键注入机制见 CHANGELOG 0.26.6keyColumnv1.30.49.1 完善仅 CSV作为唯一行标识的列名默认取表头第一列同时校验键唯一性防止重复键导致静默丢数据lockedKeysv1.6翻译过程中绝不被覆盖的键lockedPatternsv1.7正则模式命中的内容在翻译期间保持锁定MDX 中!params、!! heading、!type、!required、!values等模式即由此保护ignoredKeysv1.80.46.0 起支持 CSV完全跳过、不参与翻译的键preservedKeysv1.120.47.1以源值为占位符加入目标文件一旦存在就永不被 CLI 覆盖——适用于 URL、邮箱等“先复制再按地区定制”的值localizableKeysv1.130.48.0强制翻译本会被“不可翻译过滤器”跳过的值纯数字、URL、ISO 日期等用于有自定义术语规则时强制翻译这五个“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 起配置支持顶层providerv1.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要求 temperature1 } }对照 CHANGELOG 可还原 provider 支持的时间线基础 translators0.27.0→ Google AI0.35.0→ Ollama 作为 CLI/Compiler provider OpenRouter AIS 支持0.36.0→ Mistral AI0.38.0配置方式为环境变量MISTRAL_API_KEY或npx lingo.devlatest config set llm.mistralApiKey key→ provider settings0.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.jsonscripts/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 可以看到当前依赖已收敛为zod4.4.3与 workspace 内的lingo.dev/_locales并配置了sideEffects: false与 ESM/CJS 双格式产物build/index.mjs/build/index.cjs。八、如何在你自己的项目中使用安装npm i lingo.dev或仓库内使用 pnpm workspace 引用lingo.dev/_spec创建配置编写i18n.json最低只需versionlocale.sourcelocale.targetsbuckets也可以完全省略parseI18nConfig({})会返回带默认值的最新版本配置接入解析在工具脚本中import { parseI18nConfig } from lingo.dev/spec历史版本配置会被自动升级到 v1.15选择 bucket参考 packages/cli/demo 下 35 种格式的示例文件与配套i18n.json/i18n.lock为你的文件类型选择 loader精细化控制用lockedKeys/lockedPatterns/ignoredKeys/preservedKeys/localizableKeys/keyColumn精确约束每次翻译的边界配置 provider按需选择 openai / anthropic / google / ollama / openrouter / mistral本地自测时开启dev.usePseudotranslator即可不消耗 API 额度完成管线验证。结语从 v0 到 v1.15lingo.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
