Docs / Konzepte
Maschinell übersetzte Seite
Wie ein Lauf funktioniert
Die Übersetzungs-Pipeline von Anfang bis Ende, vom Lesen der Quell-Locale und dem Finden geänderter Keys bis zum Schreiben der Übersetzungen und der Lock-Datei.
Ein Lauf ist eine Pipeline: Quell-Locale lesen, jedes Ziel mit der Lock-Datei vergleichen, nur das
an den Provider schicken, was Arbeit braucht, prüfen, was zurückkommt, schreiben und das Ergebnis
festhalten. Die Pipeline ist dieselbe, ob der Lauf aus der CLI, dem SDK oder watch kommt.
Die Quell-Locale lesen
Der Format-Adapter liest die Quelldatei in eine neutrale Menge von Einträgen mit Keys, sodass jeder
spätere Schritt für jedes Format gleich funktioniert. Ein Quell-Key, dessen Wert für die
Nachrichtensyntax des Formats ungültig ist (ungültiges ICU), wird beiseitegelegt und gemeldet,
statt kaputt an den Provider zu gehen. Eine Quelldatei, die fehlt oder sich nicht parsen lässt,
lässt den Lauf scheitern; siehe SOURCE_ und
SOURCE_.
Mit der Lock-Baseline vergleichen
Der Vergleich macht einen Lauf inkrementell. verbatra liest die vorhandene Zieldatei (eine fehlende
Datei zählt als leer, auch wenn die Writer von xliff und apple-xcstrings ein fehlendes Ziel ablehnen) und vergleicht jeden Quell-Key mit der Lock-Datei, dem
Protokoll dessen, was schon übersetzt wurde:
| Kategorie | Bedeutung | Was der Lauf tut |
|---|---|---|
| missing | das Ziel hat den Key noch nicht | übersetzt ihn |
| changed | die Quelle passt nicht mehr zum festgehaltenen Hash | übersetzt ihn |
| unchanged | die Quelle passt noch zum festgehaltenen Hash | lässt ihn in Ruhe |
| orphaned | der Key steht im Ziel, aber nicht mehr in der Quelle | meldet ihn; entfernt ihn nur mit --prune oder prune: true |
Zurückgehaltene Keys
Zwei Arten von Kandidaten werden zurückgehalten. Ein geänderter Key, dessen aktuellen Wert ein
Mensch geschrieben oder importiert hat, ist standardmäßig geschützt (humanEdits), und ein Key, der
zu pinnedKeys passt, wird nie maschinell übersetzt. Beide bleiben veraltet, bis ein Mensch sie
auflöst; siehe Menschliche Übersetzungen schützen.
In Batches an den Provider
Jeder Kandidat wird zuerst im Übersetzungs-Cache nachgeschlagen. Ein Treffer wird wiederverwendet und erreicht den Provider nie. Von den Fehltreffern werden Keys mit demselben Quellinhalt gruppiert, sodass dieser Text einen Request pro Locale kostet statt einen pro Key.
Die Gruppen gehen in aufeinanderfolgenden Teil-Batches von höchstens maxBatchSize (Standard 50)
an deinen Provider, jeder mit den Einträgen, den Glossarbegriffen dieser Locale und deinem tone.
Scheitert ein Teil-Batch (ein Rate-Limit, ein Timeout, ein widerrufener Key), werden seine Keys für
diesen Lauf zurückgehalten, während die anderen Teil-Batches weiterlaufen. Provider
beschreibt, wie jeder Provider diese Eingaben anwendet.
Die Antwort validieren
Provider-Ausgabe ist Daten, nie freier Text. Bei den LLM-Providern muss die Antwort zu einem festen Schema passen:
- Eine fehlerhafte Antwort oder eine, die einen nie angefragten Key enthält, lässt den ganzen Teil-Batch scheitern.
- Ein angefragter Key, der fehlt oder doppelt zurückkommt, wird noch einmal angefragt.
- Ein Key, der danach immer noch ungelöst ist, wird in diesem Lauf nicht übersetzt.
Die Provider für maschinelle Übersetzung haben kein Antwortschema, aber ihre Ergebnisse durchlaufen dasselbe Integritäts-Gate.
Das Integritäts-Gate ausführen
Eine schema-gültige Übersetzung kann trotzdem kaputt sein, deshalb entscheidet verbatra anhand des Kandidatenwerts selbst, ob er angenommen wird, und vertraut nie dem eigenen Bericht des Providers. Ein Kandidat, der einen Platzhalter verliert, eine ICU-Nachricht oder ihr Markup zerbricht, leer zurückkommt oder entartet, wird zurückgehalten statt geschrieben. Die Prüfungen stehen unter Übersetzungssicherheit.
Über den Adapter schreiben
Angenommene Übersetzungen werden ins Ziel gemergt und vom Format-Adapter geschrieben, atomar und in einer stabilen Key-Reihenfolge: Ein Key, der schon im Ziel steht, behält seine Position, und neue Keys werden in der Reihenfolge der Quelle hinter den vorhandenen angehängt. Ein unterbrochener Schreibvorgang hinterlässt nie eine halb geschriebene Datei, und Reviewer sehen kleine, stabile Diffs.
Die Lock-Datei aktualisieren
Nachdem eine Locale geschrieben ist, werden ihre Lock-Einträge mit den aktuellen Quell-Hashes aufgefrischt. Ein Key, der in diesem Lauf zurückgehalten wurde, behält seinen bisherigen Hash, sodass der nächste Lauf ihn weiter als Arbeit sieht. Jede Locale wird unter einer prozessübergreifenden Schreibsperre geschrieben, sodass zwei sich überlappende Läufe nie gegen eine veraltete Baseline vergleichen oder denselben Aufruf doppelt bezahlen.
Eine Locale nach der anderen, Fehlschläge als Daten
Jede Ziel-Locale läuft für sich, und eine scheiternde Locale hält die anderen nicht auf. Der Lauf liefert eine Zusammenfassung pro Locale: übersetzt, unverändert, verwaist, zurückgehalten, zum Review markiert und Hinweise. Was jedes Feld enthält, steht unter RunSummary.
Was dieses Design garantiert:
- Ein zweiter Lauf ohne Änderungen an der Quelle ruft den Provider für nichts auf.
- Nichts, was eine Prüfung abgelehnt hat, wird je geschrieben, und nichts Zurückgehaltenes wird als erledigt festgehalten.
- Ein Probelauf (
--dry-run) hört nach dem Vergleich auf und liefert dieselbe Form der Zusammenfassung, ohne einen Provider zu bauen oder eine Datei zu schreiben.
Was es nicht tut: Es beurteilt nie, ob eine Übersetzung gut ist. Dafür gibt es Review-Flags und einen Menschen.
Siehe auch
verbatra translate: Flags, Ausgabe und Exit-Codes eines Laufs.- Die Lock-Datei und die Herkunft: was die Baseline festhält.
- Der Übersetzungs-Cache: worauf die Wiederverwendung beruht.
- Übersetzungssicherheit: das Integritäts-Gate und die Review-Flags.
- Fehlercodes: jeder Code, den ein Lauf melden kann.