GitLab-CI-Anleitung

Übersetze Dateien in einer vertrauenswürdigen GitLab-Pipeline, stelle sie über einen Merge Request bereit und lasse Merge Requests mit veralteten Übersetzungen fehlschlagen.

Ein GitLab-Runner kann Dateien aus deinem Repository mit der Lingo.dev CLI übersetzen und die Ergebnisse als Job-Artefakte speichern. So durchläuft die Übersetzung denselben checkout, dieselben Kontrollen und denselben Release-Prozess wie der Rest deiner Anwendung. GitLab übernimmt die Ausführung der Pipeline und die Bereitstellung im Repository; Lingo.dev verarbeitet die ausgewählten Quelldateien über eine Lokalisierungs-Engine.

Dies ist eine CI-Anleitung, keine native Verbindung zu einem GitLab-Konto. Beginne mit einer manuell gestarteten Pipeline auf dem Standard-Branch. Sieh dir zunächst das Ergebnis an und ergänze anschließend wiederkehrende Auslöser und die Bereitstellung über Merge Requests.

Quelle und Zugangsdaten einrichten #

Führe den CLI-Schnellstart lokal durch. Erstelle einen Commit mit .lingo/config.json, den akzeptierten Zieldateien und .lingo/lock.json. Die Konfiguration legt Quellsprache, Zielsprachen, Dateimuster und Lokalisierungs-Engine fest. Führe die CLI aus dem Verzeichnis aus, in dem diese Konfiguration liegt.

Erstelle fehlende Zieldateien mit lingo push --backfill-missing --wait. Verwende für spätere Änderungen an der Quelle den regulären Befehl lingo push --wait. Geänderte Anweisungen der Lokalisierungs-Engine allein schreiben akzeptierte Dateien nicht neu; eine gezielte Neugenerierung ist eine separate Aufgabe.

Speichere LINGO_API_KEY in den CI/CD-Variableneinstellungen des Projekts als maskierte Variable. Die CLI liest nur diesen Namen; eine LINGODOTDEV_API_KEY-Variable aus der vorherigen CLI wird ignoriert. Benenne sie deshalb um. Beschränke ihre Verfügbarkeit auf vertrauenswürdige Branches oder Umgebungen, die Übersetzungsaufträge einreichen dürfen. Auf einem ungeschützten Branch oder in einem Merge Request ist eine geschützte Variable möglicherweise nicht verfügbar. Verwende dann einen autorisierten Branch, statt sie nicht vertrauenswürdigem Code zugänglich zu machen.

Der API-Schlüssel autorisiert die Übersetzung. GitLab-Zugangsdaten mit Schreibzugriff auf das Repository brauchst du erst, wenn du die Bereitstellung per Commit ergänzt.

Die Beispiele legen die CLI-Version auf 1.21.0 fest. lingo check überprüft ab CLI 1.20.0 Übersetzungsdateien. Wenn du die Version über die Abhängigkeiten und das Lockfile deines Projekts verwalten möchtest, folge der Anleitung zur CI-Einrichtung.

Eine Pipeline ausführen, die zunächst Artefakte bereitstellt #

Dieses .gitlab-ci.yml-Beispiel setzt voraus, dass locales/en.json als Quelle konfiguriert ist und locales/es.json, eine vorhandene spanische Datei, ihr einziges Ziel ist. Führe bei mehreren Zielen die test -s- und JSON-Prüfungen für jede Zieldatei einmal aus und gib in den übrigen Befehlen, die locales/es.json nennen, alle Zielpfade an. Das Lockfile vermerkt die Quelle als übersetzt, sodass sie bei einem späteren Push übersprungen wird. Eine Zieldatei, die im Artefakt oder Commit fehlt, bleibt veraltet. Das Beispiel verwendet eine manuell gestartete Pipeline auf dem Standard-Branch:

yaml
stages:
  - translate

