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
Cronologia delle versioni
- "Aggiornare l'uso dell'API useIntlayer di Solid all'accesso diretto alle proprietà"v8.9.004/05/2026
- "Aggiungi comando init"v7.5.930/12/2025
- "Cronologia iniziale"v7.3.408/12/2025
Il 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
Traduci la tua React Router v7 (File-System Routes) con Intlayer | Internazionalizzazione (i18n)
Questa guida dimostra come integrare Intlayer per un'internazionalizzazione senza soluzione di continuità nei progetti React Router v7 usando routing basato sul file system (@react-router/fs-routes) con routing consapevole della localizzazione, supporto TypeScript e pratiche di sviluppo moderne.
Per il routing lato client, fare riferimento alla guida Intlayer con React Router v7.
Indice
Cos'è Intlayer?
Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle applicazioni web moderne.
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 sul file system di React Router v7.
Guida passo-passo per configurare Intlayer in un'applicazione React Router v7 con route basate sul file system
See Application Template on GitHub.
Passo 1: Installare le dipendenze
Installa i pacchetti necessari usando il tuo gestore di pacchetti preferito:
Copiare il codice nella clipboard
npm install intlayer react-intlayernpm install vite-intlayer --save-devnpm install @react-router/fs-routes --save-devnpx intlayer initintlayer
Il pacchetto core 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 locale preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.@react-router/fs-routes Il pacchetto che abilita il routing basato sul file system per React Router v7.
Passo 2: Configurazione del tuo progetto
Crea un file di configurazione per impostare le lingue della tua applicazione:
Copiare il codice nella clipboard
import { type IntlayerConfig, 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 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 3: 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";export default defineConfig({ plugins: [reactRouter(), 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 4: Configurare le rotte basate sul file system di React Router v7
Configura la tua configurazione di routing per utilizzare rotte basate sul file system con flatRoutes:
Copiare il codice nella clipboard
import type { RouteConfig } from "@react-router/dev/routes";import { flatRoutes } from "@react-router/fs-routes";import { configuration } from "intlayer";const routes: RouteConfig = flatRoutes({ // Ignorare i file di dichiarazione del contenuto per evitare che vengano trattati come rotte ignoredRouteFiles: configuration.content.fileExtensions.map( (fileExtension) => `**/*${fileExtension}` ),});export default routes;La funzioneflatRoutesdi@react-router/fs-routesabilita il routing basato sul file system, dove la struttura dei file nella directoryroutes/determina le rotte della tua applicazione. L'opzioneignoredRouteFilesgarantisce che i file di dichiarazione del contenuto Intlayer (.content.ts, ecc.) non vengano trattati come file di rotta.
Passo 5: Creare file di rotta con convenzioni del file system
Con il routing basato sul file system, usi una convenzione di denominazione piatta dove i punti (.) rappresentano segmenti di percorso e le parentesi () denotano segmenti opzionali.
Crea i seguenti file nella directory app/routes/:
Struttura dei file
Copiare il codice nella clipboard
app/├── root.tsx # Wrapper di layout per le rotte di locale└──routes/ ├── ($locale)._index.tsx # Pagina iniziale (/, /es, ecc.) ├── ($locale)._index.content.ts # Contenuto della pagina iniziale ├── ($locale).about.tsx # Pagina About (/about, /es/about, ecc.) └── ($locale).about.content.ts # Contenuto della pagina AboutLe convenzioni di denominazione:
($locale)- Segmento dinamico opzionale per il parametro locale_layout- Rotta di layout che avvolge le rotte figlie_index- Rotta di indice (viene renderizzata al percorso padre).(punto) - Separa i segmenti di percorso (ad esempio,($locale).about→/:locale?/about)
Componente Layout
Copiare il codice nella clipboard
import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import { isRouteErrorResponse, Meta, Outlet, Scripts, ScrollRestoration, useLoaderData,} from "react-router";import type { Route } from "./+types/root";import "./app.css";// links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) { const locale = getLocaleFromPath(request.url); return { locale };}export function Layout({ children,}: { children: React.ReactNode } & Route.ComponentProps) { const data = useLoaderData<typeof loader>(); const { locale } = data ?? {}; return ( <html lang={locale}> <head> <meta charSet="utf-8" /> <meta content="width=device-width, initial-scale=1" name="viewport" /> <Meta /> <Links /> </head> <body> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> <ScrollRestoration /> <Scripts /> </body> </html> );}Pagina Indice
Copiare il codice nella clipboard
import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale)._index";export const loader = ({ params }: Route.LoaderArgs) => { const { locale } = params; const { isValid } = validatePrefix(locale); if (!isValid) { throw data("Locale not supported", { status: 404 }); }};export const meta: Route.MetaFunction = ({ params }) => { const content = getIntlayer("page", params.locale); return [ { title: content.title }, { content: content.description, name: "description" }, ];};export default function Page() { const { title, description, aboutLink } = useIntlayer("page"); return ( <div> <h1>{title}</h1> <p>{description}</p> <nav> <LocalizedLink to="/about">{aboutLink}</LocalizedLink> </nav> </div> );}Pagina About
Copiare il codice nella clipboard
import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale).about";export const loader = ({ params }: Route.LoaderArgs) => { const { locale } = params; const { isValid } = validatePrefix(locale); if (!isValid) { throw data("Locale not supported", { status: 404 }); }};export const meta: Route.MetaFunction = ({ params }) => { const content = getIntlayer("about", params.locale); return [ { title: content.title }, { content: content.description, name: "description" }, ];};export default function AboutPage() { const { title, content, homeLink } = useIntlayer("about"); return ( <div> <h1>{title}</h1> <p>{content}</p> <nav> <LocalizedLink to="/">{homeLink}</LocalizedLink> </nav> </div> );}Passo 6: Dichiarare il Tuo Contenuto
Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni. Posiziona i file di contenuto accanto ai file di rotta:
Copiare il codice nella clipboard
import { t, type Dictionary } from "intlayer";const pageContent = { key: "page", content: { title: t({ en: "Welcome to React Router v7 + Intlayer", es: "Bienvenido a React Router v7 + Intlayer", fr: "Bienvenue sur React Router v7 + Intlayer", }), description: t({ en: "Build multilingual applications with ease using React Router v7 and Intlayer.", es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.", fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.", }), aboutLink: t({ en: "Learn About Us", es: "Aprender Sobre Nosotros", fr: "En savoir plus sur nous", }), },} satisfies Dictionary;export default pageContent;Copiare il codice nella clipboard
import { t, type Dictionary } from "intlayer";const aboutContent = { key: "about", content: { title: t({ en: "About Us", es: "Sobre Nosotros", fr: "À propos de nous", }), content: t({ en: "This is the about page content.", es: "Este es el contenido de la página de información.", fr: "Ceci est le contenu de la page à propos.", }), homeLink: t({ en: "Home", es: "Inicio", fr: "Accueil", }), },} satisfies Dictionary;export default aboutContent;Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena vengono incluse nella directorycontentDir(per default,./app). E devono corrispondere all'estensione del file di dichiarazione del contenuto (per default,.content.{json,ts,tsx,js,jsx,mjs,cjs}).
Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.
Passo 7: Crea Componenti Consapevoli della Locale
Crea un componente LocalizedLink per una navigazione consapevole della locale:
Copiare il codice nella clipboard
import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);// Funzione per localizzare l'URL in base alla linguaexport const locacalizeTo = (to: To, locale: LocalesValues): To => { if (typeof to === "string") { if (isExternalLink(to)) { return to; } return getLocalizedUrl(to, locale); } if (isExternalLink(to.pathname ?? "")) { return to; } return { ...to, pathname: getLocalizedUrl(to.pathname ?? "", locale), };};// Componente per link localizzatiexport const LocalizedLink: FC<LinkProps> = (props) => { const { locale } = useLocale(); return <Link {...props} to={locacalizeTo(props.to, locale)} />;};Nel caso in cui desideri navigare verso le rotte localizzate, puoi utilizzare l'hook useLocalizedNavigate:
Copiare il codice nella clipboard
import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate = (to: To, options?: NavigateOptions) => { const localedTo = locacalizeTo(to, locale); navigate(localedTo, options); }; return localizedNavigate;};Passo 8: Crea un Componente per il Selettore di Lingua
Crea un componente per permettere agli utenti di cambiare lingua:
Copiare il codice nella clipboard
import type { FC } from "react";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, getPathWithoutLocale, Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeItem) => ( <li key={localeItem}> <Link aria-current={localeItem === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`} reloadDocument // Ricaricare la pagina per applicare la nuova locale to={getLocalizedUrl(pathWithoutLocale, localeItem)} > <span> {/* Locale - es. FR */} {localeItem} </span> <span> {/* Lingua nella propria Locale - es. Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Lingua nella Locale corrente - es. Francés con la locale corrente impostata su Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Lingua in inglese - es. French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </Link> </li> ))} </ol> );};Per saperne di più sull'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
import { 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]);};Questo hook è già utilizzato nel componente di layout (root.tsx) mostrato nel Passo 5.
(Opzionale) Passaggio 1 : Estrarre il contenuto dei tuoi componenti
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:
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;Esegui l'estrattore per trasformare i tuoi componenti ed estrarre il contenuto
Copiare il codice nella clipboard
npx intlayer extractConfigure TypeScript
Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
Ensure your TypeScript configuration includes the autogenerated types:
Copiare il codice nella clipboard
{ // ... your existing configurations include: [ // ... your existing includes ".intlayer/**/*.ts", // Include the auto-generated types ],}Git Configuration
It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
To do this, you can add the following instructions to your .gitignore file:
Copiare il codice nella clipboard
# Ignora i file generati da Intlayer.intlayerVS Code Extension
To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.
Install from the VS Code Marketplace
This extension provides:
- Autocompletion for translation keys.
- Real-time error detection for missing translations.
- Inline previews of translated content.
- Quick actions to easily create and update translations.
For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.
Go Further
To go further, you can implement the visual editor or externalize your content using the CMS.
Documentation References
- Intlayer Documentation
- React Router v7 Documentation
- React Router fs-routes Documentation
- useIntlayer hook
- useLocale hook
- Content Declaration
- Configuration
This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 using file-system based routing for a fully internationalized application with locale-aware routing and TypeScript support.
Passo 10: Aggiungere il middleware (Opzionale)
Puoi anche utilizzare intlayerProxy per aggiungere il routing lato server alla tua applicazione. Questo plugin rileverà automaticamente la lingua corrente basandosi sull'URL e imposterà il cookie della lingua appropriata. Se non viene specificata alcuna lingua, il plugin determinerà la lingua più adatta in base alle preferenze linguistiche del browser dell'utente. Se non viene rilevata alcuna lingua, verrà effettuato un reindirizzamento alla lingua predefinita.
Nota che per utilizzareintlayerProxyin produzione, è necessario spostare il pacchettovite-intlayerdadevDependenciesadependencies.
Copiare il codice nella clipboard
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({ plugins: [ intlayerProxy(), // should be placed first reactRouter(), intlayer(), ],});Configurare TypeScript
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
È consigliato ignorare i file generati da Intlayer. Questo ti permette di evitare di committarli nel tuo repository Git.
Per farlo, puoi aggiungere le seguenti istruzioni nel tuo file .gitignore:
Copiare il codice nella clipboard
# Ignora i file generati da Intlayer.intlayerEstensione 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.
Andare Oltre
Per andare oltre, puoi implementare l’editor visuale oppure esternalizzare i tuoi contenuti utilizzando il CMS.
Riferimenti alla Documentazione
- Documentazione Intlayer
- Documentazione React Router v7
- Documentazione React Router fs-routes
- Hook useIntlayer
- Hook useLocale
- Dichiarazione dei Contenuti
- Configurazione
Questa guida completa fornisce tutto il necessario per integrare Intlayer con React Router v7 usando routing basato sul file system per un'applicazione completamente internazionalizzata con routing consapevole della localizzazione e supporto TypeScript.