GitHub Integration: Übersetzungen mit Ihrem Repository synchronisieren – better-i18n

GitHub Integration: Übersetzungen mit Ihrem Repository synchronisieren

better-i18n verbindet sich direkt mit Ihren GitHub Repositories. Push-Events lösen eine automatische Synchronisation über HMAC-SHA256-verifizierte Webhooks aus, Übersetzungsaktualisierungen werden als Pull Requests geliefert, und der Doctor CI-Workflow überwacht Ihre Übersetzungsqualität bei jedem Commit.

Wie es funktioniert

Eingehend: Code zur Cloud

Wenn Sie Code zu GitHub pushen, empfängt better-i18n ein Webhook-Event und synchronisiert Ihre Übersetzungsdateien:

1. Push zu GitHub — Ihr Team committet Code-Änderungen
2. Webhook wird ausgelöst — GitHub sendet ein push-Event, verifiziert mit HMAC-SHA256-Signatur
3. Datei-Sync — Übersetzungsdateien, die Ihren konfigurierten Mustern entsprechen, werden mit Ihrem Cloud-Projekt synchronisiert
4. Dashboard-Updates — Neue Keys erscheinen, geänderte Übersetzungen werden angezeigt

Ausgehend: Cloud zu Code

Wenn Übersetzer Übersetzungen im Dashboard (oder über API/MCP) aktualisieren, veröffentlichen Sie diese zurück in Ihr Repository:

1. Übersetzungen aktualisiert — Über Dashboard, REST API oder MCP-Tools
2. Publish — Rufen Sie publishTranslations auf oder verwenden Sie den Dashboard-Publish-Button
3. Pull Request erstellt — better-i18n erstellt einen PR mit den aktualisierten Übersetzungsdateien auf einem dedizierten Branch
4. Ihr Team reviewt und mergt — Standardmäßiger Code-Review-Workflow gilt

Webhook-Events und Sicherheit

better-i18n verwendet GitHub App Webhooks mit HMAC-SHA256-Signaturverifizierung für jedes eingehende Event. Es werden keine nicht authentifizierten Payloads verarbeitet.

Unterstützte Webhook-Events

Jeder Webhook-Payload wird gegen GitHubs HMAC-SHA256-Signatur verifiziert, bevor er verarbeitet wird. Ungültige Signaturen werden sofort abgelehnt.

PR-basierter Übersetzungsworkflow

Übersetzungsaktualisierungen folgen Ihrem bestehenden Code-Review-Prozess:

1. Übersetzer oder KI-Agenten aktualisieren Übersetzungen im better-i18n Dashboard
2. Wenn fertig, veröffentlichen Sie Übersetzungen in Ihr Repository
3. better-i18n erstellt einen Pull Request nur mit den geänderten Übersetzungsdateien
4. Ihr Team reviewt das Diff — sehen Sie genau, welche Keys sich geändert haben, welche Sprachen aktualisiert wurden
5. Mergen wenn zufrieden — Übersetzungen landen in Ihrer Codebasis durch denselben Workflow wie jede andere Code-Änderung

Dieser Ansatz bedeutet:

• Keine direkten Pushes — Alle Übersetzungsänderungen gehen durch PR-Review
• Vollständiger Audit-Trail — Jede Übersetzungsänderung wird in der Git-History verfolgt
• CI-Validierung — Ihre bestehende CI-Pipeline läuft auch gegen Übersetzungs-PRs
• Rollback-Unterstützung — Einen Übersetzungs-PR wie jeden anderen Commit zurücksetzen

Multi-Repository-Unterstützung

Verbinden Sie mehrere Repositories mit einem einzelnen better-i18n-Projekt oder verbinden Sie dasselbe Repository mit mehreren Projekten. Gängige Setups umfassen:

• Monorepo — Ein Repository mit mehreren Apps, die ein Übersetzungsprojekt teilen
• Micro-Frontends — Mehrere Repositories, die zu einem gemeinsamen Satz von Übersetzungen beitragen
• Plattform + Mobil — Web- und Mobil-Repositories, die aus derselben Übersetzungsquelle synchronisieren

Repository-Verwaltung

Verwenden Sie das Dashboard oder die tRPC API, um verbundene Repositories zu verwalten:

Doctor CI-Workflow

Der Doctor-Workflow ist ein GitHub Actions-Workflow, den better-i18n für Ihr Repository generieren kann. Er führt Übersetzungsqualitätsprüfungen bei jedem Push und Pull Request durch.

Was Doctor prüft

• Fehlende Übersetzungen — Keys in Ihrer Quellsprache, die in Zielsprachen fehlen
• Unbenutzte Keys — Keys, die in Übersetzungsdateien definiert sind, aber nicht im Code referenziert werden
• Format-Konsistenz — ICU-Nachrichtensyntax-Validierung über alle Sprachen
• Coverage-Bericht — Übersetzungsabdeckungsprozentsatz pro Sprache

