next-intl VS @intlayer/next-intl: Stessa API, Bundle Diverso

@intlayer/next-intl è un compat adapter: espone l'API di next-intl (useTranslations, getTranslations, useLocale, t.rich(), ICU plurals, NextIntlClientProvider...) e la serve da dizionari compilati da Intlayer. Il codice dell'applicazione non cambia. Il bundle sì.

Questo articolo confronta i due sulla stessa applicazione Next.js, costruita una volta con next-intl e una volta con l'adapter. I numeri provengono da Benchmark Bloom, una suite open-source che registra ciò che il browser effettivamente scarica. Se vuoi il confronto next-intl vs Intlayer come librerie, leggi next-intl vs Intlayer. Questo riguarda ciò che l'adapter cambia quando mantieni i tuoi componenti come sono.

tl;dr: Sulla stessa app Next.js, sostituire next-intl con @intlayer/next-intl ha ridotto il JavaScript per pagina da 153.6 KB a 147.5 KB gzip, il componente medio da 21.8 KB a 8.1 KB, la perdita di stringhe da pagine estere da ~90% a 0%, e l'idratazione da 14.7 ms a 12.8 ms, senza modificare alcun componente. Su TanStack Start, l'equivalente use-intl (@intlayer/use-intl) ha ridotto i componenti da 76-87 KB a 9-11 KB e il cambio di locale da 7-21 ms a 4-9 ms. L'adapter costa 8.0 KB di runtime rispetto ai 14.7 KB di next-intl e ai 5.5 KB di next-intlayer nativo. La navigazione e il middleware vengono reimplementati sulla configurazione di routing di Intlayer; i pathnames localizzati sono l'unica feature non trasferita.

Cos'è @intlayer/next-intl

next-intl è un runtime: getRequestConfig carica un messages/{locale}.json per richiesta, NextIntlClientProvider lo invia al client, e useTranslations("about") legge le chiavi da quell'oggetto al momento del render. Ogni ottimizzazione (namespace, pick(messages, [...]) per pagina, lazy loading) è a tuo carico.

@intlayer/next-intl mantiene la prima e l'ultima parte di quella catena e sostituisce quella centrale. I tuoi componenti continuano a chiamare useTranslations("about"; quello che ricevono proviene da un dizionario Intlayer compilato al momento della build, limitato a quel componente, solo nella locale attiva.

Tre meccanismi lo rendono possibile:

1. Import aliasing. createNextIntlPlugin() da @intlayer/next-intl/plugin avvolge withIntlayer e aggiunge alias Webpack / Turbopack in modo che next-intl, next-intl/server, next-intl/navigation e next-intl/middleware si risolvano a @intlayer/next-intl. Nessun import nella tua codebase viene rinominato.
2. JSON come fonte di verità. Il plugin syncJSON legge il tuo messages/{locale}.json esistente, divide le sue chiavi di primo livello in un dizionario per namespace, e scrive le traduzioni negli stessi file quando CLI o CMS li aggiorna. Il workflow dei tuoi traduttori rimane invariato.
3. Call-site binding. La pass di ottimizzazione di Intlayer (Babel o SWC) riscrive useTranslations("about") in una chiamata che riceve direttamente il dizionario about. Il componente non raggiunge più un albero di messaggi globale; raggiunge il suo stesso contenuto.

// Il tuo codice, invariato
import { useTranslations } from "next-intl";

const AboutPage = () => {
  const t = useTranslations("about");
  return <h1>{t("title")}</h1>;
};

import _dicHash_about from "../.intlayer/dictionaries/about.mjs";
import { useDictionary as useTranslations } from "@intlayer/next-intl";

const AboutPage = () => {
  const t = useTranslations(_dicHash_about);
  return <h1>{t("title")}</h1>;
};

Questo riscrittura è il motivo per cui le colonne dimensioni dei componenti e page-leakage qui sotto si spostano: una pagina estrae solo i dizionari dei componenti che renderizza, e solo nella locale servita.

Ciò che l'adapter mantiene, ignora e non sostituisce

Il benchmark

Cosa è stato misurato

La suite Benchmark Bloom costruisce la stessa applicazione con ogni setup: 10 pagine (home, about, blog, careers, contact, FAQ, pricing, products, settings, team), 10 locale (en, fr, es, de, it, pt, zh, ja, ko, ru), componenti identici e contenuto identico. Le pagine sono misurate in en e fr.

next-intl è stato costruito con quattro strategie di caricamento, dalla configurazione ingenua (messages/{locale}.json caricato interamente) a quella ottimale (uno namespace per route + pick() per pagina). L'adapter è stato costruito sugli stessi componenti della configurazione ingenua, con solo next.config.ts e intlayer.config.ts modificati. Non ha una variante "scoped": il compiler scopa il contenuto per componente, quindi le righe static e dynamic sono già scoped.

Per ogni build, la suite registra:

• Lib size: dimensione gzip di un componente vuoto che importa solo la libreria i18n. Il costo fisso del runtime.
• Page JS: JavaScript gzip scaricato per pagina, mediato su tutte le pagine e le locale.
• Locale leak %: percentuale di stringhe tradotte trovate nel JS scaricato che appartengono a una locale che l'utente non sta visualizzando.
• Page leak %: percentuale di stringhe tradotte trovate nel JS scaricato che appartengono a una pagina su cui l'utente non si trova.
• Component avg: dimensione gzip media di ogni componente compilato isolatamente. Mostra quanto runtime i18n e catalogo un singolo componente comporta.
• E2E reactivity: tempo trascorso tra la selezione di una nuova locale e l'aggiornamento di html[lang] nel DOM (Playwright, 5 iterazioni).
• Hydration: durata della fase di hydration di React.

I numeri sottostanti provengono dall'esecuzione datata 2026-09-12 con next-intl / use-intl 4.14.2 e @intlayer/* 9.5.1. L'applicazione di test è deliberatamente piccola (poche decine di stringhe per locale), quindi le percentuali di leakage descrivono un pattern: crescono con i tuoi contenuti mentre il costo del runtime rimane fisso.

Risultati su Next.js

Seleziona le metriche e le librerie che ti interessano:

Come leggerlo

• Stessi componenti, 6 KB in meno per pagina. La build dell'adapter dell'app naive atterra a 147.5 KB, al di sotto di ogni configurazione di next-intl inclusa quella completamente ottimizzata (153.6 KB). Il runtime stesso è la differenza: 8.0 KB versus 14.7 KB, pagati su ogni pagina.
• La perdita di dati va a 0% senza toccare un componente. La configurazione naive di next-intl spedisce ~90% delle stringhe di pagine straniere su ogni pagina. Raggiungere 0% con next-intl significa le configurazioni scoped-*: uno namespace per route e pick(messages, [...]) in ogni pagina. L'adapter raggiunge 0% dal codice naive perché il pass di ottimizzazione lega ogni useTranslations("ns") al proprio dizionario.
• I componenti si riducono 2.7x. Un componente compilato in isolamento media 21.8 KB con next-intl (raggiunge il provider e l'albero dei messaggi) e 8.1 KB con l'adapter. Nella configurazione scoped-static di next-intl quel numero sale fino a 80 KB, perché il file namespace di ogni route diventa raggiungibile dalla pagina che lo seleziona.
• L'idratazione è 2 ms più veloce (12.8 vs 14.7 ms): non c'è nessun oggetto messaggio da deserializzare dal payload RSC prima che React possa idrare.
• L'adapter non è il runtime nativo. next-intlayer si posiziona a 141.3 KB, +0.3 KB sopra l'app base, con un runtime di 5.5 KB. L'adapter trasporta la superficie API di next-intl (useFormatter, t.rich, il risolutore ICU) in cima al core di Intlayer, da cui 8.0 KB e +6 KB per pagina. È il ponte, non la destinazione.

Tabella completa, ogni libreria e ogni strategia, nel report di benchmark Next.js.

Risultati su TanStack Start (use-intl)

use-intl è il core framework-agnostico di next-intl. Il suo adapter, @intlayer/use-intl, segue lo stesso design con un plugin Vite (@intlayer/use-intl/plugin).

Come leggerlo

• I byte per pagina sono equivalenti rispetto a use-intl ottimizzato. @intlayer/use-intl in modalità dynamic (129.7 KB) è entro 1 KB da use-intl's scoped-dynamic (128.7 KB), e 10 KB più grande di use-intl's plain dynamic (119.4 KB). Quella riga dynamic plain ha ancora una perdita del 90% di stringhe da pagine estere; il conteggio dei byte è basso perché il contenuto dell'app di test è piccolo. Lo 0% dell'adapter è quello che rimane piatto man mano che il contenuto cresce.
• I componenti sono 7-9 volte più piccoli. I componenti use-intl hanno una media di 76-87 KB in ogni strategia, perché useTranslations è associato all'intero oggetto messaggio del provider. L'adapter ha una media di 9-11 KB.
• Lo switching delle locale è più veloce. Gli setup use-intl ottimizzati impiegano 13-21 ms per aggiornare html[lang]; l'adapter impiega 4-9 ms. Meno componenti vengono renderizzati di nuovo, e niente viene ripreso da un albero di messaggi.
• static mantiene ogni locale. La riga static dell'adapter mostra una perdita di locale del 49,7%, la stessa di Intlayer nativo in modalità static: tutte le locale vengono raggruppate, solo i dizionari della pagina. Una riga di configurazione (importMode: 'dynamic') la rimuove.

Tabella completa nel report di benchmark TanStack Start.

Perché i numeri cambiano

Poiché niente nel componente è cambiato, i guadagni provengono interamente da ciò a cui useTranslations è associato.

Con next-intl, il binding è il provider. NextIntlClientProvider riceve l'intero oggetto messages per la locale; ogni useTranslations("about") legge da esso. Il bundler vede un componente che importa un hook che legge un context, e non può sapere che solo il ramo about è utilizzato. Le route di seguito condividono tutti lo stesso oggetto message, quindi la colonna page-leak legge ~90% fino a quando non dividi il file tu stesso, e lo spreco cresce su due assi contemporaneamente, pagine e impostazioni locali:

.
├── messages
│   ├── en.json                       # ogni namespace, ogni pagina
│   └── fr.json
└── src
    ├── i18n.ts                       # getRequestConfig({ messages: await import(...) })
    ├── middleware.ts                 # createMiddleware(routing)
    └── app/[locale]
        ├── layout.tsx                # <NextIntlClientProvider messages={messages}>
        └── about/page.tsx            # useTranslations("about")

Con @intlayer/next-intl, il binding è il dizionario. syncJSON trasforma messages/en.json in un dizionario per ogni chiave di primo livello; il compilatore risolve quale componente chiama useTranslations("about") e gli passa about direttamente, nella locale attiva, come un import che il bundler può tracciare e splittare.

.
├── intlayer.config.ts                # syncJSON({ source: ({ locale }) => `./messages/${locale}.json` })
├── messages
│   ├── en.json                       # unchanged, still the source of truth
│   └── fr.json
├── .intlayer/                        # generated: one dictionary per namespace, per locale
└── src
    ├── middleware.ts                 # createMiddleware() ora restituisce il proxy di Intlayer
    └── app/[locale]
        ├── layout.tsx                # <NextIntlClientProvider> (nessun prop messages)
        └── about/page.tsx            # useTranslations("about")  ← invariato

src/i18n.ts e il prop messages scompaiono. Tutto il resto è identico.

Migrazione in tre passaggi

1. 1

   Installa

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   npx intlayer init --interactive
   

   Il comando rileva next-intl e installa intlayer, next-intlayer, @intlayer/next-intl e @intlayer/sync-json-plugin. Mantieni next-intl installato: è una peer dependency dell'adapter e fornisce i types.

2. 2

   Punta Intlayer ai tuoi messaggi

   intlayer.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   import { syncJSON } from "@intlayer/sync-json-plugin";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
       defaultLocale: Locales.ENGLISH,
     },
     dictionary: {
       // "static" raggruppa ogni locale; "dynamic" carica quella attiva su richiesta
       importMode: "dynamic",
     },
     plugins: [
       syncJSON({
         // Placeholder ICU: {name}, {count, plural, one {# item} other {# items}}
         format: "icu",
         source: ({ locale }) => `./messages/${locale}.json`,
         location: "messages",
       }),
     ],
   };
   
   export default config;
   

   messages/{locale}.json rimane dov'è. Ogni chiave di primo livello diventa un dictionary; useTranslations("about") viene mappato al dictionary about.

3. 3

   Avvolgi next.config.ts

   next.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import type { NextConfig } from "next";
   import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
   
   const withIntlayer = createNextIntlPlugin();
   
   const nextConfig: NextConfig = {};
   
   export default withIntlayer(nextConfig);
   

   createNextIntlPlugin() compone withIntlayer (content watching, compilazione del dizionario, il passaggio di ottimizzazione) e gli alias next-intl → @intlayer/next-intl per Webpack e Turbopack. Compila, e i numeri nelle tabelle sopra sono tuoi.

Cosa puoi eliminare successivamente

Cosa guadagni oltre ai byte

• Typed keys. useTranslations("about") è tipizzato rispetto al dizionario compilato about. t("does.not.exist") è un errore TypeScript, non un fallback runtime.
• npx intlayer test interrompe la CI quando a una locale manca una chiave. npx intlayer fill traduce le chiavi mancanti con il provider di tua scelta (OpenAI, Anthropic, Mistral, Gemini...) utilizzando la tua chiave personale e scrive il risultato in messages/{locale}.json.
• Visual Editor e CMS funzionano sugli stessi dizionari, quindi gli sviluppatori non svuoti possono modificare messages/fr.json attraverso un'interfaccia utente e il file si aggiorna.
• Migrazione incrementale a .content.ts. Qualsiasi componente può passare da useTranslations("about") a useIntlayer("about") con un file di contenuto colocato, uno alla volta. I dizionari JSON e .content.ts coesistono e si uniscono.

Limiti da conoscere prima di iniziare

Quando usare quale?

FAQ

Confronti correlati

Stessa serie di adattatori:

Le librerie a confronto diretto:

Documenti di riferimento:

Per capire da dove vengono queste librerie, leggi la storia dell'i18n in JavaScript.

Conclusione

@intlayer/next-intl fa una cosa sola: cambia a cosa è associato useTranslations, da un provider che contiene ogni messaggio a un dizionario compilato per quel componente. Sulla stessa app Next.js che vale 6 KB per pagina, componenti 2,7x più piccoli, 0% leakage e 2 ms di hydration, prima che chiunque apra un file di componente. Navigation e middleware mantengono la loro API in cima alla configurazione di routing di Intlayer, e il runtime nativo next-intlayer rimane ancora più leggero.

Tutti i dati grezzi, le app di test e gli script sono nel repository Benchmark Bloom. Eseguilo tu stesso.

Fai riferimento al doc 'Why Intlayer?' per ulteriori dettagli.