Lingo.dev 本地化工程工具链完全指南：CLI 批量翻译、CI/CD 持续本地化与 React 构建期编译实战

Lingo.dev 本地化工程工具链完全指南：CLI 批量翻译、CI/CD 持续本地化与 React 构建期编译实战

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

本文以开源仓库replexica中的 readme/bn.md（Lingo.dev 项目的多语言 README）为骨架，系统讲解 Lingo.dev 这一开源本地化工程工具链的四大组成——Lingo React MCP、Lingo CLI、Lingo GitHub Action 与 Lingo Compiler for React，并结合仓库源码与示例工程，帮助你掌握从单机批量翻译文件、接入自有 LLM，到在 CI/CD 流水线中实现持续本地化、再到免 i18n 包装器的构建期 React 本地化的完整实战方案。读完本文，你将能独立完成npx lingo.dev@latest init && run的最小落地，并理解 lockfile 增量翻译、i18n.json配置体系与 Compiler 转换管线的底层原理。

项目定位：连接 Lingo.dev 本地化工程平台的开源工具

Lingo.dev 是一套开源本地化工程工具（Open-source localization engineering tools），核心定位是：连接 Lingo.dev 本地化工程平台，为团队提供一致、高质量的翻译。仓库整体采用 pnpm + turborepo 的 monorepo 结构，核心工作负载分布在packages/cli（CLI 与各格式 loader）、packages/spec（i18n.json配置 schema）、packages/sdk（LingoDotDevEngine 平台 SDK）、packages/new-compiler（React 编译器）等包中，仓库根目录还有 action.yml 提供 GitHub Action 复合运行步骤。

本地化引擎（Localization Engines）：状态化的翻译 API

这些工具统一连接到本地化引擎——你在 Lingo.dev 本地化工程平台上创建的状态化翻译 API。每个引擎会在每一次请求中持久保存三样东西：

• 术语表（Glossary）：保证品牌术语、产品名词翻译一致；
• 品牌声音（Brand Voice）：维持文案语气与调性；
• 逐语言环境的指令（Per-locale Instructions）：为每个目标语言定制翻译约束。

根据项目方公布的研究结论，这种检索增强式本地化（Retrieval-Augmented Localization）方案可将术语错误降低 16.6%–44.6%。当然，如果不希望把翻译请求发送到平台，CLI 也支持**自带 LLM（Bring Your Own LLM）**模式，在下一节详细展开。

快速上手：四类工具的定位与一条命令

原文档给出了一张非常精炼的工具速查表，这里完整保留并补充仓库内的对应实现位置：

其中 CLI 与 GitHub Action 的封装关系值得注意：Action 内部实际上是通过npx lingo.dev@<version> ci调用 CLI 的ci子命令完成的（见 action.yml），因此掌握 CLI 是理解整套工具链的基础。

Lingo.dev MCP：让 AI 助手学会正确的 React i18n

在 React 应用中手动设置 i18n 很容易出错——即便是 AI 编程助手也会凭空臆造不存在的 API，甚至破坏路由结构。这是 Lingo.dev MCP 要解决的问题。

MCP（Model Context Protocol）为 AI 助手提供了结构化的、框架特定的 i18n 知识访问能力，覆盖：

• Next.js：App Router / Pages Router 的 i18n 约定；
• React Router：路由级本地化接入；
• TanStack Start：新型全栈框架的 i18n 模式。

它可以配合Claude Code、Cursor、GitHub Copilot Agents 和 Codex等主流 AI 编码工具使用。典型的使用方式是直接向 AI 助手发出提示词Set up i18n，助手基于 MCP 提供的框架知识完成 i18n 初始化，而不再靠"猜测 API"来写代码。这一工具解决的是开发期配置正确性问题，与下面 CLI 解决的翻译文件生产问题形成互补。

Lingo.dev CLI：一条命令本地化任意格式文件

CLI 是整套工具链的中枢。原文档的核心用法是两行命令：

