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本文基于仓库 readme/zh-Hans.md 展开。Lingo.dev 是一套开源本地化工程工具通过连接 Lingo.dev 本地化工程平台有状态翻译 API为开发团队提供一致、优质的翻译能力。读完本文你将掌握如何用一条命令完成 JSON/YAML/Markdown/CSV/PO 等文件的本地化、如何在 GitHub Actions 中实现推送即翻译的持续本地化、如何让 AI 助手借助 MCP 安全配置 React i18n以及如何利用 Compiler 在构建期直接生成本地化产物而无需任何 i18n 包装器。一、工具全景四大入口 一个平台Lingo.dev 的定位是本地化工程工具仓库本身是纯开源工具集而翻译质量与一致性由连接到的 Lingo.dev 平台本地化引擎提供。从根目录的 快速开始章节 可以快速一览四类工具的定位与最小用法工具功能快速命令Lingo React MCPAI 辅助的 React 应用 i18n 配置提示词Set up i18nLingo CLI本地化 JSON、YAML、Markdown、CSV、PO 文件npx lingo.devlatest runLingo GitHub Action在 GitHub Actions 中持续本地化uses: lingodotdev/lingo.devmainLingo Compiler for React构建时 React 本地化无需 i18n 包装器withLingo()插件此外还有Lingo.dev API直接从后端代码调用本地化引擎支持同步/异步本地化、webhook 交付、按语言环境隔离故障以及通过 WebSocket 实时监控进度。本地化引擎Localization Engines所有工具的背后是本地化引擎这一核心概念它是你在 Lingo.dev 平台上创建的有状态翻译 API。引擎在每一次请求中都会持久化术语表Glossary、品牌语调Brand Voice和特定语言的指令从而保证跨文件、跨批次的翻译一致性。在 CLI 源码的初始化流程中可以看到这一机制的落点——run/setup.ts 在创建 Lingo.dev Provider 时会并行展示Brand voice enabled / Translation memory connected / Glossary enabled / Quality assurance enabled四个子任务而当切换到自有 LLM 时这些子任务则全部显示为 skipped跳过对应自定义 LLM 不享受引擎级术语与翻译记忆的差异。如果你不想依赖平台也可以自带 LLMCLI 支持 OpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama相关依赖可以在 packages/cli/package.json 中一一对应找到如ai-sdk/openai、ai-sdk/anthropic、ai-sdk/google、ai-sdk/mistral、openrouter/ai-sdk-provider、ollama-ai-provider-v2。二、Lingo.dev CLI一条命令本地化七大类文件CLI 是这套工具链中使用频率最高的入口。标准用法是两步走npx lingo.devlatest init npx lingo.devlatest runinit初始化项目生成i18n.json配置文件仓库根目录的 i18n.json 即是真实示例其中locale.source为enlocale.targets列出 27 个目标语言buckets.mdx.include声明了readme/[locale].md这一内容桶run执行本地化流水线。仓库根目录的i18n.json本身就是一个很好的参考模板{ version: 1.10, locale: { source: en, targets: [zh-Hans, ja, ko, es, fr, ru /* ... */] }, buckets: { mdx: { include: [readme/[locale].md] } }, $schema: https://lingo.dev/schema/i18n.json }2.1 Lockfile 增量机制只翻译新增内容CLI 的核心设计之一是锁定文件lockfile它跟踪哪些内容已经被本地化因此每次run只处理新增或变更的内容避免重复翻译、节省成本。仓库自身的i18n.lock文件就是这一机制在生产中的产物。2.2 run 命令的全部参数从 run/index.ts 的源码可以看到run支持非常细粒度的控制参数参数说明默认值--source-locale locale覆盖i18n.json中的源语言配置文件中的 source--target-locale locale只处理指定的目标语言可重复传入多个全部目标语言--bucket bucket只处理指定类型的内容桶如json、yaml、android可重复全部桶--file pattern按子串匹配过滤桶内文件路径如messages.json无过滤--key key按点分隔路径前缀过滤键如auth.login无过滤--force强制重新翻译所有键绕过变更检测适合升级 AI 模型或翻译设置后重建false--frozen只校验不修改源文件、目标文件、lockfile 不同步即失败适合 CI/CDfalse--api-key key覆盖设置或环境变量中的 API Key设置/环境变量--debug处理前暂停以便附加调试器false--concurrency n并发翻译任务数最高 1010--watch监听源语言文件变更并自动重译关闭--debounce mswatch 模式下文件变更后的重译延迟5000--sound完成后播放成功/失败提示音关闭--pseudo伪本地化模式本地加注音符号与视觉标记不调用任何外部 API关闭--estimate打印待翻译内容的预估成本后退出不可与--watch/--frozen组合关闭其中几个参数值得展开--pseudo伪本地化不调用任何翻译 API而是把所有待翻译字符串自动替换为带重音符号和视觉标记的伪翻译文本。这在 UI 国际化就绪性测试中非常有用可以提前暴露硬编码文本、文本溢出、字符宽度问题。源码 utils/pseudo-localize.ts 与对应测试 utils/pseudo-localize.spec.ts 实现了字符替换规则。--frozen翻译一致性校验模式适合放在部署前确保源文件、目标文件、lockfile 三者完全同步才能通过。--watch--debounce本地化流水线的开发模式改动源语言文件后自动增量翻译。--estimate基于变更增量通过 Lingo.dev API 计价输出的是估算值而非报价。run的完整执行管线setup → plan → estimate/frozen → execute → summary与错误处理、退出码逻辑都集中在 run/index.ts 及其同目录的plan.ts、execute.ts、estimate.ts、frozen.ts、exit-code.ts中。2.3 支持的文件格式远超 README 所列的五种README 声称支持 JSON、YAML、Markdown、CSV、PO但实际从 packages/cli/src/cli/loaders 目录的源码看Loader 体系覆盖的格式远不止这些每个格式都有对应的.ts实现与.spec.ts测试通用文本JSON、JSON5、JSONC、YAML、CSV、每语言一个 CSV、TXT、EJS、HTML、Twig、MJML文档类Markdown、MDX、Markdoc含 frontmatter 拆分、代码占位符、章节拆分等复杂处理见 loaders/mdx2软件生态Androidstrings.xml、Flutter ARB、PHP、properties、Xcodestrings/stringsdict/xcstrings含 v2 版本、xliff、xml、POgettext、Vue SFC、TypeScript、SRT/VTT 字幕、i18n AIL 等这意味着一个团队可以用同一套配置、同一套 lockfile 机制统一管理 Web 前端JSON/MDX、移动端Android/Flutter/iOS、文档站Markdown/MDX甚至视频字幕SRT/VTT的翻译。每个 Loader 都配套了 spec 测试例如 loaders/mdx.spec.ts、loaders/yaml.spec.ts、loaders/po/index.spec.ts可作为格式行为边界的权威参考。另外 Loader 层还提供了键级别的精细控制ignored-keys忽略键、locked-keys/locked-patterns锁定键、preserved-keys保留键、unlocalizable不可本地化内容等相关实现见 loaders/ignored-keys.ts、loaders/locked-keys.ts、loaders/preserved-keys.ts。2.4 配置 Provider平台引擎或自带 LLMsetup阶段会根据配置选择 Provider见 run/setup.ts配置为 Lingo.dev 引擎时会自动执行认证检查checkAuth并启用品牌语调、翻译记忆、术语表、QA 四项能力配置为自有 LLM 时改为配置校验validateSettings并跳过上述四项平台能力启用--pseudo或配置了dev.usePseudotranslator时则进入伪本地化模式不产生任何外部 API 调用。三、Lingo.dev CI/CD推送即翻译的持续本地化持续本地化的目标是把人工补翻译从发布流程中彻底移除每次推送都会触发本地化缺失的字符串在代码到达生产环境之前自动补齐。仓库在 GitHub Actions、GitLab CI/CD 和 Bitbucket Pipelines 三个平台上均有支持CI 平台的抽象见 packages/cli/src/cli/cmd/ci/platforms分别有github.ts、gitlab.ts、bitbucket.ts实现。3.1 GitHub Action 的最小配置仓库根目录的 action.yml 定义了官方 ActionREADME 中的最小示例为uses: lingodotdev/lingo.devmain with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}从 action.yml 源码可见该 Action 本质是一个 composite 步骤内部调用npx lingo.devversion ci并透传以下全部输入参数Input说明默认值versionLingo.dev CLI 版本latestapi-key平台 API Key空pull-request是否创建 PR 提交翻译变更falsecommit-message提交信息feat: update translations via LingoDotDevpull-request-titlePR 标题同上commit-author-name提交作者名Lingo.devcommit-author-email提交作者邮箱supportlingo.devworking-directory工作目录适用于 monorepo 子目录.process-own-commits是否处理本 Action 产生的提交绕过死循环防护falseparallel是否并行处理翻译false3.2 ci 命令与两种提交模式GitHub Action 透传的底层命令是lingo.dev ci其完整参数见 packages/cli/src/cli/cmd/ci/index.ts除了与 Action 输入一一对应的选项外还有--parallel、--api-key、--gpg-sign等。其中--pull-request决定两种工作流实现位于 cmd/ci/flowsin-branch默认直接在当前分支提交翻译变更pull-request在专用分支上生成/更新翻译并自动创建或更新 Pull Request让翻译变更走代码评审流程。此外--process-own-commits与 Action 输入同名——默认情况下 CI 不会处理由自己产生的提交防止翻译→触发 CI→再翻译的死循环只有显式开启该选项才会处理这在 monorepo 或多工作流协作场景下需要谨慎使用。四、Lingo.dev MCP让 AI 助手安全地配置 React i18n在 React 应用中手工配置 i18n 容易出错——即使 AI 编码助手也会幻想出不存在的 API 并破坏路由。Lingo.dev MCPModel Context Protocol为 AI 助手提供框架特定的 i18n 结构化知识覆盖Next.js、React Router 和 TanStack Start兼容Claude Code、Cursor、GitHub Copilot Agents 和 Codex。它的工作方式是通过Set up i18n这类自然语言提示词让 AI 助手在 MCP 提供的框架知识约束下完成配置从而避免幻觉 API、错误路由等常见问题。这与仓库中 demo/new-compiler-vite-react-spaVite React SPA 示例等演示项目形成对照MCP 解决配置期的可靠性而 Compiler 解决运行时的简洁性。五、Lingo Compiler for React构建期本地化告别 i18n 包装器Lingo Compiler for React 是仓库中最具前瞻性的模块README 标注为早期 Alpha/早期测试版。它的核心理念是使用纯英文文本编写组件——编译器检测可翻译字符串并在构建时生成本地化版本。无需翻译键、无需 JSON 文件、无需t()函数。也就是说你的源码里不再出现t(auth.login)这类调用而是直接写Welcome back!编译器在构建阶段自动识别这些字符串、完成翻译注入并按语言生成对应产物。支持的框架为Next.jsApp Router与Vite React。仓库提供了两组可直接运行的最小示例demo/new-compiler-next16Next.js 16App Router示例包含app/page.tsx、components/Counter.tsx、components/ServerChild.tsx等组件以及next.config.ts中的withLingo()插件接入方式demo/new-compiler-vite-react-spaVite React SPA 示例public/translations/目录下直接以de.json、en.json、es.json、fr.json形式存放构建产物vite.config.ts中完成插件配置。5.1 编译器源码结构编译器的核心实现位于 packages/compiler/srcJSX 分析工具链jsx-attribute.ts、jsx-content.ts、jsx-element.ts、jsx-expressions.ts、jsx-scope.ts、jsx-variables.ts等模块负责从 AST 中识别可翻译的 JSX 属性、文本内容、表达式与作用域并配有大量.spec.ts测试指令与标记i18n-directive.ts、jsx-attribute-flag.ts、jsx-root-flag.ts、jsx-scope-flag.ts等实现按指令/标记控制哪些内容参与翻译字典加载器client-dictionary-loader.ts、rsc-dictionary-loader.ts、react-router-dictionary-loader.ts、lingo-turbopack-loader.ts分别面向客户端、RSC、React Router 与 Turbopack 场景注入字典更完整的下一代实现见 packages/new-compiler含 plugin/transform、react/client、react/server、react/shared、virtual/locale 等子模块并附有 TRANSLATION_ARCHITECTURE.md 架构文档。与 CLI 的提取既有键值文件思路不同Compiler 走的是源码驱动路线英文文本即键构建产物即翻译从根上消除了键名管理、JSON 字典同步、t() 调用散落各处的维护负担。六、Lingo.dev API后端代码直连本地化引擎当翻译需求发生在服务端而非构建期时可以直接从后端代码调用本地化引擎同步与异步两种模式同步调用适合即时返回异步调用适合批量任务webhook 交付异步翻译完成后通过 webhook 推送结果按语言环境隔离故障某个语言环境失败不会拖垮整个任务WebSocket 实时监控实时观察翻译进度。仓库中的 SDK 参考实现位于 packages/sdk/src/index.ts含abort-controller.spec.ts、index.spec.ts测试覆盖取消与核心行为其底层封装可参见 packages/cli/src/sdk/index.tsCLI 内部对平台 API 的调用如鉴权whoami、计价等也是同一套协议只是经过 CLI 层包装。七、从零接入的完整工作流综合以上模块一个典型的接入路径是初始化npx lingo.devlatest init生成i18n.json参考仓库根目录 i18n.json配置桶在buckets中声明各格式文件的 glob 规则如mdx: { include: [readme/[locale].md] }[locale]占位符会自动替换为目标语言代码本地翻译npx lingo.devlatest run配合--target-locale、--bucket、--key做定向翻译配合--pseudo做国际化就绪性自测接入 CI在 GitHub Actions或 GitLab CI/CD、Bitbucket Pipelines中引入lingodotdev/lingo.devmain配置api-key与pull-request实现每次推送自动补齐缺失翻译可选React 项目接入 Compiler 的withLingo()插件让组件直接书写英文文本构建期自动生成本地化产物参考 demo/new-compiler-next16 与 demo/new-compiler-vite-react-spa。八、参与贡献pnpm Turborepo 单体仓库本项目是一个pnpm Turborepo 单体仓库见根目录 pnpm-workspace.yaml、turbo.json仓库中并存packages/cliCLI 与 Loader、packages/compiler、packages/new-compiler、packages/react、packages/spec、packages/locales、packages/sdk、packages/logging等多个子包以及integrations/directus等集成。本地开发命令pnpm install # 安装依赖 pnpm test # 运行测试 pnpm build # 构建提交 PR 的约定每个 PR 需要一个变更集pnpm new非发布类变更用pnpm new:empty提交前确保测试通过。文档的本地化维护也遵循同样的工具链新增语言只需在 i18n.json 中加入 BCP-47 格式的语言代码然后通过本仓库自身的 CLI 完成翻译readme 目录下已沉淀 28 种语言版本包括本文对应的 readme/zh-Hans.md。九、总结Lingo.dev 的差异化在于工程化而非翻译本身Lockfile 增量机制让重复翻译成本趋近于零本地化引擎持久化术语表与品牌语调保证跨批次一致性MCP 把 AI 辅助 i18n 配置的幻觉风险结构化地消除Compiler 则把本地化从运行时库推进到构建期编译。无论是传统键值文件、文档站内容、移动端资源还是新一代 React 编译器方案这套工具链都提供了对应的开源实现可直接在本仓库中查看源码与测试验证其行为。说明本文引用的命令、参数与文件路径均以当前仓库实际源码与配置为准Lingo.dev 平台侧的在线服务如本地化引擎创建、WebSocket 监控需要访问官方文档进一步了解。【免费下载链接】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），仅供参考