CI-Anleitung für GitHub Actions

Führe Übersetzungen in einem vertrauenswürdigen GitHub Actions-Job aus, sieh dir die Artefakte an und ergänze die Bereitstellung per Pull Request, sobald die Ergebnisse bereit sind.

Führe die Lingo.dev CLI in GitHub Actions aus, wenn Übersetzungen die Trigger und Checks deiner bestehenden Pipeline nutzen sollen. Der Runner liest deine Repository-Konfiguration, übermittelt Änderungen am Quelltext und lädt die übersetzten Dateien herunter. Du entscheidest, ob diese Dateien als Artefakte erhalten bleiben oder in einen Pull Request einfließen.

Diese Anleitung beginnt mit einer manuellen Auslösung und rein lesendem Zugriff auf das Repository. Nachdem du dir eine geänderte Nachricht angesehen hast, kannst du die Schreibberechtigungen für einen Übersetzungs-Pull-Request hinzufügen. Die native GitHub App bietet alternativ eine verwaltete Repository-Verarbeitung, für die du diese Runner-Anleitung nicht benötigst.

Repository vorbereiten #

Führe den CLI-Schnellstart lokal mit einer Quelldatei und einer Zielsprache durch. Erstelle einen Commit mit .lingo/config.json, der kontrollierten Zieldatei und .lingo/lock.json. Die Konfiguration legt die Lokalisierungs-Engine, die Quell- und Zielsprachen sowie die Dateimuster fest. Das Lockfile hält den Ausgangsstand für spätere Änderungen am Quelltext fest.

Konfiguriere für das folgende Beispiel locales/en.json als Quellsprache und Spanisch als Zielsprache, sodass locales/es.json erzeugt wird. Erstelle die erste fehlende Zieldatei mit lingo push --backfill-missing --wait; verwende für spätere Änderungen am Quelltext lingo push --wait. Backfill wählt fehlende Zieldateien aus und ergänzt daher keine fehlenden Schlüssel in einer bereits vorhandenen Datei.

Füge LINGO_API_KEY zu den Actions-Secrets des Repositorys oder der Umgebung hinzu. Es gewährt Zugriff auf Lingo.dev, unabhängig von den GitHub-Repository-Berechtigungen. Führe den Job mit Zugangsdaten nur mit vertrauenswürdigem Code aus. Verwende insbesondere nicht pull_request_target, um den Head eines nicht vertrauenswürdigen Pull Requests mit dem Secret auszuchecken und auszuführen.

Das Beispiel verwendet eine festgelegte CLI-Version. Wenn du diese über die Abhängigkeiten und das Lockfile deines Projekts verwalten möchtest, folge der Anleitung zur CI-Einrichtung.

Ein Übersetzungsartefakt erhalten #

Speichere dies als .github/workflows/translate.yml. Das Beispiel verwendet Node.js 22.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          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
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

Kontrolliere die Organisations- und Engine-IDs in der per Commit gespeicherten .lingo/config.json. Ändere eine Stelle im englischen Quelltext, erstelle einen Commit und löse den Workflow von diesem vertrauenswürdigen Branch aus. Sieh dir das Ausführungsergebnis und den Diff im Job-Protokoll an. Lade anschließend das Artefakt herunter und suche den spanischen Eintrag, der deiner Änderung entspricht. Lade ihn über die Anwendung und kontrolliere seine Bedeutung und Variablen.

Der Upload umfasst auch versteckte Dateien, damit .lingo/lock.json erhalten bleibt. Beschränke die Pfadliste auf die vorgesehene Zieldatei und das Lockfile; nimm keine Zugangsdaten oder anderen privaten versteckten Dateien auf.

Die Shell-Checks stellen sicher, dass die Dateien vorhanden sind und die JSON-Syntax gültig ist. Auch eine alte Zieldatei kann beide Checks bestehen. Deshalb ist es wichtig, den geänderten Eintrag anzusehen. Wenn die Lokalisierungs-Engine eine menschliche Prüfung erfordert, kann die Ausführung auch nach Abschluss des Befehls noch auf eine Person warten. Ergänze vor dem Einsatz dieser Richtlinie auf einem kurzlebigen Runner das Verfahren zur Sicherung des CI-Ausführungszustands. Exportiere nach der Übermittlung den Verweis auf die konkrete Ausführung und das ursprüngliche absolute Projektstammverzeichnis. Lade .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, die Zieldatei und das Lockfile als Artefakte mit beschränktem Zugriff hoch. Verwende if: always() für die Export- und Upload-Schritte, damit ein später fehlgeschlagener Check keinen wiederherstellbaren Zustand verwirft. Fehlt der Verweis, musst du die Übermittlung untersuchen, statt einen Verweis zu erfinden.

Stelle nach der Prüfung genau diese Revision und diesen Dateizustand im aufgezeichneten absoluten Stammverzeichnis wieder her. Stelle auch den Verweis wieder her, authentifiziere dich separat und verwende Pull mit Konfliktprüfung. Wenn ein anderer Runner den Pfad nicht wiederherstellen kann, führe Übermittlung und Abruf stattdessen auf einem dauerhaften, autorisierten Runner aus. Betrachte die alte Zieldatei aus dem ersten Artefakt nicht als fertige Übersetzung.