translate_catalog:
  stage: translate
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  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:
    paths:
      - locales/es.json
      - .lingo/lock.json

--wait sorgt dafür, dass der Job auf den Abschluss des Laufs wartet und die übersetzten Dateien in den checkout schreibt. Ohne diese Option reicht lingo push den Lauf nur ein und beendet sich. Nachfolgende Schritte finden dann keine neuen Dateien, die sie untersuchen oder committen können.

Stelle sicher, dass dein Runner auf die Registry zugreifen kann, und stelle alle Werkzeuge bereit, die spätere Schritte benötigen. Bei einem alternativen Minimal-Image musst du beispielsweise möglicherweise zuerst Git installieren, um einen Diff ansehen oder einen Commit erstellen zu können.

Kontrolliere die Organisations- und Engine-IDs in der per Commit gespeicherten Datei .lingo/config.json. Nimm eine Änderung an der Quelle vor und starte die Pipeline. Vergewissere dich im Protokoll, dass der gemeldete Ausführungsstatus und der geänderte Zieleintrag stimmen. Lade das Artefakt herunter, vergleiche die Übersetzung mit dieser Quellrevision und lade sie in deiner Anwendung. Kontrollen auf vorhandene Dateien und gültiges JSON allein können weder die Aktualität noch die inhaltliche Richtigkeit sicherstellen.

--wait lädt die fertige Ausgabe herunter. Ist eine menschliche Prüfung konfiguriert, kann der Auftrag jedoch noch auf die Bearbeitung durch eine Person warten. Bevor du eine Wartephase für die Prüfung oder einen separaten Abruf-Job verwendest, ergänze das CI-Verfahren zur Sicherung des Ausführungszustands. Exportiere nach der Einreichung den spezifischen Zeiger und den ursprünglichen absoluten Projektstammpfad. Nimm .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, die Zieldatei und das Lockfile in zugriffsbeschränkte Job-Artefakte auf. Setze when: always in der artifacts-Konfiguration und plane eine ausreichend lange Aufbewahrungsdauer für die Prüfung ein. Stelle sicher, dass der Export auch bei einem Fehler in der späteren Validierung ausgeführt wird; der ursprüngliche Fehler muss sichtbar bleiben.

Schließe die Prüfung ab und stelle anschließend die aufgezeichnete Revision und den Dateizustand auf dem Abruf-Runner unter demselben absoluten Stammpfad wieder her. Stelle nur diesen Zeiger wieder her, authentifiziere dich separat und verwende vor dem Abruf lingo pull --dry-run. Kann der Runner den ursprünglichen Pfad nicht wiederherstellen, verwende stattdessen einen persistenten, autorisierten Runner für beide Jobs. Archiviere niemals den gesamten Inhalt von ~/.lingo. Eine erfolgreiche Einreichung oder eine alte Zieldatei allein liefert keine neuen Dateien zur Veröffentlichung.

Übersetzungen per Commit in einem Merge Request bereitstellen #

Dieser Job übersetzt Quelländerungen in einem Merge Request und speichert die Ergebnisse per Commit auf demselben Branch. Er setzt voraus, dass die anfängliche Ergänzung fehlender Dateien bereits per Commit gespeichert und die menschliche Prüfung der Engine deaktiviert ist. So kann die Übersetzung in einem einzigen Job abgeschlossen werden.

Aktiviere in GitLab 18.4 oder neuer Einstellungen → CI/CD → Job-Token-Berechtigungen → Git-Push-Anfragen an das Repository zulassen. Der Job verwendet das integrierte Token von GitLab; die Person, die ihn startet, muss zum Push auf den Quell-Branch berechtigt sein. Siehe GitLabs Anleitung zur Einrichtung von Job-Tokens.

