Lingo.dev 开源本地化工程工具链实战指南：MCP、CLI、CI/CD 与 React 编译器

Lingo.dev 开源本地化工程工具链实战指南：MCP、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

Lingo.dev 是一套开源本地化工程工具，用于将 AI 翻译能力接入 Web 与移动端应用的开发与发布流程，并与 Lingo.dev 本地化工程平台连接以获得一致、高质量的翻译结果。本文基于仓库 readme/he.md（项目 README 的希伯来语译本）与对应源码，系统讲解 Lingo React MCP、Lingo CLI、Lingo GitHub Action、Lingo API 与 Lingo Compiler for React 五种工具的定位、命令与配置方式，读完即可在自己的项目中落地"push 即翻译"的持续本地化流水线。

快速入门：五种工具如何选

Lingo.dev 按"翻译能力入口"把工具分成五类，官方 README 用一张速查表做了归纳：

其中 CLI 是其他工具的地基：GitHub Action 本质上是在 CI 环境里调用lingo.dev ci命令（见 action.yml），MCP 与编译器则在交互式开发与构建阶段使用。

本地化引擎：默认平台引擎与自带 LLM 两条路线

所有工具都可以连接 Lingo.dev 平台 的本地化引擎——由平台托管、带状态的翻译 API。每个引擎会在每次请求中维护字典、品牌语气（voice）与按语言划分的指令，官方文档引用其检索增强本地化（Retrieval-Augmented Localization）研究称，该机制可减少 16.6%–44.6% 的术语错误。同时，CLI 也支持"自带 LLM"（Bring Your Own LLM），从而不必把内容发送到 Lingo.dev 平台。

自带 LLM 的能力可以从 packages/cli/package.json 的依赖中直接印证：CLI 内置了 OpenAI（@ai-sdk/openai）、Anthropic（@ai-sdk/anthropic）、Google（@ai-sdk/google）、Mistral（@ai-sdk/mistral）、OpenRouter（@openrouter/ai-sdk-provider）与 Ollama（ollama-ai-provider-v2）等 provider，本地化器（localizer）在源码 packages/cli/src/cli/localizer 中分化为lingodotdev（平台引擎）、explicit（显式指定模型）与pseudo（伪本地化）三条路径。

Lingo.dev MCP：给 AI 编码助手装上 i18n 知识

在 React 应用中手工配置 i18n 极易出错——官方文档特别指出，即使是基于 AI 的编码助手也可能虚构不存在的 API 并破坏路由。Lingo.dev MCP 通过 Model Context Protocol 给 AI 助手提供框架特定的 i18n 知识，覆盖 Next.js、React Router 与 TanStack Start，可直接在 Claude Code、Cursor、GitHub Copilot Agents 与 Codex 中使用。

典型用法是在 AI 助手中直接下达Set up i18n之类的指令，由助手基于 MCP 注入的知识完成初始化配置，避免幻觉 API。从仓库结构看，CLI 还提供了一条 MCP 初始化命令入口（packages/cli/src/cli/cmd/init/cursor.ts），说明 i18n 初始化流程是可脚本化、可重复执行的。

Lingo CLI：一条命令本地化六种文件格式

Lingo CLI 是整套工具链的核心，定位是"一条命令本地化 JSON、YAML、markdown、CSV 与 PO 文件"：

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

init负责在项目中生成 i18n 配置文件，run执行本地化流水线。关键设计是锁文件（lockfile）机制：CLI 通过i18n.lock跟踪已翻译的内容，只有新增或变更的内容才会进入翻译处理，未变化的键不会被重复请求翻译，从而控制成本并保证增量一致性。仓库根目录与 packages/cli 下都可以看到i18n.lock的真实产物。

支持的格式与目录

虽然速查表只列了五种格式，但从源码 packages/cli/src/cli/loaders 的 loader 实现看，实际支持的输入远不止这些：除 JSON、YAML、markdown、CSV、PO 之外，还包括 MDX/Markdoc、EJS、Twig、MJML、SRT/VTT 字幕、XML、Android 资源、Flutter ARB、Xcode strings/stringsdict/xcstrings、XLIFF、properties、PHP 数组、HTML、纯文本等。每个 loader 都配有独立的解析与写出逻辑，并有对应.spec.ts测试覆盖（例如 json.ts、yaml.ts、markdown.ts）。

run 命令的完整参数