push --wait wartet und lädt verfügbare Ergebnisse abgeschlossener Übersetzungen herunter. Ohne --wait kehrt Push normalerweise nach der Übermittlung zurück. Separate Jobs für Übermittlung und Abruf benötigen denselben Export und dieselbe Wiederherstellung des Ausführungszustands; das Lockfile allein zu kopieren reicht nicht aus. Bewahre die heruntergeladenen Zieldateien und das Lockfile aus demselben abgeschlossenen Vorgang zusammen auf und archiviere niemals den gesamten Inhalt von ~/.lingo.

Einen Pull Request bereitstellen #

Gewähre dem Job nach erfolgreicher Kontrolle der Artefakte contents: write und pull-requests: write. Die Repository-Richtlinie muss Actions außerdem erlauben, Pull Requests zu erstellen. GITHUB_TOKEN autorisiert diese GitHub-Vorgänge; verwende für die Übersetzung weiterhin LINGO_API_KEY.

Konfiguriere eine Git-Identität gemäß der Bot-Richtlinie deines Teams. Füge dann nach der Validierung der Ausgabe einen Schritt hinzu, der nur die erwartete Zieldatei und das Lockfile für den Commit vormerkt:

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

Von GitHub gehostete Runner enthalten die GitHub CLI. Stelle diesem Schritt GH_TOKEN aus secrets.GITHUB_TOKEN bereit. Die Abfolge setzt eine manuelle Auslösung von einem vertrauenswürdigen Branch und einen neuen Branch-Namen voraus. Bei einer erneuten Ausführung mit einem bestehenden Branch musst du ausdrücklich entscheiden, ob du ihn wiederverwenden oder ersetzen möchtest. Dieser Workflow schreibt nicht in einen Fork zurück.

Der Pull Request zielt auf den Branch, von dem du den Job ausgelöst hast. Wenn GitHub dessen Workflows als auf Genehmigung wartend kennzeichnet, muss eine Person mit Schreibzugriff auf das Repository Ausführung der Workflows genehmigen auswählen; siehe GitHubs Verhalten bei GITHUB_TOKEN. Führe vor dem Merge eine Prüfung des übersetzten Diffs, der Checks und der Anwendungsausgabe durch.

Direkte Commits in den auslösenden Branch sind mit einer geeigneten Branch-Richtlinie möglich. Dabei entfällt jedoch dieser separate Schritt zur Inhaltsprüfung, und du musst Schleifen verhindern.

Ausführungen planen und mit Monorepos arbeiten #

Sobald die erste Ausführung brauchbare Ergebnisse liefert, ergänze vertrauenswürdige Branches für Push-Trigger und Filter für Quellpfade. Generierte Übersetzungs-Commits dürfen nicht immer wieder einen neuen Übersetzungsjob auslösen. Kombiniere geeignete Branch- oder Pfadfilter mit einem Ausstieg im Bereitstellungsschritt, wenn keine Änderungen vorliegen.

Lege in einem Monorepo das Paket, das .lingo/config.json enthält, als Arbeitsverzeichnis für den Übersetzungsschritt fest. Passe die Artefaktpfade und die für den Commit vorgemerkten Pfade so an, dass sie dieses Paket enthalten. Eine Matrix kann unabhängige Pakete verarbeiten. Zwei Einträge sollten jedoch nicht gleichzeitig dieselbe Konfiguration und dasselbe Lockfile aktualisieren. Alle Einträge einer Ausführung haben dieselbe Ausführungs-ID. Gib deshalb jedem Eintrag einen eigenen Artefaktnamen und einen eigenen Übersetzungs-Branch, etwa indem du den Paketnamen zu translated-catalog und lingo/translations-${GITHUB_RUN_ID} hinzufügst.

Eine unvollständige Ausführung wiederherstellen #

Gehe vom gemeldeten Zustand aus: Bei fehlgeschlagenen Zielen muss der Fehler behoben werden, bei Zielen mit ausstehender Prüfung sind Entscheidungen nötig, und bei lokalen Pull-Konflikten musst du zwischen der lokalen Änderung und dem heruntergeladenen Ergebnis wählen. Halte erfolgreiche Ergebnisse zur Kontrolle verfügbar und lasse unvollständige Sprachen weiterhin offen. Ein Teilergebnis darf nicht als vollständige Veröffentlichung einer Sprache gelten.

Sorge dafür, dass Beendigungen mit einem Exit-Code ungleich null sichtbar bleiben. || true, erzwungene Pulls über lokale Änderungen hinweg oder das Erzwingen aller Ziele können die Ursache verbergen und bereits akzeptierte Arbeit ersetzen. Die Anleitung für CI-Workflows erklärt, wie du die Revision und den Ausgangsstand bei der Wiederherstellung bewahrst.

Deaktiviere den Workflow oder seinen Trigger, um neue Runner-Jobs zu verhindern. Wenn ein Job die Übersetzung bereits übermittelt hat, sieh dir beim Abbrechen von Actions die zugehörige Serverausführung separat an. Entferne nicht mehr benötigte Secrets und den Schreibzugriff auf das Repository, wenn du den Workflow außer Betrieb nimmst.