Buone pratiche di internazionalizzazione (i18n) in React e Next.js nel 2025

In un mondo digitale sempre più connesso, lo sviluppo di applicazioni web al servizio degli utenti globali non è più un elemento di differenziazione, ma una necessità. L'internazionalizzazione (i18n) è diventata una componente fondamentale nello sviluppo di applicazioni moderne, consentendo al tuo prodotto di raggiungere un pubblico diversificato indipendentemente dalla lingua, dalla regione o dalle preferenze culturali.

In questo articolo esploreremo le migliori pratiche, strumenti e strategie per implementare un'internazionalizzazione efficace nelle applicazioni React e Next.js nel 2025, fornendo esempi pratici e soluzioni alle sfide comuni.

Fondamenti di internazionalizzazione

Cos'è i18n e perché è importante?

Il termine "i18n" è l'abbreviazione di "internazionalizzazione" (la lettera "i" seguita da 18 lettere e termina con "n"). È il processo di progettazione e sviluppo di applicazioni software che possono essere adattate a diverse lingue e regioni senza modifiche tecniche o di codice.

Nel 2025, l’importanza di i18n è amplificata da diversi fattori:

Portata globale: le applicazioni con supporto multilingue possono raggiungere i mercati internazionali ed espandere la propria base di utenti.
Esperienza utente: gli utenti si sentono più a loro agio e coinvolti quando interagiscono con le applicazioni nella loro lingua madre.
Conformità normativa: molti paesi hanno requisiti legali affinché i sistemi digitali supportino le lingue locali.
Vantaggio competitivo: le applicazioni ben internazionalizzate si distinguono nei mercati globali competitivi.

Differenza tra i18n, l10n e g11n

È importante comprendere la distinzione tra i termini frequentemente utilizzati in questo dominio:

Internazionalizzazione (i18n): processo di progettazione e sviluppo di un prodotto in modo che possa essere adattato a diverse lingue e regioni.
Localizzazione (l10n): processo di adattamento di un prodotto internazionalizzato a un luogo o mercato specifico, inclusa la traduzione di testi e l'adattamento di elementi culturali.
Globalizzazione (g11n): strategia aziendale che copre sia i18n che l10n, considerando tutti gli aspetti necessari per portare un prodotto sui mercati globali.

Librerie e strumenti moderni per i18n in React

Ecosistema i18n nel 2025

L’ecosistema di internazionalizzazione per React si è evoluto in modo significativo negli ultimi anni. Ecco le librerie più popolari e avanzate nel 2025:

1. React-i18next

Il react-i18next continua ad essere una delle soluzioni più robuste e apprezzate, in evoluzione per soddisfare le esigenze moderne:

// Configuração básica do react-i18next em 2025
import i18n from 'i18next';
import { initReactI18next, useTranslation } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import Backend from 'i18next-http-backend';

i18n
  // Carregamento sob demanda de traduções
  .use(Backend)
  // Detecção automática de idioma
  .use(LanguageDetector)
  // Integração com React
  .use(initReactI18next)
  .init({
    fallbackLng: 'pt-BR',
    supportedLngs: ['pt-BR', 'en-US', 'es', 'fr', 'zh-CN'],
    
    // Novo em 2025: Detecção avançada de idioma com preferências de usuário
    detection: {
      order: ['localStorage', 'navigator', 'querystring', 'cookie'],
      caches: ['localStorage'],
      cookieExpirationDate: new Date(Date.now() + 1000 * 60 * 60 * 24 * 365),
      lookupQuerystring: 'lng',
      lookupCookie: 'i18n',
    },
    
    // Novo em 2025: Cache inteligente com estratégia adaptativa
    backend: {
      loadPath: '/locales//.json',
      requestOptions: {
        cache: 'smart-default', // Nova estratégia de cache adaptativa
      },
    },
    
    interpolation: {
      escapeValue: false, // React já escapa por padrão
      format: function(value, format, lng) {
        // Novo suporte para formatação avançada
        if (format === 'uppercase') return value.toUpperCase();
        if (format === 'currency') return new Intl.NumberFormat(lng, { style: 'currency', currency: 'BRL' }).format(value);
        return value;
      }
    },
    
    // Novo em 2025: Análise de uso de traduções para otimização
    telemetry: {
      enabled: process.env.NODE_ENV === 'development',
      endpoint: '/api/i18n-telemetry',
      sampleRate: 0.1
    }
  });

export default i18n;

2. Formato ICU con react-intl

Il formato ICU (International Components for Unicode) è diventato lo standard predominante per la gestione dei testi internazionalizzati:

// Exemplo usando react-intl com sintaxe ICU moderna
import React from 'react';
import { FormattedMessage, useIntl } from 'react-intl';

