CLI v0 lockfile

Use the legacy source baseline to understand pending changes and recover without hiding unfinished translation.

i18n.lock lets v0 distinguish unchanged source from text that needs translation. Keep it with the source and accepted targets it describes. It does not record every human target edit or prove that a translation is correct.

What the file records #

In lingo.dev@0.138.10, the file is YAML with version: 1 and a checksums mapping. Each outer section hashes a processed path pattern; its entries map source keys to MD5-based source-value checksums. Let the CLI manage these entries rather than constructing them manually.

A changed checksum makes a present key eligible for translation. Matching source-value hashes can also connect a new key to a removed key in the same processed context, allowing rename reuse. Neither mechanism is unrestricted cross-file translation memory.

Distinguish translation from baseline replacement #

OperationWhat it does
lingo runTranslates the calculated delta and advances source state.
lingo run --forceRegenerates selected output without relying on the ordinary delta.
lingo lockfileAdds missing source-state sections, leaving populated sections alone.
lingo lockfile --forceReplaces source checksums from current files without translating targets.
lingo run --frozenChecks synchronization without translation, but initializes a missing baseline first.

Suppose English changes after a French target was accepted. Replacing its checksum with lockfile --force records the new English as baseline even though French may still express the old meaning. Rebuilding is therefore not a routine way to clear a synchronization failure.

Target-locale and key-scoped runs can write translations without refreshing an existing shared source baseline. A later ordinary run can revisit the source change and replace a correction made after that narrow run. Reconcile the relevant locale outputs deliberately before advancing the shared baseline.

When settling a source change across several locales:

  1. Keep the source revision fixed and preserve i18n.lock while any affected output is unfinished. Use lingo run for an ordinary project-wide update, or the documented scoped runs when outputs need separate work and review.
  2. Inspect every locale output covered by the source-checksum replacement, including outputs not touched by the most recent scoped run. Resolve failures and reconcile accepted manual corrections against that source. If any output is still stale or uncertain, leave the shared baseline pending.
  3. If scoped work left the existing baseline unchanged and all covered outputs are now accepted, run lingo lockfile --force from the intended project root. It replaces source checksums without translating, so do not use it to skip the preceding review or assume that the last target-locale selector limits this replacement.
  4. Inspect the lockfile diff and commit the exact source revision, all corresponding accepted targets, and i18n.lock together. A later lingo run --frozen can check synchronization against that settled baseline; it cannot establish target freshness or translation quality.

Frozen mode is not strictly read-only when i18n.lock is absent. It can initialize checksums first, and present target keys alone cannot prove freshness. Establish a trusted source/target pair before interpreting a passing frozen check as evidence of synchronization.

Recover missing or conflicted state #

When the lockfile is missing, v0 does not necessarily regenerate all present targets: without a previous checksum, it may retain their values. Inspect uncertain source/target pairs before accepting a newly created baseline. Existing translations covers that adoption case.

For a merge conflict, reconcile source and target changes from both branches first. Restore a trustworthy lockfile when possible. If you must rebuild it, review the actual translation pairs because reconstruction records source state, not target freshness.

The legacy YAML repair path retains the last duplicate entry and reports removals. That resolves duplicate syntax, not which branch's wording is correct. Inspect the conflicting values before committing the repaired file with accepted outputs.