@lingo.dev/cli · Lingo.dev

@lingo.dev/cli 会把你的源内容发送到本地化引擎，由引擎在服务器端完成翻译，并将结果写回磁盘——既可以通过 --wait 在同一条命令里完成，也可以稍后用 lingo pull 拉取。它取代了旧版的 npx lingo.dev 流程——项目还是同一个，但底层架构已截然不同。

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

旧版 CLI（npx lingo.dev run）会提取字符串、直接在你的机器上调用 LLM，并一次性把文件写回本地。新版 CLI 则把流程拆成 push 和 pull：

lingo push 将源文件上传到你的引擎，启动服务端工作流，并可选择等待完成，或立即返回一个运行 ID
lingo pull 会拉取最近一次 push 的输出——即使你在翻译过程中关闭了终端也没问题，只要你在同一台机器的同一个检出副本中执行 pull。
lockfile（.lingo/lock.json）会记录每个目标文件在服务器上的最新已知版本，以便在本地修改即将被覆盖前触发冲突检测

这带来了旧版 CLI 做不到的一点：长时间运行的翻译不再需要让终端一直挂着——先 push，关掉终端，稍后再 pull 获取结果。

等待结果#

lingo push 会上传源文件、启动服务器端工作流，并在提交运行后立即退出——不会等待翻译完成，也不会写入结果。你可以用 lingo pull 拉取输出，或者传入 --wait（-w），一条命令完成全部操作。

bash

lingo push            # submit the run and exit (default)
lingo pull            # later: re-attach to the most recent push and download its outputs

lingo push --wait     # submit, wait, and write outputs in one command

--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 中加上 `--wait`）。
`lingo push --backfill-missing`	初始化——补齐尚不存在的目标文件	首次 push，或新增语言区域后
`lingo push --force`	全量重译——覆盖所有目标文件（包括手动编辑）；`--yes`/`-y` 可跳过提示	极少使用（例如 glossary/engine 变更后）

--backfill-missing 是一个初始化标志。它会发起一次限定范围的全新请求，只补齐整份缺失的目标文件——不会把新增的键翻译到已有译文的文件中（运行会显示“already up-to-date”，并跳过该键）。持续迭代时，请直接使用 lingo push。

手动编辑翻译#

普通的 lingo push 会按键保留手动编辑：

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

本节内容#

快速开始

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

配置

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

lingo push

发送源文件并启动一次翻译运行——加上 `--wait`，即可在同一条命令中写回结果。支持作用域模式、`--force` 和重试语义。

lingo pull

拉取上一次 push 的输出——支持在同一台机器上跨终端会话继续使用，并提供冲突检测。

其他命令