企业官网建设流程全解析

Lingo.dev（replexica）开源本地化工程工具全景指南：从 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

Lingo.dev（本仓库 replexica）是一套开源本地化工程工具集，通过连接 Lingo.dev 本地化工程平台，为开发团队提供一致、高质量的翻译能力。本文以仓库根目录的 README 总览文档 readme/bho.md 为核心骨架，结合仓库源码与配置，系统讲解 MCP、CLI、GitHub Action、API 与 React Compiler 五大组件的功能定位、快速上手命令与底层实现机制，帮助你根据项目形态选择最合适的本地化接入方式。

项目定位：开源本地化工程工具

Lingo.dev 的定位是"开源本地化工程工具"，其核心思路是：开发团队在代码仓库中使用开源工具与命令行，翻译能力则由 Lingo.dev 本地化工程平台（有状态翻译 API）提供。文档原文将其描述为 "Open-source localization engineering tools. Connect to Lingo.dev localization engineering platform for consistent, quality translations."（开源本地化工程工具，连接 Lingo.dev 本地化工程平台，获得一致、优质的翻译），readme/bho.md 中同样保留了这一定位描述。

从仓库结构看，这是一个 pnpm + turborepo 的 monorepo（见根目录 package.json 的turbo build/test/typecheck脚本与packageManager: pnpm@11.10.0），核心工作区包括packages/cli（CLI 与 SDK）、packages/compiler（React 编译器）、packages/sdk（后端 SDK）、packages/spec（配置与格式规范）、packages/locales（语言代码）等，印证了"一套工具集"的定位。

快速上手：工具矩阵一览

README 用一个速查表概括了四类工具的用途与最快上手命令：

其中 CLI 实际提供了init与run两步命令（见后文"Lingo.dev CLI"小节），GitHub Action 底层调用的是 CLI 的ci命令（见 action.yml 中的npx lingo.dev@${{ inputs.version }} ci）。README 也明确指出这些工具可以连接平台上的本地化引擎，也可以自带 LLM。

本地化引擎：有状态的翻译 API

所有工具背后都对接"本地化引擎"（localization engines）——你在 Lingo.dev 平台上创建的有状态翻译 API。README 强调每个引擎会在每次请求中持久化术语表（glossary）、品牌语气（brand voice）与按语言区分的指令（per-locale instructions），据此将术语错误减少 16.6%–44.6%（该数据来自官方检索增强本地化研究报告，README 中如实引用）；当然，也可以选择在 CLI 中接入自己的 LLM。

这一设计在 packages/sdk/src/index.ts 的 SDK 实现中有清晰印证：engineParamsSchema定义了engineId（引擎标识）、apiUrl、batchSize、maxRetries、retryDelayMs等参数，本地化请求支持reference（参考译文）与hints（提示词）等字段——这些正是术语表与品牌指令在 API 层的数据载体。

Lingo.dev MCP：让 AI 助手正确配置 React i18n

在 React 应用中手工配置 i18n 极易出错，即使是 AI 编码助手也常会"幻想"出不存在的 API、破坏路由。Lingo.dev MCP 的解法是：为 AI 助手提供框架特定的结构化 i18n 知识，覆盖 Next.js、React Router 和 TanStack Start，兼容 Claude Code、Cursor、GitHub Copilot Agents 与 Codex。对开发者而言，在 AI 工具中启用该 MCP 后，只需给出提示词Set up i18n即可获得符合框架规范的 i18n 配置建议。

仓库中 demo/new-cli 与 demo/new-compiler-next16、demo/new-compiler-vite-react-spa 等演示项目，展示了不同框架下接入本地化的实际形态，可作为理解 MCP 输出目标的参考。

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

安装与两条核心命令

CLI 通过 npm 分发（包名lingo.dev，提供lingo与lingo.dev两个 bin 入口，见 packages/cli/package.json），使用 Node.js >= 18。README 给出的两条命令是：

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

• init：在项目中初始化本地化配置（生成i18n.json、settings.jsonc等）；
• run：执行本地化流水线，读取配置、计算变更、调用翻译并写回目标语言文件。

支持的文件格式

README 明确列出 JSON、YAML、Markdown、CSV、PO 五类核心格式。从 packages/cli/src/loaders 的 loader 实现看，实际支持远不止这些，还包括 Android XML、Flutter ARB、iOS Xcode strings/xcstrings/stringsdict、XLIFF、SRT/VTT 字幕、PHP、properties、Markdoc、MDX、MJML、EJS、Twig、TXT、HTML、JSON5/JSONC 等，且仓库 packages/cli/demo 下为每种格式都提供了en/es示例文件，例如 packages/cli/demo/json/en/example.json、packages/cli/demo/yaml/en/example.yml 与 packages/cli/demo/po/en/example.po。README 中"一条命令本地化多格式文件"的描述是保守的说法，实际覆盖面更广。

Lockfile：只翻译新增与变更内容

