Localisation avec React : le guide i18n complet

Commencez par une source de vérité unique pour les langues prises en charge. Stockez ensemble le code de langue, le nom affiché, le sens du texte et la relation de repli. L'analyse des routes, le sélecteur de langue, les outils de formatage Intl et le chargement des catalogues doivent tous utiliser cette configuration. Vous éviterez ainsi qu'un composant accepte fr-CA tandis qu'un autre se replie silencieusement sur fr ou l'anglais selon des règles différentes.

Les messages doivent exprimer des idées complètes. Donnez-leur des clés sémantiques stables comme checkout.payment.failed plutôt que des clés copiées de la phrase anglaise actuelle. Transmettez les variables sous forme de valeurs nommées, utilisez les placeholders de balisage de manière intentionnelle et laissez la syntaxe du message sélectionner les pluriels ou les variantes grammaticales. Vous préservez ainsi le contexte du traducteur et permettez à une autre langue de modifier l'ordre des mots sans changer le code React.

• ✓ Locale : la préférence linguistique ou régionale validée et active pour un rendu.
• ✓ Catalogue de messages : des identifiants de messages stables associés à des valeurs traduites.
• ✓ Interpolation : des valeurs d'exécution insérées dans un message traduit complet.
• ✓ Règles de pluriel et de sélection : des variantes grammaticales choisies à partir de données sensibles à la langue.
• ✓ Repli : le comportement défini lorsqu'une langue ou un message n'est pas disponible.

Cette configuration utilise react-i18next, car son modèle JSON basé sur des clés est familier à de nombreuses équipes React. La même séquence s'applique aux autres bibliothèques : définir les catalogues, initialiser une instance unique sensible à la langue, la fournir à la frontière de l'application, traduire des messages complets dans les composants et faire en sorte que le changement de langue mette à jour l'interface visible ainsi que l'URL ou la préférence persistante de l'application.

1. Étape 1

   Structurer les catalogues

   Créez un catalogue source et des fichiers de langues correspondants. Regroupez les clés par domaines produit stables, comme la navigation, le paiement et la validation. Synchronisez les jeux de clés de toutes les langues et fournissez du contexte aux traducteurs pour les messages ambigus.

2. Étape 2

   Initialiser l'instance i18n

   Créez l'instance i18next dans un module dédié, enregistrez uniquement les plugins nécessaires à l'application, définissez les langues prises en charge et de repli, et séparez les diagnostics de développement du comportement en production.

3. Étape 3

   Fournir la localisation à la racine

   Rendez l'instance initialisée disponible à la racine de l'application. Dans les frameworks avec rendu serveur, suivez l'intégration du framework afin que la langue active et les ressources restent cohérentes entre la sortie serveur et l'hydratation.

4. Étape 4

   Traduire des messages de composant complets

   Appelez useTranslation pour l'espace de noms concerné et transmettez les valeurs d'interpolation sous forme de données nommées. N'utilisez Trans que lorsqu'un message cohérent contient des éléments React, et non pour assembler des fragments arbitraires.

5. Étape 5

   Créer un sélecteur de langue accessible

   Modifiez la langue active de la bibliothèque et accédez à l'URL correspondante lorsque les routes sont localisées. Ne conservez une préférence que par commodité ; n'en faites pas l'unique source de vérité des pages publiques.

{
  "navigation": {
    "home": "Home"
  },
  "cart": {
    "items_one": "{{count}} item",
    "items_other": "{{count}} items"
  }
}

import {useTranslation} from 'react-i18next';

export function CartSummary({count}: {count: number}) {
  const {t, i18n} = useTranslation('common');

  return (
    <section>
      <h2>{t('cart.title')}</h2>
      <p>{t('cart.items', {count})}</p>
      <button onClick={() => i18n.changeLanguage('fr')}>
        {t('language.french')}
      </button>
    </section>
  );
}

Initialisez i18next avant le premier rendu visible par l'utilisateur. Dans une application uniquement côté client, affichez un état de chargement intentionnel pendant l'arrivée du catalogue actif plutôt que des clés brutes. En SSR, créez ou obtenez une instance isolée en toute sécurité pour la requête, chargez la langue résolue, effectuez le rendu avec celle-ci et sérialisez uniquement les ressources dont le client a besoin pour hydrater la même arborescence.

Un sélecteur de langue doit afficher des noms de langues lisibles, indiquer le choix actuel et préserver la route équivalente de l'utilisateur. Pour les pages publiques localisées, les liens sont préférables, car chaque langue possède une véritable URL. Un champ de sélection ou un menu peut améliorer l'interaction, mais l'accès au clavier, la gestion du focus et un chemin de navigation sans JavaScript doivent rester opérationnels.

Un catalogue pour chaque langue peut devenir l'un des fichiers les plus volumineux de l'application s'il est importé immédiatement. Divisez d'abord les catalogues par langue, puis par route ou espace de noms lorsque le produit est assez grand pour en bénéficier. Chargez le catalogue actif avant d'afficher l'interface critique, mettez en cache les ressources immuables et versionnées, et évitez de déclencher une seconde requête pour des messages que le serveur a déjà utilisés pour produire la page.

Pour le contenu public, privilégiez un framework React capable de produire du HTML localisé par génération statique ou rendu serveur. L'hydratation doit conserver la langue et les messages ayant servi à produire la sortie du serveur. Si le client redétecte la langue indépendamment, cela peut provoquer un scintillement du contenu et des incohérences d'hydratation. Transmettez la langue résolue à travers la frontière de rendu au lieu de la deviner deux fois.

Le SEO multilingue dépend de variantes faciles à découvrir. Publiez une URL stable par langue, localisez le titre et la description, émettez une URL canonique autoréférentielle et reliez les pages équivalentes avec des valeurs hreflang réciproques. Les robots des moteurs de recherche peuvent ne pas envoyer d'en-tête Accept-Language utile : ne faites donc jamais de la détection du navigateur le seul moyen d'accéder aux traductions. Un sélecteur de langue visible et composé de liens aide à la fois les visiteurs et les robots.

• ✓ Ne chargez que la langue active et les espaces de noms nécessaires à la route.
• ✓ Effectuez le rendu de la langue sélectionnée sur le serveur ou à la compilation pour les pages publiques.
• ✓ Préchargez les messages critiques afin d'éviter un affichage fugace des clés ou de la langue de repli.
• ✓ Donnez à chaque page localisée une URL et une URL canonique distinctes, ainsi que des liens hreflang réciproques.
• ✓ Présentez le sélecteur de langue sous forme de liens ordinaires et préservez la route équivalente.

La bibliothèque React gère les besoins à l'exécution : sélection des messages, interpolation des valeurs et mise à jour des composants. Une plateforme de localisation prend en charge le processus autour de ces messages : maintien de la parité des clés, invitation des réviseurs, traduction à grande échelle, enregistrement des modifications et intégration des catalogues approuvés dans l'application. La séparation de ces responsabilités protège la couche des composants contre la dépendance envers un fournisseur.

Translatable fonctionne avec les catalogues JSON et les processus des développeurs. Importez les fichiers de langues existants, gérez les valeurs dans une interface dédiée, utilisez l'aide de l'IA pour les brouillons ou les traductions en masse, synchronisez les changements via des fournisseurs Git et, si vous le souhaitez, diffusez les mises à jour des catalogues par un CDN. React reste connecté au moyen de la bibliothèque i18n déjà choisie par l'équipe.

Adoptez progressivement l'automatisation du processus. Une petite équipe peut commencer par des exports versionnés et réviser chaque changement dans une pull request. À mesure que le rythme des publications s'accélère, ajoutez la synchronisation automatique ou la diffusion par CDN tout en conservant la validation et une solution de repli intégrée. Vous accélérerez ainsi les itérations sur les textes sans faire dépendre le rendu de l'application d'un tiers indisponible.