企业官网建设流程全解析

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.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 不享受引擎级术语与翻译记忆"的差异。

如果你不想依赖平台，也可以自带 LLM：CLI 支持 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.dev@latest init npx lingo.dev@latest run

• init：初始化项目，生成i18n.json配置文件（仓库根目录的 i18n.json 即是真实示例，其中locale.source为en，locale.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支持非常细粒度的控制参数：

其中几个参数值得展开：

• --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、PO（gettext）、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：平台引擎或自带 LLM

setup阶段会根据配置选择 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 定义了官方 Action，README 中的最小示例为：

uses: lingodotdev/lingo.dev@main with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

从 action.yml 源码可见，该 Action 本质是一个 composite 步骤，内部调用npx lingo.dev@<version> ci，并透传以下全部输入参数：

3.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/flows）：

• in-branch（默认）：直接在当前分支提交翻译变更；
• pull-request：在专用分支上生成/更新翻译，并自动创建或更新 Pull Request，让翻译变更走代码评审流程。

此外--process-own-commits与 Action 输入同名——默认情况下 CI 不会处理由自己产生的提交，防止"翻译→触发 CI→再翻译"的死循环；只有显式开启该选项才会处理，这在 monorepo 或多工作流协作场景下需要谨慎使用。

四、Lingo.dev MCP：让 AI 助手安全地配置 React i18n

在 React 应用中手工配置 i18n 容易出错——即使 AI 编码助手也会幻想出不存在的 API 并破坏路由。Lingo.dev MCP（Model 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-spa（Vite + React SPA 示例）等演示项目形成对照：MCP 解决"配置期"的可靠性，而 Compiler 解决"运行时"的简洁性。

五、Lingo Compiler for React：构建期本地化，告别 i18n 包装器

Lingo Compiler for React 是仓库中最具前瞻性的模块（README 标注为早期 Alpha/早期测试版）。它的核心理念是：

使用纯英文文本编写组件——编译器检测可翻译字符串并在构建时生成本地化版本。无需翻译键、无需 JSON 文件、无需t()函数。

也就是说，你的源码里不再出现t('auth.login')这类调用，而是直接写Welcome back!；编译器在构建阶段自动识别这些字符串、完成翻译注入，并按语言生成对应产物。支持的框架为Next.js（App Router）与Vite + React。

仓库提供了两组可直接运行的最小示例：

• demo/new-compiler-next16：Next.js 16（App Router）示例，包含app/page.tsx、components/Counter.tsx、components/ServerChild.tsx等组件，以及next.config.ts中的withLingo()插件接入方式；
• demo/new-compiler-vite-react-spa：Vite + React SPA 示例，public/translations/目录下直接以de.json、en.json、es.json、fr.json形式存放构建产物，vite.config.ts中完成插件配置。

5.1 编译器源码结构

编译器的核心实现位于 packages/compiler/src：

• JSX 分析工具链：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.ts；CLI 内部对平台 API 的调用（如鉴权whoami、计价等）也是同一套协议，只是经过 CLI 层包装。

七、从零接入的完整工作流

综合以上模块，一个典型的接入路径是：

1. 初始化：npx lingo.dev@latest init，生成i18n.json（参考仓库根目录 i18n.json）；
2. 配置桶：在buckets中声明各格式文件的 glob 规则（如"mdx": { "include": ["readme/[locale].md"] }），[locale]占位符会自动替换为目标语言代码；
3. 本地翻译：npx lingo.dev@latest run，配合--target-locale、--bucket、--key做定向翻译，配合--pseudo做国际化就绪性自测；
4. 接入 CI：在 GitHub Actions（或 GitLab CI/CD、Bitbucket Pipelines）中引入lingodotdev/lingo.dev@main，配置api-key与pull-request，实现每次推送自动补齐缺失翻译；
5. （可选）React 项目：接入 Compiler 的withLingo()插件，让组件直接书写英文文本，构建期自动生成本地化产物（参考 demo/new-compiler-next16 与 demo/new-compiler-vite-react-spa）。

八、参与贡献：pnpm + Turborepo 单体仓库

本项目是一个pnpm + Turborepo 单体仓库（见根目录 pnpm-workspace.yaml、turbo.json），仓库中并存packages/cli（CLI 与 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