CDN Delivery : Traductions en Cache Edge avec better-i18n

Chaque traduction que vous publiez dans better-i18n est déployée sur le réseau edge mondial de Cloudflare. Votre application récupère les traductions depuis le nœud edge le plus proche — aucun aller-retour vers le serveur d'origine, aucun redéploiement de l'application requis pour mettre à jour les traductions.

Structure des URL CDN

Les traductions suivent un schéma d'URL prévisible basé sur votre organisation, projet, locale et namespace :

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

Exemples :

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

# Namespace auth en turc
https://cdn.better-i18n.com/acme/web-app/tr/auth.json

# Namespace navigation en français
https://cdn.better-i18n.com/acme/web-app/fr/nav.json

Chaque combinaison namespace-locale est un fichier JSON distinct, de sorte que votre application ne charge que les traductions dont elle a besoin. Cette structure d'URL est stable et mise en cache — les nœuds edge CDN, les caches navigateur et les service workers peuvent tous en tirer parti.

Manifeste de projet

Le CDN sert également un fichier manifest contenant la configuration des langues de votre projet :

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

Retourne le tableau languages avec toutes les locales de votre projet. Le SDK Expo l'utilise pour découvrir automatiquement les langues disponibles à l'exécution.

Opérations CDN

better-i18n fournit un ensemble complet d'opérations de gestion CDN via la CLI, l'API REST et les outils MCP.

Configuration et suppression

Opération	Description
`cdn.setup`	Initialise la livraison CDN pour votre projet. Crée la structure de bucket R2 et configure le routage edge.
`cdn.uninstall`	Supprime la livraison CDN. Nettoie le stockage R2 et la configuration edge.

Opérations d'import

Import unitaire (`cdn.upload`)

Importez un fichier namespace-locale unique vers le CDN :

# Importer les traductions common en anglais
better-i18n cdn upload --locale en --namespace common

Cette commande écrit le fichier dans R2 et invalide le cache edge pour ce chemin spécifique. Les modifications se propagent à tous les 300+ nœuds edge en quelques secondes.

Import en lot (`cdn.uploadBatch`)

Importez plusieurs combinaisons namespace-locale en une seule opération :

# Importer tous les namespaces pour l'anglais et le turc
better-i18n cdn upload-batch --locales en,tr --namespaces common,auth,dashboard

L'import en lot est nettement plus rapide que les imports individuels pour la publication de plusieurs fichiers. Il regroupe les écritures R2 et les invalidations de cache, réduisant le temps de propagation total.

Opérations de fusion

La fusion vous permet de mettre à jour des clés spécifiques dans un fichier CDN existant sans remplacer l'intégralité du fichier. C'est essentiel pour les mises à jour de traductions incrémentielles.

Fusion (`cdn.merge`)

# Fusionner les clés mises à jour dans le namespace common en anglais
better-i18n cdn merge --locale en --namespace common --keys "welcome,nav.home"

La fusion lit le fichier existant depuis R2, applique les modifications au niveau des clés, puis réécrit le résultat. Les clés non incluses dans la fusion restent inchangées. Cela évite les écrasements accidentels lorsque plusieurs membres de l'équipe ou pipelines d'automatisation publient simultanément.

Prévisualisation de fusion (`cdn.mergePreview`)

Prévisualisez le résultat d'une opération de fusion avant de l'exécuter :

# Prévisualiser le résultat de la fusion sans l'appliquer
better-i18n cdn merge-preview --locale en --namespace common --keys "welcome"

Retourne un diff montrant les clés ajoutées, mises à jour et inchangées. Utilisez cette option dans les pipelines CI ou les workflows de révision pour vérifier les modifications avant leur mise en production.

Gestion des fichiers

Opération	Description
`cdn.listFiles`	Liste tous les fichiers actuellement déployés sur le CDN pour votre projet. Retourne la locale, le namespace, la taille et l'horodatage de dernière modification pour chaque fichier.
`cdn.deleteFile`	Supprime un fichier namespace-locale spécifique du CDN. À utiliser lors de la dépréciation d'un namespace ou de la suppression d'une locale.

Détection et nettoyage des doublons

Les projets de traduction accumulent des doublons au fil du temps — notamment lorsque les namespaces sont réorganisés ou que des clés sont déplacées entre namespaces.

Détecter les doublons (`cdn.detectDuplicates`)

Analyse tous les fichiers CDN de votre projet et identifie les valeurs de traduction en double à travers les namespaces :

better-i18n cdn detect-duplicates

Retourne un rapport montrant quelles clés partagent des valeurs identiques dans différents namespaces. Cela vous aide à consolider les traductions dans des namespaces partagés et à réduire la taille totale du payload CDN.

Nettoyer les doublons (`cdn.cleanupDuplicates`)

Résolvez automatiquement les doublons détectés selon vos préférences de consolidation :

