CI/CD-Workflows für die Lokalisierung

Lingo.dev automatisiert deine Lokalisierung in CI/CD. Dafür gibt es zwei Wege: die GitHub App, die serverseitig auf Pushes und Pull Requests reagiert, oder die CLI in deiner eigenen Pipeline. Beide halten deine Übersetzungen bei jeder Änderung synchron und verarbeiten nur die Strings, die sich tatsächlich geändert haben – so bleibt Lokalisierung auch mit wachsendem Projekt schnell und kosteneffizient.

Option 1: GitHub App (empfohlen)#

Die GitHub App ist der einfachste Weg für Kontinuierliche Lokalisierung. Sie überwacht dein Repository und übersetzt serverseitig – du musst also nichts in deiner Pipeline installieren und keinen API-Schlüssel als CI-Secret hinterlegen.

Die Einrichtung ist einmalig:

1. Installiere die Lingo.dev GitHub App für dein Repository.
2. Committe eine .lingo/config.json mit deinem orgId, engineId, der Quell-Sprache, den Zielsprachen und den zu übersetzenden Dateien. Führe lingo init und lingo link lokal aus, um sie zu erzeugen, und committe anschließend das Ergebnis.
3. Pushen.

Ab dann übernimmt die App beide Workflow-Varianten für dich:

• Bei einem Push auf deinen Standard-Branch committet sie die Übersetzungen zurück in den Branch.
• Bei einem Pull Request fügt sie die Übersetzungen zur PR hinzu, damit du sie vor dem Merge prüfen kannst.

Da die App den Übersetzungsstatus serverseitig nachverfolgt, gibt es kein Lockfile im Repo, das zu Konflikten führen kann, und keinen zusätzlichen Verifizierungsschritt, den du verdrahten musst – sie hält deine Zielsprachen einfach synchron mit der Quelle.

Option 2: CLI in deiner eigenen Pipeline#

Wenn du nicht auf GitHub arbeitest oder Lokalisierung als eigenen Schritt neben Build- und Test-Jobs ausführen möchtest, kannst du die CLI selbst ausführen. Sie funktioniert in jeder CI-Umgebung mit Node.js 22 oder neuer – etwa GitHub Actions, GitLab CI, Bitbucket Pipelines oder jeder anderen.

Der Ablauf ist immer gleich:

1. Installiere @lingo.dev/cli.
2. Authentifiziere dich mit deinem API-Schlüssel über die Umgebungsvariable LINGO_API_KEY.
3. Führe lingo push aus, um geänderte Strings zu übersetzen.
4. Committe die Ergebnisse oder öffne direkt aus dem Job einen Pull Request.

Speichere deinen Lingo.dev API-Schlüssel als CI-Secret und stelle ihn als LINGO_API_KEY bereit. Die committete .lingo/config.json sagt der CLI, was übersetzt werden soll, und das committete .lingo/lock.json (neu erzeugt durch lingo push) verfolgt den Status, sodass nur geänderte Strings verarbeitet werden.

Minimales GitHub Actions-Beispiel#

Dieser Workflow installiert die CLI, übersetzt bei jedem Push auf main und committet die Ergebnisse zurück:

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update translations" || echo "No changes"
          git push

Dieselben zwei Zeilen – npm install -g @lingo.dev/cli, dann lingo push – passen auch in einen script:-Block in GitLab CI oder in einen Schritt in Bitbucket Pipelines. Setze LINGO_API_KEY auf diesen Plattformen als maskierte bzw. geschützte CI-Variable.

Commit oder Pull Request?#

Für welchen Weg du dich auch entscheidest – du bestimmst, wie die Übersetzungen landen:

Mit der GitHub App bekommst du beides automatisch: Bei Pushes auf deinen Standard-Branch committet sie die Übersetzungen direkt, bei offenen PRs fügt sie sie der PR hinzu. In deiner eigenen Pipeline entscheidest du selbst: Committe die Ergebnisse wie oben gezeigt oder lasse den Job statt in den Branch zu pushen einen Pull Request öffnen.

Übersetzungen vor dem Deploy prüfen#

Damit keine unübersetzten Inhalte ausgeliefert werden, füge lingo check als Gate vor deinem Deploy-Schritt hinzu. Der Befehl endet mit einem Status ungleich null, wenn noch Strings übersetzt werden müssen:

- name: Verify translations
  run: lingo check

Die GitHub App hält Sprachen kontinuierlich synchron. Ein eigener Verifizierungsschritt ist daher vor allem dann sinnvoll, wenn du die CLI selbst ausführst.

Monorepos#

Bei Monorepos, in denen jedes Paket seine eigene .lingo/config.json hat, kannst du den Lauf auf ein Paket eingrenzen, indem du einen Glob übergibst, oder die CLI direkt aus dem Verzeichnis dieses Pakets ausführst:

lingo push "apps/web/**"

Nächste Schritte#