CDN Translation Delivery: Leitfaden für Edge-gecachte i18n Performance

CDN Translation Delivery: Leitfaden für Edge-gecachte i18n Performance

Translation Delivery ist ein Performanceproblem, das sich im Verborgenen hält. Ihre App kann Seitenladezeiten unter einer Sekunde, optimierte Bilder und code-gesplittete Bundles haben — doch wenn Übersetzungen verspätet ankommen, sehen Nutzer Layout-Verschiebungen, Ladeanzeigen oder schlimmer noch: flackernde, unübersetzte Keys auf dem Bildschirm.

Dieser Leitfaden erklärt, wie better-i18n Translation Delivery mit Cloudflare R2 und Edge Caching löst, und führt durch alle CDN-Operationen, die Engineering-Teams zur Verfügung stehen.

Warum Translation Delivery für i18n Performance wichtig ist

Herkömmliche i18n-Setups bündeln Übersetzungen in der Anwendung. Jedes Mal, wenn Sie einen Tippfehler korrigieren oder eine neue Sprache hinzufügen, benötigen Sie einen vollständigen Rebuild und ein erneutes Deploy. Bei mobilen Apps bedeutet das, auf die App-Store-Prüfung zu warten. Bei Web-Apps bedeutet das eine Deploy-Pipeline, die eine Nicht-Engineering-Änderung blockiert.

CDN Translation Delivery entkoppelt Übersetzungsinhalte vom Anwendungscode. Übersetzungen liegen am Edge und werden vom nächstgelegenen Cloudflare-Knoten zum Nutzer ausgeliefert. Ihre App ruft sie zur Laufzeit über HTTP ab.

Die Performancemerkmale:

• Unter 50ms Auslieferung vom nächstgelegenen Edge-Knoten (300+ Standorte weltweit)
• Null Origin Round-Trips für gecachte Übersetzungen
• Inkrementelle Updates ohne erneutes Deployen der Anwendung
• Paralleles Laden nur der Namespaces, die die aktuelle Seite benötigt

Die URL-Struktur, die es möglich macht

Jede Übersetzungsdatei in better-i18n folgt einem deterministischen URL-Muster:

https://cdn.better-i18n.com/{org}/{project}/{locale}/{namespace}.json

Diese Struktur ist bewusst einfach und vorhersehbar. Das bedeutet:

1. Browser-Caches funktionieren nativ — jedes Locale-Namespace-Paar hat eine eindeutige, stabile URL
2. Service Workers können bekannte Pfade precachen — ohne Discovery-Requests
3. CDN Edge-Knoten cachen unabhängig pro Pfad — ein Cache-Miss für fr/auth.json beeinflusst en/common.json nicht
4. Jeder HTTP-Client kann es konsumieren — kein SDK, keine Authentifizierung, keine speziellen Header

Einige reale Beispiele:

# English common translations
https://cdn.better-i18n.com/acme/web-app/en/common.json

# Turkish authentication strings
https://cdn.better-i18n.com/acme/web-app/tr/auth.json

# Japanese dashboard translations
https://cdn.better-i18n.com/acme/web-app/ja/dashboard.json

Jedes Projekt verfügt außerdem über ein Manifest unter /{org}/{project}/manifest.json, das alle verfügbaren Locales auflistet. Mobile SDKs nutzen es, um Sprachen zur Laufzeit automatisch zu erkennen, ohne Locale-Listen hartcodieren zu müssen.

Upload vs. Merge: Zwei Modelle für CDN-Updates

better-i18n bietet zwei unterschiedliche Ansätze zum Aktualisieren von Übersetzungen im CDN.

Vollständiger Upload (cdn.upload und cdn.uploadBatch)

Upload ersetzt die gesamte Namespace-Locale-Datei auf R2:

# Single file
better-i18n cdn upload --locale en --namespace common

# Multiple files in one operation
better-i18n cdn upload-batch --locales en,tr,fr --namespaces common,auth

Batch-Upload ist die richtige Wahl, wenn:

• Eine neue Sprache zum ersten Mal veröffentlicht wird
• CDN-Dateien nach einer größeren Umstrukturierung neu aufgebaut werden
• Ein vollständiger Übersetzungsexport aus Ihrem TMS deployed wird

Batch-Operationen sind intern optimiert — R2-Schreibvorgänge und Cache-Invalidierungen werden gebündelt, was die Gesamtpropagierungszeit im Vergleich zu sequenziellen Einzeluploads reduziert.

Inkrementelles Merge (cdn.merge)

Merge liest die vorhandene Datei von R2, wendet Änderungen auf Key-Ebene an und schreibt das Ergebnis zurück:

better-i18n cdn merge --locale en --namespace common --keys "welcome,nav.home"

Keys, die nicht im Merge enthalten sind, bleiben unverändert. Dies ist die sicherere Option für inkrementelle Updates, weil:

• Kein versehentliches Überschreiben — andere Keys in der Datei bleiben erhalten
• Nebenläufigkeitssicherheit — mehrere Teammitglieder oder CI-Pipelines können verschiedene Keys gleichzeitig mergen ohne Konflikte
• Kleinere Änderungsfläche — nur die angegebenen Keys werden berührt

Merge-Vorschau (cdn.mergePreview)

Vor dem Ausführen eines Merge die Vorschau anzeigen:

better-i18n cdn merge-preview --locale en --namespace common --keys "welcome"

Dies gibt ein Diff zurück, das zeigt, welche Keys hinzugefügt, aktualisiert oder unverändert gelassen werden. Nutzen Sie die Merge-Vorschau in CI-Pipelines, um CDN-Deployments hinter einem Review-Schritt zu sichern — so wie Sie eine Datenbankmigration vor der Anwendung prüfen würden.

Duplikat-Erkennung: CDN-Payload schlank halten

Mit wachsenden Übersetzungsprojekten häufen sich Duplikate an. Ein „Speichern"-Button-String kann in common.json, settings.json und profile.json mit identischen Werten in allen dreien vorhanden sein. Jedes Duplikat vergrößert die CDN-Nutzlast und erzeugt Wartungsaufwand — eines aktualisieren, die anderen vergessen.

Duplikate erkennen (cdn.detectDuplicates)

better-i18n cdn detect-duplicates

Dies scannt alle CDN-Dateien in Ihrem Projekt und erstellt einen Bericht über Keys, die identische Übersetzungswerte über Namespaces hinweg teilen. Der Bericht zeigt:

• Welche Keys dupliziert sind
• In welchen Namespaces sie vorkommen
• Den gemeinsamen Wert

Bereinigen (cdn.cleanupDuplicates)

better-i18n cdn cleanup-duplicates --target-namespace common

Dies konsolidiert Duplikate in einen Ziel-Namespace (typischerweise common) und entfernt sie aus den Quell-Namespaces. Die Operation verwendet intern Merge, ist also sicher für gleichzeitigen Zugriff.

Best Practice: Führen Sie cdn.detectDuplicates nach jedem großen Übersetzungsimport oder jeder Namespace-Reorganisation aus. Planen Sie regelmäßige Bereinigungen, um CDN-Payloads minimal zu halten.

CDN-Lifecycle-Management

Setup (cdn.setup)

CDN Delivery für Ihr Projekt initialisieren:

better-i18n cdn setup

Dies erstellt die R2-Bucket-Struktur, konfiguriert das Cloudflare Worker Edge Routing und richtet Cache-Regeln ein. Führen Sie dies einmalig aus, wenn Sie CDN Delivery für ein Projekt zum ersten Mal aktivieren.

Dateiverwaltung

Alle deployten Dateien auflisten, um Ihren CDN-Zustand zu prüfen:

better-i18n cdn list-files

Gibt Locale, Namespace, Größe und letzten Änderungs-Timestamp jeder Datei zurück. Nützlich zum Verifizieren von Deployments und Identifizieren veralteter Dateien.

Einzelne Dateien löschen, wenn ein Namespace abgekündigt oder ein Locale entfernt wird:

better-i18n cdn delete-file --locale en --namespace legacy-feature

Teardown (cdn.uninstall)

