@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

package/blog/it/intlayer_with_next-intl.md

@@ -29,6 +29,10 @@ author: aymericzip
 
 <iframe title="Come automatizzare le traduzioni JSON di next-intl usando Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+# Indice dei contenuti
+
+<TOC/>
+
 ## Cos'è Intlayer?
 
 **Intlayer** è una libreria di internazionalizzazione innovativa e open-source progettata per superare le limitazioni delle soluzioni i18n tradizionali. Offre un approccio moderno alla gestione dei contenuti nelle applicazioni Next.js.
@@ -53,28 +57,46 @@ Questa guida ti mostra come sfruttare il sistema superiore di dichiarazione dei
 
 ## Guida passo-passo per configurare Intlayer con next-intl
 
-### Passo 1: Installa le dipendenze
+<Steps>
+
+<Step number={1} title="Installa le dipendenze">
 
 Installa i pacchetti necessari:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
+
+> Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descrizione dei pacchetti:**
@@ -82,7 +104,9 @@ bun x intlayer init
 - **intlayer**: Libreria core per la gestione dell'internazionalizzazione, dichiarazione dei contenuti e build
 - **@intlayer/sync-json-plugin**: Plugin per esportare le dichiarazioni di contenuto di Intlayer in formato JSON compatibile con next-intl
 
-### Passo 2: Implementa il plugin Intlayer per avvolgere il JSON
+</Step>
+
+<Step number={2} title="Implementa il plugin Intlayer per avvolgere il JSON">
 
 Crea un file di configurazione Intlayer per definire le tue localizzazioni supportate:
 
@@ -119,7 +143,9 @@ Se vengono effettuate modifiche utilizzando la CLI per tradurre il JSON, o utili
 
 Per maggiori dettagli sul plugin `syncJSON`, si prega di consultare la [documentazione del plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md).
 
-### (Opzionale) Passo 3: Implementare traduzioni JSON per componente
+</Step>
+
+<Step number={3} title="Implementare traduzioni JSON per componente" isOptional={true}>
 
 Per impostazione predefinita, Intlayer caricherà, fonderà e sincronizzerà sia i file JSON che i file di dichiarazione del contenuto. Consulta [la documentazione sulla dichiarazione del contenuto](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md) per maggiori dettagli. Ma se preferisci, utilizzando un plugin di Intlayer, puoi anche implementare la gestione per componente dei JSON localizzati ovunque nel tuo codice.
 
@@ -161,6 +187,10 @@ export default config;
 
 Questo caricherà tutti i file JSON nella directory `src` che corrispondono al pattern `{key}.i18n.json` e li caricherà come dizionari Intlayer.
 
+</Step>
+
+</Steps>
+
 ## Configurazione Git
 
 Si consiglia di ignorare i file Intlayer generati automaticamente:

package/blog/it/intlayer_with_react-i18next.md

@@ -57,28 +57,46 @@ Questa guida ti mostra come sfruttare il sistema superiore di dichiarazione dei
 
 ## Guida passo-passo per configurare Intlayer con react-i18next
 
-### Passo 1: Installa le dipendenze
+<Steps>
+
+<Step number={1} title="Installa le dipendenze">
 
 Installa i pacchetti necessari:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
+
+> Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descrizione dei pacchetti:**
@@ -86,7 +104,9 @@ bun x intlayer init
 - **intlayer**: Libreria core per la gestione dell'internazionalizzazione, dichiarazione dei contenuti e build
 - **@intlayer/sync-json-plugin**: Plugin per esportare le dichiarazioni di contenuto di Intlayer in un formato JSON compatibile con react-i18next
 
-### Passo 2: Implementa il plugin Intlayer per avvolgere il JSON
+</Step>
+
+<Step number={2} title="Implementa il plugin Intlayer per avvolgere il JSON">
 
 Crea un file di configurazione Intlayer per definire le tue localizzazioni supportate:
 
