i18n.lock

i18n.lock is a lockfile that stores SHA-256 fingerprints of your source content. The Lingo.dev CLI compares these fingerprints on every run to determine which strings are new or modified - only those enter the translation pipeline. Everything else is skipped.

Structure#

The lockfile uses YAML format:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    title: f8692d39317193acf0e2e47172703c46
    description: g9703e40428204bdf1f3f58283814d57

The dual-hash structure (content hash + key hash) enables key rename detection - the CLI preserves existing translations when a key is renamed but its content stays the same.

Workflow#

First run - creates the lockfile with fingerprints for all source content:

npx lingo.dev@latest run
# Creates i18n.lock

Subsequent runs - translates only the delta:

npx lingo.dev@latest run
# Compares against i18n.lock, translates only changes

Force retranslation - bypasses the lockfile and retranslates everything:

npx lingo.dev@latest run --force

Recreate lockfile - rebuilds the lockfile from the current state of your source files:

npx lingo.dev@latest lockfile --force

Frozen verification - fails if any content requires translation (designed for CI/CD):

npx lingo.dev@latest run --frozen

Deduplication#

When merging branches, the lockfile YAML can accumulate duplicate entries. The CLI deduplicates automatically on every load - duplicate keys under the same checksum block are resolved by keeping the last occurrence. If duplicates are removed, the CLI logs the count.

Deduplication runs during all commands that read the lockfile: run, status, lockfile, and others.

Version control#

i18n.lock must be committed to your repository alongside your locale files. It is the mechanism that makes incremental translation possible - without it, every run would retranslate the entire project.

Next Steps#