Posez votre question et obtenez un résumé du document en referencant cette page et le Provider AI de votre choix
Historique des versions
- Version initialev7.0.601/11/2025
Le contenu de cette page a été traduit à l'aide d'une IA.
Voir la dernière version du contenu original en anglaisSi vous avez une idée d’amélioration pour améliorer cette documentation, n’hésitez pas à contribuer en submitant une pull request sur GitHub.
Lien GitHub de la documentationCopier le Markdown du doc dans le presse-papiers
Comment internationaliser votre application Next.js avec next-i18next en 2026
Table des matières
Qu'est-ce que next-i18next ?
next-i18next est une solution d'internationalisation (i18n) populaire pour les applications Next.js. Alors que le package original next-i18next était conçu pour le Pages Router, ce guide vous montre comment implémenter i18next avec le moderne App Router en utilisant directement i18next et react-i18next.
Avec cette approche, vous pouvez :
- Organiser les traductions en utilisant des namespaces (par exemple,
common.json,about.json) pour une meilleure gestion du contenu. - Charger les traductions efficacement en ne chargeant que les namespaces nécessaires pour chaque page, réduisant ainsi la taille du bundle.
- Supporter à la fois les composants serveur et client avec une gestion appropriée du SSR et de l'hydratation.
- Assurer le support TypeScript avec une configuration locale et des clés de traduction typées en toute sécurité.
- Optimiser pour le SEO avec une internationalisation appropriée des métadonnées, sitemap et robots.txt.
En alternative, vous pouvez également vous référer au guide next-intl, ou utiliser directement Intlayer.
Voir la comparaison dans next-i18next vs next-intl vs Intlayer.
Ce que dit le benchmark sur next-i18next avec Next.js
Avant de passer à la configuration, il est essentiel de comprendre l'impact de votre bibliothèque i18n sur les performances et le bundle. Le benchmark i18n exécute la même application Next.js de 10 pages et 10 locales avec les principales bibliothèques i18n afin de mesurer l'empreinte réelle du bundle, la fuite de chaînes et le coût d'hydratation.
Chargement JSON dynamique
Charge les traductions à la volée
JSON scopé (espaces de noms)
Espaces de noms de traduction par page
Benchmark de Performance I18n
Quelle est cette métrique ?
La taille totale compressée en gzip du bundle de la bibliothèque d’internationalisation. Elle n’inclut que le fournisseur et la logique de récupération de contenu après tree-shaking et minification.
Pourquoi est-ce important ?
Une taille de bibliothèque plus petite réduit la charge utile JavaScript initiale, ce qui accélère le téléchargement et le temps d’exécution sur le client.
Voir comme
Chiffres clés pour next-i18next sur Next.js (gzip) :
Ouvrir le tableau dans une fenêtre modale pour voir tout le contenu clairement
| Configuration | Taille de la bibliothèque | JS moyen par page | Fuite autres locales | Fuite autres pages |
|---|---|---|---|---|
| Base (sans i18n) | - | 141.0 KB | 0.0% | 0.0% |
next-i18next | 19.7 KB | 169.5 KB | 50.0% | 89.8% |
@intlayer/next-i18next (compat) | 9.4 KB | 150.7 KB | 0.0% | 0.0% |
next-intlayer (Intlayer natif) | 5.5 KB | 141.3 KB | 0.0% | 0.0% |
À retenir :
- Le découpage en namespaces est indispensable : dans une configuration naïve,
next-i18nextembarque tous les namespaces sur chaque page (~89.8% de fuite entre pages). Découper les namespaces par route et les charger en lazy loading réduit le JS de page, mais demande une organisation manuelle rigoureuse. - Poids du runtime : le runtime client
i18nextpèse ~19.7 KB gzip sur chaque page. Pour une codebase existante, l'adaptateur de compatibilité@intlayer/next-i18nextconserve la même APIi18nexttout en réduisant le runtime à 9.4 KB et en supprimant les fuites.next-intlayeren natif descend à 5.5 KB.
Voir les données complètes : rapport de benchmark Next.js, et le dépôt du benchmark.
Comparaison des fonctionnalités sur Next.js
Comment next-i18next se compare à next-intl et à Intlayer sur les fonctionnalités dont un projet Next.js App Router a généralement besoin :
Ouvrir le tableau dans une fenêtre modale pour voir tout le contenu clairement
| Fonctionnalité | next-intlayer (Intlayer) | next-intl | next-i18next |
|---|---|---|---|
| Traductions proches des composants | ✅ Contenu co-localisé avec chaque composant | ❌ JSON centralisé | ❌ JSON centralisé |
| Intégration TypeScript | ✅ Types stricts générés automatiquement | ✅ Bonne, via l'augmentation AppConfig | ⚠️ Basique |
| Détection des traductions manquantes | ✅ Erreurs TypeScript et avertissements au build | ⚠️ Fallback au runtime | ⚠️ Fallback au runtime |
| Contenu riche (JSX, Markdown) | ✅ Support direct | ⚠️ Balises via t.rich, pas de Markdown | ⚠️ Balises via <Trans> |
| Traduction par IA | ✅ Votre propre fournisseur et clé API, avec le contexte de l'application | ❌ Non | ❌ Non |
| Éditeur visuel / CMS | ✅ Éditeur visuel local + CMS optionnel | ❌ Via des plateformes externes | ❌ Via des plateformes externes |
| Routage localisé | ✅ Intégré (Next.js et Vite) | ✅ Segment [locale] intégré | ✅ Intégré |
| Pluralisation | ✅ Basée sur des énumérations | ✅ ICU | ✅ Basée sur des suffixes (_one, _other) |
| Formatage (dates, nombres, devises) | ✅ Formateurs basés sur Intl | ✅ useFormatter | ✅ Basé sur Intl |
| Formats de contenu | ✅ .ts, .tsx, .js, .json, .md, .yaml | ✅ .json, .js, .ts | ⚠️ .json |
| ICU MessageFormat | ✅ Via format: "icu" | ✅ Natif | ⚠️ Via i18next-icu |
| Helpers SEO (hreflang, sitemap) | ✅ Helpers pour metadata, sitemap et robots.txt | ✅ Bon | ✅ Bon |
| Server Components | ✅ Accès direct dans n'importe quel Server Component | ⚠️ Passer t ou await getTranslations() par composant | ⚠️ Passer t à travers l'arbre de composants |
| Tree-shaking par composant | ✅ Au build (Babel / SWC) | ⚠️ Manuel, avec pick() par route | ⚠️ Manuel, avec des namespaces par route |
| Lazy loading | ✅ Par locale et par dictionnaire | ✅ Par locale, namespaces gérés à la main | ✅ Par locale, namespaces gérés à la main |
| Taille du runtime (gzip, benchmark) | 4.9 KB | 14.7 KB | 19.7 KB |
| Traductions manquantes en CI | ✅ npx intlayer test | ⚠️ Non intégré | ⚠️ Non intégré, saveMissing au runtime |
| Écosystème / communauté | ⚠️ Plus petit, en forte croissance | ✅ Large | ✅ Très large |
Les tailles de runtime proviennent du benchmark Next.js. Pour une analyse détaillée, lisez next-i18next vs next-intl vs Intlayer.
Pratiques à suivre
Avant de plonger dans l'implémentation, voici quelques pratiques que vous devriez suivre :
- Définir les attributs HTML
langetdir - Dans votre layout, calculez
diren utilisantgetLocaleDirection(locale)et définissez<html lang={locale} dir={dir}>pour une accessibilité et un SEO appropriés. - Séparer les messages par namespace
Organisez les fichiers JSON par locale et namespace (par exemple,
common.json,about.json) pour ne charger que ce dont vous avez besoin. - Minimiser la charge côté client
Sur les pages, envoyez uniquement les namespaces nécessaires à
NextIntlClientProvider(par exemple,pick(messages, ['common', 'about'])). - Préférer les pages statiques Utilisez autant que possible des pages statiques pour de meilleures performances et un meilleur SEO.
- I18n dans les composants serveur
Les composants serveur, comme les pages ou tous les composants non marqués comme
client, sont statiques et peuvent être pré-rendus lors de la compilation. Nous devrons donc leur passer les fonctions de traduction en tant que props. - Configurer les types TypeScript
- Pour vos locales, assurez la sécurité des types dans toute votre application.
- Proxy pour la redirection Utilisez un proxy pour gérer la détection de la locale et le routage, et rediriger l'utilisateur vers l'URL préfixée par la locale appropriée.
- Internationalisation de vos métadonnées, sitemap, robots.txt
Internationalisez vos métadonnées, sitemap, robots.txt en utilisant la fonction
generateMetadatafournie par Next.js afin d'assurer une meilleure découverte par les moteurs de recherche dans toutes les locales. - Localiser les liens
Localisez les liens en utilisant le composant
Linkpour rediriger l'utilisateur vers l'URL préfixée par la locale appropriée. Il est important d'assurer la découverte de vos pages dans toutes les locales. - Automatiser les tests et les traductions Automatiser les tests et les traductions permet de gagner du temps dans la maintenance de votre application multilingue.
Consultez notre documentation listant tout ce que vous devez savoir sur l'internationalisation et le SEO : Internationalisation (i18n) avec next-intl.
Guide étape par étape pour configurer i18next dans une application Next.js
Voir Application Template sur GitHub.
Voici la structure du projet que nous allons créer :
Copier le code dans le presse-papiers
Installer les dépendances
Installez les paquets nécessaires en utilisant npm :
bashCopier le codeCopier le code dans le presse-papiers
- i18next : Le framework principal d'internationalisation qui gère le chargement et la gestion des traductions.
- react-i18next : Les bindings React pour i18next qui fournissent des hooks comme
useTranslationpour les composants clients. - i18next-resources-to-backend : Un plugin qui permet le chargement dynamique des fichiers de traduction, vous permettant de charger uniquement les namespaces dont vous avez besoin.
Configurez votre projet
Créez un fichier de configuration pour définir vos locales supportées, la locale par défaut, et des fonctions utilitaires pour la localisation des URLs. Ce fichier sert de source unique de vérité pour votre configuration i18n et garantit la sécurité des types dans toute votre application.
Centraliser la configuration des locales évite les incohérences et facilite l'ajout ou la suppression de locales à l'avenir. Les fonctions utilitaires assurent une génération cohérente des URLs pour le SEO et le routage.
i18n.config.tsCopier le codeCopier le code dans le presse-papiers
Centraliser les espaces de noms de traduction
Créez une source unique de vérité pour chaque namespace que votre application expose. Réutiliser cette liste permet de garder le code serveur, client et les outils synchronisés et active une typage fort pour les helpers de traduction.
src/i18n.namespaces.tsCopier le codeCopier le code dans le presse-papiers
Typage fort des clés de traduction avec TypeScript
Augmentez
i18nextpour pointer vers vos fichiers de langue canoniques (généralement en anglais). TypeScript en déduit alors les clés valides par namespace, ce qui permet de vérifier les appels àt()de bout en bout.src/types/i18next.d.tsCopier le codeCopier le code dans le presse-papiers
Astuce : Stockez cette déclaration sous
src/types(créez le dossier s'il n'existe pas). Next.js inclut déjàsrcdanstsconfig.json, donc l'augmentation est prise en compte automatiquement. Sinon, ajoutez ce qui suit dans votre fichiertsconfig.json:tsconfig.jsonCopier le codeCopier le code dans le presse-papiers
Avec cela en place, vous pouvez compter sur l'autocomplétion et les vérifications à la compilation :
tsxCopier le codeCopier le code dans le presse-papiers
Configurer l'initialisation i18n côté serveur
Créez une fonction d'initialisation côté serveur qui charge les traductions pour les composants serveur. Cette fonction crée une instance i18next distincte pour le rendu côté serveur, garantissant que les traductions sont chargées avant le rendu.
Les composants serveur ont besoin de leur propre instance i18next car ils s'exécutent dans un contexte différent des composants client. Le préchargement des traductions côté serveur évite un affichage fugace de contenu non traduit et améliore le SEO en s'assurant que les moteurs de recherche voient le contenu traduit.
src/app/i18n/server.tsCopier le codeCopier le code dans le presse-papiers
Créer un Provider i18n côté client
Créez un provider composant client qui enveloppe votre application avec le contexte i18next. Ce provider reçoit des traductions préchargées depuis le serveur afin d'éviter un flash de contenu non traduit (FOUC) et d'éviter les requêtes en double.
Les composants client ont besoin de leur propre instance i18next qui s'exécute dans le navigateur. En acceptant des ressources préchargées depuis le serveur, nous assurons une hydratation fluide et évitons le flash de contenu. Le provider gère également dynamiquement les changements de locale et le chargement des namespaces.
src/components/I18nProvider.tsxCopier le codeCopier le code dans le presse-papiers
Définir les routes dynamiques pour les locales
Configurez le routage dynamique pour les locales en créant un répertoire
[locale]dans votre dossier app. Cela permet à Next.js de gérer le routage basé sur la locale où chaque locale devient un segment d'URL (par exemple,/en/about,/fr/about).L'utilisation de routes dynamiques permet à Next.js de générer des pages statiques pour toutes les locales au moment de la compilation, améliorant ainsi les performances et le SEO. Le composant layout définit les attributs HTML
langetdiren fonction de la locale, ce qui est crucial pour l'accessibilité et la compréhension par les moteurs de recherche.src/app/[locale]/layout.tsxCopier le codeCopier le code dans le presse-papiers
Créez vos fichiers de traduction
Créez des fichiers JSON pour chaque locale et namespace. Cette structure vous permet d'organiser les traductions de manière logique et de ne charger que ce dont vous avez besoin pour chaque page.
Organiser les traductions par namespace (par exemple,
common.json,about.json) permet le découpage du code (code splitting) et réduit la taille du bundle. Vous ne chargez que les traductions nécessaires pour chaque page, ce qui améliore les performances.src/locales/en/common.jsonCopier le codeCopier le code dans le presse-papiers
src/locales/fr/common.jsonCopier le codeCopier le code dans le presse-papiers
src/locales/en/home.jsonCopier le codeCopier le code dans le presse-papiers
src/locales/fr/home.jsonCopier le codeCopier le code dans le presse-papiers
src/locales/en/about.jsonCopier le codeCopier le code dans le presse-papiers
src/locales/fr/about.jsonCopier le codeCopier le code dans le presse-papiers
Utiliser les traductions dans vos pages
Créez un composant de page qui initialise i18next côté serveur et transmet les traductions aux composants serveur et client. Cela garantit que les traductions sont chargées avant le rendu et évite les clignotements de contenu.
L'initialisation côté serveur charge les traductions avant que la page ne soit rendue, améliorant ainsi le SEO et évitant le FOUC (Flash Of Unstyled Content). En passant les ressources préchargées au fournisseur client, on évite les requêtes redondantes et on assure une hydratation fluide.
src/app/[locale]/about/index.tsxCopier le codeCopier le code dans le presse-papiers
Utiliser les traductions dans les composants client
Les composants client peuvent utiliser le hook
useTranslationpour accéder aux traductions. Ce hook fournit l'accès à la fonction de traduction ainsi qu'à l'instance i18n, ce qui vous permet de traduire du contenu et d'accéder aux informations de locale.Les composants client ont besoin des hooks React pour accéder aux traductions. Le hook
useTranslations'intègre parfaitement avec i18next et offre des mises à jour réactives lorsque la locale change.Assurez-vous que la page/le provider inclut uniquement les namespaces dont vous avez besoin (par exemple,
about).
Si vous utilisez React < 19, mémoïsez les formateurs lourds commeIntl.NumberFormat.src/components/ClientComponent.tsxCopier le codeCopier le code dans le presse-papiers
Utiliser les traductions dans les composants serveur
Les composants serveur ne peuvent pas utiliser les hooks React, ils reçoivent donc les traductions via les props de leurs composants parents. Cette approche maintient les composants serveur synchrones et permet de les imbriquer à l'intérieur des composants client.
Les composants serveur qui pourraient être imbriqués sous des frontières client doivent être synchrones. En passant les chaînes traduites et les informations de locale via les props, nous évitons les opérations asynchrones et assurons un rendu correct.
src/components/ServerComponent.tsxCopier le codeCopier le code dans le presse-papiers
Changer la langue de votre contenu
FacultatifPour changer la langue de votre contenu dans Next.js, la méthode recommandée est d'utiliser des URLs préfixées par la locale et les liens Next.js. L'exemple ci-dessous lit la locale actuelle depuis la route, la supprime du pathname, et affiche un lien par locale disponible.
src/components/LocaleSwitcher.tsxCopier le codeCopier le code dans le presse-papiers
Construire un composant Link localisé
FacultatifRéutiliser les URLs localisées dans toute votre application permet de garder une navigation cohérente et optimisée pour le SEO. Enveloppez
next/linkdans un petit helper qui préfixe les routes internes avec la locale active tout en laissant les URLs externes intactes.src/components/LocalizedLink.tsxCopier le codeCopier le code dans le presse-papiers
Astuce : Comme
LocalizedLinkest un remplacement direct, migrez progressivement en échangeant les imports et en laissant le composant gérer les URLs spécifiques à la locale.Accéder à la locale active dans les Server Actions
FacultatifLes Server Actions ont souvent besoin de la locale courante pour les emails, la journalisation ou les intégrations tierces. Combinez le cookie de locale défini par votre proxy avec l'en-tête
Accept-Languageen tant que solution de secours.src/app/actions/get-current-locale.tsCopier le codeCopier le code dans le presse-papiers
Parce que l'assistant s'appuie sur les cookies et les en-têtes de Next.js, il fonctionne dans les Route Handlers, les Server Actions, et d'autres contextes réservés au serveur.
Internationalisez vos métadonnées
FacultatifTraduire le contenu est important, mais l'objectif principal de l'internationalisation est de rendre votre site web plus visible dans le monde. L'i18n est un levier incroyable pour améliorer la visibilité de votre site via un SEO approprié.
Des métadonnées correctement internationalisées aident les moteurs de recherche à comprendre quelles langues sont disponibles sur vos pages. Cela inclut la mise en place des balises meta hreflang, la traduction des titres et descriptions, ainsi que la garantie que les URL canoniques sont correctement définies pour chaque locale.
Voici une liste de bonnes pratiques concernant le SEO multilingue :
- Définissez les balises meta hreflang dans la balise
<head>pour aider les moteurs de recherche à comprendre quelles langues sont disponibles sur la page - Listez toutes les traductions de pages dans le sitemap.xml en utilisant le schéma XML
http://www.w3.org/1999/xhtml - N'oubliez pas d'exclure les pages préfixées dans le fichier robots.txt (par exemple,
/dashboard,/fr/dashboard,/es/dashboard) - Utilisez un composant Link personnalisé pour rediriger vers la page la plus localisée (par exemple, en français
<a href="/fr/about">À propos</a>)
Les développeurs oublient souvent de référencer correctement leurs pages selon les locales. Corrigeons cela :
src/app/[locale]/about/layout.tsxCopier le codeCopier le code dans le presse-papiers
- Définissez les balises meta hreflang dans la balise
Internationalisez votre sitemap
FacultatifGénérez un sitemap qui inclut toutes les versions locales de vos pages. Cela aide les moteurs de recherche à découvrir et indexer toutes les versions linguistiques de votre contenu.
Un sitemap correctement internationalisé garantit que les moteurs de recherche peuvent trouver et indexer toutes les versions linguistiques de vos pages. Cela améliore la visibilité dans les résultats de recherche internationaux.
src/app/sitemap.tsCopier le codeCopier le code dans le presse-papiers
Internationalisez votre fichier robots.txt
FacultatifCréez un fichier robots.txt qui gère correctement toutes les versions locales de vos routes protégées. Cela garantit que les moteurs de recherche n'indexent pas les pages d'administration ou de tableau de bord dans aucune langue.
Configurer correctement le fichier robots.txt pour toutes les locales empêche les moteurs de recherche d'indexer des pages sensibles dans n'importe quelle langue. Ceci est crucial pour la sécurité et la confidentialité.
src/app/robots.tsCopier le codeCopier le code dans le presse-papiers
Configurer un Middleware pour le Routage des Locales
FacultatifCréez un proxy pour détecter automatiquement la locale préférée de l'utilisateur et le rediriger vers l'URL préfixée par la locale appropriée. Cela améliore l'expérience utilisateur en affichant le contenu dans sa langue préférée.
Le middleware garantit que les utilisateurs sont automatiquement redirigés vers leur langue préférée lorsqu'ils visitent votre site. Il sauvegarde également la préférence de l'utilisateur dans un cookie pour les visites futures.
src/proxy.tsCopier le codeCopier le code dans le presse-papiers
Automatisez vos traductions avec Intlayer
FacultatifIntlayer est une bibliothèque gratuite et open-source conçue pour assister le processus de localisation dans votre application. Alors que i18next gère le chargement et la gestion des traductions, Intlayer aide à automatiser le flux de travail des traductions.
Gérer les traductions manuellement peut être chronophage et source d’erreurs. Intlayer automatise les tests, la génération et la gestion des traductions, vous faisant gagner du temps et assurant la cohérence dans toute votre application.
Intlayer vous permet de :
Déclarer votre contenu où vous le souhaitez dans votre base de code
Intlayer permet de déclarer votre contenu où vous le souhaitez dans votre base de code en utilisant des fichiers.content.{ts|js|json}. Cela permettra une meilleure organisation de votre contenu, assurant une meilleure lisibilité et maintenabilité de votre base de code.Tester les traductions manquantes
Intlayer fournit des fonctions de test qui peuvent être intégrées dans votre pipeline CI/CD ou dans vos tests unitaires. En savoir plus sur tester vos traductions.Automatisez vos traductions, Intlayer fournit une CLI et une extension VSCode pour automatiser vos traductions. Cela peut être intégré dans votre pipeline CI/CD. En savoir plus sur l'automatisation de vos traductions. Vous pouvez utiliser votre propre clé API, et le fournisseur d'IA de votre choix. Il offre également des traductions contextuelles, voir remplissage de contenu.
Connectez du contenu externe
Intlayer vous permet de connecter votre contenu à un système de gestion de contenu externe (CMS). Pour le récupérer de manière optimisée et l'insérer dans vos ressources JSON. En savoir plus sur la récupération de contenu externe.Éditeur visuel
Intlayer propose un éditeur visuel gratuit pour éditer votre contenu via un éditeur visuel. En savoir plus sur l'édition visuelle de vos traductions.
Et plus encore. Pour découvrir toutes les fonctionnalités offertes par Intlayer, veuillez consulter la documentation sur l'intérêt d'Intlayer.
Pour des benchmarks de performance et des comparaisons détaillés, consultez :
Rapport de benchmark Next.jsComparez les bibliothèques d'internationalisation (i18n) pour Next.js comme next-intl, next-i18next et Intlayer. Rapport de performance détaillé sur la taille du bundle, les fuites et la réactivité.Suite de benchmarks i18nDécouvrez comment Intlayer se compare aux autres bibliothèques i18n en termes de performance et de taille de bundle.i18next vs @intlayer/i18nextCe qui change lorsqu'une application React ou Next.js conserve ses appels à i18next, react-i18next et next-i18next mais les exécute via les adaptateurs @intlayer/i18next. JavaScript par page, taille des composants, fuite de chaînes et hydratation mesurés sur le même code, ainsi que ce que les adaptateurs conservent, ignorent et ne peuvent pas remplacer.Adaptateur de compatibilité @intlayer/next-i18nextApprenez à migrer votre application Next.js de next-i18next vers Intlayer en utilisant l'adaptateur de compatibilité.
Sponsor
Une fois que vous avez des namespaces comme common.json et about.json typés via la module augmentation d'i18next, vous avez de fait défini un schéma de contenu. La question suivante est de savoir où vit ce schéma et qui le modifie. Sanity le traite comme un élément de premier plan : vous modélisez les champs, les références et la validation dans le code, et les éditeurs travaillent sur ce même modèle dans Sanity Studio au lieu de modifier du JSON à la main pour chaque locale.
Le contenu vit dans le Content Lake sous forme de JSON structuré, interrogeable via GROQ et servi par API, la locale étant un champ plutôt qu'un dossier. Pour une configuration Next.js App Router, vous pouvez récupérer un namespace côté serveur, le passer à votre provider i18n exactement comme ce pattern l'attend, et laisser la même source alimenter les applications, les emails et les agents. À mesure que les locales et les surfaces se multiplient, le schéma reste le contrat ; la couche de diffusion reste i18next.
Commentaires
Aucun commentaire pour le moment. Soyez le premier à partager vos pensées.
