CDN Translation Delivery : Guide de performance i18n avec Edge Cache

CDN Translation Delivery : Guide de performance i18n avec Edge Cache

La livraison de traductions est un problème de performance qui se cache à la vue de tous. Votre application peut avoir des temps de chargement inférieurs à une seconde, des images optimisées et des bundles avec code-splitting — mais si les traductions arrivent en retard, les utilisateurs voient des décalages de mise en page, des spinners de chargement, ou pire, des clés non traduites qui clignotent à l'écran.

Ce guide explique comment better-i18n résout la livraison de traductions grâce à Cloudflare R2 et l'edge caching, et parcourt l'ensemble des opérations CDN disponibles pour les équipes d'ingénierie.

Pourquoi la livraison de traductions est importante pour la performance i18n

Les configurations i18n traditionnelles intègrent les traductions dans l'application. Chaque fois que vous corrigez une faute de frappe ou ajoutez une nouvelle langue, vous avez besoin d'un rebuild complet et d'un nouveau deploy. Pour les applications mobiles, cela signifie attendre la validation de l'App Store. Pour les applications web, cela signifie un pipeline de deploy qui bloque une modification non technique.

CDN Translation Delivery découple le contenu des traductions du code de l'application. Les traductions résident sur l'edge et sont servies depuis le nœud Cloudflare le plus proche de l'utilisateur. Votre application les récupère à l'exécution via HTTP.

Les caractéristiques de performance :

• Livraison en moins de 50ms depuis le nœud edge le plus proche (300+ emplacements dans le monde)
• Zéro aller-retour vers l'origine pour les traductions en cache
• Mises à jour incrémentielles sans redéploiement de l'application
• Chargement parallèle uniquement des namespaces nécessaires à la page actuelle

La structure d'URL qui rend tout cela possible

Chaque fichier de traduction dans better-i18n suit un modèle d'URL déterministe :

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

Cette structure est intentionnellement simple et prévisible. Cela signifie :

1. Les caches navigateur fonctionnent nativement — chaque paire locale-namespace possède une URL unique et stable
2. Les service workers peuvent précacher les chemins connus sans requêtes de découverte
3. Les nœuds edge du CDN cachent indépendamment par chemin, donc un cache miss pour fr/auth.json n'affecte pas en/common.json
4. N'importe quel client HTTP peut le consommer — pas de SDK, pas d'authentification, pas d'en-têtes spéciaux

Quelques exemples concrets :

# 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

Chaque projet dispose également d'un manifest à /{org}/{project}/manifest.json listant tous les locales disponibles. Les SDKs mobiles l'utilisent pour découvrir automatiquement les langues à l'exécution sans coder en dur les listes de locales.

Upload vs. Merge : Deux modèles pour les mises à jour CDN

better-i18n propose deux approches distinctes pour mettre à jour les traductions sur le CDN.

Upload complet (cdn.upload et cdn.uploadBatch)

Upload remplace l'intégralité du fichier namespace-locale sur 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

Le batch upload est le bon choix quand :

• On publie une nouvelle langue pour la première fois
• On reconstruit les fichiers CDN après une restructuration majeure
• On déploie un export complet de traductions depuis votre TMS

Les opérations en batch sont optimisées en interne — les écritures R2 et les invalidations de cache sont regroupées, réduisant le temps de propagation total par rapport aux uploads individuels séquentiels.

Merge incrémentiel (cdn.merge)

Merge lit le fichier existant sur R2, applique des modifications au niveau des clés, et écrit le résultat en retour :

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

Les clés non incluses dans le merge restent inchangées. C'est l'option la plus sûre pour les mises à jour incrémentielles car :

• Pas d'écrasements accidentels — les autres clés du fichier sont préservées
• Sécurité en concurrence — plusieurs membres de l'équipe ou pipelines CI peuvent merger différentes clés sans conflit
• Surface de modification réduite — seules les clés spécifiées sont touchées

Aperçu du Merge (cdn.mergePreview)

Avant d'exécuter un merge, prévisualiser le résultat :

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

Ceci retourne un diff montrant quelles clés seraient ajoutées, mises à jour ou laissées inchangées. Utilisez l'aperçu du merge dans les pipelines CI pour soumettre les déploiements CDN à une étape de validation — de la même façon que vous valideriez une migration de base de données avant de l'appliquer.

Détection des doublons : Garder le payload CDN léger

À mesure que les projets de traduction grandissent, les doublons s'accumulent. Une chaîne pour le bouton « Enregistrer » peut exister dans common.json, settings.json et profile.json avec des valeurs identiques dans les trois. Chaque doublon augmente le payload total du CDN et crée une surcharge de maintenance — on en met un à jour, on oublie les autres.

Détecter les doublons (cdn.detectDuplicates)

better-i18n cdn detect-duplicates

