Lingo.dev CLI 只需读取一个 i18n.json 配置文件，就能为你的应用和内容完成翻译：从源文件中提取可翻译字符串，并将其发送到 localization engine 或原始 LLM 提供商。它会将翻译结果写回磁盘，并持续跟踪变更，让下次运行时只处理增量内容。
五步流程#
当你运行 npx lingo.dev@latest run 时，CLI 会依次执行以下五个步骤：
内容发现
CLI 会根据 i18n.json 中的 bucket 配置 扫描项目中的源文件和目标文件。每个 bucket 都定义了文件格式，以及一组包含/排除规则，用来告诉 CLI 可翻译内容位于哪里。
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}[locale] 占位符会在运行时解析为你配置的源语言和目标语言 locale 代码。
数据清理
并不是所有内容都需要翻译。CLI 会过滤掉那些在不同语言中都应保持不变的值，例如数字、布尔值、ISO 日期、UUID、URL 和空字符串。这样可以减少发送到翻译后端的负载，降低 token 消耗并缩短处理时间。
增量计算
CLI 会为每条源字符串计算 SHA-256 指纹，并与存储在 i18n.lock 中的上一状态进行比对。只有新增或修改过的内容才会进入翻译流程，未变更的字符串会被完全跳过。
这就是增量处理的意义：一个拥有 10,000 个键的项目，如果只有 12 个发生变化，就只翻译这 12 个键，而不是整套内容。
本地化
增量内容会被发送到已配置的翻译后端。CLI 支持两种模式：
| 模式 | 工作方式 |
|---|---|
| Lingo.dev Engine | 通过你的 localization engine 转发请求，并自动应用 品牌语气、术语表、指令 和 模型配置。 |
| Raw LLM provider | 使用自定义提示词，直接向 OpenAI、Anthropic、Google、Mistral、OpenRouter 或 Ollama 发起翻译请求。 |
CLI 会通过指数退避机制重试失败请求、保存部分进度，并并发处理多个目标语言。
内容回写
翻译后的字符串会按源内容所在的准确位置写回磁盘。CLI 会保留文件结构和格式，生成最小且便于审查的 diff。如果你的项目配置了 Prettier，输出也会遵循相应的格式化规则。
输出文件#
一次典型运行通常会带来两类变更：
- 语言文件 - 目标语言文件会用新增和更新后的翻译进行刷新
i18n.lock- 更新内容指纹，用于跟踪状态
这两者都应提交到版本控制中——可以手动提交，也可以通过 CI/CD integration 自动完成。