Doctor einrichten

Generieren Sie die Workflow-Datei über die tRPC API:

github.createDoctorWorkflow

Dies erstellt eine .github/workflows/i18n-doctor.yml-Datei in Ihrem Repository, die bei jedem Push und Pull Request ausgeführt wird.

Beispiel Doctor-Ausgabe

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

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

Unused keys: 12
Format errors: 0

Result: WARNING — 2 languages below 95% threshold

Doctor integriert sich mit GitHubs Check-System — PRs, die fehlende Übersetzungen oder Format-Fehler einführen, zeigen einen Warnstatus.

GitHub-Berechtigungen

better-i18n fordert minimale GitHub-Berechtigungen an:

Nur Dateien, die Ihren konfigurierten Mustern entsprechen (z.B. locales/**/*.json), werden aufgerufen. better-i18n liest niemals Ihren Quellcode, Konfigurationsdateien oder irgendetwas außerhalb der Übersetzungsdateipfade.

Dateiformat

better-i18n arbeitet mit JSON-Übersetzungsdateien, die nach Locale und Namespace organisiert sind:

your-repo/
├── locales/
│   ├── en/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   ├── tr/
│   │   ├── common.json
│   │   ├── auth.json
│   │   └── dashboard.json
│   └── de/
│       └── ...

Konfigurieren Sie, welche Dateimuster better-i18n synchronisiert, in Ihren Projekteinstellungen.

CLI: Keys aus Ihrer Codebasis erkennen

Die @better-i18n/cli verbindet Ihre lokale Entwicklung mit dem Cloud-Projekt.

Nach fest codierten Strings suchen

npx @better-i18n/cli scan

Erkennt nicht übersetzten Text in Ihrer React/Next.js-Codebasis:

components/sign-up.tsx (11)
  24:13  missing  "Create an account"  i18n/jsx-text
  32:22  missing  "Name"               i18n/jsx-text

✖ 87 problems (87 missing translations)

Unterstützt:

• useTranslations('namespace') — Client-Komponenten
• getTranslations('namespace') — Server-Komponenten (Next.js App Router)
• JSX-Text, Attribute und locale-basierte Ternaries

Lokal vs. Cloud vergleichen

npx @better-i18n/cli sync

Zeigt, was in Ihrem Code, aber nicht in der Cloud ist, und was in der Cloud, aber nicht im Code verwendet wird:

Coverage:
  Local → Remote: 59%
  Remote Used: 63%

⊕ Missing in Remote (473 keys)
  pages (300)
    affordableEnglishLearning (meta.title, meta.description, ...+12)

⊖ Unused in Code (386 keys)
  features (25)
    practiceSpeaking (title, subtitle, icon)

CI/CD-Integration

Zu Ihrem GitHub Actions-Workflow hinzufügen:

name: i18n 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"
      - run: npx @better-i18n/cli scan --ci
      - run: npx @better-i18n/cli sync --format json

Blockieren Sie PRs, die nicht übersetzte Strings einführen. Prüfen Sie die Übersetzungsabdeckung bei jedem Push.

Pre-Commit-Hooks

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

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

Sync-Tracking

Jeder Sync-Vorgang wird als Job mit vollständigem Status und Logs verfolgt:

// MCP tool: getSyncs
{
  "project": "your-org/your-project",
  "status": "completed",
  "type": "source_sync"
}

Sync-Typen:

• initial_import — Erster Sync beim Verbinden eines Repository
• source_sync — Ausgelöst durch GitHub Push-Events
• cdn_upload — CDN-Deployment
• batch_publish — Übersetzungen zu GitHub veröffentlichen

Konfiguration

i18n.config.ts

Die CLI liest Ihre Projektkonfiguration aus i18n.config.ts:

export const project = "your-org/your-project";
export const defaultLocale = "en";

export const i18nWorkspaceConfig = {
  project,
  defaultLocale,
  lint: {
    include: ["src/**/*.tsx", "app/**/*.tsx"],
    exclude: ["**/*.test.tsx", "**/*.stories.tsx"],
  },
};

Erste Schritte

1. GitHub App installieren — Verbinden Sie Ihr GitHub-Konto unter dash.better-i18n.com
2. Repositories hinzufügen — Wählen Sie, welche Repositories über github.addRepository synchronisiert werden sollen
3. Dateimuster konfigurieren — Teilen Sie better-i18n mit, wo Ihre Übersetzungsdateien gespeichert sind
4. Doctor CI aktivieren — Generieren Sie den i18n-Gesundheitscheck-Workflow mit github.createDoctorWorkflow
5. CLI installieren — npm install -D @better-i18n/cli
6. Sync starten — Pushen Sie Code und beobachten Sie, wie Übersetzungen zwischen GitHub und der Cloud fließen

Die GitHub-Integration ist in allen Tarifen verfügbar.