GitHub Translation Sync: Lokalisierungs-Workflow automatisi…

Übersetzungsdateien, die über Branches verteilt sind, manuelles Kopieren von JSON-Schlüsseln, Slack-Nachrichten mit der Frage „Hat jemand die französischen Übersetzungen gepusht?" – wenn Ihnen das bekannt vorkommt, benötigt Ihr Lokalisierungs-Workflow Automatisierung.

GitHub Translation Sync eliminiert den manuellen Aufwand, Übersetzungsdateien mit Ihrem Codebase synchron zu halten. Es überwacht Ihr Repository auf neue Übersetzungsschlüssel, sendet sie zur Übersetzung (KI oder menschlich) und liefert fertige Übersetzungen als Pull Requests zurück – alles ohne Ihren Git-Workflow zu verlassen.

Dieser Leitfaden führt Sie durch die Einrichtung von GitHub Translation Sync von Grund auf, die Konfiguration PR-basierter Workflows, die CI/CD-Integration und die Optimierung für die Teamzusammenarbeit.

Was ist GitHub Translation Sync?

GitHub Translation Sync ist ein bidirektionaler Synchronisierungsmechanismus zwischen Ihrem Git-Repository und einer Übersetzungsmanagement-Plattform. Anstatt Übersetzungsdateien manuell zu pushen und zu pullen, erledigt die Synchronisierung Folgendes:

Erkennt neue oder geänderte Schlüssel, wenn Sie Code pushen
Sendet sie an Ihre Übersetzungsplattform zur Übersetzung
Liefert fertige Übersetzungen als Pull Requests zurück
Hält Übersetzungsdateien synchron über Branches hinweg

Warum PR-basierte Übersetzungslieferung?

Traditionelle Lokalisierungs-Workflows verwenden CLI-Push/Pull-Befehle. Der PR-basierte Ansatz ist besser, weil:

CLI Push/Pull	PR-basierte Synchronisierung
Manueller Prozess, leicht zu vergessen	Automatisch, immer synchron
Kein Überprüfungsschritt für Übersetzungen	PR-Review erkennt Probleme
Direkter Commit auf den Hauptbranch	Branch-Schutz wird eingehalten
Kein Audit-Trail	Vollständige Git-Historie für Übersetzungen
Verantwortung einer Person	Team-sichtbar über PR-Benachrichtigungen
Merge-Konflikte sind häufig	Sync erledigt Rebasing automatisch

Voraussetzungen

Bevor Sie GitHub Translation Sync einrichten, benötigen Sie:

Ein GitHub-Repository mit Übersetzungsdateien (JSON-, YAML-, PO- oder ARB-Format)
Ein Better i18n-Projekt (Registrierung auf better-i18n.com)
Repository-Administratorzugriff (für die Installation der GitHub App)
Übersetzungsdateien in einer konsistenten Verzeichnisstruktur

Unterstützte Verzeichnisstrukturen

# Muster 1: Locale-Verzeichnisse
locales/
  en/
    common.json
    dashboard.json
  es/
    common.json
    dashboard.json

# Muster 2: Locale-Dateiendung
locales/
  common.en.json
  common.es.json
  dashboard.en.json
  dashboard.es.json

# Muster 3: Einzelnes Verzeichnis mit Locale-Präfix
i18n/
  en.json
  es.json
  fr.json

# Muster 4: Framework-spezifisch (z. B. Flutter ARB)
lib/l10n/
  app_en.arb
  app_es.arb

Schritt 1: GitHub App installieren

Der GitHub Sync funktioniert über eine GitHub App, die Lese-/Schreibzugriff auf die Übersetzungsdateien Ihres Repositorys hat.

Gehen Sie zu Ihrem Better i18n-Projekt-Dashboard
Navigieren Sie zu Settings dann Integrations
Klicken Sie auf Connect GitHub
Wählen Sie die Repositories aus, die Sie synchronisieren möchten
Genehmigen Sie die angeforderten Berechtigungen

Berechtigungen erklärt

Berechtigung	Warum sie benötigt wird
Read: Code	Neue/geänderte Übersetzungsschlüssel erkennen
Read/Write: Pull Requests	PRs mit fertigen Übersetzungen erstellen
Read: Metadata	Zugriff auf Repository-Informationen
Webhooks	Push-Ereignisse für Sync-Trigger empfangen

Die GitHub App greift nur auf übersetzungsbezogene Dateien zu. Sie liest weder Ihren Quellcode noch Umgebungsvariablen oder Secrets.

Schritt 2: Synchronisierung konfigurieren

Erstellen Sie eine Konfigurationsdatei im Stammverzeichnis Ihres Repositorys:

# better-i18n.yml
sync:
  # Quellsprache — Schlüssel werden aus den Dateien dieser Locale extrahiert
  sourceLanguage: en

  # Zielsprachen — Übersetzungen werden für diese generiert
  targetLanguages:
    - es
    - fr
    - de
    - ja
    - ko
    - "zh-CN"

  # Pfadmuster für Übersetzungsdateien
  # Unterstützt Glob-Muster mit {locale}- und {namespace}-Platzhaltern
  paths:
    - "locales/{locale}/{namespace}.json"

  # Alternative: eine Datei pro Locale
  # paths:
  #   - "locales/{locale}.json"

  # Branch, der auf Änderungen überwacht wird (Standard: main)
  baseBranch: main

  # Wie Übersetzungen geliefert werden
  delivery:
    # "pr" erstellt Pull Requests, "commit" pusht direkt (nicht empfohlen)
    method: pr

    # PR-Branch-Namensschema
    branchPattern: "i18n/sync-{timestamp}"

    # PRs automatisch mergen, wenn alle Prüfungen bestehen (Branch-Schutz erforderlich)
    autoMerge: false

    # Reviewer, die Übersetzungs-PRs zugewiesen werden
    reviewers:
      - "@i18n-team"

    # Labels für Übersetzungs-PRs
    labels:
      - "i18n"
      - "automated"

  # KI-Übersetzungseinstellungen
  ai:
    # Neue Schlüssel automatisch mit KI übersetzen
    autoTranslate: true

    # Menschliche Genehmigung vor PR-Erstellung erforderlich
    requireApproval: false

    # Benutzerdefinierte Anweisungen für den KI-Übersetzer
    instructions: |
      - Use formal register for German (Sie, not du)
      - Keep brand name "Better i18n" untranslated in all languages
      - Use Oxford comma in English translations

Konfigurationsoptionen Referenz

Option	Typ	Standard	Beschreibung
`sourceLanguage`	string	`"en"`	Quell-Locale-Code
`targetLanguages`	string[]	`[]`	Ziel-Locale-Codes
`paths`	string[]	auto-detect	Glob-Muster für Übersetzungsdateien
`baseBranch`	string	`"main"`	Zu überwachender Branch
`delivery.method`	string	`"pr"`	Liefermethode: `pr` oder `commit`
`delivery.autoMerge`	boolean	`false`	Automatisch mergen, wenn Prüfungen bestehen
`delivery.reviewers`	string[]	`[]`	PR-Reviewer (Benutzer oder Teams)
`delivery.labels`	string[]	`["i18n"]`	PR-Labels
`ai.autoTranslate`	boolean	`true`	Neue Schlüssel mit KI übersetzen
`ai.requireApproval`	boolean	`false`	Genehmigung vor PR erforderlich
`ai.instructions`	string	`""`	Benutzerdefinierte KI-Anweisungen

Schritt 3: Den Sync-Workflow verstehen

Nach der Konfiguration passiert Folgendes in einem typischen Entwicklungszyklus:

Neue Schlüssel hinzufügen

Entwickler               GitHub                Better i18n              GitHub
    |                        |                       |                      |
    |-- commit pushen ------>|                       |                      |
    |   (neuen Schlüssel     |-- webhook ----------->|                      |
    |    zu en/common.json)  |                       |                      |
    |                        |                       |-- KI übersetzt ----->|
    |                        |                       |   neuen Schlüssel    |
    |                        |                       |   für alle Sprachen  |
    |                        |                       |                      |
    |                        |<---------- PR mit Übersetzungen erstellen ---|
    |                        |                       |                      |
    |<-- PR-Benachrichtigung-|                       |                      |
    |                        |                       |                      |
    |-- prüfen & mergen ---->|                       |                      |

Vorhandene Schlüssel aktualisieren

Wenn Sie den Quelltext eines vorhandenen Schlüssels ändern:

Sync erkennt die Änderung per Webhook
Vorhandene Übersetzungen werden als „Überprüfung erforderlich" markiert
KI generiert aktualisierte Übersetzungen
Ein PR mit aktualisierten Übersetzungen wird erstellt
Frühere Übersetzungen werden in der PR-Beschreibung für den Reviewer-Vergleich aufbewahrt

Schlüssel löschen

Wenn Sie einen Schlüssel aus der Quell-Locale entfernen:

Sync erkennt die Löschung
Der entsprechende Schlüssel wird aus allen Zielsprach-Dateien entfernt
Ein PR mit den Löschungen wird erstellt
Die PR-Beschreibung listet alle entfernten Schlüssel für Audit-Zwecke auf

Schritt 4: CI/CD-Integration