@@ -122,7 +142,9 @@ Se vengono apportate modifiche utilizzando la CLI per tradurre il JSON, o utiliz
 
 Per maggiori dettagli sul plugin `syncJSON`, si prega di fare riferimento alla [documentazione del plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md).
 
-### (Opzionale) Passo 3: Implementare traduzioni JSON per componente
+</Step>
+
+<Step number={3} title="Implementare traduzioni JSON per componente" isOptional={true}>
 
 Per impostazione predefinita, Intlayer caricherà, unirà e sincronizzerà sia i file JSON che i file di dichiarazione del contenuto. Vedi [la documentazione sulla dichiarazione del contenuto](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md) per maggiori dettagli. Ma se preferisci, usando un plugin Intlayer, puoi anche implementare la gestione per componente di JSON localizzati ovunque nel tuo codice.
 
@@ -163,6 +185,10 @@ export default config;
 
 Questo caricherà tutti i file JSON nella directory `src` che corrispondono al modello `{key}.i18n.json` e li caricherà come dizionari Intlayer.
 
+</Step>
+
+</Steps>
+
 ## Configurazione Git
 
 Si consiglia di ignorare i file generati automaticamente da Intlayer:

package/blog/it/intlayer_with_react-intl.md

@@ -55,28 +55,46 @@ Questa guida ti mostra come sfruttare il sistema superiore di dichiarazione dei
 
 ## Guida passo-passo per configurare Intlayer con react-intl
 
-### Passo 1: Installa le dipendenze
+<Steps>
+
+<Step number={1} title="Installa le dipendenze">
 
 Installa i pacchetti necessari:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
+
+> Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descrizione dei pacchetti:**
@@ -84,7 +102,9 @@ bun x intlayer init
 - **intlayer**: Libreria core per la gestione dell'internazionalizzazione, la dichiarazione dei contenuti e la compilazione
 - **@intlayer/sync-json-plugin**: Plugin per esportare le dichiarazioni di contenuto di Intlayer in un formato JSON compatibile con react-intl
 
-### Passo 2: Implementa il plugin Intlayer per incapsulare il JSON
+</Step>
+
+<Step number={2} title="Implementa il plugin Intlayer per incapsulare il JSON">
 
 Crea un file di configurazione Intlayer per definire le tue localizzazioni supportate:
 
@@ -121,7 +141,9 @@ Se vengono effettuate modifiche usando la CLI per tradurre il JSON, o utilizzand
 
 Per maggiori dettagli sul plugin `syncJSON`, si prega di fare riferimento alla [documentazione del plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md).
 
-### (Opzionale) Passo 3: Implementare traduzioni JSON per componente
+</Step>
+
+<Step number={3} title="Implementare traduzioni JSON per componente" isOptional={true}>
 
 Per impostazione predefinita, Intlayer caricherà, unirà e sincronizzerà sia i file JSON che i file di dichiarazione del contenuto. Vedi [la documentazione sulla dichiarazione del contenuto](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md) per maggiori dettagli. Ma se preferisci, utilizzando un plugin Intlayer, puoi anche implementare la gestione per componente di JSON localizzati ovunque nel tuo codice.
 
@@ -163,6 +185,10 @@ export default config;
 
 Questo caricherà tutti i file JSON nella directory `src` che corrispondono al modello `{key}.i18n.json` e li caricherà come dizionari Intlayer.
 
+</Step>
+
+</Steps>
+
 ## Configurazione Git
 
 Si consiglia di ignorare i file generati automaticamente da Intlayer:

package/blog/it/intlayer_with_vue-i18n.md

@@ -57,28 +57,46 @@ Questa guida ti mostra come sfruttare il sistema superiore di dichiarazione dei
 
 ## Guida passo-passo per configurare Intlayer con vue-i18n
 
-### Passo 1: Installa le dipendenze
+<Steps>
+
+<Step number={1} title="Installa le dipendenze">
 
 Installa i pacchetti necessari utilizzando il tuo gestore di pacchetti preferito:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
