@intlayer/docs 9.4.1 → 9.4.3

package/blog/it/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Come testare le traduzioni senza scrivere test fragili"
+description: Cosa vale la pena testare in un'applicazione i18n e cosa no. Test di rendering con provider, pseudolocalizzazione, copertura RTL e plurali, e la trappola degli snapshot.
+keywords:
+  - testare traduzioni
+  - test i18n
+  - testing library i18n
+  - pseudolocalizzazione
+  - test provider locale
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# Come testare le traduzioni senza scrivere test fragili
+
+La maggior parte delle suite di test i18n fallisce per due motivi. O eseguono asserzioni sul testo letterale, per cui ogni minima modifica di copy rompe cinquanta test e il team finisce per cancellarli. Oppure renderizzano tutto nella lingua predefinita, non dimostrando nulla sulle altre diciassette. Entrambe le strade portano allo stesso risultato, una suite di cui nessuno si fida.
+
+## Indice
+
+<TOC/>
+
+## I pattern sono indipendenti dalla libreria
+
+Ciascun pattern mostrato di seguito funziona con qualsiasi stack i18n. Sostituisci il provider con `I18nextProvider`, `NextIntlClientProvider` o `IntlProvider` e i test rimangono identici, poiché verificano l'output renderizzato anziché una specifica API di libreria.
+
+Anche gli strumenti di copertura si adattano facilmente: con il [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md) collegato ai tuoi cataloghi esistenti, o un [adattatore di compatibilità](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/index.md) che crea alias sui tuoi import attuali, l'asserzione di copertura viene eseguita sul JSON che già possiedi.
+
+## Decidere cosa stai realmente testando
+
+La qualità della traduzione non è un test. Nessuna asserzione può dirti se il tedesco suoni naturale, e pretendere il contrario produce una suite piena di stringhe hardcodate.
+
+Ciò che vale la pena testare è meccanico:
+
+| Vale la pena testare                        | Non vale la pena testare                |
+| :------------------------------------------ | :-------------------------------------- |
+| Ogni locale richiesta ha un valore          | Se il testo è ben scritto               |
+| La locale corretta raggiunge il componente  | La copia esatta di ogni etichetta       |
+| I plurali si risolvono per ogni categoria   | Se il traduttore ha fatto il suo lavoro |
+| I locali RTL impostano direzione e specchio | Ogni stringa in ogni lingua             |
+| Date e numeri formattati usano la locale    | La correttezza interna di `Intl`        |
+
+La copertura appartiene a un unico test basato sui dati, non ai test dei singoli componenti. Questo argomento è approfondito in [individuare le traduzioni mancanti](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/detecting_missing_translations.md); questo articolo si concentra sul resto.
+
+## Renderizzare sotto un provider e interrogare per ruolo
+
+Il pattern fondamentale consiste nel montare il componente all'interno di un provider di locale e interrogare per ruolo o test id invece che per testo.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("renderizza l'intestazione del riepilogo in francese", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Interrogare `getByRole("heading")` sopravvive a un cambio di testo. `getByText("Récapitulatif")` fallisce al primo ritocco. Usa il testo letterale solo quando la stringa stessa è l'oggetto del test, il che è raro.
+
+Per attributi come `aria-label` ti serve la stringa grezza piuttosto che un nodo renderizzabile. In React, le voci di `useIntlayer` espongono un campo `.value` a tale scopo.
+
+## Parametrizzare i test tra le diverse lingue
+
+Un unico blocco di test eseguito su tutte le lingue apporta molto più valore di un test separato per lingua.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("renderizza senza ricorrere alla chiave grezza", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // Una chiave renderizzata significa che la risoluzione è fallita.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("imposta la corretta direzione del testo", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+La prima asserzione offre un vantaggio generico ed economico: se una ricerca fallisce e la libreria mostra la chiave, il DOM conterrà qualcosa come `cart.summary.title`. Questo intercetta un'intera classe di bug senza nominare una sola stringa.
+
+## La pseudolocalizzazione rileva ciò che i cataloghi non vedono
+
+Aggiungi una finta lingua che trasformi ogni stringa, ad esempio trasformando `Checkout` in `[!!! Çĥéçķöũţ !!!]`. Quindi renderizza la pagina in quella lingua.
+
+Tutto ciò che rimane in inglese puro è scritto direttamente nel codice. Nessun controllo basato sui cataloghi può individuarlo, poiché per gli strumenti quella stringa semplicemente non esiste. Le parentesi svolgono un secondo compito: allungano il testo di circa il 30 percento, facendo emergere problemi di layout prima ancora di testare in tedesco.
+
+È consigliabile eseguire questo passaggio come verifica visiva o end-to-end piuttosto che come unit test, poiché il difetto si nota visivamente.
+
+## I plurali richiedono un test per categoria, non per lingua
+
+I bug sui plurali rimangono nascosti perché l'inglese ha solo due forme e la maggior parte degli sviluppatori si limita a quelle. Il polacco ne ha quattro, l'arabo sei.
+
+```ts fileName="plural.test.ts"
+// L'arabo copre zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("conteggio %i", (count) => {
+  it("produce una stringa non vuota in arabo", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Scegli valori numerici che coprano ciascuna categoria CLDR per la lingua più complessa anziché testare 1 e 2 ovunque. `Intl.PluralRules` ti indica in quale categoria rientra un numero, consentendoti di ricavare il campione di test senza tirare a indovinare. Maggiori dettagli nell'[articolo sul formato di messaggi ICU](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/icu_message_format.md).
+
+## La trappola degli snapshot
+
+Gli snapshot e l'i18n sono una combinazione pericolosa. Uno snapshot di un componente localizzato memorizza ogni stringa al suo interno: se un traduttore corregge un refuso in portoghese, una suite verde diventa rossa, su un file che nessun revisore è in grado di comprendere a fondo. Dopo la terza volta, qualcuno lancia `-u` senza leggere il diff, e gli snapshot perdono ogni significato.
+
+Se vuoi usare gli snapshot, eseguili solo su una singola lingua e considerali come un controllo strutturale anziché sui contenuti. Tutto ciò che è specifico di una lingua appartiene ad asserzioni esplicite.
+
+## Testare la negoziazione, non solo il rendering
+
+Il bug i18n più comune in produzione non è una stringa mancante. È la selezione della lingua sbagliata: un URL indica `/fr/`, il client legge `navigator.language`, e i due valori sono in disaccordo.
+
+Testa l'ordine di risoluzione direttamente, come funzione pura, separata da qualsiasi componente:
+
+```ts fileName="locale-resolution.test.ts"
+it("preferisce l'URL rispetto alla preferenza memorizzata", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("ricorre all'header quando l'URL non ha prefisso", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+Questo è il singolo test di i18n di maggior valore mancante nella maggior parte delle codebase, e non necessita del DOM.
+
+## Cosa eseguire e dove
+
+- **Unit**: negoziazione della lingua, formattatori, categorie di plurali. Rapido, senza DOM.
+- **Componente**: un rendering con provider per lingua, verificando ruoli e assenza di chiavi grezze.
+- **Copertura**: un test basato sui dati che certifichi l'assenza di lingue richieste mancanti.
+- **Visivo o end-to-end**: passaggio di pseudolocalizzazione e una pagina RTL, poiché tali errori sono visivi.
+
+Mantieni i primi tre nella pipeline a ogni commit. L'ultimo è economico da eseguire la notte e dispendioso su ogni push.
+
+## Errori comuni
+
+- **Verificare il testo esatto ovunque.** Porta all'abbandono e cancellazione della suite entro pochi mesi.
+- **Snapshot di componenti localizzati.** I traduttori bloccano la build e i revisori approvano senza verificare.
+- **Testare solo la lingua predefinita.** L'unica lingua che non può mai mancare.
+- **Testare solo 1 e 2 per i plurali.** Salta tutte le categorie che l'inglese non possiede.
+- **Mockare la libreria i18n.** In tal caso stai solo testando che il tuo mock restituisca stringhe.
+- **Non testare mai la negoziazione.** Il guasto reale più comune e il più semplice da validare.
+
+## Per approfondire
+
+- [Testare i contenuti: audit CLI, API programmatica e asserzioni UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/testing.md)
+- [Plugin ESLint: rilevare stringhe hardcodate e contenuti inutilizzati](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/eslint.md)
+- [Formattatori e utilità di lingua, compreso `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/formatters.md)
+- [Report di benchmark tra diversi framework](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/benchmark/index.md)
+- [Adattatore di compatibilità react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/react-i18next.md)
+- [Come individuare le traduzioni mancanti](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/detecting_missing_translations.md)
+- [Formato dei messaggi ICU: plurali, select e scheletri](https://github.com/aymericzip/intlayer/blob/main/docs/blog/it/icu_message_format.md)

package/blog/it/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
@@ -191,8 +191,6 @@ 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>

package/blog/it/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
@@ -141,8 +141,6 @@ 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).
 
----
-
 </Step>
 
 <Step number={3} title="Implementare traduzioni JSON per componente" isOptional={true}>
@@ -186,8 +184,6 @@ 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>

package/blog/it/intlayer_with_next-intl.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.

package/blog/it/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.

package/blog/it/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.

package/blog/it/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
@@ -143,8 +143,6 @@ Se vengono effettuate modifiche utilizzando la CLI per tradurre il JSON, o utili
 
 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).
 
----
-
 </Step>
 
 <Step number={3} title="Implementare traduzioni JSON per componente" isOptional={true}>
@@ -189,8 +187,6 @@ 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>

package/blog/it/is_i18next_outdated.md

@@ -0,0 +1,315 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: i18next è obsoleto nel 2026?
+description: i18next alimenta milioni di siti web, ma la sua architettura a runtime del 2011 mostra i segni del tempo. Un'analisi su bundle bloat, limiti di tree-shaking e innovazione ferma.
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - Internazionalizzazione
+  - i18n
+  - Dimensione bundle
+  - Blog
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# i18next è obsoleto nel 2026?
+
+`i18next` è nato nel 2011, molto prima che i componenti React, il bundling con Webpack o TypeScript diventassero lo standard. Ha conquistato l'ecosistema grazie a flessibilità e capillarità, con plugin per ogni tecnologia e risposte su StackOverflow per qualsiasi dubbio.
+
+Non è abbandonato, gli aggiornamenti escono regolarmente. Esiste però una differenza sostanziale tra mantenere attivo un motore collaudato ed evolversi con le moderne architetture frontend.
+
+Negli ultimi anni, il mondo frontend si è spostato verso la compilazione in fase di build, i React Server Components (RSC), il tree-shaking aggressivo e i flussi guidati dall'IA. Il nucleo di i18next resta quello di dieci anni fa: un singleton a runtime che risolve chiavi di testo sul client.
+
+<TOC/>
+
+## Punti chiave
+
+**Fase di manutenzione:**
+
+Nell'ultimo anno, `next-i18next` ha registrato ~63 commit (circa uno a settimana) e `react-i18next` ~157, quasi tutti dedicati ad aggiornamenti di dipendenze e piccole correzioni.
+
+**Impatto pesante sul runtime:**
+
+`react-i18next` e `next-i18next` introducono ~17–18 KB gzipped (~60 KB minificati) prima ancora di renderizzare una sola parola, quasi il quadruplo di `next-intlayer` (~4.7 KB).
+
+**Perdita consistente di dati (leakage):**
+
+Nelle configurazioni statiche predefinite, fino al **89.8%** dei contenuti di localizzazione inviati a una pagina appartiene ad altre route o a lingue non consultate.
+
+**Tree-shaking impossibile:**
+
+Chiamate dinamiche come `t("home.hero.title")` non possono essere interpretate dai bundler, costringendo l'intero catalogo JSON nel chunk del client.
+
+**Modello commerciale:**
+
+I maintainer gestiscono Locize. Sviluppare una pipeline di traduzione IA locale e gratuita direttamente nella CLI entrerebbe in concorrenza diretta con la loro principale fonte di ricavi.
+
+## Manutenzione vs. evoluzione attiva
+
+Le stelle GitHub testimoniano l'adozione storica più che l'attuale dinamismo architetturale.
+
+| Repository              | Stelle                                                                                                                                                     | Commit totali                                                                                                                                                           | Commit / anno                                                                                                                                                          | Ultimo commit                                                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+Attività negli ultimi 12 mesi:
+
+| Progetto        | Commit storici | Ultimi 12 mesi | Priorità                             |
+| --------------- | -------------- | -------------- | ------------------------------------ |
+| `next-i18next`  | 1.311          | **63**         | Compatibilità Next.js e correzioni   |
+| `react-i18next` | 1.988          | **157**        | Tipi e manutenzione                  |
+| `i18next` core  | 2.626          | **259**        | Piccoli aggiornamenti                |
+| Intlayer        | 7.156          | **4.343**      | Compilatore, tooling IDE e motore IA |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+Una libreria snella può essere solida e affidabile. Ma gli strumenti di i18n progrediscono costantemente: i bundler odierni eliminano i testi inutilizzati durante il build, gli LLM traducono direttamente in CI e gli editor si affidano a server di linguaggio (LSP) e agenti IA. L'architettura puramente a runtime di i18next limita queste possibilità.
+
+## Misurazione del costo sul bundle
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Misurato su build di produzione con 10 route e 10 lingue, compressione gzip attiva. Maggiori dettagli nel [report del benchmark i18n](https://intlayer.org/it/doc/benchmark).
+
+### Peso iniziale delle librerie
+
+Impatto base prima dell'inserimento di qualsiasi testo tradotto:
+
+| Libreria               | Gzipped    | Minificato  |
+| ---------------------- | ---------- | ----------- |
+| `next-i18next@16.0.5`  | 17.8 KB    | 61.2 KB     |
+| `react-i18next@17.0.2` | 17.3 KB    | 59.8 KB     |
+| `intlayer@8.7.12`      | **4.7 KB** | **12.8 KB** |
+
+### Peso della pagina e dispersione dei contenuti
+
+Test eseguito con React / TanStack Start (strategia statica):
+
+| Libreria              | JS medio / pag (gz) | Dispersione lingue | Dispersione altre pag | Componente medio (gz) | Idratazione |
+| --------------------- | ------------------- | ------------------ | --------------------- | --------------------- | ----------- |
+| `react-i18next`       | 180.3 KB            | **50.0%**          | **89.8%**             | 24.3 KB               | 85.1 ms     |
+| Intlayer              | **127.8 KB**        | 50.0%              | **0.8%**              | **7.1 KB**            | **24.1 ms** |
+| Intlayer (scoped dyn) | **118.1 KB**        | **0.0%**           | **0.8%**              | **4.6 KB**            | 23.7 ms     |
+
+Su Next.js:
+
+| Libreria        | JS medio / pag (gz) | Dispersione altre pag | Componente medio (gz) |
+| --------------- | ------------------- | --------------------- | --------------------- |
+| Base (no i18n)  | 150.8 KB            | 0.0%                  | 0.7 KB                |
+| `next-i18next`  | **227.5 KB**        | **89.8%**             | 24.5 KB               |
+| `next-intlayer` | **152.1 KB**        | **0.0%**              | **7.2 KB**            |
+
+### Risultati principali
+
+**Peso della pagina:**
+
+Su Next.js, `next-i18next` introduce **76.7 KB gzipped** rispetto alla base (+50%). `next-intlayer` aggiunge appena 1.3 KB.
+
+**Dispersione delle traduzioni:**
+
+Di base, quasi il **90% dei testi caricati** su una route appartiene ad altre pagine del sito. La separazione manuale per namespace è onerosa e fonte di imprecisioni.
+
+**Tempi di idratazione:**
+
+I componenti con `react-i18next` hanno impiegato **85 ms** per idratarsi contro i **24 ms** di Intlayer. Inviare grandi alberi JSON ai componenti client rallenta l'interattività.
+
+## Perché i18next è pesante?
+
+### Funzionalità accumulate a runtime
+
+Operare interamente nel browser impone di includere tutte le funzioni all'avvio: interpolazione, regole di plurale, contesti, formattatori ed event bus. Anche per mostrare un testo elementare viene caricato l'intero motore.
+
+### Le chiavi dinamiche bloccano il tree-shaking
+
+Poiché `"hero.title"` viene calcolata dinamicamente a runtime, i bundler non sanno quali chiavi vengano effettivamente lette. Le stringhe inutilizzate restano nel bundle.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+Il [compilatore Intlayer](https://intlayer.org/it/doc/compiler) esamina ciò che `Hero.tsx` richiama ed elimina i campi non utilizzati prima della generazione dei bundle. Consulta [ottimizzazione del bundle](https://intlayer.org/it/doc/concept/bundle-optimization) per i dettagli.
+
+## Esperienza di sviluppo
+
+### File JSON isolati vs. co-locazione
+
+Con i18next i testi sono collocati in directory JSON distinte dal codice. Intlayer organizza i file di contenuto direttamente accanto ai componenti:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/it/hero.json"
+{
+  "title": "Distribuisci in ogni lingua"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      it: "Distribuisci in ogni lingua",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+Spostando o cancellando `Hero.tsx`, anche i suoi testi vengono spostati o rimossi di pari passo.
+
+### Autocompletamento vs. rigida sicurezza dei tipi
+
+Estendere `CustomTypeOptions` fornisce autocompletamento nell'editor, ma non assicura la presenza effettiva delle traduzioni. Rimuovere una chiave da `it/home.json` non interrompe il build, genera solo un fallback a runtime.
+
+Intlayer deduce i tipi direttamente dalle dichiarazioni di contenuto, e lo [`strictMode`](https://intlayer.org/it/doc/concept/configuration) trasforma le traduzioni mancanti in errori bloccanti al build.
+
+### Confronto degli strumenti
+
+| Funzionalità                  | Ecosistema i18next   | Intlayer                                                                 |
+| ----------------------------- | -------------------- | ------------------------------------------------------------------------ |
+| **Estensione VS Code**        | Solo terze parti     | ✅ [Estensione ufficiale](https://intlayer.org/it/doc/vs-code-extension) |
+| **Language Server (LSP)**     | ❌ Nessuno           | ✅ [LSP dedicato](https://intlayer.org/it/doc/lsp)                       |
+| **Server MCP (per IA)**       | ❌ Nessuno           | ✅ [Server MCP integrato](https://intlayer.org/it/doc/mcp-server)        |
+| **Competenze agente (Skill)** | ❌ Nessuna           | ✅ [Skill pronte all'uso](https://intlayer.org/it/doc/agent_skills)      |
+| **CMS Visuale in contesto**   | Locize (A pagamento) | ✅ [Gratuito & Open Source](https://intlayer.org/it/doc/concept/editor)  |
+
+## Traduzione e il modello di Locize
+
+Locize è il servizio commerciale ufficiale creato dagli autori di i18next. Il sostegno all'open source è fondamentale, tuttavia questo modello genera un compromesso: un progetto monetizzato con una piattaforma SaaS di traduzione ha scarso incentivo a integrare gratuitamente nella CLI un comando di traduzione IA locale.
+
+Intlayer sceglie una visione aperta:
+
+- [`intlayer fill`](https://intlayer.org/it/doc/concept/auto-fill) completa le traduzioni mancanti nel terminale o in CI tramite chiavi API proprietarie (OpenAI, Anthropic, Mistral, Gemini).
+- Il [CMS Intlayer](https://intlayer.org/it/doc/concept/cms) è open source e avviabile con Docker Compose.
+- Compilatore, CLI, editor e CMS sono tutti con licenza Apache 2.0.
+
+## In quali casi i18next è ancora adatto?
+
+<AccordionGroup>
+<Accordion header="Progetti esistenti stabili">
+
+Se l'applicazione risponde perfettamente alle esigenze e la dimensione del bundle non è critica, riscrivere il codice non è prioritario.
+
+</Accordion>
+<Accordion header="Piattaforme dedicate">
+
+L'ampia gamma di plugin di i18next supporta scenari specifici (Electron, applicazioni jQuery legacy, bridge nativi dedicati) che i compilatori attuali raramente considerano.
+
+</Accordion>
+<Accordion header="Ampio archivio di supporto">
+
+Lo storico presente su StackOverflow e GitHub aiuta ad affrontare agilmente casi limite.
+
+</Accordion>
+</AccordionGroup>
+
+## Come migliorare la mia configurazione i18next esistente?
+
+Intlayer offre pacchetti di compatibilità pronti all'uso che replicano fedelmente le firme delle funzioni delle librerie i18next (`i18next`, `react-i18next` e `next-i18next`). Non è necessario riscrivere i componenti per beneficiare dei vantaggi di un'architettura guidata dal compilatore.
+
+L'installazione si effettua con un solo comando:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+Questa CLI interattiva:
+
+1. Installa il pacchetto di compatibilità `@intlayer/i18next`.
+2. Configura gli alias del bundler affinché le importazioni abituali (`useTranslation`, `Trans`, `t`) puntino direttamente a Intlayer, consentendo di rimuovere la vecchia libreria da `package.json`.
+3. Attiva all'istante il supporto del Language Server (LSP) nell'IDE, l'ottimizzazione del bundle in fase di compilazione (tree-shaking completo) e i flussi di traduzione IA locali.
+
+Per istruzioni dettagliate, consulta le nostre guide dedicate:
+
+- **Livelli di compatibilità:** Conserva il tuo codice esistente con gli adapter per [i18next](https://intlayer.org/it/doc/compatibility/i18next), [react-i18next](https://intlayer.org/it/doc/compatibility/react-i18next) e [next-i18next](https://intlayer.org/it/doc/compatibility/next-i18next).
+- **Migrazione dei cataloghi:** Converti i file JSON in dizionari tipizzati con le nostre guide: [da i18next](https://intlayer.org/it/doc/migration/i18next), [da react-i18next](https://intlayer.org/it/doc/migration/react-i18next) o [da next-i18next](https://intlayer.org/it/doc/migration/next-i18next).
+- **Setup ibrido:** Conserva il runtime di i18next mentre [utilizzi Intlayer con i18next](https://intlayer.org/it/blog/intlayer-with-i18next) per tipizzare e autotradurre i cataloghi.
+
+Valuta la tua applicazione con l'[analizzatore SEO i18n gratuito](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Letture consigliate
+
+- [Benchmark Next.js i18n: analisi completa delle performance](https://intlayer.org/it/doc/benchmark/nextjs)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/it/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [next-intl è obsoleto nel 2026?](https://intlayer.org/it/blog/is-next-intl-outdated)
+- [Architettura a compilazione vs i18n dichiarativa](https://intlayer.org/it/blog/compiler-vs-declarative-i18n)