Mes traductions n'apparaissent pas — que dois-je vérifier ?

Si votre application affiche des clés brutes (comme common.welcome_title) au lieu du texte traduit, ou si des traductions sont manquantes pour certaines langues, suivez cette liste de contrôle.

Étape 1 : Les traductions sont-elles publiées ?

La cause la plus fréquente est des traductions non publiées. Vérifiez votre tableau de bord :

1. Accédez à votre projet
2. Recherchez l'indicateur "Modifications en brouillon"
3. S'il y a des modifications non publiées, cliquez sur "Publier"

Seules les traductions publiées sont disponibles sur le CDN. Les traductions en brouillon ne sont visibles que dans le tableau de bord.

Étape 2 : Vérifier le CDN directement

Vérifiez que les traductions sont sur le CDN en les récupérant directement :

# Vérifier le manifest (liste des locales disponibles)
curl https://cdn.better-i18n.com/your-org/your-project/manifest.json

# Vérifier les traductions pour une locale spécifique
curl https://cdn.better-i18n.com/your-org/your-project/en/translations.json

Si le manifest retourne un objet vide ou { "fallback": true }, vos traductions n'ont pas encore été publiées.

Étape 3 : Vérifier la configuration du projet

Assurez-vous que votre configuration SDK correspond à votre projet :

// Vérifiez l'identifiant du projet
const i18n = createI18n({
  project: 'acme/dashboard', // Doit correspondre exactement : org/project
  defaultLocale: 'en',       // Doit correspondre à votre locale source
});

Erreurs courantes :

• Mauvais format org/project (sensible à la casse)
• defaultLocale ne correspondant pas à la langue source dans le tableau de bord
• Utilisation d'une clé secrète là où une clé publique est requise (ou vice versa)

Étape 4 : Vérifier la normalisation des locales

Le CDN utilise des codes de locale BCP 47 en minuscules. Si votre application utilise pt-BR mais que le CDN attend pt-br, les traductions ne correspondront pas.

Le SDK gère cela automatiquement via normalizeLocale(), mais si vous construisez des URLs manuellement, veillez à les mettre en minuscules.

Étape 5 : Vérifier la console du navigateur

Ouvrez DevTools et cherchez :

• Onglet Network — y a-t-il une requête vers cdn.better-i18n.com ? Quelle est la réponse ?
• Erreurs de console — des erreurs comme BETTER_I18N_PROJECT is not configured ?
• Corps de la réponse — le JSON des traductions contient-il vos clés ?

Étape 6 : Délai de mise en cache

Après publication, il y a une brève fenêtre pendant laquelle les caches peuvent servir des données obsolètes :

Couche de cache	Durée maximale obsolète
CDN edge	Vidé immédiatement lors de la publication
SDK en mémoire (TtlCache)	Jusqu'à 60 secondes
Next.js ISR	Jusqu'à 30 secondes (par défaut)
Cache HTTP du navigateur	Jusqu'à 60 secondes

Attendez 60 secondes après la publication et faites un rechargement forcé (Cmd+Shift+R).

Étape 7 : Vérifier la correspondance des namespaces

Si vous utilisez des namespaces, assurez-vous qu'ils correspondent entre votre code et le tableau de bord :

// Le code utilise le namespace 'common'
const t = useTranslations('common');

// Le tableau de bord doit avoir des clés sous le namespace 'common'
// common.welcome_title → "Bienvenue !"

Si vos clés sont dans le namespace par défaut mais que votre code en demande un spécifique (ou vice versa), les traductions ne se résoudront pas.

Toujours bloqué ?

Exécutez la commande doctor du CLI :

better-i18n doctor

Cela vérifie la configuration, l'authentification, la connectivité API et les problèmes courants de configuration.

Étapes suivantes

• Publié mais l'application affiche toujours les anciennes traductions
• Erreurs de doctor CLI