Lockfile and cache

Keep source baselines, target hashes, remote artifacts, and the local run pointer connected during updates and recovery.

Incremental translation needs to know what changed. .lingo/lock.json records source and target hashes; the server retains artifacts and translation output; a home-local pointer identifies the latest run to collect. Each serves a different operation, so deleting one is not a general repair for another.

The project baseline #

The lockfile uses version 1 and a files map from repository-relative paths to SHA-256 hashes:

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

This hash illustrates the shape, not a value to copy. Source hashes identify previous bytes for incremental comparison. Target hashes help detect local edits before collection. The file contains no translated text or quality assessment.

Commit the lockfile with the accepted source and target changes it describes. Missing state changes push to first-baseline behavior; malformed or unsupported state fails instead of silently resetting.

When hashes advance #

Completed collection records completed-target hashes. Submission without collection is not baseline settlement. Each document settles separately, withholding sibling targets until all complete. An existing whole-source baseline advances only when the document covers every configured target locale, all targets complete, and no key scope is set. Collection for only some locales keeps that baseline for the others; it can initialize a source entry if none exists. A key refresh leaves the source hash unchanged whether push --wait or pull collects it.

Artifacts and cached translations #

Artifacts are content-addressed, so push uploads only bytes the server lacks. An earlier source named by the lock must be recoverable from local bytes or the server. If neither has it, inspect the named lock entry and recover known-good bytes or a coherent baseline. Do not substitute a guessed hash.

Cached translation output is different from source storage. Deleting a local target does not prove a later request will invoke the model afresh.

The latest-run pointer #

~/.lingo/runs/<project-hash>.json identifies the most recent push for an absolute project root. It includes run, organization, and localization engine IDs, source locale, and creation time. Until the push is collected, it also retains the request identity that lets a repeated push reuse the submission instead of duplicating it.

This is not .lingo/run.json and does not travel with Git. A moved checkout or another runner can lack the pointer even with identical config and lockfile. A new push can replace it. Keep the original run identity in non-secret operational records until retrieval is complete.

Preserve a run for another CI job #

For a review wait or split submission/retrieval job, preserve the pointer before the submitting runner disappears. Run this from the absolute directory containing the intended .lingo/config.json, immediately after submission and before another 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

These two files contain the non-secret run pointer and the exact absolute project root used to locate it. Check that runId in the exported JSON matches the ID printed by this submission; an earlier pointer can remain when submission fails before recording a new run. Retain the verified files as access-controlled job artifacts with the source revision, .lingo/config.json, .lingo/lock.json, and the matching source and target files, including uncommitted output. For the one-file CI examples, retain locales/en.json and locales/es.json; use the actual selected paths for another project. Preserve the whole shared catalog when source and targets use one file. Configure artifact retention long enough for review and collection. Never archive all of ~/.lingo, credential files, or secret environment values.

After review, restore the same revision and retained file state at the same absolute project root on an authorized runner. Install the same CLI version and supply credentials separately through its secret mechanism. From that root, restore only this pointer:

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

Confirm that the reported run is the one preserved, resolve any conflicts, then use lingo pull and inspect the retrieved output. Do not push first, because that replaces the pointer. If the CI service cannot recreate the original root, use a persistent authorized runner with that path for submission and retrieval; copying the pointer into a differently located checkout is insufficient. Remove the temporary .lingo-ci export only after collection and operational retention are complete, and keep it out of translation commits.

Existing translations and human edits #

Scoped/bootstrap planning can adopt present targets. Check their language and completeness first: source-language placeholders can satisfy a presence check without being translations. Backfill creates missing ordinary files, not missing keys inside an existing file.

Normal incremental work supplies unchanged-key target edits for preservation. Changed source keys can replace them. JSON uses key paths as identities, so renaming a key creates new work even with identical source wording; this differs from v0 content-fingerprint reuse.

preservedKeys adds deliberate protection when target text should remain authoritative, but whole-file force removes the current-target context needed for it. Pull compares fresh hashes before writing; a Git commit alone does not change that comparison. Avoid editing targets during direct push --wait collection.

Branches and shared writers #

ArrangementConsequence
Translate in the feature branchReview source and target together; reconcile competing baseline edits during rebases.
Translation PR after source mergesSeparate review, with an interval before translated changes are accepted.
GitHub App translation PRThe integration controls triggers and writeback; run approval is separate from merge.
Authorized runner writes directly to a branchRequires explicit write authority, content checks, and protection against concurrent writers.

For a lockfile merge conflict, first identify the source and target revisions each side describes. Reconcile the accepted content, then retain or rebuild a coherent baseline through the appropriate workflow. Combining unrelated hashes or deleting the lock to silence a conflict can hide unfinished translation.

Provider setup belongs to GitHub App, GitHub Actions, GitLab, Bitbucket, or Buildkite. check compares configured sources with this lockfile and reports missing target files; outside React .jsonc catalogs, it does not check keys inside them.

Other home-local state #

~/.lingo/update-check.json caches version checks for 24 hours. Credentials and anonymous telemetry identity live separately. None holds translated file output. Use Troubleshooting to identify the failed operation before removing state.