Fügen Sie Ihrer CI/CD-Pipeline eine Übersetzungsvalidierung hinzu, um Probleme zu erkennen, bevor Übersetzungen gemergt werden.

GitHub Actions Workflow

# .github/workflows/i18n-validate.yml
name: Validate Translations

on:
  pull_request:
    paths:
      - "locales/**"
    types: [opened, synchronize]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Validate translation coverage
        run: |
          bunx @better-i18n/cli coverage \
            --min 95 \
            --format github-actions

      - name: Validate ICU syntax
        run: |
          bunx @better-i18n/cli validate \
            --format github-actions

      - name: Check for unused keys
        run: |
          bunx @better-i18n/cli lint \
            --unused \
            --format github-actions

      - name: Comment coverage report on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const { execSync } = require('child_process');
            const report = execSync('bunx @better-i18n/cli coverage --format markdown').toString();
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Translation Coverage Report\n\n${report}`
            });

Erforderliche Status-Prüfungen

Konfigurieren Sie den Branch-Schutz, um eine Übersetzungsvalidierung zu erzwingen:

Gehen Sie zu Settings dann Branches dann Branch protection rules
Aktivieren Sie Require status checks to pass before merging
Fügen Sie diese Prüfungen hinzu:
- Validate translation coverage
- Validate ICU syntax

Dadurch wird sichergestellt, dass kein PR mit fehlerhaften Übersetzungen oder unzureichender Abdeckung gemergt werden kann.

Schritt 5: Branch-Strategie für Übersetzungen

Standard: Einzelner Übersetzungs-Branch

Standardmäßig erstellt jede Synchronisierung einen neuen Branch mit fertigen Übersetzungen:

main ------------------------------------------------
  \                                 |
   \-- i18n/sync-20260315 ---------/
       (Übersetzungen für neue Schlüssel)

Dies funktioniert gut für die meisten Teams. Jede Synchronisierung ist isoliert, und Sie können Übersetzungen vor dem Mergen überprüfen.

Erweitert: Feature-Branch-Synchronisierung

Für Teams, die Feature-Branches verwenden, konfigurieren Sie die Synchronisierung so, dass sie Feature-Branches als Ziel hat:

# better-i18n.yml
sync:
  baseBranch: main
  featureBranchSync:
    enabled: true
    # Übersetzungen für PRs synchronisieren, die auf diese Branches abzielen
    targetBranches:
      - "main"
      - "develop"
    # Übersetzungs-PR erstellen, der auf denselben Branch wie der Feature-PR abzielt
    followBranch: true

Mit Feature-Branch-Sync:

main ------------------------------------------------
  \
   \-- feature/new-checkout -------------------------
        \                           |
         \-- i18n/new-checkout -----/
             (Übersetzungen für dieses Feature)

Merge-Konflikte handhaben

Der Sync behandelt die meisten Merge-Konflikte automatisch durch:

Rebase von Übersetzungs-Branches vor dem Erstellen von PRs
JSON-bewusstes Merging (nicht zeilenbasiert) für Übersetzungsdateien
Erneutes Auslösen der Synchronisierung bei erkanntem Konflikt

Wenn eine automatische Auflösung nicht möglich ist, fügt der Sync einen Kommentar zum PR hinzu, der den Konflikt erklärt und manuelle Auflösungsschritte vorschlägt.

Schritt 6: Monitoring und Fehlerbehebung

Sync-Status-Dashboard

Überwachen Sie den Sync-Zustand in Ihrem Better i18n-Dashboard:

Sync-Verlauf: Jedes Sync-Ereignis mit Status (erfolgreich, teilweise, fehlgeschlagen)
Ausstehende Übersetzungen: Schlüssel, die auf Übersetzung warten
Abdeckungstrends: Übersetzungsabdeckung über die Zeit pro Sprache
PR-Aktivität: Offene, gemergte und geschlossene Übersetzungs-PRs

Häufige Probleme und Lösungen

Problem: Sync wird beim Push nicht ausgelöst

Überprüfen Sie, ob die GitHub App im Repository installiert ist
Prüfen Sie, ob der Webhook unter Settings dann Webhooks aktiv ist
Stellen Sie sicher, dass der Push auf den konfigurierten baseBranch geht
Prüfen Sie, ob geänderte Dateien den konfigurierten paths-Mustern entsprechen

Problem: PR hat Merge-Konflikte

Der Sync führt automatisch Rebase durch, aber wenn Ihr Branch stark abgewichen ist, kann manuelle Auflösung erforderlich sein
Lösen Sie Konflikte im Übersetzungs-PR auf und pushen Sie dann — der Sync überschreibt Ihre Auflösung nicht

Problem: KI-Übersetzungen sind von schlechter Qualität

Fügen Sie detaillierte ai.instructions in Ihrer Konfiguration hinzu
Fügen Sie Glossarbegriffe und Markenrichtlinien hinzu
Erwägen Sie, requireApproval für kritische Sprachen zu aktivieren

Problem: Zu viele kleine PRs

Konfigurieren Sie delivery.batchWindow, um Änderungen zu bündeln:

sync:
  delivery:
    # 30 Minuten warten, um mehrere Pushes in einem PR zu bündeln
    batchWindow: 30

Erweiterte Konfiguration

Namespace-Filterung

Nur bestimmte Namespaces synchronisieren:

sync:
  paths:
    - "locales/{locale}/common.json"
    - "locales/{locale}/marketing.json"
  # Interne Namespaces explizit ausschließen
  exclude:
    - "locales/{locale}/internal.json"
    - "locales/{locale}/test-fixtures.json"

Benutzerdefinierte Commit-Nachrichten

sync:
  delivery:
    commitMessage: "chore(i18n): sync translations for {languages}"
    prTitle: "chore(i18n): translations update ({date})"
    prBody: |
      ## Automated Translation Update

      This PR contains translations synced from Better i18n.

      **Languages updated:** {languages}
      **Keys added:** {keysAdded}
      **Keys updated:** {keysUpdated}
      **Keys removed:** {keysRemoved}

      ---
      _Generated by Better i18n GitHub Sync_

Webhook-Ereignisse

Für benutzerdefinierte Integrationen können Sie Sync-Ereignisse über Webhooks abonnieren:

sync:
  webhooks:
    - url: "https://your-server.com/api/i18n-webhook"
      events:
        - sync.completed
        - sync.failed
        - pr.created
        - pr.merged
      secret: "${WEBHOOK_SECRET}"  # Im Better i18n-Dashboard festlegen

Praxisbeispiel: E-Commerce-App-Einrichtung

Hier ist eine vollständige Konfiguration für eine typische E-Commerce-Anwendung mit Next.js:

# better-i18n.yml
sync:
  sourceLanguage: en
  targetLanguages:
    - es
    - fr
    - de
    - ja
    - "pt-BR"
    - "zh-CN"

  paths:
    - "messages/{locale}/{namespace}.json"

  baseBranch: main

  delivery:
    method: pr
    branchPattern: "i18n/translations-{date}"
    autoMerge: true  # Automatisch mergen, wenn CI besteht
    reviewers:
      - "@frontend-team"
    labels:
      - "i18n"
      - "auto-merge"
    batchWindow: 15  # Änderungen innerhalb von 15 Minuten bündeln

  ai:
    autoTranslate: true
    requireApproval: false
    instructions: |
      E-commerce context:
      - "Cart" should use shopping cart terminology (not vehicle)
      - Currency amounts should not be translated (they are formatted by code)
      - Product names in {curly braces} are variables — do not translate
      - Use formal register for German and Japanese
      - Use informal register for Spanish and Portuguese
      - Keep "Better i18n" as-is in all languages

  featureBranchSync:
    enabled: true
    targetBranches: ["main", "staging"]
    followBranch: true

Mit dieser Konfiguration:

Jeder Push auf main oder staging löst eine Synchronisierung aus
Neue Schlüssel werden innerhalb von Minuten von der KI übersetzt
Übersetzungen kommen als automatisch mergefähige PRs an
Feature-Branches erhalten ihre eigenen Übersetzungs-PRs
CI/CD validiert Abdeckung und Syntax vor dem Mergen

Fazit

GitHub Translation Sync verwandelt die Lokalisierung von einem manuellen, fehleranfälligen Prozess in eine automatisierte Pipeline, die sich natürlich in Ihren bestehenden Entwicklungs-Workflow einfügt. Die Schlüsselprinzipien:

Übersetzungen leben in Git — vollständige Historie, Branch-Schutz, Code-Review
Sync ist automatisch — keine manuellen Push/Pull-Befehle mehr, die vergessen werden können
PRs ermöglichen Review — Übersetzungen werden wie jede andere Code-Änderung überprüft
CI/CD erzwingt Qualität — Abdeckungsschwellenwerte und Syntaxvalidierung blockieren fehlerhafte Übersetzungen
KI beschleunigt — neue Schlüssel werden in Minuten übersetzt, nicht in Tagen

Die Einrichtung dauert etwa 30 Minuten. Die in der ersten Woche eingesparte Zeit übersteigt typischerweise den Einrichtungsaufwand.

Bereit, Ihren Übersetzungs-Workflow zu automatisieren? Starten Sie mit Better i18n und verbinden Sie Ihr GitHub-Repository in wenigen Minuten.

GitHub Translation Sync: Lokalisierungs-Workflow automatisieren