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
Introduzione all'Internazionalizzazione (i18n) con Intlayer e React Create App
Consulta Application Template su GitHub.
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 metadati, percorsi e contenuti.
- Garantire il supporto TypeScript con tipi autogenerati, migliorando l'autocompletamento e il rilevamento degli errori.
- Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della lingua.
Guida passo-passo per configurare Intlayer in un'applicazione React
Passo 1: Installa le dipendenze
Installa i pacchetti necessari utilizzando npm:
Copiare il codice nella clipboard
npm install intlayer react-intlayer react-scripts-intlayer
intlayer
Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione delle configurazioni, traduzioni, dichiarazione dei contenuti, transpilation e comandi CLI.
react-intlayer
Il pacchetto che integra Intlayer con l'applicazione React. Fornisce provider di contesto e hook per l'internazionalizzazione in React.
react-scripts-intlayer Include i comandi e i plugin react-scripts-intlayer per integrare Intlayer con l'applicazione basata su Create React App. Questi plugin sono basati su craco e includono configurazioni aggiuntive per il bundler Webpack.
Passo 2: Configurazione del progetto
Crea un file di configurazione per configurare 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, // Altre lingue ], defaultLocale: Locales.ENGLISH, },};export default config;
Tramite questo file di configurazione, puoi configurare URL localizzati, reindirizzamenti middleware, nomi dei cookie, la posizione e l'estensione delle dichiarazioni dei contenuti, disabilitare i log di Intlayer nella console e altro. Per un elenco completo dei parametri disponibili, consulta la documentazione di configurazione.
Passo 3: Integra Intlayer nella configurazione CRA
Modifica i tuoi script per utilizzare react-intlayer
Copiare il codice nella clipboard
"scripts": { "build": "react-scripts-intlayer build", "start": "react-scripts-intlayer start", "transpile": "intlayer build" },
Gli script react-scripts-intlayer sono basati su CRACO. Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. Vedi esempio qui.
Passo 4: Dichiarare i tuoi contenuti
Crea e gestisci le dichiarazioni dei tuoi contenuti per memorizzare le traduzioni:
Gli script react-scripts-intlayer sono basati su CRACO. Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. Vedi esempio qui.
Passo 4: Dichiarare i tuoi contenuti
Crea e gestisci le dichiarazioni dei tuoi contenuti per memorizzare le traduzioni:
Copiare il codice nella clipboard
import { t, type Dictionary } from "intlayer";import React, { type ReactNode } from "react";const appContent = { key: "app", content: { getStarted: t<ReactNode>({ en: ( <> Edit <code>src/App.tsx</code> and save to reload </> ), fr: ( <> Éditez <code>src/App.tsx</code> et enregistrez pour recharger </> ), es: ( <> Edita <code>src/App.tsx</code> y guarda para recargar </> ), }), reactLink: { href: "https://reactjs.org", content: t({ en: "Learn React", fr: "Apprendre React", es: "Aprender React", }), }, },} satisfies Dictionary;export default appContent;
Le dichiarazioni dei tuoi contenuti possono essere definite ovunque nella tua applicazione purché siano incluse nella directory contentDir (di default, ./src). E corrispondano all'estensione del file di dichiarazione dei contenuti (di default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).
Per maggiori dettagli, consulta la documentazione sulla dichiarazione dei contenuti.
Se il tuo file di contenuti include codice TSX, considera di importare import React from "react"; nel tuo file di contenuti.
Passo 5: Utilizza Intlayer nel tuo codice
Accedi ai tuoi dizionari di contenuti in tutta l'applicazione:
Copiare il codice nella clipboard
import logo from "./logo.svg";import "./App.css";import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const content = useIntlayer("app"); return ( <div className="App"> <img src={logo} className="App-logo" alt="logo" /> {content.getStarted} <a className="App-link" href={content.reactLink.href.value} target="_blank" rel="noopener noreferrer" > {content.reactLink.content} </a> </div> );};const App: FC = () => ( <IntlayerProvider> <AppContent /> </IntlayerProvider>);export default App;
Nota: se vuoi usare i tuoi contenuti in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare il valore della funzione, ad esempio:
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: Cambia la lingua dei tuoi contenuti
Per cambiare la lingua dei tuoi contenuti, puoi utilizzare la funzione setLocale fornita dall'hook useLocale. Questa funzione ti consente di impostare la lingua dell'applicazione e aggiornare i contenuti di conseguenza.
Copiare il codice nella clipboard
import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher = () => { const { setLocale } = useLocale(); return ( <button onClick={() => setLocale(Locales.English)}> Change Language to English </button> );};
Per saperne di più sull'hook useLocale, consulta la documentazione.
(Opzionale) Passo 7: Aggiungi routing localizzato alla tua applicazione
Lo scopo di questo passaggio è creare percorsi univoci per ogni lingua. Questo è utile per la SEO e per URL SEO-friendly. Esempio:
Copiare il codice nella clipboard
- https://example.com/about- https://example.com/es/about- https://example.com/fr/about
Di default, i percorsi non sono prefissati per la lingua predefinita. Se desideri prefissare la lingua predefinita, puoi impostare l'opzione middleware.prefixDefault su true nella tua configurazione. Consulta la documentazione di configurazione per maggiori informazioni.
Per aggiungere il routing localizzato alla tua applicazione, puoi creare un componente LocaleRouter che avvolge i percorsi 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'// 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 localizzazione basata sull'URL. */const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({ children, locale,}) => { const { pathname, search } = useLocation(); // Ottieni il percorso URL corrente // Determina la localizzazione corrente, usando quella di default se non fornita const currentLocale = locale ?? defaultLocale; // Rimuove il prefisso della localizzazione dal percorso per costruire un percorso base const pathWithoutLocale = getPathWithoutLocale( pathname // Percorso URL corrente ); /** * Se middleware.prefixDefault è true, la localizzazione di default deve essere sempre prefissata. */ if (middleware.prefixDefault) { // Valida la localizzazione if (!locale || !locales.includes(locale)) { // Reindirizza alla localizzazione 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 è false, 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) // Verifica 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 rotte specifiche per la locale. * Usa React Router per gestire la navigazione e rendere componenti localizzati. */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => ( <BrowserRouter> <Routes> {locales .filter( (locale) => middleware.prefixDefault || locale !== defaultLocale ) .map((locale) => ( <Route // Pattern 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 al percorso root !middleware.prefixDefault && ( <Route path="*" element={ <AppLocalized locale={defaultLocale}>{children}</AppLocalized> } // Avvolge i figli con la gestione della locale /> ) } </Routes> </BrowserRouter>);
Then, you can use the LocaleRouter component in your application:
Copiare il codice nella clipboard
import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... Il tuo componente AppContentconst App: FC = () => ( <LocaleRouter> <AppContent /> </LocaleRouter>);
(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 URL.
Per modificare l'URL quando cambia la lingua, puoi usare la proprietà onLocaleChange fornita dall'hook useLocale. Parallelamente, puoi utilizzare gli hook useLocation e useNavigate di react-router-dom per aggiornare il percorso 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 lingua 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:
(Opzionale) Passo 9: Modificare 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 farli 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 i contenuti.
- Rendering del testo: L'attributo dir (direzione) garantisce 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 pagina, aiutando a mostrare il contenuto localizzato corretto 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 di locale 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 al locale 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 alla locale corrente. document.documentElement.lang = locale; // Imposta la direzione del testo in base alla locale corrente. 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 si aggiornino 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 l'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, 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 diversi.
- Fornirà un'esperienza più accessibile, poiché le tecnologie assistive dipendono da questi attributi per funzionare al meglio.
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 TypeScript includa i tipi generati automaticamente.
Copiare il codice nella clipboard
{ // ... 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 la Intlayer VS Code Extension ufficiale. 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. 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.
Approfondimenti
Per approfondire, puoi implementare l’editor visuale o esternalizzare i tuoi contenuti usando il CMS.
Cronologia della documentazione
- 5.5.10 - 2025-06-29: Cronologia iniziale