Questa pagina ha un modello di applicazione disponibile.
Pose una domanda e ottieni un riassunto del documento facendo riferimento a questa pagina e al provider AI di tua scelta
Integrando il server MCP Intlayer al tuo assistente AI, puoi recuperare tutti i documenti direttamente da ChatGPT, DeepSeek, Cursor, VSCode, ecc.
Vedi la documentazione del server MCPIl contenuto di questa pagina è stato tradotto con un'IA.
Vedi l'ultima versione del contenuto originale in ingleseSe hai un’idea per migliorare questa documentazione, non esitare a contribuire inviando una pull request su GitHub.
Collegamento GitHub alla documentazioneCopia il Markdown del documento nella porta-documenti
Iniziare con l'internazionalizzazione (i18n) con Intlayer e Tanstack Start
Questa guida dimostra come integrare Intlayer per un'internazionalizzazione senza soluzione di continuità nei progetti Tanstack Start con routing consapevole della localizzazione, supporto TypeScript e pratiche di sviluppo moderne.
Cos'è Intlayer?
Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle moderne applicazioni web.
Con Intlayer, puoi:
- Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
- Localizzare dinamicamente i metadata, le rotte e i contenuti.
- Garantire il supporto TypeScript con tipi generati automaticamente, migliorando l'autocompletamento e il rilevamento degli errori.
- Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della localizzazione.
- Abilitare il routing consapevole della localizzazione con il sistema di routing basato su file di Tanstack Start.
Guida passo-passo per configurare Intlayer in un'applicazione Tanstack Start
Passo 1: Creare il progetto
Inizia creando un nuovo progetto TanStack Start seguendo la guida Start new project sul sito di TanStack Start.
Passo 2: Installare i pacchetti Intlayer
Installa i pacchetti necessari utilizzando il tuo gestore di pacchetti preferito:
npm install intlayer react-intlayernpm install vite-intlayer --save-dev
intlayer
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 in React.
vite-intlayer Include il plugin Vite per integrare Intlayer con il bundler Vite, oltre a middleware per rilevare la localizzazione preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.
Passo 3: Configurazione del tuo progetto
Crea un file di configurazione per configurare le lingue della tua applicazione:
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, reindirizzamenti 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, consulta la documentazione di configurazione.
Passo 4: Integra Intlayer nella tua configurazione Vite
Aggiungi il plugin intlayer nella tua configurazione:
Copiare il codice nella clipboard
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [reactRouter(), tsconfigPaths(), intlayer()],});
Il plugin Vite intlayer() viene utilizzato per integrare Intlayer con Vite. Garantisce la creazione dei file di dichiarazione dei contenuti 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.
Passo 5: Crea i Componenti di Layout
Configura il layout principale e i layout specifici per locale:
Layout Principale
Copiare il codice nella clipboard
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { const { defaultLocale } = useLocale(); const { locale } = Route.useParams(); return ( <IntlayerProvider locale={defaultLocale}> <Outlet /> </IntlayerProvider> );}
Passo 6: Dichiara il Tuo Contenuto
Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:
Copiare il codice nella clipboard
import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = { content: { links: { about: t({ it: "Informazioni", en: "About", es: "Acerca de", fr: "À propos", }), home: t({ it: "Home", en: "Home", es: "Inicio", fr: "Accueil", }), }, meta: { description: t({ it: "Questo è un esempio di utilizzo di Intlayer con TanStack Router", en: "This is an example of using Intlayer with TanStack Router", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router", }), }, title: t({ it: "Benvenuto in Intlayer + TanStack Router", en: "Welcome to Intlayer + TanStack Router", es: "Bienvenido a Intlayer + TanStack Router", fr: "Bienvenue à Intlayer + TanStack Router", }), }, key: "app",} satisfies Dictionary;export default appContent; fr: "Bienvenue à Intlayer + TanStack Router", }), }, key: "app",} satisfies Dictionary;export default appContent;
Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena sono incluse nella directory contentDir (di default, ./app). E devono corrispondere all'estensione del file di dichiarazione del contenuto (di default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.
Passo 7: Crea Componenti e Hook Consapevoli della Localizzazione
Crea un componente LocalizedLink per la navigazione consapevole della localizzazione:
Copiare il codice nella clipboard
import type { FC } from "react";import { Link, type LinkComponentProps } from "@tanstack/react-router";import { useLocale } from "react-intlayer";export const LOCALE_ROUTE = "{-$locale}" as const;// Utilità principaleexport type RemoveLocaleParam<T> = T extends string ? RemoveLocaleFromString<T> : T;export type To = RemoveLocaleParam<LinkComponentProps["to"]>;type CollapseDoubleSlashes<S extends string> = S extends `${infer H}//${infer T}` ? CollapseDoubleSlashes<`${H}/${T}`> : S;type LocalizedLinkProps = { to?: To;} & Omit<LinkComponentProps, "to">;// Helpertype RemoveAll< S extends string, Sub extends string,> = S extends `${infer H}${Sub}${infer T}` ? RemoveAll<`${H}${T}`, Sub> : S;type RemoveLocaleFromString<S extends string> = CollapseDoubleSlashes< RemoveAll<S, typeof LOCALE_ROUTE>>;export const LocalizedLink: FC<LocalizedLinkProps> = (props) => { const { locale } = useLocale(); return ( <Link {...props} params={{ locale, ...(typeof props?.params === "object" ? props?.params : {}), }} to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]} /> );};
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.
Successivamente possiamo creare un hook useLocalizedNavigate per la navigazione programmatica:
Copiare il codice nella clipboard
import { useLocale } from "react-intlayer";import { useNavigate } from "@tanstack/react-router";import { LOCALE_ROUTE } from "@/components/localized-link";import type { FileRouteTypes } from "@/routeTree.gen";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); type StripLocalePrefix<T extends string> = T extends | `/${typeof LOCALE_ROUTE}` | `/${typeof LOCALE_ROUTE}/` ? "/" : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}` ? `/${Rest}` : never; type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>; interface LocalizedNavigate { (to: LocalizedTo): ReturnType<typeof navigate>; ( opts: { to: LocalizedTo } & Record<string, unknown> ): ReturnType<typeof navigate>; } const localizedNavigate: LocalizedNavigate = (args: any) => { if (typeof args === "string") { return navigate({ to: `/${LOCALE_ROUTE}${args}`, params: { locale } }); } const { to, ...rest } = args; const localedTo = `/${LOCALE_ROUTE}${to}` as any; return navigate({ to: localedTo, params: { locale, ...rest } as any }); }; return localizedNavigate;};
Passo 8: Utilizza Intlayer nelle tue Pagine
Accedi ai tuoi dizionari di contenuti in tutta l'applicazione:
Pagina Home Localizzata
Copiare il codice nella clipboard
import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";import { useIntlayer } from "react-intlayer";import LocaleSwitcher from "@/components/locale-switcher";import { LocalizedLink } from "@/components/localized-link";import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: ({ params }) => { const { locale } = params; const metaContent = getIntlayer("app", locale); return { meta: [ { title: metaContent.title }, { content: metaContent.meta.description, name: "description" }, ], }; },});function RouteComponent() { const content = useIntlayer("app"); const navigate = useLocalizedNavigate(); return ( <div> <div> {content.title} <LocaleSwitcher /> <div> <LocalizedLink to="/">{content.links.home}</LocalizedLink> <LocalizedLink to="/about">{content.links.about}</LocalizedLink> </div> <div> <button onClick={() => navigate({ to: "/" })}> {content.links.home} </button> <button onClick={() => navigate({ to: "/about" })}> {content.links.about} </button> </div> </div> </div> );}
Per saperne di più sull'hook useIntlayer, consulta la documentazione.
Passo 9: Crea un Componente per il Cambio di Lingua
Crea un componente per permettere agli utenti di cambiare lingua:
Copiare il codice nella clipboard
import type { FC } from "react";import { useLocation } from "@tanstack/react-router";import { getHTMLTextDir, getLocaleName, getPathWithoutLocale } from "intlayer";import { setLocaleCookie, useIntlayer, useLocale } from "react-intlayer";import { LocalizedLink, To } from "./localized-link";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeEl) => ( <li key={localeEl}> <LocalizedLink aria-current={localeEl === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeEl)}`} onClick={() => setLocaleCookie(localeEl)} params={{ locale: localeEl }} to={pathWithoutLocale as To} > <span> {/* Lingua - es. FR */} {localeItem} </span> <span> {/* Lingua nella sua stessa lingua - es. Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Lingua nella lingua corrente - es. Francés con la lingua corrente impostata su Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Lingua in inglese - es. French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </LocalizedLink> </li> ))} </ol> );};
Per saperne di più sul hook useLocale, consulta la documentazione.
Passo 10: Aggiungere la gestione degli attributi HTML (Opzionale)
Crea un hook per gestire gli attributi lang e dir dell'HTML:
Copiare il codice nella clipboard
// src/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};
Poi usalo nel tuo componente root:
Copiare il codice nella clipboard
import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // importa il hookexport const Route = createFileRoute("/{-$locale}")({ component: LayoutComponent,});function LayoutComponent() { useI18nHTMLAttributes(); // aggiungi questa riga const { defaultLocale } = useLocale(); const { locale } = Route.useParams(); return ( <IntlayerProvider locale={locale ?? defaultLocale}> <Outlet /> </IntlayerProvider> );}
Passo 11: Aggiungere middleware (Opzionale)
Puoi anche utilizzare intlayerMiddleware per aggiungere il routing lato server alla tua applicazione. Questo plugin rileverà automaticamente la locale corrente basandosi sull'URL e imposterà il cookie della locale appropriata. Se non viene specificata alcuna locale, il plugin determinerà la locale più adatta in base alle preferenze linguistiche del browser dell'utente. Se non viene rilevata alcuna locale, verrà effettuato un reindirizzamento alla locale predefinita.
Nota che per utilizzare intlayerMiddleware in produzione, è necessario spostare il pacchetto vite-intlayer da devDependencies a dependencies.
Copiare il codice nella clipboard
import { reactRouter } from "@react-router/dev/vite";import tailwindcss from "@tailwindcss/vite";import { defineConfig } from "vite";import { intlayer, intlayerMiddleware } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({ plugins: [ tailwindcss(), reactRouter(), tsconfigPaths(), intlayer(), intlayerMiddleware(), ],});
Passo 12: Configurare TypeScript (Opzionale)
Intlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.
Assicurati che la tua configurazione di TypeScript includa i tipi generati automaticamente:
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. Questo ti permette di evitare di committarli nel tuo repository Git.
Per fare ciò, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:
Copiare il codice nella clipboard
# Ignora i file generati da Intlayer.intlayer
Estensione VS Code
Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'Estensione ufficiale Intlayer per VS Code.
Installa dal Marketplace di VS Code
Questa estensione offre:
- Completamento automatico per le chiavi di traduzione.
- Rilevamento errori in tempo reale per traduzioni mancanti.
- Anteprime inline del contenuto tradotto.
- 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 i tuoi contenuti utilizzando il CMS.
Riferimenti alla documentazione
- Documentazione Intlayer
- Documentazione Tanstack Start
- Hook useIntlayer
- useLocale hook
- Dichiarazione del Contenuto
- Configurazione
Questa guida completa fornisce tutto il necessario per integrare Intlayer con Tanstack Start per un'applicazione completamente internazionalizzata con routing consapevole della localizzazione e supporto TypeScript.
Cronologia della Documentazione
Versione | Data | Modifiche |
---|---|---|
6.5.2 | 2025-10-03 | Aggiornamento documentazione |
5.8.1 | 2025-09-09 | Aggiunto per Tanstack Start |