i18n.lock Lockfile

i18n.lock ist eine Lockfile, die Content-Checksummen verfolgt, um unnötige Neuübersetzungen zu verhindern und die Performance der Lingo.dev CLI zu optimieren.

i18n.lock speichert Checksummen von Quellinhalten und Übersetzungsschlüsseln, um zu identifizieren, was sich zwischen Übersetzungsdurchläufen geändert hat. Dadurch werden nur neue oder geänderte Inhalte übersetzt, was die Verarbeitungszeit und Übersetzungskosten reduziert.

Lockfile-Struktur

i18n.lock verwendet ein strukturiertes YAML-Format zur Speicherung von Content-Checksummen:

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

Konfigurationselemente:

  • version — Lockfile-Schemaversion für Migrationskompatibilität
  • checksums — Map von Content-Checksummen zu Schlüssel-Checksummen, die übersetzte Inhalte verfolgt
  • checksums.[content-hash] — SHA-256-Hash des Quellinhalts, der als eindeutiger Identifier dient
  • checksums.[content-hash].key — SHA-256-Hash des Übersetzungsschlüssels, der die Erkennung von Schlüsselumbenennungen ermöglicht

Die Lingo.dev CLI bewahrt bestehende Übersetzungen, wenn sie identische Inhalte mit unterschiedlichen Schlüssel-Checksummen erkennt. Es erfolgt keine Neuübersetzung, wodurch die Übersetzungskonsistenz gewahrt bleibt und gleichzeitig Änderungen an der Schlüsselorganisation ermöglicht werden. Weitere Informationen zur Schlüsselumbenennung.

Workflow-Integration

i18n.lock arbeitet automatisch während der Übersetzungsworkflows:

Erster Durchlauf — Erstellt Lockfile mit initialen Content-Checksummen:

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

Lockfile neu erstellen — Erstellt die Lockfile von Grund auf neu:

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

Tipp: Sie können diesen Befehl sicher verwenden, um die Lockfile während der Auflösung von Merge-Konflikten auf ihren tatsächlichen Zustand zurückzusetzen. Die Deduplizierung läuft auch automatisch bei jedem Laden; siehe Lockfile-Deduplizierung.

Nachfolgende Durchläufe — Verarbeitet nur geänderte Inhalte:

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

Neuübersetzung erzwingen — Umgeht die Lockfile-Optimierung und übersetzt alle Inhalte neu, wobei die Lockfile neu erstellt wird:

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

Frozen-Verifizierung — Validiert die Vollständigkeit der Übersetzung:

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

Lockfile-Deduplizierung

Die Lockfile-YAML kann doppelte Übersetzungsschlüssel unter demselben Checksummen-Block enthalten. Standard-YAML-Parser behalten nur das letzte Vorkommen, was zu verlorenem Tracking und Merge-Konflikten führen kann, die schwer manuell aufzulösen sind.

Lingo.dev CLI ist für einen konsistenten Lockfile-Zustand konzipiert. Es dedupliziert die Lockfile automatisch bei jedem Laden. Doppelte Schlüssel unter einem Checksummen-Block werden erkannt und entfernt; das letzte Vorkommen wird beibehalten (Last-Write-Wins, entsprechend dem üblichen Merge-Verhalten). Dadurch bleibt die Lockfile intern konsistent und entspricht dem, was zurückgeschrieben wird.

Wann es läuft — Die Deduplizierung läuft bei jedem Laden, einschließlich:

  • 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

Wenn Duplikate entfernt werden, protokolliert die CLI eine Meldung wie: Removed 3 duplicate entries from i18n.lock. Es ist keine Benutzeraktion erforderlich; der Schritt ist idempotent und sicher bei jedem Laden auszuführen. Bei schwierigen oder wiederkehrenden Merge-Problemen können Sie weiterhin npx lingo.dev@latest lockfile --force verwenden, um die Lockfile von Grund auf neu zu erstellen.

Beispiel — Nach dem Zusammenführen zweier Branches, die beide dieselben Schlüssel geändert haben:

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

Beim Laden dedupliziert die CLI und behält das letzte Vorkommen jedes Schlüssels:

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

Zwei doppelte Einträge werden entfernt.

Version-Control-Integration

i18n.lock muss zusammen mit den Übersetzungsdateien in die Versionskontrolle eingecheckt werden.

Die Lockfile ist ein wesentlicher Bestandteil des inkrementellen Übersetzungssystems der Lingo.dev CLI und macht es für Projekte jeder Größe praktikabel.