CLI v0: Lockfile

Nutze den bisherigen Referenzstand des Quelltexts, um ausstehende Änderungen nachzuvollziehen und den Zustand wiederherzustellen, ohne unfertige Übersetzungen zu verbergen.

Mit i18n.lock kann v0 unveränderten Quelltext von Text unterscheiden, der übersetzt werden muss. Bewahre die Datei zusammen mit dem Quelltext und den akzeptierten Zieltexten auf, auf die sie sich bezieht. Sie erfasst nicht jede manuelle Änderung am Zieltext und belegt auch nicht, dass eine Übersetzung korrekt ist.

Was die Datei erfasst #

In lingo.dev@0.138.10 liegt die Datei im YAML-Format vor, mit version: 1 und einer checksums-Zuordnung. Jeder äußere Abschnitt enthält den Hash eines verarbeiteten Pfadmusters; seine Einträge ordnen Quellschlüsseln MD5-basierte Prüfsummen der Quellwerte zu. Lass die CLI diese Einträge verwalten, statt sie manuell anzulegen.

Eine geänderte Prüfsumme sorgt dafür, dass ein vorhandener Schlüssel für die Übersetzung berücksichtigt wird. Übereinstimmende Hashes der Quellwerte können außerdem einen neuen Schlüssel mit einem entfernten Schlüssel im selben Verarbeitungskontext verknüpfen. So lässt sich die Übersetzung bei einer Umbenennung wiederverwenden. Keiner der beiden Mechanismen bietet ein uneingeschränktes, dateiübergreifendes Translation Memory.

Übersetzung und Ersetzung des Referenzstands auseinanderhalten #

VorgangFunktionsweise
lingo runÜbersetzt die berechneten Änderungen und aktualisiert den gespeicherten Quellstand.
lingo run --forceErzeugt ausgewählte Ausgaben neu, ohne sich auf die regulär ermittelten Änderungen zu stützen.
lingo lockfileErgänzt fehlende Abschnitte zum Quellstand und lässt bereits gefüllte Abschnitte unverändert.
lingo lockfile --forceErsetzt die Quellprüfsummen anhand der aktuellen Dateien, ohne Zieltexte zu übersetzen.
lingo run --frozenKontrolliert die Synchronisierung ohne Übersetzung, initialisiert aber zunächst einen fehlenden Referenzstand.

Angenommen, der englische Quelltext ändert sich, nachdem ein französischer Zieltext akzeptiert wurde. Wenn du die Prüfsumme des Quelltexts mit lockfile --force ersetzt, wird der neue englische Text als Referenzstand gespeichert – obwohl der französische Text möglicherweise noch die alte Bedeutung wiedergibt. Eine Neuerstellung ist daher kein routinemäßiger Weg, einen Synchronisierungsfehler zu beheben.

Auf eine Zielsprache oder bestimmte Schlüssel beschränkte Läufe können Übersetzungen schreiben, ohne den bestehenden gemeinsamen Referenzstand des Quelltexts zu aktualisieren. Ein späterer regulärer Lauf kann die Quelländerung erneut aufgreifen und eine Korrektur überschreiben, die nach dem eingeschränkten Lauf vorgenommen wurde. Gleiche die Ausgaben der betroffenen Sprachen gezielt ab, bevor du den gemeinsamen Referenzstand aktualisierst.

Wenn du eine Quelländerung für mehrere Sprachen abschließt:

  1. Halte den Quellstand unverändert und bewahre i18n.lock auf, solange eine betroffene Ausgabe noch nicht fertig ist. Verwende lingo run für eine reguläre projektweite Aktualisierung oder die dokumentierten eingeschränkten Läufe, wenn Ausgaben eine separate Bearbeitung und Prüfung benötigen.
  2. Sieh dir jede Sprachausgabe an, die von der Ersetzung der Quellprüfsummen erfasst wird – auch Ausgaben, die der letzte eingeschränkte Lauf nicht verändert hat. Behebe Fehler und gleiche akzeptierte manuelle Korrekturen mit diesem Quellstand ab. Wenn eine Ausgabe noch veraltet ist oder Zweifel bestehen, lass die Aktualisierung des gemeinsamen Referenzstands ausstehen.
  3. Wenn die eingeschränkte Bearbeitung den bestehenden Referenzstand unverändert gelassen hat und nun alle erfassten Ausgaben akzeptiert sind, führe lingo lockfile --force im vorgesehenen Projektstammverzeichnis aus. Der Befehl ersetzt Quellprüfsummen, ohne zu übersetzen. Verwende ihn daher nicht, um die vorherige Prüfung zu überspringen, und gehe nicht davon aus, dass die zuletzt ausgewählte Zielsprache diese Ersetzung einschränkt.
  4. Sieh dir den Diff des Lockfile an und erstelle einen gemeinsamen Commit mit dem exakten Quellstand, allen zugehörigen akzeptierten Zieltexten und i18n.lock. Ein späterer Aufruf von lingo run --frozen kann die Synchronisierung anhand dieses abgestimmten Referenzstands kontrollieren; er kann weder die Aktualität der Zieltexte noch die Übersetzungsqualität belegen.

Der Frozen-Modus ist nicht vollständig schreibgeschützt, wenn i18n.lock fehlt. Er kann zunächst Prüfsummen initialisieren, und vorhandene Zielschlüssel allein belegen keine Aktualität. Stelle ein vertrauenswürdiges Quell-/Zieltextpaar her, bevor du eine erfolgreiche Frozen-Kontrolle als Nachweis der Synchronisierung interpretierst.

Fehlenden oder konfliktbehafteten Zustand wiederherstellen #

Wenn das Lockfile fehlt, erzeugt v0 nicht zwangsläufig alle vorhandenen Zieltexte neu: Ohne eine vorherige Prüfsumme können ihre Werte erhalten bleiben. Sieh dir Quell-/Zieltextpaare an, bei denen Zweifel bestehen, bevor du einen neu erstellten Referenzstand akzeptierst. Bestehende Übersetzungen beschreibt diesen Fall der Übernahme.

Gleiche bei einem Merge-Konflikt zuerst die Quell- und Zieltextänderungen aus beiden Branches ab. Stelle nach Möglichkeit ein vertrauenswürdiges Lockfile wieder her. Wenn du es neu erstellen musst, führe eine Prüfung der tatsächlichen Übersetzungspaare durch: Die Rekonstruktion erfasst den Quellstand, nicht die Aktualität der Zieltexte.

Das bisherige YAML-Reparaturverfahren behält bei doppelten Einträgen jeweils den letzten bei und meldet entfernte Einträge. Damit werden syntaktische Duplikate behoben, nicht aber die Frage, welcher Branch die richtige Formulierung enthält. Sieh dir die widersprüchlichen Werte an, bevor du die reparierte Datei zusammen mit den akzeptierten Ausgaben in einem Commit speicherst.