Lingo.dev 开源本地化工程工具链实战指南：MCP、CLI、CI/CD 与 React Compiler 全解析

Lingo.dev 开源本地化工程工具链实战指南MCP、CLI、CI/CD 与 React Compiler 全解析【免费下载链接】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 开源本地化工程工具集展开系统讲解其五大核心组件——Lingo React MCP、Lingo CLI、Lingo GitHub Action、Lingo API 与 Lingo Compiler for React早期 alpha——在 React 应用与多格式内容本地化场景中的定位、配置与用法。读完本文你将掌握从init到run的 CLI 工作流、基于 lockfile 的增量翻译机制、CI/CD 持续本地化接入方式以及无 i18n 包装器的构建时编译方案并能在真实项目中直接复用。快速总览五件工具一站覆盖本地化全流程原 README 将整个工具链浓缩为一张快速上手表每个工具各司其职覆盖从 AI 辅助初始化、文件批量翻译、流水线持续本地化到后端直连翻译引擎、构建时编译的完整链路。工具作用快速命令/用法Lingo React MCPReact 应用的 AI 辅助 i18n 配置PromptSet up i18nLingo CLI本地化 JSON、YAML、markdown、CSV、PO 等文件npx lingo.devlatest runLingo GitHub Action在 GitHub Actions 中持续本地化uses: lingodotdev/lingo.devmainLingo Compiler for React无 i18n 包装器的构建时 React 本地化withLingo()插件本地化引擎翻译的“状态化大脑”上述工具都连接到本地化引擎——一种在 Lingo.dev 本地化工程平台上创建的、具有状态的翻译 API。与一次性调用 LLM 不同每个引擎会在每一次请求之间持续保留术语表glossaries、品牌声音brand voice和每个 locale 的专属指令。项目 README 指出这一机制可将术语错误减少 16.6%–44.6%该数据来自项目文档引用的官方研究。从仓库源码看这一架构落在 CLI 的 localizer 层packages/cli/src/cli/localizer 目录下存在lingodotdev.ts对接 Lingo.dev 引擎、explicit.ts与pseudo.ts伪本地化统一的_types.ts定义了翻译器的通用契约而 packages/cli/src/cli/processor 中的lingo.ts负责将待翻译内容交给引擎处理。如果你不想使用托管引擎CLI 也支持自带 LLMOpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama详见下文 CLI 章节。Lingo React MCP给 AI 编程助手装上 i18n 知识库在 React 应用中配置 i18n 极易出错——即使是 AI 编码助手也经常幻觉出不存在的 API 并破坏路由。Lingo.dev MCP 正是为解决这一痛点而设计它为 AI 助手提供对Next.js、React Router 和 TanStack Start的框架特定 i18n 知识的结构化访问让助手不再凭空猜测。兼容的 AI 客户端Claude Code、Cursor、GitHub Copilot Agents、Codex。使用方式直接在 AI 助手中发出Set up i18n提示词助手即可借助 MCP 提供的框架知识完成 i18n 初始化。仓库中与该能力配套的框架适配层散见于多处packages/react下划分了 client、rsc、react-router、core 四类运行时代码分别对应客户端组件、React Server Components 与路由框架packages/compiler中还有react-router-dictionary-loader.ts与rsc-dictionary-loader.ts等加载器负责为不同框架注入词典数据。这从源码层面印证了文档所述“框架特定 i18n 知识”的落地形态。Lingo CLI一行命令本地化多格式文件Lingo CLI 是这套工具链中使用频率最高的入口核心命令只有两条npx lingo.devlatest init npx lingo.devlatest runinit生成项目配置文件i18n.jsonrun执行本地化流水线。其最关键的工程特性是lockfile 增量机制一份 lockfile 记录“哪些内容已经翻译过”因此每次运行只处理新增或变更的内容避免重复翻译、节省成本。该机制在 CLI 仓库中有专门实现与测试见 packages/cli/src/cli/lockfile.ts 及配套的 lockfile.spec.ts增量对比逻辑位于 packages/cli/src/cli/utils/delta.ts。交互式初始化与参数化初始化init命令源码见 packages/cli/src/cli/cmd/init.ts默认以交互模式运行向导会检测项目内已有的翻译文件、询问采用默认路径还是自定义路径并在结束时检查登录状态、提示写入.gitignore。同时它也支持完全非交互的参数化初始化参数说明默认值-f, --force覆盖已有的 Lingo.dev 配置破坏性操作否则初始化已存在配置时直接中止false-s, --source locale源语言翻译从这里开始en-t, --targets locale...目标语言列表支持es、fr、de-AT等 BCP-47 代码逗号或空格分隔es-b, --bucket type翻译文件的格式类型如json、yaml、androidjson-p, --paths [path...]翻译文件路径路径中可用[locale]占位符表示语言目录空从源码可以看到init对语言代码与 bucket 类型都有严格校验非法输入会给出明确的格式提示-t与-p的内部解析器parseListInput支持逗号/空格分隔、去除引号与多余空白。若 bucket 类型不支持自动扫描向导会提示在i18n.json中手动填写路径。配置文件 i18n.json 详解仓库根目录的 i18n.json 就是一份真实可用的配置——本仓库所有多语言 README包括readme/or-IN.md正是由它驱动生成的{ version: 1.10, locale: { source: en, targets: [ ar, as-IN, bho, bn, de, es, fa, fr, gu-IN, he, hi, it, ja, ko, mr-IN, or-IN, pa-IN, pl, pt-BR, ru, si-LK, ta-IN, te-IN, tr, uk-UA, ur, zh-Hans ] }, buckets: { mdx: { include: [readme/[locale].md] } }, $schema: https://lingo.dev/schema/i18n.json }字段含义version配置文件格式版本号locale.source源语言代码locale.targets目标语言数组全部使用 BCP-47 格式buckets按文件格式分组的翻译任务集合include中的[locale]占位符会在运行时替换为具体语言代码$schemaJSON Schema 校验入口保证配置合法性。若要进一步了解 bucket 的完整能力可以参考 CLI 包自带的演示配置 packages/cli/i18n.json它覆盖了 30 余种格式并展示了三个高级字段lockedKeys锁定某些 key禁止翻译如[locked_key_1]ignoredKeys忽略某些 key不参与提取如[ignored_key_1]preservedKeys翻译时保留原文如[preserved_key_1, legal/preserved_nested]此外还有exclude字段用于排除路径例如markdownbucket 中排除ignored.md。run 命令的完整参数体系run命令源码见 packages/cli/src/cli/cmd/run/index.ts是本地化流水线的执行器提供了丰富的细粒度控制参数说明--source-locale locale临时覆盖i18n.json中的源语言--target-locale locale只处理指定的目标语言可重复传参默认处理全部目标--bucket type只处理指定 bucket 类型如json、yaml、android可重复传参--file substring按子串匹配过滤 bucket 路径如messages.json或locale/可重复--key prefix按点分路径前缀过滤 key如auth.login匹配所有以auth.login开头的 key--force绕过变更检测强制重译全部 key适合更换 AI 模型或翻译设置后整体重新生成--frozen只校验不修改任何不同步即失败适合 CI/CD 部署前一致性检查--api-key key覆盖 settings 或环境变量中的 API key--debug处理前暂停便于附加调试器--concurrency n并发翻译任务数默认 10上限 10调高可加速大批量任务但更耗内存--watch持续监听源文件变更并自动重译--debounce mswatch 模式下的防抖延迟默认 5000ms--sound完成时播放成功/失败提示音--pseudo伪本地化模式给所有抽取字符串加上重音字符与视觉标记不调用任何外部 API适合测试 UI 国际化就绪度--estimate只打印待翻译内容的预估成本并退出与--watch/--frozen互斥从源码看run的执行链路为setup → plan → frozen → execute → summary其中plan负责基于 lockfile 计算增量差异execute负责调用翻译器并写回文件watch则在主流程结束后进入持续监听相关实现见 packages/cli/src/cli/cmd/run 目录下的plan.ts、execute.ts、watch.ts。登录认证与自带 LLM首次使用需要登录以获取 API key运行npx lingo.devlatest login会打开浏览器完成 OAuth 认证并保存凭据源码见 packages/cli/src/cli/cmd/login.ts其内部采用 32 字节随机 verifier 的 PKCE 式会话、2 秒轮询、15 分钟超时。在 CI 环境则推荐直接设置LINGO_API_KEY环境变量。若不想使用 Lingo.dev 托管引擎README 明确说明 CLI 支持自带 LLMOpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama 均可接入适合数据合规要求高或已有模型基建的团队。Lingo GitHub Action 与 CI/CD让每次 push 都触发翻译持续本地化Continuous Localization意味着每次 push 都会触发本地化流程——缺失的字符串在代码进入生产环境之前就被补全彻底消灭“上线才发现没翻译”的尴尬。官方支持GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines对应 CLI 源码中的平台适配层 packages/cli/src/cli/cmd/ci/platforms内含github.ts、gitlab.ts、bitbucket.ts。GitHub Actions 的最小用法uses: lingodotdev/lingo.devmain with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}Action 定义位于仓库根目录 action.yml其内部实际执行npx lingo.devversion ci并暴露了完整的输入参数输入说明默认值versionCLI 版本latestapi-keyLingo.dev 平台 API key建议存入 Secret空pull-request是否创建 PR 提交翻译变更falsecommit-message提交信息feat: update translations via LingoDotDevpull-request-titlePR 标题feat: update translations via LingoDotDevcommit-author-name提交作者名Lingo.devcommit-author-email提交作者邮箱supportlingo.devworking-directory工作目录monorepo 子项目场景很有用.process-own-commits是否允许处理本 Action 自己产生的提交绕过防死循环机制falseparallel是否并发处理翻译false这些参数与 CLIci子命令一一对应见 packages/cli/src/cli/cmd/ci/index.ts后者还额外提供--gpg-sign用于 GPG 签名提交。默认情况下ci会把翻译变更直接提交到当前分支开启--pull-request后则会在独立分支上工作并自动创建/更新 PR对应流程实现见 packages/cli/src/cli/cmd/ci/flows内含in-branch.ts与pull-request.ts两种模式。Lingo API从后端代码直接调用翻译引擎当翻译需求来自后端服务而非构建流水线时可以使用 Lingo API 从业务代码中直接调用本地化引擎其能力包括同步与异步本地化同步等待结果或以异步方式提交任务Webhook 结果投递异步任务完成后通过 Webhook 通知回调按 locale 隔离失败某个语言的翻译失败不会拖垮其他语言WebSocket 实时进度通过 WebSocket 实时获取翻译进度。仓库中的 packages/sdk 即官方 SDK 包其入口 packages/sdk/src/index.ts 暴露了调用引擎的客户端能力配套实现还包括abort-controller.ts请求中断控制与observability.ts/tracking-events.ts可观测性与事件埋点说明 SDK 在设计上考虑了超时中止与调用追踪等生产级需求。Lingo Compiler for React早期 alpha告别 t() 的构建时本地化这是 README 中技术形态最激进的组件构建时build-timeReact 本地化无需任何 i18n 包装器。直接使用普通英文文本编写组件编译器自动识别可翻译字符串在构建阶段为每个目标语言生成本地化变体没有翻译 key、没有 JSON 文件、没有t()函数——源码里就是干净的业务文案翻译产物在构建期自动生成当前支持Next.js (App Router)与Vite React。仓库中的 packages/new-compiler 即该编译器的实现主体其 plugin 层提供了 next.ts、vite.ts、webpack.ts 与 unplugin.ts 等多入口适配README 所述withLingo()插件正是从这些入口暴露的接入方式。仓库还附带两个可直接运行对照的示例项目demo/new-compiler-next16Next.js App Router 演示含app/page.tsx、components/Counter.tsx等组件展示了普通英文 JSX 如何被编译为多语言产物demo/new-compiler-vite-react-spaVite React SPA 演示其public/translations/下预置了de.json、en.json、es.json、fr.json四种语言的编译产物可通过analyze-bundle.sh分析翻译产物的打包体积。由于处于早期 alpha 阶段该方案更适合在可接受实验性 API 变更的项目中先行试用。参与贡献与本地化协作贡献指南项目欢迎社区贡献遵循以下流程Issues报告 Bug 或提交功能需求Pull Requests提交代码变更要求每个 PR 必须附带 changeset运行pnpm new非发布类变更用pnpm new:empty提交前确保测试通过开发环境这是一个 pnpm turborepo monorepo根目录 package.json、pnpm-workspace.yaml 与 turbo.json 可印证安装依赖pnpm install运行测试pnpm test构建pnpm build添加新的 README 语言版本仓库的文档体系本身就是“用工具翻译工具”的绝佳案例。当前所有语言的 README 版本含本文对应的奥里亚语版 readme/or-IN.md都存放在 readme 目录例如 readme/en.md英文源版、readme/zh-Hans.md、readme/ja.md、readme/es.md、readme/ko.md、readme/ru.md、readme/hi.md、readme/ar.md 等。新增语言只需两步使用BCP-47 格式的 locale 代码将其添加到根目录 i18n.json 的locale.targets数组正如上文展示的那样该数组目前包含 27 个目标语言提交 Pull Request。之后npx lingo.devlatest run便会依据mdxbucket 的readme/[locale].md规则自动生成对应语言的新 README 版本——一条完整、可复现、可自动化的多语言文档生产线。【免费下载链接】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），仅供参考