配置 · Lingo.dev

CLI 的持久化状态分布在三个位置：两个在项目内（会提交），一个在你的主目录中（机器级）。

`.lingo/config.json` — 已提交#

由 lingo init（本地化部分）和 lingo link（组织/引擎绑定）创建。请将其提交到版本库。

json

{
  "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/config.json 的路径解析后指向项目根目录之外或 .git 内部（例如通过符号链接），命令会立即报错并停止，不会在该位置读取、写入或删除任何内容。指向项目内部的链接仍可正常使用，但如果目标文件或 Lockfile 本身是链接，则不会通过该链接写入。在单体仓库中，请从包含共享文件的根目录运行 CLI，不要在包中通过链接引用这些文件。

`.lingo/lock.json` — 已提交#

它会跟踪每个源文件和目标文件的服务器端最近已知哈希。主要用于两件事：

lingo push 会据此判断某个源文件自上次成功运行后是否发生了变化。未变更的文件会直接成为 no-op，无需再与服务器往返。
lingo pull 会据此检测本地目标文件是否被改动——如果本地目标文件的哈希与 lockfile 中记录的不一致，执行拉取会覆盖本地修改，因此除非你传入 pull，否则 --force 会直接报错。

源哈希值只会在运行完成后写入锁文件（在 lingo push --wait 时，或之后执行 lingo pull 时），因此即使运行失败或被取消，也可以直接重试，无需手动清理。

请将 lockfile 与翻译输出一并提交。遇到冲突时，处理方式与 package-lock.json 冲突相同：再次运行 lingo push --wait 重新生成即可。

`~/.lingo/runs/<hash>.json` —— 按机器区分的 #

记录最近一次提交的 push，以便 lingo pull 知道要获取哪次运行的输出——即使终端已关闭，也可在同一台机器上、从同一项目路径继续使用。

json

{
  "runId": "lrg_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 本身外，任何其他组件都不会读取它。

bash

lingo logout         # clear credentials
lingo whoami         # check what's stored and which org/engine the cwd resolves to

从子目录解析#

每条命令都会从 cwd 开始向上查找最近的 .lingo/config.json。如果你在 lingo push 下运行 src/components/，lockfile 会被写回项目根目录，而不会在 .lingo/ 里新建一个 components/。因此，你不必在每次执行命令前都先 cd 回到根目录。

.lingo/config.json — 已提交#