Traduci il tuo sito web TanStack Start usando Intlayer | Internazionalizzazione (i18n)

Sommario

Questa guida dimostra come integrare Intlayer per un'internazionalizzazione senza interruzioni nei progetti TanStack Start con routing consapevole della localizzazione, supporto TypeScript e pratiche di sviluppo moderne.

Perché Intlayer rispetto alle alternative?

Rispetto alle soluzioni principali come react-i18next o use-intl o paraglide, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

Guida Passo-Passo per Configurare Intlayer in un'Applicazione TanStack Start

Vedi il Template dell'Applicazione su GitHub.

1. 1

   Creare il Progetto

   Inizia creando un nuovo progetto TanStack Start seguendo la guida Avvia nuovo progetto sul sito web di TanStack Start.

2. 2

   Installare i Pacchetti Intlayer

   Installa i pacchetti necessari utilizzando il tuo gestore di pacchetti preferito:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   npx intlayer init --interactive
   

   il flag --interactive è opzionale. Usa intlayer-cli init se sei un agente IA.

   Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

   • intlayer

     Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione della configurazione, la traduzione, la dichiarazione dei contenuti, la traspilazione e i comandi CLI.

   • react-intlayer Il pacchetto che integra Intlayer con l'applicazione React. Fornisce provider di contesto e hook per l'internazionalizzazione di React.

   • vite-intlayer Include il plugin Vite per l'integrazione di Intlayer con il bundler Vite, oltre al middleware per il rilevamento della localizzazione preferita dell'utente, la gestione dei cookie e la gestione del reindirizzamento degli URL.

3. 3

   Configurazione del tuo progetto

   Architettura

   In questa architettura, tutte le route localizzate sono nidificate sotto il segmento di route {-$locale}. Questo approccio garantisce che ogni lingua abbia un URL dedicato consentendo al contempo il prefisso automatico della locale, la convalida e l'ottimizzazione SEO.

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   .
   ├── 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
   

   Configurazione

   Crea un file di configurazione per configurare le lingue della tua applicazione:

   intlayer.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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;
   

   Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamento middleware, nomi dei cookie, la posizione e l'estensione delle tue dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, fai riferimento alla documentazione di configurazione.

4. 4

   Integrare Intlayer nella tua Configurazione Vite

   Aggiungi il plugin intlayer nella tua configurazione:

   vite.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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;
   

   Il plugin Vite intlayer() viene utilizzato per integrare Intlayer con Vite. Garantisce la creazione dei file di dichiarazione del contenuto e li monitora in modalità sviluppo. Definisce le variabili d'ambiente di Intlayer all'interno dell'applicazione Vite. Inoltre, fornisce alias per ottimizzare le prestazioni.

5. 5

   Creare il Layout Root

   Configura il tuo layout root per supportare l'internazionalizzazione utilizzando useParams per rilevare la localizzazione corrente e impostando gli attributi lang e dir sul tag html.

   src/routes/__root.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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

   Creare il Layout di Localizzazione

   Crea un layout che gestisca il prefisso di localizzazione ed esegua la validazione.

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

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
   import { validatePrefix } from "intlayer";
   
   export const Route = createFileRoute("/{-$locale}")({
     beforeLoad: ({ params }) => {
       const localeParam = params.locale;
   
       // Convalida il prefisso di localizzazione
       const { isValid, localePrefix } = validatePrefix(localeParam);
   
       if (!isValid) {
         throw redirect({
           to: "/{-$locale}/404",
           params: { locale: localePrefix },
         });
       }
     },
     component: Outlet,
   });
   

   Qui, {-$locale} è un parametro dinamico della rotta che viene sostituito con la localizzazione corrente. Questa notazione rende lo slot opzionale, permettendogli di funzionare con modalità di routing come 'prefix-no-default' ecc.

   Tieni presente che questo slot potrebbe causare problemi se utilizzi più segmenti dinamici nella stessa rotta (es. /{-$locale}/other-path/$anotherDynamicPath/...). Per la modalità 'prefix-all', potresti preferire passare allo slot $locale. Per la modalità 'no-prefix' o 'search-params', puoi rimuovere completamente lo slot.

