GitHub Action

verbatra liefert eine Composite GitHub Action mit, die die verbatra-CLI mit --json in CI ausführt, Fehlschläge in Annotationen auf dem Lauf verwandelt, eine Tabelle in die Job-Zusammenfassung schreibt und mit dem Exit-Code der CLI endet. Standardmäßig führt sie translate aus; setze die Eingabe command, um stattdessen ein schreibgeschütztes check- oder diff-Gate auszuführen. Diese Seite erklärt die Verdrahtung und was die Action dir zeigt.

Wann sie statt eines rohen CLI-Schritts sinnvoll ist

Die Action ist ein translate-, check- oder diff-Schritt mit fertig eingebautem Reporting: Fehler-Annotationen pro Locale, eine Zusammenfassungstabelle auf der Lauf-Seite und Exit-Code-Weitergabe, die nie einen Fehlschlag verschluckt. Nimm sie, wenn dein Job "verbatra ausführen und mir zeigen, was passiert ist" lautet, einschließlich eines schreibgeschützten check- oder diff-Gates auf einem Pull Request.

Führe stattdessen die CLI direkt aus, wenn du irgendetwas anderes willst: eigene Flags wie --prune, deine eigene Verarbeitung der JSON-Ausgabe oder einen Befehl, den die Action nicht unterstützt. Die Eingabe command akzeptiert nur translate (der Standard), check oder diff; die Action startet nie init oder watch.

Verfügbarkeit

Die Action lebt in einem eigenen Repository, verbatra/action, getrennt vom verbatra-Monorepo, und ist im GitHub Actions Marketplace gelistet. Es gibt kein npm-Paket; die Action wird nur über uses: eingebunden.

Referenziere sie per Repository, gepinnt auf einen Commit-SHA:

uses: verbatra/action@<commit-sha>

verbatra/action@v1 ist die bequeme Variante und die empfohlene Standardwahl: der v1-Tag ist die aktiv gepflegte, durchgehend aktualisierte Linie und wandert mit jedem Release mit, Fixes und Features erreichen dich also ohne Änderung am Workflow. Ein SHA-Pin ist ohnehin die sicherheitsbewusste Wahl und wird in den Beispielen auf dieser Seite verwendet.

Früher wurde sie aus dem verbatra-Monorepo ausgeliefert und per Pfad referenziert. Diese ältere Form löst nicht mehr auf, richte bestehende Workflows also auf das Repository oben aus.

Verwendung

name: translate
on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verbatra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: verbatra/action@<commit-sha> # pinnt die aktiv gepflegte v1-Linie
        with:
          version: 0.9.3 # pin @verbatra/cli to an exact version, 0.9.3 or newer
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Die Action holt und startet @verbatra/cli in exakt der Version, die du pinnst; der Workflow braucht also keinen eigenen Installationsschritt für verbatra. Der Pin oben ist nur ein Beispiel: sieh im @verbatra/cli-Paket auf npm nach dem aktuellen Release und hebe den Pin bewusst an, statt einem beweglichen Tag zu folgen.

Secret-Verdrahtung

Die Action führt die CLI aus, und die CLI liest den API-Key des Providers nur aus der Umgebung. Das gilt für den Standardbefehl translate: Übergib den Key aus deinen Repository-Secrets unter der Variable, die dein Provider erwartet (siehe Provider): ANTHROPIC_API_KEY wie oben, OPENAI_API_KEY, GEMINI_API_KEY, DEEPL_API_KEY oder GOOGLE_TRANSLATE_API_KEY. Die schreibgeschützten Befehle check und diff rufen keinen Provider auf und brauchen daher gar keinen Key - genau das macht sie als Gate auf einem Fork-Pull-Request nutzbar, wo Secrets nicht verfügbar sind. Es gibt keine Key-Eingabe; ein Key reist nie als Action-Eingabe oder CLI-Argument.

Eingaben

Die Action definiert keine Outputs. Die Ergebnisse sind die Annotationen, die Job-Zusammenfassung und der Exit-Code.

Konfigurationssuche

Wenn config-path leer bleibt, verlangt die Action eine erkannte verbatra-Konfigurationsdatei direkt im aufgelösten working-directory. Wird dort keine gefunden, schlägt der Schritt fehl, bevor die CLI installiert wird, und nennt das genau geprüfte Verzeichnis.

Die Suche ist strikt: sie geht nie in ein übergeordnetes Verzeichnis oder das Repository-Root, selbst wenn dort eine gültige Konfiguration liegt. Nimm ein Monorepo, in dem die zu übersetzende App unter apps/docs liegt:

      with:
        version: 0.9.3
        working-directory: apps/docs

