CDN Delivery: Edge-Cached Übersetzungen weltweit mit better-i18n

CDN Delivery: Edge-Cached Übersetzungen weltweit mit better-i18n

Jede Übersetzung, die du in better-i18n veröffentlichst, wird im globalen Edge-Netzwerk von Cloudflare bereitgestellt. Deine Anwendung lädt Übersetzungen vom nächstgelegenen Edge-Node — kein Umweg über den Origin-Server, kein erneutes Deployment für Translation-Updates.

CDN-URL-Struktur

Übersetzungen folgen einem vorhersehbaren URL-Muster, das auf deiner Organisation, deinem Projekt, dem Locale und dem Namespace basiert:

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

Beispiele:

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

# Türkischer auth-Namespace
https://cdn.better-i18n.com/acme/web-app/tr/auth.json

# Französischer navigation-Namespace
https://cdn.better-i18n.com/acme/web-app/fr/nav.json

Jede Namespace-Locale-Kombination ist eine separate JSON-Datei, sodass deine App nur die benötigten Übersetzungen lädt. Diese URL-Struktur ist stabil und cachebar — CDN-Edge-Nodes, Browser-Caches und Service-Worker können sie alle nutzen.

Projekt-Manifest

Das CDN stellt außerdem eine Manifest-Datei mit der Sprachkonfiguration deines Projekts bereit:

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

Gibt das languages-Array mit allen Locales in deinem Projekt zurück. Das Expo SDK nutzt dies, um verfügbare Sprachen zur Laufzeit automatisch zu erkennen.

CDN-Operationen

better-i18n bietet einen vollständigen Satz an CDN-Verwaltungsoperationen über CLI, REST API und MCP-Tools.

Setup und Teardown

Upload-Operationen

Einzelner Upload (cdn.upload)

Eine einzelne Namespace-Locale-Datei ins CDN hochladen:

# Englische common-Übersetzungen hochladen
better-i18n cdn upload --locale en --namespace common

Dies schreibt die Datei in R2 und invalidiert den Edge-Cache für diesen spezifischen Pfad. Änderungen propagieren innerhalb von Sekunden zu allen 300+ Edge-Nodes.

Batch-Upload (cdn.uploadBatch)

Mehrere Namespace-Locale-Kombinationen in einem einzigen Vorgang hochladen:

# Alle Namespaces für Englisch und Türkisch hochladen
better-i18n cdn upload-batch --locales en,tr --namespaces common,auth,dashboard

Batch-Upload ist deutlich schneller als einzelne Uploads, wenn mehrere Dateien veröffentlicht werden. Er bündelt R2-Schreibvorgänge und Cache-Invalidierungen und reduziert so die Gesamtpropagationszeit.

Merge-Operationen

Mit Merge kannst du bestimmte Keys in einer bestehenden CDN-Datei aktualisieren, ohne die gesamte Datei zu ersetzen. Dies ist entscheidend für inkrementelle Translation-Updates.

Merge (cdn.merge)

# Aktualisierte Keys in den englischen common-Namespace mergen
better-i18n cdn merge --locale en --namespace common --keys "welcome,nav.home"

Merge liest die vorhandene Datei aus R2, wendet die Key-Level-Änderungen an und schreibt das Ergebnis zurück. Keys, die nicht im Merge enthalten sind, bleiben unverändert. Dies verhindert versehentliche Überschreibungen, wenn mehrere Teammitglieder oder Automatisierungs-Pipelines gleichzeitig veröffentlichen.

Merge Preview (cdn.mergePreview)

Vorschau des Merge-Ergebnisses anzeigen, bevor es ausgeführt wird:

# Merge-Ergebnis vorab anzeigen, ohne es anzuwenden
better-i18n cdn merge-preview --locale en --namespace common --keys "welcome"

Gibt einen Diff zurück, der hinzugefügte, aktualisierte und unveränderte Keys zeigt. Nutze dies in CI-Pipelines oder Review-Workflows, um Änderungen zu prüfen, bevor sie live gehen.

Dateiverwaltung

Duplikaterkennung und -bereinigung

Translation-Projekte akkumulieren mit der Zeit Duplikate — besonders wenn Namespaces reorganisiert oder Keys zwischen Namespaces verschoben werden.

Duplikate erkennen (cdn.detectDuplicates)

Scannt alle CDN-Dateien in deinem Projekt und identifiziert doppelte Translation-Werte über Namespaces hinweg:

better-i18n cdn detect-duplicates

Gibt einen Report zurück, der zeigt, welche Keys identische Werte in verschiedenen Namespaces haben. Dies hilft dir, Übersetzungen in gemeinsame Namespaces zu konsolidieren und die gesamte CDN-Payload-Größe zu reduzieren.

Duplikate bereinigen (cdn.cleanupDuplicates)

Erkannte Duplikate automatisch auflösen basierend auf deinen Konsolidierungseinstellungen:

# Duplikate in den common-Namespace verschieben
better-i18n cdn cleanup-duplicates --target-namespace common

Dies ist eine destruktive Operation — führe immer zuerst cdn.detectDuplicates aus, um zu prüfen, was sich ändert, und verwende cdn.mergePreview, um das Ergebnis im Ziel-Namespace zu verifizieren.

So funktionieren Updates

1. Übersetzungen bearbeiten im Dashboard, über die REST API oder MCP-Tools
2. Veröffentlichen mit publishTranslations — dies löst einen cdn_upload-Sync-Job aus
3. CDN aktualisiert innerhalb von Sekunden — Cloudflare propagiert die Änderung zu allen Edge-Nodes
4. Deine App übernimmt Änderungen beim nächsten Translation-Fetch — kein erneutes Deployment nötig

Für granulare Kontrolle verwende cdn.merge statt des vollständigen Uploads, um nur die geänderten Keys zu aktualisieren. Kombiniere dies mit cdn.mergePreview in deiner CI-Pipeline, um CDN-Deployments hinter einem Review-Schritt zu sichern.

Framework-Integration

Web: Next.js, TanStack Start, Vite

Die Web-SDKs (@better-i18n/next, @better-i18n/use-intl) verwalten das CDN-Fetching automatisch basierend auf deiner i18n.config.ts:

// i18n.config.ts
export const project = "acme/web-app";
export const defaultLocale = "en";

Das SDK löst die CDN-URL aus deinem Projektbezeichner auf und lädt zur Laufzeit die richtigen Namespace-Locale-Dateien.

Mobile: Expo / React Native

@better-i18n/expo ergänzt CDN Delivery um Offline-First-Caching:

import { initBetterI18n, storageAdapter } from '@better-i18n/expo';
import { MMKV } from 'react-native-mmkv';

const mmkv = new MMKV({ id: 'translations' });

await initBetterI18n({
  project: 'acme/mobile-app',
  i18n,
  defaultLocale: 'en',
  storage: storageAdapter(mmkv),
});

Network-First-Strategie:

1. Vom CDN laden (neueste Übersetzungen abrufen)
2. Fallback auf persistenten Cache (MMKV oder AsyncStorage)
3. Fallback auf gebündelte statische Daten (optional)

Sobald ein Nutzer die App mit Netzwerkverbindung öffnet, werden Übersetzungen lokal gecacht. Die App funktioniert danach vollständig offline.

Jeder HTTP-Client

Das CDN ist ein einfacher HTTPS-Endpunkt — kein SDK erforderlich:

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

{
  "welcome": "Welcome to our app",
  "nav.home": "Home",
  "nav.settings": "Settings"
}

Nutzbar aus jeder Sprache oder Plattform: Swift, Kotlin, Go, Python, Ruby — alles, was HTTP-Requests absetzen kann.

Infrastruktur

• Cloudflare Workers — Edge-Computing an 300+ Standorten weltweit
• Cloudflare R2 — Object-Storage ohne Egress-Gebühren für Translation-Dateien
• Automatische Propagation — Änderungen erreichen alle Edge-Nodes innerhalb von Sekunden
• DDoS-Schutz — Im Netzwerk von Cloudflare integriert
• TLS 1.3 — Alle CDN-Requests sind verschlüsselt
• Keine Egress-Kosten — R2 eliminiert Bandbreitengebühren unabhängig vom Traffic-Volumen

Namespace-Organisation

Organisiere Übersetzungen in Namespaces, um zu steuern, was geladen wird:

acme/web-app/
├── en/
│   ├── common.json      → Gemeinsame UI-Strings
│   ├── auth.json        → Login, Registrierung, Passwort zurücksetzen
│   ├── dashboard.json   → Dashboard-spezifische Strings
│   └── marketing.json   → Landing-Page-Texte
├── tr/
│   ├── common.json
│   ├── auth.json
│   └── ...
└── manifest.json        → Projekt-Sprachkonfiguration

Deine App lädt nur die Namespaces, die für die aktuelle Seite oder das Feature benötigt werden. Eine Login-Seite lädt auth.json; das Dashboard lädt dashboard.json. Dies hält Bundle-Größen klein und Seitenladezeiten schnell.

Verwende cdn.detectDuplicates regelmäßig, um Keys zu identifizieren, die in mehreren Namespaces mit identischen Werten vorkommen — und konsolidiere sie dann mit cdn.cleanupDuplicates in common.json.

Veröffentlichungssteuerung

Das CDN stellt nur veröffentlichte Übersetzungen bereit. Nutze die Publish-Pipeline, um zu steuern, was live geht:

1. getPendingChanges — Vorschau auf das, was im CDN deployed wird
2. publishTranslations — Änderungen deployen (alle oder bestimmte Übersetzungen)
3. cdn.mergePreview — Key-Level-Merge-Ergebnisse vor der Anwendung prüfen
4. cdn.merge — Inkrementelle Key-Updates ohne vollständigen Datei-Ersatz anwenden
5. getSyncs / getSync — Deployment-Status verfolgen

Dies ermöglicht einen gestuften Workflow: ausstehende Änderungen prüfen, Merge-Ergebnisse verifizieren, veröffentlichen und Deployment überwachen — alles ohne Änderungen am Anwendungscode.

Erste Schritte

1. Erstelle dein Projekt unter dash.better-i18n.com
2. CDN initialisieren mit cdn.setup, um R2-Storage und Edge-Routing zu konfigurieren
3. Übersetzungen hinzufügen über Dashboard, REST API oder MCP-Tools
4. Veröffentlichen, um ins CDN zu deployen
5. Integrieren mit @better-i18n/next, @better-i18n/use-intl, @better-i18n/expo oder direktem HTTP

Übersetzungen werden im CDN auf allen Plänen bereitgestellt, einschließlich des kostenlosen Tarifs.