Traduction React avec react-i18next : Un guide complet

Apprenez à traduire une application React avec react-i18next, incluant l’internationalisation React, les pluriels, le contenu dynamique et la traduction de fichiers JSON.

À la fin de ce guide, vous disposerez d’une configuration de localisation React fonctionnelle qui change de langue en temps réel et est prête pour autant de langues que nécessaire.

Exemple d’internationalisation React

Les étapes ci-dessous décrivent un exemple complet d’i18n React, incluant l’initialisation d’i18next, la traduction de texte, la gestion de la pluralisation et l’ajout d’un sélecteur de langue.

Vous pouvez suivre la démonstration complète de localisation React sur GitHub.

Configurer votre application React

Ce guide utilise une application React + TypeScript construite avec Vite. Si vous ajoutez react-i18next à une application existante, passez à l’étape 2.

Pour créer une nouvelle application React + TypeScript, exécutez :

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

npm create vite@latest react-localization-demo -- --template react-ts
cd react-localization-demo
npm install
npm run dev

Cela démarre un serveur de développement et ouvre la page Vite + React par défaut dans votre navigateur.

Installer et configurer react-i18next

Installez les bibliothèques :

npm install i18next react-i18next

npm install i18next react-i18next

Créez la structure de dossiers de votre i18n React :

src/
 i18n/
 locales/
 en.json

src/
  i18n/
    locales/
      en.json

Ajoutez vos chaînes de caractères anglaises à src/i18n/locales/en.json :

{
 "welcome": "Welcome",
 "description": "This is a localization demo.",
 "clickMe": "Click me"
}

{
  "welcome": "Welcome",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Chaque clé (welcome, description, clickMe) correspond au texte que vous souhaitez afficher dans l’interface utilisateur.

Préparez vos composants React pour la traduction

Voici un composant React typique avec des chaînes de caractères codées en dur :

function App() {
  return (
    <div>
      <h1>Bienvenue</h1>
      <p>Ceci est une démonstration de localisation.</p>
      <button onClick={() => alert('Cliquez-moi')}>Cliquez-moi</button>
    </div>
  );
}

function App() {
  return (
    <div>
      <h1>Welcome</h1>
      <p>This is a localization demo.</p>
      <button onClick={() => alert('Click me')}>Click me</button>
    </div>
  );
}

Remplacez le texte codé en dur par le hook useTranslation dans src/App.tsx :

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

useTranslation() donne à votre composant l’accès à :

t() – recherche une chaîne de caractères par clé
i18n – vous permet de changer de langue par programmation

Initialisez i18next dans votre application React

Créez src/i18n/index.ts pour configurer i18next et charger automatiquement les fichiers de traduction.

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
 const lang = path.match(/./locales/(.*).json$/)?.[1];
 if (lang) {
 resources[lang] = { translation: modules[path].default };
 }
}

i18n
 .use(initReactI18next)
 .init({
 resources,
 fallbackLng: 'en',
 interpolation: { escapeValue: false },
 });

export default i18n;

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: 'en',
    interpolation: { escapeValue: false },
  });

export default i18n;

Le modèle import.meta.glob signifie que chaque fichier .json que vous ajoutez à src/i18n/locales/ est automatiquement détecté. Aucune importation manuelle n’est nécessaire lorsque vous ajoutez de nouvelles langues par la suite.

Importez i18n avant le rendu de votre application

Ouvrez src/main.tsx et importez la configuration i18n :

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n' // ← Ajoutez cet import !

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import './i18n'  // ← Add this import!

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
)

Si vous sautez cette étape, t() renverra simplement les clés de traduction au lieu du texte traduit.

Gérez le contenu dynamique dans les traductions React

Les applications réelles nécessitent plus que des chaînes statiques. Voici comment react-i18next gère les modèles de contenu dynamique les plus courants.

Interpolation (variables) dans i18next

Utilisez la syntaxe {{variableName}} dans votre JSON et passez la valeur à t().

Mettez à jour src/i18n/locales/en.json :

{
 "welcome": "Bienvenue",
 "userGreeting": "Bon retour, {{firstName}} !",
 "description": "Ceci est une démonstration de localisation.",
 "clickMe": "Cliquez-moi"
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me"
}

Utilisez-le dans votre composant :

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('description')}</p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

Le deuxième argument de t() est un objet avec les valeurs que vous souhaitez substituer. Vous pouvez avoir autant de variables que nécessaire. Assurez-vous simplement que chacune apparaît dans vos traductions.

Pluralisation React i18next

Utilisez le modèle de suffixe _one / _other. La variable doit être nommée count :

Mettez à jour src/i18n/locales/en.json :

{
 "welcome": "Bienvenue",
 "userGreeting": "Bon retour, {{firstName}} !",
 "description": "Ceci est une démonstration de localisation.",
 "clickMe": "Cliquez-moi",
 "newMessages_one": "Vous avez {{count}} nouveau message.",
 "newMessages_other": "Vous avez {{count}} nouveaux messages."
}

{
  "welcome": "Welcome",
  "userGreeting": "Welcome back, {{firstName}}!",
  "description": "This is a localization demo.",
  "clickMe": "Click me",
  "newMessages_one": "You have {{count}} new message.",
  "newMessages_other": "You have {{count}} new messages."
}

Utilisez-le dans votre composant :

import { useTranslation } from 'react-i18next';

function App() {
 const { t } = useTranslation();
 const user = { firstName: 'Sarah' };
 const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
 setMessageCount(messageCount + 1);
 };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

import { useTranslation } from 'react-i18next';

function App() {
  const { t } = useTranslation();
  const user = { firstName: 'Sarah' };
  const [messageCount, setMessageCount] = useState<number>(1);

  const handleIncrement = () => {
    setMessageCount(messageCount + 1);
  };

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      <button onClick={handleIncrement}>{t('clickMe')}</button>
    </div>
  );
}

export default App;

i18next sélectionne automatiquement la forme plurielle correcte. Il gère également les langues avec plus de deux formes plurielles (comme le polonais ou l’arabe) sans aucune configuration supplémentaire.

Traduisez les liens et le HTML avec le composant Trans

Pour les traductions contenant des éléments HTML comme des liens ou du texte en gras, utilisez le composant Trans :

{
 « termsText » : « J'accepte les <1>Conditions d'utilisation1> et la <3>Politique de confidentialité3>. »
}

{
  "termsText": "I agree to the <1>Terms of Service</1> and <3>Privacy Policy</3>."
}

Les balises <1> et <3> sont des placeholders basés sur l’index qui correspondent aux éléments enfants (en comptant à partir de 0) :

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
 J'accepte les <a href="/terms">Conditions d'utilisation</a> et
  <a href="/privacy">Politique de confidentialité</a>.
</Trans>

import { Trans } from 'react-i18next';

<Trans i18nKey="termsText">
  I agree to the <a href="/terms">Terms of Service</a> and
  <a href="/privacy">Privacy Policy</a>.
</Trans>

Cela permet de conserver vos éléments JSX dans le composant tout en permettant aux traducteurs de réorganiser le texte environnant naturellement.

Traduisez les fichiers JSON de votre application React

Votre application React est maintenant configurée pour l’internationalisation. L’étape suivante consiste à produire les fichiers de traduction réels pour chaque langue.

PTC est conçu exactement pour cela. Cet outil de localisation IA s’intègre directement à votre dépôt GitHub, GitLab ou Bitbucket. Il lit votre source en.json et ouvre une demande de tirage avec les fichiers traduits pour chaque langue dont vous avez besoin.

Grâce à la configuration de chargement automatique que vous avez définie à l’étape 3, ces nouveaux fichiers fonctionnent immédiatement sans nécessiter de modifications de code.

PTC commence par un essai gratuit de 30 jours qui vous permet de traduire 20 000 mots dans 2 langues. Après cela, vous payez à l’utilisation sans abonnement.

S’inscrire à PTC

Si vous préférez ne pas vous intégrer à votre dépôt, vous pouvez également :

Utiliser l’API PTC pour configurer une localisation continue
Télécharger manuellement un fichier JSON et récupérer un fichier traduit

Testez les traductions React avec un sélecteur de langue

Ajoutez des boutons de langue à src/App.tsx et vérifiez que votre configuration react-i18next fonctionne :

import { useTranslation } from 'react-i18next';

function App() {
 const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
  J'accepte les  <a href="/terms">Conditions d'utilisation</a> et la  <a href="/privacy">Politique de confidentialité</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
 );
}

import { useTranslation } from 'react-i18next';

