Como escolher a biblioteca de i18n certa para React

O React não inclui nenhuma primitiva de i18n. A biblioteca que você escolhe no primeiro dia decide como as traduções são armazenadas, como elas chegam ao bundle e quanto trabalho continuará sendo seu nos próximos anos. A maioria das equipes escolhe pela popularidade e depois descobre os trade-offs quando atinge 2.000 chaves.

Este guia segue o caminho inverso: responda a algumas perguntas sobre o seu projeto primeiro e, em seguida, mapeie as respostas para as bibliotecas mais adequadas. O foco aqui é o React puro (Vite, React Router, TanStack Start). O Next.js tem suas próprias restrições, abordadas na comparação para Next.js.

Índice

Seis perguntas a responder antes de comparar bibliotecas

Uma tabela de recursos é inútil sem saber quais linhas importam para você. Analise estes pontos primeiro.

1. Como a aplicação é renderizada? Apenas SPA, SSR com hidratação ou React Server Components. Hooks baseados em context funcionam em qualquer lugar em uma SPA. Com RSC, um hook força "use client" em todos os componentes que renderizam texto, portanto você também precisará de uma API no lado do servidor.
2. Quem escreve as traduções? Desenvolvedores, uma equipe interna usando um TMS, uma agência entregando arquivos ICU ou um pipeline de IA. Isso dita o formato do catálogo mais do que qualquer detalhe de API.
3. Quantos locales e páginas? Dois locales e cinco páginas podem se dar ao luxo de enviar tudo. Dez locales e cinquenta rotas não podem, e a estratégia de carregamento se torna o custo principal.
4. Você precisa de tipos nas chaves? Um erro de digitação em t("checkout.totl") compila em qualquer biblioteca baseada em chaves, a menos que você mesmo configure os tipos. Decida se isso é aceitável.
5. O que a string contém? Texto simples, plurais ou frases com um <Link> no meio. Conteúdo rico é onde a maioria das APIs se torna complicada.
6. Quanto tempo o projeto vai durar? Um protótipo de três meses e um produto de cinco anos não precisam da mesma quantidade de build tooling.

Anote as respostas. Tudo o que segue faz referência a elas.

O panorama geral em uma imagem

Quinze anos de JavaScript i18n cabem em quatro ondas arquiteturais, e as bibliotecas React que você vai comparar vêm de ondas diferentes.

A história do JavaScript i18n detalha como cada onda respondeu aos problemas da anterior.

A decisão que mais importa: onde o conteúdo fica e quando ele carrega

Toda biblioteca de i18n para React tem o mesmo formato: uma store, um provider, um hook. O que o provider recebe acaba no bundle do cliente ou no payload de hidratação. Portanto, as duas escolhas estruturais são:

• Conteúdo centralizado ou com escopo. Um en.json para a aplicação inteira, ou uma declaração por componente (ou por namespace).
• Import estático ou dinâmico. Tudo empacotado na inicialização, ou o locale e a rota ativos buscados sob demanda.

O gráfico abaixo estima o payload para uma aplicação teórica de 1 a 10 páginas, traduzida para 1 a 10 locales, com cerca de 30 KB de texto por página.

Conteúdo centralizado com imports estáticos cresce em ambos os eixos: 10 páginas vezes 10 locales representam 300 KB de texto em cada página. Imports dinâmicos removem o eixo dos locales. O escopo por componente remove o eixo das páginas. Apenas a combinação de ambos mantém o tamanho estável.

Isso não é uma propriedade da biblioteca, é uma propriedade de disciplina. O react-i18next pode ter escopo com namespaces e backends lazy. O use-intl pode ser dividido por rota. Mas nada impõe isso, e um <Button> compartilhado acessando t("common:cta") silenciosamente torna o common uma dependência de todas as rotas. O benchmark mede isso como "vazamento de outras rotas" e "vazamento de outros locales", e é de onde vem a maior parte da diferença entre as bibliotecas.

Se a sua resposta para a pergunta 3 foi "muitos locales, muitas páginas", dê mais peso a esta seção do que a qualquer preferência de API. O artigo sobre i18n por componente vs. centralizado aprofunda o lado da manutenção dessa mesma escolha.

Os candidatos

Os tamanhos das bibliotecas vêm do benchmark no TanStack Start: provider mais hook em um componente vazio, após bundling, tree-shaking e minificação, 10 páginas e 10 locales. O conteúdo é medido separadamente.

Os números são um snapshot das versões do benchmark e mudam com novos lançamentos. Execute o benchmark na sua própria aplicação antes de decidir apenas pelo tamanho.

Duas coisas que a tabela não mostra. O Paraglide quase não envia biblioteca porque gera código dentro do seu repositório, o que significa uma etapa de regeneração antes de cada commit e conflitos de merge em arquivos gerados. E o Intlayer requer um plugin de bundler (vite-intlayer ou equivalente), portanto não pode rodar em uma configuração sem build.

Mapeie suas respostas para uma biblioteca

Onde cada biblioteca deixa a desejar