Hier ist apps/docs das Root, in dem eine Konfiguration existieren muss; eine erkannte Konfigurationsdatei direkt in apps/docs ist erforderlich. Eine Konfiguration im äußeren Repository-Root erfüllt die Prüfung nicht, obwohl sie ein Vorfahre von apps/docs ist.

Setze config-path, um auf eine Konfigurationsdatei außerhalb dieser Konvention zu zeigen. Ein relativer config-path wird weiterhin gegen working-directory aufgelöst; ein absoluter config-path wird unverändert verwendet. Sobald eine Konfiguration bestätigt ist, übergibt die Action sie der CLI immer explizit mit --config <aufgelöster-pfad>.

Was ein Lauf dir zeigt

Annotationen. Unter dem Standardbefehl translate wird, wenn die CLI mit 1 endet (einige Locales schlugen fehl oder blieben partial), jedes fehlgeschlagene Locale zu einer Fehler-Annotation mit dem Titel verbatra: <locale>, die dessen strukturierte [CODE] message trägt. Unter check wird ein abweichendes Locale stattdessen als verbatra check: <locale> annotiert; unter diff wird ein Locale mit ausstehenden Änderungen als verbatra diff: <locale> annotiert. Wenn der ganze Lauf fehlschlägt, bevor eine Zusammenfassung entsteht (Exit 2), trägt stattdessen eine einzelne verbatra-Annotation die Fehlerzeile der CLI, unabhängig vom Befehl.

Job-Zusammenfassung. Jeder Lauf hängt eine Markdown-Zusammenfassung an die Job-Seite an, deren Form vom ausgeführten Befehl abhängt. Unter translate ist es eine Tabelle mit einer Zeile pro Locale (Status, übersetzt, unverändert, verwaist, ungültiges ICU, wegen Integrität zurückgehalten, Provider-Fehlschläge, Notices), eine Summenzeile und eine Liste fehlgeschlagener Locales mit ihren Fehlercodes; ein Dry-Run wird als solcher gekennzeichnet. Unter check meldet sie fehlende und veraltete Keys pro Locale als Zahlen. Unter diff meldet sie fehlende und geänderte Keys pro Locale, dazu separat aufgeführte verwaiste Keys, da diese den Schritt nie für sich allein scheitern lassen. Ein Fehlschlag des gesamten Laufs bekommt eine kurze Fehlerzusammenfassung mit Exit-Code und Fehlerdetail, unabhängig vom Befehl.

Exit-Verhalten. Die Action fängt stdout und Exit-Code der CLI ab, ohne früh auszusteigen, gibt erst die Annotationen und die Zusammenfassung aus und endet dann mit dem Code der CLI. Der Schritt schlägt also bei 1 oder 2 fehl, aber nie, bevor du sehen kannst, warum. Die Seite Exit-Codes erklärt, was jeder Code bedeutet. Sollte die interne Exit-Code-Verdrahtung je brechen, schlägt die Action mit 2 fehl, statt einen falschen Erfolg zu melden.

Übersetzungen persistieren

Ohne dry-run schreibt der Standardbefehl translate aktualisierte Locale-Dateien in den Checkout des Runners, und dort hört die Action auf: sie committet nicht. Um die Änderungen zu behalten, füge einen eigenen Schritt hinzu, der committet und pusht oder einen Pull Request öffnet. Wenn CI nur fehlende oder veraltete Übersetzungen melden soll, ohne etwas zu schreiben, setze dry-run: "true" unter translate, oder setze command: check (oder command: diff), um stattdessen ein schreibgeschütztes Gate auszuführen.

Sicherheit

Pinne beide Referenzen exakt: die uses:-Zeile auf einen Commit-SHA und die Eingabe version auf ein exaktes @verbatra/cli-Release. Die zweite erzwingt die Action selbst, indem sie alles ablehnt, was keine exakte Semver-Version ist; ein Lauf kann also nie stillschweigend latest auflösen. Gib dem Workflow nur die Rechte, die er braucht: contents: read für einen Bericht, plus contents: write oder pull-requests: write nur, wenn ein späterer Schritt committet oder einen Pull Request öffnet. Eingaben erreichen die CLI über die Umgebung als Daten und werden in ein quotiertes Argument-Array expandiert, nie in Shell-Text gespleißt; ein präparierter Eingabewert bleibt also ein Argument und wird nie zu ausführbarem Code.