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 i18n
# 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.

Subsequent runs — Processes only changed content:

npx lingo.dev@latest i18n
# 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 i18n --force
# Ignores i18n.lock and retranslates all content

Frozen verification — Validates translation completeness:

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

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.