Better i18n/Centre d’aide

Questions fréquentes

Trouvez les réponses aux questions fréquentes

Premiers pas

Dois-je reconstruire mon application après avoir publié des traductions ?

Non. Better i18n délivre les traductions via un CDN mondial au moment de l'exécution. Lorsque vous publiez, les traductions sont disponibles dans votre application en ~60 secondes sans aucune reconstruction ni redéploiement. Votre SDK récupère automatiquement les nouvelles traductions.

Que se passe-t-il si le CDN est hors ligne ?

Le CDN est conçu pour toujours retourner HTTP 200 — même lors d'erreurs, votre application reçoit {} ou { "fallback": true } au lieu d'un échec.

Le SDK dispose d'une chaîne de repli à 5 couches :

  1. Cache en mémoire (TtlCache, TTL 60s)
  2. Récupération CDN (avec délai d'expiration + réessai)
  3. Stockage persistant (si configuré — ex. AsyncStorage sur mobile)
  4. Données de repli statiques (traductions groupées que vous fournissez)
  5. Erreur (uniquement si toutes les couches échouent)

En pratique, les utilisateurs ne voient presque jamais d'échec car les données en cache ou statiques sont toujours disponibles.

Y a-t-il un plan gratuit ?

Oui ! Better i18n propose un niveau gratuit qui inclut :

  • 1 projet
  • Clés de traduction illimitées
  • Crédits de traduction IA
  • Livraison CDN
  • Accès CLI

Les plans payants ajoutent plus de projets, de membres d'équipe, des fonctionnalités avancées et des limites d'utilisation plus élevées. Consultez la page de tarification pour les détails actuels.

Better i18n prend-il en charge les langues RTL ?

Better i18n est une plateforme de livraison de chaînes — elle stocke et livre les chaînes de traduction quelle que soit la direction du texte. Les langues RTL comme l'arabe, l'hébreu et le persan sont entièrement prises en charge comme cibles de traduction.

Cependant, la mise en page et le CSS RTL (ex. direction: rtl, interface miroir) relèvent de la responsabilité de votre application. Le SDK livre les chaînes traduites correctes ; votre framework CSS gère la direction visuelle.

Gérer les traductions

Combien de temps prend la traduction par IA ?

La vitesse de traduction IA dépend du volume :

Clés Temps approximatif
1–50 Quelques secondes
50–500 Moins d'1 minute
500–1000 1–3 minutes
1000+ 3–5 minutes

La traduction s'exécute en lots parallèles, ce qui lui permet de bien évoluer. Vous pouvez continuer à travailler dans le tableau de bord pendant que la traduction est en cours.

Puis-je utiliser des traducteurs humains plutôt que l'IA ?

Absolument. Vous pouvez :

  • Inviter des traducteurs avec le rôle Translator — ils accèdent à une interface de traduction dédiée
  • Utiliser la file de révision — les traducteurs peuvent réviser, modifier et approuver les traductions
  • Combiner IA + humain — utiliser l'IA pour la première passe, puis des traducteurs humains pour réviser et affiner

Le rôle Translator n'a accès qu'à la modification des traductions, pas aux paramètres du projet ni à la gestion des clés.

Qu'est-ce qu'un namespace ?

Un namespace est un regroupement logique de clés de traduction. Par exemple :

  • common — chaînes partagées comme "Enregistrer", "Annuler", "Chargement"
  • auth — chaînes liées à la connexion/inscription
  • dashboard — chaînes spécifiques au tableau de bord

Les namespaces permettent le chargement différé — votre application ne récupère que les traductions dont elle a besoin pour la page actuelle. Ils aident aussi à organiser les clés et à réduire les conflits dans les grands projets.

Dans le code, vous référencez les namespaces ainsi : t('common:save_button') ou useTranslations('common').

Les traductions peuvent-elles être annulées ?

Oui. Chaque publication crée un instantané de vos traductions. Si quelque chose ne va pas :

  1. Allez dans l'Historique de publication de votre projet
  2. Trouvez la bonne publication précédente
  3. Cliquez sur Annuler

Cela restaure le CDN à l'instantané sélectionné. Votre application servira les traductions restaurées en ~60 secondes.

Intégration développeur

Dois-je utiliser un singleton ou plusieurs instances du SDK ?

Utilisez toujours un singleton — créez une instance SDK au niveau du module et réutilisez-la partout.

Le TtlCache du SDK est un global au niveau du module partagé entre toutes les instances createI18nCore() dans le même processus. Créer plusieurs instances est inutile mais pas nuisible — elles partageront le même cache.

// ✅ Bien — singleton au niveau du module
export const i18n = createI18n({ project: 'acme/dashboard', ... });

// ❌ À éviter — créer dans un composant/handler
function handler() {
  const i18n = createI18n({ ... }); // Nouvelle instance par requête
}
Quel est le format org/project ?

L'identifiant de projet utilise le format org/project, comme acme/dashboard. Cela correspond directement à l'URL CDN :

https://cdn.better-i18n.com/acme/dashboard/manifest.json
https://cdn.better-i18n.com/acme/dashboard/en/translations.json
  • org — votre slug d'organisation (défini lors de l'inscription)
  • project — le slug du projet (défini lors de la création d'un projet)

Ce format est utilisé partout : configuration du SDK, configuration CLI, appels API et URLs CDN. Il est sensible à la casse.

Le SDK fonctionne-t-il sur les runtimes edge ?

Oui. Le SDK n'utilise que l'API Fetch standard — aucun module Node.js intégré (fs, path, crypto, etc.) n'est requis. Cela signifie qu'il fonctionne sur :

  • Cloudflare Workers
  • Vercel Edge Functions
  • Deno Deploy
  • Bun
  • Tout runtime compatible avec les standards Web

La seule exigence est une fonction fetch globale. Vous pouvez aussi passer un fetch personnalisé via l'option de configuration fetch si nécessaire.

Quelle est la différence entre la CLI et le SDK ?

Ils servent des objectifs différents :

CLI (@better-i18n/cli) SDK (@better-i18n/next, etc.)
Quand Temps de développement Runtime
Objectif Scanner le code, synchroniser les clés, vérifier l'état Récupérer et afficher les traductions
Exécute sur Votre machine / CI Votre application (navigateur, serveur, mobile)
Auth Clé secrète (sk_...) Clé publique ou aucune
Installation Global ou devDependency Dependency

La CLI gère vos clés de traduction. Le SDK les livre aux utilisateurs.

Dépannage et problèmes courants

Comment vérifier si le CDN est en bonne santé ?

Récupérez directement vos traductions pour vérifier la santé du CDN :

# Vérifier le manifeste
curl -w '\nHTTP %{http_code} | Time: %{time_total}s\n' \
  https://cdn.better-i18n.com/your-org/your-project/manifest.json

# Vérifier les traductions
curl -w '\nHTTP %{http_code} | Time: %{time_total}s\n' \
  https://cdn.better-i18n.com/your-org/your-project/en/translations.json

Le CDN renvoie toujours HTTP 200. Vérifiez le corps de la réponse :

  • JSON valide avec vos traductions → CDN en bonne santé
  • {} ou { "fallback": true } → traductions pas encore publiées
  • Temps de réponse > 1s → problème réseau possible (typiquement <100ms)
Pourquoi mon application affiche la langue de repli au lieu de la langue de l'utilisateur ?

Quatre causes courantes :

  1. Locale non publiée — vérifiez si des traductions existent pour cette langue dans le tableau de bord et sont publiées
  2. Désaccord de normalisation de locale — le CDN utilise le BCP 47 en minuscules (pt-br), mais votre application pourrait envoyer pt-BR. Utilisez normalizeLocale() depuis @better-i18n/core
  3. Middleware ne détecte pas la locale — vérifiez la configuration de votre middleware et assurez-vous que la correspondance de l'en-tête Accept-Language est configurée
  4. Locale manquante dans le manifeste — le manifeste CDN liste les locales disponibles. Si votre locale n'y est pas, le SDK revient à la locale par défaut

Vérifiez en consultant le manifeste :

curl https://cdn.better-i18n.com/your-org/your-project/manifest.json

La réponse doit lister toutes les locales publiées.

IA et automatisation

La traduction IA est-elle suffisamment précise pour la production ?

Pour la plupart des contenus, oui. La qualité de traduction IA dépend de plusieurs facteurs :

  • Contexte — les clés avec des annotations de contexte se traduisent significativement mieux
  • Glossaire — appliquer une terminologie cohérente élimine les erreurs les plus courantes
  • Type de contenu — les chaînes UI, étiquettes et courtes descriptions se traduisent très bien. Le contenu marketing et créatif peut nécessiter une révision humaine

L'approche recommandée : utiliser l'IA pour la première passe, puis faire réviser le contenu critique orienté utilisateur par des locuteurs natifs. La file de révision facilite ce flux de travail.

Quels modèles d'IA sont utilisés pour la traduction ?

Better i18n utilise une combinaison de grands modèles de langage optimisés pour la qualité de traduction. La plateforme sélectionne automatiquement le meilleur modèle en fonction du type de contenu et de la paire de langues.

Vous n'avez pas besoin de choisir ou de configurer les modèles — la plateforme s'en charge. La sélection des modèles est continuellement améliorée en fonction des métriques de qualité de traduction.

Quels agents de codage IA fonctionnent avec le serveur MCP ?

Tout agent compatible MCP fonctionne avec le serveur MCP Better i18n, notamment :

  • Claude Code (CLI) — support complet
  • Claude Desktop — support complet
  • Cursor — via les paramètres MCP
  • Windsurf — via les paramètres MCP
  • Continue — via la configuration MCP
  • Agents personnalisés — tout ce qui est construit avec le MCP SDK

Le serveur MCP expose des outils pour gérer les clés de traduction, les traductions, la publication et la gestion de contenu. L'agent appelle ces outils via des commandes en langage naturel.

Gestion de contenu

Quelle est la différence entre les clés de traduction et le Content SDK ?

Ils servent des cas d'usage différents :

Clés de traduction Content SDK
Pour Courtes chaînes UI Contenu riche structuré
Exemples Étiquettes de boutons, messages d'erreur, titres de page Articles de blog, journaux de modifications, articles d'aide
Format Paires clé-valeur Modèles de contenu avec champs typés
Édition Éditeur de traduction du tableau de bord Éditeur de contenu du tableau de bord (Markdown)
Livraison CDN via SDK API de contenu via @better-i18n/sdk

Utilisez les clés de traduction pour le texte UI. Utilisez le Content SDK pour le contenu structuré avec titre, corps, métadonnées et relations.

Y a-t-il des limites de débit sur le Content SDK ?

Oui, les limites de débit dépendent de votre niveau de plan. L'API renvoie des en-têtes de limite de débit standard :

  • X-RateLimit-Limit — requêtes autorisées par fenêtre
  • X-RateLimit-Remaining — requêtes restantes
  • X-RateLimit-Reset — quand la fenêtre se réinitialise (horodatage Unix)

Si vous dépassez la limite, l'API renvoie HTTP 429. Le SDK ne réessaie pas automatiquement en cas de limite de débit — gérez cela dans votre application si vous faites de nombreuses requêtes.

Pour la plupart des applications, les limites de débit sont suffisamment généreuses. La mise en cache côté serveur (comme utilisé dans l'application du centre d'aide) réduit encore les appels API.

Équipe et compte

Combien de projets puis-je avoir ?

Le nombre de projets dépend de votre niveau de plan :

  • Gratuit — 1 projet
  • Pro — plusieurs projets (voir la page de tarification pour la limite actuelle)
  • Entreprise — projets illimités

Chaque projet est totalement indépendant avec ses propres clés, langues, membres d'équipe et historique de publication. Consultez la page de tarification pour les détails actuels.

Les traducteurs peuvent-ils voir tous les projets de mon organisation ?

Non. Les membres de l'équipe sont assignés par projet. Un traducteur invité au "Projet A" ne peut pas voir le "Projet B" sauf s'il y est explicitement ajouté.

Cela vous permet de :

  • Inviter des traducteurs externes à des projets spécifiques sans exposer les autres
  • Assigner différents traducteurs à différents projets
  • Contrôler l'accès de manière granulaire au sein de votre organisation