run命令在 packages/cli/src/cli/cmd/run/index.ts 中定义，除了无参数直接运行外，还支持以下实用参数：

注意两点约束：--estimate不能与--watch或--frozen组合使用；run的内部流程是setup → plan → (estimate|frozen) → execute → 汇总，源码中plan阶段会先计算变更增量，execute阶段再按增量执行翻译任务。

Lingo.dev CI/CD：push 即翻译的持续本地化

官方文档给出的核心主张是：每次 push 都触发本地化，缺失的字符串在代码进入生产环境之前就被补齐。支持 GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines 三种平台——这一点与源码 packages/cli/src/cli/cmd/ci/platforms 下的github.ts、gitlab.ts、bitbucket.ts一一对应。

GitHub Action 的最小配置：

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

仓库根目录的 action.yml 定义了该 Action 的全部输入，可进一步定制行为：

Action 内部实际上把上述输入拼装为一次npx lingo.dev@<version> ci调用，因此 CI 的行为与本地ci命令完全一致。对应的 CI 流程实现分为 in-branch（直接提交回当前分支）与 pull-request（创建 PR）两种模式，见 packages/cli/src/cli/cmd/ci/flows。

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

如果需要在业务后端内按需翻译，可以直接调用 Lingo.dev API，不必经过 CLI。API 提供两类调用方式：

• 同步与异步本地化：按场景选择即时返回或后台处理，异步场景通过webhook投递完成结果；
• 按 locale 的故障隔离：单个语言失败不会拖垮其他语言的翻译流程；
• WebSocket 实时进度：客户端可实时接收翻译进度事件。

CLI 底层对 Lingo.dev 平台的调用正是通过 packages/sdk 与 packages/cli/src/cli/sdk 中的 SDK 实现，SDK 同样以子路径lingo.dev/sdk对外导出（见 packages/cli/package.json 的 exports 字段），后端集成可直接复用。

Lingo Compiler for React（早期 Alpha）：去掉 t() 与 JSON 的构建期本地化

这是当前处于早期 Alpha的实验性方向：在构建期完成 React 本地化，不再需要 i18n 包装层。开发者直接用英文书写组件，编译器在构建时自动识别可翻译字符串并生成翻译版本——没有翻译 key、没有 JSON 字典文件、也没有t()函数。支持 Next.js（App Router）与 Vite + React，接入方式是withLingo()插件。

从仓库 packages/new-compiler 的实现结构看，编译器通过 unplugin 体系同时提供 vite.ts、webpack.ts、next.ts 三种接入面，核心转换逻辑集中在 transform 目录，翻译服务与缓存则由 translation-server 与 translators 承担。仓库同时提供两个可运行的参考项目：demo/new-compiler-next16（Next.js 16 示例）与 demo/new-compiler-vite-react-spa（Vite + React SPA 示例），Alpha 阶段的实践方式可参照这两个 demo 的 README 与配置。

参与贡献

仓库是一个pnpm + turborepo monorepo（工作区定义见 pnpm-workspace.yaml），贡献流程如下：

1. Issues：在仓库 Issues 中报告 bug 或提交功能请求；
2. Pull Requests：每个 PR 都必须附带 changeset——运行pnpm new（非发布相关改动用pnpm new:empty），并确保测试通过后再提交；
3. 本地开发：
   • 安装依赖：pnpm install
   • 运行测试：pnpm test
   • 构建：pnpm build

根目录 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md 提供了完整的行为准则与提交规范（commitlint 配置见 commitlint.config.js）。

多语言文档与新增语言

项目 README 被翻译为 30 种语言，存放于 readme 目录（中文版见 readme/zh-Hans.md，本篇文章依据的希伯来语版见 readme/he.md）。新增语言的方式：

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

这一机制本身也是 Lingo.dev 的"自我使用"：仓库用自己的 CLI 维护各语言 README 与i18n.lock，是观察该工具链实际运行效果最直接的样例。仓库根部的横幅图 content/banner.png 即官方使用的项目封面。

综上所述，从交互式 MCP、命令行增量翻译，到 CI 持续本地化、后端 API 与构建期编译器，Lingo.dev 提供了覆盖"写代码—提交—构建—上线"全链条的本地化工程方案；无论选择平台引擎还是自带 LLM，其增量锁文件与变更检测机制都能保证翻译成本可控、质量可追踪。

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