Lasse LINGO_API_KEY maskiert und geschützt. Verwende vertrauenswürdige Quell- und Ziel-Branches im selben Projekt, schütze beide Branches und aktiviere in den CI/CD-Einstellungen des Projekts Merge-Request-Pipelines den Zugriff auf geschützte Variablen und Runner erlauben. Die Person, die die Pipeline startet, benötigt außerdem Push- oder Merge-Zugriff auf den Ziel-Branch. Dies sind GitLabs Anforderungen für geschützte Variablen.

Verwende dieselben Quell- und Zielpfade wie im ersten Beispiel. Füge diesen Job zur translate-Phase hinzu:

yaml
translate_merge_request:
  stage: translate
  image: node:22
  resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
  rules:
    - if: >-
        $CI_PIPELINE_SOURCE == "merge_request_event" &&
        $CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
        $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
  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 "Update translations"
    - git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"

resource_group führt für jeden MR jeweils nur einen Übersetzungsjob gleichzeitig aus. Der Job speichert nur die spanische Zieldatei und das Übersetzungs-Lockfile per Commit. Ändert sich der Branch während der Übersetzung, lehnt Git den Push ab. Starte dann eine Pipeline für den aktualisierten Branch.

CI_REPOSITORY_URL stellt die Job-Token-Zugangsdaten bereit. Pushes mit diesem Token starten keine weitere Pipeline. Ergänze deshalb die Ressourcenkontrollen deiner Anwendung vor dem Commit-Schritt. Führe vor dem Merge eine Prüfung des Übersetzungs-Diffs im MR sowie alle noch ausstehenden Kontrollen durch.

Da dieser Push keine Pipeline startet, gibt es auch für den neuesten Commit des MR keine Pipeline. Wenn im Projekt Pipelines müssen erfolgreich sein vorgeschrieben ist, kann GitLab den Merge blockieren. Wähle dann im MR auf dem Tab Pipelines die Option Pipeline ausführen. Der Job findet nichts zum Pushen und beendet sich ohne Commit. Diese Pipeline gibt dem neuesten Commit einen Status.

Einen Übersetzungs-Merge-Request vom Standard-Branch aus öffnen #

Dieser Job übersetzt jede Änderung, die auf dem Standard-Branch ankommt, und öffnet einen Merge Request mit dem Ergebnis. Die GitLab-Push-Optionen erstellen den Merge Request im selben git push. Ein API-Aufruf oder ein zusätzliches Tool ist daher nicht nötig. Es gelten dieselben Voraussetzungen wie beim obigen Job: Die anfängliche Übersetzung des Bestands ist committet und die menschliche Prüfung ist deaktiviert.

Erstelle ein Projektzugriffstoken mit der Rolle Entwickler und dem Geltungsbereich write_repository. Speichere es als maskierte, geschützte CI/CD-Variable namens GITLAB_PUSH_TOKEN. Auf GitLab.com erfordern Projektzugriffstoken einen kostenpflichtigen Tarif. CI_JOB_TOKEN wird hier nicht verwendet, weil GitLab für einen damit ausgeführten Push keine Pipeline startet. Die Push-URL verwendet CI_SERVER_FQDN. So bleibt bei einer selbstverwalteten Instanz auch ein vom Standard abweichender Port erhalten. CI_SERVER_FQDN erfordert GitLab 16.10 oder neuer. Verwende auf einer älteren selbstverwalteten Instanz stattdessen ${CI_SERVER_HOST}:${CI_SERVER_PORT}.

Füge diesen Job zur Phase translate hinzu:

yaml
translate_default_branch:
  stage: translate
  image: node:22
  resource_group: lingo-translations
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
    - if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
    # 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 --force
      -o ci.skip
      -o merge_request.create
      -o merge_request.target="$CI_DEFAULT_BRANCH"
      -o merge_request.title="Update translations"
      "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
      "HEAD:refs/heads/lingo/translations"

