CLI 的持久化状态分布在三个位置：两个在项目内（会提交），一个在你的主目录中（机器级）。
.lingo/config.json — 已提交#
由 lingo init（本地化部分）和 lingo link（组织/引擎绑定）创建。请将其提交到版本库。
{
"orgId": "org_a8c...",
"engineId": "eng_b9d...",
"sourceLocale": "en",
"targetLocales": ["de", "fr", "es"],
"files": [
{ "pattern": "locales/en.json" },
{ "pattern": "docs/en/**/*.md" }
]
}字段说明#
| 字段 | 必填 | 说明 |
|---|---|---|
orgId | 是（在 link 之后） | 拥有该引擎的组织。 |
engineId | 是（在 link 之后） | 执行翻译的引擎，包含模型配置、术语表和品牌语气。 |
sourceLocale | 是 | 源文件的 locale 代码（例如 "en"）。源文件只会被读取，绝不会被写入。 |
targetLocales | 是 | 要翻译到的目标 locale。输出会写入与源文件相同的目录，并将模式中的 locale 代码替换为目标 locale（locales/en.json → locales/de.json）。 |
files | 是 | 源模式数组。pattern 是 glob 模式（正斜杠、** 递归、* 通配符）。CLI 在解析目标路径时会替换 locale 代码。 |
github | 否 | GitHub App 的相关设置——CLI 本身会忽略它。 |
模式 → 目标映射#
CLI 会将模式中的源 locale 替换为每个目标 locale：
locales/en.json→locales/de.json、locales/fr.json、……docs/en/**/*.md→docs/de/**/*.md（镜像子树）copy/en/marketing.md→copy/de/marketing.md
如果你的源文件布局没有在路径中包含 locale 代码，请先调整目录结构。否则 CLI 无法判断目标文件应写到哪里。
.lingo/lock.json — 已提交#
它会跟踪每个源文件和目标文件的服务器端最近已知哈希。主要用于两件事：
lingo push会据此判断某个源文件自上次成功运行后是否发生了变化。未变更的文件会直接成为 no-op，无需再与服务器往返。lingo pull会据此检测本地目标文件是否被改动——如果本地目标文件的哈希与 lockfile 中记录的不一致，执行拉取会覆盖本地修改，因此除非你传入--force，否则pull会直接报错。
只有在一次 push 完整成功后，源文件哈希才会写入 lockfile，因此即使运行进行到一半中断，也可以直接重试，无需手动清理。
请将 lockfile 与翻译输出一并提交。遇到冲突时，处理方式与 package-lock.json 冲突相同：再次运行 lingo push 重新生成即可。
~/.lingo/runs/<hash>.json — 机器级#
它会记录最近一次提交的 push，让 lingo pull 知道该拉取哪次运行的输出——即使终端已经关闭，或是在共享同一份检出的不同机器之间，也能正常工作。
{
"runId": "run_a8c...",
"engineId": "eng_b9d...",
"organizationId": "org_a8c...",
"sourceLocale": "en",
"createdAt": "2026-05-22T14:32:01.000Z"
}文件名中的哈希取自项目根目录的绝对路径，而不是文件内容，因此：
- 编辑
en.json不会让这个文件失效——同一个pull依然能找到对应的运行。 - 同一台机器上，同一仓库的两份检出会得到不同的文件（因为绝对路径不同）。
- 如果在 push 和 pull 之间移动了项目（
mv ~/Projects/foo ~/Projects/bar），查找就会失效，因为哈希变了。如果你需要手动恢复 run ID，对应的 JSON 仍保存在~/.lingo/runs/中。
这个文件是机器级状态，不是项目状态——它不需要加入 gitignore，因为它完全位于仓库之外。
认证凭据 — ~/.lingo/auth.json#
由 lingo login 存储（OTP 流程会保存 Supabase session；--api-key 流程会保存密钥）。不会提交到版本库，且除了 CLI 本身外，任何其他组件都不会读取它。
lingo logout # clear credentials
lingo whoami # check what's stored and which org/engine the cwd resolves to从子目录解析#
每条命令都会从 cwd 开始向上查找最近的 .lingo/config.json。如果你在 src/components/ 下运行 lingo push，lockfile 会被写回项目根目录，而不会在 components/ 里新建一个 .lingo/。因此，你不必在每次执行命令前都先 cd 回到根目录。
