--- title: "verbatra in CI ausführen" description: "Lass einen Pull Request bei Übersetzungsdrift oder ungeprüfter Maschinenausgabe scheitern und übersetze bei einem Push, mit der CLI in jedem CI-System." type: "how-to" --- # verbatra in CI ausführen Lass einen Pull Request bei Übersetzungsdrift oder ungeprüfter Maschinenausgabe scheitern und übersetze bei einem Push, mit der CLI in jedem CI-System. Nutze diese Anleitung, wenn eine Pipeline Locale-Dateien erkennen soll, die von der Quelle abweichen, oder wenn sie diese bei einem Push für dich übersetzen soll. Jeder Schritt führt dieselbe CLI aus, die du lokal nutzt, daher funktioniert das in jedem CI-System; die Beispiele verwenden GitHub Actions. Bevor du anfängst, brauchst du: - `@verbatra/cli` als Dev-Dependency, mit eingecheckter Lockfile. Die CLI braucht Node `^22.22.0 || >=24`. - Eine eingecheckte Konfiguration, Locale-Dateien und [`verbatra.lock.json`](https://verbatra.kreitz-webdev.de/de/docs/the-lock-file.md). - Nur zum Übersetzen: den API-Schlüssel deines Providers im Secret-Speicher deiner CI. Wenn du GitHub Actions nutzt und Annotationen und eine Job-Zusammenfassung willst, ohne den Job selbst zu schreiben, nimm stattdessen die [GitHub Action](https://verbatra.kreitz-webdev.de/de/docs/github-action.md). ## Ein Drift-Gate hinzufügen [#ein-drift-gate-hinzufügen] [`verbatra check`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md) vergleicht die Quelle, die Zieldateien und die Lock-Datei und endet mit `1`, wenn einer Locale Keys fehlen oder veraltet sind. Es ruft keinen Provider auf, daher braucht der Job keinen Schlüssel und läuft auch bei Pull Requests aus Forks: ```yaml title=".github/workflows/i18n.yml" name: i18n on: pull_request permissions: contents: read jobs: check-translations: runs-on: ubuntu-latest steps: - uses: actions/checkout@ - uses: pnpm/action-setup@ - uses: actions/setup-node@ with: node-version: 22 - run: pnpm install --frozen-lockfile - run: pnpm exec verbatra check ``` Tausche `check` gegen [`verbatra diff`](https://verbatra.kreitz-webdev.de/de/docs/cli/diff.md), wenn du die Key-Namen hinter der Drift willst, etwa um sie in einem Pull-Request-Kommentar zu posten. Es endet unter derselben Bedingung mit `1`; verwaiste Keys erscheinen in seiner Ausgabe, lassen es aber allein nie fehlschlagen. Um nur einige Locales zu prüfen, übergib `--locales de,fr`. Ein `--locales`-Wert, der eine nicht konfigurierte Locale nennt, endet mit `2`, auch neben gültigen, sodass ein Tippfehler das Gate nie grün macht. ### Auf Übersetzungsqualität prüfen [#auf-übersetzungsqualität-prüfen] Drift ist nicht der einzige Fehler, den du abfangen willst. Mit `--qa` laufen zusätzlich das Integritäts-Gate und die Review-Hinweise über jede eingecheckte Übersetzung, sodass ein von Hand bearbeiteter Wert mit kaputtem Platzhalter, kaputtem Markup oder unpassenden ICU-Pluralzweigen den Job fehlschlagen lässt: ```bash verbatra check --qa ``` - Mit `--strict` schlägt er auch bei Review-Warnungen und fehlenden Pluralkategorien fehl. - In einem Edit-Hook prüft `verbatra check --file ` eine einzelne Locale-Datei. Siehe [die Qualitätsprüfung](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md#qualitätsprüfung) und [Eine Datei](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md#eine-datei). Die [GitHub Action](https://verbatra.kreitz-webdev.de/de/docs/github-action.md#übersetzungsqualität-prüfen) führt dasselbe Gate mit `qa: "true"` aus. ### Auf Review-Entscheidungen prüfen [#auf-review-entscheidungen-prüfen] Mit `--require-reviewed` schlägt der Job fehl, solange eine maschinell geschriebene Übersetzung in der eingecheckten `verbatra.provenance.json` nicht freigegeben ist, der Datei, in die [die Review-Warteschlange in Studio](https://verbatra.kreitz-webdev.de/de/docs/review-in-studio.md) und die MCP-Review-Tools schreiben: ```bash verbatra check --require-reviewed ``` Auch das braucht keinen Schlüssel. Die Codes, die es meldet, stehen unter [Freigegebene Übersetzungen verlangen](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md#freigegebene-übersetzungen-verlangen). ## Bei einem Push übersetzen [#bei-einem-push-übersetzen] Führe [`verbatra translate`](https://verbatra.kreitz-webdev.de/de/docs/cli/translate.md) aus und reiche den Provider-Schlüssel aus deinem Secret-Speicher in die Umgebung des Schritts. Die CLI nimmt kein Schlüssel-Argument an und liest keinen Schlüssel aus der Konfiguration; unter [Provider](https://verbatra.kreitz-webdev.de/de/docs/providers.md#keys-kommen-aus-der-umgebung) steht, welche Variable jeder Provider liest. ```yaml - run: pnpm exec verbatra translate --json env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` - Der Schritt schreibt Locale-Dateien in den Checkout und hört dort auf. Füge einen eigenen Schritt hinzu, der sie committet oder einen Pull Request öffnet, und gib nur diesem Job `contents: write` oder `pull-requests: write`. - Für eine Vorschau führe vorher `verbatra translate --dry-run` oder `--estimate` aus: Keins von beiden ruft einen Provider auf oder braucht einen Schlüssel. Siehe [Kosten abschätzen](https://verbatra.kreitz-webdev.de/de/docs/estimating-cost.md). - Bei einem Provider mit Rate-Limit übersetzt du mit `--locales` eine Locale pro Schritt. ## Vorab mit doctor prüfen [#vorab-mit-doctor-prüfen] Setze [`verbatra doctor`](https://verbatra.kreitz-webdev.de/de/docs/cli/doctor.md) vor beide Jobs, damit ein kaputtes Setup früh auffällt. Es prüft die Konfiguration, das Format, den Provider, die Schlüsselvariable, die Netzwerkrichtlinie, die Quelldatei und die Locale-Unterstützung und ruft dabei nie einen Provider auf oder liest einen Schlüsselwert. Eine nicht gesetzte Schlüsselvariable meldet es aber als fehlgeschlagene Prüfung, also reiche den Schlüssel in jeden Job, in dem diese Prüfung bestehen soll. ## Exit-Codes [#exit-codes] Verzweige auf den Exit-Code, nie auf den Text. Was jeder Code bedeutet, samt Sonderfällen, steht unter [Exit-Codes und JSON-Ausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#exit-codes); ein Fehlercode in der Ausgabe wird unter [Fehlercodes](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md) erklärt. ## JSON-Ausgabe [#json-ausgabe] Übergib `--json` für einen Envelope pro Datensatz auf stdout. Seine Felder stehen unter [Exit-Codes und JSON-Ausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md#json-ausgabe), das `result` jedes Befehls auf seiner Befehlsseite. [verbatra mit JSON skripten](https://verbatra.kreitz-webdev.de/de/docs/agent-recipes.md) hat Rezepte, die ihn auswerten. ## Schlüssel und Installationen [#schlüssel-und-installationen] - Installiere mit `pnpm install --frozen-lockfile` oder `npm ci`, damit der Job genau das `@verbatra/cli`-Release ausführt, das deine Lockfile festhält. - Halte Secrets aus Jobs heraus, die nie einen Provider aufrufen: `check`, `diff`, `report`, `export`, `import`, `extract`, `pseudo`, `types` und `tmx`. - Verlass dich in CI auf `env:`. Welche Befehle zusätzlich `.env.local` und `.env` laden, steht unter [Umgebungsdateien](https://verbatra.kreitz-webdev.de/de/docs/cli.md#umgebungsdateien). ## Siehe auch [#siehe-auch] - [Die GitHub Action nutzen](https://verbatra.kreitz-webdev.de/de/docs/github-action.md): dieselben Gates mit Annotationen und einer Job-Zusammenfassung. - [`verbatra check`](https://verbatra.kreitz-webdev.de/de/docs/cli/check.md) und [`verbatra diff`](https://verbatra.kreitz-webdev.de/de/docs/cli/diff.md): jedes Flag der beiden Gates. - [Exit-Codes und JSON-Ausgabe](https://verbatra.kreitz-webdev.de/de/docs/cli/output.md): der Vertrag, den ein CI-Schritt liest. - [Fehlercodes](https://verbatra.kreitz-webdev.de/de/docs/error-codes.md): was jeder Code bedeutet und was als Nächstes zu tun ist.