Autore:
    Aymeric PINEAU
    Creazione:2025-09-09Ultimo aggiornamento:2026-08-25

    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:

    Intlayer è completamente ottimizzato per TanStack Start, fornendo routing multilingue, gestione dei cookie, generazione di mappe del sito, caricamento dinamico dei contenuti e tutte le funzionalità necessarie per scalare i tuoi sforzi di internazionalizzazione (i18n).

    Invece di caricare enormi file JSON nelle tue pagine, carica solo il contenuto necessario. Intlayer aiuta a ridurre le dimensioni del bundle e della pagina fino al 50%.

    L'ambito del contenuto dell'applicazione facilita la manutenzione per applicazioni su larga scala. Puoi duplicare o eliminare una singola cartella di funzionalità senza l'onere mentale di rivedere l'intera codebase dei contenuti. Inoltre, Intlayer è completamente tipizzato (fully typed) per garantire l'accuratezza dei tuoi contenuti.

    La co-localizzazione dei contenuti riduce il contesto necessario dai Large Language Models (LLM). Intlayer viene fornito anche con una suite di strumenti, come una CLI per verificare le traduzioni mancanti,LSP, MCP e agent skills, per rendere l'esperienza dello sviluppatore (DX) ancora più fluida per gli agenti IA.

    Utilizza l'automazione per tradurre nella tua pipeline CI/CD utilizzando il LLM di tua scelta al costo del tuo provider di intelligenza artificiale. Intlayer offre anche un compilatore per automatizzare l'estrazione dei contenuti, nonché una piattaforma web per aiutare a tradurre in background.

    La connessione di enormi file JSON ai componenti può portare a problemi di prestazioni e reattività. Intlayer ottimizza il caricamento dei contenuti in fase di compilazione.

    Più di una semplice soluzione i18n, Intlayer fornisce un editor visivo self-hosted e un CMS completo per aiutarti gestisci i tuoi contenuti multilingue in tempo reale, semplificando la collaborazione con traduttori, copywriter e altri membri del team. I contenuti possono essere archiviati localmente e/o in remoto.

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

    www.youtube.com
    ide.intlayer.org
    intlayer-tanstack-start-template.vercel.app

    Vedi il Template dell'Applicazione su GitHub.

    1. Creare il Progetto

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

    2. Installare i Pacchetti Intlayer

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

      bash
      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
      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. Configurazione del tuo progetto

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

      intlayer.config.ts
      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. Integrare Intlayer nella tua Configurazione Vite

      Aggiungi il plugin intlayer nella tua configurazione:

      vite.config.ts
      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. 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
      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. Creare il Layout di Localizzazione

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

      src/routes/{-$locale}/route.tsx
      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. Dichiarare il Tuo Contenuto

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

      src/contents/page.content.ts
      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. Creare Componenti e Hook Consapevoli della Localizzazione

      Crea un componente LocalizedLink per la navigazione consapevole della localizzazione:

      src/components/localized-link.tsx
      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
      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. 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
      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:

      html
      <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. Creare un Componente di Selezione delle Lingue

      Crea un componente per consentire agli utenti di cambiare lingua:

      src/components/locale-switcher.tsx
      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. 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
      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. 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
      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. Internazionalizza i tuoi Metadati

      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
      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
      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
      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?

      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. 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
      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. Gestisci le pagine non trovate

      Quando un utente visita una pagina che non esiste, puoi visualizzare una pagina "not found" personalizzata e il prefisso della locale potrebbe influire sul modo in cui la pagina "not found" viene attivata.

      Pagina Home Localizzata

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

      html
      <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.
      16. src/components/locale-switcher.tsx
      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>
              {/* Localizzazione - es. FR */}
              {localeEl}
            </span>
            <span>
              {/* Lingua nella sua localizzazione - es. Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* Lingua nella localizzazione corrente - es. Francés con localizzazione corrente impostata su Locales.SPANISH */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Lingua in inglese - es. French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      Per saperne di più sull'hook useLocale, consulta la documentazione.

      </Step>

    16. Gestione degli Attributi HTML

      return ( {/* ... _/} ); } {/_ ... */} </html> ); }

      export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: async ({ params }) => { const { locale = defaultLocale } = params; const path = "/"; // The path for this route

      plaintext
      const metaContent = await getIntlayerAsync("app", locale);
      plaintext
      
> Se un `head` legge più dizionari, risolvili con `Promise.all`: attendere ogni `getIntlayerAsync` su una riga separata concatena le richieste invece di eseguirle in parallelo.

Il compromesso: l'import dinamico viene risolto mentre `head` è in esecuzione, sul percorso critico del rendering del documento. Su una rotta fredda questo ritarda l'`head` di qualche millisecondo e può peggiorare leggermente l'**LCP**.

</Tab>

<Tab label="Risoluzione dinamica in cache" value="cached">

Risolvi il dizionario nel `loader` della rotta e rileggilo da `loaderData` dentro `head`. I loader delle rotte corrispondenti girano in parallelo e `staleTime: Infinity` comunica a TanStack Router che il risultato non scade mai: il chunk per locale viene quindi risolto una sola volta e poi servito dalla cache del router, lasciando `head` sincrono.

```tsx fileName="src/routes/{-$locale}/index.tsx"

<Tabs>
 <Tab value='Extract command'>

  return { locale, content };
});
import { createFileRoute } from "@tanstack/react-router";
      src/routes/{-$locale}/route.tsx
      src/routes/{-$locale}/$.tsx
      import { NotFoundComponent } from "./404";

    17. Estrarre il contenuto dei tuoi componenti

      Opzionale

      18. 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
      import { type IntlayerConfig } from "intlayer";

    /**
     * Definisce il percorso dei file di output
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Prefisso chiave dizionario
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

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

      bash

      bun x intlayer extract import { defineConfig } from "vite"; import { intlayer, intlayerCompiler } from "vite-intlayer";

      export default defineConfig({ plugins: [

      plaintext
      intlayer(),
intlayerCompiler(), // Adds the compiler plugin

      ], });

      plaintext

      bash packageManager="npm" npm run build # Oppure npm run dev

      plaintext

      bash packageManager="pnpm" pnpm run build # O pnpm run dev

      plaintext

      bash packageManager="yarn" yarn build # O yarn dev

      plaintext

      bash packageManager="bun"

      bun run build # Or bun run dev import { localeFlatMap } from "intlayer"; // ... altre importazioni

      export const pathList = ["", "/about", "/404"];

      const localizedPages = localeFlatMap(({ urlPrefix }) => pathList.map((path) => ({

      plaintext
      path: `${urlPrefix}${path}`,
prerender: {
  enabled: true,
},

      })) );

      export default defineConfig({ plugins: [

      plaintext
      // ... altri plugin
tanstackStart({
  // ... altre configurazioni
  sitemap: {
    enabled: false,
  },
  prerender: {
    enabled: true,
    crawlLinks: false,
    concurrency: 10,
  },
  pages: localizedPages,
}),

      ], });

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

      `typescript fileName="src/routes/sitemap[.]xml.ts"

      export const Route = createFileRoute("/sitemap.xml")({ server: {

      plaintext
      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" },
    });
  },
},

      }, }); { // ... le tue configurazioni esistenti include: [

      plaintext
      // ... i tuoi include esistenti
".intlayer/**/*.ts", // Includi i tipi generati automaticamente

      ], }

      Configurazione Git

      Si consiglia di ignorare i file generati da Intlayer. Questo ti permette di evitare di effettuare il commit nel tuo repository Git.

      Per fare ciò, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

      .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

      CompilerTanstack Start Solid