CDN Delivery vollständig entfernen:

better-i18n cdn uninstall

Bereinigt R2-Speicher, Edge-Konfiguration und Cache-Regeln. Verwenden Sie es beim Migrieren eines Projekts oder beim Abschalten einer Anwendung.

Performance in der Praxis

So sieht CDN Translation Delivery in der Produktion aus:

Der Null-Egress-Kostenaspekt ist besonders erwähnenswert. Herkömmliche CDN-Setups berechnen pro GB Bandbreite. Mit R2 sind Ihre Translation-Delivery-Kosten unabhängig vom Traffic-Volumen fest. Ein Projekt, das 10 Millionen Translation-Fetches pro Monat ausliefert, zahlt dasselbe wie eines mit 1.000.

Namespace-basiertes Code-Splitting für Übersetzungen

Das Namespace-Modell fungiert als Code-Splitting für Übersetzungen. Statt alle Übersetzungen vorab zu laden:

❌ /en/all-translations.json (450 KB)

Lädt Ihre App nur das, was die aktuelle Route benötigt:

✅ /en/common.json (12 KB) + /en/auth.json (4 KB) = 16 KB

Dies reduziert den initialen Seitenlade-Payload um über 90% bei Apps mit großen Übersetzungssätzen. In Kombination mit Edge Caching rufen nachfolgende Seitennavigationen nur den neuen Namespace ab — dashboard.json wird geladen, wenn der Nutzer zum Dashboard navigiert, nicht vorher.

Integrationsansätze

SDK-Integration (Empfohlen)

Die offiziellen SDKs übernehmen CDN-Fetching, Caching und Fallback automatisch:

• @better-i18n/next — Serverseitiges Fetching mit ISR/SSG-Unterstützung
• @better-i18n/use-intl — Clientseitiges Fetching für TanStack Router und Vite-Apps
• @better-i18n/expo — Offline-First mit MMKV/AsyncStorage-Caching

Jedes SDK löst die CDN-URL aus Ihrem i18n.config.ts-Projektbezeichner auf. Keine manuelle URL-Konstruktion erforderlich.

Direktes HTTP (Jede Plattform)

Das CDN ist ein reiner HTTPS-Endpunkt. Keine Authentifizierung, keine speziellen Header:

curl https://cdn.better-i18n.com/acme/web-app/en/common.json

Dadurch sind better-i18n-Übersetzungen von jeder Plattform aus konsumierbar: iOS (Swift), Android (Kotlin), Backend-Services (Go, Python, Ruby), Game Engines, IoT-Geräte — alles, was einen HTTP-GET-Request ausführen kann.

Die Publish-to-CDN-Pipeline

Der vollständige Workflow vom Bearbeiten einer Übersetzung bis zur globalen Auslieferung:

1. Bearbeiten — Dashboard, REST API oder MCP-Tools
2. Ausstehende Änderungen vorschauen — getPendingChanges zeigt, was deployed wird
3. Merge-Ergebnis vorschauen — cdn.mergePreview zeigt Key-Level-Diff (optional)
4. Veröffentlichen — publishTranslations löst den cdn_upload-Sync-Job aus
5. Überwachen — getSyncs / getSync verfolgt den Deployment-Status
6. Verifizieren — cdn.listFiles bestätigt, dass die aktualisierte Datei live ist

Dies gibt Engineering-Teams dieselbe Sorgfalt für Translation-Deployments wie für Code-Deployments: vorschauen, veröffentlichen, überwachen, verifizieren.

Erste Schritte

1. Projekt erstellen unter dash.better-i18n.com
2. cdn.setup ausführen, um R2-Speicher und Edge Routing zu initialisieren
3. Übersetzungen hinzufügen und ins CDN veröffentlichen
4. Integrieren mit Ihrem Framework-SDK oder direktem HTTP
5. Überwachen mit cdn.listFiles und cdn.detectDuplicates

CDN Delivery ist auf allen Tarifen verfügbar, einschließlich des kostenlosen Tarifs. Ihre Übersetzungen werden vom ersten Tag an am Edge gecacht.