企业官网建设流程全解析

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），从而保证翻译的一致性与质量。

本文将从源码与配置层面，逐一拆解文档中列出的五大工具：

1. Lingo React MCP—— 为 AI 编码助手提供 React i18n 结构化知识；
2. Lingo CLI—— 一条命令本地化 JSON / YAML / Markdown / CSV / PO 等格式文件；
3. Lingo GitHub Action（CI/CD）—— 把本地化嵌入推送流水线；
4. Lingo API—— 从后端代码直接调用本地化引擎；
5. Lingo Compiler for React—— 无需 i18n 包装器的构建期本地化。

读完本文，你将掌握每条命令、每个配置项的真实用法，并能从仓库源码定位其实现细节，直接在自己的项目中落地。

一、快速上手：五条工具速查表

文档开篇给出了一张"Quick Start"速查表，它定义了整个工具集的入口。整理为更完整的对照表：

四张"入口卡"的背后是同一条架构主线：所有工具都对接"本地化引擎"。所谓本地化引擎，是你在 Lingo.dev 平台上创建的有状态翻译 API。每次请求引擎都会携带术语表、品牌语气和按语言（per-locale）的指令上下文；文档引用的研究结论指出，这种基于检索增强的本地化方式可将术语错误降低 16.6%–44.6%。如果你不想使用平台引擎，也完全可以"自带 LLM"（Bring Your Own LLM）——这一点在 CLI 一节会展开。

仓库佐证：本地化引擎、术语表、品牌语气等概念与 packages/cli 中本地化器的实现一一对应（见下文"自带 LLM"部分）；根目录 i18n.json 是引擎/CLI 共享的配置入口。

二、Lingo React MCP：让 AI 助手不再"幻觉" i18n API

2.1 它解决什么问题

在 React 应用里手动搭建 i18n 是出了名的容易出错——即便是 AI 编码助手，也会幻觉出不存在的 API 并破坏路由。Lingo.dev MCP 的定位就是：给 AI 助手提供框架特定的 i18n 结构化知识，让它们按真实框架规范生成代码。

文档明确列出的适用框架与 AI 助手：

• 框架：Next.js、React Router、TanStack Start；
• AI 助手：Claude Code、Cursor、GitHub Copilot Agents、Codex。

2.2 典型工作流

在支持的 AI 助手中连接 MCP 后，直接发送自然语言提示词即可触发完整的 i18n 初始化流程，例如：

Set up i18n

AI 助手会依据 MCP 提供的框架知识完成：语言包文件创建、Provider 挂载、路由与动态参数处理等，而不是凭空捏造 API。这与 CLI 的init命令在思路上互为表里——一个面向 AI 助手，一个面向终端。

三、Lingo CLI：一条命令本地化所有主流格式

3.1 核心命令

文档给出的两条命令是 CLI 的最小闭环：

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

• init：交互式创建项目级配置文件i18n.json；
• run：执行本地化流水线。

源码佐证：init命令实现在 packages/cli/src/cli/cmd/init.ts，它会交互式询问源语言、目标语言、文件格式（bucket）与文件路径，最终通过saveConfig写出i18n.json；run命令实现在 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 code

3.3run的常用标志位（源码级）

run命令提供了丰富的 flag（见 packages/cli/src/cli/cmd/run/index.ts），文档未展开，这里从源码补齐：

--estimate与--watch/--frozen互斥（源码在 packages/cli/src/cli/cmd/run/index.ts 会直接抛错）。

3.4 自带 LLM：五家主流提供商 + 本地 Ollama

文档明确指出 CLI 默认使用 Lingo.dev 本地化引擎，也可以自带 LLM：OpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama。

源码实现在 packages/cli/src/cli/localizer/explicit.ts，每个提供商对应一个 case，并读取各自的环境变量：

在i18n.json的provider节点中声明即可切换到自带 LLM 模式：

{ "provider": { "id": "openai", "model": "gpt-4o", "settings": {} } }

注意：若填入不支持的 provider id，本地化器会直接抛出错误并提示"移除 provider 节点以切回 Lingo.dev"（见 explicit.ts）。

3.5i18n.json：CLI 与引擎共享的配置契约

仓库根目录的 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.dev@main 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 可以提取出全部可用输入参数：

4.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/flows）：
  • InBranchFlow：直接在当前分支提交翻译；
  • PullRequestFlow：在专用分支上创建/更新翻译，并自动管理 PR；
• --process-own-commits用于绕过"防无限循环"机制（避免 CI 提交 → 触发 CI → 再提交的死循环）；
• 除 Action 暴露的输入外，ci还支持--gpg-sign（GPG 签名提交）等参数。

五、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.js（App 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-next16（Next.js 16 示例）与 demo/new-compiler-vite-react-spa（Vite + React SPA 示例），是体验该能力的快速入口。

6.3 配置示例（以新编译器为准）

Next.js（App Router）：在next.config.ts中启用withLingo包装：

import type { NextConfig } from "next"; import { withLingo } from "@lingo.dev/compiler/next"; const nextConfig: NextConfig = {}; export default async function (): Promise<NextConfig> { 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 的开发规范：

1. Issue：报告 bug 或提出功能需求；
2. Pull Request：
   • 每个 PR 必须包含 changeset：pnpm new（非发布类变更用pnpm new:empty）；
   • 提交前确保测试通过；
3. 本地开发：
   • 安装依赖：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）生成的产物；
• 每个语言文件末尾的"本地化文档"章节都维护着全部语言版本的索引，新增语言只需两步：
  1. 按BCP-47 格式把语言代码加入根目录 i18n.json 的locale.targets；
  2. 提交 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