lingo push --wait beendet sich mit einem Status ungleich null, wenn ein Ziel fehlschlägt. Dadurch stoppt der Job vor dem Commit. Wenn sich nichts geändert hat, gibt er "Nichts zu pushen" aus. Der Diff der vorgemerkten Änderungen ist dann leer und der Job beendet sich ohne Commit.

Die ersten beiden Zeilen stoppen den Job, wenn der Standard-Branch inzwischen über den Commit hinaus fortgeschritten ist, auf dem der Job läuft. resource_group führt jeweils nur einen Job aus. Im standardmäßigen unordered-Verarbeitungsmodus von GitLab werden wartende Jobs jedoch ohne feste Reihenfolge gestartet. Ohne diese Prüfung könnte ein älterer Job zuletzt laufen und neuere Übersetzungen per Force-Push mit älteren überschreiben. Der Job für den neuesten Commit übersetzt diesen; für einen bereits veralteten Commit wird nichts eingereicht.

Der Job läuft nicht in einer Schleife. Er wird nur bei Pushes auf den Standard-Branch ausgeführt und schreibt ausschließlich nach lingo/translations. Laut GitLab-Dokumentation wirkt sich -o ci.skip nur auf Branch-Pipelines aus, nicht auf Merge-Request-Pipelines. Eine Merge-Request-Pipeline läuft, wenn ein Merge Request erstellt wird oder sein Quell-Branch einen neuen Commit erhält. Die unten gezeigte Freigabebedingung sollte daher beim Übersetzungs-Merge-Request ausgeführt werden. Vergewissere dich beim ersten Lauf, dass das tatsächlich geschieht. Der Merge dieses Merge Requests startet den Job noch einmal; dabei findet er nichts zum Pushen.

Jeder Lauf erstellt lingo/translations aus dem Commit des Standard-Branch neu, auf dem er ausgeführt wurde, und überträgt den Branch per Force-Push. So zeigt ein offener Merge Request den neuesten Übersetzungs-Diff. Manuelle Änderungen auf diesem Branch werden beim nächsten Lauf ersetzt; nimm sie deshalb erst nach dem Merge vor. Bis der Merge Request gemergt ist, behält der Standard-Branch das vorherige .lingo/lock.json. Der nächste Lauf reicht daher dieselben Quelländerungen erneut ein. Wenn spätere Commits sämtliche Quelländerungen rückgängig machen, die der Merge Request übersetzt hat, findet der nächste Lauf nichts zum Pushen. Der Merge Request bleibt dann mit veralteten Übersetzungen offen. Schließe ihn, statt ihn zu mergen.

Merge 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 beendet sich mit Status 1, wenn eine Quelle seit ihrer letzten Übersetzung geändert wurde, 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 CI/CD-Variable und schreibt nichts. Deshalb läuft er auch bei Merge Requests aus Forks. Abgesehen von der CLI-Telemetrie, die DO_NOT_TRACK=1 deaktiviert, führt er keine Netzwerkaufrufe aus. Die npx-Beispiele laden die CLI allerdings weiterhin von npm herunter, bevor die Prüfung läuft. Der Befehl ersetzt die --frozen-Freigabebedingung der vorherigen CLI.

Die Prüfung erfolgt auf Dateiebene, nicht auf Schlüsselebene: Eine manuell bearbeitete Zieldatei besteht die Prüfung. Ein Schlüssel, der in einer vorhandenen Zieldatei fehlt, wird 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 lässt die Prüfung daher nicht fehlschlagen. Darauf weist der Befehl auf stderr hin. Committe das Lockfile, das lingo push schreibt.

Füge check zur Liste stages hinzu und ergänze dann den passenden Job für deine Konfiguration. Wenn Entwicklerinnen und Entwickler lingo push --wait ausführen und das Ergebnis zusammen mit ihrer Quelländerung committen, führe die Prüfung bei jedem Merge Request aus:

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Führe beim Einsatz des Jobs für den Standard-Branch die Prüfung nur bei dessen Übersetzungs-Merge-Request aus, da Feature-Merge-Requests die Quellen vor der Übersetzung ändern:

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

