lingo.dev CLI 版本演进深度解析：从 0.70 到 0.138 的功能迭代、性能优化与安全加固

lingo.dev CLI 版本演进深度解析从 0.70 到 0.138 的功能迭代、性能优化与安全加固【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica本文基于仓库中 packages/cli/CHANGELOG.md 的完整版本记录覆盖 0.70.1 → 0.138.5 共 100 余个版本系统梳理 lingo.dev CLI原 Replexica在核心命令、锁文件机制、AI 响应容错、格式生态、键级控制、认证安全、LLM 提供商与 CI/CD 集成上的演进脉络。读者读完后既能掌握run、lockfile、ci等命令当前的能力全景与全部参数也能理解一个生产级本地化 CLI 如何通过 100 余次迭代走向成熟的工程方法论。一、文档定位与 CLI 整体架构速览packages/cli/CHANGELOG.md是 lingo.dev CLI 的完整变更记录采用 Changesets 格式每个版本分为Minor Changes新功能与Patch Changes缺陷修复、依赖更新、安全加固并标注 PR 编号、提交哈希与贡献者。记录最早可追溯至 0.70.1 版本——该版本有一条标志性变更Replexica is now Lingo.dev! 即项目从此前的 Replexica 品牌正式更名为 Lingo.dev。从 packages/cli/package.json 可以看到 CLI 的工程形态包名与二进制包名lingo.dev提供lingo与lingo.dev两个 bin 入口./bin/cli.mjs可通过npx lingo.devlatest直接运行子路径导出同时导出./cli、./sdk、./spec、./locale-codes四个子模块即一个仓库同时承载命令行工具、SDK 与配置规范运行环境Node.js 18使用 pnpm 9.12.3 管理依赖版本基线当前版本 0.138.5。CLI 的命令体系在源码中一目了然packages/cli/src/cli/cmd 目录命令族包含命令用途runrun含 estimate/watch/frozen 等子模块核心本地化流水线ciciflows/platforms 子目录持续集成跨 GitHub/GitLab/Bitbucketconfigget/set/unset用户级配置管理0.92.17 引入showconfig/files/locale/locked-keys/ignored-keys/preserved-keys查看各类状态initinit/cursor项目初始化与 Cursor 规则0.119.0 引入 cursor 命令顶层命令login、logout、status、purge、cleanup、lockfile、i18n已废弃、may-the-fourth彩蛋认证、状态、清理与锁文件维护以下各节按功能主题逐一展开这 100 余个版本的演进细节。二、核心命令run从一条命令到一整套流水线run是 lingo.dev CLI 的中枢命令其能力几乎贯穿全部版本迭代。当前版本的参数全集定义在 packages/cli/src/cli/cmd/run/index.ts下表汇总每个 flag 的语义与引入版本依据 CHANGELOG参数语义引入/增强版本--source-locale locale覆盖i18n.json中的源语言0.93.6 支持显式 source/targets--target-locale locale可重复只处理指定目标语言0.93.60.105.0 起显式指定时跳过锁文件更新--bucket type可重复只处理指定 bucket 类型json、yaml、android…随 bucket 生态同步演进--file pattern可重复按路径子串过滤 bucket0.85.6 引入0.104.0 起支持 globminimatch--key key可重复按点分路径前缀过滤键0.97.0 引入0.99.5 起用 minimatch 匹配0.132.6 修复 URL 编码键的匹配--force强制重译全部键0.122.2 起强制时不把旧译文发给 LLM 作参考--frozen只校验不写入CI 用0.113.0 引入0.135.1 修复空转误报--api-key key覆盖 API key早期版本--debug处理前暂停以便附加调试器早期版本--concurrency n并发任务数默认 10上限 100.120.0 移除硬编码并发限制--watch/--debounce ms监听源文件自动重译默认 5000ms0.102.0 引入--sound完成时播放成功/失败音效0.111.4 引入--pseudo伪本地化模式不调用外部 API0.118.0 引入--estimate估算待译成本后退出不翻译0.137.0 引入2.1 watch 模式开发期的自动重译0.102.00.102.0 是run的一次功能跃升引入--watch与--debounce两个 flag基于chokidar实现跨平台文件监听根据i18n.json的 bucket 配置自动推断监听的文件集合--debounce默认 5000ms防止连续保存触发频繁重译集成进既有setup → plan → execute流水线CtrlC 时优雅退出。示例# 默认 5 秒防抖的监听模式 lingo.dev run --watch # 自定义防抖时间 lingo.dev run --watch --debounce 7000 # 组合使用 lingo.dev run --watch --target-locale es --bucket json配套文档见 packages/cli/WATCH_MODE.md。2.2--estimate翻译成本预估0.137.00.137.0 新增lingo.dev run --estimateCLI 计算与正式运行完全相同的变更增量diff将各语言字符数发送到新的/process/estimate端点随后打印按语言拆分的成本明细并退出不产生任何翻译。SDK 同步新增estimate()方法。源码实现在 packages/cli/src/cli/cmd/run/estimate.ts含独立测试 estimate.spec.ts并在 run/index.ts 中限制了它与--watch/--frozen的互斥组合。注意输出为估算值而非报价。2.3--frozenCI 场景的只读校验0.113.0 起持续打磨--frozen于 0.113.0 引入校验源文件、目标文件与i18n.lock是否同步不同步即失败退出适合部署前保证翻译一致性。后续版本围绕它做了大量防误报修复0.135.1当run发现无内容可译源等于目标时现在会把源校验和持久化进i18n.lock使后续--frozen有基线可校验修复了空转后误报 Source file has been updated 的问题0.136.0将--frozen的报错信息改为指向恢复命令——Runlingo.dev lockfileto refresh i18n.lock, or run without --frozen.并修复了**glob 新增文件、新增 bucket、历史--target-locale运行未写校验和、空锁文件段落等四类误报场景详见下一节。三、i18n.lock锁文件增量翻译追踪机制的三次关键演进锁文件是只翻译新增/变更内容的核心机制CHANGELOG 中围绕它的演进最为密集共经历三次质变。3.1 去重逻辑统一0.125.20.125.2 将原本散落在三处的锁文件去重实现合并为一个通用函数由于i18n.lock是多人协作产物Git merge 冲突会自动留下重复段落去重逻辑需要自动处理这种冲突。合并后行为一致、可维护性显著提升。3.2 增量补充取代整文件重建0.136.0默认行为从遇到缺失段落就整体跳过改为增量填充不加--force时已有校验和的段落保持不变保留--frozen依赖的分歧信号某个 pathPattern 的段落缺失或为空时从当前源内容填充--force仍按原语义整体重建。配套的源码逻辑见 packages/cli/src/cli/cmd/lockfile.ts对每个 bucket 的每个pathPattern先经hasSourceData()判断是否已填充已填充则 skipped否则用 bucket loader 拉取源数据并registerSourceData()added / replaced最后输出统计摘要。3.3 大规模项目的写入性能优化0.138.50.138.5 是 CHANGELOG 中最新的性能优化直指两个瓶颈写入放大此前每个翻译任务都会重写整个i18n.lock一次 run 需要执行patterns × locales次读-改-写循环来持久化patterns段落。由于同一 bucket path 的所有目标语言校验和都派生自同一份源数据除每个 pattern 的首次写入外其余写入内容完全相同。优化后每个 pattern 的段落只写一次且这些写入互相串行化加载路径此前每次加载锁文件都执行完整去重整文件 CST 解析 重新序列化而去重只用于修复手写合并的锁文件——这恰恰是YAML.parse会拒绝的场景。优化后加载先尝试普通解析失败才回退到修复路径畸形与手写合并的锁文件行为不变。i18n.lock的内容格式完全不变属纯性能优化用户无感知。四、AI 输出不可靠性模型响应解析的工程化对抗LLM 返回内容天然不稳定CHANGELOG 记录了 CLI 为解析模型输出建立的多层防线版本问题解法0.92.15LLM 返回畸形 JSON引入jsonrepair并做 trimming0.132.3Gemini 2.5 Flash Lite 等模型在响应前加 OK 等填充语用indexOf/lastIndexOf结构性地提取最外层 JSON 对象后再解析jsonrepair 作为兜底0.137.1BYOK 模型省略顶层data包装接受纯 JSON 对象作为翻译数据0.138.4德语中 ICU 占位符被引号包裹导致 JSON 提前闭合parseModelResponse增加最后手段修复通道0.138.4 的修复尤其值得细读源字符串Attach {title}?译成德语会变成„{title} anhängen?——德语的语序把占位符移到句首排版又用引号包裹它模型输出的引号未转义导致 JSON 字符串提前闭合、{落到了本应是值的位置jsonrepair对Unexpected character {与Colon expected at position N双双放弃。修复策略包括仅在jsonrepair失败后才运行的修复通道字符串内部的引号被转义而非终止字符串仅当引号后的下一个非空白字符不能合法跟在字符串后时该引号才视为闭合把值位置上的{视为字符串开始而非对象开始提取时优先选择真正开启对象的第一个花括号避免Hier ist die Übersetzung für {title}:这类前导文本成为响应起点。该通道不会触碰已经能正常解析或被 jsonrepair 修复的响应真正的嵌套对象和Zeit: {time}这类值也不受影响嵌套的 stringifieddata路径同样经过该修复。五、Bucket 加载器生态30 格式支持的形成史CLI 的核心能力之一是任何格式都能译。CHANGELOG 清晰地呈现了 bucket 生态的扩张时间线格式关键版本节点JSON / YAML基础格式0.78.6 YAML 键值加引号保存0.117.2–0.117.4 保留 YAML 格式与列表缩进0.116.5 保留 literal block 标量不做反斜杠转义Markdown基础格式持续打磨围栏fence处理MDX0.87.0 引入0.84–0.86 高级支持与代码格式化0.88.0 增加lockedPatterns!params、!! 参数标题、!type、!required、!values语法0.108.0 修复占位符替换0.137.6 支持 4 反引号围栏按 CommonMark 允许闭合围栏长于开启围栏PO (gettext)0.77.2 引入0.85.7 元数据转移0.87.12 避免 msgid 回退0.92.18 跳过 obsolete 条目0.92.19 保留注释顺序0.131.7 修复无翻译段落崩溃0.133.9 修复推送性能与多条目段落PHP0.75.0 引入Android XML0.90.0 全面实现HTML 标记、CDATA、格式串、特殊字符转义0.114.1 修复 CDATA 与translatablefalse0.117.6 防止 HTML 标签重复Xcode 系列0.74.9 xcstrings 按 Xcode 顺序排序0.78.0 空节点视为值、跳过shouldTranslate: false0.113.4 新增 xcode-xcstrings-v2 支持 CLDR 复数规则0.116.2 支持 stringSet0.116.3 v2 支持 substitutions0.133.10 之前已支持 xcode-strings/stringsdictHTML / Twig0.117.5 HTML 改为 block-based 翻译0.125.3 用策略化方式正确处理 SVG 内容JSONC0.117.22 支持数组内注释json-dictionary0.107.3 引入locales 位于顶层CSV0.95.0 动态 key 列0.133.10 新增keyColumn指定唯一行标识列并校验 key 唯一性防止静默丢数据csv-per-locale0.120.0 引入并改进 CSV 的 ignoredKeys 支持EJS0.100.0 引入条件、循环、include、混合内容均有测试覆盖Markdoc0.112.0 引入TypeScript0.91.0 从 default export 提取字符串字面量0.92.0 支持嵌套字段与数组0.92.6 支持模板字符串0.110.0 全面支持ignoredKeys含嵌套键、export default 与 export constTXT0.103.0 引入用于 fastlane App Store 元数据等纯文本SRT / VTT0.97.2 VTT 解析0.131.3/0.131.4 过滤 undefined/null 字幕条目0.133.6 修复含 STYLE/REGION 块的 VTT0.133.7 跳过 VTT 增量推送中的 undefined cuesMJML0.117.7 引入0.117.10 修复格式问题Twig0.117.8 引入AIL0.117.9 引入XLIFF0.105.2 实现 1.2 版本Vue (JSON)0.78.2 支持.vue文件i18n块中的 JSON 消息0.78.3 修复 vue json 文件XML0.137.3 移除冗余的.replace(\n, )此前\s折叠已处理换行所有格式的示例文件与i18n.json/i18n.lock配置样例均可在 packages/cli/demo 目录下找到如json/、yaml/、po/、mdx/、xcstrings/等 30 余种格式每个格式还配有对应的 loader 单测如 packages/cli/src/loaders 下的*.spec.ts。六、键级翻译控制locked / ignored / preserved / localizable除格式外CLI 提供了一整套键级控制选项CHANGELOG 记录了它们的引入与全命令铺开选项语义版本节点lockedKeys锁定的键不参与翻译保持源值0.82.0JSON/YAML0.82.1 支持 startsWith0.114.0 铺开到全部 bucket0.111.7 修复 xcstrings 中的 lockedKeyslockedPatterns用正则锁定特定模式MDX 文档参数语法0.88.0MDX0.114.0 铺开到全部 bucketignoredKeys排除特定键含嵌套键不翻译0.92.8 引入0.113.3 支持0.114.0 全 bucket0.132.5 改为精确且按分隔符边界匹配而非子串前缀匹配preservedKeys用源值作占位符写入目标写入后永不被覆盖适合 URL/邮箱这类先复制再本地化的值0.130.2 引入0.131.0 铺开到 purge/cleanup/status/lockfile/i18n 全部命令并新增show preserved-keyslocalizableKeys强制翻译那些会被不可翻译过滤器跳过的值纯数字、URL、ISO 日期0.132.0 引入配套的show命令族packages/cli/src/cli/cmd/show可随时查看这些键的生效情况show locked-keys与show ignored-keys于 0.112.1 引入show preserved-keys于 0.131.0 引入。0.107.2 还允许lockedKeys、ignoredKeys、injectLocale使用通配符wildcard匹配。七、认证、API 端点与登录体验的演变7.1 命令与流程0.94.0新增login/logout命令取代旧的auth --login/auth --logout0.134.0修复 Safari 无法登录的问题。旧流程在本地起 Express 服务器让 HTTPS 网页向http://localhost:portPOST API key被 Safari 的 mixed-content 策略拦截。新流程改为轮询式设备流CLI 向 API 注册会话 → 打开浏览器确认 → 轮询直至授权。Web 端保留?port参数一个发布周期以兼容旧版 CLIexpress与cors依赖随之移除0.133.4SDK 解析服务端 JSON 错误体给出具体错误如 Invalid API key 而非笼统的 Authentication failedwhoami不再吞掉网络错误。7.2 统一 API 端点与 engineId0.133.00.133.0 将 SDK 与 CLI 迁移到统一端点所有请求走api.lingo.dev并使用X-API-Key认证同时新增engineId配置项自动从旧vNext迁移。后续版本继续完善0.131.5 中 vNext 项目跑ci不再校验旧端点 API key且自动启用并行模式0.132.8 向 vNext 端点发送 sessionId/triggerType/文件路径元数据。7.3 API key 的读取0.97.1 起支持从环境变量与.env文件加载 API key0.78.12 会在环境变量覆盖auth --login写入的配置时给出警告。八、供应链安全与依赖治理一条贯穿始终的主线CHANGELOG 后半段0.117 之后呈现出一条非常清晰的供应链安全主线0.117.0将全部依赖固定到精确版本去掉^/~防止供应链攻击依赖升级需显式审查0.137.2两层安全治理——仓库根pnpm overrides固定 axios、vite、ws、form-data、fast-xml-parser、shell-quote、lodash、serialize-javascript、minimatch、picomatch、tmp 等传递依赖pnpm audit从 121 high 5 critical 降至 0同时升级发布清单中的运行时依赖lodash 4.17.23→4.18.1、modelcontextprotocol/sdk 1.22.0→1.26.0、ws 8.18.3→8.21.0全部为同主版本内的 patch/minor 升级无 API 变更0.137.1针对 Dependabot 告警升级 fast-xml-parser、js-cookie、lodash、minimatch其中 js-cookie 特意选 3.0.8 而非 3.0.7后者把 Node 引擎要求抬到 20 破坏 ES5 兼容3.0.8 保留安全修复且不提高引擎要求维持 Node 18 支持lodash 选 4.17.23 而非被 npm 标记为 bad release 的 4.18.00.137.3修复 CodeQL 高严重度告警——org-id的 git remote 解析改为提取 URL host 并按精确 host 或子域后缀匹配host github.com || host.endsWith(.github.com)等取代子串includes()检查既识别ssh.github.com/altssh.gitlab.com这类官方备用 SSH host又拒绝github.com.evil.com这类仿冒域名同时删除 XML loader 中冗余的.replace(\n, )0.137.4消费者npm audit从 13 项降至 8 项critical 1→0high 4→1并清理ink/ink-spinner等未使用依赖顺带规避 ink v7 的 Node 22 要求0.137.5移除external-editor携带存在路径遍历漏洞的tmp^0.0.33与gray-matter携带js-yaml3分别用基于node:fs/node:child_process的mkdtempSync小助手和基于yaml包的 front-matter 助手替代gray-matter 仅作为 devDependency 测试基准保留0.137.8zod 升至 4.4.3 以满足openrouter/ai-sdk-provider的zod^4.3.5peer 要求修复strict-peer-deps下的ERESOLVE安装失败0.138.1再次通过 dependency overrides 修复 picomatch、qs、postcss、ajv、launch-editor、js-yaml、joi 等一系列漏洞0.138.0移除./compiler与./react*子路径导出及对应依赖react在 0.137.7 已改为可选 peer dependency显著收窄攻击面与依赖树。九、LLM 提供商矩阵与 BYOK 模式CLI 默认连接 Lingo.dev 平台的本地化引擎持久化术语表、品牌语气与逐语言指令也支持自带 LLMBYOK。CHANGELOG 记录的提供商扩展如下提供商引入版本说明OpenAI / Anthropic基础支持由ai-sdk/openai、ai-sdk/anthropic提供见 package.jsonGoogle AI0.97.0compiler 与 CLI 同步支持Ollama0.99.0本地模型0.120.0 修复 API key 检查条件破坏 Ollama provider 的问题Mistral AI0.101.0通过MISTRAL_API_KEY环境变量或lingo.dev config set llm.mistralApiKey key配置Groq0.93.8 前后修复从.env读取 groq key0.94.6 更新错误处理OpenRouter0.99.0 前后compiler 的 AI SDK 支持统一 AI SDK0.122.0Compiler 与 CLI 升级到 AI SDK v5BYOK 相关0.92.4 在 BYOK 模式下跳过 lingo.dev 认证0.92.14 为 BYOK 模型增加分块chunking处理0.136.4 与 0.137.1 持续改进 BYOK 模型响应解析与错误处理含接受无data包装的纯 JSON 对象。十、CI/CD 集成从ci命令到跨平台流水线0.79.0 / 0.89.0ci命令两次迭代成型复用i18n内部逻辑0.77.5 支持初始化 GitHub/Bitbucket/GitLab Action平台支持packages/cli/src/cli/cmd/ci/platforms 目录下实现了 github / gitlab / bitbucket 三个平台分别基于 octokit、gitbeaker/rest、bitbucket 包见 package.json流程上区分 in-branch 与 pull-request 两种模式packages/cli/src/cli/cmd/ci/flows0.133.5修复 PR 流程在并发运行时忽略既有翻译分支、从头建分支导致重复 PR 的问题0.130.0新增GPG 提交签名支持——action.yml增加gpg-sign输入ci命令增加--gpg-sign选项提交前做 preflight 检查验证签名密钥已配置签名提交用-S标志两种流程模式均可用。完整用法- uses: crazy-max/ghaction-import-gpgv6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} git_user_signingkey: true git_commit_gpgsign: true - uses: lingodotdev/lingo.devmain with: api-key: ${{ secrets.LINGODOTDEV_API_KEY }} gpg-sign: true0.132.9本地化任务失败时以非零退出码退出让 CI/CD 管道能正确感知部分失败exit-code.ts0.136.1在lingodotdev/ci-actionDocker 镜像中安装git使 GitLab CI 等直接使用镜像的 runner 也能运行lingo.dev ci0.89.5/0.89.4ci 提交支持--no-verify补充--api-key选项。十一、性能与并发工程细节中的工程素养CHANGELOG 中还有大量难以归类的工程细节恰恰体现了生产级 CLI 的打磨0.92.9并行处理parallel processing0.101.0 改为按块渐进推送progressive push边处理边推送0.120.0移除硬编码并发限制--concurrency默认 10、上限 100.92.10 / 0.114.2 / 0.117.21三度修复竞态——run 命令的竞态、单文件格式并发 I/O 竞态、并发处理使用错误语言数据的问题0.111.2修复ci命令因process.exit()挂起的问题移除 PostHog shutdown()、改用异常抛出0.111.1 / 0.133.3优雅退出、run 命令保留终端滚动缓冲区0.138.5上文详述的锁文件写入优化见第三节0.125.3 / 0.117.5HTML/Twig 采用策略化、block-based 提取正确区分 SVG 内容0.90.2 / 0.90.1may-the-fourth彩蛋命令Star Wars Day。十二、结语从 CHANGELOG 读懂一个本地化 CLI 的成熟路径回看packages/cli/CHANGELOG.md这 100 余个版本可以提炼出 lingo.dev CLI 的成熟路径功能广度优先先以run一条命令 少数格式跑通核心闭环再按需求快速铺开格式MDX→PO→PHP→Android→Xcode→MJML→Twig→AIL→Markdoc…与键级控制locked→ignored→preserved→localizable可靠性随后补齐AI 响应的畸形 JSON、德语引号占位符、MDX 4 反引号围栏、VTT 的 STYLE/REGION 块……每一个真实用户场景都沉淀为回归测试性能与体验渐进优化锁文件从整文件重写优化到每 pattern 写一次加载从每载必去重优化到先直解、失败再修复安全成为硬约束精确锁定依赖、三层 npm audit 治理、CodeQL 修复、移除带漏洞的传递依赖是 0.117 之后的主旋律。对于正在使用或计划接入 lingo.dev CLI 的团队本文既可作为run/lockfile/ci等命令的参数速查也可作为理解增量翻译如何被可靠追踪i18n.lock、AI 输出如何被工程化容错parseModelResponse多层修复的实现参考。更深入的代码与配置样例可继续阅读 packages/cli/src/cli/cmd 下的命令实现、packages/cli/demo 下的格式示例以及 packages/cli/troubleshooting.md、packages/cli/agents.md 等配套文档。【免费下载链接】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），仅供参考