Lingo.dev GitHub-Integration

Die Lingo.dev GitHub Action ist eine sichere, quelloffene CI/CD-Integration, die automatisch neue Inhalte lokalisiert und verhindert, dass unvollständige Übersetzungen in die Produktionsumgebung gelangen. Sie erstellt Pull Requests oder Commits direkt in Ihren Branch, abhängig von den Workflow-Anforderungen Ihres Teams.

Sie implementiert auch eine automatische Konfliktlösung, sodass Ihre Übersetzungen ohne manuelle Eingriffe mit Ihrem Code synchronisiert bleiben.

Die Action unterstützt mehrere Workflow-Szenarien:

Direkte Commits zum Main-Branch, wenn Inhaltsänderungen zusammengeführt werden
Direkte Commits zu Pull-Request-Branches, wenn PRs geöffnet oder aktualisiert werden
Pull Requests mit dem Main-Branch als Ziel für Übersetzungsaktualisierungen
Pull Requests mit bestehenden Pull-Request-Branches als Ziel für Übersetzungsaktualisierungen

Nach Abschluss dieser Anleitung werden Sie:

Eine automatisierte Lokalisierung einrichten, die durch Code-Pushes ausgelöst wird;
Eine sichere Authentifizierung mittels Repository-Secrets konfigurieren;
Zwischen direkten Commits oder Pull-Request-Workflows wählen;
Verstehen, wie kontinuierliche Lokalisierung in Ihren bestehenden Prozess passt.

Lassen Sie uns beginnen!

Voraussetzungen

Repository-Einrichtung

Ihr Repository muss mit der Lingo.dev CLI konfiguriert sein und eine gültige i18n.json-Datei enthalten. Wenn Sie dies noch nicht eingerichtet haben, absolvieren Sie zuerst den CLI-Schnellstart.

Schritt 1. Authentifizierungseinrichtung

Die Lingo.dev GitHub Actions benötigen Zugriff auf Ihre Übersetzungs-Engine und Ihr Repository. Die Authentifizierung erfolgt über Repository-Secrets, die Ihre Anmeldedaten sicher aufbewahren.

Fügen Sie Ihren API-Schlüssel hinzu

Navigieren Sie zu Ihren Repository-Einstellungen → Secrets and variables → Actions, und fügen Sie dann Ihre Übersetzungs-Engine-Anmeldedaten hinzu:

Für Nutzer der rohen LLM-API:

Secret-Name: OPENAI_API_KEY oder ANTHROPIC_API_KEY
Secret-Wert: Ihr API-Schlüssel vom jeweiligen Anbieter

Für Lingo.dev Engine-Nutzer:

Secret-Name: LINGODOTDEV_API_KEY
Secret-Wert: Ihr Projekt-API-Schlüssel von lingo.dev/app

Schritt 2. Workflow erstellen

Erstellen Sie .github/workflows/i18n.yml in Ihrem Repository mit dieser grundlegenden Konfiguration:

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Alternativ können Sie die Lingo.dev GitHub Action als Schritt zu Ihrem bestehenden Workflow hinzufügen:

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Erforderliche Berechtigungen

Ihr Workflow benötigt spezifische Berechtigungen, um ordnungsgemäß zu funktionieren. GitHub Actions erfordert explizite Berechtigungsdeklarationen in der Workflow-Datei:

permissions:
  contents: write # Erforderlich: Commits mit Übersetzungsaktualisierungen erstellen
  pull-requests: write # Optional: Nur erforderlich bei Verwendung des Pull-Request-Modus

Die Berechtigung contents: write ermöglicht der Action:

Commits mit Übersetzungsaktualisierungen zu erstellen
Änderungen direkt in Ihr Repository zu pushen
Auf Dateien in Ihrem Repository zuzugreifen und diese zu modifizieren

Diese Berechtigungen werden dem temporären GitHub-Token des Workflows (${{ github.token }}) erteilt, das automatisch von GitHub für jeden Workflow-Lauf erstellt wird und genau die Berechtigungen hat, die Sie in der Workflow-Datei angeben.

Diese Konfiguration:

Wird bei Pushes auf den Main- und Feature-Branches ausgelöst
Gewährt notwendige Berechtigungen für Commits und Pull Requests
Verwendet die neueste Action-Version für automatische Updates
Greift sicher auf Ihren API-Schlüssel über Repository-Secrets zu

Bonus:

Bei Lingo.dev fügen wir gerne einen workflow_dispatch-Trigger zu jedem Workflow hinzu, damit wir ihn manuell über die GitHub Actions UI (erneut) ausführen können. Dies ist völlig optional, aber wir fanden es sehr hilfreich.

Schritt 3. Wählen Sie Ihren Workflow-Modus

Lingo.dev GitHub Actions unterstützt zwei Betriebsmodi, abhängig von den Code-Review-Anforderungen Ihres Teams.

