Localisation React avec i18next

Créer une application React pour une audience mondiale nécessite une stratégie d'internationalisation (i18n) robuste. react-i18next est la bibliothèque de localisation React la plus populaire, construite sur le framework i18next éprouvé. Ce guide vous accompagne dans tout ce dont vous avez besoin pour localiser votre application React, de la configuration initiale à l'automatisation prête pour la production avec la traduction assistée par IA.

Pourquoi choisir react-i18next pour la localisation React ?

react-i18next est le standard de facto pour l'internationalisation React, approuvé par des milliers d'applications en production dans le monde. Voici pourquoi les développeurs le choisissent :

• API orientée hooks - Le hook useTranslation() offre une intégration React propre et idiomatique avec un re-rendu automatique lors du changement de langue.
• Écosystème riche - Des plugins pour la détection de la langue, les backends HTTP, la mise en cache et plus encore. Étendez les fonctionnalités sans réinventer la roue.
• Format de traduction JSON - Utilise des fichiers JSON standard faciles à éditer, à versionner et à intégrer avec des outils de traduction et des services d'IA.
• Support des espaces de noms - Organisez les traductions en groupes logiques (auth, tableau de bord, erreurs) pour une meilleure maintenabilité et un chargement différé.
• Prêt pour le SSR et Next.js - Fonctionne parfaitement avec le rendu côté serveur, les composants serveur React et le routeur d'application Next.js.
• Support TypeScript - Sécurité de type complète pour les clés de traduction avec autocomplétion, détectant les clés manquantes à la compilation.

Installation

Installez react-i18next et la bibliothèque principale i18next :

npm install react-i18next i18next

Plugins optionnels

Ces plugins populaires améliorent votre configuration i18next avec la détection automatique de langue et le chargement différé des traductions :

# Language detector (auto-detects user language)
npm install i18next-browser-languagedetector

# HTTP backend (load translations from server)
npm install i18next-http-backend

Structure de projet recommandée

Une structure de projet bien organisée permet de maintenir vos traductions à mesure que vous ajoutez des langues :

src/
├── i18n/
│   └── i18n.ts                  ← i18next configuration
├── locales/
│   ├── en/
│   │   └── translation.json     ← English (source)
│   ├── fr/
│   │   └── translation.json     ← French
│   ├── de/
│   │   └── translation.json     ← German
│   ├── ja/
│   │   └── translation.json     ← Japanese
│   └── es/
│       └── translation.json     ← Spanish
├── components/
├── App.tsx
└── index.tsx

Format de fichier de traduction JSON

react-i18next utilise des fichiers JSON imbriqués pour les traductions. Les clés supportent la notation par points, l'interpolation avec {{variables}} et la pluralisation intégrée :

// locales/en/translation.json
{
  "welcome": {
    "title": "Welcome to our platform",
    "greeting": "Hello, {{name}}!",
    "description": "Explore features and get started."
  },
  "nav": {
    "home": "Home",
    "dashboard": "Dashboard",
    "settings": "Settings",
    "logout": "Log out"
  },
  "cart": {
    "empty": "Your cart is empty",
    "item_one": "{{count}} item in your cart",
    "item_other": "{{count}} items in your cart",
    "checkout": "Proceed to checkout"
  }
}

• Clés imbriquées - Organisez les traductions de manière hiérarchique (ex: welcome.title, nav.home) pour une structure claire.
• Interpolation - Utilisez la syntaxe {{variableName}} pour les valeurs dynamiques insérées à l'exécution.
• Pluralisation - Ajoutez les suffixes _one et _other (ou _zero, _two, _few, _many pour les langues complexes) pour une gestion automatique du pluriel.
• Contexte - Utilisez les suffixes _male, _female pour des traductions spécifiques au genre si nécessaire.

Configuration d'i18next

i18next supporte deux approches principales pour charger les traductions : le backend HTTP (chargement différé) et les ressources groupées. Choisissez selon les besoins de votre application.

Backend HTTP (Recommandé pour les grandes applications)

Chargez les traductions à la demande depuis des fichiers JSON sur votre serveur. Cela garde votre bundle initial léger et est idéal pour les applications avec beaucoup de langues ou de gros fichiers de traduction :

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ja", "es"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false, // React already escapes by default
    },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator", "htmlTag"],
      caches: ["localStorage"],
    },
  });

export default i18n;

Ressources groupées (Approche simple)

Importez les traductions directement dans le bundle. Idéal pour les petites applications ou lorsque vous avez besoin que les traductions soient disponibles immédiatement sans requêtes réseau :

// src/i18n/i18n.ts — Bundled approach (no HTTP backend)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

import en from "../locales/en/translation.json";
import fr from "../locales/fr/translation.json";
import de from "../locales/de/translation.json";

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de"],
    defaultNS: "translation",
    interpolation: {
      escapeValue: false,
    },
    resources: {
      en: { translation: en },
      fr: { translation: fr },
      de: { translation: de },
    },
  });

export default i18n;

Initialisation dans votre application

Importez le fichier de configuration i18n dans le point d'entrée de votre application avant de rendre les composants. Cela garantit que les traductions sont chargées avant le rendu de votre interface :

// src/index.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n/i18n"; // Initialize i18next before rendering

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Traduire des composants React

react-i18next fournit deux API principales pour traduire les composants : le hook useTranslation pour un accès programmatique et le composant Trans pour le texte riche avec JSX.

Hook useTranslation

Le hook useTranslation est le moyen le plus courant d'accéder aux traductions dans les composants fonctionnels. Il fournit la fonction t() et déclenche un re-rendu automatique lors du changement de langue :

import { useTranslation } from "react-i18next";

function WelcomeBanner() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t("welcome.title")}</h1>
      <p>{t("welcome.greeting", { name: "Alice" })}</p>
      <p>{t("welcome.description")}</p>
    </div>
  );
}

Composant Trans pour le texte riche

Lorsque les traductions contiennent des éléments HTML ou JSX (gras, liens, etc.), utilisez le composant Trans. Il préserve votre arbre de composants React au sein des traductions :

import { Trans } from "react-i18next";

function RichTextExample() {
  return (
    <p>
      <Trans i18nKey="richText.welcome">
        Welcome to <strong>our platform</strong>.
        Visit your <a href="/dashboard">dashboard</a> to get started.
      </Trans>
    </p>
  );
}

// In the translation file:
// "richText.welcome": "Welcome to <1>our platform</1>. Visit your <3>dashboard</3> to get started."

Gestion de la pluralisation

i18next gère automatiquement les formes plurielles selon les règles ICU de chaque langue. Passez un paramètre count, et i18next sélectionne la forme correcte :

// In translation JSON:
// "cart.item_one": "{{count}} item in your cart"
// "cart.item_other": "{{count}} items in your cart"

import { useTranslation } from "react-i18next";

function CartSummary({ itemCount }: { itemCount: number }) {
  const { t } = useTranslation();

  return (
    <p>{t("cart.item", { count: itemCount })}</p>
  );
}

// itemCount=0 → "0 items in your cart"
// itemCount=1 → "1 item in your cart"
// itemCount=5 → "5 items in your cart"

• Ajoutez les suffixes _one et _other à vos clés de traduction pour l'anglais
• Pour les langues aux règles plurielles complexes (arabe, polonais, russe), ajoutez les suffixes _zero, _two, _few, _many si nécessaire
• i18next sélectionne automatiquement la forme correcte selon les règles plurielles CLDR de la langue cible

Organisation avec les espaces de noms

Les espaces de noms permettent de diviser les traductions en fichiers séparés par fonctionnalité ou domaine. Cela améliore la maintenabilité et permet le chargement différé des bundles de traduction :

// src/i18n/i18n.ts
i18n.init({
  defaultNS: "common",
  ns: ["common", "dashboard", "auth", "errors"],
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
  },
});

// Usage in components:
import { useTranslation } from "react-i18next";

function DashboardPage() {
  // Load specific namespace
  const { t } = useTranslation("dashboard");

  return <h1>{t("title")}</h1>;
}

function LoginForm() {
  // Load multiple namespaces
  const { t } = useTranslation(["auth", "common"]);

  return (
    <form>
      <h2>{t("auth:login.title")}</h2>
      <button>{t("common:submit")}</button>
    </form>
  );
}

Changement de langue dynamique

react-i18next rend le changement de langue fluide. Appelez i18n.changeLanguage() et tous les composants utilisant useTranslation se re-rendent automatiquement avec la nouvelle langue :

import { useTranslation } from "react-i18next";

const LANGUAGES = [
  { code: "en", label: "English" },
  { code: "fr", label: "Français" },
  { code: "de", label: "Deutsch" },
  { code: "ja", label: "日本語" },
  { code: "es", label: "Español" },
];

function LanguageSwitcher() {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <select
      value={i18n.language}
      onChange={(e) => changeLanguage(e.target.value)}
    >
      {LANGUAGES.map(({ code, label }) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

React Suspense et chargement différé

react-i18next s'intègre à React Suspense pour gérer le chargement asynchrone des traductions avec élégance. Lors de l'utilisation du backend HTTP, Suspense fournit un état de chargement propre pendant la récupération des traductions :

import { Suspense } from "react";
import { useTranslation } from "react-i18next";

// i18next supports React Suspense for async translation loading
function App() {
  return (
    <Suspense fallback={<div>Loading translations...</div>}>
      <MainContent />
    </Suspense>
  );
}

function MainContent() {
  const { t, ready } = useTranslation();

  // With Suspense, 'ready' is always true here
  return <h1>{t("welcome.title")}</h1>;
}

Clés de traduction sécurisées avec TypeScript

i18next supporte une intégration TypeScript complète. En augmentant le module i18next, vous bénéficiez de l'autocomplétion et d'une vérification à la compilation pour toutes les clés de traduction, évitant les fautes de frappe et les traductions manquantes :

// src/i18n/types.ts
import "i18next";
import translation from "../locales/en/translation.json";

declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "translation";
    resources: {
      translation: typeof translation;
    };
  }
}

// Now t() calls are fully type-safe:
// t("welcome.title")       ✅ Autocomplete works
// t("welcome.greeting")    ✅ Valid key
// t("invalid.key")         ❌ TypeScript error

Rendu côté serveur avec Next.js

Pour les applications Next.js utilisant l'App Router, vous pouvez utiliser i18next à la fois sur le serveur et le client. Créez une instance i18next séparée pour les traductions côté serveur afin d'éviter de partager l'état entre les requêtes :

// next-i18next.config.js (Next.js App Router)
// For Next.js 13+ with App Router, use next-intl or i18next directly

// src/i18n/server.ts
import { createInstance } from "i18next";
import { initReactI18next } from "react-i18next/initReactI18next";

export async function getServerTranslation(lng: string) {
  const i18nInstance = createInstance();
  await i18nInstance.use(initReactI18next).init({
    lng,
    fallbackLng: "en",
    resources: {
      [lng]: {
        translation: (await import(`../locales/${lng}/translation.json`)).default,
      },
    },
  });
  return i18nInstance;
}

// In a Server Component:
export default async function Page({ params }: { params: { lng: string } }) {
  const i18n = await getServerTranslation(params.lng);
  const t = i18n.t.bind(i18n);

  return <h1>{t("welcome.title")}</h1>;
}

• Créez une nouvelle instance i18next par requête sur le serveur pour éviter les fuites d'état entre les utilisateurs
• Utilisez les mêmes fichiers JSON de traduction pour le rendu serveur et client
• Envisagez i18next-resources-to-backend ou next-intl comme alternatives pour des configurations Next.js complexes

Accélérez la traduction avec l'IA

Configurer react-i18next n'est que la moitié du travail ; vous avez toujours besoin de traductions de haute qualité pour chaque langue cible. Traduire manuellement des dizaines de fichiers JSON est lent, coûteux et sujet aux erreurs. La traduction assistée par IA change la donne.

Pourquoi utiliser l10n.dev pour React i18next ?

l10n.dev est conçu spécifiquement pour les flux de travail de localisation des développeurs. Il comprend nativement vos fichiers de traduction JSON et produit des traductions qui semblent naturelles, et non générées par une machine :

• Support JSON natif — Téléchargez votre translation.json et récupérez des fichiers JSON parfaitement formatés et prêts à l'emploi
• IA consciente du contexte — Comprend le domaine de votre application, préservant les termes techniques et la voix de la marque dans toutes les langues
• Sécurité d'interpolation — Préserve les {{variables}}, les suffixes pluriels (_one, _other) et les structures de clés imbriquées
• Traduction par lots — Traduisez vers plus de 10 langues simultanément en quelques secondes, pas en quelques jours
• Intégration CI/CD — Automatisez les traductions dans votre pipeline de build avec le package npm ai-l10n

Flux de travail de traduction par IA

1. Rédigez votre translation.json source en anglais (ou votre langue de base)
2. Téléchargez sur l10n.dev ou exécutez la CLI ai-l10n pour traduire
3. L'IA génère des traductions contextuellement précises pour toutes les langues cibles
4. Placez les fichiers JSON traduits dans votre répertoire locales/ et déployez

Automatisez les traductions avec la CLI ai-l10n

Le package npm ai-l10n intègre la traduction par IA directement dans votre flux de travail de développement. Traduisez vos fichiers JSON depuis la ligne de commande :

# Install the l10n.dev CLI
npm install ai-l10n

# Translate your JSON files to multiple languages at once
npx ai-l10n translate src/locales/en/translation.json \
  --languages fr,de,ja,es,ko,zh-CN

Intégration au build

Ajoutez l'automatisation de la traduction à votre pipeline de build pour que les traductions soient toujours à jour :

Scripts package.json

{
  "scripts": {
    "translate": "ai-l10n translate src/locales/en/translation.json --languages fr,de,ja,es,ko --update",
    "pretranslate": "npm run translate",
    "dev": "vite",
    "build": "npm run translate && vite build"
  }
}

Makefile

LANGUAGES = fr,de,ja,es,ko,zh-CN

translate:
	npx ai-l10n translate src/locales/en/translation.json --languages $(LANGUAGES) --update

dev: translate
	npx vite

build: translate
	npx vite build

Pour plus de détails sur l'intégration CI/CD et l'automatisation, consultez notre Guide d'automatisation de la localisation

Extension VS Code pour la traduction JSON

Traduisez vos fichiers JSON React i18next directement depuis VS Code. L'extension l10n.dev vous permet de traduire des fichiers sans quitter votre éditeur :

Comment ça fonctionne

1. Installez l'extension l10n.dev depuis la Marketplace VS Code
2. Ouvrez votre fichier translation.json source
3. Faites un clic droit et sélectionnez 'Translate with l10n.dev'
4. Choisissez vos langues cibles et obtenez les fichiers traduits instantanément

Commencez à localiser votre application React dès aujourd'hui

Vous avez maintenant tout ce qu'il faut pour construire une application React entièrement localisée avec react-i18next. Combinez la puissance de l'écosystème mature d'i18next avec la traduction par IA pour déployer votre application dans n'importe quelle langue, rapidement.