npx lingo.dev@latest init npx lingo.dev@latest run

• init：初始化项目，生成i18n.json配置文件；
• run：读取配置，执行本地化流水线。

lockfile：只翻译新增或变更的内容

CLI 通过一个lockfile（i18n.lock）记录"哪些内容已经被本地化"，每次运行只处理新增或修改过的内容，从而节省 API 调用与费用。仓库中还提供了独立的lingo.dev lockfile子命令用于"根据当前源语言内容生成或刷新i18n.lock"，支持--force强制覆盖已有校验和以重置翻译跟踪（见 packages/cli/src/cli/cmd/lockfile.ts）。在增量校验（--frozen）、变更检测等场景下，lockfile 都是判断"源文件是否已更新、目标文件是否缺失翻译"的依据。

支持的格式：远超文档列举的五种

原文档列举了 JSON、YAML、markdown、CSV 和 PO 五种格式，而实际上 loader 系统覆盖了数十种 bucket 类型。从 packages/cli/src/cli/loaders/index.ts 的 loader 组合工厂可以看到完整清单：

• 通用配置：json、json5、jsonc、yaml、yaml-root-key、json-dictionary、properties、php
• 文档与标记：markdown、markdoc、mdx、html、ejs、twig、txt、mjml
• 表格数据：csv、csv-per-locale
• 软件本地化：po（gettext）、xliff、xml、android（Android strings.xml）、flutter（ARB）
• Apple 生态：xcode-strings、xcode-stringsdict、xcode-xcstrings、xcode-xcstrings-v2
• 字幕：srt、vtt
• 前端框架：typescript、vue-json、ail、dato

每种类型都由多个 loader 以"流水线"方式组合而成（如createTextFileLoader → createJsonLoader → createFlatLoader → createLockedKeysLoader → …），实现统一的键值扁平化、键锁定、格式规范化等能力。

配置体系：i18n.json 详解

i18n.json是 CLI 的核心配置，其 schema 定义在 packages/spec/src/config.ts，从 v0 一路演进到 v1.15，包含以下关键字段：

其中buckets是配置的重心。以仓库 packages/cli/demo/json/i18n.json 中的真实示例为蓝本：