Direkter Commit-Modus (Standard)

Die Action committet Übersetzungen direkt in Ihren Branch:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Dieser Modus eignet sich am besten für:

Einzelentwickler oder kleine Teams
Feature-Branches, die vor dem Mergen überprüft werden
Projekte, bei denen Übersetzungsaktualisierungen keine separate Überprüfung erfordern

Pull-Request-Modus

Die Action erstellt Pull-Requests für Übersetzungsaktualisierungen:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

Erforderliche Berechtigungen für den Pull-Request-Modus

Der Pull-Request-Modus erfordert zusätzliche Berechtigungen und Repository-Einstellungen:

permissions:
  contents: write # Erforderlich: Zugriff auf Repository-Inhalte und Erstellung von Commits
  pull-requests: write # Erforderlich: Erstellung und Aktualisierung von Pull-Requests

GitHub-Token-Setup: Die Umgebungsvariable GH_TOKEN muss auf ${{ github.token }} gesetzt werden, ein systemgeneriertes temporäres Token, das GitHub automatisch für jeden Workflow-Lauf erstellt. Dieses Token verfügt genau über die Berechtigungen, die im Abschnitt permissions Ihrer Workflow-Datei angegeben sind.

Repository-Einstellungen: Sie müssen GitHub Actions die Erstellung von Pull-Requests in Ihren Repository-Einstellungen ermöglichen:

Gehen Sie zu Settings → Actions → General
Scrollen Sie zum Ende der Seite
Stellen Sie unter "Workflow permissions" sicher, dass "Allow GitHub Actions to create and approve pull requests" aktiviert ist

Wenn Sie diese Option nicht in Ihren Repository-Einstellungen sehen, überprüfen Sie Ihre Organisationseinstellungen:

Gehen Sie zu den Settings → Actions → General Ihrer Organisation
Suchen Sie nach der gleichen Einstellung "Allow GitHub Actions to create and approve pull requests"

Dieser Modus eignet sich am besten für:

Teams mit strengen Code-Review-Anforderungen
Projekte, bei denen Übersetzungsänderungen separate Genehmigung benötigen
Workflows, die eine explizite Überprüfung aller Änderungen erfordern

Schritt 4. Workflow-Szenarien

Die Lingo.dev GitHub Action passt sich automatisch an verschiedene Entwicklungs-Workflows an. Das Verständnis dieser Szenarien hilft Ihnen, die richtige Konfiguration für Ihr Team auszuwählen.

Szenario 1: Main-Branch-Updates (Direkte Commits)

Auslöser: Push zum Main-Branch (z.B. beim Zusammenführen von Pull Requests) Aktion: Committet Übersetzungsaktualisierungen direkt in den Main-Branch

on:
  push:
    branches: [main]

# Action committet direkt in den Main-Branch

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Ablauf: Inhaltsänderungen werden zu main gepusht → Action committet Übersetzungen zu main

Dieses Szenario stellt sicher, dass Ihr Main-Branch immer über aktuelle Übersetzungen verfügt, unmittelbar nachdem Inhaltsänderungen zusammengeführt wurden.

Tipp: Dies ist der Modus, den wir empfehlen. Er erfordert eine gut konfigurierte KI-Lokalisierungs-Engine, um perfekte Lokalisierung zu gewährleisten. Der Vorteil ist, dass er zu null manueller Intervention führt, da fehlende Übersetzungen vor jedem Produktions-Deployment automatisch überprüft und ergänzt werden.

Szenario 2: Pull-Request-Updates (Direkte Commits)

Auslöser: Pull Request geöffnet oder aktualisiert mit Inhaltsänderungen Aktion: Committet Übersetzungsaktualisierungen direkt in den Pull-Request-Branch

on:
  pull_request:
    types: [opened, synchronize]

# Action committet direkt in den PR-Branch

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Ablauf: Inhaltsänderungen im PR-Branch → Action committet Übersetzungen in denselben PR-Branch

Dies hält Übersetzungsaktualisierungen innerhalb des Feature-Branches und stellt sicher, dass Übersetzungen zusammen mit den ursprünglichen Änderungen überprüft werden.

Szenario 3: Pull Requests zum Main-Branch (Pull-Request-Modus)

Auslöser: Push zum Main-Branch (z.B. beim Zusammenführen von Pull Requests) Aktion: Erstellt einen Pull Request mit Übersetzungsaktualisierungen

on:
  push:
    branches: [main]

# Aktion erstellt PR: main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Ablauf: Inhaltsänderungen werden in main gepusht → Aktion erstellt main/lingo.dev Branch → Öffnet PR von main/lingo.dev → main

Szenario 4: Pull Requests zu Feature-Branches (Pull-Request-Modus)

