Engineering/12. März 2026/9 Min. Lesezeit

Übersetzungen automatisch mit GitHub synchronisieren: Ein vollständiger CI/CD-Leitfaden zur Lokalisierung

Eray Gündoğmuş

Die meisten Teams verwalten Übersetzungen über einen mühsamen manuellen Zyklus: Strings exportieren, an Übersetzer senden, warten, Dateien zurückerhalten, ins Repository kopieren, Merge-Konflikte beheben und von vorne beginnen. Dieser Prozess bricht schnell zusammen, wenn Sie häufig ausliefern oder mehrere Sprachen unterstützen.

Es gibt einen besseren Weg. Indem Sie Ihren GitHub-Repository direkt mit Ihrem Übersetzungsmanagement-System verbinden, können Sie den gesamten Zyklus automatisieren – von der Erkennung neuer Strings im Code bis zur Lieferung fertiger Übersetzungen als Pull Requests.

Dieser Leitfaden führt durch die Einrichtung der automatischen Übersetzungssynchronisation mit GitHub mithilfe von better-i18n und behandelt Webhook-Mechanismen, den PR-basierten Lieferworkflow, Multi-Repo-Konfigurationen und den Doctor CI-Gesundheitscheck-Workflow.

Warum die Übersetzungssynchronisation automatisieren?

Bevor wir zur Einrichtung kommen, lohnt es sich zu verstehen, was manuelle Übersetzungsworkflows kosten:

Kontextwechsel — Entwickler jonglieren zwischen Code und Übersetzungsdateien
Veraltete Übersetzungen — Manuelle Exporte bedeuten, dass Übersetzer an veralteten Quell-Strings arbeiten
Merge-Konflikte — JSON-Übersetzungsdateien sind Konflikt-Magneten, wenn mehrere Personen sie anfassen
Fehlende Abdeckung — Keine automatische Möglichkeit zu wissen, ob ein neues Feature ohne Übersetzungen ausgeliefert wurde
Langsame Lieferung — Übersetzungen warten in einer Warteschlange statt kontinuierlich zu fließen

Die Automatisierung der Synchronisation zwischen GitHub und Ihrer Übersetzungsplattform beseitigt diese Engpässe. Jeder Push zu Ihrem Repository löst die Schlüsselerkennung aus. Jede abgeschlossene Übersetzung wird als Pull Request zurückgeliefert. CI-Checks erkennen fehlende Übersetzungen, bevor sie die Produktion erreichen.

Architekturübersicht

Das Synchronisationssystem hat zwei Richtungen:

Eingehend (Code zur Cloud): Wenn Entwickler Code pushen, sendet GitHub einen Webhook an better-i18n. Die Plattform liest Ihre Übersetzungsdateien, erkennt neue oder geänderte Schlüssel und aktualisiert das Cloud-Dashboard. Übersetzer sehen neue Strings sofort.

Ausgehend (Cloud zum Code): Wenn Übersetzungen abgeschlossen sind, erstellt better-i18n einen Pull Request in Ihrem Repository mit den aktualisierten JSON-Dateien. Ihr Team überprüft und merged über den Standard-Code-Review-Workflow.

Beide Richtungen sind mit HMAC-SHA256-Signaturverifizierung gesichert. Keine nicht authentifizierten Payloads werden verarbeitet.

Schritt 1: Die GitHub App installieren

Beginnen Sie damit, Ihr GitHub-Konto mit better-i18n zu verbinden:

Gehen Sie zu dash.better-i18n.com und öffnen Sie Ihre Projekteinstellungen
Klicken Sie auf Connect GitHub, um die better-i18n GitHub App zu installieren
Wählen Sie aus, auf welche Repositories die App zugreifen kann – Sie können Zugriff auf bestimmte Repositories oder Ihre gesamte Organisation gewähren
Autorisieren Sie die angeforderten Berechtigungen

better-i18n fordert minimale Berechtigungen an:

Berechtigung	Zweck
Repository Contents	Übersetzungsdateien lesen/schreiben (nur Dateien, die Ihren konfigurierten Mustern entsprechen)
Pull Requests	PRs für Übersetzungsupdates erstellen
Webhooks	Push-Events empfangen, um Sync auszulösen

Die App greift niemals auf Ihren Quellcode, Umgebungsvariablen, Secrets oder Dateien außerhalb Ihrer Übersetzungsdateimuster zu.

Schritt 2: Repositories hinzufügen

Sobald die GitHub App installiert ist, fügen Sie die Repositories hinzu, die Sie synchronisieren möchten. Sie können dies über das Dashboard oder programmatisch tun:

github.addRepository({
  project: "your-org/your-project",
  repositoryId: 123456789,
  branch: "main",
  filePattern: "locales/{locale}/{namespace}.json"
})

Der Parameter filePattern teilt better-i18n mit, wo Ihre Übersetzungsdateien zu finden sind. Gängige Muster sind:

locales/{locale}/{namespace}.json — Locale-Ordner mit Namespace-Dateien
src/i18n/{locale}.json — Einzelne Datei pro Locale
packages/*/locales/{locale}.json — Monorepo mit Übersetzungen pro Paket

Multi-Repository-Unterstützung

Sie sind nicht auf ein einzelnes Repository beschränkt. better-i18n unterstützt mehrere Multi-Repo-Konfigurationen:

Monorepo: Ein Repository mit mehreren Apps, die ein Übersetzungsprojekt teilen
Micro-Frontends: Mehrere Repositories, die zu einem gemeinsamen Übersetzungsset beitragen
Plattform + Mobil: Web- und Mobile-Repositories, die aus derselben Übersetzungsquelle synchronisieren

Jedes Repository kann sein eigenes Dateimuster und seine eigene Branch-Konfiguration haben. Übersetzungen fließen zwischen allen verbundenen Repositories und dem zentralen Cloud-Projekt.

Schritt 3: Die Webhook-Mechanismen verstehen

Sobald ein Repository verbunden ist, sendet GitHub Webhook-Events an better-i18n. Hier ist, was jedes Event bewirkt:

Push-Events

Das push-Event ist der primäre Sync-Auslöser. Wenn Sie Code in einen verbundenen Branch pushen:

GitHub sendet den Push-Payload an better-i18n
Die Payload-Signatur wird mit HMAC-SHA256 verifiziert
better-i18n prüft, ob geänderte Dateien Ihrem konfigurierten Dateimuster entsprechen
Wenn Übersetzungsdateien geändert wurden, startet ein Sync-Job
Neue Schlüssel werden zum Cloud-Projekt hinzugefügt, geänderte Übersetzungen werden aktualisiert
Der Sync-Status wird verfolgt und im Dashboard angezeigt

Nur Pushes zu konfigurierten Branches lösen Sync aus. Das Pushen zu einem Feature-Branch löst keinen Sync aus, es sei denn, Sie haben ihn explizit konfiguriert.

Installations-Lifecycle-Events

Event	Was passiert
`installation.deleted`	Die Integration wird automatisch deinstalliert und alle Webhook-Abonnements werden bereinigt
`installation.suspend`	Sync pausiert — keine Webhooks werden verarbeitet, bis die Installation fortgesetzt wird
`installation.unsuspend`	Sync wird fortgesetzt — Webhooks werden wieder normal verarbeitet

Diese Events stellen sicher, dass die Integration mit Ihrem GitHub App-Installationsstatus synchron bleibt. Wenn ein Organisations-Administrator die App aussetzt, stoppt better-i18n die Verarbeitung sofort, anstatt fehlgeschlagene Webhook-Lieferungen anzusammeln.

Schritt 4: Den PR-basierten Übersetzungsworkflow einrichten

Der ausgehende Fluss — die Lieferung von Übersetzungen zurück in Ihr Repository — verwendet Pull Requests statt direkter Pushes. Dies ist eine bewusste Designentscheidung:

Warum Pull Requests?

Code-Review gilt auch für Übersetzungen. Reviewer können Kontextprobleme, Platzhalter-Fehler oder Formatierungsprobleme erkennen, bevor Übersetzungen die Produktion erreichen.
CI läuft gegen Übersetzungsänderungen. Ihre Test-Suite, Linter und der Build-Prozess validieren, dass neue Übersetzungen nichts kaputt machen.
Vollständiger Audit-Trail in git. Jede Übersetzungsänderung ist ein Commit mit einem klaren Diff, der genau zeigt, was sich geändert hat.
Einfaches Rollback. Setzen Sie einen Übersetzungs-PR genauso zurück wie jede andere Änderung.

Wie es funktioniert

Übersetzer oder KI-Agenten aktualisieren Übersetzungen im better-i18n-Dashboard
Wenn ein Batch von Übersetzungen bereit ist, wird eine Veröffentlichung ausgelöst
better-i18n erstellt einen Branch in Ihrem Repository (z.B. better-i18n/translations-2026-03-13)
Die aktualisierten Übersetzungs-JSON-Dateien werden in diesen Branch committed
Ein Pull Request wird gegen Ihren konfigurierten Basis-Branch geöffnet
Ihr Team überprüft den Diff und merged, wenn zufrieden

Der PR enthält nur Übersetzungsdateien — keine anderen Dateien werden berührt. Der Diff zeigt klar, welche Schlüssel sich in welchen Sprachen geändert haben.

Übersetzungen veröffentlichen

Sie können eine Veröffentlichung über mehrere Kanäle auslösen:

Dashboard: Klicken Sie auf den Button "Publish to GitHub" in den Projekteinstellungen
REST API: Rufen Sie den Publish-Endpoint programmatisch auf
MCP-Tools: Verwenden Sie publishTranslations aus KI-Agenten-Workflows

Schritt 5: Den Doctor CI-Workflow aktivieren

Der Doctor-Workflow ist ein GitHub Actions-Workflow, der die Übersetzungsgesundheit bei jedem Commit überwacht. Denken Sie daran als ESLint für Ihre Übersetzungen.

Den Workflow generieren

Verwenden Sie die tRPC API, um die Workflow-Datei zu generieren:

github.createDoctorWorkflow({
  project: "your-org/your-project",
  repositoryId: 123456789
})

Dies erstellt eine .github/workflows/i18n-doctor.yml-Datei in Ihrem Repository.

Was Doctor prüft

Fehlende Übersetzungen — Schlüssel, die in Ihrer Quellsprache vorhanden sind, aber in einer oder mehreren Zielsprachen fehlen. Doctor meldet genaue Anzahlen pro Sprache.

Ungenutzte Schlüssel — Schlüssel, die in Ihren Übersetzungsdateien definiert sind, aber in Ihrer Codebasis nie referenziert werden. Diese blähen Ihre Übersetzungs-Bundles auf und verwirren Übersetzer.

Formatkonsistenz — ICU-Nachrichtensyntax-Validierung über alle Sprachen hinweg. Erkennt Fehler wie nicht übereinstimmende Platzhalter ({count} auf Englisch, aber {nombre} auf Spanisch) oder kaputte Pluralregeln.

Abdeckungsbericht — Ein Vervollständigungsprozentsatz pro Sprache, sodass Sie den Fortschritt auf einen Blick verfolgen können.

Beispiel Doctor-Ausgabe

i18n Doctor Report
==================

Coverage:
  en: 100% (source)
  tr: 94.2% (missing 23 keys)
  de: 87.1% (missing 51 keys)
  ja: 78.3% (missing 86 keys)

Unused keys: 12
Format errors: 0

Result: WARNING — 3 languages below 95% threshold

Doctor integriert sich in das GitHub-Check-System. Pull Requests, die fehlende Übersetzungen oder Formatfehler einführen, zeigen einen Warnstatus an, der Reviewern sofortige Sichtbarkeit über die Übersetzungsauswirkungen gibt.

Doctor mit der CLI kombinieren

Für die gründlichste Abdeckung kombinieren Sie Doctor mit der better-i18n CLI in Ihrer CI-Pipeline:

name: i18n Health Check
on: [push, pull_request]

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Auf hartcodierte Strings scannen, die übersetzt werden sollten
      - name: Scan for untranslated strings
        run: npx @better-i18n/cli scan --ci

      # Lokale Schlüssel mit dem Cloud-Projekt vergleichen
      - name: Sync coverage report
        run: npx @better-i18n/cli sync --format json

      # Doctor läuft automatisch über den generierten Workflow

Der Befehl scan --ci wird mit einem Nicht-Null-Code beendet, wenn nicht übersetzte Strings gefunden werden, und blockiert den PR. Der Befehl sync --format json gibt einen maschinenlesbaren Abdeckungsbericht aus.

Schritt 6: Pre-Commit-Hooks konfigurieren

Erkennen Sie Übersetzungsprobleme noch früher — bevor Code committed wird — mit Pre-Commit-Hooks:

# Mit Husky
npx husky init
echo "npx @better-i18n/cli scan --staged --ci" > .husky/pre-commit

Das Flag --staged teilt der CLI mit, nur Dateien im aktuellen git-Staging-Bereich zu scannen, wodurch der Hook auch in großen Codebasen schnell bleibt.

Für granularere Kontrolle verwenden Sie lint-staged:

{
  "lint-staged": {
    "*.{tsx,jsx}": ["better-i18n scan --ci"]
  }
}

Sync-Tracking und Observability

Jede Sync-Operation — eingehend oder ausgehend — wird als Job mit vollständigem Status und Logs verfolgt. Sie können den Sync-Verlauf über die MCP-Tools oder die REST API abfragen:

Sync-Typen, die Sie sehen werden:

initial_import — Der erste Sync, wenn ein Repository verbunden wird. Importiert alle vorhandenen Übersetzungsdateien.
source_sync — Ausgelöst durch ein GitHub-Push-Event. Synchronisiert geänderte Übersetzungsdateien in die Cloud.
cdn_upload — Deploy von Übersetzungen zum CDN für die Laufzeitnutzung.
batch_publish — Veröffentlicht Übersetzungen als Pull Request zurück zu GitHub.

Jeder Job enthält Zeitstempel, Status (ausstehend, laufend, abgeschlossen, fehlgeschlagen) und detaillierte Logs zum Debuggen.

Alles zusammenfügen

Hier ist der vollständige automatisierte Übersetzungsworkflow nach der Einrichtung:

Ein Entwickler fügt ein neues Feature mit benutzerseitigen Strings hinzu
Sie verwenden useTranslations('namespace') oder getTranslations('namespace') in ihren Komponenten
Pre-Commit-Hook führt scan --staged aus und warnt vor nicht übersetzten Strings
Entwickler pusht zu GitHub
Der Push-Webhook löst einen eingehenden Sync aus — neue Schlüssel erscheinen im better-i18n-Dashboard
Doctor CI läuft auf dem PR und meldet die Übersetzungsabdeckung
Übersetzer (oder KI-Agenten über MCP) übersetzen die neuen Schlüssel
Übersetzungen werden veröffentlicht — ein PR wird im Repository mit aktualisierten JSON-Dateien erstellt
Das Team überprüft und merged den Übersetzungs-PR
CDN Deploy macht Übersetzungen sofort zur Laufzeit verfügbar

Der gesamte Zyklus läuft ohne manuelles Dateikopieren, Export-/Importschritte oder Merge-Konfliktlösung. Übersetzungen fließen kontinuierlich zwischen Ihrer Codebasis und der Cloud.

Häufige Konfigurationen

Monorepo mit mehreren Apps

your-monorepo/
├── apps/
│   ├── web/
│   │   └── locales/{locale}/{namespace}.json
│   └── admin/
│       └── locales/{locale}/{namespace}.json

Verbinden Sie das Repository einmal mit einem Dateimuster, das beide Apps abdeckt: apps/*/locales/{locale}/{namespace}.json.