README 特别强调了 lockfile 机制："锁定文件跟踪已本地化的内容——仅处理新增或更改的内容"。仓库中 packages/cli/i18n.lock 与根目录 i18n.lock 即为实例，lockfile 的实现位于 packages/cli/src/utils/lockfile.ts，配套 packages/cli/src/cli/cmd/lockfile.ts 命令与 packages/cli/src/cli/lockfile.spec.ts 测试。这一机制让增量翻译成为可能：只有新增或内容发生变化的 key 才会被重新翻译，既省成本又保证已审校译文不被覆盖。

核心运行参数（来自 run 命令源码）

packages/cli/src/cli/cmd/run/index.ts 是run命令的入口，它定义了丰富的可选项，可精确控制一次翻译的范围与行为：

• --source-locale <code>：覆盖i18n.json中的源语言，用于本次运行；
• --target-locale <code>：只处理指定目标语言，可重复传入多个；
• --bucket <type>：只处理指定 bucket 类型（如json、yaml、android），可重复；
• --file <pattern>：按路径子串过滤 bucket 文件，例如messages.json或locale/；
• --key <prefix>：按点分路径前缀过滤 key，例如auth.login匹配所有以auth.login开头的 key；
• --force：绕过变更检测，强制重译所有 key（适合换模型或改翻译设置后重生成）；
• --frozen：只校验不修改，源文件、目标文件、lockfile 不同步即失败退出，适合 CI/CD 前置校验；
• --api-key <key>：覆盖 settings 或环境变量中的 API key；
• --concurrency <n>：并发翻译任务数，默认 10，最大 10；
• --watch：持续监听源文件变化并自动重译（配合--debounce <ms>，默认 5000ms 防抖）；
• --sound：完成时播放成功/失败音效（资产见 packages/cli/assets）；
• --pseudo：伪本地化模式，用带重音符号的字符与视觉标记"翻译"全部字符串，不调用任何外部 API，用于测试界面 i18n 就绪度；
• --estimate：打印待翻译内容的预估成本后退出，不实际翻译（不能与--watch/--frozen组合）。

run的执行流程为 setup → plan →（可选 estimate）→ frozen → execute → 输出摘要，最后按结果设置退出码；--watch模式下完成后进入文件监听循环。

默认引擎或自带 LLM

CLI 默认使用你在 Lingo.dev 平台创建的本地化引擎；也可以接入自己的 LLM。README 列举了 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）与之完全对应。翻译器的实现位于 packages/cli/src/localizer（lingodotdev.ts对接平台引擎、explicit.ts对接显式 LLM、pseudo.ts伪本地化）。

杂项命令

除init、run外，CLI 还提供ci（供 CI/CD 平台调用）、config get/set/unset（配置读写）、show files/locale/ignored-keys/locked-keys/preserved-keys（查看状态）、status、purge、cleanup、login/logout等命令（见 packages/cli/src/cli/cmd），帮助你在本地排查 lockfile、忽略键与锁定键的状态。

Lingo.dev CI/CD：在流水线中持续本地化

持续本地化（continuous localization）解决的是"代码改了、翻译没跟上"的问题：每次 push 都触发本地化，缺失字符串在代码进入生产环境前被自动补齐。README 声明支持 GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines。

GitHub Action 用法

README 给出的最小 YAML 片段为：

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

仓库根目录的 action.yml 是这条 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 }} shell: bash

Action 完整输入参数

除api-key外，Action 还暴露了以下可配置输入（均有默认值）：

• version：Lingo.dev CLI 版本，默认latest；
• pull-request：是否以 PR 形式提交翻译变更，默认false（false 时直接提交到当前分支）；
• commit-message：提交信息，默认feat: update translations via @LingoDotDev；
• pull-request-title：PR 标题，默认同上；
• commit-author-name/commit-author-email：提交作者信息，默认Lingo.dev/support@lingo.dev；
• working-directory：工作目录，默认.；
• process-own-commits：是否处理该 Action 自己提交的内容，默认false（防止触发循环翻译）；
• parallel：是否并行运行，默认false。

GitLab 与 Bitbucket 的接入同样由 CLI 的ci命令支撑——仓库中 packages/cli/src/cli/cmd/ci/platforms 下实现了github.ts、gitlab.ts、bitbucket.ts三个平台适配器，对应 pull-request 与 in-branch 两种提交流程（见 packages/cli/src/cli/cmd/ci/flows）。

Lingo.dev API / SDK：从后端代码直接调用引擎

当本地化需要由业务后端触发（而非构建或 CI 流程）时，可以绕过 CLI 直接调用本地化引擎：README 描述其支持同步与异步本地化、webhook 结果投递、按语言环境隔离失败、通过 WebSocket 实时查看进度。

仓库中 packages/sdk 与 packages/cli/src/sdk/index.ts 提供了 TypeScript SDK 实现。以 packages/sdk/src/index.ts 为例，SDK 暴露：

