Übersetzungen per Git-Sync oder zur Laufzeit ausliefern: Was passt zu Ihrer CI/CD-Pipeline?

Per Git synchronisierte Übersetzungen sind Übersetzungsdateien, die in Ihrem Repository liegen und von Ihrer CI-Pipeline aktuell gehalten werden: Neue Keys gehen an eine Übersetzungsplattform, fertige Übersetzungen kommen als Commit oder Pull Request zurück, und die Nutzer sehen sie nach dem nächsten Deploy. Auslieferung zur Laufzeit bedeutet, dass die Anwendung ihre Übersetzungen während des Betriebs von einem CDN lädt, eine veröffentlichte Änderung erreicht die Nutzer also ohne Commit und ohne erneutes Deployment. Die beiden schliessen sich nicht aus: Viele produktive Setups bündeln eine synchronisierte Kopie in den Build und holen Aktualisierungen zusätzlich vom CDN.

Dieser Beitrag ist eine Entscheidungshilfe für die Frage "Wie synchronisieren wir Übersetzungen mit unserer CI/CD-Pipeline?": wie jede Architektur von Anfang bis Ende aussieht, eine Entscheidungstabelle entlang der Kriterien, die wirklich entscheiden, wie Teams es heute machen, und was keine der beiden Architekturen löst.

Architektur 1: Übersetzungsdateien in Git, per CI synchronisiert

Die Dateien sind das Ergebnis. Der Ablauf, von Anfang bis Ende:

1. Eine Entwicklerin fügt im Code einen Key hinzu, zum Beispiel t('checkout.title'), mit einem Standardwert in der Quellsprache.
2. Bei Push oder Pull Request extrahiert die CI die Keys aus dem Quellcode (oder liest die Dateien der Quellsprache) und schickt neue und geänderte Keys an die Übersetzungsplattform.
3. Übersetzer, maschinelle Übersetzung oder KI füllen die Zielsprachen in der Plattform; Reviewer geben frei.
4. Ein CI-Schritt lädt die Übersetzungen in die Sprachdateien im Repository herunter.
5. Die Änderung landet als Commit oder Pull Request und geht mit dem nächsten Build und Deployment live.

Was Sie bekommen: Das Repository ist das vollständige Bild eines Releases, inklusive seiner Texte. Eine Übersetzungsänderung ist ein Diff, der neben dem Code reviewt werden kann, der sie ausgelöst hat, mit git revert rückgängig gemacht und durch das Auschecken eines alten Tags reproduziert wird. Der Build hat zur Laufzeit keine Abhängigkeit ausserhalb Ihrer Infrastruktur, und genau das wollen Static Site Generation, Server-Side Rendering, Offline-Apps und native Mobile-Apps.

Was es kostet: Jede Übersetzungsänderung ist eine Code-Änderung. Ein Tippfehler im Italienischen wartet auf das nächste Deployment oder bekommt ein eigenes Hotfix-Release. Übersetzung läuft asynchron, die CI kann also nicht darauf warten: Ein heute gepushter Key wird meist erst übersetzt, wenn die Pipeline, die ihn gepusht hat, längst fertig ist, und das Ergebnis kommt in einem späteren Lauf oder in einem Bot-Pull-Request. Sprachdateien, die jeder Feature-Branch anfasst, sind eine klassische Quelle für Merge-Konflikte, und ein Sync-Job, der ganze Dateien neu schreibt, erzeugt Diffs, die niemand reviewen kann.

Architektur 2: Übersetzungen zur Laufzeit vom CDN ausgeliefert

Die Dateien sind ein Implementierungsdetail der Plattform. Der Ablauf:

1. Eine Entwicklerin fügt im Code einen Key hinzu. Er erreicht die Übersetzungsplattform entweder aus der laufenden Anwendung während der Entwicklung (in i18next über die Option saveMissing) oder über einen Sync-Schritt in der CI.
2. Übersetzer, maschinelle Übersetzung oder KI füllen die Zielsprachen; Reviewer geben frei.
3. Die Plattform veröffentlicht den freigegebenen Stand auf einem CDN.
4. Die laufende Anwendung holt die Namespaces, die sie für die aktuelle Sprache braucht, vom CDN, typischerweise beim Laden.
5. Die Nutzer sehen den neuen Text, sobald der Cache abläuft, ohne Commit, Build oder Deployment.

Was Sie bekommen: Übersetzung ist keine Abhängigkeit des Releases mehr. Produkt, Marketing und Übersetzer korrigieren Texte nach ihrem eigenen Zeitplan, eine neue Sprache kann ohne Release live gehen, und das Repository enthält keine Sprachdateien, die kollidieren könnten. Das ist das Auslieferungsmodell hinter Continuous Localization; die Definition und ihre Phasen stehen in Was ist Continuous Localization?.

