Anleitung für Bitbucket Pipelines
Übersetze Dateien in Bitbucket Pipelines, committe die Ergebnisse zurück ins Repository und lass Pull Requests mit veralteten Übersetzungen fehlschlagen.
Nutze eine Bitbucket-Pipeline, um die in deiner Lingo.dev-Konfiguration ausgewählten Quelldateien zu übersetzen. Die CLI übermittelt den Auftrag und lädt die Zieldateien herunter. Deine Pipeline legt fest, wie du sie aufbewahrst und bereitstellst. Diese Anleitung beginnt mit einer benutzerdefinierten, manuell gestarteten Pipeline. So kannst du dir zunächst eine Übersetzung ansehen, bevor du regelmäßige Ausführungen einplanst.
Die Verbindung erfolgt über einen API-Aufruf deines Runners, nicht über eine native Anbindung an ein Bitbucket-Konto. Schreibzugriffe auf das Repository und das Erstellen von Pull Requests erfordern separate Bitbucket-Berechtigungen.
Einen funktionsfähigen Katalog vorbereiten #
Folge lokal dem CLI-Schnellstart und committe anschließend .lingo/config.json, die gesichteten Zieldateien und .lingo/lock.json. Quell- und Zielsprachen, die Lokalisierungs-Engine und Dateimuster legst du in dieser Konfiguration fest.
Das Beispiel verwendet locales/en.json und hat nur ein Ziel: eine bereits vorhandene spanische Datei unter locales/es.json. Führe bei mehreren Zielen test -s und die JSON-Prüfungen für jede Zieldatei einmal aus und gib in den anderen Befehlen, die locales/es.json nennen, sämtliche Zielpfade an. Das Lockfile vermerkt die Quelle als übersetzt, sodass ein späterer Push sie überspringt. Ein Ziel, das im Artefakt fehlt, bleibt veraltet. Erstelle fehlende Zieldateien mit lingo push --backfill-missing --wait, bevor du den unten stehenden Befehl für wiederkehrende Quelländerungen verwendest. Ein regulärer Push verarbeitet spätere Änderungen an der Quelle; das nachträgliche Erstellen fehlender Dateien ergänzt keine fehlenden Schlüssel in einem bereits vorhandenen Ziel.
Speichere LINGO_API_KEY als geschützte Repository-Variable. Die CLI liest nur diesen Namen; eine LINGODOTDEV_API_KEY-Variable aus der vorherigen CLI wird ignoriert. Benenne sie daher um. Führe die Pipeline mit vertrauenswürdigem Code aus und lass Shell-Tracing beim Umgang mit Zugangsdaten deaktiviert. Auch eine geschützte Variable kann nicht bedenkenlos beliebigen Skripten aus einem Pull Request zugänglich gemacht werden.
Die Beispiele sind auf CLI-Version 1.21.0 festgelegt. lingo check kontrolliert Übersetzungsdateien ab CLI-Version 1.20.0. Wenn du die Version über die Abhängigkeiten und das Lockfile deines Projekts verwalten möchtest, folge der Anleitung zur CI-Einrichtung.
Übersetzen und das Ergebnis aufbewahren #
Füge diese benutzerdefinierte Pipeline zu bitbucket-pipelines.yml hinzu:
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git diff -- locales/es.json .lingo/lock.json
artifacts:
- locales/es.json
- .lingo/lock.jsonStelle sicher, dass der Runner die CLI von npm herunterladen kann. Passe die Dateipfade an deine Konfiguration an.
Kontrolliere die Organisations- und Engine-IDs in der committeten Datei .lingo/config.json. Committe eine kleine Änderung an der englischen Quelle und führe translate-catalog auf diesem vertrauenswürdigen Branch aus. Sieh dir das Ergebnis der Ausführung und den Diff an. Lade anschließend das Artefakt herunter und vergleiche den geänderten spanischen Eintrag mit der Quellrevision. Lade den Katalog über die Anwendung, um Variablen und Darstellung zu kontrollieren.
Die Kontrolle auf vorhandene Dateien und das Parsen von JSON erkennen fehlende oder fehlerhafte Ausgaben. Sie können jedoch eine alte, gültige Datei nicht von der neu angeforderten Übersetzung unterscheiden. Wenn die Lokalisierungs-Engine eine menschliche Prüfung erfordert, schließe diese ab und rufe die fertigen Ergebnisse ab, bevor du das Artefakt akzeptierst.
Den Zustand für Übermittlung und Abruf sichern #
Push ist standardmäßig asynchron. push --wait wartet, bis die Ausführung abgeschlossen ist, und schreibt die übersetzten Dateien in den checkout. Ohne --wait stößt lingo push die Ausführung nur an und beendet sich. Der nächste Befehl findet deshalb keine neuen Dateien, die er behalten oder committen kann. Bei Wartezeiten auf eine menschliche Prüfung kann weiterhin ein späterer Abrufschritt nötig sein.
Ergänze vor einer Wartephase für die Prüfung oder einem separaten Abrufschritt das Verfahren zur Sicherung des CI-Ausführungszustands. Exportiere nach der Übermittlung den konkreten Verweis und den ursprünglichen absoluten Pfad zum Projektstamm, auch wenn eine anschließende Validierung fehlschlägt. Bewahre .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, die Zieldatei und das Lockfile als zugriffsbeschränkte Artefakte auf. Wähle eine Aufbewahrungsdauer, die genügend Zeit für die Prüfung lässt. Sorge dafür, dass der ursprüngliche Fehler des Schritts sichtbar bleibt, und archiviere niemals den gesamten Inhalt von ~/.lingo oder Zugangsdaten.
Stelle für den Abruf dieselbe Revision und den aufbewahrten Dateizustand am aufgezeichneten absoluten Projektstammpfad wieder her. Stelle nur diesen Verweis wieder her, übergib die Zugangsdaten separat und verwende Pull mit --dry-run, bevor du die Ergebnisse sammelst. Kann ein späterer Pipeline-Schritt den Pfad nicht wiederherstellen, nutze stattdessen für Übermittlung und Abruf einen persistenten, autorisierten Runner. Löse lokale Konflikte in den Ausgabedateien gezielt: Ein erzwungener Pull kann Änderungen eines Prüfers verwerfen.
Festlegen, wie Ergebnisse ins Repository gelangen #
Ein Artefakt genügt, wenn eine Person oder ein späterer Release-Job die Ergebnisse vor der Bereitstellung sichten soll. Bewahre die übersetzten Dateien und das Lockfile aus demselben abgeschlossenen Vorgang gemeinsam auf.
Für eine Repository-Aktualisierung mit Prüfung pushe auf einen Übersetzungs-Branch und öffne anschließend einen Pull Request in Bitbucket oder über dessen dokumentierte API. Ein Schritt kann über den standardmäßigen origin ohne zusätzliche Zugangsdaten in sein eigenes Repository pushen, wie der nächste Abschnitt zeigt. Füge nur dann einen Repository-SSH-Schlüssel oder ein Zugriffstoken hinzu, wenn Branch-Berechtigungen diesen Push blockieren oder du den Pull Request über die API erstellen möchtest. Letzteres erfordert Schreibzugriff auf Pull Requests. Konfiguriere die Bot-Identität des Teams, nimm nur bekannte Zielpfade und .lingo/lock.json in den Staging-Bereich auf und beende den Schritt, wenn der Diff im Staging-Bereich leer ist. Verwende unterschiedliche Branch-Namen oder verwende Branches gezielt wieder, damit parallele Ausführungen einander nicht überschreiben.
Ein direkter Commit nutzt dieselben Ausgabekontrollen und dieselbe eingeschränkte Auswahl für den Staging-Bereich, führt den Push aber auf den ausdrücklich vorgesehenen vertrauenswürdigen Branch aus. Bei einer direkten Bereitstellung auf dem Standard-Branch entfällt der Prüfungsschritt des Übersetzungs-Pull-Requests. Das muss daher eine bewusste Entscheidung im Rahmen der Branch-Richtlinien sein. Führe bei beiden Modellen eine Prüfung der resultierenden Anwendungsausgabe durch.
Halte den Lingo.dev-API-Schlüssel von den Repository-Zugangsdaten getrennt. Er gehört in die Umgebung des Übersetzungsprozesses, niemals in ein Git-Remote, eine committete Datei oder ein Ausgabeartefakt. Nimm explizite Pfade statt git add . in den Staging-Bereich auf, damit keine unbeteiligten Runner-Dateien erfasst werden.
Übersetzungen zurück in den Branch committen #
Diese Branch-Pipeline übersetzt jede Änderung, die main erreicht, und committet das Ergebnis in main. Sie setzt voraus, dass die anfängliche Übersetzung der bestehenden Inhalte bereits committet und die menschliche Prüfung der Engine deaktiviert ist. So wird die Übersetzung in einem Schritt abgeschlossen. Füge ihren branches-Abschnitt unter demselben pipelines-Schlüssel wie die benutzerdefinierte Pipeline hinzu. Die vollständige Datei sieht dann so aus:
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
script:
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git diff -- locales/es.json .lingo/lock.json
artifacts:
- locales/es.json
- .lingo/lock.json
branches:
main:
- step:
name: Translate and commit
auth:
system:
scopes:
- read:git:bitbucket
- write:git:bitbucket
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "[skip ci] Update translations"
- git push origin "HEAD:$BITBUCKET_BRANCH"lingo push --wait beendet sich mit einem Exit-Code ungleich null, wenn ein Ziel fehlschlägt. Dadurch stoppt der Schritt vor dem Commit. Wenn sich nichts geändert hat, gibt der Befehl "Nothing to push" aus, der Diff im Staging-Bereich ist leer und der Schritt endet ohne Commit.
Pipelines richtet origin als Remote ein, damit ein Schritt ohne zusätzliche Zugangsdaten Änderungen in sein eigenes Repository zurückpushen kann. Der auth-Block des Schritts gewährt dessen integriertem Token Git-Push-Zugriff. Ab dem 30. April 2027 gewährt Bitbucket diesen Zugriff nicht mehr für Schritte ohne auth-Block. Selbst gehostete Runner benötigen Version 6.1.0 oder neuer, um auth zu verwenden. Wenn eine Branch-Einschränkung für main den Push blockiert, füge main in den Einstellungen der Einschränkung unter Pipelines-Schreibzugriff als Quell-Branch hinzu. Alternativ kannst du dem Schritt einen SSH-Schlüssel oder einen Zugriffstoken mit Schreibzugriff geben, wie in Bitbuckets Anleitung zum Zurückpushen beschrieben.
Der Schritt löst keine Schleife aus. [skip ci] in der Commit-Nachricht verhindert, dass Bitbucket für den Übersetzungs-Commit eine Pipeline startet. Ohne diesen Zusatz würde die nächste Ausführung nichts zum Pushen finden, da das committete .lingo/lock.json die neue Quelle bereits erfasst. Wenn sich der Branch während der Übersetzung weiterbewegt hat, lehnt Git den Push ab. Die Pipeline für den neueren Commit übernimmt dann dessen Übersetzung.
Auslöser und Paketpfade anpassen #
Füge automatische Branch- oder Pull-Request-Auslöser erst hinzu, wenn feststeht, welcher Quellcode auf Zugangsdaten zugreifen darf und welcher Branch Schreibzugriffe erhalten kann. Einem Fork fehlen möglicherweise geheime Zugangsdaten oder ein beschreibbares Ziel. Löse das nicht, indem du seinen nicht vertrauenswürdigen Code mit privilegierten Zugangsdaten ausführst.
Generierte Commits sollten Übersetzungen nicht endlos auslösen. Wähle relevante Quellpfade und vertrauenswürdige Branches aus, wende eine geeignete Regel für generierte Commits an und behalte die Beendigung bei ausbleibenden Änderungen bei. Bei unveränderter Quelle ist es durchaus normal, dass kein Diff entsteht.
Führe die CLI bei einer Konfiguration unter apps/web/.lingo/config.json aus dem Verzeichnis apps/web aus. Für Pipeline-Artefaktpfade gelten weiterhin die repository-relativen Regeln von Bitbucket. Verwende daher Pfade wie apps/web/locales/es.json und apps/web/.lingo/lock.json. Ein anderes CLI-Arbeitsverzeichnis ändert nichts an der Konvention für Artefaktpfade.
Pull Requests mit veralteten Übersetzungen fehlschlagen lassen #
lingo check vergleicht jede konfigurierte Quelle mit .lingo/lock.json und setzt voraus, dass alle Zieldateien vorhanden sind. Der Befehl endet mit Exit-Code 1, wenn sich eine Quelle seit ihrer letzten Übersetzung geändert hat, für eine Quelle kein Lockfile-Eintrag vorliegt, eine Zieldatei fehlt oder keine Quelldatei den files-Mustern entspricht. Er benötigt weder einen API-Schlüssel noch eine Repository-Variable und schreibt nichts. Abgesehen von der CLI-Telemetrie, die DO_NOT_TRACK=1 deaktiviert, führt er keine Netzwerkaufrufe aus. Im npx-Beispiel wird die CLI allerdings vor der Prüfung von npm heruntergeladen. Der Befehl ersetzt die --frozen-Freigabebedingung der bisherigen CLI.
Der Befehl kontrolliert Dateien, nicht Schlüssel: Ein manuell bearbeitetes Ziel besteht die Prüfung. Fehlende Schlüssel in einem bereits vorhandenen Ziel werden nicht gemeldet – außer in React-.jsonc-Katalogen. Ohne .lingo/lock.json kann der Befehl Quelländerungen nicht erkennen. Eine geänderte oder noch nie gepushte Quelle führt daher nicht zum Fehlschlagen; darauf weist er auf stderr hin. Nimm das Lockfile, das lingo push schreibt, in einen Commit auf.
Die Schranke ist für eine Konfiguration ohne die oben beschriebene Branch-Pipeline gedacht. Die folgende Tabelle erklärt, warum. Füge unter pipelines einen pull-requests-Abschnitt hinzu, neben custom, falls du die manuelle Pipeline beibehältst. Für sich allein sieht die Datei so aus:
image: node:22
pipelines:
pull-requests:
"**":
- step:
name: Check translations
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkDie Schranke eignet sich für eine Konfiguration, in der Übersetzungen zusammen mit der Quelländerung committet werden:
| Wo die Übersetzung ausgeführt wird | Schranke für jeden Pull Request |
|---|---|
Entwicklerinnen und Entwickler führen lingo push --wait aus und committen das Ergebnis, bevor sie den Pull Request öffnen | Ja. Sie lässt einen Pull Request fehlschlagen, wenn dessen Quelle ohne Übersetzung geändert wurde. |
Die Branch-Pipeline committet nach dem Merge in main | Nein. Bei Feature-Pull-Requests werden die Quellen bewusst vor der Übersetzung geändert. |
Quell-Hashes sind bytegenau. Sorge dafür, dass der checkout, in dem lingo push ausgeführt wurde, und der CI-checkout dieselben Zeilenenden verwenden, etwa mit * text=auto eol=lf in .gitattributes. Behalte auch die Ressourcenkontrollen der Anwendung bei.
Fehlende Ergebnisse wiederherstellen oder Arbeit stoppen #
Untersuche bei fehlenden Ergebnissen die ausgewählten Quelldateien, den Ausgangsstand, die Abdeckung der Zieldateien, die Verfügbarkeit geschützter Variablen, den Prüfungsstatus und die gemeldeten Fehler. Stelle die aufgezeichnete Ausführung wieder her, bevor du einen weiteren Auftrag übermittelst. Bevor du fehlende Zieldateien in einem bestehenden Projekt nachträglich erstellst, schließe die regulären Aktualisierungen der vorhandenen Zieldateien ab, rufe sie ab und sichte sie. Halte danach die Quellrevision unverändert, bis die fehlenden Zieldateien erstellt sind. Folge für diese Abfolge der Anleitung Eine Sprache hinzufügen. Nutze eine erzwungene Neugenerierung nur, wenn du den ausgewählten, bereits akzeptierten Text tatsächlich ersetzen möchtest. Wiederherstellung nach fehlgeschlagenen Ausführungen erklärt, wie du einen weiteren Versuch anforderst, ohne eine Ersetzung zu erzwingen.
Deaktiviere den Pipeline-Auslöser, um neue Jobs zu stoppen. Sieh dir beim Abbrechen des Runners bereits übermittelte Server-Ausführungen separat an. Entferne nicht mehr benötigte API-Variablen und Schreibrechte beim Anbieter, wenn du diese Einrichtung außer Betrieb nimmst.