Übersetzungen in CI automatisieren

Mache Übersetzungen zu einem wiederholbaren Bestandteil jedes Releases – von einer bekannten Quellrevision über kontrollierte Dateien bis zu Anwendungstests.

Eine Release-Pipeline verbindet eine Quellrevision bereits mit einem Ergebnis, das Menschen nutzen können. Diese Verbindung muss auch bei der Übersetzung erhalten bleiben. Der Job muss wissen, welche Quellen sich geändert haben, die zugehörigen Zieldateien abrufen und dem nächsten Schritt genügend Nachweise liefern, um sie anzunehmen oder abzulehnen.

Die kniffligen Fälle treten nach der ersten erfolgreichen Anfrage auf: Ein Bewerter arbeitet noch an einer Übersetzung, ein Runner fällt aus oder eine neuere Version des Quelltexts trifft ein, bevor eine ältere Übersetzung fertig ist. Dieser Leitfaden zeigt, wie Sie einen CI-Prozess aufbauen, der mit diesen Fällen umgehen kann, ohne veraltete Dateien zu veröffentlichen oder akzeptierte Änderungen unnötig zu ersetzen. Anbieterspezifische YAML-Konfigurationen finden Sie in den Anleitungen für GitHub Actions, GitLab, Bitbucket und Buildkite.

Festlegen, wo Übersetzungen in den Release-Prozess einfließen #

Nutze die verwaltete GitHub App, wenn ihr Repository-Workflow zu deinem Prozess passt. Änderungen am Standard-Branch erzeugen einen Übersetzungs-Pull Request; die optional aktivierbare Verarbeitung von Pull Requests schreibt in den Branch des jeweiligen Pull Requests. Die Freigabe der Ausführung erlaubt die Übersetzungsarbeit; die Prüfung der Inhalte und der Merge erfolgen anschließend.

Mit einem CLI-Runner übernimmt deine Pipeline die Verantwortung für Übermittlung, Abruf und Bereitstellung. Wähle ein Ziel, das zu deinem Release-Prozess passt:

ZielUnterstützte Entscheidung
Nur als ArtefaktEin anderer Job oder eine Person kontrolliert die Ausgabe, bevor Änderungen am Repository oder Release erfolgen.
Übersetzungs-Branch und Pull RequestSeparate Prüfung der übersetzten Änderungen, bevor sie in den Standard-Branch gelangen.
Branch des Quell-Pull RequestsGemeinsame Prüfung von Quelle und Übersetzungen in einer Änderung.
Direkter Commit auf dem Standard-BranchBereitstellung ohne separaten Übersetzungs-Pull Request, wenn die Branch-Richtlinie dies ausdrücklich erlaubt.

Lege für Schreibzugriffe auf das Repository pro Übersetzungsstand genau einen aktiven schreibenden Prozess fest. Zwei Runner mit unterschiedlichen Quellrevisionen können sonst beim Committen von Dateien und Lockfile miteinander konkurrieren. Für generierte Commits brauchst du außerdem Regeln anhand von Branches, Pfaden oder der Kennzeichnung als generierter Commit, damit sie nicht immer wieder Übersetzungen auslösen.

Die Ausgangsbasis für den Runner festlegen #

Übersetze vor der Aktivierung regelmäßiger Ausführungen eine Quelldatei lokal in eine Sprache und führe die Ressourcenprüfungen der Anwendung aus. Committe die Konfiguration, die akzeptierte Zieldatei und .lingo/lock.json gemeinsam. Ein sauberer checkout sollte dieselbe Quellauswahl und Zielstruktur reproduzieren.

Die Anbieterbeispiele legen die Version mit @lingo.dev/cli@1.21.0 fest. Ersetze diese Version beim Einrichten deines Workflows durch die aktuelle CLI-Version. Wenn du die CLI über die Abhängigkeiten deines Projekts verwalten möchtest, installiere sie mit npm install --save-dev --save-exact @lingo.dev/cli@1.21.0 und committe package.json und package-lock.json. Verwende anschließend npm ci und npx --no-install lingo, um die im Lockfile verzeichnete Version auszuführen.

