Come scegliere la giusta libreria i18n per React

React non include alcuna primitiva nativa per l'i18n. La libreria scelta al primo giorno determina come vengono archiviate le traduzioni, come arrivano nel bundle e quanto lavoro di manutenzione rimarrà a vostro carico per i prossimi anni. La maggior parte dei team sceglie in base alla popolarità, per poi scoprire i compromessi raggiunte le 2.000 chiavi.

Questa guida adotta l'approccio opposto: rispondete prima ad alcune domande sul vostro progetto, poi mappate le risposte sulle librerie più adatte. Si concentra su React puro (Vite, React Router, TanStack Start). Next.js ha vincoli specifici, trattati nel confronto Next.js.

Indice

Sei domande a cui rispondere prima di confrontare le librerie

Una tabella di funzionalità è inutile se non sapete quali aspetti contano per voi. Esaminate prima questi punti.

1. Come viene renderizzata l'applicazione? Solo SPA, SSR con hydration o React Server Components. Gli hook basati su Context funzionano ovunque in una SPA. Con i RSC, un hook forza "use client" su ogni componente che renderizza testo, quindi avrete bisogno anche di un'API lato server.
2. Chi scrive le traduzioni? Sviluppatori, un team interno che usa un TMS, un'agenzia che fornisce file ICU o una pipeline AI. Questo determina il formato del catalogo più di qualsiasi dettaglio di API.
3. Quante lingue (locales) e quante pagine? Due lingue e cinque pagine possono permettersi di includere tutto nel bundle. Dieci lingue e cinquanta route no, e la strategia di caricamento diventa il costo principale.
4. Avete bisogno di types sulle chiavi? Un errore di battitura in t("checkout.totl") compila senza problemi in qualsiasi libreria basata su chiavi a meno che non configuriate manualmente i types. Valutate se questo è accettabile.
5. Cosa contiene la stringa? Testo semplice, plurali o frasi con un <Link> nel mezzo. I contenuti complessi (rich content) sono il punto in cui la maggior parte delle API diventa macchinosa.
6. Quanto durerà il progetto? Un prototipo di tre mesi e un prodotto di cinque anni non richiedono la stessa quantità di build tooling.

Scrivete le risposte. Tutto ciò che segue fa riferimento ad esse.

Il panorama in un'unica panoramica

Quindici anni di i18n in JavaScript si riassumono in quattro ondate architetturali, e le librerie React che metterete a confronto provengono da ondate diverse.

La storia dell'i18n in JavaScript descrive in dettaglio come ogni ondata ha risolto i problemi della precedente.

La decisione più importante: dove risiedono i contenuti e quando vengono caricati

Ogni libreria i18n per React ha la stessa struttura: uno store, un provider, un hook. Tutto ciò che il provider riceve finisce nel bundle client o nel payload di hydration. Le due scelte strutturali sono quindi:

• Contenuto centralizzato o scoped. Un unico en.json per tutta l'applicazione, oppure una dichiarazione per componente (o per namespace).
• Import statico o dinamico. Tutto incluso nel bundle all'avvio, oppure locale e route attivi caricati on demand.

Il grafico seguente stima il payload per un'applicazione teorica da 1 a 10 pagine, tradotta in 1 - 10 lingue, con circa 30 KB di testo per pagina.

Il contenuto centralizzato con import statici cresce su entrambi gli assi: 10 pagine per 10 lingue equivalgono a 300 KB di testo su ogni pagina. Gli import dinamici eliminano l'asse delle lingue. Lo scoping elimina l'asse delle pagine. Solo la combinazione di entrambi mantiene il payload costante.

Questa non è una proprietà della libreria in sé, ma una questione di disciplina. react-i18next può essere strutturato con namespace e backend lazy. use-intl può essere suddiviso per route. Ma nulla lo impone in modo vincolante, e un componente <Button> condiviso che richiede t("common:cta") rende silenziosamente common una dipendenza di ogni route. Il benchmark misura questo fenomeno come "leakage da altre route" e "leakage da altre lingue", ed è qui che si crea la maggior parte del divario tra le librerie.

