@lingo.dev/cli

@lingo.dev/cli 会将你的源内容发送到本地化引擎，等待引擎生成翻译，然后将结果写回磁盘。它是对旧版 npx lingo.dev 流程的替代——同一个项目，但底层架构已截然不同。

新版 CLI 相比旧版有哪些变化#

旧版 CLI（npx lingo.dev run）会提取字符串、直接从你的机器调用 LLM，并以一次同步流程写入文件。新的 CLI 则是以异步为核心设计的：

lingo push 会将源文件上传到你的引擎，启动服务端工作流，并可选择等待完成，或立即返回一个运行 ID
lingo pull 会获取最近一次 push 的输出——即使你在翻译过程中关闭了终端，或是在另一台机器上执行 pull，也照样可用
lockfile（.lingo/lock.json）会跟踪每个目标文件在服务端的最新已知版本，以便在本地修改被覆盖前通过冲突检测及时提示

这带来了旧版 CLI 做不到的两件事：长时间翻译时无需让终端一直挂起，以及可以在执行 push 的机器之外拉取结果（包括在 CI 中）。

等待结果#

目前，lingo push 会上传源文件、启动服务端工作流、等待其完成，并将输出写回——全部通过一条命令完成。传入 --wait（-w）会明确启用这种阻塞行为。你也可以稍后使用 lingo pull 重新关联到一个已完成的运行。

bash

lingo push            # submit, wait, and write outputs (current default)
lingo push --wait     # same thing, made explicit

lingo pull            # later: re-attach to the most recent push and download its outputs

即将到来的变更： 即将发布的版本会将默认行为切换为异步。lingo push 将提交运行后立即退出；你需要运行 lingo pull 下载已完成的翻译，而 --wait（-w）则会成为重新启用单命令阻塞流程的方式。

--wait（-w）会一直阻塞到工作流完成，并在同一条命令中写入输出。
lingo pull 会重新关联到此项目最近一次 push，并下载其输出——即使你已经关闭了终端也没问题。运行状态按机器存储在 ~/.lingo/runs/<project-hash>.json，因此 pull 会在同一台机器上恢复。

认证：两个命令都会读取 LINGO_API_KEY（或 --api-key，或 lingo login 会话）。在 CI 中，只需设置 LINGO_API_KEY，无需其他配置。

push 模式#

命令	模式	适用场景
`lingo push`	增量——对比源文件与 `.lingo/lock.json` 的差异，只将新增或变更的键翻译到现有目标文件中，其余内容保持不变	每次常规运行 / CI
`lingo push --backfill-missing`	引导——补齐尚不存在的目标文件	首次 push，或新增语言区域后
`lingo push --force`	全量重新翻译——覆盖所有目标文件（包括手动修改）；`--yes`/`-y` 会跳过提示	极少使用（例如术语表或引擎变更后）

--backfill-missing 是一个引导标志。它会发起一次限定范围的全新请求，并且只会补齐缺失的整个目标文件——不会将新添加的键翻译到已有翻译的文件中（运行会报告“already up-to-date”，并跳过该键）。对于持续性的编辑，请使用普通的 lingo push。

手动编辑翻译#

普通的 lingo push 会按键保留手动修改：

编辑某个目标字符串（其源文本未变）→ 该字符串会被保留；其他键会继续更新。
已编辑键对应的源文本发生变化 → 会为该键生成新的翻译，并替换手动修改。
新增一个源键 → 会被翻译并添加进去，即使目标文件中存在手动修改也一样。

本节内容#

快速开始

安装、认证、连接到引擎，并完成首次 push 和 pull。

配置

`.lingo/config.json`、`.lingo/lock.json`，以及存储在 `~/.lingo/runs/<hash>.json` 中、按机器区分的运行状态。

lingo push

发送源文件、等待翻译、写入输出。支持限定范围的模式、`--force` 和重试语义。

lingo pull

获取最近一次 push 的输出——跨机器、跨终端会话，支持冲突检测。

其他命令