Posez votre question et obtenez un résumé du document en referencant cette page et le Provider AI de votre choix
En intégrant le serveur MCP Intlayer à votre assistant AI, vous pouvez récupérer tous les documents directement depuis ChatGPT, DeepSeek, Cursor, VSCode, etc.
Voir la documentation du serveur MCPLe 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
Prise en main de l'internationalisation (i18n) avec Intlayer et Tanstack Start
Ce guide montre comment intégrer Intlayer pour une internationalisation fluide dans les projets Tanstack Start avec un routage sensible à la locale, la prise en charge de TypeScript et des pratiques de développement modernes.
Qu'est-ce qu'Intlayer ?
Intlayer est une bibliothèque d'internationalisation (i18n) innovante et open-source, conçue pour simplifier la prise en charge multilingue dans les applications web modernes.
Avec Intlayer, vous pouvez :
- Gérer facilement les traductions en utilisant des dictionnaires déclaratifs au niveau des composants.
- Localiser dynamiquement les métadonnées, les routes et le contenu.
- Assurer la prise en charge de TypeScript avec des types générés automatiquement, améliorant l'autocomplétion et la détection d'erreurs.
- Bénéficier de fonctionnalités avancées, telles que la détection et le changement dynamique de la locale.
- Activer un routage sensible à la locale avec le système de routage basé sur les fichiers de Tanstack Start.
Guide étape par étape pour configurer Intlayer dans une application Tanstack Start
Étape 1 : Créer le projet
Commencez par créer un nouveau projet TanStack Start en suivant le guide Démarrer un nouveau projet sur le site de TanStack Start.
Étape 2 : Installer les packages Intlayer
Installez les packages nécessaires en utilisant votre gestionnaire de paquets préféré :
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
intlayer
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.
Étape 3 : Configuration de votre projet
Créez un fichier de configuration pour configurer les langues de votre application :
Copier le code dans le presse-papiers
import type { IntlayerConfig } from "intlayer";import { 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 URL 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.
Étape 4 : Intégrer Intlayer dans votre configuration Vite
Ajoutez le plugin intlayer dans votre configuration :
Copier le code dans le presse-papiers
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [reactRouter(), tsconfigPaths(), intlayer()],});
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.
Étape 5 : Créez les composants de mise en page
Configurez votre mise en page racine et les mises en page spécifiques aux locales :
Mise en page racine
Copier le code dans le presse-papiers
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { const { defaultLocale } = useLocale(); const { locale } = Route.useParams(); return ( <IntlayerProvider locale={defaultLocale}> <Outlet /> </IntlayerProvider> );}
Étape 6 : Déclarez votre contenu
Créez et gérez vos déclarations de contenu pour stocker les traductions :
Copier le code dans le presse-papiers
import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = { content: { links: { about: t({ fr: "À propos", en: "About", es: "Acerca de", }), home: t({ fr: "Accueil", en: "Home", es: "Inicio", }), }, meta: { description: t({ fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", en: "This is an example of using Intlayer with TanStack Router", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", }), }, title: t({ fr: "Bienvenue à Intlayer + TanStack Router", en: "Welcome to Intlayer + TanStack Router", es: "Bienvenido a Intlayer + TanStack Router", fr: "Bienvenue à Intlayer + TanStack Router", }), }, key: "app",} satisfies Dictionary;export default appContent;
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 elles doivent correspondre à l'extension de fichier des déclarations de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
Pour plus de détails, référez-vous à la documentation des déclarations de contenu.
Étape 7 : Créez des composants et hooks sensibles à la locale
Créez un composant LocalizedLink pour une navigation sensible à la locale :
Copier le code dans le presse-papiers
import type { FC } from "react";import { Link, type LinkComponentProps } from "@tanstack/react-router";import { useLocale } from "react-intlayer";export const LOCALE_ROUTE = "{-$locale}" as const;// Utilitaire principalexport type RemoveLocaleParam<T> = T extends string ? RemoveLocaleFromString<T> : T;export type To = RemoveLocaleParam<LinkComponentProps["to"]>;type CollapseDoubleSlashes<S extends string> = S extends `${infer H}//${infer T}` ? CollapseDoubleSlashes<`${H}/${T}`> : S;type LocalizedLinkProps = { to?: To;} & Omit<LinkComponentProps, "to">;// Helperstype RemoveAll< S extends string, Sub extends string,> = S extends `${infer H}${Sub}${infer T}` ? RemoveAll<`${H}${T}`, Sub> : S;type RemoveLocaleFromString<S extends string> = CollapseDoubleSlashes< RemoveAll<S, typeof LOCALE_ROUTE>>;export const LocalizedLink: FC<LocalizedLinkProps> = (props) => { const { locale } = useLocale(); return ( <Link {...props} params={{ locale, ...(typeof props?.params === "object" ? props?.params : {}), }} to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]} /> );};
Ce composant a deux objectifs :
- Supprimer le préfixe {-$locale} inutile de l'URL.
- Injecter le paramètre de locale dans l'URL pour garantir que l'utilisateur est directement redirigé vers la route localisée.
Ensuite, nous pouvons créer un hook useLocalizedNavigate pour la navigation programmatique :
Copier le code dans le presse-papiers
import { useLocale } from "react-intlayer";import { useNavigate } from "@tanstack/react-router";import { LOCALE_ROUTE } from "@/components/localized-link";import type { FileRouteTypes } from "@/routeTree.gen";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); type StripLocalePrefix<T extends string> = T extends | `/${typeof LOCALE_ROUTE}` | `/${typeof LOCALE_ROUTE}/` ? "/" : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}` ? `/${Rest}` : never; type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>; interface LocalizedNavigate { (to: LocalizedTo): ReturnType<typeof navigate>; ( opts: { to: LocalizedTo } & Record<string, unknown> ): ReturnType<typeof navigate>; } const localizedNavigate: LocalizedNavigate = (args: any) => { if (typeof args === "string") { return navigate({ to: `/${LOCALE_ROUTE}${args}`, params: { locale } }); } const { to, ...rest } = args; const localedTo = `/${LOCALE_ROUTE}${to}` as any; return navigate({ to: localedTo, params: { locale, ...rest } as any }); }; return localizedNavigate;};
Étape 8 : Utilisez Intlayer dans vos pages
Accédez à vos dictionnaires de contenu dans toute votre application :
Page d'accueil localisée
Copier le code dans le presse-papiers
import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";import { useIntlayer } from "react-intlayer";import LocaleSwitcher from "@/components/locale-switcher";import { LocalizedLink } from "@/components/localized-link";import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: ({ params }) => { const { locale } = params; const metaContent = getIntlayer("app", locale); return { meta: [ { title: metaContent.title }, { content: metaContent.meta.description, name: "description" }, ], }; },});function RouteComponent() { const content = useIntlayer("app"); const navigate = useLocalizedNavigate(); return ( <div> <div> {content.title} <LocaleSwitcher /> <div> <LocalizedLink to="/">{content.links.home}</LocalizedLink> <LocalizedLink to="/about">{content.links.about}</LocalizedLink> </div> <div> <button onClick={() => navigate({ to: "/" })}> {content.links.home} </button> <button onClick={() => navigate({ to: "/about" })}> {content.links.about} </button> </div> </div> </div> );}
Pour en savoir plus sur le hook useIntlayer, consultez la documentation.
Étape 9 : Créer un composant de changement de langue
Créez un composant pour permettre aux utilisateurs de changer de langue :
Copier le code dans le presse-papiers
import type { FC } from "react";import { useLocation } from "@tanstack/react-router";import { getHTMLTextDir, getLocaleName, getPathWithoutLocale } from "intlayer";import { setLocaleCookie, useIntlayer, useLocale } from "react-intlayer";import { LocalizedLink, To } from "./localized-link";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeEl) => ( <li key={localeEl}> <LocalizedLink aria-current={localeEl === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeEl)}`} onClick={() => setLocaleCookie(localeEl)} params={{ locale: localeEl }} to={pathWithoutLocale as To} > <span> {/* Locale - ex. FR */} {localeItem} </span> <span> {/* Langue dans sa propre locale - ex. Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Langue dans la locale courante - ex. Francés avec la locale courante définie sur Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Langue en anglais - ex. French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </LocalizedLink> </li> ))} </ol> );};
Pour en savoir plus sur le hook useLocale, consultez la documentation.
Étape 10 : Ajouter la gestion des attributs HTML (Optionnel)
Créez un hook pour gérer les attributs lang et dir du HTML :
Copier le code dans le presse-papiers
// src/hooks/useI18nHTMLAttributes.tsximport { 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]);};
Ensuite, utilisez-le dans votre composant racine :
Copier le code dans le presse-papiers
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // importer le hookexport const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { useI18nHTMLAttributes(); // ajouter cette ligne const { defaultLocale } = useLocale(); const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale ?? defaultLocale}> <Outlet /> </IntlayerProvider> );}
Étape 11 : Ajouter un middleware (Optionnel)
Vous pouvez également utiliser le intlayerMiddleware 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 intlayerMiddleware en production, vous devez déplacer le paquet vite-intlayer de devDependencies vers dependencies.
Copier le code dans le presse-papiers
import { reactRouter } from "@react-router/dev/vite";import tailwindcss from "@tailwindcss/vite";import { defineConfig } from "vite";import { intlayer, intlayerMiddleware } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ tailwindcss(), reactRouter(), tsconfigPaths(), intlayer(), intlayerMiddleware(), ],});
Étape 12 : Configurer TypeScript (Optionnel)
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 :
Copier le code dans le presse-papiers
{ // ... 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 committer dans votre dépôt Git.
Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier .gitignore :
Copier le code dans le presse-papiers
# 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 :
- Autocomplétion pour les clés de traduction.
- Détection d’erreurs en temps réel pour les traductions manquantes.
- Aperçus en ligne du contenu traduit.
- 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 VS Code Intlayer.
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
- Documentation Intlayer
- Documentation Tanstack Start
- Hook useIntlayer
- Hook useLocale
- Déclaration de contenu
- Configuration
Ce guide complet fournit tout ce dont vous avez besoin pour intégrer Intlayer avec Tanstack Start afin de créer une application entièrement internationalisée avec un routage sensible à la locale et une prise en charge de TypeScript.
Historique de la documentation
Version | Date | Modifications |
---|---|---|
5.8.1 | 2025-09-09 | Ajout pour Tanstack Start |