Se la vostra risposta alla domanda 3 era "molte lingue, molte pagine", date a questa sezione più peso rispetto a qualsiasi preferenza di API. L'articolo i18n per-component vs centralizzato approfondisce l'aspetto della manutenzione legato a questa scelta.

I candidati

Le dimensioni delle librerie provengono dal benchmark TanStack Start: provider più hook in un componente vuoto, dopo bundling, tree-shaking e minificazione, su 10 pagine e 10 lingue. I contenuti sono misurati separatamente.

I dati rappresentano uno snapshot delle versioni utilizzate nel benchmark e variano con le nuove release. Eseguite il benchmark sulla vostra applicazione prima di basare la decisione solo sulle dimensioni.

Due aspetti che la tabella non mostra. Paraglide non include quasi alcuna libreria a runtime perché genera codice direttamente nella vostra repository, il che implica uno step di rigenerazione prima di ogni commit e possibili conflitti di merge sui file generati. Intlayer richiede un plugin per il bundler (vite-intlayer o equivalente), quindi non può funzionare in configurazioni prive di build step.

Abbinare le risposte a una libreria

Dove ogni libreria mostra i suoi limiti

Limiti reali, poiché ogni opzione comporta dei compromessi.

• react-i18next: la più pesante del gruppo, formato proprietario per i plurali, configurazione dei types a carico dello sviluppatore, accumulo silenzioso di chiavi inutilizzate.
• react-intl: DX verbosa (useIntl() seguito da formatMessage({ id })), istanza globale legata a molti nodi.
• use-intl: semplice all'inizio, complessa da ottimizzare. La combinazione di namespace, caricamento dinamico e types rallenta notevolmente lo sviluppo.
• Lingui: step di build aggiuntivo con extract / compile, molteplici sintassi sovrapposte (t(), tagged template, i18n.t(), <Trans>) che disorientano sviluppatori e assistenti AI.
• Paraglide: file generati direttamente nel repository, tree-shaking non pienamente efficace nel benchmark React, e lettura della lingua dallo storage su ogni nodo invece che da uno store centralizzato.
• Tolgee: assenza di types sulle chiavi, onboarding più ripido, in-context editing come punto di forza principale.
• Intlayer: plugin di build obbligatorio, ecosistema più piccolo, supporto ICU parziale, contenuti distribuiti per progetto che richiedono tooling specifico per esportare un singolo JSON a un traduttore esterno.
• gt-react, lingo.dev: non consigliate nel benchmark: errori di quota in fase di build, vendor lock-in e problemi di reattività che richiedevano di forzare i re-render del provider.

Come si presenta ciascuna opzione nel codice

Lo stesso componente, un riepilogo del carrello con titolo e plurale, implementato con ciascun candidato. La parte rilevante non è il componente in sé, ma la collocazione dei contenuti e ciò che il type checker è in grado di verificare.

{
  "title": "Your cart",
  "items_one": "{{count}} item",
  "items_other": "{{count}} items"
}

import type { FC } from "react";
import { useTranslation } from "react-i18next";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { t } = useTranslation("cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

{
  "cart.title": "Your cart",
  "cart.items": "{count, plural, one {# item} other {# items}}"
}

import type { FC } from "react";
import { FormattedMessage, useIntl } from "react-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const intl = useIntl();

  return (
    <section>
      <h2>
        <FormattedMessage id="cart.title" />
      </h2>
      <p>{intl.formatMessage({ id: "cart.items" }, { count })}</p>
    </section>
  );
};

{
  "Cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

import type { FC } from "react";
import { useTranslations } from "use-intl";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const t = useTranslations("Cart");

  return (
    <section>
      <h2>{t("title")}</h2>
      <p>{t("items", { count })}</p>
    </section>
  );
};

msgid "Your cart"
msgstr "Votre panier"

msgid "{count, plural, one {# item} other {# items}}"
msgstr "{count, plural, one {# article} other {# articles}}"

import type { FC } from "react";
import { Plural, Trans } from "@lingui/react/macro";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>
      <Trans>Your cart</Trans>
    </h2>
    <p>
      <Plural value={count} one="# item" other="# items" />
    </p>
  </section>
);

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

import type { FC } from "react";
import { m } from "../paraglide/messages.js";

