Lockfile 与缓存

在更新和恢复过程中,保持源内容基线、目标哈希、远程产物与本地运行指针之间的关联。

增量翻译需要知道哪些内容发生了变化。.lingo/lock.json 记录源内容和目标内容的哈希;服务器保留产物和翻译输出;用户主目录中的本地指针标识最近一次待收集的运行。它们各自用于不同的操作,因此删除其中一项,并不能解决另一项的问题。

项目基线 #

Lockfile 使用 1 版本,并通过 files 映射,将相对于仓库根目录的路径关联到 SHA-256 哈希:

json
{
  "version": 1,
  "files": {
    "locales/en.json": {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

此哈希仅用于展示格式,并非可直接复制使用的值。源内容哈希标识先前的字节内容,用于增量比较。目标内容哈希有助于在收集前检测本地修改。该文件不包含翻译文本或质量评估。

请将 Lockfile 与其记录的、已接受的源内容和目标内容变更一同提交。状态缺失时,push 会按首次建立基线的方式处理;状态格式错误或不受支持时,操作会失败,而不会静默重置。

哈希何时更新 #

收集操作会记录已完成目标的哈希。仅提交而不收集,不会确立基线。每个文档单独确立基线,在该文档的所有目标都完成之前,不会交付其中任何目标。现有的完整源内容基线只有在文档涵盖所有已配置的目标语言区域、所有目标均已完成且未设置键范围时才会更新。仅收集部分语言区域时,会为其他语言区域保留该基线;如果尚无源条目,则可以初始化一个。键刷新不会改变源内容哈希,无论由 push --wait 还是 pull 收集。

产物与翻译缓存 #

产物按内容寻址,因此 push 只会上传服务器尚未存储的字节内容。Lockfile 中指定的先前源内容必须能从本地字节内容或服务器恢复。如果两处都找不到,请检查指定的 Lockfile 条目,恢复已知正确的字节内容或一致的基线。不要用猜测的哈希代替。

翻译输出缓存与源内容存储不同。删除本地目标文件,并不意味着后续请求一定会重新调用模型。

最近一次运行的指针 #

~/.lingo/runs/<project-hash>.json 标识特定绝对项目根目录下最近一次 push。它包含运行、组织和本地化引擎的 ID、源语言区域及创建时间。在此次 push 的结果收集完成前,它还会保留请求标识,让重复执行的 push 复用已有提交,而不再创建重复提交。

它不是 .lingo/run.json,也不会随 Git 一同传递。即使配置和 Lockfile 完全相同,移动后的 checkout 或另一个运行器也可能没有该指针。新的 push 可能会替换它。在获取完成之前,请将原始运行标识保留在不含机密信息的运维记录中。

为另一个 CI 作业保留运行 #

如果需要等待审核,或将提交与获取拆分为不同作业,请在提交运行器被销毁前保留指针。提交后立即在包含所需 .lingo/config.json 的绝对目录中执行以下操作,并确保在此之前没有再次执行 push:

sh
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const root = process.cwd();
if (!existsSync(".lingo/config.json")) throw new Error("Run from the configured project root");
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
mkdirSync(".lingo-ci", { recursive: true });
copyFileSync(join(homedir(), ".lingo", "runs", `${hash}.json`), ".lingo-ci/run.json");
writeFileSync(".lingo-ci/project-root.txt", root);
JS

这两个文件包含不含机密信息的运行指针,以及用于定位它的确切绝对项目根目录。请检查导出的 JSON 中的 runId 是否与此次提交打印的 ID 一致;如果提交在记录新运行之前失败,旧指针可能仍然保留。将验证后的文件作为受访问控制的作业产物保留,同时保留源代码修订版本、.lingo/config.json、.lingo/lock.json 以及匹配的源文件和目标文件,包括尚未提交的输出。对于单文件 CI 示例,请保留 locales/en.json 和 locales/es.json;其他项目则使用实际选定的路径。源内容和目标内容共用一个文件时,请保留整个共享资源集。产物保留时间应足够长,以便完成审核和收集。切勿归档整个 ~/.lingo、凭据文件或含机密信息的环境变量值。

审核完成后,在获授权的运行器上,于相同的绝对项目根目录恢复相同的修订版本和已保留的文件状态。安装相同版本的 CLI,并通过运行器的机密信息机制单独提供凭据。在该根目录中,仅恢复此指针:

sh
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const root = readFileSync(".lingo-ci/project-root.txt", "utf8");
if (process.cwd() !== root || !existsSync(".lingo/config.json")) {
  throw new Error("Restore the configured project at its original absolute root");
}
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
const directory = join(homedir(), ".lingo", "runs");
mkdirSync(directory, { recursive: true });
const destination = join(directory, `${hash}.json`);
if (existsSync(destination)) throw new Error("Preserve the existing run pointer before replacing it");
copyFileSync(".lingo-ci/run.json", destination);
JS
lingo pull --dry-run

确认报告的运行就是之前保留的运行,解决所有冲突,然后使用 lingo pull 并检查获取的输出。不要先执行 push,否则会替换指针。如果 CI 服务无法重建原始根目录,请使用具有该路径的持久化授权运行器执行提交和获取;仅将指针复制到其他位置的 checkout 中并不足够。只有在收集完成且运维保留期结束后,才删除临时导出的 .lingo-ci,并将其排除在翻译提交之外。

现有翻译与人工编辑 #

限定范围或初始化规划可以采用已有的目标内容。请先检查其语言和完整性:源语言占位文本可能通过存在性检查,但并不是真正的翻译。补填会创建缺失的普通文件,不会补充现有文件中缺失的键。

常规增量操作会传入源键未变更时对应的目标修改,以便保留这些修改。源键发生变更后,对应的目标修改可能被替换。JSON 使用键路径作为标识,因此即使源文本完全相同,重命名键也会产生新的翻译任务;这与 v0 基于内容指纹的复用方式不同。

当需要以目标文本为准时,preservedKeys 可提供显式保护,但整文件强制处理会移除该保护所需的当前目标上下文。pull 会在写入前比较最新哈希;仅执行 Git 提交不会改变这一比较。直接通过 push --wait 收集期间,请避免编辑目标内容。

分支与共享写入者 #

方式影响
在功能分支中翻译一并审核源内容和目标内容;在变基时协调相互冲突的基线修改。
源内容合并后创建翻译 PR单独审核,翻译变更被接受前会有一段间隔。
GitHub App 翻译 PR集成控制触发和回写;运行批准与合并相互独立。
授权运行器直接写入分支需要明确的写入权限、内容检查,以及防止并发写入冲突的保护措施。

遇到 Lockfile 合并冲突时,请先确定双方各自记录的源内容和目标内容修订版本。协调已接受的内容,再通过适当的工作流保留或重建一致的基线。拼合无关的哈希,或通过删除 Lockfile 消除冲突,可能会掩盖尚未完成的翻译。

提供商的配置方式请参阅 GitHub App、GitHub Actions、GitLab、Bitbucket 或 Buildkite。check 会将已配置的源文件与此 Lockfile 进行比对,并报告缺失的目标文件。对于 React .jsonc 翻译资源集以外的目标文件,它不会检查其中的键。

用户主目录中的其他本地状态 #

~/.lingo/update-check.json 会将版本检查结果缓存 24 小时。凭据和匿名遥测标识分别存储。这些状态都不保存翻译后的文件输出。移除状态前,请先参阅 故障排查,确定失败的是哪个操作。