Limites honestos, já que todas as opções têm os seus.

• react-i18next: a mais pesada do conjunto, formato de plural próprio, tipagem depende da sua própria configuração manual, chaves sem uso acumulam-se silenciosamente.
• react-intl: DX verbosa (useIntl() e depois formatMessage({ id })), instância global vinculada a muitos nós.
• use-intl: simples para começar, difícil de otimizar. Namespaces, carregamento dinâmico e tipagem juntos tornam o desenvolvimento bem mais lento.
• Lingui: etapa extra de build com extract / compile, várias sintaxes sobrepostas (t(), tagged template, i18n.t(), <Trans>) que confundem desenvolvedores e assistentes de IA.
• Paraglide: arquivos gerados no repositório, o tree-shaking não surtiu efeito no benchmark React, e o locale é lido do storage a cada nó em vez de vir de uma store.
• Tolgee: sem tipos nas chaves, onboarding mais difícil, edição em contexto é o principal diferencial.
• Intlayer: plugin de build obrigatório, ecossistema menor, suporte parcial a ICU, conteúdo distribuído pela codebase por design, logo exportar um único JSON para um tradutor exige ferramentas.
• gt-react, lingo.dev: não recomendadas no benchmark: erros de cota no build, vendor lock-in e problemas de reatividade que exigiram forçar re-renderizações do provider.

Como cada opção se parece no código

O mesmo componente, um resumo de carrinho com título e plural, escrito com cada candidata. A parte interessante não é o componente em si, mas onde o conteúdo fica e o que o verificador de tipos sabe sobre ele.

{
  "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({
      pt: "Seu carrinho",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      pt: plural({ one: "{{count}} item", other: "{{count}} itens" }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", 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>
  );
};

Já usa react-i18next, react-intl ou Lingui? Os adaptadores de compatibilidade (react-i18next, react-intl, Lingui) criam aliases para os imports no nível do bundler para que a API existente continue funcionando enquanto você migra componente por componente. O guia de migração cobre o restante.

Antes de tomar sua decisão

Uma tabela de funcionalidades mostra o que uma biblioteca faz hoje. Estes pontos mostram como será a convivência com ela no dia a dia.

Verifique a atividade do repositório.

Commits, tempo de resposta a issues e se a última versão minor foi lançada este ano. Um bom design sem mantenedores é uma migração à espera de acontecer.

Não escolha pelo número de downloads no npm.

A biblioteca mais instalada é a que foi lançada primeiro, não a que melhor se adapta a uma codebase React em 2026. Downloads medem história, não adequação.

Pergunte quem financia o mantenedor e o que eles vendem.

O i18next é apoiado pela Locize. O next-intl / use-intl, vue-i18n, svelte-i18n e Lingui são apoiados pelo Crowdin. Tolgee, Paraglide (inlang) e Intlayer mantêm suas próprias plataformas. Um fornecedor cuja receita depende de traduções hospedadas tem pouco incentivo para tornar a tradução gratuita dentro da sua cadeia de ferramentas. O Intlayer é o único do grupo que oferece tradução por IA via CLI com sua própria chave de API e um CMS que você pode auto-hospedar (self-host).

Está pronto para agentes de IA?

Os agentes ainda têm dificuldades com i18n: esquecem locales, inventam chaves e misturam sintaxes de mensagens. A biblioteca oferece Agent Skills ou um servidor MCP para que o agente possa listar, preencher e testar conteúdo? E o carregamento de conteúdo é otimizado por padrão, ou alguém precisa revisar namespaces e lazy imports a cada trimestre?

Type safety pronto para uso.

Não "pode ser tipado com configuração extra", mas "uma chave errada falha no tsc em uma instalação nova". Verifique o que acontece com uma chave inexistente e com um locale que está com uma tradução faltando.

Detecção de conteúdo não utilizado.

Os catálogos só aumentam. O build do Intlayer purga campos não utilizados e registra logs (build.purge). O Paraglide atinge isso por arquitetura, já que uma função de mensagem não chamada sofre tree-shaking. Todas as outras deixam essa limpeza para você.

Experiência do desenvolvedor (DX).

Tempo de configuração até a primeira string traduzida, um LSP ou extensão para VS Code que mostra a tradução ao passar o cursor e navega até a declaração, uma CLI para preencher, testar e sincronizar (push), e uma forma para não-desenvolvedores editarem conteúdo (editor visual ou CMS) sem a necessidade de um pull request.

Perguntas Frequentes

Indo além

• Benchmark de bibliotecas de i18n: tamanho de bundle, vazamento e tempo de troca de locale e o relatório para TanStack Start
• React i18n: como funciona o modelo de provider e quanto ele custa
• react-i18next vs react-intl vs Intlayer, recurso por recurso
• next-i18next vs next-intl vs Intlayer
• A história do JavaScript i18n
• Compilador vs. i18n declarativo
• i18n por componente vs. centralizado
• Como funciona a otimização de bundle em tempo de build
• Configure i18n em uma aplicação Vite + React
• O mesmo guia para Vue, Svelte e Solid