{ "version": "1.12", "locale": { "source": "en", "targets": ["es"] }, "buckets": { "json": { "include": ["./[locale]/example.json"], // [locale] 占位符会被替换为具体语言 "lockedKeys": ["locked_key_1"], // 这些键永不参与翻译、不被覆盖 "preservedKeys": ["preserved_key_1", "legal/preserved_nested"] // 占位加入目标文件但之后不被覆盖 } }, "$schema": "https://lingo.dev/schema/i18n.json" }

每个 bucket 还支持exclude（排除路径/glob）、lockedPatterns（正则锁定内容）、ignoredKeys（完全忽略的键）、localizableKeys（强制翻译的键，例如本应被跳过为"不可翻译"的纯数字、URL、日期，当它们有自定义术语表规则时使用）、injectLocale（注入/移除当前语言的键）、keyColumn（CSV 桶指定作为行唯一标识的列，默认取首列）等选项。文件路径通过[locale]占位符定位各语言文件，并可用**递归匹配。

run 命令的完整选项

在run子命令的实现（packages/cli/src/cli/cmd/run/index.ts）中可以看到完整的运行时参数：

其中--pseudo对应 packages/cli/src/cli/localizer/pseudo.ts 的伪本地化实现；--estimate则通过平台 API 对同样的变更增量计价，属于估算而非报价。

认证方式与自带 LLM（BYOK）

CLI 默认使用 Lingo.dev 平台引擎。认证有三条路径（见 packages/cli/src/cli/localizer/lingodotdev.ts）：

1. 运行lingo.dev login交互式登录；
2. 使用--api-key参数显式传入 API Key；
3. 设置LINGO_API_KEY环境变量。

而一旦在i18n.json中配置了provider字段，CLI 就会切换为BYOK（Bring Your Own Key）模式，跳过平台认证，直接调用你指定的 LLM（见 packages/cli/src/cli/localizer/index.ts）。provider 支持的服务商由 schema 枚举限定（packages/spec/src/config.ts）：

• OpenAI
• Anthropic
• Google
• Mistral
• OpenRouter
• Ollama（本地模型）

provider 配置示例：

{ "provider": { "id": "openai", "model": "gpt-4o", // 使用的模型名 "prompt": "Translate the following JSON…", // 翻译请求的提示词模板 "baseUrl": "https://…", // 可选：自定义 API 基地址 "settings": { "temperature": 0.3 } // 可选：模型参数（0=确定，2=随机，部分模型要求 temperature=1） } }

最小实战流程

结合仓库 packages/cli/demo 下覆盖 30 余种格式的示例工程，一个典型流程是：

1. 准备源语言文件，例如en/example.json，并创建i18n.json指定locale.source: "en"、targets: ["es"]与buckets.json.include: ["./[locale]/example.json"]；
2. 执行npx lingo.dev@latest init完成初始化与认证；
3. 执行npx lingo.dev@latest run，CLI 会生成i18n.lock、对比增量、调用翻译引擎并写回es/example.json；
4. 增量场景再次执行run时，只有变更的键会被重新翻译。

持续本地化：CI/CD 集成（GitHub / GitLab / Bitbucket）

原文档强调的核心价值：把本地化放进流水线，每次 push 触发翻译，缺失的字符串在代码进入生产环境之前就被补齐。支持的平台包括 GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines。

GitHub Action 的最小用法（原文档示例）：

uses: lingodotdev/lingo.dev@main with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Action 的完整输入参数定义在仓库根目录 action.yml，全部可选且有默认值：

该 Action 内部执行的是npx lingo.dev@<version> ci命令（action.yml），对应 CLI 的ci子命令（packages/cli/src/cli/cmd/ci/index.ts）。ci命令同样暴露了--parallel、--pull-request、--commit-message、--pull-request-title、--commit-author-name、--commit-author-email、--working-directory、--process-own-commits、--gpg-sign（GPG 签名提交）等选项，并支持in-branch（直接提交到当前分支）与 pull-request（在独立分支上更新翻译并自动管理 PR）两种流程（见 packages/cli/src/cli/cmd/ci/flows），平台适配层则抽象了 GitHub / GitLab / Bitbucket 三套 API（packages/cli/src/cli/cmd/ci/platforms）。

在 CI 场景中，还可以结合run --frozen做只读校验：不产生任何变更，一旦源文件、目标文件或 lockfile 不同步就直接以非零退出码失败，从而在部署前守住翻译一致性底线。

Lingo.dev API：从后端直接调用本地化引擎

当本地化需求发生在后端代码内部（而不是仓库文件）时，可以直接通过 API 调用你的本地化引擎。原文档明确了 API 的四大能力：

• 同步与异步本地化：按场景选择等待结果或异步处理；
• Webhook 交付：异步任务完成时通过 webhook 推送结果；
• 按语言环境失败隔离：单个 locale 的翻译失败不会拖垮整体；
• WebSocket 实时进度：长耗时任务可实时获取进度。

在仓库侧，CLI 的 Lingo.dev provider 正是通过@lingo.dev/_sdk（即 packages/sdk）中的LingoDotDevEngine客户端与平台 API 通信，包括whoami()鉴权探测、localizeObject()批量翻译与estimate()成本估算（见 packages/cli/src/cli/localizer/lingodotdev.ts）。SDK 的 packages/sdk/src/index.ts 提供了可复用的 TypeScript 客户端实现，可作为后端集成的参考。

Lingo Compiler for React（早期 alpha）：免包装器的构建期本地化

这是工具链中最具颠覆性的组件。原文档给出的理念非常明确：

用普通英文文本编写组件——编译器在构建期识别可翻译字符串并生成本地化版本。没有翻译键、没有 JSON 文件、没有t()函数。

支持的框架：Next.js（App Router）与Vite + React。仓库中对应的两个示例工程分别是 demo/new-compiler-next16 与 demo/new-compiler-vite-react-spa。

从源码文档 packages/new-compiler/src/plugin/transform/TRANSFORMATION_PIPELINE.md 可以看到完整的转换管线：

Source JSX → Babel Parser → AST Transformation → Code Generation → Transformed JSX ↓ Metadata Extraction ↓ .lingo/metadata-{env}/ (LMDB 元数据库)

管线分五个阶段：

1. 文件过滤：只处理.tsx/.jsx文件，跳过node_modules，支持自定义跳过规则，可选"use i18n"指令模式；
2. 代码解析：用@babel/parser将源码解析为 AST（启用jsx、typescript插件）；
3. 组件识别：识别返回 JSX 的函数声明、箭头函数、函数表达式；默认视为 Server Component，带"use client"指令的视为 Client Component；
4. 文本提取：遍历 JSX 文本节点（如<div>Hello World</div>、<h1>Welcome!</h1>会被转换；纯空白文本与{variable}表达式跳过），基于**文本内容 + 上下文（组件名、文件路径）**生成唯一哈希，并记录源文本、上下文、行列号、时间戳等元数据；
5. 代码转换：把文本替换为翻译调用。例如 Server Component 会被改写为通过getServerTranslations({ hashes: [...] })获取翻译并解构出t进行渲染（TRANSFORMATION_PIPELINE.md）。

这种设计把"字符串如何翻译、翻译放哪里"完全托管给编译器与元数据库，业务代码只需写纯英文文案，大幅降低 i18n 的侵入性。需要提醒的是，该组件目前处于早期 alpha阶段，生产环境使用前应充分评估稳定性。

参与贡献与多语言文档

仓库欢迎社区贡献，规范如下（详见 CONTRIBUTING.md）：

• Issues：报告 bug 或请求功能；
• Pull Requests：每个 PR 需要携带 changeset，发布类变更执行pnpm new，非发布类变更执行pnpm new:empty，提交前需确保测试通过；
• 开发环境：这是一个 pnpm + turborepo monorepo，安装依赖pnpm install、运行测试pnpm test、构建pnpm build。

该仓库本身也是自身工具的"自举"案例：根目录 i18n.json 与 i18n.lock 管理着 readme 目录下 30 余种语言的 README 翻译（含本文对应的 readme/bn.md）。如果你希望新增一种语言，步骤非常轻量：

1. 使用 BCP-47 格式在根目录 i18n.json 中添加语言代码；
2. 提交 Pull Request。

总结：一条从开发到上线的本地化链路

把四个工具串联起来，就构成了一条完整的本地化工程链路：

• 开发期：Lingo React MCP 帮助 AI 助手正确初始化框架 i18n；Lingo Compiler 让你用纯英文文案写组件，构建期自动产出各语言版本；
• 内容期：Lingo CLI 配合 lockfile 增量机制，将 JSON、YAML、Markdown、CSV、PO 及数十种格式的文件批量翻译，默认走 Lingo.dev 引擎，也可切换 OpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama 等自带 LLM；
• 上线期：GitHub Actions / GitLab CI / Bitbucket Pipelines 中的持续本地化确保每次 push 后缺失字符串在代码到达生产前被补齐，--frozen模式可在部署前做一致性校验；
• 后端集成：Lingo.dev API 以同步/异步、webhook、WebSocket 方式满足动态内容翻译需求。

无论你的团队采用"文件翻译 + 持续集成"的传统路线，还是拥抱"构建期编译 + AI 辅助"的新范式，这套工具链都提供了可落地的开源实现，本文涉及的源码与示例工程均可在仓库内进一步查阅验证。

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