Die Lingo.dev CLI läuft in jeder CI/CD-Umgebung mit Node.js. Füge sie als Pipeline-Schritt hinzu, damit bei jedem Push übersetzt wird – das lockfile sorgt dafür, dass nur geänderte Strings verarbeitet werden. So bleiben Übersetzungen schnell und kosteneffizient, auch wenn dein Projekt wächst.
Auf GitHub? Du hast zwei Möglichkeiten
Die GitHub App ist auf GitHub die einfachste Option – einmal installieren, und sie reagiert automatisch auf Pushes und Pull Requests. Kein Runner, kein API-Key-Secret und kein Lockfile; du konfigurierst das Repository mit .lingo/config.json und einer engineId.
Die GitHub Action und die anderen Integrationen unten führen die CLI in deiner eigenen Pipeline aus – mit i18n.json, einem i18n.lock-Lockfile und einem LINGODOTDEV_API_KEY-Secret. Das ist der richtige Weg, wenn Übersetzungen zusammen mit anderen CI-Schritten laufen sollen oder wenn du nicht auf GitHub bist.
Im Rest dieses Leitfadens geht es um die GitHub Action und die CLI.
So funktioniert's#
Die CI/CD-Pipeline führt die CLI nach dem Checkout als Schritt aus. Die CLI liest deine i18n.json-Konfiguration, vergleicht die Quelldateien mit dem Lockfile, um Änderungen zu erkennen, übersetzt das Delta über eine konfigurierte Lokalisierungs-Engine und schreibt die Ergebnisse in die Zieldateien der jeweiligen Sprache. Anschließend committet die Pipeline die übersetzten Dateien oder öffnet einen Pull Request – je nachdem, welchen Workflow du bevorzugst.
Wähle deinen Workflow#
Vier Workflow-Muster decken die meisten Teamstrukturen ab. Starte mit der einfachsten Variante und wechsle zu anspruchsvolleren Setups, wenn dein Team wächst.
| Workflow | So funktioniert's | Am besten geeignet für | Nachteil |
|---|---|---|---|
| Direkt nach main committen | Übersetzt und committet direkt nach main | Kleine Teams, null Reibung | Kein Prüfungsschritt für Übersetzungen |
| PR von main | Übersetzt und öffnet einen PR zur Prüfung | Teams, die Übersetzungen prüfen | Erfordert manuelle PR-Freigabe |
| In den Feature-Branch committen | Übersetzt bei Pushes auf den Feature-Branch | Langlebige Feature-Branches | Übersetzungs-Commits in der Branch-Historie |
| PR vom Feature-Branch | Übersetzt und öffnet einen PR vom Feature-Branch | Maximale Kontrolle pro Feature | Mehrere PRs pro Feature |
Unsere Empfehlung zum Start
Direkt nach main zu committen funktioniert für die meisten Teams sehr gut. Übersetzungen werden bei jedem Push ausgeliefert, das Lockfile sorgt für Konsistenz, und Glossar- sowie Markenstimme-Regeln der Lokalisierungs-Engine sichern die Qualität. Wechsle zu PR-basierten Workflows, wenn du eine menschliche Prüfung von Übersetzungen brauchst.
Schnellstart#
Speichere deinen Lingo.dev-API-Key als CI/CD-Secret und füge dann den Übersetzungsschritt zu deiner Pipeline hinzu.
Lingo.dev bietet eine offizielle GitHub Action, die Checkout, Übersetzung sowie das Erstellen von Commits oder PRs übernimmt.
Du willst keine Workflow-Datei, kein API-Key-Secret und kein Lockfile verwalten? Die GitHub App übernimmt kontinuierliche Lokalisierung auf GitHub ganz ohne all das – einmal installieren und .lingo/config.json konfigurieren.
Direkt nach main committen:
name: Translate
on:
push:
branches: [main]
permissions:
contents: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}PR von main – füge pull-request: true und ein GH_TOKEN hinzu:
name: Translate
on:
push:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
pull-request: true
env:
GH_TOKEN: ${{ github.token }}Im vollständigen Leitfaden zur GitHub-Actions-Integration findest du Feature-Branch-Workflows, benutzerdefinierte Commit-Nachrichten, Monorepo-Unterstützung und GPG-Signierung.
Übersetzungen verifizieren#
Das Flag --frozen und das Lockfile gehören zur GitHub Action und zur CLI. Die GitHub App verfolgt den Übersetzungsstatus serverseitig und hat weder ein Lockfile noch ein entsprechendes --frozen-Äquivalent.
Verwende das Flag --frozen als Deployment-Gate, um sicherzustellen, dass keine unübersetzten Inhalte in Produktion gehen. Die CLI beendet sich mit einem Status ungleich null, wenn Strings übersetzt werden müssen.
npx lingo.dev@latest run --frozenFüge das als separaten Pipeline-Schritt hinzu, der vor dem Deployment ausgeführt wird:
- name: Verify translations
run: npx lingo.dev@latest run --frozenMonorepo-Workflows#
Für Monorepos mit mehreren Paketen, die jeweils eigene Übersetzungsdateien haben, verwende die Option working-directory, um gezielt bestimmte Pakete anzusteuern:
- uses: lingodotdev/lingo.dev@main
with:
api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
working-directory: apps/webMerge-Konflikte#
Das gilt für die GitHub Action und die CLI. Die GitHub App verwendet kein Lockfile und hat daher keine i18n.lock-Konflikte, die gelöst werden müssen.
Das Lockfile (i18n.lock) kann zu Konflikten führen, wenn Branches mit Übersetzungsänderungen zusammengeführt werden. Die Lösung ist einfach: Lösche das konfliktbehaftete Lockfile, schließe den Merge ab und generiere es neu:
git merge feature-branch
rm i18n.lock
git add .
git merge --continue
npx lingo.dev@latest lockfile --forceDer Befehl lockfile --force erstellt das Lockfile aus dem aktuellen Stand deiner Quelldateien neu, ohne neue Übersetzungen auszulösen. Im Leitfaden zu fortgeschrittenen Integrationsmustern findest du rebase-basierte Lösungen und Strategien zur Vermeidung von Konflikten.