function ProductDetails({ product, inventory, lastUpdated }) {
  const intl = useIntl();
  
  return (
    <div className="product-card">
      <h2>{product.name}</h2>
      
      {/* Pluralização avançada */}
      <FormattedMessage
        id="product.inventory"
        defaultMessage="{inventory, plural, =0 {Fora de estoque} one {Última unidade disponível!} other {# unidades em estoque}}"
        values=
      />
      
      {/* Formatação de data relativa */}
      <FormattedMessage
        id="product.lastUpdated"
        defaultMessage="Atualizado {lastUpdated, relativeTime, style=long}"
        values=
      />
      
      {/* Formatação de valores variáveis dependentes de idioma */}
      <p>
        {intl.formatMessage(
          {
            id: 'product.price',
            defaultMessage: 'Preço: {price, number, currency}'
          },
          { price: product.price }
        )}
      </p>
      
      {/* Formatação condicional com seleção */}
      <FormattedMessage
        id="product.status"
        defaultMessage="{status, select, new {Novo} sale {Promoção} limited {Edição limitada} other {Regular}}"
        values=
      />
    </div>
  );
}

3. LinguiJS: una potente alternativa

LinguiJS ha guadagnato una notevole popolarità per la sua semplicità e prestazioni:

// Exemplo com Lingui v5 (versão 2025)
import React from 'react';
import { Trans, Plural, t } from '@lingui/macro';

function ShoppingCart({ items, totalPrice, lastUpdated }) {
  return (
    <div className="shopping-cart">
      <h2><Trans id="cart.title">Seu Carrinho</Trans></h2>
      
      <Plural
        value={items.length}
        zero={<Trans id="cart.empty">Seu carrinho está vazio</Trans>}
        one={<Trans id="cart.oneItem">1 item no carrinho</Trans>}
        other={<Trans id="cart.items">{items.length} itens no carrinho</Trans>}
      />
      
      {items.map(item => (
        <div key={item.id} className="cart-item">
          <span>{item.name}</span>
          <span>{t({
            id: 'cart.item.price',
            message: 'Preço: {price, number, currency}',
            values: { price: item.price }
          })}</span>
        </div>
      ))}
      
      <div className="cart-footer">
        <div className="total">
          <Trans id="cart.total" values=>
            Total: {totalPrice, number, currency}
          </Trans>
        </div>
        
        <div className="updated">
          <Trans id="cart.updated" values=>
            Atualizado em {lastUpdated, date, long}
          </Trans>
        </div>
      </div>
    </div>
  );
}

Implementazione di i18n in Next.js

Next.js si è affermato come uno dei framework React più popolari e le sue capacità di internazionalizzazione si sono evolute notevolmente nel 2025.

Configurazione i18n moderna in Next.js

L’approccio integrato di Next.js per i18n è diventato più robusto:

// next.config.js em 2025
/** @type {import('next').NextConfig} */
const nextConfig = {
  i18n: {
    // Idiomas suportados
    locales: ['pt-BR', 'en-US', 'es', 'fr', 'zh-CN'],
    
    // Idioma padrão
    defaultLocale: 'pt-BR',
    
    // Novos recursos em 2025
    localeDetection: true,     // Detecção automática de idioma
    automaticLocalePrefix: true, // Novo em 2025 - prefixos de URL simplificados
    
    // Domínios específicos por idioma (para SEO otimizado)
    domains: [
      {
        domain: 'meuapp.com.br',
        defaultLocale: 'pt-BR',
      },
      {
        domain: 'myapp.com',
        defaultLocale: 'en-US',
      },
      {
        domain: 'miapp.es',
        defaultLocale: 'es',
      },
    ],
    
    // Novo em 2025: estratégia de fallback para conteúdo parcialmente traduzido
    fallbackStrategy: 'partial',
    
    // Padrões de URL que não devem ser traduzidos 
    excludeFromTranslation: [
      '/api/*',
      '/admin/*',
      '/static/*',
    ],
  },
  
  // Outras configurações do Next.js
};

module.exports = nextConfig;

Utilizzo delle traduzioni nei componenti server e client

Next.js App Router ha introdotto una chiara separazione tra componenti server e client, che richiede approcci specifici per i18n:

// Exemplo para componentes Server no Next.js App Router

// Em /app/[lang]/layout.tsx
import { Locale } from '@/i18n/config';
import { getTranslations } from '@/i18n/server';

export default async function RootLayout({
  children,
  params: { lang }
}: {
  children: React.ReactNode;
  params: { lang: Locale };
}) {
  // Obter traduções no servidor
  const { t } = await getTranslations(lang, 'common');
  
  return (
    <html lang={lang}>
      <body>
        <header>
          <h1>{t('site.title')}</h1>
          <nav>
            <ul>
              <li>{t('nav.home')}</li>
              <li>{t('nav.products')}</li>
              <li>{t('nav.contact')}</li>
            </ul>
          </nav>
        </header>
        <main>{children}</main>
        <footer>{t('site.footer')}</footer>
      </body>
    </html>
  );
}

// Para componentes Client
'use client';

import { useTranslation } from '@/i18n/client';
import { useParams } from 'next/navigation';

