Lockfile und Cache

Halte Ausgangsstände der Quellen, Ziel-Hashes, entfernte Artefakte und den lokalen Ausführungsverweis bei Aktualisierungen und der Wiederherstellung miteinander im Einklang.

Für inkrementelle Übersetzungen muss bekannt sein, was sich geändert hat. .lingo/lock.json erfasst Quell- und Ziel-Hashes; der Server speichert Artefakte und Übersetzungsergebnisse; ein lokaler Verweis im Home-Verzeichnis kennzeichnet die neueste Ausführung, deren Ergebnisse abzurufen sind. Jeder dieser Bestandteile dient einem anderen Vorgang. Einen davon zu löschen, behebt daher nicht pauschal Probleme mit einem anderen.

Der Ausgangsstand des Projekts #

Das Lockfile verwendet Version 1 und eine files-Zuordnung von Pfaden relativ zum Repository zu SHA-256-Hashes:

json
{
  "version": 1,
  "files": {
    "locales/en.json": {
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }
}

Dieser Hash veranschaulicht das Format und ist nicht zum Kopieren gedacht. Quell-Hashes kennzeichnen die bisherigen Bytes für den inkrementellen Vergleich. Ziel-Hashes helfen, lokale Änderungen vor dem Abruf zu erkennen. Die Datei enthält weder übersetzten Text noch eine Qualitätsbeurteilung.

Erstelle einen Commit mit dem Lockfile und den akzeptierten Quell- und Zieländerungen, die es beschreibt. Fehlen die Zustandsdaten, verhält sich Push wie beim erstmaligen Anlegen eines Ausgangsstands. Fehlerhafte oder nicht unterstützte Zustandsdaten führen dagegen zum Abbruch, statt stillschweigend zurückgesetzt zu werden.

Wann Hashes aktualisiert werden #

Beim Abruf werden Hashes für fertiggestellte Ziele erfasst. Eine Einreichung ohne Abruf schreibt den Ausgangsstand nicht fest. Jedes Dokument wird separat abgeschlossen; die zugehörigen Ziele werden zurückgehalten, bis alle fertiggestellt sind. Ein bestehender Ausgangsstand für die gesamte Quelle wird nur aktualisiert, wenn das Dokument alle konfigurierten Zielsprachen abdeckt, alle Ziele fertiggestellt sind und keine Einschränkung auf bestimmte Schlüssel festgelegt ist. Werden nur einige Sprachen abgerufen, bleibt dieser Ausgangsstand für die anderen erhalten. Dabei kann ein Quelleintrag angelegt werden, falls noch keiner existiert. Eine Aktualisierung einzelner Schlüssel lässt den Quell-Hash unverändert, unabhängig davon, ob push --wait oder Pull die Ergebnisse abruft.

Artefakte und zwischengespeicherte Übersetzungen #

Artefakte werden anhand ihres Inhalts adressiert. Deshalb lädt Push nur Bytes hoch, die dem Server fehlen. Eine frühere Quelle, auf die das Lockfile verweist, muss aus lokalen Bytes oder vom Server wiederherstellbar sein. Ist sie an keinem der beiden Orte vorhanden, sieh dir den angegebenen Lockfile-Eintrag an und stelle nachweislich korrekte Bytes oder einen konsistenten Ausgangsstand wieder her. Ersetze den Hash nicht durch einen geratenen Wert.

Zwischengespeicherte Übersetzungsergebnisse sind nicht dasselbe wie gespeicherte Quelldaten. Das Löschen einer lokalen Zieldatei belegt nicht, dass eine spätere Anfrage das Modell erneut aufruft.

Der Verweis auf die neueste Ausführung #

~/.lingo/runs/<project-hash>.json kennzeichnet den neuesten Push für ein absolutes Projektstammverzeichnis. Der Verweis enthält die IDs der Ausführung, der Organisation und der Lokalisierungs-Engine sowie die Quellsprache und den Erstellungszeitpunkt. Bis die Ergebnisse des Push abgerufen wurden, speichert er außerdem die Anfragekennung. Damit kann ein wiederholter Push die Einreichung wiederverwenden, statt sie zu duplizieren.

Dieser Verweis ist nicht .lingo/run.json und wird nicht mit Git übertragen. Bei einem verschobenen checkout oder auf einem anderen Runner kann er fehlen, selbst wenn Konfiguration und Lockfile identisch sind. Ein neuer Push kann ihn ersetzen. Bewahre die ursprüngliche Ausführungskennung in Betriebsaufzeichnungen ohne geheime Daten auf, bis der Abruf abgeschlossen ist.

Eine Ausführung für einen anderen CI-Job sichern #

Wenn ein Job auf eine Prüfung wartet oder Einreichung und Abruf auf getrennte Jobs verteilt sind, sichere den Verweis, bevor der einreichende Runner nicht mehr verfügbar ist. Führe dies im absoluten Verzeichnis aus, das die vorgesehene .lingo/config.json enthält – unmittelbar nach der Einreichung und vor einem weiteren Push:

sh
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const root = process.cwd();
if (!existsSync(".lingo/config.json")) throw new Error("Run from the configured project root");
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
mkdirSync(".lingo-ci", { recursive: true });
copyFileSync(join(homedir(), ".lingo", "runs", `${hash}.json`), ".lingo-ci/run.json");
writeFileSync(".lingo-ci/project-root.txt", root);
JS

Diese beiden Dateien enthalten den Ausführungsverweis ohne geheime Daten sowie das genaue absolute Projektstammverzeichnis, über das er gefunden wird. Stelle sicher, dass runId im exportierten JSON mit der bei dieser Einreichung ausgegebenen ID übereinstimmt. Ein früherer Verweis kann bestehen bleiben, wenn die Einreichung fehlschlägt, bevor eine neue Ausführung erfasst wird. Bewahre die verifizierten Dateien als zugriffsgeschützte Job-Artefakte zusammen mit der Quellrevision, .lingo/config.json, .lingo/lock.json und den passenden Quell- und Zieldateien auf, einschließlich der Ergebnisse, die noch nicht per Commit festgehalten wurden. Bewahre für die CI-Beispiele mit einer Datei locales/en.json und locales/es.json auf; verwende für ein anderes Projekt die tatsächlich ausgewählten Pfade. Sichere den gesamten gemeinsamen Katalog, wenn Quelle und Ziele dieselbe Datei verwenden. Lege eine ausreichend lange Aufbewahrungsdauer für die Artefakte fest, damit Prüfung und Abruf möglich bleiben. Archiviere niemals das gesamte ~/.lingo, Dateien mit Zugangsdaten oder geheime Umgebungswerte.

Stelle nach der Prüfung dieselbe Revision und den gesicherten Dateistand im selben absoluten Projektstammverzeichnis auf einem autorisierten Runner wieder her. Installiere dieselbe CLI-Version und stelle Zugangsdaten separat über den Mechanismus des Runners für geheime Daten bereit. Stelle von diesem Stammverzeichnis aus nur diesen Verweis wieder her:

sh
node --input-type=module <<'JS'
import { createHash } from "node:crypto";
import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";

const root = readFileSync(".lingo-ci/project-root.txt", "utf8");
if (process.cwd() !== root || !existsSync(".lingo/config.json")) {
  throw new Error("Restore the configured project at its original absolute root");
}
const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
const directory = join(homedir(), ".lingo", "runs");
mkdirSync(directory, { recursive: true });
const destination = join(directory, `${hash}.json`);
if (existsSync(destination)) throw new Error("Preserve the existing run pointer before replacing it");
copyFileSync(".lingo-ci/run.json", destination);
JS
lingo pull --dry-run

Vergewissere dich, dass die angezeigte Ausführung der gesicherten entspricht, löse etwaige Konflikte und verwende anschließend lingo pull. Sieh dir danach die abgerufenen Ergebnisse an. Führe nicht zuerst einen Push aus, da dieser den Verweis ersetzt. Wenn der CI-Dienst das ursprüngliche Stammverzeichnis nicht wiederherstellen kann, verwende für Einreichung und Abruf einen dauerhaft verfügbaren, autorisierten Runner mit diesem Pfad. Den Verweis in einen checkout an einem anderen Speicherort zu kopieren, reicht nicht aus. Entferne den temporären .lingo-ci-Export erst, wenn Abruf und betriebliche Aufbewahrung abgeschlossen sind, und nimm ihn nicht in Übersetzungs-Commits auf.

Bestehende Übersetzungen und manuelle Änderungen #

Bei der Planung für einen eingeschränkten Umfang oder die Erstinitialisierung können vorhandene Ziele übernommen werden. Kontrolliere zuerst deren Sprache und Vollständigkeit: Platzhalter in der Quellsprache können eine Kontrolle auf Vorhandensein bestehen, ohne Übersetzungen zu sein. Das nachträgliche Auffüllen erstellt fehlende reguläre Dateien, ergänzt aber keine fehlenden Schlüssel in einer vorhandenen Datei.

Bei der normalen inkrementellen Verarbeitung werden Änderungen an Zieltexten für unveränderte Schlüssel mitgeliefert, damit sie erhalten bleiben. Geänderte Quellschlüssel können diese Texte ersetzen. JSON verwendet Schlüsselpfade als Identitäten. Deshalb erzeugt das Umbenennen eines Schlüssels neue Arbeit, selbst bei identischem Quelltext. Das unterscheidet sich von der Wiederverwendung anhand von Inhaltsfingerabdrücken in v0.

preservedKeys bietet gezielten Schutz, wenn der Zieltext maßgeblich bleiben soll. Wird die Verarbeitung jedoch für die gesamte Datei erzwungen, entfällt der dafür erforderliche Kontext des aktuellen Ziels. Pull vergleicht vor dem Schreiben neu berechnete Hashes; ein Git-Commit allein verändert diesen Vergleich nicht. Vermeide Änderungen an Zieldateien während des direkten Abrufs mit push --wait.

Branches und gemeinsame Schreibzugriffe #

VorgehensweiseAuswirkung
Im Feature-Branch übersetzenGemeinsame Prüfung von Quelle und Ziel; konkurrierende Änderungen am Ausgangsstand bei Rebases abstimmen.
Übersetzungs-PR nach dem Merge der QuelleSeparate Prüfung mit einer Wartezeit, bevor die übersetzten Änderungen akzeptiert werden.
Übersetzungs-PR der GitHub AppDie Integration steuert Auslöser und das Zurückschreiben; die Freigabe der Ausführung erfolgt unabhängig vom Merge.
Autorisierter Runner schreibt direkt in einen BranchErfordert eine ausdrückliche Schreibberechtigung, Inhaltskontrollen und Schutz vor gleichzeitigen Schreibzugriffen.

Ermittle bei einem Merge-Konflikt im Lockfile zuerst, welche Quell- und Zielrevisionen die beiden Seiten beschreiben. Gleiche die akzeptierten Inhalte ab und behalte anschließend einen konsistenten Ausgangsstand bei oder erstelle ihn über den passenden Workflow neu. Nicht zusammengehörige Hashes zu kombinieren oder das Lockfile nur zur Unterdrückung eines Konflikts zu löschen, kann unvollständige Übersetzungen verbergen.

Wie Sie den Anbieter einrichten, erfahren Sie unter GitHub App, GitHub Actions, GitLab, Bitbucket oder Buildkite. check gleicht die konfigurierten Quellen mit diesem Lockfile ab und meldet fehlende Zieldateien. Die Schlüssel in diesen Dateien werden nur bei React-.jsonc-Katalogen überprüft.

Weitere lokale Zustandsdaten im Home-Verzeichnis #

~/.lingo/update-check.json speichert Versionskontrollen für 24 Stunden zwischen. Zugangsdaten und die Kennung für anonyme Telemetrie werden separat gespeichert. Keiner dieser Speicher enthält übersetzte Dateiinhalte. Ermittle mithilfe von Fehlerbehebung den fehlgeschlagenen Vorgang, bevor du Zustandsdaten entfernst.