@intlayer/docs 5.5.9 → 5.5.11

package/docs/it/intlayer_with_create_react_app.md

@@ -0,0 +1,1156 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: Traduci il tuo sito web Create React App (CRA) (i18n)
+description: Scopri come rendere il tuo sito Create React App (CRA) multilingue. Segui la documentazione per internazionalizzare (i18n) e tradurlo.
+keywords:
+  - Internazionalizzazione
+  - Documentazione
+  - Intlayer
+  - Create React App
+  - CRA
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - environment
+  - create-react-app
+---
+
+# Introduzione all'Internazionalizzazione (i18n) con Intlayer e React Create App
+
+Consulta [Application Template](https://github.com/aymericzip/intlayer-react-cra-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:
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer react-scripts-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer react-scripts-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer react-intlayer react-scripts-intlayer
+```
+
+- **intlayer**
+
+  Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione delle configurazioni, traduzioni, [dichiarazione dei contenuti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/get_started.md), transpilation e [comandi CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_cli.md).
+
+- **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](https://craco.js.org/) e includono configurazioni aggiuntive per il bundler [Webpack](https://webpack.js.org/).
+
+### Passo 2: Configurazione del progetto
+
+Crea un file di configurazione per configurare le lingue della tua applicazione:
+
+```typescript fileName="intlayer.config.ts"  codeFormat="typescript"
+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;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Le tue altre lingue
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Le tue altre lingue
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).
+
+### Passo 3: Integra Intlayer nella configurazione CRA
+
+Modifica i tuoi script per utilizzare react-intlayer
+
+```json fileName="package.json"
+  "scripts": {
+    "build": "react-scripts-intlayer build",
+    "start": "react-scripts-intlayer start",
+    "transpile": "intlayer build"
+  },
+```
+
+> Gli script `react-scripts-intlayer` sono basati su [CRACO](https://craco.js.org/). Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. [Vedi esempio qui](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+
+### 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](https://craco.js.org/). Puoi anche implementare la tua configurazione basata sul plugin craco di Intlayer. [Vedi esempio qui](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+
+### Passo 4: Dichiarare i tuoi contenuti
+
+Crea e gestisci le dichiarazioni dei tuoi contenuti per memorizzare le traduzioni:
+
+```tsx fileName="src/app.content.tsx" codeFormat="typescript"
+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;
+```
+
+```jsx fileName="src/app.content.mjx" codeFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    getStarted: t({
+      en: "Get started by editing",
+      fr: "Commencez par éditer",
+      es: "Comience por editar",
+    }),
+    reactLink: {
+      href: "https://reactjs.org",
+      content: t({
+        en: "Learn React",
+        fr: "Apprendre React",
+        es: "Aprender React",
+      }),
+    },
+  },
+};
+
+export default appContent;
+```
+
+```jsx fileName="src/app.content.csx" codeFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    getStarted: t({
+      en: "Get started by editing",
+      fr: "Commencez par éditer",
+      es: "Comience por editar",
+    }),
+    reactLink: {
+      href: "https://reactjs.org",
+      content: t({
+        en: "Learn React",
+        fr: "Apprendre React",
+        es: "Aprender React",
+      }),
+    },
+  },
+};
+
+module.exports = appContent;
+```
+
+```jsx fileName="src/app.content.csx" codeFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    getStarted: t({
+      en: "Get started by editing",
+      fr: "Commencez par éditer",
+      es: "Comience por editar",
+      it: "Inizia modificando",
+    }),
+    reactLink: {
+      href: "https://reactjs.org",
+      content: t({
+        en: "Learn React",
+        fr: "Apprendre React",
+        es: "Aprender React",
+        it: "Impara React",
+      }),
+    },
+  },
+};
+
+module.exports = 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/get_started.md).
+
+> 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:
+
+```tsx {4,7} fileName="src/App.tsx"  codeFormat="typescript"
+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;
+```
+
+```jsx {3,6} fileName="src/App.mjx" codeFormat="esm"
+import "./App.css";
+import logo from "./logo.svg";
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+
+const AppContent = () => {
+  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 = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+```
+
+```jsx {3,6} fileName="src/App.csx" codeFormat="commonjs"
+require("./App.css");
+const logo = require("./logo.svg");
+const { IntlayerProvider, useIntlayer } = require("react-intlayer");
+
+const AppContent = () => {
+  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 = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+```
+
+> 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:
+
+> ```jsx
+> <img src={content.image.src.value} alt={content.image.value} />
+> ```
+>
+> Per saperne di più sull'hook `useIntlayer`, consulta la [documentazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useIntlayer.md).
+
+### (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.
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import { Locales } from "intlayer";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { setLocale } = useLocale();
+
+  return (
+    <button onClick={() => setLocale(Locales.English)}>
+      Cambia lingua in Inglese
+    </button>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  const { setLocale } = useLocale();
+
+  return (
+    <button onClick={() => setLocale(Locales.English)}>
+      Cambia lingua in Inglese
+    </button>
+  );
+};
+```
+
+> Per saperne di più sull'hook `useLocale`, consulta la [documentazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useLocale.md).
+
+### (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:
+
+```plaintext
+- 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md) 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](https://reactrouter.com/home):
+
+```tsx fileName="src/components/LocaleRouter.tsx"  codeFormat="typescript"
+// Importing necessary dependencies and functions
+import { 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 props
+import { IntlayerProvider } from "react-intlayer"; // Provider per il contesto di internazionalizzazione
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} from "react-router-dom"; // Componenti router per la gestione della navigazione
+
+// Destrutturazione della configurazione da Intlayer
+const { 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>
+);
+```
+
+```jsx fileName="src/components/LocaleRouter.mjx" codeFormat="esm"
+// Importazione delle dipendenze e funzioni necessarie
+import { configuration, getPathWithoutLocale } from "intlayer"; // Funzioni e tipi di utilità da 'intlayer'
+// Funzioni e tipi di utilità da 'intlayer'
+import { IntlayerProvider } from "react-intlayer"; // Provider per il contesto di internazionalizzazione
+import {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} from "react-router-dom"; // Componenti router per la gestione della navigazione
+
+// Destrutturazione della configurazione da Intlayer
+const { internationalization, middleware } = configuration;
+const { locales, defaultLocale } = internationalization;
+
+/**
+ * Un componente che gestisce la localizzazione e avvolge i figli con il contesto della locale appropriata.
+ * Gestisce il rilevamento e la validazione della localizzazione basata sull'URL.
+ */
+const AppLocalized = ({ children, locale }) => {
+  const { pathname, search } = useLocation(); // Ottiene il percorso URL corrente
+
+  // Determina la localizzazione corrente, utilizzando 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 sempre essere 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 della 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 quella 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 imposta rotte specifiche per la locale.
+ * Usa React Router per gestire la navigazione e rendere componenti localizzati.
+ */
+export const LocaleRouter = ({ children }) => (
+  <BrowserRouter>
+    <Routes>
+      {locales
+        .filter(
+          (locale) => middleware.prefixDefault || locale !== defaultLocale
+        )
+        .map((locale) => (
+          <Route
+            // Pattern di route per catturare la locale (es. /en/, /fr/) e abbinare tutti i percorsi successivi
+            path={`/${locale}/*`}
+            key={locale}
+            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Avvolge i children con la gestione della locale
+          />
+        ))}
+
+      {
+        // Se il prefisso per la locale di default è disabilitato, renderizza i children direttamente al percorso root
+        !middleware.prefixDefault && (
+          <Route
+            path="*"
+            element={
+              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
+            } // Avvolge i children con la gestione della locale
+          />
+        )
+      }
+    </Routes>
+  </BrowserRouter>
+);
+```
+
+Then, you can use the `LocaleRouter` component in your application:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import { LocaleRouter } from "./components/LocaleRouter";
+import type { FC } from "react";
+
+// ... Il tuo componente AppContent
+
+const App: FC = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+```jsx fileName="src/App.mjx" codeFormat="esm"
+import { LocaleRouter } from "./components/LocaleRouter";
+
+// ... Il tuo componente AppContent
+
+const App = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+```jsx fileName="src/App.cjx" codeFormat="commonjs"
+const { LocaleRouter } = require("./components/LocaleRouter");
+
+// ... Il tuo componente AppContent
+
+const App = () => (
+  <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.
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.msx" codeFormat="esm"
+import { useLocation, useNavigate } from "react-router-dom";
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  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>
+              {/* 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 localizzazione corrente - es. Francés con la localizzazione 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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocation, useNavigate } = require("react-router-dom");
+const {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} = require("intlayer");
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  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>
+              {/* 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>
+          </a>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+> Riferimenti alla documentazione:
+>
+> - [`useLocale` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useLocale.md)
+> - [`getLocaleName` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getLocaleName.md)
+> - [`getLocalizedUrl` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getLocalizedUrl.md)
+> - [`getHTMLTextDir` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/intlayer/getHTMLTextDir.md)
+> - [`hrefLang` attribute](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=fr)
+> - [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
+> - [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
+> - [`aria-current` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
+
+### (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:
+
+```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+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]);
+};
+```
+
+```jsx fileName="src/hooks/useI18nHTMLAttributes.msx" codeFormat="esm"
+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 locale corrente.
+ * - `lang`: Informa browser e motori di ricerca della 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]);
+};
+```
+
+```jsx fileName="src/hooks/useI18nHTMLAttributes.csx" codeFormat="commonjs"
+const { useEffect } = require("react");
+const { useLocale } = require("react-intlayer");
+const { getHTMLTextDir } = require("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 (ad esempio, 'ltr' per l'inglese, 'rtl' per l'arabo).
+ *
+ * Questo aggiornamento dinamico è essenziale per una corretta resa del testo, accessibilità e SEO.
+ */
+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]);
+};
+
+module.exports = { useI18nHTMLAttributes };
+```
+
+#### 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:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+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;
+```
+
+```jsx fileName="src/App.msx" codeFormat="esm"
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
+import "./App.css";
+
+const AppContent = () => {
+  // Applica l'hook per aggiornare gli attributi lang e dir del tag <html> in base alla locale.
+  useI18nHTMLAttributes();
+
+  // ... Resto del componente
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+export default App;
+```
+
+```jsx fileName="src/App.csx" codeFormat="commonjs"
+const { FC } = require("react");
+const { IntlayerProvider, useIntlayer } = require("react-intlayer");
+const { useI18nHTMLAttributes } = require("./hooks/useI18nHTMLAttributes");
+require("./App.css");
+
+const AppContent = () => {
+  // Applica l'hook per aggiornare gli attributi lang e dir del tag <html> in base alla locale.
+  useI18nHTMLAttributes();
+
+  // ... Resto del componente
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+module.exports = 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.
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png)
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png)
+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`:
+
+```plaintext fileName=".gitignore"
+# 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](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+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](https://intlayer.org/doc/vs-code-extension).
+
+### Vai oltre
+
+Per andare oltre, puoi implementare l'[editor visuale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md) o esternalizzare i tuoi contenuti utilizzando il [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md).
+[Installa dal Marketplace di VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+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](https://intlayer.org/doc/vs-code-extension).
+
+### Approfondimenti
+
+Per approfondire, puoi implementare l’[editor visuale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md) o esternalizzare i tuoi contenuti usando il [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md).
+
+## Cronologia della documentazione
+
+- 5.5.10 - 2025-06-29: Cronologia iniziale