@intlayer/docs 9.1.3 → 9.3.0

package/docs/it/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Traccia l'esposizione dei contenuti ed esegui test A/B
+description: Scopri come @intlayer/analytics traccia le visualizzazioni di pagine/lingue e l'esposizione dei contenuti, e come usarlo per eseguire test A/B sui tuoi contenuti Intlayer.
+keywords:
+  - Analytics
+  - Test A/B
+  - Audience
+  - Internazionalizzazione
+  - Documentazione
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — pacchetto @intlayer/analytics, tracciamento a livello provider/nodo, test A/B, dashboard"
+author: aymericzip
+---
+
+# Documentazione Intlayer Analytics
+
+`@intlayer/analytics` è un pacchetto complementare opzionale che ti indica **quali contenuti vengono effettivamente mostrati** ai tuoi visitatori — in quale pagina, in quale lingua (locale) e quale specifico frammento di contenuto tradotto — così da poter comprendere il tuo pubblico ed eseguire **test A/B sui contenuti**.
+
+## Indice
+
+<TOC/>
+
+---
+
+## Cosa traccia
+
+`@intlayer/analytics` raggruppa tre tipi di eventi anonimi in batch:
+
+| Evento             | Dove viene catturato                             | Cosa ti dice                                                                                                                                       |
+| ------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | Livello Provider (`IntlayerProvider`)            | Quale pagina e lingua una sessione ha visualizzato, al caricamento iniziale, al cambio di rotta o al cambio di lingua.                             |
+| `content_exposure` | Livello Nodo (`useIntlayer` / plugin interpreti) | Quale chiave del dizionario / percorso della chiave è stato effettivamente risolto e mostrato — e, se parte di un esperimento, quale **variante**. |
+| `conversion`       | Ovunque chiami `useConversion()`                 | Un obiettivo raggiunto (registrazione, clic, acquisto...) attribuito alla variante A/B a cui la sessione è stata esposta.                          |
+
+Gli eventi vengono raccolti in memoria e inviati come una **singola richiesta batch all'incirca ogni 20 secondi** — mai a ogni pressione di tasto o rendering — così l'analisi non impatta mai il tempo di primo rendering né aggiunge una richiesta per interazione.
+
+## Come supporta i test A/B sui contenuti
+
+Intlayer ti permette già di dichiarare le [Varianti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md) del contenuto (es. un dizionario `hero-banner` con una variante `control` e una `black_friday`). `@intlayer/analytics` chiude il cerchio:
+
+1. `getVariant(experimentKey, variants)` assegna in modo deterministico ogni sessione anonima a una variante — una funzione pura dell'id della sessione e della chiave dell'esperimento, quindi l'assegnazione è **stabile per tutta la sessione** e non richiede **round-trip al server** prima del primo rendering (nessun fastidioso sfarfallio, nessun layout shift).
+2. Ogni evento di `content_exposure` trasporta la `variant` che è stata mostrata.
+3. `useConversion()` ti permette di attribuire un obiettivo (es. `"cta_click"`) a quella variante.
+4. L'endpoint dei risultati degli esperimenti della dashboard confronta i tassi di conversione per variante, includendo la significatività statistica (uno z-test).
+
+## Installazione
+
+`@intlayer/analytics` è una dipendenza **peer e opzionale** — non viene mai installata automaticamente da un pacchetto del framework. Aggiungila assieme a `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+Se non la installi, ogni punto di integrazione si risolve in una no-op (nessuna operazione) — vedi [Costo zero quando non installato](#costo-zero-quando-non-installato) di seguito.
+
+## Configurazione
+
+Analytics **riutilizza il blocco di configurazione `editor` esistente** — non c'è uno schema di configurazione `analytics` separato da compilare:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Utilizzato anche come endpoint di acquisizione analytics
+    clientId: "your-client-id", // Utilizzato anche come chiave progetto analytics
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — l'URL base a cui vengono inviati gli eventi analytics (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — la chiave pubblica del progetto attribuita a ogni evento acquisito. Funge anche da **interruttore di abilitazione**: l'analisi rimane completamente disabilitata (e scartata dal tree-shaking, vedi sotto) finché `clientId` non viene configurato.
+
+Se gestisci Intlayer in self-hosting, le analytics puntano automaticamente alla tua istanza poiché condivide `editor.backendURL`.
+
+## Supporto Framework
+
+L'Analytics è cablata nel `IntlayerProvider` condiviso di `react-intlayer`, quindi è disponibile oggi ovunque venga utilizzato quel provider:
+
+| Framework                                                | Stato                                                                                                            |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Disponibile                                                                                                   |
+| Next.js (`next-intlayer`)                                | ✅ Disponibile (tramite `react-intlayer`)                                                                        |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Disponibile (tramite `react-intlayer`)                                                                        |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Pianificato — stesso client, binding a livello provider seguendo il pattern di rilascio di `@intlayer/editor` |
+
+## Utilizzo
+
+### Tracciamento automatico a livello di provider
+
+Non sono richieste modifiche al codice. Una volta installato `@intlayer/analytics` e configurato `editor.clientId`, `IntlayerProvider` automaticamente:
+
+- inizializza il client analytics al montaggio (mount),
+- registra un `page_view` al caricamento iniziale,
+- registra un `page_view` ad ogni cambio di lingua (locale),
+- avvia il ciclo di svuotamento (flush) di ~20s e svuota eventuali eventi rimanenti allo smontaggio / chiusura della scheda (tramite `navigator.sendBeacon`, con fallback su `fetch(..., { keepalive: true })`).
+
+### Tracciamento automatico a livello di nodo
+
+Ogni volta che `useIntlayer` risolve un pezzo di contenuto da mostrare, l'interprete riporta un evento di `content_exposure` per quell'esatto `dictionaryKey` + percorso della chiave + lingua — di nuovo, nessuna modifica al codice richiesta. Le esposizioni ripetute dello stesso nodo entro una finestra di flush vengono riunite in un singolo evento con un conteggio (`count`), così un elenco che esegue 50 re-rendering non invia 50 eventi.
+
+### Tracciare le conversioni per i test A/B
+
+Usa `useConversion()` per attribuire un obiettivo alla variante che una sessione ha visto:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Inizia ora
+    </button>
+  );
+};
+```
+
+### Risolvere una variante lato client
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Privacy e prestazioni
+
+- **Anonimo by design**: le sessioni sono identificate da un id a rotazione; il backend memorizza sempre e solo un **hash SHA-256** di quell'id — mai l'id non elaborato, mai un indirizzo IP.
+- **La localizzazione è approssimativa**: solo un codice paese, derivato dalle intestazioni di geolocalizzazione della CDN (`cf-ipcountry`, `x-vercel-ip-country`, ...) — nessun IP viene letto o memorizzato.
+- **Gli URL escludono i parametri di ricerca** per impostazione predefinita, quindi le query string non vengono mai catturate.
+- **Campionamento (Sampling)**: `sampleRate` ti permette di conservare solo una frazione degli eventi di esposizione dei contenuti nelle app ad alto traffico.
+- **In batch**: una richiesta circa ogni 20 secondi (`flushInterval`), o prima se il buffer si riempie (`maxBufferSize`) — mai una richiesta per evento.
+
+### Costo zero quando non installato
+
+`@intlayer/analytics` segue esattamente lo stesso pattern di dipendenza opzionale di `@intlayer/editor`:
+
+- ogni punto di integrazione carica il pacchetto tramite un **`import()` dinamico racchiuso in `try/catch`** — un'app che non installa mai `@intlayer/analytics` non paga un costo in termini di bundle-size o runtime, e non vede mai un errore;
+- una variabile d'ambiente a tempo di compilazione (`INTLAYER_ANALYTICS_ENABLED`), impostata automaticamente su `'false'` da `@intlayer/config` qualora `editor.clientId` non sia configurato, permette ai bundler di **eliminare tramite dead-code** l'intera integrazione;
+- le analytics sono disabilitate all'interno dell'iframe di anteprima di Intlayer editor/CMS, in modo che le sessioni dell'editor non contino mai come vero traffico.
+
+## Dashboard: Pagina Analytics
+
+Una volta che il tuo progetto ha raccolto eventi, la pagina **Analytics** nella [dashboard di Intlayer](https://app.intlayer.org/analytics) (visibile nella barra laterale una volta selezionato un progetto) mostra:
+
+- **Utenti attivi** — visitatori distinti nella finestra mobile selezionata (7 / 30 / 90 giorni).
+- **Utenti di oggi** e **utenti negli ultimi 7 giorni**.
+- **Visualizzazioni di pagina** nella finestra selezionata.
+- Un **grafico di evoluzione** dei visitatori distinti giornalieri.
+- Schede di ripartizione per **Lingue (Locales)** e **Posizione (Location)**, classificando il tuo pubblico per lingua e per nazione.
+
+## Riferimento API Backend
+
+Tutti gli endpoint di lettura richiedono l'autenticazione; l'acquisizione è pubblica e attribuita dal `clientId`.
+
+| Metodo | Endpoint                                    | Descrizione                                                                          |
+| ------ | ------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `POST` | `/api/analytics/events`                     | Ingerisci un batch di eventi (pubblico, attribuito da `clientId` nel body).          |
+| `GET`  | `/api/analytics/overview`                   | Totali pagina/lingua per il progetto autenticato.                                    |
+| `GET`  | `/api/analytics/audience?days=30`           | Visitatori distinti, visualizzazioni pagina, serie giornaliera, ripartizioni.        |
+| `GET`  | `/api/analytics/content-stats`              | Totali esposizione per contenuto, raggruppati per chiave dizionario/percorso/lingua. |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Tassi di conversione per variante e significatività statistica per test A/B.         |
+
+Puoi anche richiamare questi endpoint in modo programmatico con il [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## Link utili
+
+- [Dizionari Dinamici - Collezioni & Varianti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md)
+- [Riferimento Configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md)
+- [Guida Self-Hosting](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/self_hosting.md)

package/docs/it/autoFill.md

@@ -75,11 +75,30 @@ In v7, il comportamento del comando `fill` è stato aggiornato:
 
 Quando si utilizza un'opzione di percorso per scrivere in un altro file, il meccanismo di compilazione funziona attraverso una relazione _master-slave_ tra i file di dichiarazione del contenuto. Il file principale (master) funge da fonte di verità, e quando viene aggiornato, Intlayer applicherà automaticamente tali modifiche ai file di dichiarazione derivati (compilati) specificati dal percorso.
 
-# Traduzioni dei File di Dichiarazione del Contenuto con Compilazione Automatica
+### Personalizzazione per Locale
 
-I **file di dichiarazione del contenuto con compilazione automatica** sono un modo per velocizzare il tuo flusso di lavoro di sviluppo.
+Puoi anche personalizzare il comportamento per ogni locale utilizzando un oggetto:
 
-Il meccanismo di compilazione automatica funziona attraverso una relazione _master-slave_ tra i file di dichiarazione dei contenuti. Quando il file principale (master) viene aggiornato, Intlayer applicherà automaticamente tali modifiche ai file di dichiarazione derivati (compilati automaticamente).
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Consigliato per evitare Property 'pl' is missing in type '{ en: string; xxx } on your t function if
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Riempi e modifica il file corrente per l'inglese
+      fr: "./translations/fr.json", // Crea file separato per il francese
+      es: false, // Disabilita il fill per lo spagnolo
+    },
+  },
+};
+```
+
+Ciò ti consente di avere comportamenti di fill diversi per locale diversi all'interno dello stesso progetto.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -87,16 +106,16 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
-    contentExample: "Questo è un esempio di contenuto", // esempio di contenuto
+    contentExample: "This is an example of content",
   },
 } satisfies Dictionary;
 
 export default exampleContent;
 ```
 
