企业官网建设流程全解析

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.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 也支持自带 LLM（OpenAI、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.dev@latest init npx lingo.dev@latest run

init生成项目配置文件i18n.json，run执行本地化流水线。其最关键的工程特性是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。同时它也支持完全非交互的参数化初始化：

从源码可以看到，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]占位符会在运行时替换为具体语言代码；
• $schema：JSON 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）是本地化流水线的执行器，提供了丰富的细粒度控制：

从源码看，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.dev@latest login会打开浏览器完成 OAuth 认证并保存凭据（源码见 packages/cli/src/cli/cmd/login.ts，其内部采用 32 字节随机 verifier 的 PKCE 式会话、2 秒轮询、15 分钟超时）。在 CI 环境则推荐直接设置LINGO_API_KEY环境变量。

若不想使用 Lingo.dev 托管引擎，README 明确说明 CLI 支持自带 LLM：OpenAI、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.dev@main with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Action 定义位于仓库根目录 action.yml，其内部实际执行npx lingo.dev@<version> ci，并暴露了完整的输入参数：

这些参数与 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-time）React 本地化，无需任何 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-next16：Next.js App Router 演示，含app/page.tsx、components/Counter.tsx等组件，展示了普通英文 JSX 如何被编译为多语言产物；
• demo/new-compiler-vite-react-spa：Vite + React SPA 演示，其public/translations/下预置了de.json、en.json、es.json、fr.json四种语言的编译产物，可通过analyze-bundle.sh分析翻译产物的打包体积。

由于处于早期 alpha 阶段，该方案更适合在可接受实验性 API 变更的项目中先行试用。

参与贡献与本地化协作

贡献指南

项目欢迎社区贡献，遵循以下流程：

1. Issues：报告 Bug 或提交功能需求；
2. Pull Requests：提交代码变更，要求：
   • 每个 PR 必须附带 changeset：运行pnpm new（非发布类变更用pnpm new:empty）；
   • 提交前确保测试通过；
3. 开发环境：这是一个 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 等。新增语言只需两步：

1. 使用BCP-47 格式的 locale 代码将其添加到根目录 i18n.json 的locale.targets数组（正如上文展示的那样，该数组目前包含 27 个目标语言）；
2. 提交 Pull Request。

之后npx lingo.dev@latest 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