企业官网建设流程全解析

Lingo.dev 本地化工程工具集深度解析：从 Lingo CLI 到 React Compiler 的 i18n 全流程指南

【免费下载链接】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 是一套开源的本地化（Localization）工程工具集，围绕"本地化引擎"（Localization Engine）这一有状态翻译 API 构建，帮助开发团队在命令行、CI/CD 流水线和 React 构建链路中自动完成高质量、术语一致的翻译。本文基于仓库根目录的 readme/hi.md 文档骨架，结合 packages/cli、packages/compiler、action.yml 等源码实现，完整讲解 Lingo React MCP、Lingo CLI、Lingo GitHub Action、Lingo API 与 Lingo Compiler for React 五大组件的用法、参数与底层机制，读完即可在自己的项目中落地一套端到端的自动化 i18n 方案。

项目概览：开源本地化工程工具集

仓库的核心定位是：

Open-source localization engineering tools. Connect to Lingo.dev localization engineering platform for consistent, quality translations.（开源本地化工程工具，连接 Lingo.dev 本地化工程平台，获得一致、高质量的翻译。）

整个工具集围绕五个可独立使用的模块组织，快速导航如下：

这五个模块分别对应仓库中的 packages/cli（CLI 与 CI 命令）、action.yml（GitHub Action 定义）、packages/compiler（编译器）以及 packages/sdk（API SDK）等实现。

本地化引擎：有状态翻译 API 的核心机制

理解这套工具之前，必须先理解"本地化引擎"（Localization Engine）这一概念。文档明确指出：这些工具都连接到在 Lingo.dev 本地化工程平台上创建的本地化引擎——这是一种有状态（stateful）的翻译 API。

引擎的有状态特性体现在三个关键维度：

1. 词汇表（Glossary）：每次翻译请求都会保留项目定义的术语表，确保"登录"始终翻译为 "Sign in" 而非 "Log in" 这类术语混用。
2. 品牌声音（Brand Voice）：翻译结果符合产品既定的语气风格，避免机器翻译的"翻译腔"。
3. 每语言指令（Per-locale Instructions）：针对每个目标语言单独配置的约束与说明，例如某些语言的形式/敬语规则。

文档引用平台研究数据称，这种检索增强式本地化机制可以将术语错误降低 16.6%–44.6%。该机制在源码层面由packages/cli/src/cli/localizer/lingodotdev.ts的 Lingodotdev Localizer 实现——它作为默认本地化器，将待翻译内容发送到 Lingo.dev 平台引擎处理；而packages/cli/src/cli/localizer/pseudo.ts则提供不依赖外部 API 的伪本地化模式，用于 UI 国际化就绪性测试。

如果你不想接入平台，文档也明确给出了替代方案：自带 LLM（Bring Your Own LLM），支持 OpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama 等多家模型供应商（详见下文 CLI 部分）。

Lingo.dev MCP：给 AI 编程助手装上 i18n 知识库

文档指出一个现实痛点：在 React 应用中搭建 i18n 是极易出错的工作——即使是 AI 编码助手也会幻觉出不存在的 API，或破坏路由结构。

Lingo.dev MCP 的解决方案是：通过 MCP（Model Context Protocol）协议，为 AI 助手提供框架特定的 i18n 结构化知识，覆盖：

• Next.js
• React Router
• TanStack Start

它兼容的主流 AI 编码工具包括 Claude Code、Cursor、GitHub Copilot Agents 与 Codex。使用方式极其简单——在支持的 AI 助手中发出提示词Set up i18n，助手即可依据框架知识完成配置，而非凭空猜测。

Lingo.dev CLI：一条命令本地化多种文件格式

CLI 是这套工具集中最核心、最常用的组件，对应 packages/cli 包。文档给出的基本工作流只有两条命令：

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

init用于初始化项目配置（生成 i18n.json 并创建 .gitignore 规则等），run则执行本地化管线。在仓库 packages/cli/demo 目录中保留了 30 余种格式的完整示例，覆盖 JSON、YAML、markdown、CSV、PO、MDX、Markdoc、Android XML、Flutter ARB、Xcode Strings/StringsDict/Xcstrings、XLIFF、PHP、Properties、SRT、VTT、HTML、EJS、Twig、TXT、Vue JSON 等，说明其解析层（packages/cli/src/cli/loaders/下的json.ts、yaml.ts、markdown.ts、csv.ts、po/index.ts、mdx.ts、android.ts、flutter.ts、xliff.ts等）覆盖面远超文档列出的五种基础格式。

锁文件机制：只翻译新增与变更内容

CLI 最重要的设计之一是锁文件（Lockfile）机制：i18n.lock跟踪哪些内容已经本地化，run时只处理新增或变更的内容，已翻译且未变化的字符串不会被重复调用翻译接口，从而大幅节省成本与时间。该机制由packages/cli/src/cli/cmd/run/plan.ts规划变更、packages/cli/src/cli/cmd/run/execute.ts执行，配套的i18n.lock文件可见于 packages/cli/demo 各格式示例目录，以及仓库根目录的 i18n.lock。

run 命令完整参数详解

结合源码 packages/cli/src/cli/cmd/run/index.ts 中run命令的 flags 定义，run支持以下参数：

