Traduisez votre site Tanstack Start avec Intlayer | Internationalisation (i18n)

Table des matières

Ce guide montre comment intégrer Intlayer pour une internationalisation transparente dans les projets Tanstack Start avec un routage tenant compte de la locale, un support TypeScript et des pratiques de développement modernes.

Pourquoi Intlayer plutôt que des alternatives ?

Par rapport aux solutions principales telles que react-i18next ou next-intl, ou paraglide, Intlayer est une solution qui vient avec des optimisations intégrées telles que :

Guide étape par étape pour configurer Intlayer dans une application Tanstack Start

Voir le Modèle d'Application sur GitHub.

1. 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.

2. 2

   Installer les paquets Intlayer

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

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npx intlayer init --interactive
   

   l'indicateur --interactive est facultatif. Utilisez intlayer-cli init si vous êtes un agent IA.

   Cette commande détectera votre environnement et installera les packages requis. Par exemple :

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   npm install intlayer react-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

     Le paquet 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 paquet qui intègre Intlayer avec l'application React. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation React.

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

3. 3

   Configuration de votre projet

   Architecture

   Dans cette architecture, toutes les routes localisées sont imbriquées sous le segment de route {-$locale}. Cette approche garantit que chaque langue dispose d'une URL dédiée tout en permettant le préfixage automatique de la locale, la validation et l'optimisation SEO.

   bash

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   .
   ├── src
   │   ├── components
   │   │   ├── Header.tsx
   │   │   ├── locale-switcher.content.ts
   │   │   ├── locale-switcher.tsx
   │   │   └── localized-link.tsx
   │   ├── hooks
   │   │   ├── useI18nHTMLAttributes.tsx
   │   │   └── useLocalizedNavigate.ts
   │   ├── routes
   │   │   ├── {-$locale}
   │   │   │   ├── 404.content.ts
   │   │   │   ├── 404.tsx
   │   │   │   ├── about.content.ts
   │   │   │   ├── about.tsx
   │   │   │   ├── index.content.tsx
   │   │   │   ├── index.tsx
   │   │   │   └── route.tsx             # Locale layout & prefix validation
   │   │   ├── __root.tsx                # Root route with IntlayerProvider
   │   │   └── sitemap[.]xml.ts
   │   ├── router.tsx
   │   └── styles.css
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   Configuration

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

   intlayer.config.ts

   Copier le contenu

   Copier le code

   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;
   

   Via ce fichier de configuration, vous pouvez configurer les 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.

