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
Guida passo-passo per configurare Intlayer in un'applicazione Vite e React
Passo 1: Installa le dipendenze
Installa i pacchetti necessari usando npm:
Copiare il codice nella clipboard
npm install intlayer react-intlayernpm 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 le applicazioni 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 lingua preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.
Passo 2: Configurazione del tuo progetto
Crea un file di configurazione per impostare le lingue della tua applicazione:
Copiare il codice nella clipboard
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [ Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, // Le tue altre localizzazioni ], defaultLocale: Locales.ENGLISH, },};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 3: Integra Intlayer nella tua configurazione Vite
Aggiungi il plugin intlayer nella tua configurazione.
Copiare il codice nella clipboard
import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({ plugins: [react(), intlayerPlugin()],});
Il plugin Vite intlayerPlugin() 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.
Passo 4: Dichiara il Tuo Contenuto
Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:
Copiare il codice nella clipboard
import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = { key: "app", content: { viteLogo: t({ en: "Vite logo", fr: "Logo Vite", es: "Logo Vite", }), reactLogo: t({ en: "React logo", fr: "Logo React", es: "Logo React", }), title: "Vite + React", count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es ", }), edit: t<ReactNode>({ en: ( <> Modifica <code>src/App.tsx</code> e salva per testare HMR </> ), fr: ( <> Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR </> ), es: ( <> Edita <code>src/App.tsx</code> y guarda para probar HMR </> ), }), readTheDocs: t({ en: "Clicca sui loghi di Vite e React per saperne di più", fr: "Cliquez sur les logos Vite et React pour en savoir plus", es: "Haga clic en los logotipos de Vite y React para obtener más información", }), },} 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, ./src). 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 sulle dichiarazioni di contenuto.
Se il tuo file di contenuto include codice TSX, dovresti considerare di importare import React from "react"; nel tuo file di contenuto.
Passo 5: Utilizza Intlayer nel tuo Codice
Accedi ai tuoi dizionari di contenuti in tutta la tua applicazione:
Copiare il codice nella clipboard
import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app"); return ( <> <div> <a href="https://vitejs.dev" target="_blank"> <img src={viteLogo} className="logo" alt={content.viteLogo.value} /> </a> <a href="https://react.dev" target="_blank"> <img src={reactLogo} className="logo react" alt={content.reactLogo.value} /> </a> </div> <h1>{content.title}</h1> <div className="card"> <button onClick={() => setCount((count) => count + 1)}> {content.count} {count} </button> <p>{content.edit}</p> </div> <p className="read-the-docs">{content.readTheDocs}</p> </> );};const App: FC = () => ( <IntlayerProvider> <AppContent /> </IntlayerProvider>);export default App;
Se vuoi usare il tuo contenuto in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare il valore della funzione, come:
jsxCopiare il codiceCopiare il codice nella clipboard
<img src={content.image.src.value} alt={content.image.value} />
Per saperne di più sull'hook useIntlayer, consulta la documentazione.
(Opzionale) Passo 6: Cambiare la lingua del tuo contenuto
Per cambiare la lingua del tuo contenuto, puoi utilizzare la funzione setLocale fornita dall'hook useLocale. Questa funzione ti permette di impostare la localizzazione dell'applicazione e aggiornare di conseguenza il contenuto.
Copiare il codice nella clipboard
import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => { const { setLocale } = useLocale(); return ( <button onClick={() => setLocale(Locales.English)}> Cambia lingua in Inglese </button> );};
Per saperne di più sull'hook useLocale, consulta la documentazione.
(Opzionale) Passo 7: Aggiungere il routing localizzato alla tua applicazione
Lo scopo di questo passaggio è creare rotte uniche per ogni lingua. Questo è utile per la SEO e per URL amichevoli per i motori di ricerca. Esempio:
Copiare il codice nella clipboard
- https://example.com/about- https://example.com/es/about- https://example.com/fr/about
Per impostazione predefinita, i percorsi non sono prefissati per la lingua predefinita. Se desideri aggiungere un prefisso anche per la lingua predefinita, puoi impostare l'opzione middleware.prefixDefault su true nella tua configurazione. Consulta la documentazione sulla configurazione per maggiori informazioni.
Per aggiungere il routing localizzato alla tua applicazione, puoi creare un componente LocaleRouter che avvolge le rotte della tua applicazione e gestisce il routing basato sulla lingua. Ecco un esempio che utilizza React Router:
Copiare il codice nella clipboard
// Importing necessary dependencies and functionsimport { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Funzioni di utilità e tipi da 'intlayer'import type { FC, PropsWithChildren } from "react"; // Tipi React per componenti funzionali e propsimport { IntlayerProvider } from "react-intlayer"; // Provider per il contesto di internazionalizzazioneimport { BrowserRouter, Routes, Route, Navigate, useLocation,} from "react-router-dom"; // Componenti router per la gestione della navigazione// Destrutturazione della configurazione da Intlayerconst { internationalization, middleware } = configuration;const { locales, defaultLocale } = internationalization;/** * Un componente che gestisce la localizzazione e avvolge i figli con il contesto locale appropriato. * Gestisce il rilevamento e la validazione della lingua basata sull'URL. */const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({ children, locale,}) => { const { pathname, search } = useLocation(); // Ottieni il percorso URL corrente // Determina la locale corrente, utilizzando quella di default se non fornita const currentLocale = locale ?? defaultLocale; // Rimuovi il prefisso della locale dal percorso per costruire un percorso base const pathWithoutLocale = getPathWithoutLocale( pathname // Percorso URL corrente ); /** * Se middleware.prefixDefault è true, la locale di default deve sempre essere prefissata. */ if (middleware.prefixDefault) { // Valida la locale if (!locale || !locales.includes(locale)) { // Reindirizza alla locale di default con il percorso aggiornato return ( <Navigate to={`/${defaultLocale}/${pathWithoutLocale}${search}`} replace // Sostituisce la voce corrente nella cronologia con quella nuova /> ); } // Avvolge i figli con IntlayerProvider e imposta la locale corrente return ( <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider> ); } else { /** * Quando middleware.prefixDefault è falso, la locale predefinita non è prefissata. * Assicurarsi che la locale corrente sia valida e non la locale predefinita. */ if ( currentLocale.toString() !== defaultLocale.toString() && !locales .filter( (locale) => locale.toString() !== defaultLocale.toString() // Esclude la locale predefinita ) .includes(currentLocale) // Controlla se la locale corrente è nella lista delle locale valide ) { // Reindirizza al percorso senza prefisso della locale return <Navigate to={`${pathWithoutLocale}${search}`} replace />; } // Avvolge i figli con IntlayerProvider e imposta la locale corrente return ( <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider> ); }};/** * Un componente router che configura le rotte specifiche per la locale. * Usa React Router per gestire la navigazione e renderizzare componenti localizzati. */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => ( <BrowserRouter> <Routes> {locales .filter( (locale) => middleware.prefixDefault || locale !== defaultLocale ) .map((locale) => ( <Route // Modello di percorso per catturare la locale (es. /en/, /fr/) e corrispondere a tutti i percorsi successivi path={`/${locale}/*`} key={locale} element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Avvolge i figli con la gestione della locale /> ))} { // Se il prefisso per la locale predefinita è disabilitato, renderizza i figli direttamente nel percorso root !middleware.prefixDefault && ( <Route path="*" element={ <AppLocalized locale={defaultLocale}>{children}</AppLocalized> } // Avvolge i figli con la gestione della locale /> ) } </Routes> </BrowserRouter>);
Quindi, puoi utilizzare il componente LocaleRouter nella tua applicazione:
Copiare il codice nella clipboard
import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... Il tuo componente AppContentconst App: FC = () => ( <LocaleRouter> <AppContent /> </LocaleRouter>);
In parallelo, puoi anche utilizzare il intLayerMiddlewarePlugin 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.
Copiare il codice nella clipboard
import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({ plugins: [react(), intlayerPlugin(), intLayerMiddlewarePlugin()],});
(Opzionale) Passo 8: Cambiare l'URL quando la lingua cambia
Per cambiare l'URL quando la lingua cambia, puoi usare la proprietà onLocaleChange fornita dall'hook useLocale. Parallelamente, puoi usare gli hook useLocation e useNavigate di react-router-dom per aggiornare il percorso dell'URL.
Copiare il codice nella clipboard
import { useLocation, useNavigate } from "react-router-dom";import { Locales, getHTMLTextDir, getLocaleName, getLocalizedUrl,} from "intlayer";import { useLocale } from "react-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => { const { pathname, search } = useLocation(); // Ottieni il percorso URL corrente. Esempio: /fr/about?foo=bar const navigate = useNavigate(); const { locale, availableLocales, setLocale } = useLocale({ onLocaleChange: (locale) => { // Costruisci l'URL con la locale aggiornata // Esempio: /es/about?foo=bar const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale); // Aggiorna il percorso URL navigate(pathWithLocale); }, }); return ( <div> <button popoverTarget="localePopover">{getLocaleName(locale)}</button> <div id="localePopover" popover="auto"> {availableLocales.map((localeItem) => ( <a href={getLocalizedUrl(location.pathname, localeItem)} hrefLang={localeItem} aria-current={locale === localeItem ? "page" : undefined} onClick={(e) => { e.preventDefault(); setLocale(localeItem); }} key={localeItem} > <span> {/* Località - es. FR */} {localeItem} </span> <span> {/* Lingua nella sua stessa località - es. Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Lingua nella località corrente - es. Francés con la località corrente impostata su Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Lingua in inglese - es. French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </a> ))} </div> </div> );};
Riferimenti alla documentazione:
Di seguito il Passo 9 aggiornato con spiegazioni aggiuntive ed esempi di codice migliorati:
(Opzionale) Passo 9: Cambiare gli attributi di lingua e direzione dell’HTML
Quando la tua applicazione supporta più lingue, è fondamentale aggiornare gli attributi lang e dir del tag <html> per corrispondere alla locale corrente. Questo garantisce:
- Accessibilità: I lettori di schermo e le tecnologie assistive si basano sull'attributo lang corretto per pronunciare e interpretare accuratamente il contenuto.
- Rendering del testo: L'attributo dir (direzione) assicura che il testo venga visualizzato nell'ordine corretto (ad esempio, da sinistra a destra per l'inglese, da destra a sinistra per l'arabo o l'ebraico), essenziale per la leggibilità.
- SEO: I motori di ricerca utilizzano l'attributo lang per determinare la lingua della tua pagina, aiutando a mostrare il contenuto localizzato appropriato nei risultati di ricerca.
Aggiornando dinamicamente questi attributi quando la lingua cambia, garantisci un'esperienza coerente e accessibile per gli utenti in tutte le lingue supportate.
Implementazione del Hook
Crea un hook personalizzato per gestire gli attributi HTML. L'hook ascolta i cambiamenti della lingua e aggiorna gli attributi di conseguenza:
Copiare il codice nella clipboard
import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";/** * Aggiorna gli attributi `lang` e `dir` dell'elemento HTML <html> in base alla lingua corrente. * - `lang`: Informa browser e motori di ricerca sulla lingua della pagina. * - `dir`: Garantisce l'ordine di lettura corretto (es. 'ltr' per inglese, 'rtl' per arabo). * * Questo aggiornamento dinamico è essenziale per una corretta resa del testo, accessibilità e SEO. */export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { // Aggiorna l'attributo della lingua all'attuale locale. document.documentElement.lang = locale; // Imposta la direzione del testo in base all'attuale locale. document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};
Utilizzo del Hook nella Tua Applicazione
Integra il hook nel tuo componente principale in modo che gli attributi HTML vengano aggiornati ogni volta che la locale cambia:
Copiare il codice nella clipboard
import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => { // Applica il hook per aggiornare gli attributi lang e dir del tag <html> in base alla locale. useI18nHTMLAttributes(); // ... Resto del tuo componente};const App: FC = () => ( <IntlayerProvider> <AppContent /> </IntlayerProvider>);export default App;
Applicando queste modifiche, la tua applicazione:
- Garantirà che l'attributo language (lang) rifletta correttamente la locale corrente, importante per la SEO e il comportamento del browser.
- Adatterà la direzione del testo (dir) in base alla locale, migliorando la leggibilità e l'usabilità per lingue con ordini di lettura differenti.
- Fornirà un'esperienza più accessibile, poiché le tecnologie assistive si basano su questi attributi per funzionare al meglio.
(Opzionale) Passo 10: Creare un componente Link localizzato
// Applica l'hook per aggiornare gli attributi lang e dir del tag in base alla locale. useI18nHTMLAttributes();
// ... Resto del tuo componente };
const App = () => (
module.exports = App;
Applicando queste modifiche, la tua applicazione: - Garantirà che l'attributo **lingua** (`lang`) rifletta correttamente la locale corrente, cosa importante per la SEO e il comportamento del browser. - Adatterà la **direzione del testo** (`dir`) in base alla locale, migliorando la leggibilità e l'usabilità per le lingue con ordini di lettura differenti. - Fornirà un'esperienza più **accessibile**, poiché le tecnologie assistive dipendono da questi attributi per funzionare in modo ottimale. ### (Opzionale) Passo 10: Creare un componente Link localizzato Per garantire che la navigazione della tua applicazione rispetti la lingua corrente, puoi creare un componente `Link` personalizzato. Questo componente aggiunge automaticamente il prefisso della lingua corrente agli URL interni. Ad esempio, quando un utente francofono clicca su un link alla pagina "About", viene reindirizzato a `/fr/about` invece che a `/about`. Questo comportamento è utile per diversi motivi: - **SEO e esperienza utente**: Gli URL localizzati aiutano i motori di ricerca a indicizzare correttamente le pagine specifiche per lingua e forniscono agli utenti contenuti nella loro lingua preferita. - **Coerenza**: Utilizzando un link localizzato in tutta l'applicazione, garantisci che la navigazione rimanga all'interno della lingua corrente, evitando cambiamenti di lingua imprevisti. - **Manutenibilità**: Centralizzare la logica di localizzazione in un unico componente semplifica la gestione degli URL, rendendo il tuo codice più facile da mantenere ed estendere man mano che la tua applicazione cresce. Di seguito è riportata l'implementazione di un componente `Link` localizzato in TypeScript: ```tsx fileName="src/components/Link.tsx" codeFormat="typescript" import { getLocalizedUrl } from "intlayer"; import { forwardRef, type DetailedHTMLProps, type AnchorHTMLAttributes, } from "react"; import { useLocale } from "react-intlayer"; export interface LinkProps extends DetailedHTMLProps< AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement > {} /** * Funzione di utilità per verificare se un dato URL è esterno. * Se l'URL inizia con http:// o https://, è considerato esterno. */ export const checkIsExternalLink = (href?: string): boolean => /^https?:\/\//.test(href ?? ""); /** * Un componente Link personalizzato che adatta l'attributo href in base alla locale corrente. * Per i link interni, utilizza `getLocalizedUrl` per aggiungere il prefisso della locale all'URL (es. /fr/about). * Questo garantisce che la navigazione rimanga all'interno dello stesso contesto di locale. */ export const Link = forwardRef<HTMLAnchorElement, LinkProps>( ({ href, children, ...props }, ref) => { const { locale } = useLocale(); const isExternalLink = checkIsExternalLink(href); // Se il link è interno e viene fornito un href valido, ottieni l'URL localizzato. const hrefI18n = href && !isExternalLink ? getLocalizedUrl(href, locale) : href; return ( <a href={hrefI18n} ref={ref} {...props}> {children} </a> ); } ); Link.displayName = "Link";Come Funziona
Rilevamento dei Link Esterni:
La funzione di supporto checkIsExternalLink determina se un URL è esterno. I link esterni vengono lasciati invariati perché non necessitano di localizzazione.Recupero della Locale Corrente:
L'hook useLocale fornisce la locale corrente (ad esempio, fr per francese).Localizzazione dell'URL:
Per i link interni (cioè non esterni), getLocalizedUrl viene utilizzato per aggiungere automaticamente il prefisso della locale corrente all'URL. Ciò significa che se l'utente è in francese, passando /about come href verrà trasformato in /fr/about.Restituzione del Link:
Il componente restituisce un elemento <a> con l'URL localizzato, garantendo che la navigazione sia coerente con la lingua selezionata.
Integrando questo componente Link in tutta la tua applicazione, mantieni un'esperienza utente coerente e consapevole della lingua, beneficiando anche di un miglior SEO e usabilità.
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 TypeScript esistenti "include": [Il componente restituisce un elemento `<a>` con l'URL localizzato, garantendo che la navigazione sia coerente con la lingua selezionata.Integrando questo componente `Link` in tutta la tua applicazione, mantieni un'esperienza utente coerente e consapevole della lingua, beneficiando inoltre di un miglior SEO e usabilità.### Configurare TypeScriptIntlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.Assicurati che la tua configurazione TypeScript includa i tipi generati automaticamente.```json5 fileName="tsconfig.json"{ // ... Le tue configurazioni TypeScript esistenti "include": [ // ... Le tue configurazioni TypeScript 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 farlo, 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 VS Code Extension.
Installa dal Marketplace di VS Code
Questa estensione offre:
- Completamento automatico per le chiavi di traduzione.
- Rilevamento errori in tempo reale per le 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.
Approfondimenti
Per approfondire, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.
Cronologia del documento
- 5.5.10 - 2025-06-29: Inizio cronologia