Was es kostet: ein Netzwerk-Request im kritischen Pfad, abgestimmt über Cache-Laufzeiten (ein langer Cache heisst schnelles Laden und langsamere Aktualisierung, ein kurzer das Gegenteil). Eine Laufzeit-Abhängigkeit vom CDN, produktive Setups brauchen also einen Fallback für blockierte oder fehlende Netzwerke. Traffic, der mit Ihren Besuchern wächst statt mit Ihren Builds. Auf einem öffentlichen CDN veröffentlichte Dateien kann jeder lesen, der die URL kennt. Und das sprachliche Review findet in der Übersetzungsplattform statt, nicht in Ihren Pull Requests.

Architektur 3: beides

Der Hybrid nutzt jede Architektur für das, was sie gut kann:

1. Keys fliessen über einen CI-Sync zur Plattform (oder während der Entwicklung über saveMissing).
2. Beim Build lädt die CI die veröffentlichten Übersetzungen herunter und bündelt sie: Der Server rendert damit, statische Seiten werden daraus generiert, eine Offline-App wird damit ausgeliefert.
3. Zur Laufzeit lädt die Anwendung dieselben Namespaces vom CDN, wo sie es kann, und fällt auf die gebündelte Kopie zurück, wo nicht.
4. Eine zwischen zwei Releases veröffentlichte Korrektur erreicht die Nutzer über das CDN; der nächste Build übernimmt sie ins Bundle.

Die Bedingung ist eine einzige Quelle der Wahrheit für Übersetzungswerte. Der Code besitzt die Keys, die Plattform besitzt die Übersetzungen, und die Dateien in Git sind ein generierter Schnappschuss eines veröffentlichten Stands. Sobald jemand einen Wert im Repository bearbeitet, während jemand anderes ihn in der Plattform bearbeitet, laufen die beiden Ausgaben auseinander, und jeder Sync wird zur Konfliktlösung.

Entscheidungstabelle

So lesen Sie die Tabelle:

• Wählen Sie Git-Sync, wenn Entwickler den Grossteil der Texte schreiben, "mit dem nächsten Release" für eine Korrektur schnell genug ist, der Build in sich geschlossen sein muss (SSR, statischer Export, Offline, native Mobile-Apps) oder Ihre Review-Kultur auf Pull Requests beruht.
• Wählen Sie die Laufzeit-Auslieferung, wenn Personen ausserhalb der Entwicklung die Texte verantworten, Übersetzungskorrekturen nicht auf ein Release warten sollen oder sich Texte deutlich häufiger ändern, als Sie deployen.
• Wählen Sie beides, wenn Sie einen in sich geschlossenen Build und Texte brauchen, die sich zwischen Releases ändern. Serverseitig gerenderte Web-Apps, deren Texte trotzdem korrigierbar sein sollen, sind der typische Fall.

Wie Teams es heute machen

• Dateien im Repository bearbeitet, kein Sync. Entwickler bearbeiten JSON oder YAML direkt neben dem Code. Das günstigste korrekte Setup für eine Entwicklerin und Sprachen, die sie lesen kann; es hört auf zu funktionieren, sobald ein Übersetzer Zugang braucht. Die typischen Fehlerbilder stehen in Übersetzungsdateien verwalten ohne manuelles JSON-Editing.
• Ein zeitgesteuerter Sync-Job. Ein nächtlicher Job oder ein Job nach dem Merge schickt neue Keys los und öffnet einen Bot-Pull-Request mit allem, was seit dem letzten Lauf übersetzt wurde. Das funktioniert und trennt die Übersetzung vom Feature, das sie brauchte: Das Feature wird in der Quellsprache gemergt, seine Übersetzungen kommen später in einem eigenen Pull Request.
• Sync pro Pull Request. Der Sync läuft im Pull Request selbst und nur für die Keys, die dieser Pull Request hinzugefügt oder geändert hat, die Übersetzungen können also vor dem Merge im selben Branch landen. Dafür braucht es einen Diff gegen den Basis-Branch (die volle Git-History im CI-Checkout), und es hängt weiterhin davon ab, dass die Übersetzungen fertig sind, bevor jemand auf Merge klickt.
• CDN-Auslieferung für die Web-App. Die Anwendung lädt Übersetzungen zur Laufzeit; das Repository enthält keine Sprachdateien oder nur die der Quellsprache. Übersetzer veröffentlichen Korrekturen, ohne die Entwicklung zu fragen. Die Mechanik, inklusive Caching, steht in Übersetzungen ohne erneutes Deployment aktualisieren.
• Der Hybrid. Builds laden die veröffentlichten Übersetzungen für das serverseitige Rendering und als Offline-Fallback herunter; der Client lädt die CDN-Version obendrauf.
• Native Apps in der Mobile-CI. Der Mobile-Build lädt die Texte vor dem Kompilieren im Ressourcenformat der Plattform herunter, und Textänderungen kommen mit App-Releases.