.lingo/config.json wählt Sprachen, Dateimuster und die Lokalisierungs-Engine aus. Richte dabei auch den Zugriff auf die Organisation und die Lokalisierungs-Engine ein. Wenn der Job ein Projekt initialisieren oder verknüpfen muss, nutze die expliziten Optionen in den Referenzen zu Initialisieren und Verknüpfen, statt auf eine Eingabeaufforderung zu warten, die im unbeaufsichtigten Betrieb niemand beantworten kann.

Wechsle in einem Monorepo vor dem Ausführen der CLI in das Paket mit der gewünschten Konfiguration. Als Positionsargumente übergebene Muster grenzen die Quellen ein, die diese Konfiguration auswählt; sie wählen nicht die Konfiguration eines anderen Pakets aus. Halte für jedes unabhängig konfigurierte Paket den Zustand und die Artefaktpfade zusammen.

Stelle LINGO_API_KEY über die Geheimnisverwaltung des Runners bereit. Das funktioniert ohne interaktive Anmeldung. Führe Jobs mit Zugangsdaten nur mit vertrauenswürdigem Code aus, da Skripte in einem Branch so geändert werden können, dass sie den Schlüssel offenlegen. Einschränkungen für geschützte Variablen und Forks sollten bestimmen, wo der Job ausgeführt wird. Hebe sie nicht auf, nur damit ein nicht vertrauenswürdiger Job erfolgreich durchläuft.

Die richtigen Übersetzungsaufträge übermitteln #

Fordere für eine saubere erste Übersetzung die fehlenden Zieldateien an. Schließe in einem bestehenden Projekt zunächst die regulären Quellaktualisierungen für die vorhandenen Ziele ab, rufe die Ergebnisse ab und kontrolliere sie. Füge dann die fehlenden Sprachen hinzu und ergänze die fehlenden Dateien, ohne die Quellrevision zu ändern. Folge vor diesem Befehl der Anleitung Eine Sprache hinzufügen:

sh
lingo push --backfill-missing --wait

Für Quelländerungen gegenüber der festgelegten Ausgangsbasis:

sh
lingo push --wait

Ein erster einfacher Push kann den Quellzustand erfassen, ohne ihn zu übersetzen. Das Ergänzen fehlender Dateien liefert den entsprechenden Auftrag; spätere reguläre Pushes bestimmen anhand von Quelländerungen, welche Arbeit anfällt. Ein auf einen Teilbereich beschränkter Push oder ein Push zum Ergänzen fehlender Dateien behebt nicht pauschal fehlende Schlüssel in bestehenden Zieldateien.

--wait wartet auf die Ausführung und lädt fertiggestellte Ergebnisse herunter. Ohne diese Option kehrt Push nach der Übermittlung zurück. Wenn auf eine Prüfung gewartet wird oder ein separater Job den Abruf übernimmt, brauchst du das Verfahren zur Sicherung des CI-Ausführungszustands: Bewahre vor dem Beenden des Runners den spezifischen, nicht geheimen Verweis im Home-Verzeichnis, den ursprünglichen absoluten Projekt-Stammpfad sowie den dazugehörigen Zustand von Quelle, Konfiguration, Zieldateien und Lockfile auf. Stelle alles unter demselben Stammpfad wieder her und authentifiziere dich separat, bevor du lingo pull --dry-run und anschließend lingo pull verwendest. Wenn der Runner den Pfad nicht wiederherstellen kann, nutze stattdessen einen persistenten, autorisierten checkout. Archiviere niemals Zugangsdaten oder den gesamten Inhalt von ~/.lingo.

Bewahre den Exit-Status und die gemeldeten Ergebnisse für die Ziele auf. Die aktuelle CLI schlägt fehl, wenn fehlgeschlagene Ziele gemeldet werden. Bei einer menschlichen Prüfung kann eine Ausführung jedoch noch auf Entscheidungen warten. Während die neue Version wartet, kann eine alte Datei weiterhin vorhanden sein. Schließe die Prüfung ab und rufe das Ergebnis ab, bevor der Bereitstellungsjob es veröffentlichen darf.