Ceci scanne tous les fichiers CDN de votre projet et produit un rapport des clés partageant des valeurs de traduction identiques entre namespaces. Le rapport indique :

• Quelles clés sont dupliquées
• Dans quels namespaces elles se trouvent
• La valeur partagée

Nettoyage (cdn.cleanupDuplicates)

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

Ceci consolide les doublons dans un namespace cible (typiquement common) et les supprime des namespaces sources. L'opération utilise merge en interne, elle est donc sûre pour les accès concurrents.

Bonne pratique : Exécutez cdn.detectDuplicates après chaque import majeur de traductions ou réorganisation de namespaces. Planifiez des nettoyages périodiques pour garder les payloads CDN minimaux.

Gestion du cycle de vie CDN

Setup (cdn.setup)

Initialiser la livraison CDN pour votre projet :

better-i18n cdn setup

Ceci crée la structure du bucket R2, configure l'edge routing du Cloudflare Worker et établit les règles de cache. À exécuter une seule fois lors de la première activation de la livraison CDN pour un projet.

Gestion des fichiers

Lister tous les fichiers déployés pour auditer l'état du CDN :

better-i18n cdn list-files

Retourne le locale, le namespace, la taille et le timestamp de dernière modification de chaque fichier. Utile pour vérifier les déploiements et identifier les fichiers obsolètes.

Supprimer des fichiers individuels lors de la dépréciation d'un namespace ou de la suppression d'un locale :

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

Teardown (cdn.uninstall)

Supprimer entièrement la livraison CDN :

better-i18n cdn uninstall

Nettoie le stockage R2, la configuration edge et les règles de cache. À utiliser lors de la migration d'un projet ou de la mise hors service d'une application.

Performance en pratique

Voici à quoi ressemble la livraison CDN de traductions en production :

L'aspect zéro coût d'egress mérite d'être souligné. Les configurations CDN traditionnelles facturent par Go de bande passante. Avec R2, vos coûts de livraison de traductions sont fixes quel que soit le volume de trafic. Un projet servant 10 millions de fetches de traductions par mois paie la même chose qu'un projet avec 1 000.

Code splitting par namespace pour les traductions

Le modèle de namespace agit comme du code splitting pour les traductions. Au lieu de charger toutes les traductions d'emblée :

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

Votre application charge uniquement ce dont la route actuelle a besoin :

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

Cela réduit le chargement initial de la page de plus de 90% pour les applications avec de grands ensembles de traductions. Combiné avec l'edge caching, les navigations suivantes ne récupèrent que le nouveau namespace — dashboard.json est chargé quand l'utilisateur navigue vers le dashboard, pas avant.

Approches d'intégration

Intégration SDK (Recommandé)

Les SDKs officiels gèrent automatiquement le fetching CDN, le caching et le fallback :

• @better-i18n/next — Fetching côté serveur avec support ISR/SSG
• @better-i18n/use-intl — Fetching côté client pour TanStack Router et les apps Vite
• @better-i18n/expo — Offline-first avec caching MMKV/AsyncStorage

Chaque SDK résout l'URL du CDN depuis l'identifiant de projet dans votre i18n.config.ts. Aucune construction d'URL manuelle n'est nécessaire.

HTTP direct (N'importe quelle plateforme)

Le CDN est un simple endpoint HTTPS. Pas d'authentification, pas d'en-têtes spéciaux :

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

Cela rend les traductions better-i18n consommables depuis n'importe quelle plateforme : iOS (Swift), Android (Kotlin), services backend (Go, Python, Ruby), moteurs de jeux, appareils IoT — tout ce qui peut effectuer une requête HTTP GET.

Le pipeline Publish-to-CDN

Le workflow complet de l'édition d'une traduction jusqu'à sa diffusion mondiale :

1. Éditer — Dashboard, REST API ou outils MCP
2. Prévisualiser les changements en attente — getPendingChanges montre ce qui sera déployé
3. Prévisualiser le résultat du merge — cdn.mergePreview affiche le diff au niveau des clés (optionnel)
4. Publier — publishTranslations déclenche le job de sync cdn_upload
5. Surveiller — getSyncs / getSync suit l'état du déploiement
6. Vérifier — cdn.listFiles confirme que le fichier mis à jour est en ligne

Cela donne aux équipes d'ingénierie la même rigueur pour les déploiements de traductions que pour les déploiements de code : prévisualiser, publier, surveiller, vérifier.

Pour commencer

1. Créez votre projet sur dash.better-i18n.com
2. Exécutez cdn.setup pour initialiser le stockage R2 et l'edge routing
3. Ajoutez des traductions et publiez-les sur le CDN
4. Intégrez avec le SDK de votre framework ou utilisez HTTP direct
5. Surveillez avec cdn.listFiles et cdn.detectDuplicates

La livraison CDN est disponible sur tous les plans, y compris le plan gratuit. Vos traductions sont mises en cache sur l'edge dès le premier jour.