Iniziare a Internazionalizzare (i18n) con Intlayer e React Create App
Cos'è Intlayer?
Intlayer è una libreria di internazionalizzazione (i18n) innovativa e open-source 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 metadati, le rotte e i contenuti.
- Garantire il supporto TypeScript con tipi generati automaticamente, migliorando l'autocompletamento e la rilevazione degli errori.
- Beneficiare di funzionalità avanzate, come la rilevazione e il cambio dinamico della locale.
Guida Passo-Passo per Configurare Intlayer in un'Applicazione React
Passo 1: Installa le Dipendenze
Installa i pacchetti necessari utilizzando npm:
1npm install intlayer react-intlayer1yarn add intlayer react-intlayer1pnpm add intlayer react-intlayerPasso 2: Configurazione del tuo progetto
Crea un file di configurazione per configurare le lingue della tua applicazione:
1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6 internationalization: {
7 locales: [
8 Locales.ENGLISH,
9 Locales.FRENCH,
10 Locales.SPANISH,
11 // Le tue altre lingue
12 ],
13 defaultLocale: Locales.ENGLISH,
14 },
15};
16
17export default config;Per vedere tutti i parametri disponibili, fai riferimento alla documentazione di configurazione qui.
Passo 3: Integra Intlayer nella tua Configurazione CRA
Cambia i tuoi script per usare react-intlayer
1 "scripts": {
2 "build": "react-intlayer build",
3 "start": "react-intlayer start",
4 "transpile": "intlayer build"
5 },Nota: gli script di react-intlayer si basano su craco. Puoi anche implementare la tua configurazione basata sul plugin craco di intlayer. Vedi l'esempio qui.
Passo 4: Dichiarare il tuo Contenuto
Crea e gestisci i tuoi dizionari di contenuto:
1// src/app.content.tsx
2import { t, type DeclarationContent } from "intlayer";
3import { type ReactNode } from "react";
4
5const appContent = {
6 key: "app",
7 content: {
8 getStarted: t<ReactNode>({
9 en: (
10 <>
11 Modifica <code>src/App.tsx</code> e salva per ricaricare
12 </>
13 ),
14 fr: (
15 <>
16 Éditez <code>src/App.tsx</code> et enregistrez pour recharger
17 </>
18 ),
19 es: (
20 <>
21 Edita <code>src/App.tsx</code> y guarda para recargar
22 </>
23 ),
24 }),
25 reactLink: {
26 href: "https://reactjs.org",
27 content: t({
28 en: "Impara React",
29 fr: "Apprendre React",
30 es: "Aprender React",
31 }),
32 },
33 },
34} satisfies DeclarationContent;
35
36export default appContent;Vedi come dichiarare i tuoi file di dichiarazione Intlayer.
Passo 5: Utilizza Intlayer nel tuo Codice
Accedi ai tuoi dizionari di contenuto in tutta l'applicazione:
1import logo from "./logo.svg";
2import "./App.css";
3import { IntlayerProvider, useIntlayer } from "react-intlayer";
4import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
5
6function AppContent() {
7 const content = useIntlayer("app");
8
9 return (
10 <header className="App-header">
11 <img src={logo} className="App-logo" alt="logo" />
12
13 {content.getStarted}
14 <a
15 className="App-link"
16 href={content.reactLink.href.value}
17 target="_blank"
18 rel="noopener noreferrer"
19 >
20 {content.reactLink.content}
21 </a>
22 </header>
23 );
24}
25
26function App() {
27 return (
28 <IntlayerProvider>
29 <div className="App">
30 {/* Per usare correttamente l'hook useIntlayer, dovresti accedere ai tuoi dati in un componente figlio */}
31 <AppContent />
32 </div>
33 <div className="absolute bottom-5 right-5 z-50">
34 <LocaleSwitcher />
35 </div>
36 </IntlayerProvider>
37 );
38}
39
40export default App;Nota: Se desideri utilizzare il tuo contenuto in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare il valore della funzione, come:
tsx1<img src={content.image.src.value} alt={content.image.value} />
(Opzionale) Passo 6: Cambiare la lingua del tuo contenuto
Per cambiare la lingua del tuo contenuto, puoi usare la funzione setLocale fornita dall'hook useLocale. Questa funzione consente di impostare la locale dell'applicazione e aggiornare i contenuti di conseguenza.
1import { Locales } from "intlayer";
2import { useLocale } from "react-intlayer";
3
4const LocaleSwitcher = () => {
5 const { setLocale } = useLocale();
6
7 return (
8 <button onClick={() => setLocale(Locales.English)}>
9 Cambiare lingua in Inglese
10 </button>
11 );
12};(Opzionale) Passo 7: Aggiungere Routing Localizzato alla tua applicazione
Lo scopo di questo passaggio è creare rotte uniche per ogni lingua. Questo è utile per SEO e URL friendly.
Esempio:
1// /dashboard
2// /es/dashboard
3// /fr/dashboardPer impostazione predefinita, le rotte non sono prefissate per la locale predefinita. Se desideri prefissare la locale predefinita, puoi impostare l'opzione middleware.prefixDefault su true nella tua configurazione. Vedi la documentazione di configurazione per ulteriori informazioni.
Per aggiungere routing localizzato alla tua applicazione, puoi creare un componente LocaleRouter che avvolge le rotte della tua applicazione e gestisce il routing basato sulla locale. Ecco un esempio usando React Router:
1// Importare dipendenze e funzioni necessarie
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // Funzioni e tipi di utilità da 'intlayer'
3import { FC, PropsWithChildren } from "react"; // Tipi React per componenti funzionali e props
4import { IntlayerProvider } from "react-intlayer"; // Provider per il contesto di internazionalizzazione
5import {
6 BrowserRouter,
7 Routes,
8 Route,
9 useParams,
10 Navigate,
11 useLocation,
12} from "react-router-dom"; // Componenti Router per gestire la navigazione
13
14// Destrutturazione della configurazione da Intlayer
15const { internationalization, middleware } = getConfiguration();
16const { locales, defaultLocale } = internationalization;
17
18/**
19 * Un componente che gestisce la localizzazione e avvolge i figli con il contesto locale appropriato.
20 * Gestisce la rilevazione e la validazione della locale basata su URL.
21 */
22const AppLocalized: FC<PropsWithChildren> = ({ children }) => {
23 const path = useLocation().pathname; // Ottieni il percorso URL attuale
24 const { locale } = useParams<{ locale: Locales }>(); // Estrai il parametro locale dall'URL
25
26 // Determina la locale attuale, tornando alla predefinita se non fornita
27 const currentLocale = locale ?? defaultLocale;
28
29 // Rimuovi il prefisso locale dal percorso per costruire un percorso di base
30 const pathWithoutLocale = removeLocaleFromUrl(
31 path // Percorso URL attuale
32 );
33
34 /**
35 * Se middleware.prefixDefault è vero, la locale predefinita deve sempre essere prefissata.
36 */
37 if (middleware.prefixDefault) {
38 // Valida la locale
39 if (!locale || !locales.includes(locale)) {
40 // Reindirizza alla locale predefinita con il percorso aggiornato
41 return (
42 <Navigate
43 to={`/${defaultLocale}/${pathWithoutLocale}`}
44 replace // Sostituisci l'attuale voce della cronologia con la nuova
45 />
46 );
47 }
48
49 // Avvolgi i bambini con l'IntlayerProvider e imposta la locale attuale
50 return (
51 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
52 );
53 } else {
54 /**
55 * Quando middleware.prefixDefault è falso, la locale predefinita non è prefissata.
56 * Assicurati che la locale attuale sia valida e non sia la locale predefinita.
57 */
58 if (
59 currentLocale.toString() !== defaultLocale.toString() &&
60 !locales
61 .filter(
62 (locale) => locale.toString() !== defaultLocale.toString() // Escludi la locale predefinita
63 )
64 .includes(currentLocale) // Controlla se la locale attuale è nell'elenco delle lingue valide
65 ) {
66 // Reindirizza al percorso senza prefisso locale
67 return <Navigate to={pathWithoutLocale} replace />;
68 }
69
70 // Avvolgi i bambini con l'IntlayerProvider e imposta la locale attuale
71 return (
72 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
73 );
74 }
75};
76
77/**
78 * Un componente router che crea rotte specifiche per la locale.
79 * Utilizza React Router per gestire la navigazione e rendere i componenti localizzati.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82 <BrowserRouter>
83 <Routes>
84 <Route
85 // Modello di percorso per catturare la locale (es. /en/, /fr/) e corrispondere a tutti i percorsi successivi
86 path="/:locale/*"
87 element={<AppLocalized>{children}</AppLocalized>} // Avvolge i bambini con la gestione della locale
88 />
89
90 {
91 // Se il prefisso della locale predefinita è disabilitato, rendi i bambini direttamente al percorso radice
92 !middleware.prefixDefault && (
93 <Route
94 path="*"
95 element={<AppLocalized>{children}</AppLocalized>} // Avvolge i bambini con la gestione della locale
96 />
97 )
98 }
99 </Routes>
100 </BrowserRouter>
101);(Opzionale) Passo 8: Cambiare l'URL quando cambia la locale
Per cambiare l'URL quando cambia la locale, puoi utilizzare la prop onLocaleChange fornita dall'hook useLocale. In parallelo, puoi utilizzare gli hooks useLocation e useNavigate da react-router-dom per aggiornare il percorso URL.
1import { Locales, getLocalizedUrl } from "intlayer";
2import { useLocale } from "react-intlayer";
3import { useLocation, useNavigate } from "react-router-dom";
4
5const LocaleSwitcher = () => {
6 const location = useLocation(); // Ottieni il percorso URL attuale. Esempio: /fr/about
7 const navigate = useNavigate();
8
9 const changeUrl = (locale: Locales) => {
10 // Costruisci l'URL con la locale aggiornata
11 // Esempio: /es/about con la locale impostata su Spagnolo
12 const pathWithLocale = getLocalizedUrl(location.pathname, locale);
13
14 // Aggiorna il percorso URL
15 navigate(pathWithLocale);
16 };
17
18 const { setLocale } = useLocale({
19 onLocaleChange: changeUrl,
20 });
21
22 return (
23 <button onClick={() => setLocale(Locales.English)}>
24 Cambiare lingua in Inglese
25 </button>
26 );
27};Configurare TypeScript
Intlayer utilizza l'augmentation del modulo per ottenere i vantaggi di TypeScript e rendere il tuo codice più robusto.
Assicurati che la tua configurazione TypeScript includa i tipi generati automaticamente.
1// tsconfig.json
2
3{
4 // la tua configurazione personalizzata
5 include: [
6 "src",
7 "types", // <- Include i tipi generati automaticamente
8 ],
9}Configurazione di Git
Si consiglia di ignorare i file generati da Intlayer. Questo ti consente di evitare di commetterli nel tuo repository Git.
Per farlo, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:
1# Ignora i file generati da Intlayer
2.intlayerSe hai un’idea per migliorare questa documentazione, non esitare a contribuire inviando una pull request su GitHub.
Collegamento GitHub alla documentazione