快速上手 - 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

输入你的邮箱后，CLI 会发送一次性验证码，并将会话令牌保存到 ~/.lingo/auth.json。在 CI / 非交互式场景下，请使用 API 密钥：lingo login --api-key lk_...（或将 --api-key 作为任意命令的全局参数传入）。

初始化项目

在项目根目录中：

bash

lingo init

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

连接到引擎

bash

lingo link

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

首次推送#

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

bash

lingo push --backfill-missing

它会为所有已配置模式下缺失的目标文件生成翻译。CLI 会等待本次运行完成，并将输出结果（locales/de.json、locales/fr.json，...）写入磁盘。在全新检出的环境中，这个过程可能只需几秒（小型 JSON），也可能需要几分钟（大型 markdown 文件集）。

完成后：

text

✓ Run run_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

在另一台机器上拉取#

push 会将运行 ID 记录到 ~/.lingo/runs/<hash>.json 中（按项目绝对路径作为键）。在任何检出内容相同且使用相同凭据的机器上：

bash

lingo pull

…即可拉取上一次 push 的输出结果。这在 CI 中尤其有用（“译者在笔记本上执行 push，CI 在每次构建时执行 pull”），也适合在终端关闭后继续之前的流程。

接下来#

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

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

前置条件

需要 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

初始化项目

在项目根目录中：

bash

lingo init

连接到引擎

bash

lingo link

首次推送#

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

bash

lingo push --backfill-missing

完成后：

text

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

后续运行#

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

在另一台机器上拉取#

push 会将运行 ID 记录到 ~/.lingo/runs/<hash>.json 中（按项目绝对路径作为键）。在任何检出内容相同且使用相同凭据的机器上：

bash

lingo pull

接下来#

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