export const CartSummary: FC<{ count: number }> = ({ count }) => (
  <section>
    <h2>{m.cart_title()}</h2>
    <p>{m.cart_items({ count })}</p>
  </section>
);

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      it: "Il tuo carrello",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      it: plural({ one: "{{count}} articolo", other: "{{count}} articoli" }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} articolo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const CartSummary: FC<{ count: number }> = ({ count }) => {
  const { title, items } = useIntlayer("cart-summary");

  return (
    <section>
      <h2>{title}</h2>
      <p>{items(count)}</p>
    </section>
  );
};

Utilizzate già react-i18next, react-intl o Lingui? Gli adattatori di compatibilità (react-i18next, react-intl, Lingui) creano un alias per le importazioni a livello di bundler, consentendo all'API esistente di continuare a funzionare mentre migrate componente per componente. La guida alla migrazione illustra tutti i passaggi.

Prima di scegliere definitivamente

Una tabella riassuntiva illustra cosa offre una libreria oggi. I seguenti punti indicano come sarà gestirla nella quotidianità del progetto.

Verificate l'attività del repository.

Numero di commit, tempi di risposta alle issue e data dell'ultima minor release. Un'architettura solida senza un manutentore attivo si trasforma rapidamente in una migrazione forzata.

Non basatevi unicamente sui download di npm.

La libreria più scaricata è spesso quella rilasciata per prima, non necessariamente quella più adatta a una codebase React del 2026. I download misurano la storia, non la pertinenza tecnica attuale.

Verificate chi finanzia i manutentori e qual è il loro modello di business.

i18next è supportato da Locize. next-intl / use-intl, vue-i18n, svelte-i18n e Lingui sono supportati da Crowdin. Tolgee, Paraglide (inlang) e Intlayer gestiscono ciascuno la propria piattaforma. Un vendor i cui ricavi derivano dai servizi di traduzione hosted ha poco interesse a rendere la traduzione gratuita all'interno della vostra toolchain. Intlayer è l'unica del gruppo a offrire la traduzione con AI tramite CLI utilizzando la vostra chiave API personale, insieme a un CMS self-hostabile.

È pronta per gli agenti AI?

Gli agenti AI riscontrano ancora difficoltà con l'i18n: dimenticano lingue, inventano chiavi e mescolano sintassi di messaggi. La libreria fornisce Agent Skills o un server MCP affinché l'agente possa elencare, completare e testare i contenuti? Inoltre, il caricamento dei contenuti è ottimizzato per impostazione predefinita, o è necessario verificare namespace e lazy import a ogni release?

Type safety integrata di default.

Non "può essere tipizzata con configurazioni aggiuntive", ma "una chiave errata blocca tsc su un'installazione pulita". Verificate cosa accade con una chiave inesistente e con una lingua in cui manca una traduzione.

Rilevamento dei contenuti inutilizzati.

I cataloghi tendono solo a crescere nel tempo. La build di Intlayer elimina i campi inutilizzati e li segnala nei log (build.purge). Paraglide ottiene questo risultato a livello architetturale, poiché una funzione messaggio non invocata viene rimossa tramite tree-shaking. Tutte le altre soluzioni lasciano la pulizia a carico dello sviluppatore.

Developer experience.

Tempo necessario per configurare la prima stringa tradotta, presenza di un LSP o di un'estensione VS Code che mostra la traduzione all'hover e porta direttamente alla dichiarazione, una CLI per completamento, test e push, e uno strumento per consentire a figure non tecniche di modificare i contenuti (editor visuale o CMS) senza aprire una pull request.

Domande frequenti

Per approfondire

• Benchmark delle librerie i18n: bundle size, leakage e tempi di cambio lingua e il report TanStack Start
• React i18n: come funziona il modello del provider e quali sono i costi
• react-i18next vs react-intl vs Intlayer, funzionalità per funzionalità
• next-i18next vs next-intl vs Intlayer
• La storia dell'i18n in JavaScript
• Compiler vs i18n dichiarativo
• i18n per-component vs centralizzato
• Come funziona l'ottimizzazione del bundle in fase di build
• Configurare l'i18n in un'app Vite + React
• La stessa guida per Vue, Svelte e Solid