4. 4

   Intégrer Intlayer dans votre configuration Vite

   Ajoutez le plugin intlayer dans votre configuration :

   vite.config.ts

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { tanstackStart } from "@tanstack/react-start/plugin/vite";
   import viteReact from "@vitejs/plugin-react";
   import { nitro } from "nitro/vite";
   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   const config = defineConfig({
     plugins: [
       nitro(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
       tanstackStart({
         router: {
           routeFileIgnorePattern:
             ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
         },
       }),
       viteReact(),
     ],
   });
   
   export default config;
   

   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.

5. 5

   Créer le Layout Racine

   Configurez votre layout racine pour supporter l'internationalisation en utilisant useParams pour détecter la locale actuelle et en définissant les attributs lang et dir sur la balise html.

   src/routes/__root.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import {
     createRootRouteWithContext,
     getRouteApi,
     HeadContent,
     Scripts,
   } from "@tanstack/react-router";
   import { defaultLocale, getHTMLTextDir } from "intlayer";
   import { type ReactNode } from "react";
   import { IntlayerProvider } from "react-intlayer";
   
   const localeRoute = getRouteApi("/{-$locale}");
   
   export const Route = createRootRouteWithContext<{}>()({
     head: () => ({
       meta: [
         {
           charSet: "utf-8",
         },
         {
           content: "width=device-width, initial-scale=1",
           name: "viewport",
         },
         {
           title: "TanStack Start Starter",
         },
       ],
     }),
   
     shellComponent: RootDocument,
   });
   
   function RootDocument({ children }: { children: ReactNode }) {
     const params = localeRoute.useParams();
     const locale = params?.locale ?? defaultLocale;
   
     return (
       <html dir={getHTMLTextDir(locale)} lang={locale}>
         <head>
           <HeadContent />
         </head>
         <body>
           <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
           <Scripts />
         </body>
       </html>
     );
   }
   

6. 6

   Créer le Layout de Locale

   Créez un layout qui gère le préfixe de locale et effectue la validation.

   src/routes/{-$locale}/route.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
   import { validatePrefix } from "intlayer";
   
   export const Route = createFileRoute("/{-$locale}")({
     beforeLoad: ({ params }) => {
       const localeParam = params.locale;
   
       // Valider le préfixe de locale
       const { isValid, localePrefix } = validatePrefix(localeParam);
   
       if (!isValid) {
         throw redirect({
           to: "/{-$locale}/404",
           params: { locale: localePrefix },
         });
       }
     },
     component: Outlet,
   });
   

   Ici, {-$locale} est un paramètre de route dynamique qui est remplacé par la locale actuelle. Cette notation rend le slot optionnel, lui permettant de fonctionner avec des modes de routage tels que 'prefix-no-default', etc.

   Soyez conscient que ce slot peut causer des problèmes si vous utilisez plusieurs segments dynamiques dans la même route (ex: /{-$locale}/other-path/$anotherDynamicPath/...). Pour le mode 'prefix-all', vous préférerez peut-être passer le slot en $locale à la place. Pour les modes 'no-prefix' ou 'search-params', vous pouvez supprimer complètement le slot.

7. 7

   Déclarer votre contenu

   Créez et gérez vos déclarations de contenu pour stocker les traductions :

   src/contents/page.content.ts

   Copier le contenu

   Copier le code

   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: "Home",
           es: "Inicio",
           fr: "Accueil",
         }),
       },
       meta: {
         title: t({
           en: "Welcome to Intlayer + TanStack Router",
           es: "Bienvenido a Intlayer + TanStack Router",
           fr: "Bienvenue à Intlayer + TanStack Router",
         }),
         description: t({
           en: "This is an example of using Intlayer with 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",
         }),
       },
     },
     key: "app",
   } satisfies Dictionary;
   
   export default appContent;
   

   Vos déclarations de contenu peuvent être définies n'importe où dans votre application tant 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,cjs,md,mdx,yaml,yml}).

   Pour plus de détails, reportez-vous à la documentation sur la déclaration de contenu.

8. 7

   Créer des composants et hooks tenant compte de la locale

   Créez un composant LocalizedLink pour une navigation tenant compte de la locale :

   src/components/localized-link.tsx

   Copier le contenu

   Copier le code

   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";
   import { getPrefix } from "intlayer";
   
   export const LOCALE_ROUTE = "{-$locale}" as const;
   
   export type To = StripLocalePrefix<LinkComponentProps["to"]>;
   
   export type StripLocalePrefix<T extends string | undefined> = T extends
     `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
     ? "/"
     : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
       ? `/${Rest}`
       : T;
   
   type LocalizedLinkProps = {
     to?: To;
   } & Omit<LinkComponentProps, "to">;
   
   export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
     const { locale } = useLocale();
     const { localePrefix } = getPrefix(locale);
   
     return (
       <Link
         {...props}
         params={{
           locale: localePrefix,
           ...(typeof props?.params === "object" ? props?.params : {}),
         }}
         to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
       />
     );
   };
   

   Ce composant a deux objectifs :

   • Supprimer le préfixe inutile {-$locale} de l'URL.
   • Injecter le paramètre de locale dans l'URL pour s'assurer que l'utilisateur est directement redirigé vers la route localisée.

   Ensuite, nous pouvons créer un hook useLocalizedNavigate pour la navigation programmatique :

   src/hooks/useLocalizedNavigate.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { useNavigate } from "@tanstack/react-router";
   import { getPrefix } from "intlayer";
   import { useLocale } from "react-intlayer";
   import type { StripLocalePrefix } from "@/components/localized-link";
   import type { FileRouteTypes } from "@/routeTree.gen";
   
   type NavigateFn = ReturnType<typeof useNavigate>;
   type BaseNavigateOptions = Parameters<NavigateFn>[0];
   
   type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;
   
   export type LocalizedNavigateOptions = Omit<
     BaseNavigateOptions,
     "to" | "params"
   > & {
     to: LocalizedTo;
     params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
   };
   
   type LocalizedNavigate = (
     options: LocalizedNavigateOptions
   ) => ReturnType<NavigateFn>;
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
   
     const { locale } = useLocale();
   
     const localizedNavigate: LocalizedNavigate = (args: any) => {
       const { localePrefix } = getPrefix(locale);
   
       if (typeof args === "string") {
         return navigate({
           to: `/${LOCALE_ROUTE}${args}`,
           params: { locale: localePrefix },
         });
       }
   
       const { to, ...rest } = args;
   
       const localizedTo = `/${LOCALE_ROUTE}${to}` as any;
   
       return navigate({
         to: localizedTo,
         params: { locale: localePrefix, ...rest } as any,
       });
     };
   
     return localizedNavigate;
   };
   

9. 8

   Utiliser Intlayer dans vos pages

   Utilisez useIntlayer par défaut : c'est la manière recommandée de lire du contenu dans vos composants, et le compilateur le résout vers la locale rendue. Ne recourez à getIntlayer / getIntlayerAsync qu'en dehors de l'arbre React : le head des routes, les loaders et les server functions.

   Accédez à vos dictionnaires de contenu dans toute votre application :

   Page d'accueil localisée

   src/routes/{-$locale}/index.tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   import { createFileRoute } from "@tanstack/react-router";
   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,
   });
   
   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>
     );
   }
   

   Si vous souhaitez utiliser votre contenu dans un attribut string, tel que alt, title, href, aria-label, etc., vous pouvez utiliser la valeur de la fonction, comme :

   tsx

   Copier le contenu

   Copier le code

   Copier le code dans le presse-papiers

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

   Pour en savoir plus sur le hook useIntlayer, consultez la documentation.

10. 9

    Créer un composant Locale Switcher

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

    src/components/locale-switcher.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { useLocation } from "@tanstack/react-router";
    import {
      getHTMLTextDir,
      getLocaleName,
      getPathWithoutLocale,
      getPrefix,
      Locales,
    } from "intlayer";
    import type { FC } from "react";
    import { useLocale } from "react-intlayer";
    
    import { LocalizedLink, type To } from "./localized-link";
    
    export const LocaleSwitcher: FC = () => {
      const { pathname } = useLocation();
    
      const { availableLocales, locale, setLocale } = useLocale();
    
      const pathWithoutLocale = getPathWithoutLocale(pathname);
    
      return (
        <ol>
          {availableLocales.map((localeEl) => (
            <li key={localeEl}>
              <LocalizedLink
                aria-current={localeEl === locale ? "page" : undefined}
                onClick={() => setLocale(localeEl)}
                params={{ locale: getPrefix(localeEl).localePrefix }}
                to={pathWithoutLocale as To}
              >
                <span>
                  {/* Locale - par ex. FR */}
                  {localeEl}
                </span>
                <span>
                  {/* Langue dans sa propre locale - par ex. Français */}
                  {getLocaleName(localeEl, locale)}
                </span>
                <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
                  {/* Langue dans la locale actuelle - par ex. Francés avec la locale actuelle définie sur Locales.SPANISH */}
                  {getLocaleName(localeEl)}
                </span>
                <span dir="ltr" lang={Locales.ENGLISH}>
                  {/* Langue en anglais - par ex. French */}
                  {getLocaleName(localeEl, Locales.ENGLISH)}
                </span>
              </LocalizedLink>
            </li>
          ))}
        </ol>
      );
    };
    

    Pour en savoir plus sur le hook useLocale, consultez la documentation.

11. 10

    Gestion des attributs HTML

    Comme vu à l'étape 5, vous pouvez gérer les attributs lang et dir de la balise html en utilisant useParams dans votre composant racine. Cela garantit que les attributs corrects sont définis sur le serveur et le client.

    src/routes/__root.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    const localeRoute = getRouteApi("/{-$locale}");
    
    function RootDocument({ children }: { children: ReactNode }) {
      const params = localeRoute.useParams();
      const locale = params?.locale ?? defaultLocale;
    
      return (
        <html dir={getHTMLTextDir(locale)} lang={locale}>
          {/* ... */}
        </html>
      );
    }
    

12. 11

    Ajouter un middleware

    Vous pouvez également utiliser intlayerProxy pour ajouter du routing 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 intlayerProxy en production, vous devez passer le package vite-intlayer de devDependencies à dependencies.

    Depuis Intlayer v9, intlayerProxy() est fourni directement dans le plugin intlayer() et activé par défaut via l'option routing.enableProxy (true par défaut). L'enregistrer séparément comme montré ci-dessous est maintenant optionnel : il est conservé pour la compatibilité rétroactive et pour les configurations qui doivent contrôler l'ordre des plugins. Définissez routing.enableProxy: false pour désactiver. Consultez les notes de version v9.

    vite.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { tanstackStart } from "@tanstack/react-start/plugin/vite";
    import viteReact from "@vitejs/plugin-react";
    import { nitro } from "nitro/vite";
    import { defineConfig } from "vite";
    import { intlayer } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        nitro(),
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
        tanstackStart({
          router: {
            routeFileIgnorePattern:
              ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
          },
        }),
        viteReact(),
      ],
    });
    

13. 12

    Internationaliser vos métadonnées

    Résolution statiqueRésolution dynamiqueRésolution dynamique en cache

    getIntlayer se résout de façon synchrone par rapport au dictionnaire fusionné, celui qui contient chaque locale déclarée. head reste synchrone et rien n'est attendu, mais tout le dictionnaire multilingue est inclus dans le chunk de route envoyé au navigateur.

    src/routes/{-$locale}/index.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayer,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Le chemin pour cette route
    
        const metaContent = getIntlayer("app", locale);
    
        return {
          links: [
            // Lien canonique : Points vers la page localisée actuelle
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang : Indiquer à Google toutes les versions localisées
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default : Pour les utilisateurs dans les langues non correspondantes
            // Définir la locale de secours par défaut (généralement votre langue principale)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Meilleur pour les petits dictionnaires de métadonnées, une poignée de locales, ou lors du prototypage.

    getIntlayerAsync (disponible à partir de v9.4) se comporte comme getIntlayer, mais le plugin de build la pointe vers le chunk par locale dans .intlayer/dynamic_dictionaries/ au lieu du dictionnaire fusionné. Une page envoie donc uniquement la locale qu'elle affiche. Parce que ce chunk est chargé à la demande, head devient async :

    src/routes/{-$locale}/index.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: async ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Le chemin pour cette route
    
        const metaContent = await getIntlayerAsync("app", locale);
    
        return {
          links: [
            // Lien canonique : Points vers la page localisée actuelle
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang : Indiquer à Google toutes les versions localisées
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default : Pour les utilisateurs dans les langues non correspondantes
            // Définir la locale de secours par défaut (généralement votre langue principale)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Si un head lit plusieurs dictionnaires, résolvez-les avec Promise.all : attendre chaque getIntlayerAsync sur sa propre ligne chaîne les requêtes au lieu de les exécuter en parallèle.

    Le compromis : l'import dynamique est résolu pendant l'exécution de head, sur le chemin critique du rendu du document. Sur une route froide, cela retarde le head de quelques millisecondes et peut légèrement dégrader le LCP.

    Résolvez le dictionnaire dans le loader de la route et relisez-le depuis loaderData dans head. Les loaders des routes correspondantes s'exécutent en parallèle, et staleTime: Infinity indique à TanStack Router que le résultat ne devient jamais obsolète, donc le chunk par locale est résolu une fois et servi à partir du cache du routeur après, laissant head synchrone.

    src/routes/{-$locale}/index.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Résolu en parallèle avec les autres routes correspondantes, hors du chemin critique du head
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // Le dictionnaire ne change jamais pour une locale donnée : résoudre le chunk une fois
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Le chemin pour cette route
    
        return {
          links: [
            // Lien canonique : Points vers la page localisée actuelle
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang : Indiquer à Google toutes les versions localisées
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default : Pour les utilisateurs dans les langues non correspondantes
            // Définir la locale de secours par défaut (généralement votre langue principale)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: loaderData?.metaContent.title },
            {
              name: "description",
              content: loaderData?.metaContent.meta.description,
            },
          ],
        };
      },
    });
    

    head peut être appelé avant que le loader ne se termine, donc loaderData est typé comme possiblement undefined. Conservez le chaînage optionnel, ou retournez un titre de secours.

    Vous conservez le chunk par locale sans payer son coût sur le chemin critique du head. Le prix est l'expérience développeur : le contenu doit être transmis explicitement du loader au head via loaderData.

    Quelle résolution choisir ?

    Afficher tout le contenu du tableau

    Afficher tout le contenu du tableau

    Ouvrir le tableau dans une fenêtre modale pour voir tout le contenu clairement

    	Résolution statique	Résolution dynamique	Résolution dynamique en cache
    API	getIntlayer	getIntlayerAsync (v9.4+)	getIntlayerAsync in loader (v9.4+)
    Signature head	synchrone	async	synchrone, lit loaderData
    Locales livrées	toute locale déclarée	locale demandée uniquement	locale demandée uniquement
    Navigations client	rien à résoudre	relancé à chaque match	servi depuis le cache du routeur
    Expérience développeur	la plus simple	un await	contenu transmis via loaderData

14. 13

    Récupérer la locale dans vos server actions

    Vous voudrez peut-être accéder à la locale actuelle depuis vos server actions ou endpoints API. Vous pouvez le faire en utilisant l'helper getLocale de intlayer.

    Voici un exemple utilisant les server functions de TanStack Start :

    src/routes/{-$locale}/index.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createServerFn } from "@tanstack/react-start";
    import {
      getRequestHeader,
      getRequestHeaders,
    } from "@tanstack/react-start/server";
    import { getCookie, getIntlayer, getLocale } from "intlayer";
    
    export const getLocaleServer = createServerFn().handler(async () => {
      const locale = await getLocale({
        // Obtenez le cookie de la requête (par défaut : 'INTLAYER_LOCALE')
        getCookie: (name) => {
          const cookieString = getRequestHeader("cookie");
    
          return getCookie(name, cookieString);
        },
        // Obtenez l'en-tête de la requête (par défaut : 'x-intlayer-locale')
        // Secours utilisant la négociation Accept-Language
        getHeader: (name) => getRequestHeader(name),
      });
    
      // Récupérez du contenu en utilisant getIntlayerAsync()
      const content = getIntlayer("app", locale);
    
      return { locale, content };
    });
    

15. 14

    Gérer les pages non trouvées

    Lorsqu'un utilisateur visite une page inexistante, vous pouvez afficher une page 404 personnalisée, et le préfixe de locale peut influencer la manière dont la page non trouvée est déclenchée.

    Comprendre la gestion des 404 de TanStack Router avec les préfixes de locale

    Dans TanStack Router, la gestion des pages 404 avec des routes localisées nécessite une approche à plusieurs niveaux :

    1. Route 404 dédiée : Une route spécifique pour afficher l'interface utilisateur 404
    2. Validation au niveau de la route : Valide les préfixes de locale et redirige ceux qui sont invalides vers la page 404
    3. Route catch-all : Capture tous les chemins non correspondants dans le segment de la locale

    src/routes/{-$locale}/404.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute } from "@tanstack/react-router";
    
    // Ceci crée une route dédiée /[locale]/404
    // Elle est utilisée à la fois comme route directe et importée comme composant dans d'autres fichiers
    export const Route = createFileRoute("/{-$locale}/404")({
      component: NotFoundComponent,
    });
    
    // Exporté séparément pour pouvoir être réutilisé dans notFoundComponent et les routes catch-all
    export function NotFoundComponent() {
      return (
        <div>
          <h1>404</h1>
        </div>
      );
    }
    

    src/routes/{-$locale}/route.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
    import { validatePrefix } from "intlayer";
    import { NotFoundComponent } from "./404";
    
    export const Route = createFileRoute("/{-$locale}")({
      // beforeLoad s'exécute avant que la route ne soit rendue (sur le serveur et le client)
      // C'est l'endroit idéal pour valider le préfixe de locale
      beforeLoad: ({ params }) => {
        const localeParam = params.locale;
    
        // validatePrefix vérifie si la locale est valide selon votre configuration intlayer
        const { isValid, localePrefix } = validatePrefix(localeParam);
    
        if (!isValid) {
          // Préfixe de locale invalide - rediriger vers la page 404 avec un préfixe de locale valide
          throw redirect({
            to: "/{-$locale}/404",
            params: { locale: localePrefix },
          });
        }
      },
      component: Outlet,
      // notFoundComponent est appelé lorsqu'une route enfant n'existe pas
      // ex: /fr/page-inexistante déclenche cela au sein du layout /fr
      notFoundComponent: NotFoundComponent,
    });
    

    src/routes/{-$locale}/$.tsx

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute } from "@tanstack/react-router";
    
    import { NotFoundComponent } from "./404";
    
    // La route $ (splat/catch-all) correspond à tout chemin qui ne correspond pas aux autres routes
    // ex: /fr/certains/chemins/tres/profonds/invalides
    // Cela garantit que TOUS les chemins non correspondants au sein d'une locale affichent la page 404
    // Sans cela, les chemins profonds non correspondants pourraient afficher une page vide ou une erreur
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 15

    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

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    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.
         *
         * - Si `true`, le compilateur réécrira le fichier du composant sur le disque. La transformation sera donc permanente, et le compilateur sautera la transformation pour le prochain processus. De cette façon, le compilateur peut transformer l'application, puis il peut être supprimé.
         *
         * - Si `false`, le compilateur injectera l'appel de fonction `useIntlayer()` dans le code dans la sortie de build uniquement, et gardera la base de code intacte. La transformation sera effectuée uniquement en mémoire.
         */
        saveComponents: false,
    
        /**
         * Préfixe de clé de dictionnaire
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Commande d'extractionCompilateur Babel

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

    bash

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    npx intlayer extract
    

    intlayer >= 9intlayer < 9

    Depuis la v9, intlayerCompiler est inclus dans le plugin intlayer. Vous n'avez donc pas besoin de l'ajouter manuellement.

    Mettez à jour votre fichier vite.config.ts pour inclure le plugin intlayerCompiler :

    vite.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Ajoute le plugin du compilateur
      ],
    });
    

    Buildez votre application pour transformer vos composants et extraire le contenu

    bash

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    npm run build # Ou npm run dev
    

17. 16

    Pré-rendre & Générer le Sitemap

    Intlayer est livré avec un générateur de sitemap intégré pour vous aider à créer facilement un sitemap pour votre application. Il gère les routes localisées et ajoute les métadonnées nécessaires pour les moteurs de recherche.

    Le sitemap généré par Intlayer prend en charge l'espace de noms xhtml:link (Hreflang XML Extensions). Contrairement aux générateurs de sitemap par défaut qui ne répertorient que les URL brutes, Intlayer crée automatiquement les liens bidirectionnels requis entre toutes les versions linguistiques d'une page (par exemple, /about, /about?lang=fr et /about?lang=es). Cela garantit que les moteurs de recherche indexent et servent correctement la bonne version linguistique au bon public.

    Pour l'utiliser, vous devez d'abord configurer votre fichier vite.config.ts pour activer le pré-rendu de vos routes localisées et désactiver la génération de sitemap par défaut de TanStack Start.

    vite.config.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { localeFlatMap } from "intlayer";
    // ... autres imports
    
    export const pathList = ["", "/about", "/404"];
    
    const localizedPages = localeFlatMap(({ urlPrefix }) =>
      pathList.map((path) => ({
        path: `${urlPrefix}${path}`,
        prerender: {
          enabled: true,
        },
      }))
    );
    
    export default defineConfig({
      plugins: [
        // ... autres plugins
        tanstackStart({
          // ... autres configurations
          sitemap: {
            enabled: false,
          },
          prerender: {
            enabled: true,
            crawlLinks: false,
            concurrency: 10,
          },
          pages: localizedPages,
        }),
      ],
    });
    

    Ensuite, créez une route src/routes/sitemap[.]xml.ts qui utilise la fonction generateSitemap :

    src/routes/sitemap[.]xml.ts

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    import { createFileRoute } from "@tanstack/react-router";
    import { generateSitemap } from "intlayer";
    
    export const Route = createFileRoute("/sitemap.xml")({
      server: {
        handlers: {
          GET: async () => {
            const sitemap = generateSitemap(
              [
                { path: "/", changefreq: "daily", priority: 1.0 },
                { path: "/about", changefreq: "monthly", priority: 0.8 },
              ],
              { siteUrl: "https://example.com" }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

18. 17

    Configurer TypeScript

    Intlayer utilise l'augmentation de module pour bénéficier des avantages de TypeScript et rendre votre codebase plus robuste.

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

    tsconfig.json

    Copier le contenu

    Copier le code

    Copier le code dans le presse-papiers

    {
      // ... vos configurations existantes
      include: [
        // ... vos includes existants
        ".intlayer/**/*.ts", // Inclure les types auto-générés
      ],
    }
    

Configuration Git

Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les valider dans votre référentiel 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'extension officielle Intlayer VS Code Extension.

Installer depuis la VS Code Marketplace

Cette extension fournit :

• Autocomplétion pour les clés de traduction.
• Détection d'erreurs en temps réel pour les traductions manquantes.
• Aperçus intégrés 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 Documentation

• Documentation Intlayer
• Documentation Tanstack Start
• Hook useIntlayer
• Hook useLocale
• Content Declaration
• Configuration

Questions fréquentes