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 des erreurs.
- Bénéficier de fonctionnalités avancées, comme la détection dynamique de la locale et son changement.
- Activer le 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é :
Copier le code dans le presse-papiers
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
- 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
Inclut 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, // Vos autres langues ], },};export default config;
Grâce à ce fichier de configuration, vous pouvez configurer des 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, référez-vous à 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 { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ reactRouter(), tsconfigPaths(), intlayerPlugin(), intlayerMiddlewarePlugin(), ],});
Le plugin Vite intlayerPlugin() 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 à chaque locale :
Mise en page racine
Copier le code dans le presse-papiers
// src/routes/{-$locale}/route.tsximport { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale}> <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({ en: "About", es: "Acerca de", fr: "À propos", }), home: t({ en: "Accueil", es: "Inicio", fr: "Accueil", }), }, meta: { description: t({ en: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", }), }, title: t({ en: "Bienvenue à 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 correspondent à l'extension de fichier de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
Pour plus de détails, consultez la documentation sur la déclaration de contenu.
Étape 7 : Créer 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
// src/components/localized-link.tsx// eslint-disable-next-line no-restricted-importsimport { Link, type LinkProps } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedLinkProps = { to: string;} & Omit<LinkProps, "to">;export function LocalizedLink(props: LocalizedLinkProps) { const { locale } = useLocale(); const isExternal = (to: string) => { return /^(https?:)?\/\//.test(to); }; const to = isExternal(props.to) ? props.to : getLocalizedUrl(props.to, locale); return <Link {...props} to={to as LinkProps["to"]} />;}
Créez un hook useLocalizedNavigate pour la navigation programmatique :
Copier le code dans le presse-papiers
// src/hooks/useLocalizedNavigate.tsx// eslint-disable-next-line no-restricted-importsimport { NavigateOptions, useNavigate } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedNavigateOptions = { to: string;} & Omit<NavigateOptions, "to">;export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const isExternal = (to: string) => { return /^(https?:)?\/\//.test(to); }; const localizedNavigate = (options: LocalizedNavigateOptions) => { const to = isExternal(options.to) ? options.to : getLocalizedUrl(options.to, locale); navigate({ ...options, to: to as NavigateOptions["to"] }); }; return localizedNavigate;};
Étape 8 : Utilisez Intlayer dans vos pages
Accédez à vos dictionnaires de contenu dans toute votre application :
Page de redirection racine
Copier le code dans le presse-papiers
// src/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() { const { locale } = useLocale(); return <Navigate replace to={locale} />;}
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 className="grid place-items-center h-screen"> <div className="flex flex-col gap-4 items-center text-center"> {content.title} <LocaleSwitcher /> <div className="flex gap-4"> <a href="/">Index</a> <LocalizedLink to="/">{content.links.home}</LocalizedLink> <LocalizedLink to="/about">{content.links.about}</LocalizedLink> </div> <div className="flex gap-4"> <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 { useLocation } from "@tanstack/react-router";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";export default function LocaleSwitcher() { const { pathname, searchStr } = useLocation(); const content = useIntlayer("locale-switcher"); const { availableLocales, locale, setLocale } = useLocale({ onLocaleChange: (newLocale) => { const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale); location.replace(pathWithLocale); }, }); return ( <select aria-label={content.label.toString()} onChange={(e) => setLocale(e.target.value)} value={locale} > {availableLocales.map((localeItem) => ( <option dir={getHTMLTextDir(localeItem)} key={localeItem} lang={localeItem} value={localeItem} > {/* Exemple : Français (French) */} {getLocaleName(localeItem, locale)} ( {getLocaleName(localeItem, Locales.ENGLISH)}) </option> ))} </select> );}
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 { configuration } from "intlayer";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 { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
Étape 11 : Construisez et lancez votre application
Construisez les dictionnaires de contenu et lancez votre application :
Copier le code dans le presse-papiers
# Construire les dictionnaires Intlayernpm run intlayer:build# Démarrer le serveur de développementnpm run dev
É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
{ compilerOptions: { // ... vos configurations TypeScript 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 dans votre fichier .gitignore :
Copier le code dans le presse-papiers
# Ignorer les fichiers générés par Intlayer.intlayer
Étape 13 : Créer une redirection (Optionnel)
Copier le code dans le presse-papiers
function LayoutComponent() { useI18nHTMLAttributes(); const { locale } = Route.useParams(); const { locale: selectedLocale } = useLocale(); const { defaultLocale } = configuration.internationalization; const { prefixDefault } = configuration.middleware; // Rediriger vers la locale par défaut si aucune locale n'est présente dans l'URL lorsque prefixDefault est vrai if (selectedLocale === defaultLocale && !locale && prefixDefault) { return <Navigate replace to={defaultLocale} />; } // Rediriger vers la locale sélectionnée si la locale dans l'URL ne correspond pas à la locale sélectionnée if (selectedLocale !== defaultLocale && !locale) { return <Navigate replace to={selectedLocale} />; } return ( <IntlayerProvider locale={locale}> <Outlet /> </IntlayerProvider> );}
Déploiement en Production
Lors du déploiement de votre application :
Construisez votre application :
bashCopier le codeCopier le code dans le presse-papiers
npm run build
Générez les dictionnaires Intlayer :
bashCopier le codeCopier le code dans le presse-papiers
npm run intlayer:build
Déplacez vite-intlayer dans les dépendances si vous utilisez le middleware en production :
bashCopier le codeCopier le code dans le presse-papiers
npm install vite-intlayer --save
Votre application prendra désormais en charge :
- Structure des URL : /en, /en/about, /tr, /tr/about
- Détection automatique de la langue basée sur les préférences du navigateur
- Routage sensible à la langue avec Tanstack Start
- Support TypeScript avec des types générés automatiquement
- Rendu côté serveur avec une gestion correcte de la langue
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 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 Intlayer 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
- Documentation Intlayer
- Documentation Tanstack Start
- Hook useIntlayer
- Hook useLocale
- Déclaration de contenu
- Configuration
Ce guide complet vous 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 |