7. 7

   Dichiarare il Tuo Contenuto

   Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:

   src/contents/page.content.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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;
   

   Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione purché siano incluse nella directory contentDir (per impostazione predefinita, ./app). E corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Per ulteriori dettagli, fai riferimento alla documentazione sulla dichiarazione dei contenuti.

8. 8

   Creare Componenti e Hook Consapevoli della Localizzazione

   Crea un componente LocalizedLink per la navigazione consapevole della localizzazione:

   src/components/localized-link.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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"]}
       />
     );
   };
   

   Questo componente ha due obiettivi:

   • Rimuovere il prefisso {-$locale} non necessario dall'URL.
   • Iniettare il parametro locale nell'URL per garantire che l'utente venga reindirizzato direttamente alla rotta localizzata.

   Quindi possiamo creare un hook useLocalizedNavigate per la navigazione programmatica:

   src/hooks/useLocalizedNavigate.tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

   Utilizzare Intlayer nelle tue Pagine

   Usa useIntlayer come impostazione predefinita: è il modo consigliato per leggere i contenuti nei componenti e il compilatore lo risolve sulla locale effettivamente renderizzata. Ricorri a getIntlayer / getIntlayerAsync solo al di fuori dell'albero React: l'head delle rotte, i loader e le server function.

   Accedi ai tuoi dizionari di contenuti in tutta l'applicazione:

   Pagina Home Localizzata

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

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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>
     );
   }
   

   Se vuoi usare il tuo contenuto in un attributo string, come alt, title, href, aria-label, ecc., puoi usare il valore della funzione, come:

   tsx

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   <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)} />
   

   Per saperne di più sull'hook useIntlayer, consulta la documentazione.

10. 9

    Creare un Componente di Selezione delle Lingue

    Crea un componente per consentire agli utenti di cambiare lingua:

    src/components/locale-switcher.tsx

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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 - ad es. FR */}
                  {localeEl}
                </span>
                <span>
                  {/* Lingua nella sua stessa Locale - ad es. Français */}
                  {getLocaleName(localeEl, locale)}
                </span>
                <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
                  {/* Lingua nella Locale corrente - ad es. Francese con la locale corrente impostata su Locales.ITALIAN */}
                  {getLocaleName(localeEl)}
                </span>
                <span dir="ltr" lang={Locales.ENGLISH}>
                  {/* Lingua in inglese - ad es. French */}
                  {getLocaleName(localeEl, Locales.ENGLISH)}
                </span>
              </LocalizedLink>
            </li>
          ))}
        </ol>
      );
    };
    

    Per saperne di più sull'hook useLocale, consulta la documentazione.

