verbatra in CI ausführen

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.
• 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.

Ein Drift-Gate hinzufügenLink zu diesem Abschnitt kopieren

verbatra check 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:

name: i18n
on: pull_request

permissions:
  contents: read

jobs:
  check-translations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
      - uses: pnpm/action-setup@<commit-sha>
      - uses: actions/setup-node@<commit-sha>
        with:
          node-version: 22
      - run: pnpm install --frozen-lockfile
      - run: pnpm exec verbatra check

Tausche check gegen verbatra diff, 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üfenLink zu diesem Abschnitt kopieren

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:

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 <path> eine einzelne Locale-Datei.

Siehe die Qualitätsprüfung und Eine Datei. Die GitHub Action führt dasselbe Gate mit qa: "true" aus.

Auf Review-Entscheidungen prüfenLink zu diesem Abschnitt kopieren

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 und die MCP-Review-Tools schreiben:

verbatra check --require-reviewed

Auch das braucht keinen Schlüssel. Die Codes, die es meldet, stehen unter Freigegebene Übersetzungen verlangen.

Bei einem Push übersetzenLink zu diesem Abschnitt kopieren

Führe verbatra translate 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 steht, welche Variable jeder Provider liest.

      - 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.
• Bei einem Provider mit Rate-Limit übersetzt du mit --locales eine Locale pro Schritt.

Vorab mit doctor prüfenLink zu diesem Abschnitt kopieren

Setze verbatra doctor 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-CodesLink zu diesem Abschnitt kopieren

Verzweige auf den Exit-Code, nie auf den Text. Was jeder Code bedeutet, samt Sonderfällen, steht unter Exit-Codes und JSON-Ausgabe; ein Fehlercode in der Ausgabe wird unter Fehlercodes erklärt.

JSON-AusgabeLink zu diesem Abschnitt kopieren

Übergib --json für einen Envelope pro Datensatz auf stdout. Seine Felder stehen unter Exit-Codes und JSON-Ausgabe, das result jedes Befehls auf seiner Befehlsseite. verbatra mit JSON skripten hat Rezepte, die ihn auswerten.

Schlüssel und InstallationenLink zu diesem Abschnitt kopieren

• 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.

Siehe auchLink zu diesem Abschnitt kopieren

• Die GitHub Action nutzen: dieselben Gates mit Annotationen und einer Job-Zusammenfassung.
• verbatra check und verbatra diff: jedes Flag der beiden Gates.
• Exit-Codes und JSON-Ausgabe: der Vertrag, den ein CI-Schritt liest.
• Fehlercodes: was jeder Code bedeutet und was als Nächstes zu tun ist.