Das genaue Verhalten der Befehle findest du unter Push und Pull. --yes überspringt die Bestätigung für die erzwungene Neugenerierung; es erteilt weder die Freigabe für eine menschliche Prüfung noch macht es aus jeder ausstehenden Aktion abgeschlossene Arbeit.

Die CLI überspringt Update-Prüfungen in CI. LINGO_DISABLE_UPDATE_CHECK=1 und LINGO_TELEMETRY_DISABLED=1 bieten bei Bedarf explizite Steuerungsmöglichkeiten, ohne die Kommunikation für Übersetzungen zu deaktivieren.

Nachweisen, dass der nächste Schritt nutzbare Dateien erhält #

Gleiche den erwarteten geänderten Eintrag mit der Quellrevision ab. Die bloße Existenz einer Datei ist kein belastbarer Nachweis, wenn der checkout bereits eine ältere Zieldatei enthält. Bewahre die heruntergeladene Ausgabe und den Lockfile-Zustand aus demselben Vorgang auf und kennzeichne fehlgeschlagene oder noch wartende Sprachen deutlich als unvollständig.

Verwende anschließend Prüfungen, die auf die jeweilige Ressource abgestimmt sind:

  • Führe für die React-Extraktion lingo extract --check, lingo check, die TypeScript-Prüfung des Projekts und den eigentlichen Anwendungs-Build aus. Sie untersuchen jeweils unterschiedliche Teile des Ergebnisses.
  • Führe für native Ressourcen die Ressourcengenerierung oder Kompilierung der Plattform aus.
  • Parse bei statischen Inhalten die übersetzten Dokumente und kontrolliere Links, Variablen und die erhaltene Syntax.
  • Führe lingo check aus, damit ein Merge Request fehlschlägt, wenn Übersetzungen veraltet sind. Dafür ist kein API-Schlüssel nötig.

lingo check arbeitet auf Dateiebene: Es meldet eine geänderte Quelle und eine fehlende Zieldatei für jede konfigurierte Sprache, aber keinen fehlenden Schlüssel innerhalb einer bestehenden Android-, Apple-, ARB- oder Markdoc-Datei.

Kontrolliere die Bedeutung der Übersetzung im Rahmen des gewählten Abnahmeprozesses. Ein Build kann eine fehlerhaft formatierte Ressource erkennen und trotzdem einen Satz akzeptieren, der eine wichtige Bedingung verändert. Sobald die technischen Kontrollen und die Prüfung erfolgreich abgeschlossen sind, committe oder veröffentliche nur die vorgesehenen Ausgabepfade. Behalte einen Ausstieg für den Fall bei, dass keine Änderungen vorliegen. Lasse erforderliche Kontrollen den Job fehlschlagen, statt Fehler mit einem bedingungslosen Commit zu verdecken.

Erfasste Arbeit fortsetzen, bevor neue Ersatzaufträge entstehen #

Stelle nach einem unterbrochenen Job seine Ausführungskennung und die Ergebnisse für die Ziele wieder her. Wenn die Übersetzung abgeschlossen ist, rufe diese Ausgabe mit Pull ab, bevor du eine weitere Anfrage übermittelst. Wenn sich eine lokale Zieldatei während der Wartezeit geändert hat, löse den Pull-Konflikt so, dass die akzeptierte Änderung sichtbar bleibt. Erzwungenes Überschreiben kann genau die Korrektur verwerfen, die der Workflow bewahren soll.

Behalte das Lockfile während der Diagnose bei. Wenn du es löschst, ändert sich die Quellbasis für die nächste Ausführung. So kann aus einer gezielten Wiederherstellung eine andere Aufgabe werden. Sieh dir den Diff an und wiederhole nur den noch unvollständigen Teilbereich. Eine unterbrochene Lokalisierungsausführung wiederherstellen erläutert diese Entscheidung.

Erprobe vor dem Einrichten geplanter Job-Ausführungen neben dem Erfolgsfall auch einmal das Warten auf eine menschliche Prüfung und einen unterbrochenen Abruf. Der Release-Schritt sollte den zuletzt akzeptierten Stand beibehalten und die unvollständige Sprache kenntlich machen, statt jede zufällig vorhandene Datei zu akzeptieren.