Die Freigabebedingung eignet sich für eine Konfiguration, bei der Übersetzungen zusammen mit der Quelländerung committet werden:

Wo die Übersetzung läuftFreigabebedingung bei jedem Merge Request
Entwicklerinnen und Entwickler führen lingo push --wait aus und committen das Ergebnis, bevor sie den Merge Request öffnenJa. Sie lässt einen Merge Request fehlschlagen, dessen Quelle ohne Übersetzung geändert wurde.
Der Merge-Request-Job committet auf den Quell-BranchNein. Die Prüfung würde den Commit vor der Übersetzung erfassen, und der Push des Jobs startet keine neue Pipeline.
Der Job für den Standard-Branch öffnet einen Übersetzungs-Merge-RequestNur bei lingo/translations, mit dem zweiten Job oben. Bei Feature-Merge-Requests werden die Quellen bewusst vor der Übersetzung geändert.

Quell-Hashes sind bytegenau. Stelle sicher, dass der checkout, in dem lingo push ausgeführt wurde, und der CI-checkout dieselben Zeilenenden verwenden, zum Beispiel mit * text=auto eol=lf in .gitattributes.

Wiederkehrende Abläufe planbar machen #

Beschränke automatische Jobs durch Filter auf die vorgesehenen vertrauenswürdigen Branches und Quellpfade. Wenn du Merge-Request-Auslöser verwendest, schränke auch das Quellprojekt und den Ziel-Branch ein. Verhindere mit einer geeigneten Branch-Regel oder einer Richtlinie zum Überspringen der CI sowie einem Abbruch bei leerem Diff, dass generierte Commits wiederholt Übersetzungsaufträge einreichen.

Wechsle bei einem Monorepo in das Paket mit der vorgesehenen Konfiguration und bewahre dessen Ausgabe und Zustand relativ zum Paketverzeichnis auf. Unabhängige Pakete können unterschiedliche Lokalisierungs-Engines und Sprachen verwenden; halte ihre Lockfiles getrennt. Derselbe Runner-Ansatz funktioniert auch mit selbstverwaltetem GitLab, wenn Netzwerkzugriff, Runner-Werkzeuge, Variablen und Repository-Richtlinien dies unterstützen.

Eine reguläre inkrementelle Übersetzung kann einen manuell bearbeiteten Zielschlüssel beibehalten, solange dessen Quelle unverändert bleibt. Ändert sich die Quelle, kann dieser Schlüssel neu generiert werden. Das Ergänzen fehlender Dateien und eine erzwungene Neugenerierung haben unterschiedliche Geltungsbereiche. Ohne Dateimuster erfasst --force alle konfigurierten Quell- und Zielsprachen und kann akzeptierte Übersetzungen ersetzen. Verwende explizite Muster und sieh dir eine Schätzung an, bevor du die Verarbeitung erzwingst. Ziehe Push zu Rate, wenn du den Befehl zur Einreichung änderst.

Die Pipeline wiederherstellen und außer Betrieb nehmen #

Leite aus dem Fehler den nächsten Schritt ab: Repariere die Paketinstallation, stelle eine autorisierte Variable bereit, schließe die Prüfung ab, behebe einen Merge-Konflikt oder wiederhole die fehlgeschlagene Verarbeitung einer Zieldatei, nachdem du die Ursache behoben hast. Bewahre erfolgreiche Artefakte auf, aber kennzeichne einen nur teilweise abgeschlossenen Release weiterhin deutlich als unvollständig.

Deaktiviere den Auslöser, um neue Pipelines zu verhindern. Sieh dir bereits eingereichte Übersetzungsaufträge separat an, wenn du den zugehörigen Runner abbrichst. Entferne nicht mehr benötigte API- und Repository-Zugangsdaten, wenn du diese CI-Einrichtung außer Betrieb nimmst.