• engineParamsSchema：引擎级参数（apiKey、apiUrl、engineId、batchSize默认 25、maxRetries默认 3 次指数退避重试、retryDelayMs默认 500ms 等）；
• localizationParamsSchema：单次请求参数（sourceLocale、targetLocale、可选的reference参考译文、hints提示、filePath、triggerType: "cli" | "ci"等）；
• CostEstimate类型：/process/estimate接口返回的近似成本估算（字符数 → token 数的启发式，非正式报价）。

同步/异步模式、webhook 与 WebSocket 机制从 SDK 的类型与常量中可以推断其为引擎侧能力，CLI 的ci流程（packages/cli/src/cli/cmd/ci/index.ts）正是通过这类接口在后端完成"拉取变更 → 翻译 → 提交/开 PR"的闭环。

Lingo Compiler for React：无 i18n 包装器的构建时本地化

核心理念

Lingo Compiler for React（早期 Alpha）是文档矩阵中技术形态最特别的一个：构建时本地化，彻底去掉 i18n 包装层。用纯英文编写组件，编译器在构建时识别可翻译字符串并生成本地化变体——没有翻译 key、没有 JSON 文件、没有t()函数。当前支持 Next.js（App Router）与 Vite + React。

配置方式（withLingo 插件）

README 矩阵给出的快速命令是withLingo()插件。旧编译器迁移文档 packages/compiler/README.md 给出了新旧两代编译器的配置对照，新版（@lingo.dev/compiler）用法如下：

Next.js（App Router）

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

import { defineConfig, type UserConfig } from "vite"; import react from "@vitejs/plugin-react"; import { withLingo } from "@lingo.dev/compiler/vite"; const viteConfig: UserConfig = { plugins: [react()], }; export default defineConfig(async () => await withLingo(viteConfig, { sourceLocale: "en", targetLocales: ["es", "fr"], models: "lingo.dev", }) );

仓库中的实现与演示

新一代编译器位于 packages/new-compiler，其插件体系（packages/new-compiler/src/plugin）包含next.ts、vite.ts、webpack.ts、unplugin.ts以及 Next.js 各加载器（next-config-loader、next-locale-server-loader等），翻译服务则位于 packages/new-compiler/src/translation-server。仓库提供了两个可直接运行/构建的演示项目：

• demo/new-compiler-next16：Next.js 16 应用，含 App Router 页面与计数器等组件（如 demo/new-compiler-next16/components/Counter.tsx）；
• demo/new-compiler-vite-react-spa：Vite + React SPA，public/translations下已有de/en/es/fr四种语言的 JSON 翻译产物。

两者可作为理解"构建时生成本地化变体"这一工作方式的最小实验对象。

仓库自身的 dogfooding：i18n 配置与多语言文档

Lingo.dev 的一个特色是项目自己用自己。根目录 i18n.json 就是一份真实配置：locale.source为en，targets列出 27 种目标语言（含bho），buckets.mdx.include指向readme/[locale].md——这正是 readme 目录下 29 个语言版本 README 的生成来源。任何读者都可以参考这份配置理解i18n.json的字段语义：locale.source（源语言）、locale.targets（目标语言数组）、buckets.<名称>.include（glob 匹配规则，[locale]为语言占位符）。

README 还说明了为项目新增一种语言的步骤：

1. 使用 BCP-47 格式将语言代码加入 i18n.json；
2. 提交 Pull Request。

参与开发与本地构建

README 的贡献章节明确了开发与测试流程（亦与根 package.json 脚本一致）：这是一个 pnpm + turborepo 的 monorepo，贡献者应通过 Issue 报告问题、通过 PR 提交改动，且每个 PR 都需要 changeset（发布变更用pnpm new，非发布变更用pnpm new:empty）。常用命令：

pnpm install # 安装依赖 pnpm test # 运行测试（turbo 并行执行各包 vitest） pnpm build # 构建全部包

仓库根目录还提供 Dockerfile 与 action.yml，前者可用于容器化运行环境，后者即前文分析的 GitHub Action 定义；开发细节可进一步参考 CLAUDE.md 与 packages/cli/WATCH_MODE.md。

小结：如何选择接入方式

综合 README 文档与仓库源码，可以根据团队工作流选择合适的工具组合：

• AI 辅助配置阶段：用 Lingo React MCP 在 Claude Code / Cursor / Copilot Agents / Codex 中快速、正确地完成 i18n 搭建；
• 日常增量翻译：用 Lingo CLI（init+run），lockfile 保证只翻译新增与变更内容，--watch可本地实时翻译，--estimate可先看成本；
• 持续本地化：在 GitHub Actions / GitLab CI / Bitbucket Pipelines 中接入lingo.dev的ci流程，push 即翻译，产物可以是直接提交或自动创建的 PR；
• 后端集成：用 SDK/API 在业务代码中直接调用引擎，配合 webhook 与 WebSocket 获取结果与进度；
• 全新 React 项目：尝试 Compiler for React（早期 Alpha），用withLingo()插件在构建期完成本地化，彻底告别 key 与t()样板代码。

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