-Ecco un [file di dichiarazione dei contenuti per locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/per_locale_file.md) che utilizza l'istruzione `autoFill`.
+Qui c'è un [file di dichiarazione di contenuto per locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/per_locale_file.md) che utilizza l'istruzione `fill`.
 
 Quindi, quando esegui il seguente comando:
 
@@ -116,7 +135,7 @@ pnpm intlayer fill --file 'src/components/example/example.content.ts'
 bun x intlayer fill --file 'src/components/example/example.content.ts'
 ```
 
-Intlayer genererà automaticamente il file di dichiarazione derivato in `src/components/example/example.content.json`, compilando tutte le localizzazioni non già dichiarate nel file principale.
+Intlayer genererà automaticamente il file di dichiarazione derivato in `src/components/example/example.content.json`, compilando tutti i locale non già dichiarati nel file principale.
 
 ```json5 fileName="src/components/example/example.content.json"
 {
@@ -133,7 +152,7 @@ Intlayer genererà automaticamente il file di dichiarazione derivato in `src/com
 }
 ```
 
-Successivamente, entrambi i file di dichiarazione saranno uniti in un unico dizionario, accessibile tramite il consueto hook `useIntlayer("example")` (react) / composable (vue).
+In seguito, entrambi i file di dichiarazione verranno uniti in un unico dizionario, accessibile utilizzando l'hook standard `useIntlayer("example")` (react) / composable (vue).
 
 ## Configurazione Globale
 

package/docs/it/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Ottimizzazione delle dimensioni e delle prestazioni del bundle i18n
 description: Riduci le dimensioni del bundle della tua applicazione ottimizzando i contenuti di internazionalizzazione (i18n). Scopri come sfruttare il tree shaking e il lazy loading per i dizionari con Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` e `minify` ora funzionano su Next.js tramite `@intlayer/swc` — nessun `babel.config.js` richiesto"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "Elencare i plugin Babel nell'ordine di pipeline richiesto (extract → purge → minify → optimize) nelle tabelle di riferimento"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Aggiunto `intlayerPurgeBabelPlugin` e `intlayerMinifyBabelPlugin` per Babel/Webpack; chiarimento della pipeline dei plugin"
@@ -191,12 +197,14 @@ L'ottimizzazione in fase di build di Intlayer è suddivisa tra diversi plugin di
 
 Questi sono usati direttamente nel file `babel.config.js` per i setup basati su Webpack (Next.js con Babel, CRA, Webpack personalizzato, ecc.).
 
+La tabella seguente li elenca nel loro ordine di pipeline richiesto (lo stesso ordine in cui devono comparire in `babel.config.js`):
+
 | Plugin                        | Cosa fa                                                                                                                                    |
 | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | Scansiona i file `.content.ts` e scrive i dizionari compilati in `.intlayer/`                                                              |
-| `intlayerOptimizeBabelPlugin` | Riscrive `useIntlayer('key')` in `useDictionary(hash)` e inietta la dichiarazione di `import` corrispondente al dizionario                 |
 | `intlayerPurgeBabelPlugin`    | Scansiona tutti i file sorgente, rimuove i **campi di contenuto inutilizzati** dai file di dizionario JSON compilati `.intlayer/**/*.json` |
 | `intlayerMinifyBabelPlugin`   | **Rinomina le chiavi dei campi di contenuto** in brevi alias alfabetici (`title` → `a`) sia nei file JSON che nel codice sorgente          |
+| `intlayerOptimizeBabelPlugin` | Riscrive `useIntlayer('key')` in `useDictionary(hash)` e inietta la dichiarazione di `import` corrispondente al dizionario                 |
 
 > **L'ordine dei plugin è importante.** Nel tuo `babel.config.js` i plugin purge e minify devono apparire **prima** del plugin optimize. La fase optimize sostituisce `useIntlayer('key')` con una chiamata opaca a `useDictionary(hash)`, cancellando le informazioni della chiave del dizionario di cui le fasi purge e minify hanno bisogno per identificare quali campi vengono usati.
 
@@ -205,9 +213,9 @@ Ogni plugin Babel ha un relativo helper per le opzioni che legge il tuo `intlaye
 | Helper opzioni               | Usato con                     |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Plugin Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Gli utenti di Vite **non configurano mai questi direttamente**. Vengono cablati
 | Dictionary minify   | Stesso comportamento della fase di scrittura JSON in `intlayerMinifyBabelPlugin`                                    |
 | Babel transform     | Stesso comportamento di ridenominazione codice sorgente `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
 
+### Plugin SWC (`@intlayer/swc`)
+
+Nemmeno gli utenti di Next.js **configurano mai questi direttamente**. Dalla **v9.2.1**, `withIntlayer()` in `next.config.ts` esegue l'intera pipeline — purge, minify e riscrittura degli import — basandosi solo sui flag `build.purge` e `build.minify`.
+
+Il lavoro è diviso in due, perché un plugin Wasm SWC trasforma un file alla volta e non ha accesso al file system:
+
+| Passata                                           | Dove viene eseguita           | Cosa fa                                                                                                 |
+| :------------------------------------------------ | :---------------------------- | :------------------------------------------------------------------------------------------------------ |
+| Analisi d'uso + purge/minify del JSON             | Node, dentro `withIntlayer()` | Legge ogni file sorgente dei componenti, riscrive `.intlayer/**/*.json`, produce le tabelle di rinomina |
+| Riscrittura del sorgente (`content.title` → `.a`) | `@intlayer/swc` (Wasm)        | Applica le tabelle di rinomina agli accessi alle proprietà corrispondenti nel tuo codice                |
+| Riscrittura degli import (`useIntlayer` → dict)   | `@intlayer/swc` (Wasm)        | Come `intlayerOptimizeBabelPlugin`                                                                      |
+
+Decidere _quali_ campi sono inutilizzati e _quale_ alias assegnare a ciascuno richiede stato tra file e I/O su file, quindi quella metà viene eseguita in Node; il plugin SWC riceve solo le tabelle risultanti.
+
 ## Configurazione per Piattaforma
 
 <Tabs>
@@ -227,10 +249,12 @@ Gli utenti di Vite **non configurano mai questi direttamente**. Vengono cablati
 
 ### Next.js
 
-Next.js richiede il plugin `@intlayer/swc` per la fase optimize (riscrittura degli import), perché Next.js usa SWC per le build.
+Next.js richiede il plugin `@intlayer/swc`, perché Next.js usa SWC per le build. Dalla **v9.2.1** questo singolo pacchetto copre l'intera pipeline — ottimizzazione (riscrittura degli import), purge e minify.
 
 > Questo plugin non è installato di default perché i plugin SWC sono ancora sperimentali in Next.js. Questo aspetto potrebbe cambiare in futuro.
 
+> **Next.js 16.1.0 è la versione minima.** È la prima release costruita sull'ABI dei plugin Wasm di SWC compatibile in avanti; le release precedenti rifiutano il plugin. `withIntlayer` legge la tua versione di Next.js e semplicemente non registra il plugin sotto la 16.1.0 — quelle build riescono comunque, semplicemente girano senza l'ottimizzazione del bundle.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 Una volta installato, Intlayer rileverà e utilizzerà automaticamente il plugin.
 
-Per i passaggi di **purge e minify** (rimozione dei campi e ridenominazione dei campi), installa `@intlayer/babel` insieme e aggiungi i plugin Babel. Dal momento che Next.js usa SWC per le trasformazioni ma valuta ancora `babel.config.js` per la configurazione dei plugin, i plugin Babel agiscono come fase preliminare rispetto ad SWC.
+Le passate di **purge e minify** (rimozione e rinomina dei campi) non richiedono alcun pacchetto aggiuntivo né `babel.config.js`. Avvolgi la tua configurazione con `withIntlayer` e attiva i flag in `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* la tua configurazione */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: rimuove campi di contenuto inutilizzati da .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: rinomina le chiavi dei campi di contenuto nel JSON + codice sorgente
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Nota: intlayerOptimizeBabelPlugin NON è necessario qui perché
-    // @intlayer/swc gestisce la riscrittura da useIntlayer a useDictionary.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // rimuove i campi di contenuto inutilizzati dal JSON incluso nel bundle
+    minify: true, // rinomina le chiavi dei campi con alias brevi
+  },
 };
+
+export default config;
 ```
 
+Durante `next build`, `withIntlayer` analizza i tuoi sorgenti, riscrive i dizionari compilati e passa le tabelle di rinomina risultanti a `@intlayer/swc`, che aggiorna gli accessi alle proprietà corrispondenti nel tuo codice.
+
+> Usa il `withIntlayer` asincrono, non `withIntlayerSync`. La variante sincrona non esegue la pipeline di analisi, quindi purge e minify non hanno alcun effetto con essa.
+
+> Purge e minify vengono eseguiti solo con `next build` — la pipeline di ottimizzazione è disattivata durante `next dev`.
+
+> Sono inoltre disabilitati quando sono configurati chiamanti degli adattatori di compatibilità (`swcExtraCallers`, impostati dai pacchetti di compatibilità come `@intlayer/next-intl` o `@intlayer/react-i18next`): quei punti di chiamata sono invisibili all'analizzatore d'uso, quindi il purge rimuoverebbe campi che il codice legge ancora. La riscrittura degli import resta attiva.
+
+**Le versioni precedenti (prima della 9.2.1)** richiedevano `@intlayer/babel` e un `babel.config.js` che dichiarasse `intlayerPurgeBabelPlugin` e `intlayerMinifyBabelPlugin`. Quel file non è più necessario e può essere eliminato.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > La minificazione viene saltata quando `optimize` è `false` o quando `editor.enabled` è `true` (l'editor visuale richiede il nome completo della proprietà per consentire la modifica).
 
+> Su Next.js la minificazione viene saltata anche quando `@intlayer/swc` non è installato o non può essere caricato (Next.js sotto la 16.1.0). Il plugin è la metà che riscrive gli accessi nel sorgente, quindi rinominare i dizionari senza di esso lascerebbe il tuo codice a leggere nomi di campi che non esistono più.
+
 > La minificazione viene ignorata anche per i dizionari caricati tramite `importMode: 'fetch'` perché i loro JSON vengono serviti tramite API remote usando le chiavi dei campi originali; rinominarle rovinerebbe il contratto tra client e server.
 
 ### Purging (rimozione dei campi non usati)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Il purge viene saltato se `optimize` è `false` o quando `editor.enabled` è `true`.
+> Il purge viene saltato se `optimize` è `false` o quando `editor.enabled` è `true`. Su Next.js viene inoltre saltato quando `@intlayer/swc` non è disponibile e quando sono configurati chiamanti degli adattatori di compatibilità.
 
 > Il purge viene saltato per precauzione qualora un file non riesca a essere analizzato, oppure se l'oggetto `useIntlayer` viene riversato in altri valori usando parametri dinamici non analizzabili (come distruggere parti non strutturate, assegnazioni generiche ai props ecc.). In questi scenari viene conservato l'intero dizionario.
 

package/docs/it/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Configurazione
 description: Scopri come configurare Intlayer per la tua applicazione. Comprendi le diverse impostazioni e opzioni disponibili per personalizzare Intlayer secondo le tue necessità.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "Rendere `routing.enableProxy` a tre stati: non impostato (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "Aggiunta la configurazione `analytics`"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Abilita il proxy di routing delle locale di Intlayer (middleware).
+     * Gestisce rilevamento della locale, redirect e rewrite in dev, preview e SSR.
+     * - non impostato (auto): i server di dev e preview mantengono il routing
+     *   guidato dall'URL ignorando la locale salvata in cookie e header. I prefissi
+     *   vengono ancora risolti, la locale viene ancora persistita e il rilevamento
+     *   Accept-Language si applica ancora. In produzione si comporta come `true`.
+     * - true: comportamento completo in ogni ambiente.
+     * - false: nessun routing delle locale.
+     * Predefinito: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Dove memorizzare il locale selezionato dall'utente.
      * Opzioni: 'cookie', 'localStorage', 'sessionStorage', 'header' o un array di questi.
@@ -716,13 +732,14 @@ Gli analytics sono rigorosamente opt-in: non viene raccolto nulla a meno che `an
 
 Impostazioni che controllano il comportamento del routing, inclusa la struttura dell'URL, lo storage del locale e la gestione del middleware.
 
-| Campo      | Descrizione                                                                                                                                                                                                               | Tipo                                                                                                                                                                                                         | Predefinito            | Esempio                                                                                                                                                                                 | Commenti                                                                                                                                                                                                                                                                                                           |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mode`     | Modalità di routing URL per la gestione dei locale.                                                                                                                                                                       | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) o `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale gestito diversamente. `'search-params'`: `/dashboard?locale=fr` | Non influisce sulla gestione dei cookie o sul local storage.                                                                                                                                                                                                                                                       |
-| `storage`  | Configurazione per lo storage del locale sul client.                                                                                                                                                                      | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | Vedi la tabella dei parametri di storage sotto.                                                                                                                                                                                                                                                                    |
-| `basePath` | Percorso base per gli URL dell'applicazione.                                                                                                                                                                              | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | Se la tua app è su `https://example.com/my-app`, basePath è `'/my-app'` e gli URL sono `https://example.com/my-app/en`.                                                                                                                                                                                            |
-| `rewrite`  | Regole di riscrittura URL personalizzate per sovrascrivere la modalità di routing predefinita per percorsi specifici. Supporta parametri dinamici `[param]`.                                                              | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Vedi Esempio sotto                                                                                                                                                                      | • Regole di riscrittura con priorità più alta rispetto alla `mode`.<br/>• Funziona con Next.js e Vite.<br/>• `getLocalizedUrl()` applica automaticamente le regole appropriate.<br/>• Vedi [Riscritture URL Personalizzate](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md). |
-| `domains`  | Mappa i locale ai nomi host del dominio per il routing basato sul dominio. Quando impostato, gli URL per un locale usano quel dominio come base (URL assoluto) e non viene aggiunto alcun prefisso di locale al percorso. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • Il protocollo è impostato su `https://` se non incluso nel nome host.<br/>• Il dominio stesso identifica il locale, quindi non viene aggiunto alcun prefisso `/zh/`.<br/>• `getLocalizedUrl('/', 'zh')` restituisce `https://intlayer.zh/`.                                                                      |
+| Campo         | Descrizione                                                                                                                                                                                                               | Tipo                                                                                                                                                                                                         | Predefinito            | Esempio                                                                                                                                                                                 | Commenti                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | Modalità di routing URL per la gestione dei locale.                                                                                                                                                                       | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) o `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale gestito diversamente. `'search-params'`: `/dashboard?locale=fr` | Non influisce sulla gestione dei cookie o sul local storage.                                                                                                                                                                                                                                                                                                                                       |
+| `enableProxy` | Abilita il proxy di routing delle locale di Intlayer (middleware).                                                                                                                                                        | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                  | • Non impostato (auto): i server di dev e preview ignorano la locale salvata in cookie/header come sorgente di redirect; prefissi, persistenza e rilevamento `Accept-Language` si applicano ancora. In produzione si comporta come `true`.<br/>• `true`: comportamento completo ovunque.<br/>• `false`: nessun routing delle locale. Su Next.js il middleware `intlayerProxy` diventa trasparente. |
+| `storage`     | Configurazione per lo storage del locale sul client.                                                                                                                                                                      | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | Vedi la tabella dei parametri di storage sotto.                                                                                                                                                                                                                                                                                                                                                    |
+| `basePath`    | Percorso base per gli URL dell'applicazione.                                                                                                                                                                              | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | Se la tua app è su `https://example.com/my-app`, basePath è `'/my-app'` e gli URL sono `https://example.com/my-app/en`.                                                                                                                                                                                                                                                                            |
+| `rewrite`     | Regole di riscrittura URL personalizzate per sovrascrivere la modalità di routing predefinita per percorsi specifici. Supporta parametri dinamici `[param]`.                                                              | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Vedi Esempio sotto                                                                                                                                                                      | • Regole di riscrittura con priorità più alta rispetto alla `mode`.<br/>• Funziona con Next.js e Vite.<br/>• `getLocalizedUrl()` applica automaticamente le regole appropriate.<br/>• Vedi [Riscritture URL Personalizzate](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                                                 |
+| `domains`     | Mappa i locale ai nomi host del dominio per il routing basato sul dominio. Quando impostato, gli URL per un locale usano quel dominio come base (URL assoluto) e non viene aggiunto alcun prefisso di locale al percorso. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • Il protocollo è impostato su `https://` se non incluso nel nome host.<br/>• Il dominio stesso identifica il locale, quindi non viene aggiunto alcun prefisso `/zh/`.<br/>• `getLocalizedUrl('/', 'zh')` restituisce `https://intlayer.zh/`.                                                                                                                                                      |
 
 **Esempio di `rewrite`**:
 

package/docs/it/dictionary/file.md

@@ -23,7 +23,9 @@ history:
 author: aymericzip
 ---
 
-# Contenuto File / Incorporare File in Intlayer
+# Contenuto File / Incorporamento di File in Intlayer
+
+In Intlayer, la funzione `file` consente di incorporare il contenuto di file esterni in un dizionario. Questo approccio garantisce che Intlayer riconosca il file sorgente, abilitando un'integrazione perfetta con l'Editor Visuale Intlayer e CMS.
 
 ## Come Funziona l'Incorporamento dei File