i18n.lock Lockfile

i18n.lock is a lockfile that tracks content checksums to prevent unnecessary retranslations and optimize Lingo.dev CLI performance.

i18n.lock stores checksums of source content and translation keys to identify what has changed between translation runs. As a result, only new or modified content gets translated, reducing processing time and translation costs.

Lockfile Structure

i18n.lock uses a structured YAML format to store content checksums:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    key: f8692d39317193acf0e2e47172703c46
  b18975fb19122ebb67g0ef817641f553:
    key: g9703e40428204bdf1f3f58283814d57

Configuration elements:

  • version — Lockfile schema version for migration compatibility
  • checksums — Map of content checksums to key checksums that tracks translated content
  • checksums.[content-hash] — SHA-256 hash of source content that serves as unique identifier
  • checksums.[content-hash].key — SHA-256 hash of translation key that enables key rename detection

Lingo.dev CLI preserves existing translations when it detects identical content with different key checksums. No retranslation occurs, maintaining translation consistency while allowing key organization changes. Read more about key renaming.

Workflow Integration

i18n.lock operates automatically during translation workflows:

First run — Creates lockfile with initial content checksums:

npx lingo.dev@latest run
# Creates i18n.lock with all source content checksums

Recreate lockfile — Recreates the lockfile from scratch:

npx lingo.dev@latest lockfile --force
# Recreates i18n.lock with all source content checksums

Tip: You can safely use this command to reset the lockfile to its true state during merge conflict resolution. Deduplication also runs automatically on each load; see Lockfile deduplication.

Subsequent runs — Processes only changed content:

npx lingo.dev@latest run
# Compares current content against i18n.lock
# Translates only new or modified content

Force retranslation — Bypasses lockfile optimization and retranslates all content, recreating the lockfile:

npx lingo.dev@latest run --force
# Ignores i18n.lock and retranslates all content

Frozen verification — Validates translation completeness:

npx lingo.dev@latest run --frozen
# Fails if any content requires translation
# Used in CI/CD to ensure complete translations

Lockfile deduplication

The lockfile YAML can contain duplicate translation keys under the same checksum block. Standard YAML parsers keep only the last occurrence, which can lead to lost tracking and merge conflicts that are difficult to resolve by hand.

Lingo.dev CLI is built for consistent lockfile state. It deduplicates the lockfile automatically every time it is loaded. Duplicate keys under a checksum block are detected and removed; the last occurrence is kept (last-write-wins, matching common merge behavior). As a result, the lockfile stays internally consistent and matches what gets written back.

When it runs — Deduplication runs on every load, including:

  • npx lingo.dev@latest run
  • npx lingo.dev@latest pull
  • npx lingo.dev@latest push
  • npx lingo.dev@latest status
  • npx lingo.dev@latest lockfile

If duplicates are removed, the CLI logs a message such as: Removed 3 duplicate entries from i18n.lock. No user action is required; the step is idempotent and safe to run on every load. For difficult or recurring merge issues, you can still use npx lingo.dev@latest lockfile --force to recreate the lockfile from scratch.

Example — After merging two branches that both changed the same keys:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.hello: abc123
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: ghi012
    button.submit: jkl345

On load, the CLI deduplicates and keeps the last occurrence of each key:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: jkl345

Two duplicate entries are removed.

Version Control Integration

i18n.lock must be committed to version control along with the translation files.

The lockfile is an essential part of Lingo.dev CLI's incremental translation system, making it practical for projects of any size.