--- title: "Die GitHub Action nutzen" description: "Führe verbatra in GitHub Actions mit der Composite Action aus: übersetze bei einem Push oder sichere einen Pull Request ab, mit Annotationen und Job-Bericht." type: "how-to" --- # Die GitHub Action nutzen Führe verbatra in GitHub Actions mit der Composite Action aus: übersetze bei einem Push oder sichere einen Pull Request ab, mit Annotationen und Job-Bericht. Nutze die Action, wenn ein GitHub-Actions-Job verbatra ausführen und dir zeigen soll, was passiert ist. Sie führt `translate`, `check` oder `diff` mit `--json` aus; für jeden anderen Befehl oder jedes andere Flag, etwa `--prune`, führst du [die CLI direkt](https://verbatra.kreitz-webdev.de/de/docs/ci-and-exit-codes.md) aus. Bevor du anfängst, brauchst du: - Eine verbatra-Konfiguration direkt in dem Verzeichnis, in dem die Action läuft (siehe [Konfigurationssuche](#konfigurationssuche)). - Eine exakte `@verbatra/cli`-Version zum Pinnen, `0.9.3` oder neuer. - Nur für `translate`: den API-Schlüssel deines Providers als Repository-Secret. - Actions Runner v2.327.1 oder neuer und `verbatra/action` `v1.3.0` oder neuer, was diese Seite beschreibt und `qa`, `require-reviewed`, `sensitive`, `locales` und `needs-human` brauchen. ## Die Action in einen Workflow einbauen [#die-action-in-einen-workflow-einbauen] Die Action liegt in [verbatra/action](https://github.com/verbatra/action) und im [GitHub Marketplace](https://github.com/marketplace/actions/verbatra); ein npm-Paket gibt es nicht. Pinne sie wie unten auf einen Commit-SHA oder nutze den mitwandernden Tag `verbatra/action@v1`. Der alte Pfad `mariokreitz/verbatra/packages/github-action` wird nicht mehr aufgelöst. ```yaml title=".github/workflows/translate.yml" name: translate on: push: branches: [main] permissions: contents: read jobs: verbatra: runs-on: ubuntu-latest steps: - uses: actions/checkout@ - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 # an exact @verbatra/cli release, 0.9.3 or newer env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` Die Action installiert `@verbatra/cli` und `@verbatra/sdk` in genau dieser Version in ein temporäres Verzeichnis und lässt deine eigenen Abhängigkeiten unberührt, daher braucht der Job keinen Installationsschritt. ### Den Provider-Schlüssel übergeben [#den-provider-schlüssel-übergeben] Reiche den Schlüssel aus deinen Repository-Secrets unter der Variable weiter, die dein Provider liest; [Provider](https://verbatra.kreitz-webdev.de/de/docs/providers.md#keys-kommen-aus-der-umgebung) listet sie auf. Die Action hat keine Schlüssel-Eingabe, ein Schlüssel reist also nie als Eingabe oder CLI-Argument. ## Einen Pull Request absichern [#einen-pull-request-absichern] Setze `command: check`, damit ein Pull Request mit abweichenden Locale-Dateien fehlschlägt, oder `command: diff`, um zusätzlich die offenen Keys aufzulisten. Beide sind nur lesend und rufen keinen Provider auf, brauchen also keinen Schlüssel und laufen auch bei Pull Requests aus Forks: ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check ``` ## Übersetzungsqualität prüfen [#übersetzungsqualität-prüfen] Ergänze `command: check` um `qa: "true"`, um [`verbatra check --qa`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md#qualitätsprüfung) über jede eingecheckte Übersetzung laufen zu lassen, auch über von Hand getippte Werte. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check qa: "true" ``` - Jeder Befund wird zu einer Annotation mit dem Titel `verbatra qa: `: ein Fehler für einen Wert, den das Integritäts-Gate ablehnen würde, eine Warnung für einen Review-Grund. - Der Schritt schlägt bei jedem Fehler-Befund fehl. Mit `qa-strict: "true"` schlägt er auch bei Warnungen und unvollständigen Pluralen fehl, mit `qa-severity: error` meldet er nur Fehler. Die CLI lehnt beides zusammen ab. ## Freigegebene Übersetzungen verlangen [#freigegebene-übersetzungen-verlangen] Ergänze `command: check` um `require-reviewed: "true"`, um [`verbatra check --require-reviewed`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md#freigegebene-übersetzungen-verlangen) auszuführen. Der Schritt schlägt fehl, solange eine maschinell geschriebene Übersetzung in der committeten `verbatra.provenance.json` nicht freigegeben ist; dort speichert [Studio](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md) die Review-Entscheidungen. Es bleibt nur lesend und ohne Schlüssel und lässt sich mit `qa` kombinieren. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check require-reviewed: "true" ``` - Jede Locale mit nicht freigegebenen Keys bekommt eine [`REVIEW_REQUIRED`](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md#review_required)-Fehler-Annotation, die sie nennt, und die Job-Zusammenfassung ergänzt eine Spalte `unreviewed`. - Ist `verbatra.provenance.json` beschädigt oder stammt sie von einem neueren verbatra, schlägt das Gate mit einer einzigen `REVIEW_STATE_UNREADABLE`-Annotation fehl. ## Locales auswählen und Quellen prüfen [#locales-auswählen-und-quellen-prüfen] Setze `locales` auf eine kommagetrennte Liste wie `de,fr`, um jeden Befehl auf diese Ziel-Locales zu beschränken. ```yaml - uses: verbatra/action@ # a commit on the v1 line with: version: 0.12.0 command: check locales: "de,fr" ``` ### Sensible Inhalte [#sensible-inhalte] Ergänze `command: check` um `sensitive: "true"`, um `verbatra check --sensitive` auszuführen. Der Schritt schlägt fehl, wenn die Quelldatei oder das Glossar Inhalte enthält, die ein `sensitiveData`-Detektor oder -Muster trifft, etwa E-Mails, Schlüssel oder Kartennummern, und annotiert jeden betroffenen Quell-Key, ohne den Treffer auszugeben. Eine ältere `version` oder ein `0.12.0-next.*`-Prerelease lässt den Schritt fehlschlagen, bevor irgendetwas installiert wird. ## Rein menschlicher Modus [#rein-menschlicher-modus] Mit `provider: { id: "none" }` (siehe [Rein menschlicher Workflow](https://verbatra.kreitz-webdev.de/de/docs/human-only-workflow.md)) endet `translate` mit `3`, wenn es Keys für eine Person übrig lässt. Die Action behandelt das als Arbeit zur Übergabe, nicht als Fehlschlag: Der Schritt besteht, jede betroffene Locale bekommt eine `NEEDS_HUMAN`-Warnung, die Job-Zusammenfassung listet die Keys, und der Output `needs-human` ist `"true"`. Verzweige darauf: ```yaml - uses: verbatra/action@ # a commit on the v1 line id: verbatra with: version: 0.12.0 - if: steps.verbatra.outputs.needs-human == 'true' run: echo "Some keys need a human translation; see the job summary." ``` Nur `translate` wird so behandelt. `check` und `diff` enden nie mit `3`, ein Fehlschlag von ihnen lässt den Schritt also weiterhin fehlschlagen. ## Konfigurationssuche [#konfigurationssuche] Ist `config-path` leer, verlangt die Action eine erkannte Konfigurationsdatei direkt in `working-directory` (standardmäßig das Repository-Root). Sie sucht nie in einem übergeordneten Verzeichnis, also richte `working-directory` in einem Monorepo auf die App und lege ihre Konfiguration dort ab: ```yaml with: version: 0.12.0 working-directory: apps/docs ``` Wird keine Konfiguration gefunden, schlägt der Schritt vor der Installation der CLI fehl und nennt das geprüfte Verzeichnis. Um eine Konfiguration von woanders zu laden, setze `config-path`: Ein relativer Pfad wird gegen `working-directory` aufgelöst. ## Übersetzungen behalten [#übersetzungen-behalten] `translate` schreibt die aktualisierten Locale-Dateien in den Checkout des Runners; die Action committet nie. Füge einen eigenen Schritt hinzu, der committet und pusht oder einen Pull Request öffnet, und gib nur diesem Job `contents: write` oder `pull-requests: write`. ## Eingaben [#eingaben] | Eingabe | Standard | Wirkung | | --- | --- | --- | | `version` | Pflicht | exaktes `@verbatra/cli`-Release, `0.9.3` oder neuer; ein Dist-Tag, ein Bereich oder ein `^`/`~`-Präfix lässt den Schritt fehlschlagen | | `command` | `translate` | `translate`, `check` oder `diff`; alles andere lässt den Schritt fehlschlagen | | `config-path` | `""` | zu ladende Konfigurationsdatei (`--config`); relativ zu `working-directory` | | `working-directory` | `""` | Verzeichnis, in dem die CLI läuft (`--cwd`); leer ist es das Repository-Root | | `dry-run` | `"false"` | `"true"` zeigt eine Vorschau ohne Provider-Aufruf und ohne Schreiben (`--dry-run`); nur `translate` | | `qa` | `"false"` | `"true"` ergänzt die Qualitätsprüfung (`--qa`); nur `check` | | `qa-severity` | `""` | niedrigste gemeldete Schwere, `error` oder `warning` (`--severity`); verlangt `qa` | | `qa-strict` | `"false"` | `"true"` lässt auch Warnungen fehlschlagen (`--strict`); verlangt `qa` | | `require-reviewed` | `"false"` | `"true"` lässt auch nicht freigegebene maschinelle Übersetzungen fehlschlagen (`--require-reviewed`); nur `check` | | `sensitive` | `"false"` | `"true"` ergänzt die Prüfung auf sensible Inhalte (`--sensitive`); nur `check` | | `locales` | `""` | kommagetrennte Ziel-Locales, auf die der Lauf beschränkt wird (`--locales`) | | `node-version` | `"24"` | Node.js-Version, die die Action einrichtet. CLI 0.13.0+: `22.22.0`+ auf 22, 24+ (Action v1.4.0: nur gerade Hauptversionen); CLI 0.12.x: `^22.18.0 || >=24`; älter: `>=22.14.0` | Die booleschen Eingaben akzeptieren nur `"true"` oder `"false"`. Ein ungültiger boolescher Wert oder eine Eingabe ohne den Befehl oder `qa`, den sie braucht, lässt den Schritt mit Exit `1` vor der CLI-Installation fehlschlagen. Die CLI lehnt ein unbekanntes `qa-severity` und `qa-severity: error` mit `qa-strict` mit Exit `2` danach ab. ## Outputs [#outputs] | Output | Wert | | --- | --- | | `needs-human` | `"true"`, wenn `translate` mit `3` geendet und Keys für eine Person übrig gelassen hat, sonst `"false"` | ## Was ein Lauf dir zeigt [#was-ein-lauf-dir-zeigt] - **Annotationen.** Unter `translate` mit Exit `1` wird jede fehlgeschlagene oder teilweise Locale zu einer Fehler-Annotation mit dem Titel `verbatra: `. Unter `check` oder `diff` bekommt jede abweichende Locale eine mit dem Titel `verbatra check: ` oder `verbatra diff: `. Alle hängen an der Datei ihrer Locale, wenn die Action sie findet. Die `LOCALE_PARTIAL`-Annotation einer teilweisen Locale nennt die zurückgehaltenen Keys, nach Ursache gruppiert. Jeder `check` ergänzt pro Locale eine `PLURAL_CATEGORIES_INCOMPLETE`-Warnung, wenn ihren Pluralen eine CLDR-Kategorie fehlt, die die Sprache nutzt. Mit `sensitive` bekommt jeder markierte Key eine `SENSITIVE_CONTENT`-Fehler-Annotation und eine Zeile in der Zusammenfassung. Ein Lauf, der als Ganzes fehlschlägt, bekommt eine einzige `verbatra`-Annotation mit dem Fehlercode, der Ursache als `(cause: X)` und einem `Next step:`-Hinweis, sofern die CLI sie liefert. GitHub zeigt höchstens 10 Annotationen pro Schweregrad, daher sortiert die Action sie nach Drift, Review, Qualitätsfehlern und Warnungen und ergänzt einen Hinweis, der den Rest zählt. - **Job-Zusammenfassung.** Eine Zeile pro Locale mit den Zahlen des ausgeführten Befehls, eine Gesamtzeile und die teilweisen und fehlgeschlagenen Locales. Mit `qa` kommt eine Befundtabelle mit bis zu 1000 Befunden hinzu; unvollständige Plurale bekommen einen eigenen Abschnitt. - **Exit-Status.** Die Action gibt zuerst die Annotationen und die Zusammenfassung aus und endet dann mit dem [Exit-Code](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes) der CLI, außer dass ein `translate`-Exit `3` besteht und ein Fehler vor dem Start der CLI (kein Arbeitsverzeichnis, keine Config, eine gescheiterte Installation) mit `1` endet; eine abgelehnte Eingabe bekommt ein einziges `::error::`, keine Zusammenfassung. ## Sicherheit [#sicherheit] Pinne beide Referenzen: `uses:` auf einen Commit-SHA und `version` auf ein exaktes Release ([aktuelles auf npm](https://www.npmjs.com/package/@verbatra/cli)); die Action lehnt alles ab, was sich zu `latest` auflösen könnte. Eingaben erreichen die CLI als Argument-Array in Anführungszeichen und werden nie in Shell-Text eingefügt. ## Siehe auch [#siehe-auch] - [verbatra in CI ausführen](https://verbatra.kreitz-webdev.de/de/docs/ci-and-exit-codes.md): dieselben Gates in jedem CI-System. - [verbatra/action](https://github.com/verbatra/action): die Release Notes und die aus `action.yml` erzeugte Eingaben-Referenz.