+
+> Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Spiegazioni dei pacchetti:**
@@ -86,7 +104,9 @@ bun x intlayer init
 - **intlayer**: Libreria core per la dichiarazione e gestione dei contenuti
 - **@intlayer/sync-json-plugin**: Plugin per sincronizzare le dichiarazioni di contenuto di Intlayer nel formato JSON di vue-i18n
 
-### Passo 2: Implementa il plugin Intlayer per incapsulare il JSON
+</Step>
+
+<Step number={2} title="Implementa il plugin Intlayer per incapsulare il JSON">
 
 Crea un file di configurazione Intlayer per definire le tue localizzazioni supportate:
 
@@ -125,7 +145,9 @@ Per maggiori dettagli sul plugin `syncJSON`, si prega di fare riferimento alla [
 
 ---
 
-### (Opzionale) Passo 3: Implementare traduzioni JSON per componente
+</Step>
+
+<Step number={3} title="Implementare traduzioni JSON per componente" isOptional={true}>
 
 Per impostazione predefinita, Intlayer caricherà, unirà e sincronizzerà sia i file JSON che i file di dichiarazione del contenuto. Vedi [la documentazione sulla dichiarazione del contenuto](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md) per maggiori dettagli. Ma se preferisci, utilizzando un plugin Intlayer, puoi anche implementare la gestione per componente del JSON localizzato ovunque nel tuo codice.
 
@@ -169,6 +191,10 @@ Questo caricherà tutti i file JSON nella directory `src` che corrispondono al m
 
 ---
 
+</Step>
+
+</Steps>
+
 ## Configurazione Git
 
 Escludi i file generati dal controllo di versione:

package/blog/it/next-i18next_vs_next-intl_vs_intlayer.md

@@ -61,14 +61,6 @@ Ci concentriamo su **Next.js 13+ App Router** (con **React Server Components**)
 
 ---
 
-## Confronto delle funzionalità affiancate (focalizzato su Next.js)
-
-| Funzionalità | `next-intlayer` (Intlayer) | `next-intl` | `next-i18next` |
-
-> I badge si aggiornano automaticamente. Gli snapshot varieranno nel tempo.
-
----
-
 ## Confronto delle Funzionalità Affiancate (focalizzato su Next.js)
 
 | Funzionalità                                            | `next-intlayer` (Intlayer)                                                                                                                     | `next-intl`                                                                                                                      | `next-i18next`                                                                                                                   |
@@ -288,34 +280,6 @@ Ecco un esempio dell'impatto dell'ottimizzazione della dimensione del bundle uti
 
 ---
 
-## DX, strumenti e manutenzione
-
-<Columns>
-  <Column>
-
-**next-intl**
-
-- Comunemente abbinato a piattaforme di localizzazione esterne e flussi editoriali.
-
-  </Column>
-  <Column>
-
-**next-i18next**
-
-- Comunemente abbinato a piattaforme di localizzazione esterne e flussi editoriali.
-
-  </Column>
-  <Column>
-
-**intlayer**
-
-- Fornisce un **Editor Visivo gratuito** e un **CMS opzionale** (compatibile con Git o esternalizzato), oltre a un’**estensione VSCode** e **traduzioni assistite da AI** utilizzando le tue chiavi provider.
-
-  </Column>
-</Columns>
-
-**Perché è importante:** Riduce i costi operativi e accorcia il ciclo tra sviluppatori e autori dei contenuti.
-
 ## Integrazione con piattaforme di localizzazione (TMS)
 
 Le grandi organizzazioni spesso si affidano a Sistemi di Gestione delle Traduzioni (TMS) come **Crowdin**, **Phrase**, **Lokalise**, **Localizely** o **Localazy**.
@@ -1182,6 +1146,127 @@ export default robots;
 
 ---
 
+### Middleware per il routing delle lingue
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+Aggiungi un middleware per gestire il rilevamento delle lingue e il routing:
+
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from "next/server";
+import { defaultLocale, locales } from "@/i18n.config";
+
+const PUBLIC_FILE = /\.[^/]+$/; // esclude i file con estensioni
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/static") ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+
+  const hasLocale = locales.some(
+    (l) => pathname === "/" + l || pathname.startsWith("/" + l + "/")
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = "/" + locale + (pathname === "/" ? "" : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+
+export const config = {
+  matcher: [
+    // Corrisponde a tutti i percorsi tranne quelli che iniziano con questi e i file con un'estensione
+    "/((?!api|_next|static|.*\\..*).*)",
+  ],
+};
+```
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+Aggiungi un middleware per gestire il rilevamento delle lingue e il routing:
+
+```ts fileName="src/middleware.ts"
+import createMiddleware from "next-intl/middleware";
+import { locales, defaultLocale } from "@/i18n";
+
+export default createMiddleware({
+  locales: [...locales],
+  defaultLocale,
+  localeDetection: true,
+});
+
+export const config = {
+  // Salta API, Next internals e asset statici
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+Intlayer fornisce la gestione del middleware integrata attraverso la configurazione del package `next-intlayer`.
+
+```ts fileName="src/middleware.ts"
+import { intlayerProxy } from "next-intlayer/proxy";
+
+export const middleware = intlayerProxy();
+
+// applica questo middleware solo ai file nella directory app
+export const config = {
+  matcher: "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+La configurazione del middleware è centralizzata nel file `intlayer.config.ts`.
+
+  </Tab>
+</Tabs>
+
+### Checklist di configurazione e buone pratiche
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+- Assicurati che `lang` e `dir` siano impostati su root `<html>` in `src/app/[locale]/layout.tsx`.
+- Dividi le traduzioni in namespace (ad esempio `common.json`, `about.json`) sotto `src/locales/<locale>/`.
+- Carica solo i namespace richiesti nei componenti client utilizzando `useTranslation('<ns>')` e limitando il scope di `I18nProvider` agli stessi namespace.
+- Mantieni le pagine statiche quando possibile: esporta `export const dynamic = 'force-static'` nelle pagine; imposta `dynamicParams = false` e implementa `generateStaticParams`.
+- Utilizza componenti server sincronizzati annidati sotto i confini client passando stringhe già calcolate o la funzione `t` e la `locale`.
+- Per SEO, imposta `alternates.languages` nei metadati, elenca gli URL localizzati in `sitemap.ts` e disabilita le rotte localizzate duplicate in `robots.ts`.
+- Preferisci i formatter consapevoli della locale (ad esempio `Intl.NumberFormat(locale)`) e memoizzali sul client se usi React < 19.
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+- **Imposta l'`lang` e il `dir` dell'html**: In `src/app/[locale]/layout.tsx`, calcola `dir` tramite `getLocaleDirection(locale)` e imposta `<html lang={locale} dir={dir}>`.
+- **Dividi i messaggi per namespace**: Organizza il JSON per locale e namespace (ad esempio `common.json`, `about.json`).
+- **Minimizza il payload client**: Nelle pagine, invia solo i namespace richiesti a `NextIntlClientProvider` (ad esempio `pick(messages, ['common', 'about'])`).
+- **Preferisci pagine statiche**: Esporta `export const dynamic = 'force-static'` e genera parametri statici per tutte le `locales`.
+- **Componenti server sincronizzati**: Mantieni i componenti server sincronizzati passando stringhe precalcolate (etichette tradotte, numeri formattati) piuttosto che chiamate asincrone o funzioni non serializzabili.
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+- **Contenuto modulare**: Coloca i dizionari di contenuto insieme ai componenti utilizzando file `.content.{ts|js|json}`.
+- **Type safety**: Sfrutta l'integrazione TypeScript per la validazione del contenuto in fase di compilazione.
+- **Ottimizzazione in fase di build**: Utilizza gli strumenti di build di Intlayer per il tree-shaking automatico e l'ottimizzazione del bundle.
+- **Tooling integrato**: Approfitta del routing integrato, degli helper SEO e del supporto dell'editor visuale.
+
+  </Tab>
+</Tabs>
+
+---
+
 ## E il vincitore è…
 
 Non è semplice. Ogni opzione ha dei compromessi. Ecco come la vedo: