i18next VS @intlayer/i18next: Mesma API, Outro Bundle

@intlayer/i18next, @intlayer/react-i18next e @intlayer/next-i18next são adaptadores de compatibilidade. Eles expõem a API do i18next que seu código já utiliza (useTranslation, t(), <Trans>, i18n.changeLanguage(), getFixedT, serverSideTranslations...) e a fornecem a partir de dicionários compilados pelo Intlayer. Os componentes não mudam. O runtime abaixo deles sim.

Este artigo analisa essa substituição na mesma aplicação Next.js, construída uma vez com next-i18next e outra com @intlayer/next-i18next. Os dados são do Benchmark Bloom. Para comparar i18next e Intlayer como bibliotecas completas, leia i18next vs Intlayer. Este artigo se concentra no que o adaptador transforma quando você preserva seu código como está.

tl;dr: Na mesma aplicação Next.js, substituir next-i18next por @intlayer/next-i18next reduziu o JavaScript por página de 218.5 KB para 150.7 KB gzip (setup básico) e superou o setup do next-i18next totalmente otimizado (163.4 KB) em 12.7 KB. O componente médio caiu de 78.5 KB para 9.7 KB, o vazamento de strings para outras páginas foi de ~90% para 0%, a hidratação de 15.6 ms para 11.3 ms e o runtime de 19.7 KB para 9.4 KB. Nenhum componente foi editado; apenas um arquivo de provider foi ajustado. Plugins do i18next (backends, detectores de idioma) são aceitos mas não realizam nada: não há mais nada para carregar ou detectar em tempo de execução.

O que é o @intlayer/i18next

O i18next é um runtime. i18n.init({ resources }) ou um plugin de backend carrega locales/{lng}/{ns}.json em uma instância global; useTranslation("about") inscreve o componente nela; t("title") busca a chave no momento da renderização. Namespaces, carregamento sob demanda (lazy loading), listas de namespaces por página e segurança de tipos ficam sob sua responsabilidade de configuração e manutenção.

Os adaptadores preservam a API e substituem a instância:

1. Aliases de importação. createNextI18nPlugin() do @intlayer/next-i18next/plugin (ou withI18next) envolve o withIntlayer e cria aliases no Webpack / Turbopack para que next-i18next, react-i18next e i18next resolvam para os pacotes @intlayer/*. No Vite, o reactI18nextVitePlugin() do @intlayer/react-i18next/plugin tem o mesmo papel. Nenhuma importação precisa ser renomeada.
2. JSON como fonte de verdade. O plugin syncJSON lê seus arquivos existentes locales/{lng}/{ns}.json com format: "i18next" (garantindo que {{name}}, aninhamento $t(), _one / _other e sufixos de contexto sejam interpretados adequadamente) e regrava as traduções quando a CLI ou o CMS as atualizam.
3. Vinculação no ponto de chamada. A etapa de otimização do Intlayer reescreve useTranslation("about") em uma chamada que recebe o dicionário about diretamente, no idioma ativo. O componente deixa de acessar a store global.

// Seu código, inalterado
import { useTranslation } from "react-i18next";

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

import _dicHash_about from "../.intlayer/dictionaries/about.mjs";
import { useDictionary as useTranslation } from "@intlayer/react-i18next";

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

Essa transformação é a razão pela qual as colunas de tamanho de componente e vazamento de página caem drasticamente nos dados abaixo.

O que os adaptadores mantêm, ignoram e não substituem

O benchmark

O que foi medido

A suite Benchmark Bloom compila a mesma aplicação em cada ambiente: 10 páginas (home, about, blog, careers, contact, FAQ, pricing, products, settings, team), 10 locales (en, fr, es, de, it, pt, zh, ja, ko, ru), componentes idênticos e conteúdo idêntico. As páginas são avaliadas em en e fr.

O next-i18next foi configurado em quatro estratégias de carregamento, desde o JSON de cada idioma importado em resources (static) até um namespace por rota, carregado de forma diferida via backend (scoped-dynamic). O adaptador foi testado sobre os mesmos componentes do setup inicial, com alterações limitadas a next.config.ts, intlayer.config.ts e ao arquivo do provider. Ele não possui variante "scoped" manual: o compilador define o escopo do conteúdo por componente.

Para cada compilação, registram-se:

• Tamanho da lib: tamanho gzip de um componente vazio que apenas importa a biblioteca de i18n.
• JS por página: média de JavaScript gzip transferido por página em todas as rotas e locales.
• % de vazamento de locale: parcela de strings traduzidas no JS que pertence a um idioma que o usuário não está visualizando.
• % de vazamento de página: parcela de strings traduzidas no JS que pertence a uma página em que o usuário não está navegando.
• Média por componente: tamanho médio gzip de cada componente compilado de forma isolada.
• Reatividade E2E: intervalo de tempo real entre selecionar um novo idioma e a alteração de html[lang] no DOM (Playwright, 5 repetições).
• Hidratação: tempo de duração da fase de hidratação do React.

Os dados abaixo resultam da execução de 12/09/2026 com next-i18next 16.3.0 (react-i18next 17.0.13, i18next 26.4.2) e @intlayer/next-i18next 9.5.1. A aplicação de teste foi projetada com escopo enxuto propositalmente (algumas dezenas de strings por idioma), portanto os percentuais de vazamento ilustram um comportamento: expandem-se proporcionalmente ao crescimento do conteúdo enquanto o custo do runtime permanece estático.

Resultados no Next.js

Escolha as métricas e as bibliotecas que importam para você:

Como interpretar os dados

• 68 KB a menos por página em relação ao setup básico. resources: { en, fr, ... } despacha todos os idiomas e namespaces para cada rota: 218.5 KB. O build com o adaptador cai para 150.7 KB. Supera também a configuração mais elaborada do next-i18next (163.4 KB, namespace único por rota, carregado sob demanda) em 12.7 KB, pois a própria biblioteca i18next consome 19.7 KB contra 9.4 KB.
• O vazamento atinge 0% sem intervenção em componentes. Cada configuração do next-i18next, à exceção da modularizada manualmente, entrega ~90% de strings de rotas distintas. A linha dynamic é pior na prática do que aparenta: preserva o vazamento entre páginas e adiciona 50% de vazamento de idioma, dado que o backend busca todo o namespace translation do locale ativo. O adaptador estabelece 0% / 0% a partir do código original.
• Componentes: 8x mais enxutos. Um componente com useTranslation() isolado consome 78.5 KB com resources inlined e 26-27 KB com backend, já que t continua preso à store global. No adaptador, a média cai para 9.7 KB.
• Hidratação e alternância de idioma aceleradas. A hidratação cai de 15.6 ms para 11.3 ms (e de 27.7 ms no modo dynamic, no qual o carregamento do backend reside no caminho crítico). A troca de idioma cai de 15-16 ms para 11-12 ms.
• O adaptador é diferente do runtime nativo. O next-intlayer crava 141.3 KB, meros +0.3 KB acima do app sem i18n. O adaptador suporta as particularidades da API do i18next (expressões de interpolação, sufixos de plural e contexto, tags <Trans>) sobre o núcleo do Intlayer: 9.4 KB e +9.4 KB por página em relação ao nativo. Atua como transição, não como destino final.

Tabela completa, cada biblioteca e cada estratégia, no relatório de benchmark do Next.js.

Resultados no TanStack Start (react-i18next)

Para Vite e TanStack Start, o benchmark compara o react-i18next puro com o intlayer:

Tabela completa no relatório de benchmark do TanStack Start.

O adaptador react-i18next no Vite / TanStack Start não constou desta rodada de testes. A medição para react-i18next no TanStack Start pode ser verificada em i18next vs Intlayer: 127-184 KB por página e 123-185 ms na troca de idioma com backend sob demanda.

O motivo da mudança nos indicadores

Nenhum arquivo em components/ foi alterado, logo o ganho advém da entidade à qual useTranslation se acopla.

Com o i18next, a ligação é feita na instância global. Qualquer recurso alocado nela (todos os idiomas em static, o namespace completo do idioma ativo em dynamic) torna-se acessível para qualquer componente chamador de useTranslation(). O bundler não consegue fragmentar abaixo do volume contido na instância, e o runtime não é capaz de prever quais chaves serão demandadas em renderização.

.
├── next-i18next.config.js
├── public/locales
│   ├── en/translation.json           # strings de todas as páginas
│   └── fr/translation.json
├── i18n/i18n.ts                      # i18n.use(initReactI18next).init({ resources })
└── components
    ├── AppProviders.tsx              # <I18nextProvider i18n={i18n}>
    └── About.tsx                     # useTranslation(); t("about.title")

Tudo o que a instância contém é enviado para todas as páginas, e o desperdício cresce em dois eixos, páginas e idiomas:

Com o @intlayer/next-i18next, a ligação é feita diretamente com o dicionário. O plugin syncJSON transforma cada arquivo de namespace em um dicionário; o ciclo de otimização repassa ao componente apenas o dicionário declarado, na forma de import que o empacotador rastreia e separa por página e locale.

.
├── intlayer.config.ts                # syncJSON({ format: "i18next", source: ... })
├── public/locales
│   ├── en/translation.json           # inalterado, continua como fonte da verdade
│   └── fr/translation.json
├── .intlayer/                        # gerado: um dicionário por namespace, por locale
└── components
    ├── AppProviders.tsx              # <IntlayerClientProvider locale={locale}>
    └── About.tsx                     # useTranslation(); t("about.title")  ← inalterado

O arquivo i18n/i18n.ts e sua importação de resources tornam-se código inerte. É daí que procedem os 68 KB de alívio.

Migração em três etapas

1. 1

   Instalação

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npx intlayer init --interactive
   

   O comando identifica i18next / react-i18next / next-i18next, instala o intlayer, o pacote do framework (next-intlayer ou react-intlayer), o respectivo adaptador @intlayer/* e o @intlayer/sync-json-plugin, além de preencher o intlayer.config.ts. Conserve as dependências originais instaladas: elas operam como peer dependencies e entregam as tipagens.

2. 2

   Aponte o Intlayer para seus arquivos de tradução

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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: {
       importMode: "dynamic",
       format: "i18next",
     },
     plugins: [
       syncJSON({
         // dialeto i18next: {{name}}, $t(key), key_one / key_other, key_male
         format: "i18next",
         // Um arquivo por namespace: `useTranslation("about")` → about.json
         source: ({ locale, key }) => `./public/locales/${locale}/${key}.json`,
         location: "public/locales",
       }),
     ],
   };
   
   export default config;
   

   Caso você mantenha um único arquivo translation.json por locale (o namespace padrão do i18next), configure splitKeys: false para que o arquivo integral permaneça como um único dicionário e invocações diretas de useTranslation() prossigam sem falhas.

3. 3

   Adicione o plugin

   Next.jsVite / TanStack Start

   next.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

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

   No App Router, componentes de cliente identificam o idioma pelo segmento [locale]. O I18nextProvider do adaptador não aceita locale como propriedade, logo substitua-o uma única vez no arquivo de provider:

   components/AppProviders.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   "use client";
   
   import { IntlayerClientProvider } from "next-intlayer";
   import type { LocalesValues } from "intlayer";
   
   export const AppProviders = ({
     locale,
     children,
   }: {
     locale: LocalesValues;
     children: React.ReactNode;
   }) => (
     <IntlayerClientProvider locale={locale}>{children}</IntlayerClientProvider>
   );
   

   Todos os componentes abaixo continuam invocando useTranslation().

   vite.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react";
   import { reactI18nextVitePlugin } from "@intlayer/react-i18next/plugin";
   
   export default defineConfig({
     plugins: [react(), reactI18nextVitePlugin()],
   });
   

   O reactI18nextVitePlugin() encapsula o vite-intlayer e define os aliases para react-i18next e i18next. Para projetos sem React, i18nextVitePlugin() do @intlayer/i18next/plugin provê o alias somente para i18next.

O que você pode remover em seguida

O que você ganha além da redução em bytes

• Tipagem estrita de chaves. useTranslation("about") valida chaves contra o dicionário about compilado; t("does.not.exist") gera um erro do compilador TypeScript em vez de retornar a string crua.
• npx intlayer test bloqueia a integração contínua (CI) se faltar qualquer tradução em qualquer idioma. npx intlayer fill traduz pendências com sua própria chave de provedor (OpenAI, Anthropic, Mistral, Gemini...) e as salva em locales/{lng}/{ns}.json.
• Editor Visual e CMS atuam diretamente no mesmo JSON, permitindo que editores atualizem textos por interface gráfica enquanto os arquivos Git são versionados.
• Migração gradual para .content.ts. Cada componente pode migrar de useTranslation("about") para useIntlayer("about") adotando um arquivo de conteúdo co-localizado. Dicionários JSON e .content.ts operam juntos harmonicamente.

Limitações importantes antes de iniciar

Comparação de funcionalidades

Além dos bytes, o que cada opção oferece:

Os tamanhos de runtime vêm da execução em Next.js descrita acima.

Quando utilizar cada alternativa?

FAQ

Comparações relacionadas

Mesma série de adaptadores:

Bibliotecas comparadas diretamente:

Documentação de referência:

Compat adapters:

Migration guides:

Para entender de onde vêm essas bibliotecas, leia a história do i18n em JavaScript.

Conclusão

O i18next figura como o runtime mais pesado deste benchmark, e os adaptadores cortam a maior parte dessa carga sem exigir que você abandone sua API habitual. Na mesma aplicação Next.js, isso representa 68 KB a menos por página comparado à configuração inicial, 12.7 KB a menos em relação à opção mais otimizada manualmente, componentes 8x mais leves, 0% de vazamento e 4 ms a menos de hidratação, demandando apenas um arquivo de configuração, uma inclusão de plugin e um ajuste no provider. Backends e detectores tornam-se inócuos, resources é descartado ao invés de incorporado, e a implementação nativa do next-intlayer preserva outros 9 KB de leveza adicional.

A totalidade dos dados brutos, aplicações de teste e scripts encontra-se publicada no repositório do Benchmark Bloom.

Consulte o documento Por que Intlayer? para aprofundar.