此外，CLI 还提供ci（CI 模式，内部再分 in-branch 与 pull-request 两种流程）、show（查看配置/文件/键）、config（读取与设置配置）、status、purge、auth、login、logout、init等子命令，完整清单见 packages/cli/src/cli 目录。

Lingo.dev CI/CD：把本地化搬进流水线

文档强调的核心理念是持续本地化（Continuous Localization）：每次 push 都触发本地化，让缺失的翻译字符串在代码进入生产环境之前就被补齐。支持 GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines 三种主流平台——这一点在源码中有直接对应：packages/cli/src/cli/cmd/ci/platforms/下分别实现了github.ts、gitlab.ts、bitbucket.ts三个平台适配器。

GitHub Action 最小用法

文档给出的 YAML 示例：

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

完整输入参数

根据仓库根目录 action.yml 的定义，该 Action 的输入参数远比示例丰富：

从 action.yml 的实现看，该 Action 是一个 composite action，本质上是将上述参数透传给npx lingo.dev@<version> ci命令，由 CLI 的ci命令完成翻译、提交与 PR 创建全流程。这意味着 Action 的每一个输入都能在 CLI 的ci命令中找到对应参数，两者能力完全对齐。

Lingo.dev API：后端代码直连本地化引擎

文档指出，Lingo.dev API 允许你从后端代码直接调用自己的本地化引擎，其能力包括：

• 同步与异步本地化：可根据业务需要选择同步等待结果或异步处理；
• Webhook 投递：异步翻译完成后通过 Webhook 将结果推送给你的服务；
• 每语言失败隔离（Failure Isolation per Locale）：某个语言翻译失败不影响其他语言的产出，避免单点故障拖垮整批任务；
• WebSocket 实时进度：通过 WebSocket 订阅翻译任务的实时进度。

对应实现可见于 packages/sdk 包（packages/sdk/src/index.ts），其中还包含请求取消（abort-controller.spec.ts）与可观测性（observability.ts）相关实现，适合把本地化能力嵌入 Node.js 后端服务。

Lingo Compiler for React：没有 t() 函数的构建时本地化

这是文档中标注为早期 Alpha（Early alpha）的模块，也是理念上最激进的一个：

用纯英文文本编写组件——编译器自动检测可翻译字符串，并在构建时生成本地化变体。没有翻译键（translation keys）、没有 JSON 文件、没有t()函数。

也就是说，你不需要维护 key-value 的翻译字典，也不需要把每段文案包进t("...")，只需在 JSX 中写普通的英文文本，编译器在构建阶段完成字符串抽取、翻译与多语言产物生成。

从仓库实现看，对应代码在 packages/compiler（构建时转换逻辑，如jsx-content.ts、jsx-attribute.ts等字符串提取与转换模块）与 packages/new-compiler（新一代编译器，包含 Vite/Webpack/unplugin/Next 等接入方式）中，文档明确支持的目标框架为Next.js（App Router）与Vite + React。仓库 demo 目录下也提供了可运行的参考示例：new-compiler-next16/（Next.js 16 示例）与new-compiler-vite-react-spa/（Vite + React SPA 示例）。

贡献指南与本地化文档建设

开发环境：pnpm + turborepo 单仓

文档说明这是一个pnpm + turborepo 的 monorepo，贡献者需要遵循以下流程：

1. Issue：报告 Bug 或请求新功能；
2. Pull Request：每个 PR 必须附带 changeset——运行pnpm new（非发布类变更用pnpm new:empty），提交前确保测试通过；
3. 开发命令：
   • 安装依赖：pnpm install
   • 运行测试：pnpm test
   • 构建：pnpm build

仓库根目录的 pnpm-workspace.yaml、turbo.json 与 package.json 即为该工程化的实际配置。

多语言文档：i18n.json 配置实例

本仓库自身就是 CLI 工具的最佳实践案例——它的 README 通过i18n.json配置被翻译成了 29 种语言（包括本篇文章所依据的 readme/hi.md 印地语版本）。添加新语言的方法非常简单：

1. 使用 BCP-47 格式在根目录 i18n.json 中添加 locale 代码；
2. 提交 Pull Request。

以仓库实际配置为例，i18n.json 的结构为：

{ "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"] } } }

其中locale.source定义源语言，locale.targets列出全部目标语言，buckets声明需要本地化的文件模式（[locale]为占位符，会在翻译时替换为具体语言代码）。仓库 readme 目录下即存放了全部 29 个语言的 README 文件，正是这套配置的产出物——你也可以在 packages/cli/demo 的各个格式示例中看到i18n.json与i18n.lock的配套使用方式。

结语

Lingo.dev 的工具链覆盖了本地化的完整生命周期：MCP 帮助 AI 助手正确搭建 i18n，CLI 处理存量文件的批量本地化，GitHub Action 把翻译并入持续集成，API 服务后端动态翻译需求，Compiler 则从构建层面消灭翻译键样板代码。它们共享同一个本地化引擎，因此无论从哪个入口接入，都能获得一致的术语、品牌声音与逐语言指令约束。对于正在评估自动化 i18n 方案的团队，可以从 readme/hi.md（或英文原版 readme/en.md）出发，再对照 packages/cli/demo 中的格式示例，快速验证这套工具链在自己技术栈中的适用性。

【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica