i18next : Le guide complet du framework d'internationalisation pour 2026

Réponse rapide

i18next est le framework d'internationalisation JavaScript le plus populaire avec plus de 8 millions de téléchargements hebdomadaires npm. Installez avec npm install i18next, configurez avec i18n.init({ lng: 'fr', resources: {...} }), puis appelez i18n.t('key') pour traduire. Il fonctionne dans n'importe quel environnement JavaScript—React, Vue, Node.js, JS vanilla, applications mobiles. Pour la production, combinez avec IntlPull pour la gestion de la traduction assistée par IA et la collaboration d'équipe.

---

Qu'est-ce que i18next ?

i18next est une bibliothèque d'internationalisation (i18n) agnostique du framework pour JavaScript. Créée en 2011, c'est la solution i18n la plus éprouvée avec :

• Support universel : Navigateur, Node.js, React Native, Electron, Deno
• Liaisons de framework : React, Vue, Angular, Svelte, Next.js
• Écosystème de plugins : 50+ plugins pour les backends, la détection, la mise en cache
• Prêt pour l'entreprise : Utilisé par des entreprises comme Microsoft, Adobe, Airbnb

Pourquoi i18next ?

Concepts de base

1. Fichiers de traduction (Ressources)

Les traductions sont organisées sous forme d'objets JSON avec des clés imbriquées :

JSONCopy
1{
2  "greeting": "Bonjour !",
3  "nav": {
4    "home": "Accueil",
5    "about": "À propos de nous"
6  },
7  "buttons": {
8    "submit": "Soumettre",
9    "cancel": "Annuler"
10  }
11}

2. Espaces de noms

Les espaces de noms divisent les traductions en groupes logiques (comme des modules de code) :

locales/
├── en/
│   ├── common.json    # Chaînes partagées
│   ├── auth.json      # Authentification
│   └── dashboard.json # Page tableau de bord
└── fr/
    ├── common.json
    ├── auth.json
    └── dashboard.json

3. Détection de langue

i18next peut détecter la langue de l'utilisateur à partir de plusieurs sources :

• Paramètre URL (?lng=fr)
• Cookie
• localStorage
• Paramètres du navigateur
• Attribut lang HTML

4. Chaîne de repli

Lorsqu'une traduction est manquante :

1. Vérifier la langue demandée (fr-FR)
2. Vérifier la langue parente (fr)
3. Vérifier la langue de repli (en)
4. Retourner la clé ou la valeur par défaut

Configuration de base

Installation

TerminalCopy
1npm install i18next
2# ou
3yarn add i18next
4# ou
5pnpm add i18next

Configuration minimale

JavaScriptCopy
1import i18next from 'i18next';
2
3i18next.init({
4  lng: 'en',
5  resources: {
6    en: {
7      translation: {
8        greeting: 'Hello, World!',
9        welcome: 'Welcome to our app',
10      },
11    },
12    fr: {
13      translation: {
14        greeting: 'Bonjour le monde !',
15        welcome: 'Bienvenue dans notre application',
16      },
17    },
18  },
19});
20
21// Utiliser les traductions
22console.log(i18next.t('greeting')); // "Bonjour le monde !" (si lng est 'fr')

Configuration complète

JavaScriptCopy
1import i18next from 'i18next';
2
3i18next.init({
4  // Paramètres de langue
5  lng: 'fr',                    // Langue actuelle
6  fallbackLng: 'en',            // Repli si traduction manquante
7  supportedLngs: ['en', 'es', 'fr', 'de'],
8  load: 'languageOnly',         // 'en' au lieu de 'en-US'
9
10  // Paramètres d'espace de noms
11  ns: ['common', 'auth', 'dashboard'],
12  defaultNS: 'common',
13
14  // Ressources (en ligne ou chargées via backend)
15  resources: {
16    en: { common: {...}, auth: {...} },
17    fr: { common: {...}, auth: {...} },
18  },
19
20  // Interpolation
21  interpolation: {
22    escapeValue: false,         // Pas nécessaire pour React
23    formatSeparator: ',',
24  },
25
26  // Paramètres de clé
27  keySeparator: '.',            // Pour les clés imbriquées
28  nsSeparator: ':',             // namespace:key
29
30  // Clés manquantes
31  saveMissing: true,
32  missingKeyHandler: (lng, ns, key) => {
33    console.warn(`Manquant : ${lng}/${ns}/${key}`);
34  },
35
36  // Débogage
37  debug: process.env.NODE_ENV === 'development',
38});

Interpolation de variables

Variables de base

JSONCopy
1{
2  "greeting": "Bonjour, {{name}} !",
3  "cartInfo": "Vous avez {{count}} articles valant {{total}}"
4}

JavaScriptCopy
1i18next.t('greeting', { name: 'Jean' });
2// "Bonjour, Jean !"
3
4i18next.t('cartInfo', { count: 5, total: '99,99 €' });
5// "Vous avez 5 articles valant 99,99 €"

Objets imbriqués

JSONCopy
{
  "userInfo": "{{user.name}} ({{user.email}})"
}

JavaScriptCopy
1i18next.t('userInfo', {
2  user: { name: 'Jean', email: 'jean@exemple.com' }
3});
4// "Jean (jean@exemple.com)"

Valeurs par défaut

JavaScriptCopy
1i18next.t('unknown.key', 'Texte par défaut');
2// "Texte par défaut" (quand la clé n'existe pas)
3
4i18next.t('greeting', { name: 'Invité', defaultValue: 'Bonjour !' });
5// Utilise defaultValue si la clé est manquante

Formatage

JSONCopy
1{
2  "price": "Total : {{amount, currency}}",
3  "date": "Créé : {{date, datetime}}"
4}

JavaScriptCopy
1i18next.init({
2  interpolation: {
3    format: (value, format, lng) => {
4      if (format === 'currency') {
5        return new Intl.NumberFormat(lng, {
6          style: 'currency',
7          currency: 'EUR',
8        }).format(value);
9      }
10      if (format === 'datetime') {
11        return new Intl.DateTimeFormat(lng, {
12          dateStyle: 'medium',
13        }).format(value);
14      }
15      return value;
16    },
17  },
18});
19
20i18next.t('price', { amount: 99.99 });
21// "Total : 99,99 €"

Pluralisation

Pluriels de base

JSONCopy
1{
2  "item_one": "{{count}} article",
3  "item_other": "{{count}} articles"
4}

JavaScriptCopy
i18next.t('item', { count: 1 });  // "1 article"
i18next.t('item', { count: 5 });  // "5 articles"

Compte zéro

JSONCopy
1{
2  "item_zero": "Aucun article",
3  "item_one": "{{count}} article",
4  "item_other": "{{count}} articles"
5}

Pluriels complexes

Les langues comme le russe et l'arabe ont des règles plurielles complexes :

JSONCopy
1{
2  "item_zero": "нет товаров",
3  "item_one": "{{count}} товар",
4  "item_few": "{{count}} товара",
5  "item_many": "{{count}} товаров",
6  "item_other": "{{count}} товаров"
7}

i18next sélectionne automatiquement la forme correcte basée sur les règles plurielles CLDR.

Ordinaux

JSONCopy
1{
2  "rank_ordinal_one": "{{count}}er",
3  "rank_ordinal_other": "{{count}}ème"
4}

JavaScriptCopy
i18next.t('rank', { count: 1, ordinal: true });  // "1er"
i18next.t('rank', { count: 2, ordinal: true });  // "2ème"

Contexte

Même clé, différentes traductions basées sur le contexte :

JSONCopy
1{
2  "friend": "Un ami",
3  "friend_male": "Un petit ami",
4  "friend_female": "Une petite amie"
5}

JavaScriptCopy
i18next.t('friend');                        // "Un ami"
i18next.t('friend', { context: 'male' });   // "Un petit ami"
i18next.t('friend', { context: 'female' }); // "Une petite amie"

Combiner contexte et pluriels

JSONCopy
1{
2  "friend_male_one": "{{count}} petit ami",
3  "friend_male_other": "{{count}} petits amis",
4  "friend_female_one": "{{count}} petite amie",
5  "friend_female_other": "{{count}} petites amies"
6}

JavaScriptCopy
i18next.t('friend', { context: 'male', count: 2 });
// "2 petits amis"

Espaces de noms

Chargement de plusieurs espaces de noms

JavaScriptCopy
1i18next.init({
2  ns: ['common', 'auth', 'dashboard'],
3  defaultNS: 'common',
4  resources: {
5    en: {
6      common: { submit: 'Submit' },
7      auth: { login: 'Sign In' },
8      dashboard: { title: 'Dashboard' },
9    },
10    fr: {
11      common: { submit: 'Soumettre' },
12      auth: { login: 'Se connecter' },
13      dashboard: { title: 'Tableau de bord' },
14    },
15  },
16});
17
18i18next.t('submit');           // De common (défaut)
19i18next.t('auth:login');       // De l'espace de noms auth
20i18next.t('dashboard:title');  // De l'espace de noms dashboard

Chargement dynamique d'espace de noms

JavaScriptCopy
1// Charger l'espace de noms à la demande
2await i18next.loadNamespaces('settings');
3
4// Vérifier si l'espace de noms est chargé
5i18next.hasLoadedNamespace('settings');

Système de Plugin

Détection de langue

JavaScriptCopy
1import i18next from 'i18next';
2import LanguageDetector from 'i18next-browser-languagedetector';
3
4i18next.use(LanguageDetector).init({
5  detection: {
6    order: ['querystring', 'cookie', 'localStorage', 'navigator'],
7    lookupQuerystring: 'lng',
8    lookupCookie: 'i18next',
9    caches: ['localStorage', 'cookie'],
10  },
11});

Backend HTTP

Charger les traductions depuis le serveur :

JavaScriptCopy
1import i18next from 'i18next';
2import HttpBackend from 'i18next-http-backend';
3
4i18next.use(HttpBackend).init({
5  backend: {
6    loadPath: '/locales/{{lng}}/{{ns}}.json',
7    addPath: '/locales/add/{{lng}}/{{ns}}',
8  },
9});

Backends en chaîne

Sources de repli multiples :

JavaScriptCopy
1import i18next from 'i18next';
2import ChainedBackend from 'i18next-chained-backend';
3import LocalStorageBackend from 'i18next-localstorage-backend';
4import HttpBackend from 'i18next-http-backend';
5
6i18next.use(ChainedBackend).init({
7  backend: {
8    backends: [LocalStorageBackend, HttpBackend],
9    backendOptions: [
10      { expirationTime: 7 * 24 * 60 * 60 * 1000 }, // 7 jours
11      { loadPath: '/locales/{{lng}}/{{ns}}.json' },
12    ],
13  },
14});

Plugins populaires

Intégration de Framework

React (react-i18next)

JSXCopy
1import { useTranslation } from 'react-i18next';
2
3function Component() {
4  const { t } = useTranslation();
5  return <h1>{t('welcome')}</h1>;
6}

Voir notre guide react-i18next pour les détails.

Vue (vue-i18next)

VUECopy
<template>
  <h1>{{ $t('welcome') }}</h1>
</template>

Angular (angular-i18next)

TypeScriptCopy
1@Component({
2  template: `<h1>{{ 'welcome' | i18next }}</h1>`
3})
4export class AppComponent {}

Node.js

JavaScriptCopy
1import i18next from 'i18next';
2import Backend from 'i18next-fs-backend';
3
4await i18next.use(Backend).init({
5  lng: 'en',
6  backend: {
7    loadPath: './locales/{{lng}}/{{ns}}.json',
8  },
9});
10
11console.log(i18next.t('greeting'));

Support TypeScript

Clés Type-Safe

TypeScriptCopy
1// types/i18next.d.ts
2import 'i18next';
3import en from '../locales/en/common.json';
4
5declare module 'i18next' {
6  interface CustomTypeOptions {
7    defaultNS: 'common';
8    resources: {
9      common: typeof en;
10    };
11  }
12}

TypeScriptCopy
1import i18next from 'i18next';
2
3i18next.t('greeting');    // ✅ L'autocomplétion fonctionne
4i18next.t('nonexistent'); // ❌ Erreur TypeScript

Interpolation Typée

TypeScriptCopy
// Les traductions avec variables sont vérifiées
i18next.t('greeting', { name: 'John' }); // ✅
i18next.t('greeting', { wrong: 'var' }); // ❌ Erreur TypeScript

Bonnes pratiques de production

1. Organisation des fichiers

src/
├── i18n/
│   ├── index.ts           # config i18next
│   ├── types.d.ts         # Déclarations TypeScript
│   └── locales/
│       ├── en/
│       │   ├── common.json
│       │   ├── auth.json
│       │   └── errors.json
│       └── fr/
│           ├── common.json
│           ├── auth.json
│           └── errors.json

2. Convention de nommage des clés

JSONCopy
1{
2  "page.section.element": "Valeur",
3  "auth.login.title": "Se connecter",
4  "errors.validation.required": "Ce champ est requis",
5  "buttons.submit": "Soumettre"
6}

3. Suivi des clés manquantes

JavaScriptCopy
1i18next.init({
2  saveMissing: true,
3  missingKeyHandler: (lngs, ns, key, fallbackValue) => {
4    // Envoyer au suivi d'erreurs
5    Sentry.captureMessage(`Clé i18n manquante : ${key}`);
6
7    // Ou loguer pour extraction
8    console.warn(`[i18n] Manquant : ${lngs.join(',')}/${ns}/${key}`);
9  },
10});

4. Optimisation des performances

JavaScriptCopy
1i18next.init({
2  // Charger uniquement les espaces de noms nécessaires
3  ns: ['common'],
4
5  // Désactiver les fonctionnalités inutiles
6  initImmediate: false,
7
8  // Mettre en cache dans localStorage
9  backend: {
10    expirationTime: 7 * 24 * 60 * 60 * 1000,
11  },
12});
13
14// Précharger les espaces de noms critiques
15await i18next.loadNamespaces(['auth']);

5. Intégration CI/CD

YAMLCopy
1# .github/workflows/i18n.yml
2name: i18n Check
3on: [push]
4jobs:
5  check:
6    runs-on: ubuntu-latest
7    steps:
8      - uses: actions/checkout@v4
9      - name: Check missing translations
10        run: npx @intlpullhq/cli status --fail-on-missing

Mise à l'échelle avec IntlPull

Gérer les fichiers JSON manuellement devient difficile à l'échelle. IntlPull s'intègre directement avec i18next :

Flux de travail CLI

TerminalCopy
1# Initialiser
2npx @intlpullhq/cli init
3
4# Extraire les clés du code
5npx @intlpullhq/cli extract
6
7# Télécharger vers IntlPull
8npx @intlpullhq/cli upload
9
10# Traduire avec l'IA
11npx @intlpullhq/cli translate --target es,fr,de
12
13# Télécharger les traductions
14npx @intlpullhq/cli download

Backend OTA

Mettre à jour les traductions sans déployer :

JavaScriptCopy
1import { IntlPullBackend } from '@intlpull/i18next-backend';
2
3i18next.use(IntlPullBackend).init({
4  backend: {
5    projectId: 'votre-projet',
6    apiKey: process.env.INTLPULL_API_KEY,
7    reloadOnSave: true, // Auto-actualiser quand les traductions changent
8  },
9});

Avantages

Foire aux questions

Qu'est-ce que i18next ?

i18next est un framework d'internationalisation JavaScript qui fonctionne dans n'importe quel environnement—navigateur, Node.js, React Native, Electron. Avec plus de 8 millions de téléchargements hebdomadaires, c'est la bibliothèque i18n la plus populaire. Elle fournit le chargement de traduction, l'interpolation, la pluralisation, le formatage et un système de plugin pour les backends personnalisés et la détection de langue.

Comment installer i18next ?

Installez avec npm : npm install i18next. Pour React, ajoutez react-i18next. Pour la détection de langue, ajoutez i18next-browser-languagedetector. Pour charger depuis le serveur, ajoutez i18next-http-backend. Initialisez avec i18next.init({ lng: 'fr', resources: {...} }).

Quelle est la différence entre i18next et react-i18next ?

i18next est la bibliothèque de base qui fonctionne dans n'importe quel environnement JavaScript. react-i18next est la liaison officielle React qui fournit des hooks (useTranslation), des composants (Trans) et des optimisations spécifiques à React. Utilisez i18next seul pour Node.js ou JS vanilla ; utilisez react-i18next pour les applications React.

Comment gérer la pluralisation dans i18next ?

Utilisez des suffixes pluriels sur les clés de traduction : item_one, item_other, item_zero. Passez count à la fonction t : t('item', { count: 5 }). i18next utilise les règles plurielles CLDR, donc les langues complexes comme le russe (avec les formes _few, _many) fonctionnent automatiquement.

Comment charger des traductions depuis un serveur ?

Utilisez le plugin i18next-http-backend. Configurez backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' }. Les traductions sont récupérées à la demande en fonction de la langue et de l'espace de noms actuels. Combinez avec i18next-localstorage-backend pour la mise en cache.

Comment détecter la langue de l'utilisateur automatiquement ?

Utilisez le plugin i18next-browser-languagedetector. Configurez l'ordre de détection : order: ['querystring', 'cookie', 'localStorage', 'navigator']. Il vérifie les paramètres URL, les cookies, localStorage et les paramètres du navigateur pour déterminer la meilleure langue.

Puis-je utiliser i18next avec TypeScript ?

Oui, i18next a un excellent support TypeScript. Créez un fichier de déclaration de type important votre JSON de traduction, et étendez CustomTypeOptions. Vous obtenez l'autocomplétion et les erreurs de compilation pour les clés invalides. Cela attrape les fautes de frappe avant l'exécution.

Comment utiliser les espaces de noms dans i18next ?

Les espaces de noms divisent les traductions en groupes logiques comme 'common', 'auth', 'dashboard'. Configurez ns: ['common', 'auth'] et accédez avec t('auth:login') ou définissez defaultNS pour éviter les préfixes. Chargez les espaces de noms à la demande avec loadNamespaces().

Quels plugins sont disponibles pour i18next ?

50+ plugins existent pour divers besoins : i18next-http-backend (chargement serveur), i18next-localstorage-backend (mise en cache), i18next-browser-languagedetector (détection), i18next-icu (format ICU), et des liaisons de framework pour React, Vue, Angular, Svelte. Consultez la liste officielle des plugins.

Résumé

i18next est le framework d'internationalisation JavaScript standard de l'industrie :

Pour les applications de production, combinez i18next avec IntlPull pour obtenir la traduction IA, les mises à jour OTA et la collaboration d'équipe sans gérer les fichiers JSON manuellement.

Prêt à simplifier votre i18n ? Commencez gratuitement avec IntlPull — fonctionne parfaitement avec toute configuration i18next.