Buildkite-Anleitung
Dateien in einer Buildkite-Pipeline übersetzen, die Ergebnisse per Push zurück in den Branch übertragen und Pull Requests mit veralteten Übersetzungen fehlschlagen lassen.
Mit einem Buildkite-Schritt kannst du Repository-Dateien über die Lingo.dev CLI auf deinen eigenen Agents übersetzen. Die CLI übermittelt die Quelldateien, die deine Lingo.dev-Konfiguration auswählt, und schreibt die übersetzten Dateien in den checkout. Deine Pipeline bestimmt, wie die Ergebnisse bereitgestellt werden. Buildkite verwaltet die Agents, Secrets und den Repository-Zugriff; Lingo.dev verarbeitet die Dateien über eine Lokalisierungs-Engine.
Dies ist eine CI-Anleitung, keine native Buildkite-Anbindung. Beginne mit einem Übersetzungsschritt auf dem Standard-Branch oder in Pull-Request-Builds und sieh dir den ersten Commit dieses Schritts an. Ergänze die Pull-Request-Prüfung nur, wenn die zugehörige Tabelle diese Freigabebedingung für deine Einrichtung empfiehlt.
Repository und Agent vorbereiten #
Führe den CLI-Schnellstart lokal durch. Erstelle einen Commit mit .lingo/config.json, den akzeptierten Zieldateien und .lingo/lock.json. Die Konfiguration legt die Quellsprache, Zielsprachen, Dateimuster und Lokalisierungs-Engine fest. Die Beispiele verwenden locales/en.json als Quelle und eine vorhandene spanische Zieldatei unter locales/es.json. Führe bei weiteren Zielen die test -s- und JSON-Prüfungen einmal für jede Zieldatei aus und gib in den anderen Befehlen, die locales/es.json nennen, sämtliche Zielpfade an. Alternativ kannst du das gesamte Zielverzeichnis, etwa locales/, für den Commit vormerken. Das Lockfile hält fest, dass die Quelle übersetzt wurde, sodass ein späterer Push sie überspringt. Eine Zieldatei, die du nicht in den Commit aufnimmst, bleibt veraltet.
Erstelle fehlende Zieldateien mit lingo push --backfill-missing --wait, bevor du den regelmäßig ausgeführten Schritt einrichtest. Verwende für spätere Änderungen an der Quelle das normale lingo push --wait. Das nachträgliche Anlegen fehlender Dateien ergänzt keine fehlenden Schlüssel in einer vorhandenen Zieldatei.
Der Agent benötigt Node.js, npm und Git sowie Netzwerkzugriff auf die npm-Registry und Lingo.dev. Die Repository-Zugangsdaten, die der Agent für den checkout verwendet, etwa ein Deploy-Schlüssel, müssen auch Pushes auf den Branch erlauben, in den der Schritt schreibt.
Speichere den Lingo.dev-API-Schlüssel als Buildkite-Secret mit dem Namen LINGO_API_KEY. Die CLI liest nur diesen Namen; eine LINGODOTDEV_API_KEY-Variable aus der vorherigen CLI wird ignoriert. Benenne sie daher um. Lade das Secret nur im Übersetzungsschritt. Der secrets:-Schlüssel des Schritts erfordert Buildkite Agent 3.106.0 oder neuer. Der Agent muss in dem Cluster laufen, in dem das Secret gespeichert ist; mit älteren Agents schlägt die Pipeline fehl. Entferne bei älteren Agents oder Agents ohne Cluster secrets: und exportiere stattdessen LINGO_API_KEY für diesen Schritt über einen environment-Hook des Agents oder dein Secrets-Plugin.
Lass Builds aus geforkten Repositorys von Drittanbietern zulassen in den GitHub-Einstellungen der Pipeline deaktiviert. Pull-Request-Builds eines Forks verwenden dessen eigene pipeline.yml. Diese kann einen Schritt hinzufügen, der das Secret liest, und kein if: in deiner Datei kann das verhindern. Ergänze außerdem eine Zugriffsrichtlinie für das Secret, damit nur Builds dieser Pipeline es lesen können.
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 per Push zurück in den Branch übertragen #
Dieser Schritt übersetzt jede Änderung, die den Standard-Branch erreicht, und überträgt das Ergebnis per Push in denselben Branch. Er setzt voraus, dass die anfangs ergänzten Zieldateien bereits in einem Commit enthalten sind und die menschliche Prüfung der Engine deaktiviert ist. So wird die Übersetzung in einem Schritt abgeschlossen. Füge ihn zu .buildkite/pipeline.yml hinzu:
steps:
- label: "Translate"
if: build.branch == pipeline.default_branch && build.pull_request.id == null
concurrency: 1
concurrency_group: "lingo-translations"
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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:refs/heads/$${BUILDKITE_BRANCH}"--wait sorgt dafür, dass der Schritt auf den Durchlauf wartet und die übersetzten Dateien in den checkout schreibt. Ohne diese Option übermittelt lingo push nur den Durchlauf und beendet sich. Der Schritt findet dann nichts für einen Commit. lingo push --wait beendet sich mit einem Exit-Status ungleich null, wenn ein Ziel fehlschlägt, sodass der Schritt vor dem Commit stoppt. Wenn sich nichts geändert hat, gibt er „Nichts zu übertragen“ aus, der vorgemerkte Diff ist leer und der Schritt endet ohne Commit.
Buildkite führt den checkout eines einzelnen Commits statt eines Branches durch. Deshalb gibt der Push den Branch ausdrücklich an. $$ lässt BUILDKITE_BRANCH unverändert, damit die Shell es bei der Ausführung des Schritts expandiert. Mit einem einzelnen $ würde Buildkite den Branch-Namen bereits beim Hochladen der Pipeline in den Befehlstext schreiben. concurrency und concurrency_group sorgen dafür, dass immer nur eine Übersetzung gleichzeitig läuft. Wenn sich der Branch während der Übersetzung geändert hat, lehnt Git den Push ab; der Build für den neueren Commit übersetzt die Änderung.
Der Schritt gerät nicht in eine Schleife. Buildkite überspringt Builds für Commits, deren Nachricht [skip ci] enthält. Ohne diese Angabe würde der nächste Build nichts für einen Push finden, weil das im Commit enthaltene .lingo/lock.json die neue Quelle bereits erfasst.
Ein direkter Push auf den Standard-Branch umgeht die Prüfung eines Übersetzungs-Pull-Requests. Triff diese Entscheidung daher bewusst im Rahmen deiner Branch-Richtlinie. Wenn du zuerst eine Prüfung der Übersetzungen durchführen möchtest, übertrage sie stattdessen per Push auf einen separaten Branch wie lingo/translations und öffne mit den Werkzeugen deines Git-Anbieters einen Pull Request.
In Pull-Request-Builds übersetzen #
Verwende diesen Schritt anstelle des Schritts für den Standard-Branch, um die Quelländerungen jedes Pull Requests auf dessen eigenem Branch zu übersetzen. Es gelten dieselben Voraussetzungen wie für den Schritt auf dem Standard-Branch. Sein if: überspringt Pull Requests aus Forks, da der Schritt keinen Push auf den Branch eines Forks ausführen kann.
Der Schritt benötigt zwei Einstellungen in den GitHub-Einstellungen der Pipeline. Aktiviere Build beim Öffnen oder Aktualisieren eines Pull Requests. Deaktiviere Branches bauen oder beschränke diese Einstellung auf den Standard-Branch. Bei aktivierten Branch-Builds kann ein Push auf einen Pull-Request-Branch einen Build ohne Pull-Request-Details starten. Der Schritt überspringt diesen Build, sodass nichts übersetzt wird und nichts fehlschlägt.
Das if: schützt LINGO_API_KEY nicht. Buildkite liest es aus der eigenen pipeline.yml des Pull Requests, und ein Fork kann diese Datei ändern. Fork-Builds müssen daher deaktiviert bleiben, wie in der Einrichtung beschrieben. Auch ein Pull Request aus einem Branch im Repository kann die Datei ändern. Wer einen Branch per Push übertragen kann, kann daher über diesen Schritt den Schlüssel lesen. Verwende den Schritt nur dort, wo alle Personen mit Push-Zugriff den Schlüssel besitzen dürfen.
steps:
- label: "Translate pull request"
if: build.pull_request.id != null && build.pull_request.repository.fork != true
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# 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 "Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"Die Commit-Nachricht enthält absichtlich kein [skip ci]. Buildkite erstellt einen Build für den Übersetzungs-Commit. Der Schritt läuft erneut, findet nichts für einen Push und endet ohne Commit. Die Schleife endet somit nach einem zusätzlichen Build. Dieser Build gibt dem neuesten Commit des Pull Requests einen Status. Mit [skip ci] würde für den neuesten Commit kein Buildkite-Build ausgeführt, und eine erforderliche Buildkite-Statusprüfung würde den Merge blockieren.
Die Zugangsdaten des Agents für den checkout müssen Pushes auf Pull-Request-Branches erlauben. Wenn sich der Branch während der Übersetzung geändert hat, lehnt Git den Push ab und der Schritt schlägt fehl; der Build für den neueren Commit übersetzt die Änderung. Zwei schnell aufeinanderfolgende Pushes starten also zwei Übersetzungen, die beide abgerechnet werden. Aktiviere in den Pipeline-Einstellungen Zwischenzeitliche Builds abbrechen, damit ein neuerer Push den älteren Build abbricht. Eine Übersetzung, die der ältere Build bereits übermittelt hat, wird nicht abgebrochen.
Pull Requests mit veralteten Übersetzungen fehlschlagen lassen #
lingo check vergleicht jede konfigurierte Quelle mit .lingo/lock.json und verlangt, dass alle Zieldateien vorhanden sind. Der Befehl endet mit Exit-Status 1, wenn sich eine Quelle seit ihrer letzten Übersetzung geändert hat, eine Quelle keinen Lockfile-Eintrag hat, eine Zieldatei fehlt oder keine Quelldatei den files-Mustern entspricht. Er benötigt weder API-Schlüssel noch Secret und schreibt nichts. Abgesehen von der CLI-Telemetrie, die DO_NOT_TRACK=1 deaktiviert, führt er keine Netzwerkaufrufe aus. Das npx-Beispiel lädt jedoch vor der Prüfung die CLI von npm herunter. Der Befehl ersetzt die --frozen-Freigabebedingung der vorherigen CLI.
Der Befehl kontrolliert Dateien, nicht Schlüssel: Eine von Hand bearbeitete Zieldatei besteht die Prüfung. Ein fehlender Schlüssel in einer vorhandenen Zieldatei wird nicht gemeldet, außer in React-.jsonc-Katalogen. Ohne .lingo/lock.json erkennt der Befehl keine Quelländerungen. Eine geänderte oder noch nie per Push übertragene Quelle lässt ihn daher nicht fehlschlagen; darauf weist er über stderr hin. Erstelle einen Commit mit dem Lockfile, das lingo push schreibt.
Füge diesen Schritt zu .buildkite/pipeline.yml hinzu, wenn die folgende Tabelle diese Freigabebedingung für deine Einrichtung empfiehlt. Er ist für eine Einrichtung ohne die beiden oben genannten Übersetzungsschritte gedacht. Jedes Beispiel hier enthält daher eine vollständige steps:-Liste für eine Einrichtung. Füge den Schritt in deine vorhandene steps:-Liste ein, statt einen zweiten steps:-Schlüssel hinzuzufügen:
steps:
- label: "Check translations"
if: build.pull_request.id != null
command:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkDie Freigabebedingung eignet sich für eine Einrichtung, in der Übersetzungen zusammen mit der Quelländerung in einem Commit gespeichert werden:
| Wo die Übersetzung ausgeführt wird | Freigabebedingung für jeden Pull Request |
|---|---|
Entwicklerinnen und Entwickler führen lingo push --wait aus und speichern das Ergebnis in einem Commit, bevor sie den Pull Request öffnen | Ja. Sie lässt einen Pull Request fehlschlagen, dessen Quelle ohne Übersetzung geändert wurde. |
| Der Übersetzungsschritt überträgt die Ergebnisse nach dem Merge per Push auf den Standard-Branch | Nein. Bei Feature-Pull-Requests werden die Quellen bewusst vor der Übersetzung geändert. |
| Der Pull-Request-Schritt erstellt einen Commit auf dem Pull-Request-Branch | Nein. Im Build, der die Übersetzung ausführt, sieht die Prüfung den Commit vor der Übersetzung und schlägt fehl. Der erneute Durchlauf des Schritts auf dem Übersetzungs-Commit findet nichts für einen Push und zeigt damit, dass sich seit .lingo/lock.json keine Quelle geändert hat. |
Quell-Hashes sind bytegenau. Sorge dafür, dass der checkout, in dem lingo push ausgeführt wurde, und der CI-checkout dieselben Zeilenenden verwenden, beispielsweise mit * text=auto eol=lf in .gitattributes.
Den Schritt anpassen #
Führe die CLI in einem Monorepo aus dem Paket aus, das .lingo/config.json enthält, beispielsweise mit cd apps/web am Anfang des Befehls. Merke die Zieldateien und das Lockfile dieses Pakets für den Commit vor. Unabhängige Pakete haben separate Lockfiles und können unterschiedliche Lokalisierungs-Engines verwenden.
Wenn die Lokalisierungs-Engine Arbeit zur menschlichen Prüfung weiterleitet, endet lingo push --wait mit Exit-Status 0, nachdem nur die fertigen Dateien geschrieben wurden. Speichere dieses Teilergebnis nicht als vollständiges Ergebnis in einem Commit. Ergänze das Verfahren zur Erhaltung des CI-Durchlaufstatus und rufe die restlichen Dateien nach Abschluss der Prüfung mit Pull auf demselben Agent ab.
Fehler beheben und den Schritt außer Betrieb nehmen #
Leite aus dem Fehler den nächsten Schritt ab: Repariere die Paketinstallation, stelle das Secret bereit, schließe die Prüfung ab, behebe einen Pull-Konflikt oder wiederhole die fehlgeschlagene Verarbeitung eines Ziels, nachdem du die Ursache behoben hast. Lass Exit-Status ungleich null sichtbar; || true verbirgt die Ursache.
Entferne den Schritt oder seinen Auslöser, um neue Builds zu stoppen. Sieh dir beim Abbrechen eines Builds bereits übermittelte Übersetzungen separat an. Entferne das LINGO_API_KEY-Secret und den Schreibzugriff des Agents, wenn du diese Einrichtung außer Betrieb nimmst.