Creation:2025-12-07Last update:2026-05-31

    Traduire votre React Router v7 (File-System Routes) avec Intlayer | Internationalisation (i18n)

    Ce guide montre comment intégrer Intlayer pour une internationalisation fluide dans les projets React Router v7 en utilisant un routage basé sur le système de fichiers (@react-router/fs-routes) avec un routage sensible à la locale, la prise en charge de TypeScript, et des pratiques de développement modernes.

    Pour le routage côté client, consultez le guide Intlayer avec React Router v7.

    Table des matières

    Pourquoi Intlayer plutôt que des alternatives ?

    Par rapport aux solutions principales telles que react-i18next ou i18next, Intlayer est une solution dotée d'optimisations intégrées telles que :

    Intlayer est optimisé pour fonctionner parfaitement avec React Router en offrant un routage compatible avec les paramètres régionaux, un middleware pour la détection des paramètres régionaux et toutes les fonctionnalités nécessaires à la mise à l'échelle de l'internationalisation (i18n).

    Au lieu de charger de lourds fichiers JSON dans vos pages, ne chargez que le contenu strictement nécessaire. Intlayer vous aide à réduire la taille de votre bundle et de vos pages jusqu'à 50 %.

    Déclarer le contenu directement au plus près de vos composants facilite la maintenance des applications de grande envergure. Vous pouvez dupliquer ou supprimer le dossier d'une fonctionnalité sans le fardeau mental de devoir passer en revue toute votre base de code de contenu. De plus, Intlayer est entièrement typé pour garantir l'exactitude de vos traductions.

    La colocalisation du contenu réduit le contexte nécessaire aux grands modèles de langage (LLM). Intlayer est également livré avec une suite d'outils, tels qu'une CLI pour vérifier les traductions manquantes, un LSP, un MCP et des agent skills, afin de rendre l'expérience développeur (DX) encore plus fluide pour les agents IA.

    Automatisez les traductions dans votre pipeline CI/CD en utilisant le LLM de votre choix au coût de votre propre fournisseur d'IA. Intlayer propose également un compilateur pour automatiser l'extraction de contenu, ainsi qu'une plateforme web pour vous aider à traduire en arrière-plan.

    Associer de gros fichiers JSON à vos composants peut ralentir les performances et impacter la réactivité. Intlayer optimise le chargement du contenu directement au moment du build.

    Bien plus qu'une simple solution i18n, Intlayer propose un éditeur visuel auto-hébergé et un CMS complet pour gérer votre contenu multilingue en temps réel. Cela rend la collaboration avec les traducteurs, concepteurs-rédacteurs et autres membres de l'équipe extrêmement simple. Le contenu peut être stocké localement et/ou à distance.

    Guide étape par étape pour configurer Intlayer dans une application React Router v7 avec des routes basées sur le système de fichiers

    www.youtube.com

    Voir le Modèle d'Application sur GitHub.

    1. Installer les dépendances

      Installez les paquets nécessaires en utilisant votre gestionnaire de paquets préféré :

      bash
      npm install intlayer react-intlayernpm install vite-intlayer --save-devnpm install @react-router/fs-routes --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 une application React. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation dans React.

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

      • @react-router/fs-routes Le package qui active le routage basé sur le système de fichiers pour React Router v7.

    2. Configuration de votre projet

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

      intlayer.config.ts
      import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

