Comment rendre multilingue (i18n) une application Vite et React existante après coup (guide i18n 2026)

Voir le Modèle d'application sur GitHub.

Table des matières

Pourquoi est-il difficile d'internationaliser une application existante ?

Si vous avez déjà essayé d'ajouter plusieurs langues à une application conçue pour une seule, vous connaissez la douleur. Ce n'est pas seulement « difficile », c'est fastidieux. Vous devez passer au peigne fin chaque fichier, traquer chaque chaîne de texte et les déplacer dans des fichiers de dictionnaire séparés.

Vient ensuite la partie risquée : remplacer tout ce texte par des hooks de code sans casser votre mise en page ou votre logique. C'est le genre de travail qui interrompt le développement de nouvelles fonctionnalités pendant des semaines et ressemble à un refactoring sans fin.

Qu'est-ce que l'Intlayer Compiler ?

L'Intlayer Compiler a été conçu pour éviter ce travail manuel ingrat. Au lieu que vous extrayiez manuellement les chaînes, le compilateur le fait pour vous. Il scanne votre code, trouve le texte et utilise l'IA pour générer les dictionnaires en coulisses. Ensuite, il modifie votre code pendant le build pour injecter les hooks i18n nécessaires. Fondamentalement, vous continuez à écrire votre application comme s'il s'agissait d'une application unilingue, et le compilateur gère automatiquement la transformation multilingue.

Doc Compiler : /fr/doc/compiler

Limitations

Parce que le compilateur effectue l'analyse et la transformation du code (insertion de hooks et génération de dictionnaires) au moment de la compilation, il peut ralentir le processus de build de votre application.

Pour atténuer cet impact pendant le développement, vous pouvez configurer le compilateur pour qu'il s'exécute en mode 'build-only' ou le désactiver lorsque vous n'en avez pas besoin.

Guide étape par étape pour configurer Intlayer dans une application Vite et React

Étape 1 : Installer les dépendances

Installez les packages nécessaires avec npm :

npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer Le package principal qui fournit des outils d'internationalisation pour la gestion de la configuration, la traduction, la déclaration de contenu, la transpilation et les commandes CLI.

• react-intlayer Le package qui intègre Intlayer avec l'application React. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation de React.

• vite-intlayer Comprend le plugin Vite pour intégrer Intlayer avec le bundler Vite, ainsi qu'un middleware pour détecter la langue préférée de l'utilisateur, gérer les cookies et gérer la redirection d'URL.

Étape 2 : Configurer votre projet

Créez un fichier de configuration pour configurer les langues de votre application :

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  compiler: {    /**     * Indique si le compilateur doit être activé.     */    enabled: true,    /**     * Répertoire de sortie pour les dictionnaires optimisés.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Insérer uniquement le contenu dans le fichier généré, sans clé.     */    noMetadata: false,    /**     * Préfixe de clé de dictionnaire     */    dictionaryKeyPrefix: "", // Supprimer le préfixe de base    /**     * Indique si les composants doivent être sauvegardés après avoir été transformés.     * De cette façon, le compilateur peut être exécuté une seule fois pour transformer l'application, puis il peut être supprimé.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "This app is an map app", // Note : vous pouvez personnaliser cette description de l'application  },};export default config;

Note : Assurez-vous d'avoir votre OPEN_AI_API_KEY définie dans vos variables d'environnement.

Grâce à ce fichier de configuration, vous pouvez configurer des URL localisées, la redirection du middleware, les noms des cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et plus encore. Pour une liste complète des paramètres disponibles, reportez-vous à la documentation de configuration.

Étape 3 : Intégrer Intlayer dans votre configuration Vite

Ajoutez le plugin intlayer dans votre configuration.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerCompiler } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerCompiler()],});

Le plugin Vite intlayer() est utilisé pour intégrer Intlayer avec Vite. Il assure la construction des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement Intlayer au sein de l'application Vite. De plus, il fournit des alias pour optimiser les performances.

Le plugin Vite intlayerCompiler() est utilisé pour extraire le contenu des composants et écrire des fichiers .content.

Étape 4 : Compiler votre code

Écrivez simplement vos composants avec des chaînes codées en dur dans votre langue par défaut. Le compilateur s'occupe du reste.

Exemple de ce à quoi pourrait ressembler votre page :

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt="Vite logo" />       </a>       <a href="https://react.dev" target="_blank">         <img src={reactLogo} className="logo react" alt="React logo" />       </a>     </div>     <h1>Vite + React</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         count is {count}       </button>       <p>         Edit <code>src/App.tsx</code> and save to test HMR       </p>     </div>     <p className="read-the-docs">       Click on the Vite and React logos to learn more     </p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

