Getting Started Internationalizing (i18n) with Intlayer and Vite and React
What is Intlayer?
Intlayer è una libreria innovativa e open-source di 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 metadati, percorsi e contenuti.
- Garantire il supporto TypeScript con tipi autogenerati, migliorando l'autocompletamento e la rilevazione degli errori.
- Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamici della lingua.
Step-by-Step Guide to Set Up Intlayer in a Vite and React Application
Step 1: Install Dependencies
Installa i pacchetti necessari utilizzando npm:
1npm install intlayer react-intlayer1yarn add intlayer react-intlayer1pnpm add intlayer react-intlayerStep 2: Configuration of your project
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.ITALIAN, // Modificato per includere l'italiano
9 Locales.ENGLISH,
10 Locales.FRENCH,
11 Locales.SPANISH,
12 // Altre lingue
13 ],
14 defaultLocale: Locales.ENGLISH,
15 },
16};
17
18export default config;Per vedere tutti i parametri disponibili, consulta la documentazione di configurazione qui.
Step 3: Integrate Intlayer in Your Vite Configuration
Aggiungi il plugin intlayer nella tua configurazione.
1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react-swc";
3import { intLayerPlugin } from "react-intlayer/vite";
4
5// https://vitejs.dev/config/
6export default defineConfig({
7 plugins: [react(), intLayerPlugin()],
8});Step 4: Declare Your Content
Crea e gestisci i tuoi dizionari di contenuti:
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 viteLogo: t({
9 it: "Logo Vite", // Tradotto in italiano
10 en: "Vite logo",
11 fr: "Logo Vite",
12 es: "Logo Vite",
13 }),
14 reactLogo: t({
15 it: "Logo React", // Tradotto in italiano
16 en: "React logo",
17 fr: "Logo React",
18 es: "Logo React",
19 }),
20
21 title: "Vite + React",
22
23 count: t({
24 it: "il conteggio è ", // Tradotto in italiano
25 en: "count is ",
26 fr: "le compte est ",
27 es: "el recuento es ",
28 }),
29
30 edit: t<ReactNode>({
31 // Non dimenticare di importare React se utilizzi un nodo React nel tuo contenuto
32 it: (
33 <>
34 Modifica <code>src/App.tsx</code> e salva per testare HMR
35 </>
36 ),
37 en: (
38 <>
39 Edit <code>src/App.tsx</code> and save to test HMR
40 </>
41 ),
42 fr: (
43 <>
44 Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR
45 </>
46 ),
47 es: (
48 <>
49 Edita <code>src/App.tsx</code> y guarda para probar HMR
50 </>
51 ),
52 }),
53
54 readTheDocs: t({
55 it: "Clicca sui loghi di Vite e React per saperne di più", // Tradotto in italiano
56 en: "Click on the Vite and React logos to learn more",
57 fr: "Cliquez sur les logos Vite et React pour en savoir plus",
58 es: "Haga clic en los logotipos de Vite y React para obtener más información",
59 }),
60 },
61} satisfies DeclarationContent;
62
63export default appContent;Note: Se il tuo file di contenuto include codice TSX, dovresti considerare di importare import React from "react"; nel tuo file di contenuto.
See how to declare your Intlayer declaration files.
Step 5: Utilize Intlayer in Your Code
Accedi ai tuoi dizionari di contenuto in tutta la tua applicazione:
1import { useState } from "react";
2import reactLogo from "./assets/react.svg";
3import viteLogo from "/vite.svg";
4import "./App.css";
5import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
6import { IntlayerProvider, useIntlayer } from "react-intlayer";
7
8function AppContent() {
9 const [count, setCount] = useState(0);
10 const content = useIntlayer("app");
11
12 return (
13 <>
14 <div>
15 <a href="https://vitejs.dev" target="_blank">
16 <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
17 </a>
18 <a href="https://react.dev" target="_blank">
19 <img
20 src={reactLogo}
21 className="logo react"
22 alt={content.reactLogo.value}
23 />
24 </a>
25 </div>
26 <h1>{content.title}</h1>
27 <div className="card">
28 <button onClick={() => setCount((count) => count + 1)}>
29 {content.count}
30 {count}
31 </button>
32 <p>{content.edit}</p>
33 </div>
34 <p className="read-the-docs">{content.readTheDocs}</p>
35 <div className="absolute bottom-5 right-5 z-50">
36 <LocaleSwitcher />
37 </div>
38 </>
39 );
40}
41
42function App() {
43 return (
44 <IntlayerProvider>
45 <AppContent />
46 </IntlayerProvider>
47 );
48}
49
50export default App;Note: Se vuoi 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} />
(Optional) Step 6: Change the language of your content
Per cambiare la lingua del tuo contenuto, puoi usare la funzione setLocale fornita dal hook useLocale. Questa funzione consente di impostare la lingua dell'applicazione e aggiornare di conseguenza il contenuto.
1import { Locales } from "intlayer";
2import { useLocale } from "react-intlayer";
3
4const LocaleSwitcher = () => {
5 const { setLocale } = useLocale();
6
7 return (
8 <button onClick={() => setLocale(Locales.ITALIAN)}>
9 {" "}
10 {/* Modificato per includere l'italiano */}
11 Cambia lingua in Italiano
12 </button>
13 );
14};(Optional) Step 7: Add localized Routing to your application
Lo scopo di questo passaggio è creare percorsi unici per ogni lingua. Questo è utile per SEO e URL amichevoli per SEO. Esempio:
1// /dashboard
2// /it/dashboard
3// /fr/dashboardPer impostazione predefinita, 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 ulteriori informazioni.
Per aggiungere il routing localizzato alla tua applicazione, puoi creare un componente LocaleRouter che racchiude i percorsi della tua applicazione e gestisce il routing basato sulla lingua. Ecco un esempio usando React Router:
1// Importazione delle dipendenze e delle funzioni necessarie
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // Funzioni e tipi utili 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 di lingua appropriato.
20 * Gestisce la rilevazione e la validazione della lingua basata sull'URL.
21 */
22const AppLocalized: FC<PropsWithChildren> = ({ children }) => {
23 const path = useLocation().pathname; // Ottieni il percorso URL corrente
24 const { locale } = useParams<{ locale: Locales }>(); // Estrai il parametro lingua dall'URL
25
26 // Determina la lingua corrente, tornando alla predefinita se non fornita
27 const currentLocale = locale ?? defaultLocale;
28
29 // Rimuovi il prefisso della lingua dal percorso per costruire un percorso base
30 const pathWithoutLocale = getPathWithoutLocale(
31 path // Percorso URL corrente
32 );
33
34 /**
35 * Se middleware.prefixDefault è vero, la lingua predefinita dovrebbe sempre essere prefissata.
36 */
37 if (middleware.prefixDefault) {
38 // Valida la lingua
39 if (!locale || !locales.includes(locale)) {
40 // Reindirizza alla lingua predefinita con il percorso aggiornato
41 return (
42 <Navigate
43 to={`/${defaultLocale}/${pathWithoutLocale}`}
44 replace // Sostituisci l'attuale voce della storia con la nuova
45 />
46 );
47 }
48
49 // Avvolgi i figli con IntlayerProvider e imposta la lingua corrente
50 return (
51 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
52 );
53 } else {
54 /**
55 * Quando middleware.prefixDefault è falso, la lingua predefinita non è prefissata.
56 * Assicurati che la lingua corrente sia valida e non sia la lingua predefinita.
57 */
58 if (
59 currentLocale.toString() !== defaultLocale.toString() &&
60 !locales
61 .filter(
62 (locale) => locale.toString() !== defaultLocale.toString() // Escludi la lingua predefinita
63 )
64 .includes(currentLocale) // Controlla se la lingua corrente è nella lista delle lingue valide
65 ) {
66 // Reindirizza al percorso senza prefisso della lingua
67 return <Navigate to={pathWithoutLocale} replace />;
68 }
69
70 // Avvolgi i figli con IntlayerProvider e imposta la lingua corrente
71 return (
72 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
73 );
74 }
75};
76
77/**
78 * Un componente router che imposta percorsi specifici per la lingua.
79 * Usa React Router per gestire la navigazione e rendere componenti localizzati.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82 <BrowserRouter>
83 <Routes>
84 <Route
85 // Modello di percorso per catturare la lingua (es., /it/, /fr/) e corrispondere a tutti i percorsi successivi
86 path="/:locale/*"
87 element={<AppLocalized>{children}</AppLocalized>} // Avvolge i figli con la gestione della lingua
88 />
89
90 {
91 // Se il prefisso della lingua predefinita è disabilitato, renderizza i figli direttamente nel percorso principale
92 !middleware.prefixDefault && (
93 <Route
94 path="*"
95 element={<AppLocalized>{children}</AppLocalized>} // Avvolge i figli con la gestione della lingua
96 />
97 )
98 }
99 </Routes>
100 </BrowserRouter>
101);In parallelo, puoi anche usare il intLayerMiddlewarePlugin per aggiungere il routing sul server alla tua applicazione. Questo plugin rileverà automaticamente la lingua corrente in base all'URL e imposterà il cookie della lingua appropriata. Se nessuna lingua è specificata, il plugin determinerà la lingua più appropriata in base alle preferenze linguistiche del browser dell'utente. Se non viene rilevata alcuna lingua, verrà reindirizzato alla lingua predefinita.
1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react-swc";
3import { intLayerPlugin, intLayerMiddlewarePlugin } from "react-intlayer/vite";
4
5// https://vitejs.dev/config/
6export default defineConfig({
7 plugins: [react(), intLayerPlugin(), intLayerMiddlewarePlugin()],
8});(Optional) Step 8: Change the URL when the locale changes
Per cambiare l'URL quando cambia la lingua, puoi usare la prop onLocaleChange fornita dal hook useLocale. In parallelo, puoi usare i hook 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 corrente. Esempio: /it/about
7 const navigate = useNavigate();
8
9 const changeUrl = (locale: Locales) => {
10 // Costruisci l'URL con la lingua aggiornata
11 // Esempio: /fr/about con la lingua impostata su francese
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.ITALIAN)}>
24 Cambia lingua in Italiano
25 </button>
26 );
27};Configure TypeScript
Intlayer utilizza l'augmentation del modulo per ottenere i benefici di TypeScript e rendere il tuo codice più robusto.
Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.
1// tsconfig.json
2
3{
4 // la tua configurazione personalizzata
5 include: [
6 "src",
7 "types", // <- Includi i tipi auto generati
8 ],
9}Git Configuration
Si consiglia di ignorare i file generati da Intlayer. Questo ti permette di evitare di commetterli nel tuo repository Git.
Per fare ciò, 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