# Déplacer les doublons vers le namespace common
better-i18n cdn cleanup-duplicates --target-namespace common

C'est une opération destructive — exécutez toujours cdn.detectDuplicates en premier pour examiner ce qui va changer, et utilisez cdn.mergePreview pour vérifier le résultat dans le namespace cible.

Comment fonctionnent les mises à jour

Modifiez les traductions dans le dashboard, via l'API REST ou les outils MCP
Publiez avec publishTranslations — cela déclenche un job de synchronisation cdn_upload
Le CDN se met à jour en quelques secondes — Cloudflare propage la modification vers tous les nœuds edge
Votre application récupère les modifications lors du prochain fetch de traductions — aucun redéploiement requis

Pour un contrôle granulaire, utilisez cdn.merge plutôt qu'un import complet pour ne mettre à jour que les clés modifiées. Combinez avec cdn.mergePreview dans votre pipeline CI pour conditionner les déploiements CDN à une étape de révision.

Intégration avec les frameworks

Web : Next.js, TanStack Start, Vite

Les SDK web (@better-i18n/next, @better-i18n/use-intl) gèrent automatiquement le fetch CDN en fonction de votre i18n.config.ts :

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

Le SDK résout l'URL CDN à partir de votre identifiant de projet et récupère les bons fichiers namespace-locale à l'exécution.

Mobile : Expo / React Native

@better-i18n/expo ajoute un cache offline-first par-dessus la livraison CDN :

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),
});

Stratégie network-first :

Fetch depuis le CDN (obtenir les traductions les plus récentes)
Repli sur le cache persistant (MMKV ou AsyncStorage)
Repli sur les données statiques embarquées (optionnel)

Une fois qu'un utilisateur ouvre l'application avec une connexion réseau, les traductions sont mises en cache localement. L'application fonctionne entièrement hors ligne à partir de ce moment.

Tout client HTTP

Le CDN est un endpoint HTTPS standard — aucun SDK requis :

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

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

Utilisez-le depuis n'importe quel langage ou plateforme : Swift, Kotlin, Go, Python, Ruby — tout ce qui peut effectuer une requête HTTP.

Infrastructure

Cloudflare Workers — Edge computing réparti sur 300+ emplacements dans le monde
Cloudflare R2 — Stockage objet sans frais d'egress pour les fichiers de traduction
Propagation automatique — Les modifications atteignent tous les nœuds edge en quelques secondes
Protection DDoS — Intégrée au réseau Cloudflare
TLS 1.3 — Toutes les requêtes CDN sont chiffrées
Zéro coût d'egress — R2 élimine les frais de bande passante, quel que soit le volume de trafic

Organisation par namespaces

Organisez les traductions en namespaces pour contrôler ce qui est chargé :

acme/web-app/
├── en/
│   ├── common.json      → Chaînes UI partagées
│   ├── auth.json        → Connexion, inscription, réinitialisation du mot de passe
│   ├── dashboard.json   → Chaînes spécifiques au dashboard
│   └── marketing.json   → Contenu de la landing page
├── tr/
│   ├── common.json
│   ├── auth.json
│   └── ...
└── manifest.json        → Configuration des langues du projet

Votre application ne charge que les namespaces dont elle a besoin pour la page ou fonctionnalité en cours. Une page de connexion charge auth.json ; le dashboard charge dashboard.json. Cela maintient une taille de bundle réduite et des chargements de page rapides.

Utilisez cdn.detectDuplicates régulièrement pour identifier les clés présentes dans plusieurs namespaces avec des valeurs identiques — puis consolidez-les dans common.json avec cdn.cleanupDuplicates.

Contrôles de publication

Le CDN ne sert que les traductions publiées. Utilisez le pipeline de publication pour contrôler ce qui est mis en ligne :

getPendingChanges — Prévisualisez ce qui sera déployé sur le CDN
publishTranslations — Déployez les modifications (toutes ou spécifiques)
cdn.mergePreview — Prévisualisez les résultats de fusion au niveau des clés avant application
cdn.merge — Appliquez des mises à jour de clés incrémentielles sans remplacement complet du fichier
getSyncs / getSync — Suivez l'état du déploiement

Cela vous offre un workflow par étapes : prévisualisez les modifications en attente, vérifiez les résultats de fusion, publiez et surveillez le déploiement — sans toucher au code de l'application.

Démarrage

Créez votre projet sur dash.better-i18n.com
Initialisez le CDN avec cdn.setup pour configurer le stockage R2 et le routage edge
Ajoutez des traductions via le dashboard, l'API REST ou les outils MCP
Publiez pour déployer sur le CDN
Intégrez avec @better-i18n/next, @better-i18n/use-intl, @better-i18n/expo, ou directement via HTTP

Les traductions sont servies depuis le CDN sur tous les plans, y compris le niveau gratuit.

CDN Delivery : Traductions en Cache Edge avec better-i18n