Separate Repositories pro Plattform

Verbinden Sie jedes Repository unabhängig mit seinem eigenen Dateimuster. Übersetzungen werden über das zentrale Cloud-Projekt geteilt — einmal aktualisieren, in alle Repositories veröffentlichen.

Feature-Branch-Workflow

Standardmäßig löst Sync nur bei Pushes zu Ihrem konfigurierten Basis-Branch (normalerweise main) aus. Für Teams, die Übersetzungs-Sync auf Feature-Branches wünschen, konfigurieren Sie mehrere Branches in den Repository-Einstellungen.

Fazit

Die Automatisierung der Übersetzungssynchronisation mit GitHub beseitigt die manuellen Engpässe, die die internationale Produktentwicklung verlangsamen. Webhook-getriebener eingehender Sync hält Übersetzer mit frischen Strings am Arbeiten. PR-basierte ausgehende Lieferung stellt sicher, dass Übersetzungsänderungen denselben Review-Prozess durchlaufen wie Code. Doctor CI erkennt Abdeckungslücken, bevor sie die Produktion erreichen.

Die Einrichtung dauert etwa fünfzehn Minuten: Installieren Sie die GitHub App, fügen Sie Ihre Repositories hinzu, konfigurieren Sie Dateimuster und aktivieren Sie den Doctor-Workflow. Ab diesem Punkt fließen Übersetzungen automatisch zwischen Ihrer Codebasis und der Cloud.

Wenn Sie Übersetzungen über mehrere Repositories verwalten oder Benutzer in mehr als einigen wenigen Sprachen bedienen, amortisiert sich diese Automatisierung im ersten Sprint.

Comments

Loading comments...