export default config;
      Grâce à ce fichier de configuration, vous pouvez configurer les URLs localisées, la redirection via 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 bien plus encore. Pour une liste complète des paramètres disponibles, consultez la documentation de configuration.

    3. Intégrer Intlayer dans votre configuration Vite

      Ajoutez le plugin intlayer dans votre configuration :

      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [reactRouter(), intlayer()],});
      Le plugin Vite intlayer() est utilisé pour intégrer Intlayer avec Vite. Il assure la génération 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.

    4. Configurer les routes basées sur le système de fichiers de React Router v7

      Configurez votre routage pour utiliser des routes basées sur le système de fichiers avec flatRoutes :

      app/routes.ts
      import type { RouteConfig } from "@react-router/dev/routes";import { flatRoutes } from "@react-router/fs-routes";import { configuration } from "intlayer";const routes: RouteConfig = flatRoutes({  // Ignorer les fichiers de déclaration de contenu pour qu'ils ne soient pas traités comme des routes  ignoredRouteFiles: configuration.content.fileExtensions.map(    (fileExtension) => `**/*${fileExtension}`  ),});export default routes;
      La fonction flatRoutes de @react-router/fs-routes active le routage basé sur le système de fichiers, où la structure des fichiers dans le répertoire routes/ détermine les routes de votre application. L'option ignoredRouteFiles garantit que les fichiers de déclaration de contenu Intlayer (.content.ts, etc.) ne sont pas traités comme des fichiers de route.

    5. Créer des fichiers de route avec les conventions du système de fichiers

      Avec le routage basé sur le système de fichiers, vous utilisez une convention de nommage plate où les points (.) représentent les segments de chemin et les parenthèses () désignent les segments optionnels.

      Créez les fichiers suivants dans votre répertoire app/routes/ :

      Structure des fichiers

      bash
      app/├── root.tsx                         # Wrapper de mise en page pour les routes de locale└──routes/    ├── ($locale)._index.tsx         # Page d'accueil (/, /es, etc.)    ├── ($locale)._index.content.ts  # Contenu de la page d'accueil    ├── ($locale).about.tsx          # Page À propos (/about, /es/about, etc.)    └── ($locale).about.content.ts   # Contenu de la page À propos

      Les conventions de nommage :

      • ($locale) - Segment dynamique optionnel pour le paramètre de locale
      • _layout - Route de mise en page qui enveloppe les routes enfants
      • _index - Route d'index (s'affiche au chemin parent)
      • . (point) - Sépare les segments de chemin (par exemple, ($locale).about → /:locale?/about)

      Composant de mise en page

      app/root.tsx
      import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import {  isRouteErrorResponse,  Meta,  Outlet,  Scripts,  ScrollRestoration,  useLoaderData,} from "react-router";import type { Route } from "./+types/root";import "./app.css";// links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) {  const locale = getLocaleFromPath(request.url);  return { locale };}export function Layout({  children,}: { children: React.ReactNode } & Route.ComponentProps) {  const data = useLoaderData<typeof loader>();  const { locale } = data ?? {};  return (    <html lang={locale}>      <head>        <meta charSet="utf-8" />        <meta content="width=device-width, initial-scale=1" name="viewport" />        <Meta />        <Links />      </head>      <body>        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>        <ScrollRestoration />        <Scripts />      </body>    </html>  );}

      Page d'index

      app/routes/($locale)._index.tsx
      import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale)._index";export const loader = ({ params }: Route.LoaderArgs) => {  const { locale } = params;  const { isValid } = validatePrefix(locale);  if (!isValid) {    throw data("Locale not supported", { status: 404 });  }};export const meta: Route.MetaFunction = ({ params }) => {  const content = getIntlayer("page", params.locale);  return [    { title: content.title },    { content: content.description, name: "description" },  ];};export default function Page() {  const { title, description, aboutLink } = useIntlayer("page");  return (    <div>      <h1>{title}</h1>      <p>{description}</p>      <nav>        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>      </nav>    </div>  );}

      Page À propos

      app/routes/($locale).about.tsx
      import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale).about";export const loader = ({ params }: Route.LoaderArgs) => {  const { locale } = params;  const { isValid } = validatePrefix(locale);  if (!isValid) {    throw data("Locale not supported", { status: 404 });  }};export const meta: Route.MetaFunction = ({ params }) => {  const content = getIntlayer("about", params.locale);  return [    { title: content.title },    { content: content.description, name: "description" },  ];};export default function AboutPage() {  const { title, content, homeLink } = useIntlayer("about");  return (    <div>      <h1>{title}</h1>      <p>{content}</p>      <nav>        <LocalizedLink to="/">{homeLink}</LocalizedLink>      </nav>    </div>  );}

    6. Déclarez votre contenu

      Créez et gérez vos déclarations de contenu pour stocker les traductions. Placez les fichiers de contenu à côté de vos fichiers de route :

      app/routes/($locale)._index.content.ts
      import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    title: t({      en: "Welcome to React Router v7 + Intlayer",      es: "Bienvenido a React Router v7 + Intlayer",      fr: "Bienvenue sur React Router v7 + Intlayer",    }),    description: t({      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",    }),    aboutLink: t({      en: "Learn About Us",      es: "Aprender Sobre Nosotros",      fr: "En savoir plus sur nous",    }),  },} satisfies Dictionary;export default pageContent;
      app/routes/($locale).about.content.ts
      import { t, type Dictionary } from "intlayer";const aboutContent = {  key: "about",  content: {    title: t({      en: "About Us",      es: "Sobre Nosotros",      fr: "À propos de nous",    }),    content: t({      en: "This is the about page content.",      es: "Este es el contenido de la página de información.",      fr: "Ceci est le contenu de la page à propos.",    }),    homeLink: t({      en: "Home",      es: "Inicio",      fr: "Accueil",    }),  },} satisfies Dictionary;export default aboutContent;
      Vos déclarations de contenu peuvent être définies n'importe où dans votre application dès qu'elles sont incluses dans le répertoire contentDir (par défaut, ./app). Et correspondent à l'extension des fichiers de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Pour plus de détails, référez-vous à la documentation sur la déclaration de contenu.
      Si votre application existe déjà, vous pouvez utiliser le Compilateur Intlayer, ainsi que la commande d'extraction, pour transformer des milliers de composants en une seconde.

    7. Créez des composants sensibles à la locale

      Créez un composant LocalizedLink pour la navigation sensible à la locale :

      app/components/localized-link.tsx
      import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);// Vérifie si le lien est externeexport const locacalizeTo = (to: To, locale: LocalesValues): To => {  if (typeof to === "string") {    if (isExternalLink(to)) {      return to;    }    return getLocalizedUrl(to, locale);  }  if (isExternalLink(to.pathname ?? "")) {    return to;  }  return {    ...to,    pathname: getLocalizedUrl(to.pathname ?? "", locale),  };};// Composant LocalizedLink pour la navigation localeexport const LocalizedLink: FC<LinkProps> = (props) => {  const { locale } = useLocale();  return <Link {...props} to={locacalizeTo(props.to, locale)} />;};

      Dans le cas où vous souhaitez naviguer vers les routes localisées, vous pouvez utiliser le hook useLocalizedNavigate :

      app/hooks/useLocalizedNavigate.ts
      import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => {  const navigate = useNavigate();  const { locale } = useLocale();  const localizedNavigate = (to: To, options?: NavigateOptions) => {    const localedTo = locacalizeTo(to, locale);    navigate(localedTo, options);  };  return localizedNavigate;};

    8. Créer un composant de changement de langue

      Créez un composant pour permettre aux utilisateurs de changer de langue :

      app/components/locale-switcher.tsx
      import type { FC } from "react";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  getPathWithoutLocale,  Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => {  const { localeSwitcherLabel } = useIntlayer("locale-switcher");  const { pathname } = useLocation();  const { availableLocales, locale } = useLocale();  const pathWithoutLocale = getPathWithoutLocale(pathname);  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <Link            aria-current={localeItem === locale ? "page" : undefined}            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}            reloadDocument // Recharger la page pour appliquer la nouvelle locale            to={getLocalizedUrl(pathWithoutLocale, localeItem)}          >            <span>              {/* Locale - par exemple FR */}              {localeItem}            </span>            <span>              {/* Langue dans sa propre locale - par exemple Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Langue dans la locale actuelle - par exemple Francés avec la locale actuelle définie sur Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Langue en anglais - par exemple French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        </li>      ))}    </ol>  );};
      Pour en savoir plus sur le hook useLocale, consultez la documentation.

    9. Ajouter la gestion des attributs HTML

      Créez un hook pour gérer les attributs lang et dir du HTML :

      app/hooks/useI18nHTMLAttributes.tsx
      import { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

      Ce hook est déjà utilisé dans le composant de mise en page (root.tsx) montré à l'Étape 5.

    10. Extraire le contenu de vos composants

      Facultatif

      Si vous avez une base de code existante, transformer des milliers de fichiers peut prendre beaucoup de temps.

      Pour faciliter ce processus, Intlayer propose un compilateur / extracteur pour transformer vos composants et extraire le contenu.

      Pour le configurer, vous pouvez ajouter une section compiler dans votre fichier intlayer.config.ts :

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Reste de votre configuration
  compiler: {
    /**
     * Indique si le compilateur doit être activé.
     */
    enabled: true,

    /**
     * Définit le chemin des fichiers de sortie
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 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,

    /**
     * Préfixe de clé de dictionnaire
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Exécutez l'extracteur pour transformer vos composants et extraire le contenu

      bash
      npx intlayer extract

    Configurer TypeScript

    Intlayer utilise l'augmentation de module pour tirer parti des avantages de TypeScript et renforcer votre base de code.

    Autocomplétion

    Erreur de traduction

    Assurez-vous que votre configuration TypeScript inclut les types générés automatiquement :

    tsconfig.json
    {  // ... vos configurations existantes  include: [    // ... vos configurations existantes    ".intlayer/**/*.ts", // Inclure les types générés automatiquement  ],}

    Configuration de 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 :

    .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'extension officielle Intlayer VS Code Extension.

    Installer depuis le Marketplace VS Code

    Cette extension fournit :

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

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

    Aller plus loin

    Pour aller plus loin, vous pouvez implémenter l'éditeur visuel ou externaliser votre contenu en utilisant le CMS.

    Références de Documentation

    Ce guide complet vous fournit tout ce dont vous avez besoin pour intégrer Intlayer avec React Router v7 en utilisant un routage basé sur le système de fichiers pour obtenir une application entièrement internationalisée avec un routage sensible à la locale et une prise en charge de TypeScript.

    1. Ajouter un middleware

      Vous pouvez également utiliser le intlayerProxy pour ajouter un routage côté serveur à votre application. Ce plugin détectera automatiquement la locale actuelle en fonction de l'URL et définira le cookie de locale approprié. Si aucune locale n'est spécifiée, le plugin déterminera la locale la plus appropriée en fonction des préférences linguistiques du navigateur de l'utilisateur. Si aucune locale n'est détectée, il redirigera vers la locale par défaut.

      Notez que pour utiliser le intlayerProxy en production, vous devez déplacer le package vite-intlayer de devDependencies vers dependencies.
      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    reactRouter(),    intlayer(),  ],});

    Configurer TypeScript

    Intlayer utilise l'augmentation de module pour bénéficier de TypeScript et renforcer votre base de code.

    Assurez-vous que votre configuration TypeScript inclut les types générés automatiquement :

    tsconfig.json
    {  // ... vos configurations existantes  include: [    // ... vos inclusions existantes    ".intlayer/**/*.ts", // Inclure les types générés automatiquement  ],}

    Configuration Git

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

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

    .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’extension officielle Intlayer pour VS Code.

    Installer depuis le Marketplace VS Code

    Cette extension offre :

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

    Pour plus de détails sur l’utilisation de l’extension, consultez la documentation de l’extension Intlayer pour VS Code.

    Aller plus loin

    Pour aller plus loin, vous pouvez implémenter l’éditeur visuel ou externaliser votre contenu en utilisant le CMS.

    Références de la documentation

    Ce guide complet vous fournit tout ce dont vous avez besoin pour intégrer Intlayer avec React Router v7 afin d’obtenir une application entièrement internationalisée avec un routage sensible à la locale et une prise en charge de TypeScript.

    React Router v7
    Compiler