export default function LanguageSwitcher() {
  const params = useParams();
  const lang = params.lang as Locale;
  const { t } = useTranslation(lang, 'common');
  
  return (
    <div className="language-selector">
      <p>{t('language.select')}</p>
      <select>
        <option value="pt-BR">{t('language.portuguese')}</option>
        <option value="en-US">{t('language.english')}</option>
        <option value="es">{t('language.spanish')}</option>
      </select>
    </div>
  );
}

Implementazione di una soluzione completa

Per mostrare come tutto si combina, ecco un'implementazione più completa dell'App Router di Next.js:

// Em /i18n/config.ts
export const defaultLocale = 'pt-BR';
export const locales = ['pt-BR', 'en-US', 'es', 'fr', 'zh-CN'] as const;
export type Locale = typeof locales[number];

// Em /i18n/server.ts
import { createInstance } from 'i18next';
import resourcesToBackend from 'i18next-resources-to-backend';
import { initReactI18next } from 'react-i18next/initReactI18next';
import { Locale, defaultLocale } from './config';

export async function getTranslations(locale: Locale, namespace: string) {
  const i18nInstance = createInstance();
  await i18nInstance
    .use(initReactI18next)
    .use(resourcesToBackend((language: string, ns: string) => 
      import(`./locales/${language}/${ns}.json`)))
    .init({
      lng: locale,
      fallbackLng: defaultLocale,
      supportedLngs: locales,
      defaultNS: 'common',
      ns: namespace,
      fallbackNS: 'common',
    });

  return {
    t: i18nInstance.getFixedT(locale, namespace),
    i18n: i18nInstance
  };
}

// Em /middleware.ts - para roteamento e redirecionamento baseado em idioma
import { NextRequest, NextResponse } from 'next/server';
import { match as matchLocale } from '@formatjs/intl-localematcher';
import Negotiator from 'negotiator';
import { locales, defaultLocale } from './i18n/config';

function getLocale(request: NextRequest): string {
  // Simulando cabeçalhos para o negotiator
  const headers = {
    'accept-language': request.headers.get('accept-language') || defaultLocale
  };

  const languages = new Negotiator({ headers }).languages();
  
  // Usar @formatjs/intl-localematcher para escolher o melhor idioma
  const locale = matchLocale(languages, locales, defaultLocale);
  
  return locale;
}

export function middleware(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  
  // Verificar se a URL já inclui uma localidade
  const pathnameHasLocale = locales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );

  if (pathnameHasLocale) return NextResponse.next();

  // Redirecionar se a localidade não estiver na URL
  const locale = getLocale(request);
  const newUrl = new URL(`/${locale}${pathname}`, request.url);
  
  return NextResponse.redirect(newUrl);
}

export const config = {
  matcher: [
    // Excluir arquivos estáticos e API
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
};

Decisioni architettoniche che contano

Al di là delle biblioteche, internazionalizzare bene è, innanzitutto, una decisione architettonica. Tre scelte definiscono quanto sarà sostenibile nel tempo l’operazione multilingue.

Il primo è separare il contenuto dal codice fin dall'inizio. Le stringhe non dovrebbero mai essere incorporate nei componenti; appartengono a file di traduzione con versione, organizzati per spazio dei nomi, in modo che traduttori e sviluppatori lavorino senza intromettersi a vicenda. Il secondo è trattare la pluralizzazione, il genere e la formattazione di numeri, date e valuta come responsabilità della libreria i18n, e non dei condizionali sparsi nel codice, poiché queste regole variano da lingua a lingua in modi che non possono essere risolti con la concatenazione di stringhe. Il terzo è definire, a livello di routing, una strategia chiara per il rilevamento della lingua, i prefissi URL e il fallback per i contenuti parzialmente tradotti, garantendo che ogni utente arrivi nella lingua giusta senza pagine interrotte lungo il percorso.

Nell'App Router di Next.js, ciò significa decidere consapevolmente cosa viene tradotto sul server e cosa viene consegnato al client, mantenendo la massima traduzione sul server per ridurre il JavaScript inviato al browser.

Conclusione

L’internazionalizzazione non è più una caratteristica opzionale ma è diventata parte del fondamento di qualsiasi prodotto con ambizione globale. In React e Next.js, l'ecosistema 2025 offre strumenti maturi, react-i18next, react-intl con ICU e LinguiJS, in grado di coprire qualsiasi cosa, dalla pluralizzazione avanzata alla formattazione sensibile alle impostazioni locali.

La differenza, però, raramente sta nella biblioteca scelta, ma nella disciplina dell’architettura: separare il contenuto dal codice, delegare le regole linguistiche a chi sa come gestirle e progettare il routing del linguaggio come un cittadino di prima classe. I team che considerano i18n come una decisione strategica fin dal primo impegno raggiungono nuovi mercati più velocemente e con meno rielaborazioni rispetto a quelli che lo lasciano in un secondo momento.