Translation Sync Engine — Zuverlässige Async-Verarbeitung für Ihre Lokalisierungs-Pipeline mit better-i18n
Eine zuverlässige, asynchrone Übersetzungs-Pipeline, die Ihren Quellcode, Übersetzungen und CDN perfekt synchron hält — mit Konflikterkennung, Activity Logging und null Datenverlust.
Warum eine dedizierte Sync Engine?
Übersetzungs-Workflows berühren mehrere Systeme — Ihr Git-Repository, eine Übersetzungsdatenbank, ein CDN für die Laufzeitbereitstellung und KI-Dienste für die Kontextanalyse. Diese Systeme in Echtzeit zu koordinieren ist fehleranfällig. Ein einziger API-Timeout kann Ihre Übersetzungen in einen inkonsistenten Zustand versetzen.
Better i18n löst dies mit einer dedizierten Sync Engine, die auf Cloudflare Queues aufgebaut ist. Jede Operation — vom Importieren von Keys bis zum Veröffentlichen von Übersetzungen — wird als Async-Job mit Wiederholungsversuchen, Reihenfolgegarantien und vollständiger Transparenz verarbeitet.
Das Ergebnis: Ihre Übersetzungen bleiben über alle Systeme hinweg konsistent, selbst wenn etwas schiefgeht.
Architekturübersicht
Die Sync Engine ist ein Cloudflare Queue Consumer, der strukturierte Nachrichten verarbeitet. Jede Nachricht stellt eine diskrete Arbeitseinheit dar — einen auszulösenden Sync, eine hochzuladende Datei, einen zu veröffentlichenden Batch.
Nachrichten durchlaufen einen klar definierten Lebenszyklus:
- Producer — Ihre Aktion (Push-Event, manueller Sync, Veröffentlichung) stellt eine Nachricht in die Warteschlange
- Queue — Cloudflare Queues sorgt für dauerhafte, geordnete Zustellung
- Consumer — Der Sync-Worker nimmt die Nachricht auf und führt den Job aus
- Activity Log — Jeder Schritt wird als Sync-Aktivität für vollständige Rückverfolgbarkeit aufgezeichnet
Diese Trennung bedeutet, dass Ihre API-Antworten schnell sind (die Arbeit geschieht im Hintergrund), und Fehler automatisch wiederholt werden, ohne dass ein Benutzereingriff erforderlich ist.
10 Nachrichtentypen
Die Sync Engine verarbeitet 10 verschiedene Nachrichtentypen, von denen jeder für eine bestimmte Klasse von Arbeit zuständig ist:
| Nachrichtentyp | Zweck |
|---|---|
| SYNC_START | Löst einen vollständigen oder inkrementellen GitHub-Sync aus — ruft Dateien ab, vergleicht Keys, aktualisiert die Datenbank |
| REPO_PUSH_SYNC | Verarbeitet GitHub Push-Webhook-Events — verarbeitet nur geänderte Dateien für schnellen inkrementellen Sync |
| CDN_SETUP | Erstellt das initiale CDN-Manifest und leere Sprachdateien, wenn ein Projekt erstmals konfiguriert wird |
| CDN_UPLOAD | Lädt eine einzelne JSON-Übersetzungsdatei in R2-Speicher hoch |
| CDN_MERGE | Fügt neuen Übersetzungsinhalt in eine bestehende CDN-Datei ein, ohne unveränderte Keys zu überschreiben |
| CDN_CLEANUP | Entfernt alle R2-Dateien für ein Projekt (verwendet bei Projektlöschung oder -zurücksetzung) |
| AI_CONTEXT_ANALYSIS | Analysiert Ihre Website mit Firecrawl + Gemini, um Übersetzungskontext aufzubauen |
| REPO_ANALYSIS | Scannt Ihr GitHub-Repository, um Frameworks zu erkennen, Terminologie zu extrahieren und Projektkontext aufzubauen |
| PUBLISH_BATCH | Überträgt genehmigte Übersetzungen in einer einzigen atomaren Operation sowohl an CDN als auch an GitHub |
| GLOSSARY_SYNC | Synchronisiert Terminologie-Glossare mit DeepL für konsistente maschinelle Übersetzung |
Jeder Nachrichtentyp hat seinen eigenen Handler, seine eigene Validierung und Fehlerwiederherstellungslogik. Ein Fehler beim CDN-Upload blockiert niemals eine Sync-Operation und umgekehrt.
12 Job-Typen für vollständige Lebenszyklusabdeckung
Jobs repräsentieren übergeordnete Workflows, die möglicherweise mehrere Nachrichten erzeugen:
- initial_import — Erstmalige Key-Extraktion aus Ihrem Repository
- incremental_sync — Nur geänderte Dateien seit dem letzten Lauf synchronisieren
- full_sync — Vollständige Neusynchronisierung aller Übersetzungsdateien
- source_sync — Nur Quellsprachänderungen synchronisieren
- bulk_translate — Maschinelle Übersetzung für mehrere Sprachen auslösen
- publish / batch_publish — Genehmigte Übersetzungen in die Produktion übertragen
- cdn_upload / cdn_merge / cdn_setup / cdn_cleanup — CDN-Lebenszyklusoperationen
- glossary_sync — DeepL-Glossare aktuell halten
Job-Typen geben Ihnen granulare Kontrolle. Sie können genau den Workflow auslösen, den Sie benötigen — keine unnötige Verarbeitung, keine verschwendete Rechenleistung.
45+ Activity Actions für vollständige Transparenz
Jeder Sync-Job protokolliert strukturierte Activity Actions während seiner Ausführung. Mit 45+ verschiedenen Action-Typen erhalten Sie ein vollständiges Bild davon, was passiert ist, wann und warum.
Ein typischer Sync-Flow erzeugt diese Aktivitätsspur:
SYNC_STARTED → FETCH_FILES → FILES_FETCHED → COMPARE_KEYS →
UPDATE_DATABASE → PR_GENERATION_STARTED → PR_CREATED → SYNC_COMPLETED
Activity Actions dienen nicht nur zum Debuggen — sie steuern die Echtzeit-Sync-Status-Benutzeroberfläche und ermöglichen es Ihrem Team, genau zu sehen, wo sich ein Sync in seinem Lebenszyklus befindet. Wenn etwas fehlschlägt, verrät Ihnen die zuletzt aufgezeichnete Action genau, was schiefgelaufen ist.
Konflikterkennung und -lösung
Wenn mehrere Quellen denselben Übersetzungs-Key ändern, sind Konflikte unvermeidlich. Die Sync Engine behandelt dies mit einem dedizierten System zur Konflikterkennung und -lösung.
Wie Konflikte erkannt werden
Bei jedem Sync vergleicht die Engine eingehende Änderungen mit dem aktuellen Datenbankzustand. Wenn ein Key seit dem letzten Sync sowohl im Repository als auch in der Datenbank geändert wurde, wird er als Konflikt markiert.
Wie Konflikte gelöst werden
Konflikte werden Ihrem Team mit vollem Kontext angezeigt — dem Quellwert, dem Datenbankwert und den Zeitstempeln jeder Änderung. Sie können Konflikte einzeln oder in großen Mengen lösen:
- Quelle behalten — Die Repository-Version akzeptieren
- Datenbank behalten — Die bestehende Übersetzung beibehalten
- Manuelles Zusammenführen — Den endgültigen Wert selbst bearbeiten
Die Engine überschreibt niemals stillschweigend eine Übersetzung. Jeder Konflikt wird protokolliert, verfolgt und erfordert eine explizite Auflösung.
Zuverlässigkeit by Design
Die Sync Engine ist auf jeder Ebene auf Zuverlässigkeit ausgelegt:
- Dauerhafte Nachrichtenzustellung — Cloudflare Queues garantiert mindestens einmalige Zustellung. Nachrichten überleben Worker-Neustarts und Infrastrukturausfälle.
- Automatische Wiederholungen — Fehlgeschlagene Jobs werden mit exponentiellem Backoff wiederholt. Vorübergehende Fehler (API-Timeouts, Rate-Limits) lösen sich von selbst.
- Idempotente Operationen — Jeder Message-Handler ist so konzipiert, dass er sicher erneut ausgeführt werden kann. Wiederholungen erstellen niemals doppelte Daten.
- Geordnete Verarbeitung — Nachrichten innerhalb eines Projekts werden in der richtigen Reihenfolge verarbeitet, was Race Conditions zwischen verwandten Operationen verhindert.
- Activity Logging — Jeder Schritt wird aufgezeichnet und gibt Ihnen einen vollständigen Audit-Trail für Debugging und Compliance.
Erste Schritte
Die Sync Engine funktioniert sofort, wenn Sie Ihr GitHub-Repository mit Better i18n verbinden. Es gibt nichts zu konfigurieren — Syncs, CDN-Updates und Konflikterkennung werden alle automatisch durchgeführt.
Für Teams, die mehr Kontrolle benötigen, stellt die Sync Engine APIs auf Job-Ebene bereit, mit denen Sie spezifische Workflows auslösen, den Fortschritt überwachen und Konflikte programmatisch lösen können.