function App() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('userGreeting', { firstName: user.firstName })}</p>
      <p>{t('newMessages', { count: messageCount })}</p>
      <p>{t('description')}</p>
      
      <p>
        <Trans i18nKey="termsText">
          I agree to the <a href="/terms">Terms of Service</a> and <a href="/privacy">Privacy Policy</a>.
        </Trans>
      </p>
      <button onClick={() => alert(t('clickMe'))}>{t('clickMe')}</button>

      <button onClick={() => i18n.changeLanguage('en')}>EN</button>
      <button onClick={() => i18n.changeLanguage('fr')}>FR</button>
    </div>
  );
}

Exécutez npm run dev et cliquez sur les boutons de langue. Le texte devrait se mettre à jour immédiatement sans rechargement de page. Si c’est le cas, votre configuration i18n React fonctionne correctement.

React app in English

React app in French

Étapes suivantes : Optimisez votre configuration de localisation React

Votre application React dispose désormais d’un support multilingue complet. Quelques ajouts méritent d’être considérés avant de passer en production :

Détection automatique de la langue de l’utilisateur

Installez i18next-browser-languagedetector pour charger automatiquement la langue correcte à partir des paramètres du navigateur de l’utilisateur, de l’URL ou des préférences enregistrées :

npm install i18next-browser-languagedetector

npm install i18next-browser-languagedetector

Mettez à jour src/i18n/index.ts :

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
 const lang = path.match(/./locales/(.*).json$/)?.[1];
 if (lang) {
 resources[lang] = { translation: modules[path].default };
 }
}

i18n
 .use(LanguageDetector) // détecte le navigateur/localStorage/etc.
 .use(initReactI18next)
 .init({
 resources,
 fallbackLng: "en",
 supportedLngs: ["en", "fr", "de", "ar"], // ajustez à vos langues
 interpolation: { escapeValue: false },
 detection: {
 order: ["querystring", "localStorage", "cookie", "navigator"],
 caches: ["localStorage", "cookie"],
 }
 });

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";

type TranslationResources = string | { [k: string]: TranslationResources } | TranslationResources[];

const modules = import.meta.glob<{default: Record<string, TranslationResources>}>('./locales/*.json', { eager: true })

const resources: Record<string, { translation: Record<string, TranslationResources> }> = {};

for (const path in modules) {
  const lang = path.match(/\.\/locales\/(.*)\.json$/)?.[1];
  if (lang) {
    resources[lang] = { translation: modules[path].default };
  }
}

i18n
  .use(LanguageDetector) // detect browser/localStorage/etc.
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: "en",
    supportedLngs: ["en", "fr", "de", "ar"], // adjust to your languages
    interpolation: { escapeValue: false },
    detection: {
      order: ["querystring", "localStorage", "cookie", "navigator"],
      caches: ["localStorage", "cookie"],
    }
  });

export default i18n;

Chargement différé des traductions

Par défaut, tous les fichiers de traduction sont regroupés au moment de la construction. Pour les applications React avec de nombreuses langues, utilisez i18next-http-backend pour récupérer uniquement les fichiers de langue dont l’utilisateur a réellement besoin :

npm install i18next-http-backend

npm install i18next-http-backend

Mettez à jour src/i18n/index.ts :

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

i18n
 .use(Backend) // charge JSON via HTTP
 .use(LanguageDetector)
 .use(initReactI18next)
 .init({
 fallbackLng: "en",
 supportedLngs: ["en", "fr"],
 interpolation: { escapeValue: false },
 backend: {
 loadPath: "/locales/{{lng}}/{{ns}}.json"
 }
 });

export default i18n;

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import Backend from "i18next-http-backend";
import LanguageDetector from "i18next-browser-languagedetector";

i18n
  .use(Backend) // load JSON over HTTP
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en",
    supportedLngs: ["en", "fr"],
    interpolation: { escapeValue: false },
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json"
    }
  });

export default i18n;

Déplacez vos fichiers de traduction vers public/locales/ afin qu’ils soient servis comme des ressources statiques :

public/
 locales/
 en/
 translation.json
 fr/
 translation.json

public/
  locales/
    en/
      translation.json
    fr/
      translation.json

Avec cette structure, le passage au français récupère /locales/fr/common.json à la demande plutôt que de le regrouper avec votre application. Cela permet de maintenir votre bundle initial léger, quel que soit le nombre de langues que vous supportez.

Traduisez React avec PTC

Votre application React est prête pour l’internationalisation. Laissez maintenant PTC gérer les traductions.

Vos 20 000 premiers mots sont gratuits, sans abonnement requis.

Essayez PTC maintenant