Die GitHub Action nutzen

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

Bevor du anfängst, brauchst du:

• Eine verbatra-Konfiguration direkt in dem Verzeichnis, in dem die Action läuft (siehe 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 einbauenLink zu diesem Abschnitt kopieren

Die Action liegt in verbatra/action und im GitHub Marketplace; 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.

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> # 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 übergebenLink zu diesem Abschnitt kopieren

Reiche den Schlüssel aus deinen Repository-Secrets unter der Variable weiter, die dein Provider liest; Provider listet sie auf. Die Action hat keine Schlüssel-Eingabe, ein Schlüssel reist also nie als Eingabe oder CLI-Argument.

Einen Pull Request absichernLink zu diesem Abschnitt kopieren

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:

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check

Übersetzungsqualität prüfenLink zu diesem Abschnitt kopieren

Ergänze command: check um qa: "true", um verbatra check --qa über jede eingecheckte Übersetzung laufen zu lassen, auch über von Hand getippte Werte.

      - uses: verbatra/action@<commit-sha> # 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: <locale>: 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 verlangenLink zu diesem Abschnitt kopieren

Ergänze command: check um require-reviewed: "true", um verbatra check --require-reviewed auszuführen. Der Schritt schlägt fehl, solange eine maschinell geschriebene Übersetzung in der committeten verbatra.provenance.json nicht freigegeben ist; dort speichert Studio die Review-Entscheidungen. Es bleibt nur lesend und ohne Schlüssel und lässt sich mit qa kombinieren.

      - uses: verbatra/action@<commit-sha> # 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-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üfenLink zu diesem Abschnitt kopieren

Setze locales auf eine kommagetrennte Liste wie de,fr, um jeden Befehl auf diese Ziel-Locales zu beschränken.

      - uses: verbatra/action@<commit-sha> # a commit on the v1 line
        with:
          version: 0.12.0
          command: check
          locales: "de,fr"

Sensible InhalteLink zu diesem Abschnitt kopieren

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 ModusLink zu diesem Abschnitt kopieren

Mit provider: { id: "none" } (siehe Rein menschlicher Workflow) 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:

      - uses: verbatra/action@<commit-sha> # 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.

KonfigurationssucheLink zu diesem Abschnitt kopieren

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:

      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 behaltenLink zu diesem Abschnitt kopieren

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.

EingabenLink zu diesem Abschnitt kopieren

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.

OutputsLink zu diesem Abschnitt kopieren

Was ein Lauf dir zeigtLink zu diesem Abschnitt kopieren

• Annotationen. Unter translate mit Exit 1 wird jede fehlgeschlagene oder teilweise Locale zu einer Fehler-Annotation mit dem Titel verbatra: <locale>. Unter check oder diff bekommt jede abweichende Locale eine mit dem Titel verbatra check: <locale> oder verbatra diff: <locale>. 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 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.

SicherheitLink zu diesem Abschnitt kopieren

Pinne beide Referenzen: uses: auf einen Commit-SHA und version auf ein exaktes Release (aktuelles auf npm); 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 auchLink zu diesem Abschnitt kopieren

• verbatra in CI ausführen: dieselben Gates in jedem CI-System.
• verbatra/action: die Release Notes und die aus action.yml erzeugte Eingaben-Referenz.