工作原理
Lingo.dev CLI 将复杂的本地化处理流程封装在一个优雅的命令行界面之下。
当你运行 npx lingo.dev@latest run 时，CLI 会读取标准的 i18n.json 配置文件，并执行以下 5 个步骤：
1. 内容发现
Lingo.dev CLI 将你的项目视为唯一可信的数据源。它会根据 bucket 配置递归扫描项目中的翻译源文件和目标文件，并将其读入内存进行处理。
内容发现阶段遵循：
- 包含类似
locales/[locale].json的模式 - 排除你希望跳过的文件模式
- 针对不同文件类型的多种 bucket 配置
2. 数据清洗
并非所有内容都需要翻译。生产环境中的应用通常包含数字、布尔值、日期、UUID 以及代码片段，这些内容在不同语言间通常保持不变。
Lingo.dev CLI 会智能过滤以下内容：
- 数值，如
42或3.14 - 布尔值（
true/false） - ISO 日期和时间戳
- UUID 及类似标识符
- 代码块和技术片段
这种过滤方式能够降低 LLM 推理成本，并通过聚焦可翻译内容提升处理速度。
3. 差异计算
未发生变化的内容无需重新翻译。Lingo.dev CLI 实现了先进的版本管理系统，能够：
- 使用 SHA-256 哈希生成内容指纹
- 将当前内容与存储在
i18n.lock的先前状态进行比对 - 识别新增、修改和删除的翻译键
- 仅将差异部分发送至翻译引擎
这种增量式方法意味着你只需为新增或变更的内容付费，而不是每次都为整个内容库买单。
了解更多：i18n.lock Lockfile
4. 本地化
即使在网络不稳定或 LLM 服务商宕机的情况下，本地化也必须可靠。在此阶段，Lingo.dev CLI 会将差异内容发送到你配置的翻译后端。
CLI 实现了以下功能：
- 针对网络故障的指数退避重试策略
- 自动错误恢复与部分进度保存
- 同时支持原生 LLM API（OpenAI、Anthropic）和 Lingo.dev Engine
- 支持多目标语言的并发处理
每个翻译请求都包含上下文信息，以确保整个项目中的一致性和高质量。
5. 内容注入
为保持变更集的简洁和可审查性，Lingo.dev CLI 会在源内容所在的确切位置注入翻译。此方法：
- 保持文件结构和格式不变
- 避免不必要的 git 冲突
- 生成最小且聚焦的差异
- 如有 Prettier 配置，将自动遵循
最终生成的本地化文件看起来就像是手工打造，随时可供代码审查和部署。
完整工作流程
这五个步骤通常会产生两类变更：
- 本地化文件 — 包含新增和修改的翻译内容
- i18n.lock 文件 — 用于追踪状态的内容指纹已更新
这两类文件都应提交到你的代码仓库，可以手动提交，也可以通过 CI/CD 集成 自动提交。
这种架构确保 Lingo.dev CLI 能高效扩展，无论是单个开发者翻译少量字符串，还是团队管理数百万字、数十种语言。
下一步
现在你已经了解 Lingo.dev CLI 的内部工作原理，可以：
- 加入我们的社区：Discord — 与其他 Lingo.dev CLI 用户交流，分享反馈，获得本地化相关帮助；
- 参与项目贡献：Open issues — Lingo.dev CLI 是开源项目，欢迎贡献。浏览待办问题、提出新功能建议，或提交 Pull Request，帮助大家共同完善工具。
准备好开始了吗？运行 npx lingo.dev@latest init 来配置你的第一个项目。