快速上手 · Lingo.dev

完整流程一站式搞定：安装、身份验证、连接引擎、推送源文件、拉取翻译。

前置条件

需要 Node.js 22+（可用 node -v 检查）。安装完成后，CLI 通过 lingo 运行。

安装配置#

安装

bash

npm install -g @lingo.dev/cli

也可以使用 pnpm add -g @lingo.dev/cli / yarn global add @lingo.dev/cli / bun add -g @lingo.dev/cli。

身份验证

bash

lingo login

在浏览器中打开 Lingo.dev，授权 CLI；如果尚未登录，请先登录。CLI 会将会话保存在 ~/.lingo/credentials.json 中。在 CI/非交互式环境中，请使用 API 密钥：lingo login --api-key lk_...（或在任意命令中将 --api-key 设为全局标志）。

初始化项目

在项目根目录中：

bash

lingo init

CLI 会提示你填写 源语言区域、目标语言区域 和 文件模式（即指向源文件的 glob 模式），然后将本地化配置写入 .lingo/config.json。请提交这个文件——它是决定哪些内容会被翻译的唯一事实来源。

连接到引擎

bash

lingo link

选择（或创建）一个组织和一个本地化引擎。引擎会集中保存你的 AI 模型配置、术语表、品牌语气和规则——只需在 Lingo.dev platform 上配置一次，即可在多个项目中复用。link 会将 orgId 和 engineId 添加到 .lingo/config.json 中（也会一并提交）。

首次推送#

准备好一个非空的源文件后（例如 locales/en.json）：

bash

lingo push --backfill-missing --wait

它会按照每个已配置的模式，翻译所有缺失的目标内容。--wait 会让 CLI 一直保持连接，直到本次运行完成，然后将输出（locales/de.json、locales/fr.json……）写入磁盘。在干净的 checkout 上，这个过程可能只需几秒钟（小型 JSON），也可能要几分钟（大型 markdown 包）。如果不使用 --wait，push 会在运行提交后立即退出，而 lingo pull 会稍后再写入输出。

完成后：

text

✓ Run lrg_a8c... : localized 12 target file(s), uploaded 1 new artifact(s).

后续运行#

编辑源文件后，直接运行 lingo push 只会翻译增量内容——源哈希未变化的文件会在服务端自动跳过。默认会保留你对本地目标文件的修改；如需覆盖，请传入 --force（并指定作用范围）。

bash

lingo push                       # delta only
lingo push docs/en/**/*.md       # scoped: only this subtree
lingo push docs/en/about.md -f   # scoped + force: retranslate even if up to date

这些命令都会在运行提交后退出——添加 --wait，即可在同一条命令中写入输出；或者用 lingo pull 稍后再收集输出。

稍后拉取结果#

push 会把运行 ID 记录到 ~/.lingo/runs/<hash>.json 中（以项目的绝对路径为键）。之后，只要还在同一台机器上，并且使用同一个 checkout：

bash

lingo pull

……如果上一次 push 仍在运行，它会先等待完成，再写入输出。特别适合在翻译过程中中途关闭终端后使用。提交这些翻译后，其他机器也能获取它们。

接下来#

Configuration —— .lingo/config.json 的结构、锁文件，以及运行状态的存储位置。
lingo push —— 作用域模式、--force、重试语义。
lingo pull —— 冲突检测、--dry-run。