@intlayer/docs 9.4.1 → 9.4.3

package/blog/pt/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Como testar traduções sem criar testes frágeis"
+description: O que vale a pena testar em uma aplicação i18n e o que não vale. Testes de renderização baseados em provider, pseudolocalização, cobertura de RTL e plurais, e a armadilha dos snapshots.
+keywords:
+  - testar traduções
+  - testes i18n
+  - testing library i18n
+  - pseudolocalização
+  - teste provider locale
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# Como testar traduções sem criar testes frágeis
+
+A maioria das suítes de testes de i18n falha por um de dois motivos. Ou fazem asserções sobre textos literais, fazendo com que qualquer alteração de redação quebre cinquenta testes e a equipe termine por deletá-los. Ou renderizam tudo no locale padrão, não provando nada sobre os outros dezessete. Ambos chegam ao mesmo destino, uma suíte na qual ninguém confia.
+
+## Sumário
+
+<TOC/>
+
+## Os padrões são independentes de biblioteca
+
+Cada padrão a seguir funciona em qualquer stack de i18n. Troque o provider por `I18nextProvider`, `NextIntlClientProvider` ou `IntlProvider` e os testes permanecerão idênticos, pois verificam a saída renderizada e não uma API de biblioteca específica.
+
+As ferramentas de cobertura também se adaptam: com o [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md) apontado para seus catálogos existentes, ou um [adaptador de compatibilidade](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/index.md) criando aliases para seus imports atuais, a asserção de cobertura é executada diretamente contra o JSON que você já possui.
+
+## Decida o que você realmente está testando
+
+Qualidade de tradução não se valida com teste de código. Nenhuma asserção é capaz de informar se o alemão soa natural, e fingir o contrário apenas enche sua suíte de strings hardcoded.
+
+O que vale a pena testar é mecânico:
+
+| Vale a pena testar                         | Não vale a pena testar           |
+| :----------------------------------------- | :------------------------------- |
+| Cada locale obrigatório possui valor       | Se a redação é elegante          |
+| O locale correto alcança o componente      | O texto exato de cada label      |
+| Plurais resolvem para cada categoria       | Se o tradutor fez bem o trabalho |
+| Locales RTL definem direção e espelhamento | Toda string em cada idioma       |
+| Datas e números formatados usam o locale   | A precisão interna de `Intl`     |
+
+A cobertura pertence a um teste orientado a dados, não aos seus testes de componentes. Isso é abordado em [detectar traduções ausentes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/detecting_missing_translations.md); este artigo trata do restante.
+
+## Renderize com um provider e consulte por papel (role)
+
+O padrão central consiste em montar o componente dentro de um provider de locale e consultar por role ou test id em vez de pelo texto.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("renderiza o cabeçalho do resumo em francês", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Consultar `getByRole("heading")` sobrevive a mudanças de texto. `getByText("Récapitulatif")` falha com qualquer alteração. Use o texto literal somente quando a própria string for o objeto do teste, o que é raro.
+
+Para atributos como `aria-label`, você precisa da string bruta e não de um nó renderizável. No React, as entradas de `useIntlayer` expõem um campo `.value` para essa finalidade.
+
+## Parametrize os testes entre os locales
+
+Um único corpo de teste executado para cada locale vale muito mais do que testes separados por idioma.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("renderiza sem recorrer à chave não traduzida", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // Uma chave renderizada indica falha na resolução.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("define a direção de texto correta", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+A primeira asserção traz um benefício genérico valioso: se uma chave falhar e a biblioteca renderizar a chave bruta, o DOM exibirá algo no formato `cart.summary.title`. Isso captura uma classe inteira de erros sem inspecionar uma única frase.
+
+## A pseudolocalização encontra o que os catálogos não veem
+
+Adicione um locale fictício que transforme cada texto, por exemplo alterando `Checkout` para `[!!! Çĥéçķöũţ !!!]`. Em seguida, renderize a página nessa linguagem.
+
+Qualquer texto que ainda apareça em inglês padrão está hardcoded no código, e nenhuma auditoria em catálogos consegue detectar isso, pois para as ferramentas essa string simplesmente não existe. Os colchetes cumprem uma segunda função: expandem o texto em cerca de 30 por cento, expondo quebras de layout antes mesmo de testar em alemão.
+
+Convém rodar isso em uma passagem visual ou end-to-end em vez de testes unitários, já que a falha é identificada visualmente.
+
+## Plurais exigem um teste por categoria, não por idioma
+
+Erros em plurais passam despercebidos porque o inglês possui apenas duas formas e a maioria dos desenvolvedores só testa essas. O polonês possui quatro, o árabe seis.
+
+```ts fileName="plural.test.ts"
+// O árabe cobre zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("quantidade %i", (count) => {
+  it("produz uma string não vazia em árabe", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Escolha quantidades que atinjam cada categoria CLDR para o idioma mais exigente em vez de testar apenas 1 e 2 em todos os lugares. O `Intl.PluralRules` informa em qual categoria um número se encaixa, permitindo deduzir os casos de teste com exatidão. Mais detalhes no [artigo sobre o formato de mensagens ICU](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/icu_message_format.md).
+
+## A armadilha dos snapshots
+
+Snapshots e i18n formam uma combinação perigosa. O snapshot de um componente localizado fixa todas as strings contidas nele: quando um tradutor corrige um erro no português, uma suíte verde fica vermelha, em um arquivo que nenhum revisor consegue avaliar adequadamente. Após a terceira ocorrência, alguém executa `-u` sem verificar o diff, e os snapshots perdem todo o sentido.
+
+Se quiser usar snapshots, capture-os apenas em um único locale e trate-os como verificação puramente estrutural. Tudo que for específico de um locale deve estar em asserções explícitas.
+
+## Teste a negociação do locale, não apenas a renderização
+
+O bug de i18n mais frequente em produção não é uma string ausente. É a escolha do locale incorreto: a URL indica `/fr/`, o cliente lê `navigator.language`, e ambos entram em conflito.
+
+Teste a ordem de resolução diretamente como uma função pura, separada de qualquer componente:
+
+```ts fileName="locale-resolution.test.ts"
+it("prioriza a URL em relação à preferência salva", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("usa o cabeçalho quando a URL não possui prefixo", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+Este é o teste de i18n de maior valor ausente na maioria dos projetos, e não requer nenhum DOM.
+
+## O que rodar e onde
+
+- **Unitários**: negociação de locale, formatadores, categorias de plural. Rápido, sem DOM.
+- **Componentes**: uma renderização com provider por locale, validando roles e a ausência de chaves brutas.
+- **Cobertura**: um teste orientado a dados que garanta a ausência de locales obrigatórios faltantes.
+- **Visual ou end-to-end**: verificação com pseudolocalização e uma página RTL, pois são falhas visuais.
+
+Mantenha os três primeiros na pipeline a cada commit. O último pode rodar em builds noturnos, poupando tempo em cada push.
+
+## Erros comuns
+
+- **Asserções em textos literais em toda parte.** Faz com que a suíte seja apagada em poucos meses.
+- **Tirar snapshots de componentes localizados.** Tradutores quebram o build e revisores aprovam no piloto automático.
+- **Testar somente o locale padrão.** O único locale que não tem como faltar.
+- **Testar apenas 1 e 2 para plurais.** Ignora todas as categorias que o inglês não contempla.
+- **Criar mocks da biblioteca de i18n.** Você passa a testar apenas se o seu mock retorna strings.
+- **Nunca testar a negociação.** A falha mais comum em produção e a mais simples de testar.
+
+## Para se aprofundar
+
+- [Testar seu conteúdo: auditoria CLI, API programática e asserções de UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/testing.md)
+- [Plugin ESLint: detecção de strings hardcoded e conteúdo não utilizado](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/eslint.md)
+- [Formatadores e utilitários de locale, incluindo `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/formatters.md)
+- [Relatórios de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/index.md)
+- [Adaptador de compatibilidade react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/compat/react-i18next.md)
+- [Como detectar traduções ausentes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/detecting_missing_translations.md)
+- [Formato de mensagem ICU: plurais, select e skeletons](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/icu_message_format.md)

package/blog/pt/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
@@ -191,8 +191,6 @@ export default config;
 
 Isso carregará todos os arquivos JSON no diretório `src` que correspondem ao padrão `{key}.i18n.json` e os carregará como dicionários do Intlayer.
 
----
-
 </Step>
 
 </Steps>

package/blog/pt/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
@@ -141,8 +141,6 @@ Se alterações forem feitas usando o CLI para traduzir o JSON, ou usando o CMS,
 
 Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [documentação do plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md).
 
----
-
 </Step>
 
 <Step number={3} title="Implementar traduções JSON por componente" isOptional={true}>
@@ -186,8 +184,6 @@ export default config;
 
 Isso irá carregar todos os arquivos JSON no diretório `src` que correspondem ao padrão `{key}.i18n.json` e carregá-los como dicionários do Intlayer.
 
----
-
 </Step>
 
 </Steps>

package/blog/pt/intlayer_with_next-intl.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.

package/blog/pt/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.

package/blog/pt/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.

package/blog/pt/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
@@ -143,8 +143,6 @@ Se alterações forem feitas usando o CLI para traduzir o JSON, ou usando o CMS,
 
 Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [documentação do plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md).
 
----
-
 </Step>
 
 <Step number={3} title="Implementar traduções JSON por componente" isOptional={true}>
@@ -189,8 +187,6 @@ export default config;
 
 Isso carregará todos os arquivos JSON no diretório `src` que correspondem ao padrão `{key}.i18n.json` e os carregará como dicionários do Intlayer.
 
----
-
 </Step>
 
 </Steps>

package/blog/pt/is_i18next_outdated.md

@@ -0,0 +1,315 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: O i18next está obsoleto em 2026?
+description: O i18next alimenta milhões de sites, mas sua arquitetura em tempo de execução de 2011 começa a mostrar a idade. Uma análise sobre inchaço de bundle, limites de tree-shaking e estagnação.
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - Internacionalização
+  - i18n
+  - Tamanho do bundle
+  - Blog
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# O i18next está obsoleto em 2026?
+
+Lançado em 2011, muito antes de componentes React, empacotamento com Webpack ou TypeScript se tornarem padrão, o `i18next` dominou o ecossistema por ser flexível e onipresente, conquistando plugins para diversas stacks e respostas no StackOverflow para quase todo tipo de dúvida.
+
+O projeto não está abandonado, correções continuam sendo lançadas regularmente. No entanto, há uma diferença marcante entre manter um motor legado em funcionamento e evoluir ativamente com as arquiteturas frontend contemporâneas.
+
+Nos últimos anos, o frontend migrou para compilação em tempo de build, React Server Components (RSC), tree-shaking agressivo e fluxos potencializados por IA. O núcleo do i18next segue fiel ao que era há mais de uma década: um singleton em tempo de execução que resolve chaves de texto no cliente.
+
+<TOC/>
+
+## Principais conclusões
+
+**Modo de manutenção:**
+
+No último ano, o `next-i18next` registrou cerca de 63 commits (aproximadamente um por semana) e o `react-i18next` cerca de 157, a maioria voltada a atualizações de dependências e correções pontuais.
+
+**Penalidade pesada em runtime:**
+
+`react-i18next` e `next-i18next` injetam ~17–18 KB gzipped (~60 KB minificados) antes de renderizar qualquer palavra traduzida, quase 4x mais que o `next-intlayer` (~4.7 KB).
+
+**Vazamento severo de conteúdo:**
+
+Em configurações estáticas padrão, até **89.8%** dos dados de localização enviados para uma página pertencem a outras rotas ou a idiomas não visualizados.
+
+**Tree-shaking inviável:**
+
+Chamadas dinâmicas como `t("home.hero.title")` não podem ser analisadas por empacotadores, obrigando catálogos JSON inteiros a entrarem no chunk do cliente.
+
+**Incentivos comerciais:**
+
+Os mantenedores gerenciam o Locize. Criar uma esteira de tradução por IA local e sem custos diretamente na CLI concorreria com sua fonte primária de receita.
+
+## Manutenção vs. evolução ativa
+
+Estrelas no GitHub refletem adoção histórica em vez de fôlego arquitetural recente.
+
+| Repositório             | Estrelas                                                                                                                                                   | Total de commits                                                                                                                                                        | Commits / ano                                                                                                                                                          | Último commit                                                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+Atividade nos últimos doze meses:
+
+| Projeto         | Commits históricos | Últimos 12 meses | Foco                                       |
+| --------------- | ------------------ | ---------------- | ------------------------------------------ |
+| `next-i18next`  | 1.311              | **63**           | Compatibilidade com Next.js e correções    |
+| `react-i18next` | 1.988              | **157**          | Tipos e manutenção                         |
+| `i18next` core  | 2.626              | **259**          | Correções menores                          |
+| Intlayer        | 7.156              | **4.343**        | Compilador, extensões de IDE e motor de IA |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+Uma biblioteca enxuta pode ser completa e estável. Contudo, o ferramental de i18n continua a se transformar: bundlers modernos eliminam conteúdo desnecessário em tempo de build, modelos de linguagem traduzem em CI e editores utilizam Language Servers (LSP) e agentes de IA. A dependência exclusiva de plugins em tempo de execução impede que o i18next acompanhe essa evolução.
+
+## Medindo o impacto no bundle
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Avaliado em build de produção com 10 rotas e 10 idiomas sob compressão gzip. Mais detalhes no [relatório de benchmark de i18n](https://intlayer.org/pt/doc/benchmark).
+
+### Sobrecarga base da biblioteca
+
+Tamanho inicial antes de adicionar qualquer texto traduzido:
+
+| Biblioteca             | Gzipped    | Minificado  |
+| ---------------------- | ---------- | ----------- |
+| `next-i18next@16.0.5`  | 17.8 KB    | 61.2 KB     |
+| `react-i18next@17.0.2` | 17.3 KB    | 59.8 KB     |
+| `intlayer@8.7.12`      | **4.7 KB** | **12.8 KB** |
+
+### Peso de página e vazamento de dados
+
+Testado em React / TanStack Start (estratégia estática):
+
+| Biblioteca            | JS médio / pág (gz) | Vazamento idioma | Vazamento outras págs | Componente médio (gz) | Hidratação  |
+| --------------------- | ------------------- | ---------------- | --------------------- | --------------------- | ----------- |
+| `react-i18next`       | 180.3 KB            | **50.0%**        | **89.8%**             | 24.3 KB               | 85.1 ms     |
+| Intlayer              | **127.8 KB**        | 50.0%            | **0.8%**              | **7.1 KB**            | **24.1 ms** |
+| Intlayer (scoped dyn) | **118.1 KB**        | **0.0%**         | **0.8%**              | **4.6 KB**            | 23.7 ms     |
+
+No Next.js:
+
+| Biblioteca      | JS médio / pág (gz) | Vazamento outras págs | Componente médio (gz) |
+| --------------- | ------------------- | --------------------- | --------------------- |
+| Base (sem i18n) | 150.8 KB            | 0.0%                  | 0.7 KB                |
+| `next-i18next`  | **227.5 KB**        | **89.8%**             | 24.5 KB               |
+| `next-intlayer` | **152.1 KB**        | **0.0%**              | **7.2 KB**            |
+
+### Principais constatações
+
+**Peso de página:**
+
+No Next.js, o `next-i18next` adiciona **76.7 KB gzipped** em relação ao projeto base (+50%). O `next-intlayer` acrescenta apenas 1.3 KB.
+
+**Vazamento de traduções:**
+
+Por padrão, cerca de **90% dos textos carregados** em uma rota pertencem a outras páginas. A divisão manual de namespaces é desgastante e vulnerável a omissões.
+
+**Tempo de hidratação:**
+
+Componentes com `react-i18next` levaram **85 ms** para hidratar, contra **24 ms** no Intlayer. Repassar grandes estruturas JSON aos componentes atrasa a interatividade.
+
+## Por que o i18next é pesado?
+
+### Acúmulo de funcionalidades em tempo de execução
+
+Executar integralmente no navegador requer enviar todos os módulos previamente: interpolação, regras plurais, contextos, registros de formatação e barramentos de eventos. Até mesmo a troca de uma frase simples carrega todo o motor.
+
+### Chaves dinâmicas inviabilizam o tree-shaking
+
+Como `"hero.title"` é interpretada dinamicamente em runtime, os bundlers não têm como saber quais textos são acessados. Textos não utilizados acabam permanecendo nos pacotes do cliente.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+O [compilador do Intlayer](https://intlayer.org/pt/doc/compiler) identifica o que `Hero.tsx` realmente utiliza e remove propriedades não referenciadas antes de emitir os bundles do cliente. Veja [otimização de bundle](https://intlayer.org/pt/doc/concept/bundle-optimization) para mais esclarecimentos.
+
+## Experiência do desenvolvedor
+
+### Arquivos JSON desconexos vs. co-localização
+
+Com o i18next, as traduções ficam isoladas em diretórios JSON separados do código. O Intlayer reúne as declarações de conteúdo junto aos componentes:
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/pt/hero.json"
+{
+  "title": "Lance em todos os idiomas"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      pt: "Lance em todos os idiomas",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+Ao mover ou excluir `Hero.tsx`, seus arquivos de conteúdo acompanham o componente.
+
+### Autocompletar vs. segurança estrita de tipos
+
+Estender `CustomTypeOptions` concede autocompletar no editor, mas não valida a integridade das traduções. Excluir uma chave de `pt/home.json` não causa falha no build, gerando apenas um fallback em tempo de execução.
+
+O Intlayer infere os tipos a partir das próprias declarações, e o [`strictMode`](https://intlayer.org/pt/doc/concept/configuration) faz com que traduções faltantes interrompam o build com erros claros.
+
+### Comparativo de ferramentas
+
+| Funcionalidade             | Ecossistema i18next | Intlayer                                                                |
+| -------------------------- | ------------------- | ----------------------------------------------------------------------- |
+| **Extensão VS Code**       | Somente terceiros   | ✅ [Extensão oficial](https://intlayer.org/pt/doc/vs-code-extension)    |
+| **Language Server (LSP)**  | ❌ Nenhum           | ✅ [LSP dedicado](https://intlayer.org/pt/doc/lsp)                      |
+| **Servidor MCP (para IA)** | ❌ Nenhum           | ✅ [Servidor MCP embutido](https://intlayer.org/pt/doc/mcp-server)      |
+| **Habilidades de Agente**  | ❌ Nenhuma          | ✅ [Skills prontas](https://intlayer.org/pt/doc/agent_skills)           |
+| **CMS Visual em contexto** | Locize (SaaS pago)  | ✅ [Gratuito & Open Source](https://intlayer.org/pt/doc/concept/editor) |
+
+## A tradução e o modelo do Locize
+
+O Locize é a solução comercial mantida pelos mesmos criadores do i18next. Sustentar projetos abertos é fundamental, mas esse arranjo gera incentivos divergentes: uma biblioteca cuja renda depende de uma plataforma SaaS de tradução tem pouco interesse em oferecer uma solução gratuita de tradução local por IA na CLI.
+
+O Intlayer apoia um formato aberto:
+
+- [`intlayer fill`](https://intlayer.org/pt/doc/concept/auto-fill) preenche traduções pendentes no terminal ou em pipelines de CI usando suas próprias chaves de API da OpenAI, Anthropic, Mistral ou Gemini.
+- O [CMS Intlayer](https://intlayer.org/pt/doc/concept/cms) é código aberto e pode ser hospedado via Docker Compose.
+- Compilador, CLI, editor e CMS são distribuídos sob a licença Apache 2.0.
+
+## Em quais cenários o i18next ainda faz sentido?
+
+<AccordionGroup>
+<Accordion header="Projetos legados estáveis">
+
+Se a aplicação opera com estabilidade e o tamanho do pacote não é um impedimento, migrar não se faz urgente.
+
+</Accordion>
+<Accordion header="Plataformas não convencionais">
+
+O amplo ecossistema de plugins do i18next contempla configurações particulares (Electron, jQuery legado, pontes nativas sob medida) fora do foco de compiladores modernos.
+
+</Accordion>
+<Accordion header="Extensa base comunitária">
+
+O histórico de discussões no StackOverflow e GitHub agiliza a solução de cenários atípicos.
+
+</Accordion>
+</AccordionGroup>
+
+## Como melhorar minha configuração atual do i18next?
+
+O Intlayer oferece pacotes de compatibilidade direta que preservam com exatidão as assinaturas de função das bibliotecas i18next (`i18next`, `react-i18next` e `next-i18next`). Não é necessário reescrever seus componentes para usufruir de uma arquitetura otimizada por compilador.
+
+A configuração é feita com um único comando:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+Essa CLI interativa:
+
+1. Instala o pacote de compatibilidade `@intlayer/i18next`.
+2. Configura aliases no empacotador para que suas importações habituais (`useTranslation`, `Trans`, `t`) apontem para o Intlayer, permitindo remover a biblioteca antiga do seu `package.json`.
+3. Ativa imediatamente o suporte a Language Server (LSP) no editor, a eliminação de código inútil no build (tree-shaking) e fluxos locais de tradução por IA.
+
+Para instruções passo a passo, explore nossos guias dedicados:
+
+- **Camadas de compatibilidade:** Mantenha a sintaxe existente com os adaptadores para [i18next](https://intlayer.org/pt/doc/compatibility/i18next), [react-i18next](https://intlayer.org/pt/doc/compatibility/react-i18next) e [next-i18next](https://intlayer.org/pt/doc/compatibility/next-i18next).
+- **Migração de catálogos:** Converta arquivos JSON em dicionários tipados com os guias: [a partir do i18next](https://intlayer.org/pt/doc/migration/i18next), [a partir do react-i18next](https://intlayer.org/pt/doc/migration/react-i18next) ou [a partir do next-i18next](https://intlayer.org/pt/doc/migration/next-i18next).
+- **Estratégia híbrida:** Mantenha o runtime do i18next enquanto [utiliza o Intlayer com o i18next](https://intlayer.org/pt/blog/intlayer-with-i18next) para tipar e traduzir catálogos automaticamente.
+
+Examine sua aplicação em produção com o [scanner de SEO para i18n gratuito](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Leituras recomendadas
+
+- [Benchmark Next.js i18n: avaliação detalhada de performance](https://intlayer.org/pt/doc/benchmark/nextjs)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/pt/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [O next-intl está obsoleto em 2026?](https://intlayer.org/pt/blog/is-next-intl-outdated)
+- [Arquitetura orientada a compilador vs i18n declarativa](https://intlayer.org/pt/blog/compiler-vs-declarative-i18n)