11. 10

    Gestione degli Attributi HTML

    Come visto nel Passaggio 5, puoi gestire gli attributi lang e dir del tag html utilizzando useParams nel tuo componente root. Questo assicura che gli attributi corretti siano impostati sia lato server che lato client.

    src/routes/__root.tsx

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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

    Aggiungi middleware

    Puoi anche usare intlayerProxy per aggiungere il routing lato server alla tua applicazione. Questo plugin rileva automaticamente la locale corrente in base all'URL e imposta il cookie della locale appropriato. Se non viene specificata alcuna locale, il plugin determinerà la locale più appropriata in base alle preferenze della lingua del browser dell'utente. Se non viene rilevata alcuna locale, reindirizzerà alla locale predefinita.

    Nota che per usare intlayerProxy in produzione, devi spostare il package vite-intlayer da devDependencies a dependencies.

    A partire da Intlayer v9, intlayerProxy() è aggruppato direttamente nel plugin intlayer() e abilitato per impostazione predefinita tramite l'opzione routing.enableProxy (true per impostazione predefinita). Registrarlo separatamente come mostrato di seguito è ora opzionale: viene mantenuto per compatibilità con le versioni precedenti e per i setup che devono controllare l'ordine dei plugin. Imposta routing.enableProxy: false per disattivarlo. Vedi le note di rilascio della v9.

    vite.config.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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

    Internazionalizza i tuoi Metadati

    Risoluzione staticaRisoluzione dinamicaRisoluzione dinamica memorizzata nella cache

    getIntlayer si risolve sincronamente rispetto al dizionario unito, quello che contiene ogni locale dichiarata. head rimane sincrono e nulla viene atteso, ma l'intero dizionario multilingue viene inserito nel chunk di route inviato al browser.

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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 = "/"; // Il percorso per questa route
    
        const metaContent = getIntlayer("app", locale);
    
        return {
          links: [
            // Link canonico: punta alla pagina localizzata corrente
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: comunica a Google tutte le versioni localizzate
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: per gli utenti con lingue non corrispondenti
            // Definisci la locale di fallback predefinita (di solito la tua lingua principale)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Migliore per piccoli dizionari di metadati, un pugno di locale o durante il prototipo.

    getIntlayerAsync (disponibile da v9.4) si comporta come getIntlayer, ma il plugin di build lo punta al chunk per locale in .intlayer/dynamic_dictionaries/ invece che al dizionario unito. Una pagina quindi spedisce solo la locale che rende. Poiché quel chunk viene caricato su richiesta, head diventa async:

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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 = "/"; // Il percorso per questa route
    
        const metaContent = await getIntlayerAsync("app", locale);
    
        return {
          links: [
            // Link canonico: punta alla pagina localizzata corrente
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: comunica a Google tutte le versioni localizzate
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: per gli utenti con lingue non corrispondenti
            // Definisci la locale di fallback predefinita (di solito la tua lingua principale)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: metaContent.title },
            { name: "description", content: metaContent.meta.description },
          ],
        };
      },
    });
    

    Se un head legge più dizionari, risolvili con Promise.all: attendere ogni getIntlayerAsync su una riga propria concatena le richieste invece di eseguirle in parallelo.

    Il compromesso: l'importazione dinamica viene risolta mentre head viene eseguito, sul percorso critico del rendering del documento. Su una route fredda questo ritarda l'head di pochi millisecondi e può degradare leggermente LCP.

    Risolvi il dizionario nel loader della route e leggilo di nuovo da loaderData in head. I loader delle route corrispondenti vengono eseguiti in parallelo e staleTime: Infinity dice a TanStack Router che il risultato non scade mai, quindi il chunk per locale viene risolto una volta e servito dalla cache del router successivamente, lasciando head sincrono.

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { createFileRoute } from "@tanstack/react-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Risolto in parallelo con le altre route corrispondenti, al di fuori del percorso critico dell'head
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // Il dizionario non cambia mai per una determinata locale: risolvi il chunk una volta
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Il percorso per questa route
    
        return {
          links: [
            // Link canonico: punta alla pagina localizzata corrente
            { rel: "canonical", href: getLocalizedUrl(path, locale) },
    
            // Hreflang: comunica a Google tutte le versioni localizzate
            ...localeMap(({ locale: mapLocale }) => ({
              rel: "alternate",
              hrefLang: mapLocale,
              href: getLocalizedUrl(path, mapLocale),
            })),
    
            // x-default: per gli utenti con lingue non corrispondenti
            // Definisci la locale di fallback predefinita (di solito la tua lingua principale)
            {
              rel: "alternate",
              hrefLang: "x-default",
              href: getLocalizedUrl(path, defaultLocale),
            },
          ],
          meta: [
            { title: loaderData?.metaContent.title },
            {
              name: "description",
              content: loaderData?.metaContent.meta.description,
            },
          ],
        };
      },
    });
    

    head può essere chiamato prima che il loader si risolva, quindi loaderData è tipizzato come possibilmente undefined. Mantieni l'optional chaining o restituisci un titolo di fallback.

    Mantieni il chunk per locale senza pagarne il costo sul percorso critico dell'head. Il prezzo è l'esperienza dello sviluppatore: il contenuto deve essere trasferito esplicitamente dal loader all'head attraverso loaderData.

    Quale risoluzione dovrei scegliere?

    Mostra tutto il contenuto della tabella

    Mostra tutto il contenuto della tabella

    Apri la tabella in una finestra modale per visualizzare tutti i dati in modo chiaro

    	Static resolution	Dynamic resolution	Cached dynamic resolution
    API	getIntlayer	getIntlayerAsync (v9.4+)	getIntlayerAsync in loader (v9.4+)
    head signature	synchronous	async	synchronous, reads loaderData
    Locales shipped	every declared locale	requested locale only	requested locale only
    Client navigations	nothing to resolve	re-entered on every match	served from the router cache
    Developer experience	simplest	one await	content threaded through loaderData