Was keine der beiden Architekturen löst

• Qualität. Wo die Dateien liegen, hat keinen Einfluss darauf, ob eine Übersetzung stimmt. Terminologie, Ton und Freigabe regeln Glossare, ein Review-Workflow und automatische QA-Checks, in beiden Architekturen.
• Asynchrone Übersetzung. Weder CI noch CDN machen Übersetzer schneller. Legen Sie fest, was passiert, solange ein Key noch nicht übersetzt ist: Der Rückfall auf die Quellsprache ist eine bewusste Produktentscheidung, kein Fehler.
• Zwei Quellen der Wahrheit. Bidirektionaler Sync ist ein Werkzeug, kein Governance-Modell. Wenn Werte an beiden Orten geändert werden können, entscheiden Sie vor dem ersten Konflikt, welcher gewinnt, nicht währenddessen.
• Sofortige Aktualisierung. Laufzeit-Auslieferung heisst "ohne Deployment", nicht "sofort": Gecachte Dateien bleiben veraltet, bis der Cache abläuft, und ein sehr kurzer Cache kostet Latenz.
• Key-Design. Benennung, Namespaces und Zuständigkeiten liegen in beiden Modellen bei Ihnen; weder ein Sync-Job noch ein CDN entwirft sie.
• Kleine Setups. Eine Entwicklerin, zwei Sprachen, die sie lesen kann, seltene Textänderungen: Dateien in Git und gar keine Plattform sind die günstigste korrekte Antwort. Das Signal zum Umstieg ist die zweite Person, die Texte ändern muss.

Wie das in Locize funktioniert

Locize unterstützt beide Architekturen aus einem Projekt heraus, die Wahl ist also eine Einstellung der Auslieferung, keine Migration. Das Projekt ist die einzige Quelle der Wahrheit für Übersetzungswerte; die Dateien in Ihrem Repository und die Dateien auf dem CDN sind beides Ausgaben seines veröffentlichten Stands.

• In Git, per CI. Drei GitHub Actions: locize/translate extrahiert neue und geänderte Keys, synchronisiert sie, stösst die KI-Übersetzung an und lädt die Ergebnisse herunter (es kapselt i18next-cli localize --ci und verändert Ihren Quellcode nie); locize/sync gleicht bestehende Sprachdateien in beide Richtungen ab, optional mit auto-translate; locize/download holt die veröffentlichten Übersetzungen beim Build für SSR und statische Builds. Keine davon committet: Sie kombinieren sie mit einem Commit- oder Pull-Request-Schritt. Ausserhalb von GitHub führt das CLI dieselben Abläufe aus (locize sync, locize download, npx i18next-cli locize-sync). Ein neues kostenloses Projekt kann eine begrenzte Startmenge automatisch übersetzen, siehe kostenlose CI-Übersetzung für i18next.
• Zur Laufzeit, vom CDN. Übersetzungen werden standardmässig auf dem CDN veröffentlicht: Das Standard-CDN ist öffentlich und hat einen festen Cache von einer Stunde. Das Pro-CDN, ab dem Growth-Plan, ergänzt ein konfigurierbares Cache-max-age pro Version und private Veröffentlichung, die einen API-Key verlangt. Mit i18next lädt i18next-locize-backend sie, und i18next-chained-backend ergänzt für den Hybrid einen gebündelten Fallback. Downloads beim Build zählen ebenfalls als CDN-Downloads, aber pro Build statt pro Besucher.
• Releases und Rollback. Versionen trennen Stufen wie latest und production (locize copy-version, locize publish-version), und die History jedes Keys zeigt, wer was geändert hat, und lässt frühere Werte wiederherstellen.
• Natives iOS und Android. Nur Sync zur Build-Zeit: locize download oder locize sync mit dem Format android, strings oder xcstrings schreibt die Ressourcendateien, bevor die App kompiliert wird. Locize hat kein natives Over-the-Air-SDK, neue Texte erreichen native Apps also mit dem nächsten App-Release.

Um nur zu übersetzen, was ein Pull Request geändert hat: Bei pull_request-Events nutzt command: sync standardmässig den Changed-only-Modus, nur die Keys, die der PR hinzugefügt oder geändert hat, werden also synchronisiert und per KI übersetzt, und nichts wird gelöscht. Der Basis-Branch muss im Checkout enthalten sein:

name: Translate PR
on:
  pull_request:

permissions:
  contents: write

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.head_ref }}
          fetch-depth: 0
      - uses: locize/translate@v2
        with:
          command: sync
          project-id: ${{ secrets.LOCIZE_PROJECTID }}
          api-key: ${{ secrets.LOCIZE_API_KEY }}
      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: 'chore(i18n): translate PR changes'

Pull Requests aus Forks erhalten keine Repository-Secrets, dieser Workflow funktioniert also nur für Branches im selben Repository. Ein Commit, der mit dem Standard-GITHUB_TOKEN gepusht wird, startet keine neuen Workflow-Läufe; die CI läuft auf dem Übersetzungs-Commit also nicht erneut.

Dieselbe Beschränkung auf den Diff gibt es als changed-only: true in locize/sync, als locize sync --changed-only true (locize-cli 12.7 oder neuer) und als npx i18next-cli locize-sync --changed-only (i18next-cli 1.72 oder neuer).

Wenn Sie beides an Ihrem eigenen Code vergleichen möchten: Erstellen Sie ein Projekt, fügen Sie den Workflow oben mit Ihren Secrets hinzu und laden Sie dasselbe Projekt in einem Preview-Build vom CDN. Dann entscheiden Sie mit Ihren eigenen Diffs und Ladezeiten vor Augen.

Häufig gestellte Fragen

Was ist der Unterschied zwischen per Git synchronisierten Übersetzungen und Auslieferung zur Laufzeit? Beim Git-Sync liegen die Übersetzungsdateien im Repository, und ein CI-Schritt hält sie aktuell, Übersetzungen gehen also mit dem nächsten Build und Deployment live. Bei der Laufzeit-Auslieferung lädt die Anwendung die Übersetzungen während des Betriebs von einem CDN, eine veröffentlichte Änderung erreicht die Nutzer also ohne Commit und ohne Deployment, sobald der Cache abläuft.

Wie synchronisieren wir Übersetzungen mit unserer CI/CD-Pipeline? Extrahieren Sie die Keys aus dem Code und schicken Sie neue oder geänderte Keys an Ihre Übersetzungsplattform (idealerweise nur den Diff des Pull Requests), laden Sie dann die fertigen Übersetzungen in Ihre Sprachdateien herunter und committen Sie sie oder öffnen Sie einen Pull Request. Konfigurieren Sie eine Fallback-Sprache für noch nicht übersetzte Keys, und ergänzen Sie die CDN-Auslieferung, wenn sich Texte zwischen Releases ändern sollen.

Welche Übersetzungstools synchronisieren automatisch mit CI/CD-Pipelines? Suchen Sie nach einem CLI oder einer fertigen CI-Action, die Keys extrahiert oder Ihre bestehenden Dateien liest, einen Sync auf den Diff eines Pull Requests beschränken kann, Ihr Dateiformat ohne Verlust von Struktur oder Pluralformen schreibt, Commits Ihrem eigenen Git-Workflow überlässt und optional über ein CDN ausliefern kann. Locize bietet drei GitHub Actions und ein CLI, das in jedem CI-System läuft.

Wir halten unsere Übersetzungen in einem Git-Repository. Kann eine Lokalisierungsplattform die Dateien automatisch synchronisieren? Ja. Ein Sync-Schritt in der CI schickt neue Keys der Quellsprache hinauf und schreibt Übersetzungen in dieselben Dateien und Ordner zurück, festgehalten als Commit oder Pull Request. Halten Sie eine Richtung pro Zuständigkeit ein: Der Code besitzt die Keys, die Plattform besitzt die Übersetzungswerte.

Sollten Übersetzungsdateien ins Repository committet werden? Wenn Build oder Review sie brauchen: SSR und statische Builds, Offline-Apps, native Mobile-Apps oder Teams, die Übersetzungsänderungen im Pull Request reviewen. Kommen die Übersetzungen von einem CDN und liest der Build sie nicht, sind die Dateien eine generierte Kopie, die Sie aus Git heraushalten können. Von Hand bearbeiten sollte sie so oder so niemand.

Können wir Git-Sync und CDN-Auslieferung gleichzeitig nutzen? Ja. Der Build bündelt eine heruntergeladene Kopie der veröffentlichten Übersetzungen als Basis, und die laufende Anwendung lädt neuere Übersetzungen vom CDN, wenn sie es erreicht. Das funktioniert, solange beide Ausgaben aus einem veröffentlichten Stand stammen, und bricht, sobald Werte an zwei Orten bearbeitet werden.