Replexica开源本地化工程工具集 —— 一站式接入 Lingo.dev 平台的多语言解决方案【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica本文以仓库 readme/pa-IN.md 为骨架结合 action.yml、i18n.json 及 packages/cli 等源码深入讲解 Replexica 的五大工具MCP、CLI、CI/CD、API、Compiler的定位、工作原理与实战用法。导读Replexica原 lingo.dev 开源仓库是一套开源本地化工程工具面向需要在代码库中持续产出高质量多语言翻译的开发团队。它以 localization engineering本地化工程为核心理念所有工具都连接到 Lingo.dev 平台上的本地化引擎stateful translation APIs引擎在每次请求中持久化术语表glossaries、品牌语气brand voice和按语言区分的指令per-locale instructions从而保证翻译的一致性与质量。本文将从源码与配置层面逐一拆解文档中列出的五大工具Lingo React MCP—— 为 AI 编码助手提供 React i18n 结构化知识Lingo CLI—— 一条命令本地化 JSON / YAML / Markdown / CSV / PO 等格式文件Lingo GitHub ActionCI/CD—— 把本地化嵌入推送流水线Lingo API—— 从后端代码直接调用本地化引擎Lingo Compiler for React—— 无需 i18n 包装器的构建期本地化。读完本文你将掌握每条命令、每个配置项的真实用法并能从仓库源码定位其实现细节直接在自己的项目中落地。一、快速上手五条工具速查表文档开篇给出了一张Quick Start速查表它定义了整个工具集的入口。整理为更完整的对照表工具作用快速命令 / 用法Lingo React MCP为 React 应用提供 AI 辅助的 i18n 配置向 AI 助手发送提示词Set 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。每次请求引擎都会携带术语表、品牌语气和按语言per-locale的指令上下文文档引用的研究结论指出这种基于检索增强的本地化方式可将术语错误降低 16.6%–44.6%。如果你不想使用平台引擎也完全可以自带 LLMBring Your Own LLM——这一点在 CLI 一节会展开。仓库佐证本地化引擎、术语表、品牌语气等概念与 packages/cli 中本地化器的实现一一对应见下文自带 LLM部分根目录 i18n.json 是引擎/CLI 共享的配置入口。二、Lingo React MCP让 AI 助手不再幻觉 i18n API2.1 它解决什么问题在 React 应用里手动搭建 i18n 是出了名的容易出错——即便是 AI 编码助手也会幻觉出不存在的 API 并破坏路由。Lingo.dev MCP 的定位就是给 AI 助手提供框架特定的 i18n 结构化知识让它们按真实框架规范生成代码。文档明确列出的适用框架与 AI 助手框架Next.js、React Router、TanStack StartAI 助手Claude Code、Cursor、GitHub Copilot Agents、Codex。2.2 典型工作流在支持的 AI 助手中连接 MCP 后直接发送自然语言提示词即可触发完整的 i18n 初始化流程例如Set up i18nAI 助手会依据 MCP 提供的框架知识完成语言包文件创建、Provider 挂载、路由与动态参数处理等而不是凭空捏造 API。这与 CLI 的init命令在思路上互为表里——一个面向 AI 助手一个面向终端。三、Lingo CLI一条命令本地化所有主流格式3.1 核心命令文档给出的两条命令是 CLI 的最小闭环npx lingo.devlatest init npx lingo.devlatest runinit交互式创建项目级配置文件i18n.jsonrun执行本地化流水线。源码佐证init命令实现在 packages/cli/src/cli/cmd/init.ts它会交互式询问源语言、目标语言、文件格式bucket与文件路径最终通过saveConfig写出i18n.jsonrun命令实现在 packages/cli/src/cli/cmd/run/index.ts。3.2 lockfile增量本地化的关键机制文档强调了一个核心设计lockfile 追踪已本地化的内容只有新增或变更的内容才会被处理。仓库根目录 i18n.lock 以及 packages/cli/demo 下每个示例目录中的i18n.lock都是这一机制的产物每次run会先做变更检测plan再只翻译增量部分既节省成本又避免覆盖人工修正。run命令的完整执行链路从 packages/cli/src/cli/cmd/run/index.ts 可看到setup → plan → frozen校验→ execute执行翻译→ renderSummary → exit code3.3run的常用标志位源码级run命令提供了丰富的 flag见 packages/cli/src/cli/cmd/run/index.ts文档未展开这里从源码补齐标志作用默认值--source-locale locale覆盖i18n.json中的源语言取配置--target-locale locale只处理指定目标语言可重复传全部目标语言--bucket bucket只处理指定 bucket 类型如json、yaml、android全部 bucket--file file按子串过滤 bucket 路径如messages.json无--key key按点分路径前缀过滤 key如auth.login无--force强制重新翻译所有 key绕过变更检测关闭--frozen只校验不修改源文件/目标文件/lockfile 不同步则失败——适合 CI 前置校验关闭--api-key api-key覆盖 API Key设置或环境变量--concurrency n并发翻译任务数10上限 10--watch持续监听源语言文件变更自动重译关闭--debounce mswatch 模式下的防抖延迟5000ms--sound翻译完成时播放成功/失败音效assets 中自带 success.mp3 / failure.mp3关闭--pseudo伪本地化模式不调用外部 API用重音字符和视觉标记伪翻译所有字符串用于测试 UI 国际化就绪度关闭--estimate仅打印待翻译内容的预估成本并退出不做翻译关闭--estimate与--watch/--frozen互斥源码在 packages/cli/src/cli/cmd/run/index.ts 会直接抛错。3.4 自带 LLM五家主流提供商 本地 Ollama文档明确指出 CLI 默认使用 Lingo.dev 本地化引擎也可以自带 LLMOpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama。源码实现在 packages/cli/src/cli/localizer/explicit.ts每个提供商对应一个 case并读取各自的环境变量provider id使用的 SDKAPI Key 环境变量openaiai-sdk/openaiOPENAI_API_KEYanthropicai-sdk/anthropicANTHROPIC_API_KEYgoogleai-sdk/googleGOOGLE_API_KEYopenrouteropenrouter/ai-sdk-providerOPENROUTER_API_KEYmistralai-sdk/mistralMISTRAL_API_KEYollamaollama-ai-provider-v2本地模型无需云端 Key—在i18n.json的provider节点中声明即可切换到自带 LLM 模式{ provider: { id: openai, model: gpt-4o, settings: {} } }注意若填入不支持的 provider id本地化器会直接抛出错误并提示移除 provider 节点以切回 Lingo.dev见 explicit.ts。3.5i18n.jsonCLI 与引擎共享的配置契约仓库根目录的 i18n.json 即真实配置样例它同时被 CLI 解析与平台引擎消费{ 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源语言与目标语言列表本文档 pa-IN.md 本身正是该配置targets中的pa-IN目标语言的产物buckets定义从哪些文件提取/写入翻译include支持[locale]占位符——readme/[locale].md表示按语言替换占位符生成各语言文档$schema编辑器校验用的 JSON Schema 地址。延伸阅读packages/cli/demo 下每个示例目录都提供了一整套可运行的示例包括i18n.json、示例文件与i18n.lock覆盖 json、yaml、csv、mdx、markdown、flutter(arb)、android(xml)、po、properties、srt、vtt、xliff、xcode-strings 等 20 种格式是理解 bucket 机制的最佳实景教材。四、Lingo GitHub Action把本地化嵌入推送流水线4.1 最小接入文档给出的 CI/CD 最小配置uses: lingodotdev/lingo.devmain with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}仓库根目录 action.yml 就是该 Action 的完整定义它是一个composite action内部实际调用的是 CLI 的ci子命令runs: using: composite steps: - name: Run run: | npx lingo.dev${{ inputs.version }} ci \ --api-key ${{ inputs.api-key }} \ --pull-request ${{ inputs.pull-request }} \ --commit-message ${{ inputs.commit-message }} \ --pull-request-title ${{ inputs.pull-request-title }} \ --commit-author-name ${{ inputs.commit-author-name }} \ --commit-author-email ${{ inputs.commit-author-email }} \ --working-directory ${{ inputs.working-directory }} \ --process-own-commits ${{ inputs.process-own-commits }} \ --parallel ${{ inputs.parallel }}4.2 全部 inputs 一览从 action.yml 可以提取出全部可用输入参数输入说明默认值versionLingo.dev CLI 版本latestapi-key平台 API Key建议用secrets.LINGODOTDEV_API_KEY空pull-request是否创建包含翻译变更的 Pull Requestfalsecommit-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是否并行处理false4.3 底层ci命令与平台支持文档说明该机制支持GitHub Actions、GitLab CI/CD、Bitbucket Pipelines三种平台。从源码看ci命令实现在 packages/cli/src/cli/cmd/ci/index.ts其设计要点通过getPlatformKit()自动识别当前 CI 平台对应 packages/cli/src/cli/cmd/ci/platforms 下的github.ts/gitlab.ts/bitbucket.ts根据--pull-request开关选择两种流水线模式packages/cli/src/cli/cmd/ci/flowsInBranchFlow直接在当前分支提交翻译PullRequestFlow在专用分支上创建/更新翻译并自动管理 PR--process-own-commits用于绕过防无限循环机制避免 CI 提交 → 触发 CI → 再提交的死循环除 Action 暴露的输入外ci还支持--gpg-signGPG 签名提交等参数。五、Lingo API从后端代码直接调用本地化引擎文档对 API 的描述是从后端代码直接调用本地化引擎支持同步与异步本地化异步场景通过 Webhook 回传结果按语言隔离失败failure isolation per locale——单个语言失败不影响其他语言WebSocket 实时进度。典型适用场景动态内容用户生成内容、CMS 条目、运营文案需要在后端运行时即时翻译而不是走构建期流水线。对应文档见 packages/sdk 与 SDK 参考实现 packages/cli/src/sdk。六、Lingo Compiler for React摆脱t()函数的构建期本地化6.1 核心理念文档将其定位为Early alpha阶段的实验性能力核心理念非常激进直接用纯英文文本写组件——编译器在构建期检测可翻译字符串并生成各语言的本地化变体。没有翻译 key、没有 JSON 文件、没有t()函数。支持范围Next.jsApp Router与Vite React。6.2 仓库中的对应实现新旧两代实现并存旧实现位于 packages/compiler/README.md已标记 deprecated建议迁移到lingo.dev/compiler新实现位于 packages/new-compiler新编译器入口 packages/new-compiler/src/index.ts按构建工具拆分为 unplugin / webpack / vite / next 等插件形态并附带独立的翻译服务packages/new-compiler/src/translation-server仓库中还提供两个可直接运行的演示工程demo/new-compiler-next16Next.js 16 示例与 demo/new-compiler-vite-react-spaVite React SPA 示例是体验该能力的快速入口。6.3 配置示例以新编译器为准Next.jsApp Router在next.config.ts中启用withLingo包装import type { NextConfig } from next; import { withLingo } from lingo.dev/compiler/next; const nextConfig: NextConfig {}; export default async function (): PromiseNextConfig { return await withLingo(nextConfig, { sourceLocale: en, targetLocales: [es, fr], models: lingo.dev, }); }Vite React在vite.config.ts中注册插件import { defineConfig, type UserConfig } from vite; import react from vitejs/plugin-react; import lingoCompiler from lingo.dev/_compiler; const viteConfig: UserConfig { plugins: [react()], }; export default defineConfig(() lingoCompiler.vite({ models: lingo.dev, })(viteConfig) );启用后组件内直接书写英文文案即可构建产物会自动包含各语言的本地化版本无需手动维护翻译 key 与字典文件。七、参与贡献monorepo 开发约定文档的贡献章节定义了这个 pnpm turborepo monorepo 的开发规范Issue报告 bug 或提出功能需求Pull Request每个 PR 必须包含 changesetpnpm new非发布类变更用pnpm new:empty提交前确保测试通过本地开发安装依赖pnpm install运行测试pnpm test构建pnpm build仓库佐证根目录 package.json、pnpm-workspace.yaml 与 turbo.json 构成 monorepo 骨架CONTRIBUTING.md 与 CLAUDE.md 提供了更细的协作约定。八、多语言文档体系i18n.json驱动整个仓库自身一个非常有意思的细节本仓库自己的多语言 README 体系就是 Lingo 工具集自举dogfooding的产物。根目录 i18n.json 的buckets.mdx.include配置为readme/[locale].md意即以readme/en.md为源为targets中列出的 28 个目标语言各生成一份readme/locale.md本文的关联文档 readme/pa-IN.md 正是这条流水线为旁遮普语pa-IN生成的产物每个语言文件末尾的本地化文档章节都维护着全部语言版本的索引新增语言只需两步按BCP-47 格式把语言代码加入根目录 i18n.json 的locale.targets提交 Pull Request。这也是持续本地化理念在真实仓库中的最小可观察示例改动i18n.json→ 触发翻译 → 生成/更新各语言文档 → 合入。结语Replexica 把本地化从零散的翻译脚本升级为一套工程体系MCP 为 AI 助手补上框架知识CLI 以 lockfile 增量机制覆盖全格式文件GitHub Action 把翻译搬进流水线API 满足运行时动态内容Compiler 则在构建期消灭翻译样板代码。无论你是想在 CI 里自动补齐缺失字符串还是想试验无 key 无字典的编译期翻译都可以从本文的配置与源码索引出发直接落地。【免费下载链接】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），仅供参考