Auslöser: Pull Request geöffnet oder aktualisiert mit Inhaltsänderungen Aktion: Erstellt einen Pull Request mit Übersetzungsaktualisierungen, der auf den Feature-Branch abzielt

on:
  pull_request:
    types: [opened, synchronize]

# Aktion erstellt PR: feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

Ablauf: Inhaltsänderungen in feat/new-feature → Aktion erstellt feat/new-feature/lingo.dev Branch → Öffnet PR von feat/new-feature/lingo.dev → feat/new-feature

Dies ermöglicht separate Übersetzungsreviews für jeden Feature-Branch.

Branch-Namenskonvention

Bei Verwendung des Pull-Request-Modus folgt die Lingo.dev GitHub Action einem konsistenten Benennungsmuster:

Format: <base-branch>/lingo.dev

Beispiele:

Main-Branch-Updates: main/lingo.dev → main
Feature-Branch-Updates: feat/user-auth/lingo.dev → feat/user-auth
Release-Branch-Updates: release/v2.0/lingo.dev → release/v2.0

Diese Namenskonvention stellt sicher, dass Übersetzungs-Branches klar identifizierbar und automatisch mit ihren Quell-Branches verknüpft sind.

Umgang mit externen Beiträgen

Bei der Arbeit mit externen Forks implementieren Sie selektives Checkout, um die Repository-Sicherheit zu gewährleisten:

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

Erforderliche Berechtigungen für externe Beiträge

Die Verarbeitung externer Forks erfordert erhöhte Berechtigungen, um Beiträge sicher zu verarbeiten:

permissions:
  actions: write # Erforderlich: Zugriff auf Workflow-Informationen und Artefakte
  contents: write # Erforderlich: Commits erstellen und auf Repository-Inhalte zugreifen
  pull-requests: write # Erforderlich: Pull Requests von externen Forks aktualisieren

Die Berechtigung actions: write wird speziell benötigt, um:

Auf Pull-Request-Metadaten von externen Forks zuzugreifen
Workflow-Kontext für Sicherheitsvalidierung zu lesen
Artefakte und Workflow-Status sicher zu verwalten

Diese erhöhten Berechtigungen stellen sicher, dass die Aktion Übersetzungen von externen Mitwirkenden sicher verarbeiten kann, während die Repository-Sicherheit durch selektives Auschecken von Dateien gewährleistet wird.

Dieser Ansatz:

Checkt nur Übersetzungsdateien aus dem Fork aus
Verhindert die Offenlegung von sensiblem Repository-Code
Behält die notwendigen Schreibberechtigungen für die Aktion bei

Erweiterte Konfiguration

Passen Sie das Aktionsverhalten mit zusätzlichen Parametern an:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: update translations via lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

Konfigurationsoptionen:

commit-message — Benutzerdefinierte Nachricht für Übersetzungs-Commits
working-directory — Führen Sie die Aktion in einem Unterverzeichnis aus
version — Auf eine bestimmte CLI-Version festlegen (nicht empfohlen)
process-own-commits — Von dieser Aktion erstellte Commits verarbeiten
parallel — Parallele Verarbeitung von Lokalisierungsaufgaben aktivieren (Standard: false)

Parallele Verarbeitung

Die GitHub Action unterstützt parallele Verarbeitung von Lokalisierungsaufgaben, um Übersetzungsworkflows für große Projekte erheblich zu beschleunigen. Aktivieren Sie diese Funktion durch Setzen von parallel: true:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

Wenn aktiviert, wird die Aktion:

Lokalisierungsaufgaben auf mehrere gleichzeitige Worker verteilen
Intelligente Aufgabenverteilungsalgorithmen verwenden, um den Durchsatz zu maximieren
Dateikorruption und Race Conditions durch sorgfältiges Nebenläufigkeitsmanagement verhindern
Die Verarbeitungszeit für Projekte mit vielen Übersetzungsdateien drastisch reduzieren

Diese Funktion ist besonders vorteilhaft für:

Große Projekte mit umfangreichen Übersetzungsanforderungen
Workflows, die mehrere Sprachen gleichzeitig verarbeiten
Teams, die eine schnellere CI/CD-Pipeline-Ausführung benötigen

Hinweis: Parallele Verarbeitung kann die API-Nutzung erhöhen. Überwachen Sie Ihre Nutzung, wenn Sie strikte Ratenbegrenzungen haben.

Verifizierungsmodus

Mit dem Flag --frozen können Sie vor jedem Produktions-Deployment überprüfen, ob alle Übersetzungen aktuell sind.

Hier ist ein Beispiel für die Verwendung des --frozen-Flags in Ihrer Deployment-Pipeline:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

Das --frozen-Flag:

Überprüft, ob alle Übersetzungen aktuell sind
Nimmt keine Änderungen an Dateien vor
Lässt den Build fehlschlagen, wenn Übersetzungen fehlen oder veraltet sind