14. 13

    Recupera la locale nelle tue server actions

    Potresti voler accedere alla locale corrente all'interno delle tue server actions o endpoint API. Puoi farlo usando l'helper getLocale da intlayer.

    Ecco un esempio usando le server functions di TanStack Start:

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    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({
        // Ottieni il cookie dalla richiesta (default: 'INTLAYER_LOCALE')
        getCookie: (name) => {
          const cookieString = getRequestHeader("cookie");
    
          return getCookie(name, cookieString);
        },
        // Ottieni l'header dalla richiesta (default: 'x-intlayer-locale')
        // Fallback usando la negoziazione Accept-Language
        getHeader: (name) => getRequestHeader(name),
      });
    
      // Recupera alcuni contenuti usando getIntlayerAsync()
      const content = getIntlayer("app", locale);
    
      return { locale, content };
    });
    

15. 14

    Gestire le pagine non trovate

    Quando un utente visita una pagina non esistente, puoi visualizzare una pagina 404 personalizzata e il prefisso di localizzazione può influire sul modo in cui viene attivata la pagina non trovata.

    Comprendere la Gestione 404 di TanStack Router con i Prefissi di Localizzazione

    In TanStack Router, la gestione delle pagine 404 con rotte localizzate richiede un approccio a più livelli:

    1. Rotta 404 dedicata: Una rotta specifica per visualizzare l'interfaccia utente 404
    2. Validazione a livello di rotta: Convalida i prefissi di localizzazione e reindirizza quelli non validi al 404
    3. Rotta catch-all: Cattura qualsiasi percorso non corrispondente all'interno del segmento di localizzazione

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { createFileRoute } from "@tanstack/react-router";
    
    // Questo crea una rotta dedicata /[locale]/404
    // Viene utilizzata sia come rotta diretta che importata come componente in altri file
    export const Route = createFileRoute("/{-$locale}/404")({
      component: NotFoundComponent,
    });
    
    // Esportata separatamente in modo che possa essere riutilizzata in notFoundComponent e nelle rotte catch-all
    export function NotFoundComponent() {
      return (
        <div>
          <h1>404</h1>
        </div>
      );
    }
    

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
    import { validatePrefix } from "intlayer";
    import { NotFoundComponent } from "./404";
    
    export const Route = createFileRoute("/{-$locale}")({
      // beforeLoad viene eseguito prima del rendering della rotta (sia sul server che sul client)
      // È il luogo ideale per convalidare il prefisso di localizzazione
      beforeLoad: ({ params }) => {
        const localeParam = params.locale;
    
        // validatePrefix controlla se la localizzazione è valida in base alla tua configurazione intlayer
        const { isValid, localePrefix } = validatePrefix(localeParam);
    
        if (!isValid) {
          // Prefisso di localizzazione non valido - reindirizza alla pagina 404 con un prefisso valido
          throw redirect({
            to: "/{-$locale}/404",
            params: { locale: localePrefix },
          });
        }
      },
      component: Outlet,
      // notFoundComponent viene chiamato quando una rotta figlia non esiste
      // es. /en/non-existent-page attiva questo all'interno del layout /en
      notFoundComponent: NotFoundComponent,
    });
    

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

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { createFileRoute } from "@tanstack/react-router";
    
    import { NotFoundComponent } from "./404";
    
    // La rotta $ (splat/catch-all) corrisponde a qualsiasi percorso che non corrisponde ad altre rotte
    // es. /en/some/deeply/nested/invalid/path
    // Questo assicura che TUTTI i percorsi non corrispondenti all'interno di una localizzazione mostrino la pagina 404
    // Senza questo, i percorsi profondi non corrispondenti potrebbero mostrare una pagina vuota o un errore
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 15

    Estrarre il contenuto dei tuoi componenti

    Opzionale

    isOptional={true}>

    Se hai una base di codice esistente, trasformare migliaia di file può richiedere molto tempo.

    Per facilitare questo processo, Intlayer propone un compilatore / estrattore per trasformare i tuoi componenti ed estrarre il contenuto.

    Per configurarlo, puoi aggiungere una sezione compiler nel tuo file intlayer.config.ts:

    intlayer.config.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Resto della tua configurazione
      compiler: {
        /**
         * Indica se il compilatore deve essere abilitato.
         */
        enabled: true,
    
        /**
         * Definisce il percorso dei file di output
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Indica se i componenti devono essere salvati dopo essere stati trasformati. In questo modo, il compilatore può essere eseguito solo una volta per trasformare l'app e poi rimosso.
         */
        saveComponents: false,
    
        /**
         * Prefisso chiave dizionario
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Comando di estrazioneCompilatore Babel

    Esegui l'estrattore per trasformare i tuoi componenti ed estrarre il contenuto

    bash

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Aggiorna il tuo vite.config.ts per includere il plugin intlayerCompiler:

    vite.config.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    npm run build # Oppure npm run dev
    

17. 16

    Generare una Sitemap

    Intlayer include un generatore di sitemap integrato per aiutarti a creare facilmente una sitemap per la tua applicazione. Gestisce i percorsi localizzati e aggiunge i metadati necessari per i motori di ricerca.

    La sitemap generata da Intlayer supporta lo spazio dei nomi xhtml:link (Hreflang XML Extensions). A differenza dei generatori di sitemap predefiniti che elencano solo URL grezzi, Intlayer crea automaticamente i collegamenti bidirezionali richiesti tra tutte le versioni linguistiche di una pagina (ad esempio, /about, /about?lang=fr e /about?lang=es). Ciò garantisce che i motori di ricerca indicizzino e servano correttamente la versione linguistica corretta al pubblico giusto.

    Per utilizzarlo, devi prima configurare il tuo file vite.config.ts per abilitare il pre-rendering per i tuoi percorsi localizzati e disabilitare la generazione predefinita della sitemap di TanStack Start.

    vite.config.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

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

    Quindi, crea un percorso src/routes/sitemap[.]xml.ts che utilizzi la funzione generateSitemap:

    src/routes/sitemap[.]xml.ts

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    import { createFileRoute } from "@tanstack/react-router";
    import { generateSitemap } from "intlayer";
    
    const SITE_URL = (
      import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
    ).replace(/\/$/, "");
    
    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: SITE_URL }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

18. 17

    Configurare TypeScript

    Intlayer utilizza l'augmentation dei moduli per ottenere i vantaggi di TypeScript e rendere il tuo codice più robusto.

    Assicurati che la tua configurazione TypeScript includa i tipi generati automaticamente:

    tsconfig.json

    Copia contenuto

    Copiare il codice

    Copiare il codice nella clipboard

    {
      // ... le tue configurazioni esistenti
      include: [
        // ... i tuoi include esistenti
        ".intlayer/**/*.ts", // Includi i tipi generati automaticamente
      ],
    }
    

Configurazione Git

Si consiglia di ignorare i file generati da Intlayer. Ciò consente di evitare di commetterli nel repository Git.

Per farlo, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

# Ignora i file generati da Intlayer
.intlayer

Estensione VS Code

Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'Estensione Intlayer per VS Code.

Installa da VS Code Marketplace

Questa estensione fornisce:

• Autocompletamento per le chiavi di traduzione.
• Rilevamento errori in tempo reale per traduzioni mancanti.
• Anteprime inline dei contenuti tradotti.
• Azioni rapide per creare e aggiornare facilmente le traduzioni.

Per maggiori dettagli su come utilizzare l'estensione, consulta la documentazione dell'Estensione Intlayer per VS Code.

Vai oltre

Per andare oltre, puoi implementare l'editor visuale o esternalizzare il tuo contenuto utilizzando il CMS.

Riferimenti alla Documentazione

• Documentazione di Intlayer
• Documentazione di Tanstack Start
• hook useIntlayer
• hook useLocale
• Dichiarazione dei Contenuti
• Configurazione

Domande frequenti