2026/9/18 23:06:46
FEATURED · 精选文章 
Lingo.dev 本地化工程工具链完全指南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本文以开源仓库replexica中的 readme/bn.mdLingo.dev 项目的多语言 README为骨架系统讲解 Lingo.dev 这一开源本地化工程工具链的四大组成——Lingo React MCP、Lingo CLI、Lingo GitHub Action 与 Lingo Compiler for React并结合仓库源码与示例工程帮助你掌握从单机批量翻译文件、接入自有 LLM到在 CI/CD 流水线中实现持续本地化、再到免 i18n 包装器的构建期 React 本地化的完整实战方案。读完本文你将能独立完成npx lingo.devlatest init run的最小落地并理解 lockfile 增量翻译、i18n.json配置体系与 Compiler 转换管线的底层原理。项目定位连接 Lingo.dev 本地化工程平台的开源工具Lingo.dev 是一套开源本地化工程工具Open-source localization engineering tools核心定位是连接 Lingo.dev 本地化工程平台为团队提供一致、高质量的翻译。仓库整体采用 pnpm turborepo 的 monorepo 结构核心工作负载分布在packages/cliCLI 与各格式 loader、packages/speci18n.json配置 schema、packages/sdkLingoDotDevEngine 平台 SDK、packages/new-compilerReact 编译器等包中仓库根目录还有 action.yml 提供 GitHub Action 复合运行步骤。本地化引擎Localization Engines状态化的翻译 API这些工具统一连接到本地化引擎——你在 Lingo.dev 本地化工程平台上创建的状态化翻译 API。每个引擎会在每一次请求中持久保存三样东西术语表Glossary保证品牌术语、产品名词翻译一致品牌声音Brand Voice维持文案语气与调性逐语言环境的指令Per-locale Instructions为每个目标语言定制翻译约束。根据项目方公布的研究结论这种检索增强式本地化Retrieval-Augmented Localization方案可将术语错误降低 16.6%–44.6%。当然如果不希望把翻译请求发送到平台CLI 也支持**自带 LLMBring Your Own LLM**模式在下一节详细展开。快速上手四类工具的定位与一条命令原文档给出了一张非常精炼的工具速查表这里完整保留并补充仓库内的对应实现位置工具作用快速命令仓库实现Lingo React MCP为 React 应用提供 AI 辅助的 i18n 设置提示词Set up i18n框架 i18n 知识注入 AI 助手Lingo CLI本地化 JSON、YAML、markdown、CSV、PO 等文件npx lingo.devlatest runpackages/cli/src/cli/cmd/run/index.tsLingo GitHub Action在 GitHub Actions 中实现持续本地化uses: lingodotdev/lingo.devmainaction.ymlLingo Compiler for React无 i18n 包装器的构建期 React 本地化早期 alphawithLingo()插件packages/new-compiler/src/plugin/transform其中 CLI 与 GitHub Action 的封装关系值得注意Action 内部实际上是通过npx lingo.devversion ci调用 CLI 的ci子命令完成的见 action.yml因此掌握 CLI 是理解整套工具链的基础。Lingo.dev MCP让 AI 助手学会正确的 React i18n在 React 应用中手动设置 i18n 很容易出错——即便是 AI 编程助手也会凭空臆造不存在的 API甚至破坏路由结构。这是 Lingo.dev MCP 要解决的问题。MCPModel Context Protocol为 AI 助手提供了结构化的、框架特定的 i18n 知识访问能力覆盖Next.jsApp Router / Pages Router 的 i18n 约定React Router路由级本地化接入TanStack Start新型全栈框架的 i18n 模式。它可以配合Claude Code、Cursor、GitHub Copilot Agents 和 Codex等主流 AI 编码工具使用。典型的使用方式是直接向 AI 助手发出提示词Set up i18n助手基于 MCP 提供的框架知识完成 i18n 初始化而不再靠猜测 API来写代码。这一工具解决的是开发期配置正确性问题与下面 CLI 解决的翻译文件生产问题形成互补。Lingo.dev CLI一条命令本地化任意格式文件CLI 是整套工具链的中枢。原文档的核心用法是两行命令npx lingo.devlatest init npx lingo.devlatest runinit初始化项目生成i18n.json配置文件run读取配置执行本地化流水线。lockfile只翻译新增或变更的内容CLI 通过一个lockfilei18n.lock记录哪些内容已经被本地化每次运行只处理新增或修改过的内容从而节省 API 调用与费用。仓库中还提供了独立的lingo.dev lockfile子命令用于根据当前源语言内容生成或刷新i18n.lock支持--force强制覆盖已有校验和以重置翻译跟踪见 packages/cli/src/cli/cmd/lockfile.ts。在增量校验--frozen、变更检测等场景下lockfile 都是判断源文件是否已更新、目标文件是否缺失翻译的依据。支持的格式远超文档列举的五种原文档列举了 JSON、YAML、markdown、CSV 和 PO 五种格式而实际上 loader 系统覆盖了数十种 bucket 类型。从 packages/cli/src/cli/loaders/index.ts 的 loader 组合工厂可以看到完整清单通用配置json、json5、jsonc、yaml、yaml-root-key、json-dictionary、properties、php文档与标记markdown、markdoc、mdx、html、ejs、twig、txt、mjml表格数据csv、csv-per-locale软件本地化pogettext、xliff、xml、androidAndroid strings.xml、flutterARBApple 生态xcode-strings、xcode-stringsdict、xcode-xcstrings、xcode-xcstrings-v2字幕srt、vtt前端框架typescript、vue-json、ail、dato每种类型都由多个 loader 以流水线方式组合而成如createTextFileLoader → createJsonLoader → createFlatLoader → createLockedKeysLoader → …实现统一的键值扁平化、键锁定、格式规范化等能力。配置体系i18n.json 详解i18n.json是 CLI 的核心配置其 schema 定义在 packages/spec/src/config.ts从 v0 一路演进到 v1.15包含以下关键字段字段说明version配置 schema 版本号当前最新为1.15$schemaJSON Schema 地址用于编辑器校验locale.source源语言代码如en、en-US、pt_BR、pt-rBR支持-、_、Android-r三种记法locale.targets目标语言代码数组locale.extraSource可选的额外源语言作为翻译时的回退buckets桶配置bucket 类型 → { include, exclude, injectLocale, keyColumn, … }formatter输出格式化工具prettier或biome未指定时默认 prettierprovider自带 LLM 时的翻译服务商配置见下文engineId指定 Lingo.dev 平台上的本地化引擎 IDdev开发期设置如usePseudotranslator使用伪翻译而非真实翻译便于免 API 调用测试 i18n其中buckets是配置的重心。以仓库 packages/cli/demo/json/i18n.json 中的真实示例为蓝本{ version: 1.12, locale: { source: en, targets: [es] }, buckets: { json: { include: [./[locale]/example.json], // [locale] 占位符会被替换为具体语言 lockedKeys: [locked_key_1], // 这些键永不参与翻译、不被覆盖 preservedKeys: [preserved_key_1, legal/preserved_nested] // 占位加入目标文件但之后不被覆盖 } }, $schema: https://lingo.dev/schema/i18n.json }每个 bucket 还支持exclude排除路径/glob、lockedPatterns正则锁定内容、ignoredKeys完全忽略的键、localizableKeys强制翻译的键例如本应被跳过为不可翻译的纯数字、URL、日期当它们有自定义术语表规则时使用、injectLocale注入/移除当前语言的键、keyColumnCSV 桶指定作为行唯一标识的列默认取首列等选项。文件路径通过[locale]占位符定位各语言文件并可用**递归匹配。run 命令的完整选项在run子命令的实现packages/cli/src/cli/cmd/run/index.ts中可以看到完整的运行时参数选项作用--source-locale code本次运行覆盖源语言--target-locale code只处理指定的目标语言可重复传入多个--bucket type只处理指定桶类型如json、yaml、android--file substr按文件路径子串过滤桶路径如messages.json或locale/--key prefix按点分路径前缀过滤键如auth.login匹配所有以auth.login开头的键--force跳过变更检测强制重译所有键适合升级模型或翻译设置后重新生成--frozen只校验不修改若源文件/目标文件/lockfile 不同步则失败适合 CI 部署前一致性检查--api-key key覆盖 API Key优先级高于 settings 与环境变量--debug处理前暂停便于附加调试器--concurrency n并发翻译任务数默认 10最大 10调大可加速大批量但增加内存占用--watch持续监听源语言文件变更时自动重新翻译--debounce mswatch 模式下文件变更后的防抖延迟默认 5000ms--sound翻译完成时播放提示音成功/失败见packages/cli/assets/下的 mp3--pseudo伪本地化模式用带重音字符与视觉标记的伪翻译替换全部字符串不调用任何外部 API用于 UI 国际化就绪性测试--estimate预估待翻译内容的成本后退出不能与--watch/--frozen组合其中--pseudo对应 packages/cli/src/cli/localizer/pseudo.ts 的伪本地化实现--estimate则通过平台 API 对同样的变更增量计价属于估算而非报价。认证方式与自带 LLMBYOKCLI 默认使用 Lingo.dev 平台引擎。认证有三条路径见 packages/cli/src/cli/localizer/lingodotdev.ts运行lingo.dev login交互式登录使用--api-key参数显式传入 API Key设置LINGO_API_KEY环境变量。而一旦在i18n.json中配置了provider字段CLI 就会切换为BYOKBring Your Own Key模式跳过平台认证直接调用你指定的 LLM见 packages/cli/src/cli/localizer/index.ts。provider 支持的服务商由 schema 枚举限定packages/spec/src/config.tsOpenAIAnthropicGoogleMistralOpenRouterOllama本地模型provider 配置示例{ provider: { id: openai, model: gpt-4o, // 使用的模型名 prompt: Translate the following JSON…, // 翻译请求的提示词模板 baseUrl: https://…, // 可选自定义 API 基地址 settings: { temperature: 0.3 } // 可选模型参数0确定2随机部分模型要求 temperature1 } }最小实战流程结合仓库 packages/cli/demo 下覆盖 30 余种格式的示例工程一个典型流程是准备源语言文件例如en/example.json并创建i18n.json指定locale.source: en、targets: [es]与buckets.json.include: [./[locale]/example.json]执行npx lingo.devlatest init完成初始化与认证执行npx lingo.devlatest runCLI 会生成i18n.lock、对比增量、调用翻译引擎并写回es/example.json增量场景再次执行run时只有变更的键会被重新翻译。持续本地化CI/CD 集成GitHub / GitLab / Bitbucket原文档强调的核心价值把本地化放进流水线每次 push 触发翻译缺失的字符串在代码进入生产环境之前就被补齐。支持的平台包括 GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines。GitHub Action 的最小用法原文档示例uses: lingodotdev/lingo.devmain with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}Action 的完整输入参数定义在仓库根目录 action.yml全部可选且有默认值输入默认值说明versionlatestCLI 版本api-key空Lingo.dev 平台 API Key建议通过 secrets 传入pull-requestfalse是否创建 PR 提交翻译变更commit-messagefeat: update translations via LingoDotDev提交信息pull-request-titlefeat: update translations via LingoDotDevPR 标题commit-author-nameLingo.dev提交作者名commit-author-emailsupportlingo.dev提交作者邮箱working-directory.工作目录monorepo 中本地化文件位于子目录时很有用process-own-commitsfalse是否处理本 Action 自己产生的提交绕过防无限循环机制parallelfalse是否并发处理翻译以加速执行该 Action 内部执行的是npx lingo.devversion ci命令action.yml对应 CLI 的ci子命令packages/cli/src/cli/cmd/ci/index.ts。ci命令同样暴露了--parallel、--pull-request、--commit-message、--pull-request-title、--commit-author-name、--commit-author-email、--working-directory、--process-own-commits、--gpg-signGPG 签名提交等选项并支持in-branch直接提交到当前分支与 pull-request在独立分支上更新翻译并自动管理 PR两种流程见 packages/cli/src/cli/cmd/ci/flows平台适配层则抽象了 GitHub / GitLab / Bitbucket 三套 APIpackages/cli/src/cli/cmd/ci/platforms。在 CI 场景中还可以结合run --frozen做只读校验不产生任何变更一旦源文件、目标文件或 lockfile 不同步就直接以非零退出码失败从而在部署前守住翻译一致性底线。Lingo.dev API从后端直接调用本地化引擎当本地化需求发生在后端代码内部而不是仓库文件时可以直接通过 API 调用你的本地化引擎。原文档明确了 API 的四大能力同步与异步本地化按场景选择等待结果或异步处理Webhook 交付异步任务完成时通过 webhook 推送结果按语言环境失败隔离单个 locale 的翻译失败不会拖垮整体WebSocket 实时进度长耗时任务可实时获取进度。在仓库侧CLI 的 Lingo.dev provider 正是通过lingo.dev/_sdk即 packages/sdk中的LingoDotDevEngine客户端与平台 API 通信包括whoami()鉴权探测、localizeObject()批量翻译与estimate()成本估算见 packages/cli/src/cli/localizer/lingodotdev.ts。SDK 的 packages/sdk/src/index.ts 提供了可复用的 TypeScript 客户端实现可作为后端集成的参考。Lingo Compiler for React早期 alpha免包装器的构建期本地化这是工具链中最具颠覆性的组件。原文档给出的理念非常明确用普通英文文本编写组件——编译器在构建期识别可翻译字符串并生成本地化版本。没有翻译键、没有 JSON 文件、没有t()函数。支持的框架Next.jsApp Router与Vite React。仓库中对应的两个示例工程分别是 demo/new-compiler-next16 与 demo/new-compiler-vite-react-spa。从源码文档 packages/new-compiler/src/plugin/transform/TRANSFORMATION_PIPELINE.md 可以看到完整的转换管线Source JSX → Babel Parser → AST Transformation → Code Generation → Transformed JSX ↓ Metadata Extraction ↓ .lingo/metadata-{env}/ (LMDB 元数据库)管线分五个阶段文件过滤只处理.tsx/.jsx文件跳过node_modules支持自定义跳过规则可选use i18n指令模式代码解析用babel/parser将源码解析为 AST启用jsx、typescript插件组件识别识别返回 JSX 的函数声明、箭头函数、函数表达式默认视为 Server Component带use client指令的视为 Client Component文本提取遍历 JSX 文本节点如divHello World/div、h1Welcome!/h1会被转换纯空白文本与{variable}表达式跳过基于**文本内容 上下文组件名、文件路径**生成唯一哈希并记录源文本、上下文、行列号、时间戳等元数据代码转换把文本替换为翻译调用。例如 Server Component 会被改写为通过getServerTranslations({ hashes: [...] })获取翻译并解构出t进行渲染TRANSFORMATION_PIPELINE.md。这种设计把字符串如何翻译、翻译放哪里完全托管给编译器与元数据库业务代码只需写纯英文文案大幅降低 i18n 的侵入性。需要提醒的是该组件目前处于早期 alpha阶段生产环境使用前应充分评估稳定性。参与贡献与多语言文档仓库欢迎社区贡献规范如下详见 CONTRIBUTING.mdIssues报告 bug 或请求功能Pull Requests每个 PR 需要携带 changeset发布类变更执行pnpm new非发布类变更执行pnpm new:empty提交前需确保测试通过开发环境这是一个 pnpm turborepo monorepo安装依赖pnpm install、运行测试pnpm test、构建pnpm build。该仓库本身也是自身工具的自举案例根目录 i18n.json 与 i18n.lock 管理着 readme 目录下 30 余种语言的 README 翻译含本文对应的 readme/bn.md。如果你希望新增一种语言步骤非常轻量使用 BCP-47 格式在根目录 i18n.json 中添加语言代码提交 Pull Request。总结一条从开发到上线的本地化链路把四个工具串联起来就构成了一条完整的本地化工程链路开发期Lingo React MCP 帮助 AI 助手正确初始化框架 i18nLingo Compiler 让你用纯英文文案写组件构建期自动产出各语言版本内容期Lingo CLI 配合 lockfile 增量机制将 JSON、YAML、Markdown、CSV、PO 及数十种格式的文件批量翻译默认走 Lingo.dev 引擎也可切换 OpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama 等自带 LLM上线期GitHub Actions / GitLab CI / Bitbucket Pipelines 中的持续本地化确保每次 push 后缺失字符串在代码到达生产前被补齐--frozen模式可在部署前做一致性校验后端集成Lingo.dev API 以同步/异步、webhook、WebSocket 方式满足动态内容翻译需求。无论你的团队采用文件翻译 持续集成的传统路线还是拥抱构建期编译 AI 辅助的新范式这套工具链都提供了可落地的开源实现本文涉及的源码与示例工程均可在仓库内进一步查阅验证。【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Lingo.dev 本地化工程工具链完全指南：CLI 批量翻译、CI/CD 持续本地化与 React 构建期编译实战
Lingo.dev 本地化工程工具链完全指南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本文以开源仓库replexica中的 readme/bn.mdLingo.dev 项目的多语言 README为骨架系统讲解 Lingo.dev 这一开源本地化工程工具链的四大组成——Lingo React MCP、Lingo CLI、Lingo GitHub Action 与 Lingo Compiler for React并结合仓库源码与示例工程帮助你掌握从单机批量翻译文件、接入自有 LLM到在 CI/CD 流水线中实现持续本地化、再到免 i18n 包装器的构建期 React 本地化的完整实战方案。读完本文你将能独立完成npx lingo.devlatest init run的最小落地并理解 lockfile 增量翻译、i18n.json配置体系与 Compiler 转换管线的底层原理。项目定位连接 Lingo.dev 本地化工程平台的开源工具Lingo.dev 是一套开源本地化工程工具Open-source localization engineering tools核心定位是连接 Lingo.dev 本地化工程平台为团队提供一致、高质量的翻译。仓库整体采用 pnpm turborepo 的 monorepo 结构核心工作负载分布在packages/cliCLI 与各格式 loader、packages/speci18n.json配置 schema、packages/sdkLingoDotDevEngine 平台 SDK、packages/new-compilerReact 编译器等包中仓库根目录还有 action.yml 提供 GitHub Action 复合运行步骤。本地化引擎Localization Engines状态化的翻译 API这些工具统一连接到本地化引擎——你在 Lingo.dev 本地化工程平台上创建的状态化翻译 API。每个引擎会在每一次请求中持久保存三样东西术语表Glossary保证品牌术语、产品名词翻译一致品牌声音Brand Voice维持文案语气与调性逐语言环境的指令Per-locale Instructions为每个目标语言定制翻译约束。根据项目方公布的研究结论这种检索增强式本地化Retrieval-Augmented Localization方案可将术语错误降低 16.6%–44.6%。当然如果不希望把翻译请求发送到平台CLI 也支持**自带 LLMBring Your Own LLM**模式在下一节详细展开。快速上手四类工具的定位与一条命令原文档给出了一张非常精炼的工具速查表这里完整保留并补充仓库内的对应实现位置工具作用快速命令仓库实现Lingo React MCP为 React 应用提供 AI 辅助的 i18n 设置提示词Set up i18n框架 i18n 知识注入 AI 助手Lingo CLI本地化 JSON、YAML、markdown、CSV、PO 等文件npx lingo.devlatest runpackages/cli/src/cli/cmd/run/index.tsLingo GitHub Action在 GitHub Actions 中实现持续本地化uses: lingodotdev/lingo.devmainaction.ymlLingo Compiler for React无 i18n 包装器的构建期 React 本地化早期 alphawithLingo()插件packages/new-compiler/src/plugin/transform其中 CLI 与 GitHub Action 的封装关系值得注意Action 内部实际上是通过npx lingo.devversion ci调用 CLI 的ci子命令完成的见 action.yml因此掌握 CLI 是理解整套工具链的基础。Lingo.dev MCP让 AI 助手学会正确的 React i18n在 React 应用中手动设置 i18n 很容易出错——即便是 AI 编程助手也会凭空臆造不存在的 API甚至破坏路由结构。这是 Lingo.dev MCP 要解决的问题。MCPModel Context Protocol为 AI 助手提供了结构化的、框架特定的 i18n 知识访问能力覆盖Next.jsApp Router / Pages Router 的 i18n 约定React Router路由级本地化接入TanStack Start新型全栈框架的 i18n 模式。它可以配合Claude Code、Cursor、GitHub Copilot Agents 和 Codex等主流 AI 编码工具使用。典型的使用方式是直接向 AI 助手发出提示词Set up i18n助手基于 MCP 提供的框架知识完成 i18n 初始化而不再靠猜测 API来写代码。这一工具解决的是开发期配置正确性问题与下面 CLI 解决的翻译文件生产问题形成互补。Lingo.dev CLI一条命令本地化任意格式文件CLI 是整套工具链的中枢。原文档的核心用法是两行命令npx lingo.devlatest init npx lingo.devlatest runinit初始化项目生成i18n.json配置文件run读取配置执行本地化流水线。lockfile只翻译新增或变更的内容CLI 通过一个lockfilei18n.lock记录哪些内容已经被本地化每次运行只处理新增或修改过的内容从而节省 API 调用与费用。仓库中还提供了独立的lingo.dev lockfile子命令用于根据当前源语言内容生成或刷新i18n.lock支持--force强制覆盖已有校验和以重置翻译跟踪见 packages/cli/src/cli/cmd/lockfile.ts。在增量校验--frozen、变更检测等场景下lockfile 都是判断源文件是否已更新、目标文件是否缺失翻译的依据。支持的格式远超文档列举的五种原文档列举了 JSON、YAML、markdown、CSV 和 PO 五种格式而实际上 loader 系统覆盖了数十种 bucket 类型。从 packages/cli/src/cli/loaders/index.ts 的 loader 组合工厂可以看到完整清单通用配置json、json5、jsonc、yaml、yaml-root-key、json-dictionary、properties、php文档与标记markdown、markdoc、mdx、html、ejs、twig、txt、mjml表格数据csv、csv-per-locale软件本地化pogettext、xliff、xml、androidAndroid strings.xml、flutterARBApple 生态xcode-strings、xcode-stringsdict、xcode-xcstrings、xcode-xcstrings-v2字幕srt、vtt前端框架typescript、vue-json、ail、dato每种类型都由多个 loader 以流水线方式组合而成如createTextFileLoader → createJsonLoader → createFlatLoader → createLockedKeysLoader → …实现统一的键值扁平化、键锁定、格式规范化等能力。配置体系i18n.json 详解i18n.json是 CLI 的核心配置其 schema 定义在 packages/spec/src/config.ts从 v0 一路演进到 v1.15包含以下关键字段字段说明version配置 schema 版本号当前最新为1.15$schemaJSON Schema 地址用于编辑器校验locale.source源语言代码如en、en-US、pt_BR、pt-rBR支持-、_、Android-r三种记法locale.targets目标语言代码数组locale.extraSource可选的额外源语言作为翻译时的回退buckets桶配置bucket 类型 → { include, exclude, injectLocale, keyColumn, … }formatter输出格式化工具prettier或biome未指定时默认 prettierprovider自带 LLM 时的翻译服务商配置见下文engineId指定 Lingo.dev 平台上的本地化引擎 IDdev开发期设置如usePseudotranslator使用伪翻译而非真实翻译便于免 API 调用测试 i18n其中buckets是配置的重心。以仓库 packages/cli/demo/json/i18n.json 中的真实示例为蓝本{ version: 1.12, locale: { source: en, targets: [es] }, buckets: { json: { include: [./[locale]/example.json], // [locale] 占位符会被替换为具体语言 lockedKeys: [locked_key_1], // 这些键永不参与翻译、不被覆盖 preservedKeys: [preserved_key_1, legal/preserved_nested] // 占位加入目标文件但之后不被覆盖 } }, $schema: https://lingo.dev/schema/i18n.json }每个 bucket 还支持exclude排除路径/glob、lockedPatterns正则锁定内容、ignoredKeys完全忽略的键、localizableKeys强制翻译的键例如本应被跳过为不可翻译的纯数字、URL、日期当它们有自定义术语表规则时使用、injectLocale注入/移除当前语言的键、keyColumnCSV 桶指定作为行唯一标识的列默认取首列等选项。文件路径通过[locale]占位符定位各语言文件并可用**递归匹配。run 命令的完整选项在run子命令的实现packages/cli/src/cli/cmd/run/index.ts中可以看到完整的运行时参数选项作用--source-locale code本次运行覆盖源语言--target-locale code只处理指定的目标语言可重复传入多个--bucket type只处理指定桶类型如json、yaml、android--file substr按文件路径子串过滤桶路径如messages.json或locale/--key prefix按点分路径前缀过滤键如auth.login匹配所有以auth.login开头的键--force跳过变更检测强制重译所有键适合升级模型或翻译设置后重新生成--frozen只校验不修改若源文件/目标文件/lockfile 不同步则失败适合 CI 部署前一致性检查--api-key key覆盖 API Key优先级高于 settings 与环境变量--debug处理前暂停便于附加调试器--concurrency n并发翻译任务数默认 10最大 10调大可加速大批量但增加内存占用--watch持续监听源语言文件变更时自动重新翻译--debounce mswatch 模式下文件变更后的防抖延迟默认 5000ms--sound翻译完成时播放提示音成功/失败见packages/cli/assets/下的 mp3--pseudo伪本地化模式用带重音字符与视觉标记的伪翻译替换全部字符串不调用任何外部 API用于 UI 国际化就绪性测试--estimate预估待翻译内容的成本后退出不能与--watch/--frozen组合其中--pseudo对应 packages/cli/src/cli/localizer/pseudo.ts 的伪本地化实现--estimate则通过平台 API 对同样的变更增量计价属于估算而非报价。认证方式与自带 LLMBYOKCLI 默认使用 Lingo.dev 平台引擎。认证有三条路径见 packages/cli/src/cli/localizer/lingodotdev.ts运行lingo.dev login交互式登录使用--api-key参数显式传入 API Key设置LINGO_API_KEY环境变量。而一旦在i18n.json中配置了provider字段CLI 就会切换为BYOKBring Your Own Key模式跳过平台认证直接调用你指定的 LLM见 packages/cli/src/cli/localizer/index.ts。provider 支持的服务商由 schema 枚举限定packages/spec/src/config.tsOpenAIAnthropicGoogleMistralOpenRouterOllama本地模型provider 配置示例{ provider: { id: openai, model: gpt-4o, // 使用的模型名 prompt: Translate the following JSON…, // 翻译请求的提示词模板 baseUrl: https://…, // 可选自定义 API 基地址 settings: { temperature: 0.3 } // 可选模型参数0确定2随机部分模型要求 temperature1 } }最小实战流程结合仓库 packages/cli/demo 下覆盖 30 余种格式的示例工程一个典型流程是准备源语言文件例如en/example.json并创建i18n.json指定locale.source: en、targets: [es]与buckets.json.include: [./[locale]/example.json]执行npx lingo.devlatest init完成初始化与认证执行npx lingo.devlatest runCLI 会生成i18n.lock、对比增量、调用翻译引擎并写回es/example.json增量场景再次执行run时只有变更的键会被重新翻译。持续本地化CI/CD 集成GitHub / GitLab / Bitbucket原文档强调的核心价值把本地化放进流水线每次 push 触发翻译缺失的字符串在代码进入生产环境之前就被补齐。支持的平台包括 GitHub Actions、GitLab CI/CD 与 Bitbucket Pipelines。GitHub Action 的最小用法原文档示例uses: lingodotdev/lingo.devmain with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }}Action 的完整输入参数定义在仓库根目录 action.yml全部可选且有默认值输入默认值说明versionlatestCLI 版本api-key空Lingo.dev 平台 API Key建议通过 secrets 传入pull-requestfalse是否创建 PR 提交翻译变更commit-messagefeat: update translations via LingoDotDev提交信息pull-request-titlefeat: update translations via LingoDotDevPR 标题commit-author-nameLingo.dev提交作者名commit-author-emailsupportlingo.dev提交作者邮箱working-directory.工作目录monorepo 中本地化文件位于子目录时很有用process-own-commitsfalse是否处理本 Action 自己产生的提交绕过防无限循环机制parallelfalse是否并发处理翻译以加速执行该 Action 内部执行的是npx lingo.devversion ci命令action.yml对应 CLI 的ci子命令packages/cli/src/cli/cmd/ci/index.ts。ci命令同样暴露了--parallel、--pull-request、--commit-message、--pull-request-title、--commit-author-name、--commit-author-email、--working-directory、--process-own-commits、--gpg-signGPG 签名提交等选项并支持in-branch直接提交到当前分支与 pull-request在独立分支上更新翻译并自动管理 PR两种流程见 packages/cli/src/cli/cmd/ci/flows平台适配层则抽象了 GitHub / GitLab / Bitbucket 三套 APIpackages/cli/src/cli/cmd/ci/platforms。在 CI 场景中还可以结合run --frozen做只读校验不产生任何变更一旦源文件、目标文件或 lockfile 不同步就直接以非零退出码失败从而在部署前守住翻译一致性底线。Lingo.dev API从后端直接调用本地化引擎当本地化需求发生在后端代码内部而不是仓库文件时可以直接通过 API 调用你的本地化引擎。原文档明确了 API 的四大能力同步与异步本地化按场景选择等待结果或异步处理Webhook 交付异步任务完成时通过 webhook 推送结果按语言环境失败隔离单个 locale 的翻译失败不会拖垮整体WebSocket 实时进度长耗时任务可实时获取进度。在仓库侧CLI 的 Lingo.dev provider 正是通过lingo.dev/_sdk即 packages/sdk中的LingoDotDevEngine客户端与平台 API 通信包括whoami()鉴权探测、localizeObject()批量翻译与estimate()成本估算见 packages/cli/src/cli/localizer/lingodotdev.ts。SDK 的 packages/sdk/src/index.ts 提供了可复用的 TypeScript 客户端实现可作为后端集成的参考。Lingo Compiler for React早期 alpha免包装器的构建期本地化这是工具链中最具颠覆性的组件。原文档给出的理念非常明确用普通英文文本编写组件——编译器在构建期识别可翻译字符串并生成本地化版本。没有翻译键、没有 JSON 文件、没有t()函数。支持的框架Next.jsApp Router与Vite React。仓库中对应的两个示例工程分别是 demo/new-compiler-next16 与 demo/new-compiler-vite-react-spa。从源码文档 packages/new-compiler/src/plugin/transform/TRANSFORMATION_PIPELINE.md 可以看到完整的转换管线Source JSX → Babel Parser → AST Transformation → Code Generation → Transformed JSX ↓ Metadata Extraction ↓ .lingo/metadata-{env}/ (LMDB 元数据库)管线分五个阶段文件过滤只处理.tsx/.jsx文件跳过node_modules支持自定义跳过规则可选use i18n指令模式代码解析用babel/parser将源码解析为 AST启用jsx、typescript插件组件识别识别返回 JSX 的函数声明、箭头函数、函数表达式默认视为 Server Component带use client指令的视为 Client Component文本提取遍历 JSX 文本节点如divHello World/div、h1Welcome!/h1会被转换纯空白文本与{variable}表达式跳过基于**文本内容 上下文组件名、文件路径**生成唯一哈希并记录源文本、上下文、行列号、时间戳等元数据代码转换把文本替换为翻译调用。例如 Server Component 会被改写为通过getServerTranslations({ hashes: [...] })获取翻译并解构出t进行渲染TRANSFORMATION_PIPELINE.md。这种设计把字符串如何翻译、翻译放哪里完全托管给编译器与元数据库业务代码只需写纯英文文案大幅降低 i18n 的侵入性。需要提醒的是该组件目前处于早期 alpha阶段生产环境使用前应充分评估稳定性。参与贡献与多语言文档仓库欢迎社区贡献规范如下详见 CONTRIBUTING.mdIssues报告 bug 或请求功能Pull Requests每个 PR 需要携带 changeset发布类变更执行pnpm new非发布类变更执行pnpm new:empty提交前需确保测试通过开发环境这是一个 pnpm turborepo monorepo安装依赖pnpm install、运行测试pnpm test、构建pnpm build。该仓库本身也是自身工具的自举案例根目录 i18n.json 与 i18n.lock 管理着 readme 目录下 30 余种语言的 README 翻译含本文对应的 readme/bn.md。如果你希望新增一种语言步骤非常轻量使用 BCP-47 格式在根目录 i18n.json 中添加语言代码提交 Pull Request。总结一条从开发到上线的本地化链路把四个工具串联起来就构成了一条完整的本地化工程链路开发期Lingo React MCP 帮助 AI 助手正确初始化框架 i18nLingo Compiler 让你用纯英文文案写组件构建期自动产出各语言版本内容期Lingo CLI 配合 lockfile 增量机制将 JSON、YAML、Markdown、CSV、PO 及数十种格式的文件批量翻译默认走 Lingo.dev 引擎也可切换 OpenAI、Anthropic、Google、Mistral、OpenRouter、Ollama 等自带 LLM上线期GitHub Actions / GitLab CI / Bitbucket Pipelines 中的持续本地化确保每次 push 后缺失字符串在代码到达生产前被补齐--frozen模式可在部署前做一致性校验后端集成Lingo.dev API 以同步/异步、webhook、WebSocket 方式满足动态内容翻译需求。无论你的团队采用文件翻译 持续集成的传统路线还是拥抱构建期编译 AI 辅助的新范式这套工具链都提供了可落地的开源实现本文涉及的源码与示例工程均可在仓库内进一步查阅验证。【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
