@intlayer/docs 5.8.1 → 6.0.0-canary.1

package/docs/it/intlayer_with_react_router_v7.md

@@ -0,0 +1,535 @@
+---
+createdAt: 2025-09-04
+updatedAt: 2025-09-04
+title: Iniziare con Intlayer in React Router v7
+description: Scopri come aggiungere l'internazionalizzazione (i18n) alla tua applicazione React Router v7 utilizzando Intlayer. Segui questa guida completa per rendere la tua app multilingue con il routing consapevole della localizzazione.
+keywords:
+  - Internazionalizzazione
+  - Documentazione
+  - Intlayer
+  - React Router v7
+  - React
+  - i18n
+  - TypeScript
+  - Routing Locale
+slugs:
+  - doc
+  - environment
+  - vite-and-react
+  - react-router-v7
+applicationTemplate: https://github.com/AydinTheFirst/react-router-intlayer
+author: AydinTheFirst
+---
+
+# Iniziare con l'internazionalizzazione (i18n) usando Intlayer e React Router v7
+
+Questa guida dimostra come integrare **Intlayer** per un'internazionalizzazione senza soluzione di continuità nei progetti React Router v7 con routing consapevole della localizzazione, supporto TypeScript e pratiche di sviluppo moderne.
+
+## 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**, rotte e contenuti.
+- **Garantire il supporto TypeScript** con tipi generati automaticamente, migliorando l'autocompletamento e il rilevamento degli errori.
+- **Beneficiare di funzionalità avanzate**, come il rilevamento e il cambio dinamico della localizzazione.
+- **Abilitare il routing consapevole della localizzazione** con il sistema di routing basato su configurazione di React Router v7.
+
+---
+
+## Guida passo-passo per configurare Intlayer in un'applicazione React Router v7
+
+### Passo 1: Installare le dipendenze
+
+Installa i pacchetti necessari utilizzando il tuo gestore di pacchetti preferito:
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer
+npm install vite-intlayer --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer
+pnpm add vite-intlayer --save-dev
+```
+
+- **intlayer**
+
+- **intlayer**
+
+  Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione della configurazione, la traduzione, la [dichiarazione dei contenuti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/get_started.md), la traspilazione e i [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.
+
+- **vite-intlayer**
+  Include il plugin Vite per integrare Intlayer con il [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), oltre a middleware per rilevare la localizzazione preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.
+
+### Passo 2: Configurazione del tuo progetto
+
+Crea un file di configurazione per configurare le lingue della tua applicazione:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [Locales.ENGLISH, Locales.TURKISH],
+  },
+  middleware: {
+    prefixDefault: true, // Prefissa sempre la lingua predefinita negli URL
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [Locales.ENGLISH, Locales.TURKISH],
+  },
+  middleware: {
+    prefixDefault: true,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+// Configurazione per Intlayer
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH, // Lingua predefinita
+    locales: [Locales.ENGLISH, Locales.TURKISH], // Lingue supportate
+  },
+  middleware: {
+    prefixDefault: true, // Prefissa sempre la lingua predefinita negli URL
+  },
+};
+
+module.exports = 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).
+
+### Passo 3: Configurare le Rotte di React Router v7
+
+Configura la tua configurazione di routing con rotte consapevoli della localizzazione:
+
+```typescript fileName="app/routes.ts" codeFormat="typescript"
+import { layout, route, type RouteConfig } from "@react-router/dev/routes";
+
+export default [
+  layout("routes/layout.tsx", [
+    route("/", "routes/page.tsx"), // Pagina radice - reindirizza alla localizzazione
+    route("/:lang", "routes/[lang]/page.tsx"), // Pagina iniziale localizzata
+    route("/:lang/about", "routes/[lang]/about/page.tsx"), // Pagina "about" localizzata
+  ]),
+] satisfies RouteConfig;
+```
+
+### Passo 4: Integrare Intlayer nella Configurazione di Vite
+
+Aggiungi il plugin intlayer nella tua configurazione:
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    tsconfigPaths(),
+    intlayerPlugin(),
+    intlayerMiddlewarePlugin(),
+  ],
+});
+```
+
+> 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 5: Creare i Componenti Layout
+
+Configura il layout principale e i layout specifici per la localizzazione:
+
+#### Layout Principale
+
+```tsx fileName="app/routes/layout.tsx" codeFormat="typescript"
+tsx fileName="app/routes/layout.tsx" codeFormat="typescript"
+// app/routes/layout.tsx
+import { Outlet } from "react-router";
+import { IntlayerProvider } from "react-intlayer";
+
+export default function RootLayout() {
+  return (
+    <IntlayerProvider>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
+
+### Passo 6: Dichiara il Tuo Contenuto
+
+Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:
+
+```tsx fileName="app/routes/[lang]/page.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const pageContent = {
+  key: "page",
+  content: {
+    title: t({
+      en: "Welcome to React Router v7 + Intlayer",
+      tr: "React Router v7 + Intlayer'a Hoş Geldiniz",
+    }),
+    description: t({
+      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
+      tr: "React Router v7 e Intlayer per creare facilmente applicazioni multilingue.",
+    }),
+    aboutLink: t({
+      en: "Scopri di noi",
+      tr: "Hakkımızda Öğrenin",
+    }),
+    homeLink: t({
+      en: "Home",
+      tr: "Ana Sayfa",
+    }),
+  },
+} satisfies Dictionary;
+
+export default pageContent;
+```
+
+> Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena sono incluse nella directory `contentDir` (di default, `./app`). 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 sulla dichiarazione del contenuto](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/get_started.md).
+
+### Passo 7: Crea Componenti Consapevoli della Locale
+
+Crea un componente `LocalizedLink` per una navigazione consapevole della localizzazione:
+
+```tsx fileName="app/components/localized-link.tsx" codeFormat="typescript"
+// app/components/localized-link.tsx
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
+import React from "react";
+import { Link, useLocation } from "react-router";
+
+type RouterLinkProps = React.ComponentProps<typeof Link>;
+
+export default function LocalizedLink({ to, ...props }: RouterLinkProps) {
+  const { locale } = useLocale();
+  const location = useLocation();
+
+  const isExternal = (path: string) =>
+    /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:");
+
+  if (typeof to === "string") {
+    if (to.startsWith("/") && !isExternal(to)) {
+      return <Link to={getLocalizedUrl(to, locale)} {...props} />;
+    }
+    return <Link to={to} {...props} />;
+  }
+
+  if (to && typeof to === "object") {
+    const pathname = (to as { pathname?: string }).pathname;
+    if (pathname && pathname.startsWith("/") && !isExternal(pathname)) {
+      return (
+        <Link
+          to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }}
+          {...props}
+        />
+      );
+    }
+    return <Link to={to} {...props} />;
+  }
+
+  return (
+    <Link
+      to={getLocalizedUrl(location.pathname + location.search, locale)}
+      {...props}
+    />
+  );
+}
+```
+
+### Passo 8: Utilizza Intlayer nelle Tue Pagine
+
+Accedi ai tuoi dizionari di contenuti in tutta l'applicazione:
+
+#### Pagina di Reindirizzamento Root
+
+```tsx fileName="app/routes/page.tsx" codeFormat="typescript"
+// app/routes/page.tsx
+import { useLocale } from "react-intlayer";
+import { Navigate } from "react-router";
+
+export default function Page() {
+  const { locale } = useLocale();
+
+  return <Navigate replace to={locale} />;
+}
+```
+
+#### Pagina Home Localizzata
+
+```tsx fileName="app/routes/[lang]/page.tsx" codeFormat="typescript"
+import { useIntlayer } from "react-intlayer";
+import LocalizedLink from "~/components/localized-link";
+
+export default function Page() {
+  const content = useIntlayer("page");
+
+  return (
+    <div style={{ padding: "2rem", textAlign: "center" }}>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+      <nav style={{ marginTop: "2rem" }}>
+        <LocalizedLink
+          to="/about"
+          style={{
+            display: "inline-block",
+            padding: "0.5rem 1rem",
+            backgroundColor: "#007bff",
+            color: "white",
+            textDecoration: "none",
+            borderRadius: "4px",
+          }}
+        >
+          {content.aboutLink}
+        </LocalizedLink>
+      </nav>
+    </div>
+  );
+}
+```
+
+> 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).
+
+### Passo 9: Crea un componente per il selettore di lingua
+
+Crea un componente per permettere agli utenti di cambiare lingua:
+
+```tsx fileName="app/components/locale-switcher.tsx" codeFormat="typescript"
+import { getLocalizedUrl, getLocaleName } from "intlayer";
+import { useLocale } from "react-intlayer";
+import { useLocation, useNavigate } from "react-router";
+
+export default function LocaleSwitcher() {
+  const { locale, availableLocales, setLocale } = useLocale();
+  const location = useLocation();
+  const navigate = useNavigate();
+
+  const handleLocaleChange = (newLocale: string) => {
+    const localizedUrl = getLocalizedUrl(
+      location.pathname + location.search,
+      newLocale
+    );
+    setLocale(newLocale);
+    navigate(localizedUrl);
+  };
+
+  return (
+    <div style={{ margin: "1rem 0" }}>
+      <label htmlFor="locale-select">Scegli la lingua: </label>
+      <select
+        id="locale-select"
+        value={locale}
+        onChange={(e) => handleLocaleChange(e.target.value)}
+        style={{ padding: "0.25rem", marginLeft: "0.5rem" }}
+      >
+        {availableLocales.map((availableLocale) => (
+          <option key={availableLocale} value={availableLocale}>
+            {getLocaleName(availableLocale)}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}
+```
+
+> 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).
+
+### Passo 10: Aggiungere la Gestione degli Attributi HTML (Opzionale)
+
+Crea un hook per gestire gli attributi lang e dir dell'HTML:
+
+```tsx fileName="app/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+// app/hooks/useI18nHTMLAttributes.tsx
+import { getHTMLTextDir } from "intlayer";
+import { useEffect } from "react";
+import { useLocale } from "react-intlayer";
+
+export const useI18nHTMLAttributes = () => {
+  const { locale } = useLocale();
+
+  useEffect(() => {
+    document.documentElement.lang = locale;
+    document.documentElement.dir = getHTMLTextDir(locale);
+  }, [locale]);
+};
+```
+
+Quindi usalo nel tuo componente root:
+
+```tsx fileName="app/root.tsx" codeFormat="typescript"
+// app/routes/layout.tsx
+import { Outlet } from "react-router";
+import { IntlayerProvider } from "react-intlayer";
+
+import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // importa il hook
+
+export default function RootLayout() {
+  useI18nHTMLAttributes(); // chiama il hook
+
+  return (
+    <IntlayerProvider>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
+
+### Passo 11: Compila ed Esegui la Tua Applicazione
+
+Costruisci i dizionari di contenuto e avvia la tua applicazione:
+
+```bash packageManager="npm"
+# Costruisci i dizionari di Intlayer
+npm run intlayer:build
+
+# Avvia il server di sviluppo
+npm run dev
+```
+
+```bash packageManager="pnpm"
+# Costruisci i dizionari di Intlayer
+pnpm intlayer:build
+
+# Avvia il server di sviluppo
+pnpm dev
+```
+
+```bash packageManager="yarn"
+# Costruisci i dizionari di Intlayer
+yarn intlayer:build
+
+# Avvia il server di sviluppo
+yarn dev
+```
+
+### Passo 12: Configura TypeScript (Opzionale)
+
+Intlayer utilizza l'augmentazione 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:
+
+```json5 fileName="tsconfig.json"
+{
+  compilerOptions: {
+    // ... le tue configurazioni TypeScript esistenti
+  },
+  include: [
+    // ... i tuoi include 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
+```
+
+---
+
+## Distribuzione in Produzione
+
+Quando distribuisci la tua applicazione:
+
+1. **Compila la tua applicazione:**
+
+   ```bash
+   npm run build
+   ```
+
+2. **Compila i dizionari di Intlayer:**
+
+   ```bash
+   npm run intlayer:build
+   ```
+
+3. **Sposta `vite-intlayer` nelle dipendenze** se usi il middleware in produzione:
+   ```bash
+   npm install vite-intlayer --save
+   ```
+
+La tua applicazione supporterà ora:
+
+- **Struttura URL**: `/en`, `/en/about`, `/tr`, `/tr/about`
+- **Rilevamento automatico della lingua** basato sulle preferenze del browser
+- **Routing consapevole della lingua** con React Router v7
+- **Supporto TypeScript** con tipi generati automaticamente
+- **Rendering lato server** con gestione corretta della lingua
+
+## Estensione VS Code
+
+Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare la **Estensione ufficiale Intlayer per VS Code**.
+
+[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 in tempo reale degli errori** per traduzioni mancanti.
+- **Anteprime inline** dei contenuti tradotti.
+- **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).
+
+---
+
+## Riferimenti alla documentazione
+
+- [Documentazione Intlayer](https://intlayer.org)
+- [Documentazione React Router v7](https://reactrouter.com/)
+- [Hook useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useIntlayer.md)
+- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/react-intlayer/useLocale.md)
+- [Dichiarazione del Contenuto](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/get_started.md)
+- [Configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+
+Questa guida completa fornisce tutto il necessario per integrare Intlayer con React Router v7 per un'applicazione completamente internazionalizzata con routing consapevole della localizzazione e supporto TypeScript.
+
+## Cronologia della Documentazione
+
+| Versione | Data      | Modifiche                    |
+| -------- | --------- | ---------------------------- |
+| 5.8.2    | 2025-09-4 | Aggiunto per React Router v7 |