Localisation React avec i18next

Construire une application React pour un public mondial 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 la norme de facto pour l'internationalisation React, approuvée par des milliers d'applications en production dans le monde entier. Voici pourquoi les développeurs le choisissent :

• API orientée hooks - Le hook useTranslation() fournit 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 langue, les backend 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 à modifier, à contrôler en version et à intégrer avec des outils de traduction et des services d'IA.
• Prise en charge 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 SSR et Next.js - Fonctionne parfaitement avec le rendu côté serveur, les composants serveur React et le routeur d'application Next.js.
• Prise en charge de TypeScript - Sécurité de type complète pour les clés de traduction avec saisie semi-automatique, détectant les clés manquantes au moment de la compilation.

Installation

Installez react-i18next et le framework i18next principal :

npm install react-i18next i18next

Plugins optionnels

Ces plugins populaires améliorent votre configuration i18next avec la détection automatique de langue et les traductions chargées de manière différée :

# 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 maintient vos traductions maintenables à mesure que vous ajoutez plus de 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 JSON de traduction

react-i18next utilise des fichiers JSON imbriqués pour les traductions. Les clés prennent en charge 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 (par ex., welcome.title, nav.home) pour une structure claire.
• Interpolation - Utilisez la syntaxe {{variableName}} pour les valeurs dynamiques qui sont insérées au moment de 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 prend en charge deux approches principales pour le chargement des traductions : backend HTTP (chargement différé) et ressources groupées. Choisissez selon les besoins de votre application.

Backend HTTP (Recommandé pour les grandes applications)

Chargez les traductions à la demande à partir de fichiers JSON sur votre serveur. Cela garde votre bundle initial petit et est idéal pour les applications avec de nombreuses 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 votre point d'entrée d'application avant de rendre des composants. Cela garantit que les traductions sont chargées avant que votre interface ne s'affiche :

// 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>
);

Traduction des composants React

react-i18next fournit deux API principales pour traduire des 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 se re-rend automatiquement lorsque la langue change :

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 de pluriel ICU pour chaque langue. Passez un paramètre de compte, et i18next sélectionne la forme plurielle 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 avec des règles de pluriel complexes (arabe, polonais, russe), ajoutez les suffixes _zero, _two, _few, _many selon les besoins
• i18next sélectionne automatiquement la forme correcte selon les règles de pluriel CLDR de la langue cible

Organisation avec les espaces de noms

Les espaces de noms vous 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 que les traductions sont récupérées :

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 par TypeScript

i18next prend en charge une intégration TypeScript complète. En augmentant le module i18next, vous obtenez la saisie semi-automatique et la vérification au moment de 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 le routeur d'application, vous pouvez utiliser i18next sur les composants serveur et 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 côté serveur et côté client
• Considérez i18next-resources-to-backend ou next-intl comme alternatives pour les configurations Next.js complexes

Accélérez la traduction avec l'IA

Configurer react-i18next n'est que la moitié de la bataille, 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 spécialement conçu 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 machine :

• Prise en charge native du JSON — Téléchargez votre translation.json et obtenez 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écurisé pour l'interpolation — Préserve les {{variables}}, les suffixes de pluriel (_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 le cadre de votre pipeline de construction 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 le CLI ai-l10n pour traduire
3. L'IA génère des traductions contextuellement précises pour toutes les langues cibles
4. Déposez les fichiers JSON traduits dans votre répertoire locales/ et déployez

Automatisez les traductions avec le CLI ai-l10n

Le package npm ai-l10n intègre la traduction assistée 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 de construction

Ajoutez l'automatisation de la traduction à votre pipeline de construction afin 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 le Marketplace VS Code
2. Ouvrez votre fichier translation.json source
3. Faites un clic droit et sélectionnez 'Traduire avec 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 dont vous avez besoin 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 assistée par IA pour expédier votre application dans n'importe quelle langue, rapidement.