{ key: "app-content", content: {   nodeType: "translation",   translation: {     en: {       viteLogo: "Vite logo",       reactLogo: "React logo",       title: "Vite + React",       countButton: "count is",       editMessage: "Edit",       hmrMessage: "and save to test HMR",       readTheDocs: "Click on the Vite and React logos to learn more",     },     fr: {       viteLogo: "Logo Vite",       reactLogo: "Logo React",       title: "Vite + React",       countButton: "compte est",       editMessage: "Modifier",       hmrMessage: "et enregistrer pour tester HMR",       readTheDocs: "Cliquez sur les logos Vite et React pour en savoir plus",     },   } }}

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app-content"); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt={content.viteLogo.value} />       </a>       <a href="https://react.dev" target="_blank">         <img           src={reactLogo}           className="logo react"           alt={content.reactLogo.value}         />       </a>     </div>     <h1>{content.title}</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         {content.countButton} {count}       </button>       <p>         {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}       </p>     </div>     <p className="read-the-docs">{content.readTheDocs}</p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

• IntlayerProvider est utilisé pour fournir la langue aux composants imbriqués.

(Facultatif) Étape 6 : Changer la langue de votre contenu

Pour changer la langue de votre contenu, vous pouvez utiliser la fonction setLocale fournie par le hook useLocale. Cette fonction vous permet de définir la langue de l'application et de mettre à jour le contenu en conséquence.

import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Change Language to English    </button>  );};

Pour en savoir plus sur le hook useLocale, reportez-vous à la documentation.

(Facultatif) Étape 7 : Remplir les traductions manquantes

Intlayer fournit un outil CLI pour vous aider à remplir les traductions manquantes. Vous pouvez utiliser la commande intlayer pour tester et remplir les traductions manquantes à partir de votre code.

npx intlayer test         # Tester s'il y a des traductions manquantes

npx intlayer fill         # Remplir les traductions manquantes

Pour plus de détails, consultez la documentation CLI

(Facultatif) Sitemap et robots.txt (génération au build)

Intlayer fournit des utilitaires - generateSitemap et getMultilingualUrls - pour produire un sitemap.xml multilingue et un robots.txt prêts pour les crawlers, que vous pouvez écrire automatiquement dans public/. En pratique, exécutez un petit script Node avant Vite (par exemple les hooks npm predev / prebuild) afin que ces fichiers soient présents au build ou au serveur de développement.

Sitemap

Le générateur de sitemap Intlayer tient compte de vos locales et ajoute les métadonnées attendues par les moteurs.

Le sitemap généré prend en charge l’espace de noms xhtml:link (extensions hreflang). Contrairement aux générateurs qui ne listent que des URL brutes, Intlayer relie de façon bidirectionnelle toutes les versions linguistiques d’une même page (par ex. /about, /fr/about ou /about?lang=fr selon votre mode de routage), ce qui aide les crawlers.

Robots.txt

Utilisez getMultilingualUrls pour que les règles Disallow couvrent toutes les variantes localisées des chemins sensibles.

1. Créer generate-seo.mjs à la racine du projet

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Le paquet intlayer doit être installé pour que le script puisse l’importer. Définissez SITE_URL dans l’environnement pour la production (par ex. en CI).

Préférez generate-seo.mjs pour l’ESM Node. Avec generate-seo.js, assurez-vous que "type": "module" est présent dans package.json, ou activez l’ESM côté Node.

2. Lancer le script avant Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Adaptez les commandes si vous utilisez pnpm ou yarn. Vous pouvez aussi appeler ce script depuis la CI ou une autre étape de votre pipeline.

Configuration Git

Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les committer dans votre dépôt Git.

Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier .gitignore :

# Ignorer les fichiers générés par Intlayer.intlayer

Extension VS Code

Pour améliorer votre expérience de développement avec Intlayer, vous pouvez installer l'officielle Extension Intlayer VS Code.

Installer depuis le VS Code Marketplace

Cette extension fournit :

• L'autocomplétion pour les clés de traduction.
• La détection d'erreurs en temps réel for les traductions manquantes.
• Des aperçus en ligne du contenu traduit.
• Des actions rapides pour créer et mettre à jour facilement des traductions.

Pour plus de détails sur l'utilisation de l'extension, reportez-vous à la documentation de l'extension Intlayer VS Code.

Aller plus loin

Pour aller plus loin, vous pouvez implémenter l'éditeur visuel ou externaliser votre contenu à l'aide du CMS.