Übersetzungen in GitHub Actions prüfen

Der Workflow

Speichern Sie es als .github/workflows/i18n-check.yml. Ändern Sie source zu Ihrer Basis-Sprachdatei und languages zu den von Ihnen ausgelieferten Lokalisierungen.

name: i18n check
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kaeris-io/kaeris-action@v1
        with:
          mode: check
          source: locales/en.json
          languages: de,fr

Ohne Python: npx

Das npm-Paket kaeris führt dieselbe Prüfung mit Node 18 oder neuer aus; npx lädt es selbst, ein Installationsschritt entfällt. Es enthält nur check: Zum Übersetzen braucht es das Python-Paket.

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx kaeris check --source locales/en.json --langs de,fr

Das Gleiche ohne die Action

Einfache Schritte mit Python und pip. Das Log zeigt dann jede Fundstelle zeilenweise anstelle der Tabelle, die die Action ausgibt.

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install kaeris
      - run: kaeris check --source locales/en.json --langs de,fr --ci

Fundstellen in der exakten Zeile des Pull Requests (optional)

Die Action kann auch einen SARIF-Bericht schreiben; das Hochladen verwandelt jede Fundstelle in eine Anmerkung im Diff. Code-Scanning-Uploads sind auf öffentlichen Repositories kostenlos; private benötigen GitHub Advanced Security.

name: i18n check
on: pull_request
permissions:
  contents: read
  security-events: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kaeris-io/kaeris-action@v1
        with:
          mode: check
          source: locales/en.json
          languages: de,fr
          sarif-file: kaeris.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: kaeris.sarif

Was der Job ausgibt

Die Action gibt eine Zusammenfassungstabelle pro Sprache aus und endet mit der Fehlerzeile, wenn etwas schiefgeht. Links: Dateien, die in Ordnung sind. Rechts: de.json mit {nam} anstelle von {name} und fehlendem checkout-Schlüssel.

## KAERIS i18n — CI check

Placeholder-loss: **0** (should be 0).

| Language | Status | Missing | Placeholder issues | Translated |
|---|---|---|---|---|
| de | ✓ complete | 0 | 0 | – |
| fr | ✓ complete | 0 | 0 | – |

_Generated from `kaeris check --json` — no fabricated numbers._
step exit=0
--- GITHUB_OUTPUT (without summary body):
missing=0
placeholder-issues=0
changed=false
check-exit-code=0
translate-exit-code=0

## KAERIS i18n — CI check

Placeholder-loss: **1** (should be 0).
Missing keys remaining: **1**.

| Language | Status | Missing | Placeholder issues | Translated |
|---|---|---|---|---|
| de | ⚠ 1 missing, 1 placeholder issue | 1 | 1 | – |
| fr | ✓ complete | 0 | 0 | – |

_Generated from `kaeris check --json` — no fabricated numbers._
::error::kaeris check found incomplete/broken translations — see the job summary for the language matrix
step exit=1
--- GITHUB_OUTPUT (without summary body):
missing=1
placeholder-issues=1
changed=false
check-exit-code=1
translate-exit-code=0

Was der npx-Schritt ausgibt

Dasselbe Projekt, geprüft mit npx: kaeris 0.2.37 aus npm, leerer npm-Cache und CI=true, wie auf einem frischen Runner. In der ersten Zeile installiert npm das Paket.

$ npx kaeris check --source locales/en.json --langs de,fr
npm warn exec The following package was not found and will be installed: [email protected]
✓ de: complete & placeholder-safe
✓ fr: complete & placeholder-safe
✓ all locales complete & placeholder-safe
exit code: 0

$ npx kaeris check --source locales/en.json --langs de,fr
npm warn exec The following package was not found and will be installed: [email protected]
✗ de: 1 missing key(s): checkout
✗ de: 1 placeholder mismatch(es):
    greeting: missing ['{name}'], added ['{nam}']
✗ de: 2 translation fault(s):
    greeting: lost placeholder {name}
    greeting: invented placeholder {nam} (not in source)
✓ fr: complete & placeholder-safe
✗ 1 missing key, 1 placeholder mismatch, 2 translation faults
exit code: 1

1. Speichern Sie den Workflow

   Erstellen Sie .github/workflows/i18n-check.yml mit dem obigen Workflow, mit Ihren eigenen source und languages.

2. Öffnen Sie einen Pull Request

   Pushen Sie einen Branch, der eine Locale-Datei ändert. Der Job läuft bei jedem Pull Request und wird bei einem verlorenen Platzhalter oder einem fehlenden Schlüssel rot.

3. Machen Sie die Prüfung erforderlich

   Fügen Sie in den Repository-Einstellungen den Job als erforderliche Statusprüfung in der Branch-Schutzregel hinzu. Ein roter Job blockiert dann den Merge.

• Was ausgeführt wurde

  Das Schritt-Skript von kaeris-io/kaeris-action unter dem Tag v1, kopiert von GitHub am 27. Oktober 2026 und in Bash auf einem Testprojekt ausgeführt, mit der von PyPI installierten CLI (kaeris 0.2.35). Saubere Dateien: Exit-Code 0. Die fehlerhafte de.json: Exit-Code 1 und die oben gezeigte Fehlerzeile.

• npx

  npx kaeris check aus dem npm-Paket kaeris 0.2.37 lief am 28. Oktober 2026 auf demselben Testprojekt, mit leerem npm-Cache, CI=true und ohne --yes. Saubere Dateien: Exit-Code 0. Die fehlerhafte de.json: Exit-Code 1.

• SARIF

  Das Flag --sarif wurde auf dem fehlerhaften Projekt ausgeführt und schrieb einen Bericht mit 4 Ergebnissen; bei sauberen Dateien schrieb es einen Bericht mit 0. Der Upload zu GitHub wurde nicht versucht.

• Was nicht ausgeführt wurde

  Die Workflow-Datei selbst wurde nicht auf einem GitHub-Runner ausgeführt, ebenso wenig wie actions/checkout, actions/setup-python, actions/setup-node und upload-sarif. Die Syntax der obigen Workflows wurde von GitHub nicht geprüft.

• Welche CLI die Action installiert

  Die Action führt pip install "kaeris>=0.2.12" aus, sodass ein Job die jeweils neueste Veröffentlichung erhält. Wenn Sie eine feste Version benötigen, verwenden Sie die Variante mit einfachen Schritten und fixieren Sie sie: pip install kaeris==0.2.35.

• Auch bei veralteten Schlüsseln fehlschlagen

  Setzen Sie strict: true in der Action (oder --strict in der einfachen Variante).

• Übersetzungen in einem anderen Ordner

  Setzen Sie out: path/to/translations in der Action; standardmäßig wird der Ordner der Quelldatei verwendet.

• Markennamen beibehalten, wie sie geschrieben sind

  --glossary 'KAERIS,GitHub' führt dazu, dass ein Ziel fehlschlägt, das einen der Begriffe fallen gelassen hat. Dieselbe Liste kann unter keep in kaeris.json stehen.

• Anderes Dateilayout

  --out ist der Ordner mit den Übersetzungen und --pattern '{lang}/common.json' deren Dateinamen. Standard: das Layout, das kaeris translate schreibt.

Andere Rezepte: GitLab CI · pre-commit · Make- und npm-Skripte

Referenz zur CLI · Referenz zur Prüfung · Referenz zur GitHub Action · Kostenlose Prüfung im Browser · Übersetzen im Browser