@intlayer/docs 9.5.6 → 9.5.8

package/blog/pt/lingui_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "Lingui vs Intlayer: Benchmark e Comparativo 2026"
 description: "Duas bibliotecas de i18n baseadas em compilador avaliadas no Next.js e TanStack Start. Tamanho do bundle, vazamento de conteúdo, tamanho dos componentes, hidratação, reatividade na troca de idioma e experiência do desenvolvedor."
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # Lingui VS Intlayer | Benchmark de Internacionalização (i18n) para React e Next.js
 
+![JavaScript i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 Lingui e Intlayer são as duas bibliotecas deste benchmark que utilizam um **compilador** em vez de operarem estritamente como um runtime. O Lingui extrai mensagens a partir de macros durante o build e compila catálogos por idioma. O Intlayer compila dicionários por componente e aplica tree-shaking por idioma. Na teoria, deveriam ser muito parecidos. Os números revelam onde eles se distanciam.
 
 Os dados são provenientes do [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), uma suíte de código aberto que constrói a mesma aplicação com cada biblioteca e afere o que o navegador efetivamente baixa e executa.
@@ -96,6 +98,10 @@ Para cada compilação, registram-se:
 
 ### Resultados no Next.js
 
+Escolha as métricas e bibliotecas do seu interesse:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Biblioteca          | Estratégia     | Lib size (gz) | Page JS méd (gz) | Vazamento idioma | Vazamento página | Componente méd (gz) | Reatividade E2E | Hidratação |
 | ------------------- | -------------- | ------------: | ---------------: | ---------------: | ---------------: | ------------------: | --------------: | ---------: |
 | **base** (sem i18n) | -              |        0,0 KB |         141,0 KB |             0,0% |             0,0% |              0,9 KB |         13,4 ms |    11,8 ms |
@@ -114,6 +120,15 @@ Para cada compilação, registram-se:
 - **O fallback do idioma de origem vaza por construção.** Mesmo nas configurações mais bem planejadas, **entre 3% e 15% das strings em inglês são enviadas nas páginas em francês**. As macros do Lingui guardam o texto fonte como salvaguarda, de modo que ele aterrissa no bundle. O Intlayer resolve fallbacks no build e entrega exclusivamente o idioma ativo.
 - **O tamanho dos componentes isolados dispara em `scoped-dynamic`.** Cada componente compilado isoladamente projeta uma média de **152,6 KB**, pois os catálogos das rotas permanecem alcançáveis pelos imports. O mesmo componente usando `useIntlayer()` registra uma média de **6,9 KB**.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Tabela completa, cada biblioteca e cada estratégia, no [relatório de benchmark do Next.js](https://intlayer.org/pt/doc/benchmark/nextjs).
+
 ### Resultados no TanStack Start
 
 | Biblioteca                  | Estratégia     | Lib size (gz) | Page JS méd (gz) | Vazamento idioma | Vazamento página | Componente méd (gz) | Reatividade E2E | Hidratação |
@@ -135,8 +150,19 @@ Para cada compilação, registram-se:
 - **A linha `static` do Intlayer já apresenta 0% de vazamento de página**, pois inclui unicamente os dicionários consumidos pelos componentes daquela tela. Uma única linha de configuração (`importMode: 'dynamic'`) extingue igualmente o vazamento de idioma.
 - **`@intlayer/lingui`** mantém a sintaxe das macros do Lingui consumindo dicionários do Intlayer. Ele cede um pouco no tamanho final da página (137 KB, devido à presença do runtime de macros) em troca de componentes muito mais leves (12,8 KB) e hidratação mais ágil. Uma excelente rota de transição.
 
+<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;"
+/>
+
+> Tabela completa no [relatório de benchmark do TanStack Start](https://intlayer.org/pt/doc/benchmark/tanstack).
+
 ## Qual é a origem desse contraste? Dois compiladores, duas unidades de trabalho
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Ambas as soluções utilizam um compilador. O divisor de águas é **o que** elas compilam.
 
 **O Lingui compila catálogos.** As macros espalhadas pelo seu código são recolhidas em um arquivo `.po` por idioma e compiladas em um módulo JS por idioma. A unidade central é o **idioma**. Dividir além disso, por rota ou por componente, pressupõe criar catálogos adicionais, configurar o `lingui.config.ts` para extrair cada pedaço separadamente e administrar o carregamento manualmente. A instância `I18n` é global; cada `useLingui()` subscreve o componente a ela.
@@ -176,7 +202,9 @@ Ambas as soluções utilizam um compilador. O divisor de águas é **o que** ela
             └── about.content.ts
 ```
 
-É por essa razão que o padrão `scoped-dynamic` é uma entrega nativa e automática do Intlayer, enquanto no Lingui constitui um projeto próprio de engenharia de configuração.
+É por essa razão que o padrão `scoped-dynamic` é uma entrega nativa e automática do Intlayer, enquanto no Lingui constitui um projeto próprio de engenharia de configuração. O abismo aumenta em dois eixos ao mesmo tempo, páginas e idiomas:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 > Para reproduzir as marcas da linha `dynamic`, defina `dictionary.importMode: 'dynamic'` no seu `intlayer.config.ts`. Acesse a [documentação sobre otimização de bundle](https://intlayer.org/pt/doc/concept/bundle-optimization).
 
@@ -184,7 +212,8 @@ Ambas as soluções utilizam um compilador. O divisor de águas é **o que** ela
 
 ### Configuração
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="lingui.config.ts"
 import { defineConfig } from "@lingui/cli";
@@ -215,7 +244,8 @@ export const loadCatalog = async (locale: string) => {
 
 Depois é necessário incluir `@lingui/babel-plugin-lingui-macro` (ou `@lingui/swc-plugin`) ao bundler, rodar `lingui extract` após alterar textos, rodar `lingui compile` antes do build e encapsular a aplicação em `<I18nProvider i18n={i18n}>`.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="intlayer.config.ts"
 import { type IntlayerConfig, Locales } from "intlayer";
@@ -232,9 +262,12 @@ export default config;
 
 Basta adicionar `intlayer()` ao seu `vite.config.ts` (ou `withIntlayer()` no `next.config.ts`) e envolver a árvore de renderização com `<IntlayerProvider>`. Sem etapas de extração ou compilação manuais: os dicionários são montados diretamente quando o empacotador roda.
 
+</Tab>
+</Tabs>
 ### Componente
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```tsx fileName="src/components/Counter.tsx"
 import { useState } from "react";
@@ -258,7 +291,8 @@ export const Counter = () => {
 
 O texto em inglês vive no próprio componente; a tradução em francês fica em `src/locales/fr/messages.po` sob um ID em hash após a execução de `lingui extract`. Esquecer de extrair ou compilar aciona silenciosamente a string em inglês como fallback.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -297,11 +331,14 @@ export const Counter = () => {
 
 Ambos os idiomas coexistem no mesmo arquivo ao lado do componente. Um valor de `fr` em falta gera erro no build; uma chave digitada de forma errada aciona o verificador de tipos do TypeScript na hora.
 
+</Tab>
+</Tabs>
 ### Fora dos componentes
 
 Metadados, funções de carregamento (loaders), funções de servidor: em qualquer ponto fora da árvore do React.
 
-**Lingui**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="Lingui" value="lingui">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { setupI18n } from "@lingui/core";
@@ -324,7 +361,8 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 
 Gera-se uma nova instância `I18n` por execução, faz-se a importação manual do catálogo específico e emprega-se `msg` + `i18n._()` em vez de `t`. Conforme registrado nas [notas do benchmark](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md), saber a hora exata de recorrer a `t`, `` t` ` ``, `i18n.t()`, `msg` ou `<Trans>` é reconhecidamente confuso.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/routes/$locale/about.tsx"
 import { getIntlayer } from "intlayer";
@@ -336,6 +374,9 @@ export const loader = async ({ params }: { params: { locale: string } }) => {
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## Mantenha as macros do Lingui, adote dicionários do Intlayer
 
 O `@intlayer/lingui` atua como um adaptador compatível para `@lingui/core` e `@lingui/react`. As macros continuam compilando normalmente; as chamadas resultantes para `i18n._()` passam a ser atendidas pelos dicionários do Intlayer, enquanto os plugins de sincronização `.po` sustentam seus catálogos originais como fonte da verdade. Plurais e condicionais ICU comportam-se com paridade absoluta.
@@ -353,16 +394,82 @@ Mantenha `@lingui/babel-plugin-lingui-macro` ou `@lingui/swc-plugin` no processo
 
 ## Qual ferramenta escolher?
 
-- **Escolha o Lingui** se você precisa do formato **ICU MessageFormat** com macros tipadas, seus tradutores trabalham em arquivos **`.po`** acoplados a sistemas TMS consolidados, sua equipe tem preferência por strings declaradas inline no JSX e domina o ciclo operacional de extração, compilação e divisão de catálogos. Seu peso em JavaScript por página é muito competitivo com lazy loading.
-- **Escolha o Intlayer** se você busca **conteúdo encapsulado por componente**, **TypeScript rigoroso**, **erros de compilação para chaves ausentes**, **tree-shaking e lazy loading automatizados sem esforço de configuração**, componentes leves, hidratação instantânea, alternância imediata de idiomas e suíte editorial nativa (Editor Visual, CMS, tradução por IA, servidor MCP). Uma escolha natural para aplicações modulares e design systems.
-- **Escolha o `@intlayer/lingui`** se você já opera sobre uma base de código em Lingui e quer evoluir para o modelo de dicionários do Intlayer de modo gradativo sem mexer nas macros.
+<AccordionGroup>
+<Accordion header="Escolha o Lingui">
+
+Você quer **ICU MessageFormat** com macros tipadas, seus tradutores trabalham em **`.po`** com um pipeline TMS existente, prefere strings de origem inline em JSX e sua equipe gerencia confortavelmente o fluxo de extração / compilação / divisão de catálogos. Seu JS por página é competitivo uma vez configurado o lazy loading.
+
+</Accordion>
+<Accordion header="Escolha o Intlayer">
+
+Você quer **conteúdo com escopo por componente**, **TypeScript rigoroso**, **erros de chaves ausentes em tempo de build**, **tree-shaking e lazy loading sem esforço**, componentes leves, hidratação rápida, troca instantânea de idioma e ferramentas editoriais integradas ([Editor Visual](https://intlayer.org/pt/doc/concept/editor), [CMS](https://intlayer.org/pt/doc/concept/cms), [tradução por IA](https://intlayer.org/pt/doc/concept/auto-fill), [servidor MCP](https://intlayer.org/pt/doc/mcp-server)). Especialmente relevante para bases de código modulares grandes e sistemas de design.
+
+</Accordion>
+<Accordion header="Escolha o @intlayer/lingui">
+
+Você já está no Lingui e quer migrar para os dicionários Intlayer gradualmente sem tocar nas macros. Seus catálogos `.po` permanecem a fonte da verdade através do [plugin de sincronização PO](https://intlayer.org/pt/doc/compatibility/lingui). Medido lado a lado em [Lingui vs @intlayer/lingui](https://intlayer.org/pt/blog/lingui-vs-intlayer-lingui).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="O Lingui também compila. Por que o resultado é tão diferente?">
+
+Porque a unidade de compilação difere. O Lingui compila **um catálogo por idioma**: tudo abaixo disso (catálogos por rota, lazy loading, exclusão do fallback do bundle) depende de configuração. O Intlayer compila **um dicionário por componente**, de modo que a divisão por rotas é resultado direto do build. É por isso que um componente Lingui compilado isoladamente pesa 58-153 KB contra 6-8 KB no Intlayer.
+
+</Question>
+
+<Question title="Por que o vazamento de idioma nunca chega a 0% com o Lingui?">
+
+As macros mantêm a mensagem de origem disponível como fallback em tempo de execução, então a string em inglês é enviada junto com a tradução. O benchmark mede **3-15% de strings `en` dentro de páginas `fr`** em cada configuração otimizada. O Intlayer resolve fallbacks no build e envia apenas o idioma ativo.
+
+</Question>
+
+<Question title="O JavaScript por página do Lingui é realmente competitivo?">
+
+Sim, e no TanStack Start vence por muito pouco: 115.2 KB no modo `dynamic` contra 118.6 KB do Intlayer. Catálogos compilados com IDs hasheados são compactos. O custo aparece em outros pontos: hidratação em 28-34 ms contra 11-14 ms, e uma troca de idioma de **42 ms** na configuração `scoped-dynamic`.
+
+</Question>
+
+<Question title="Preciso abrir mão das macros para migrar?">
+
+Não. O `@intlayer/lingui` mantém a compilação de `` t`...` ``, `<Trans>`, `msg`, `plural`, `select` e `selectOrdinal` como antes; apenas a resolução de `i18n._()` muda. Mantenha `@lingui/babel-plugin-lingui-macro` ou `@lingui/swc-plugin` no build. Veja a [documentação de compatibilidade do Lingui](https://intlayer.org/pt/doc/compatibility/lingui).
+
+</Question>
+
+<Question title="E quanto às etapas de extração e compilação?">
+
+Elas continuam para as macros e desaparecem para o conteúdo nativo do Intlayer. Dicionários `.content.ts` são gerados na execução do bundler, sem etapa separada de CLI, e [`intlayer test`](https://intlayer.org/pt/doc/concept/cli) falha no CI em caso de chave ausente em vez de usar silenciosamente a string de origem.
+
+</Question>
+
+</FAQ>
 
 ## Comparações correlatas
 
-- [next-intl vs Intlayer](https://intlayer.org/pt/blog/next-intl-vs-intlayer) (sob o mesmo benchmark)
-- [i18next vs Intlayer](https://intlayer.org/pt/blog/i18next-vs-intlayer) (sob o mesmo benchmark)
-- [vue-i18n vs Intlayer](https://intlayer.org/pt/blog/vue-i18n-vs-intlayer-benchmark) (sob o mesmo benchmark)
-- [Compilador vs i18n declarativo](https://intlayer.org/pt/blog/compiler-vs-declarative-i18n)
+Mesmo benchmark, outras bibliotecas:
+
+- [next-intl vs Intlayer](https://intlayer.org/pt/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/pt/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/pt/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/pt/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/pt/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Indo além:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/pt/blog/lingui-vs-intlayer-lingui), o adaptador medido na mesma aplicação
+- [Compiler-driven vs declarative i18n](https://intlayer.org/pt/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/pt/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/pt/blog/icu-message-format)
+
+Documentação de referência:
+
+- [Relatório de benchmark do Next.js](https://intlayer.org/pt/doc/benchmark/nextjs) e [relatório de benchmark do TanStack Start](https://intlayer.org/pt/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/pt/doc/compatibility/lingui)
+- [Otimização de bundle](https://intlayer.org/pt/doc/concept/bundle-optimization) e [o compilador Intlayer](https://intlayer.org/pt/doc/compiler)
 
 ## Estrelas no GitHub
 

package/blog/pt/next-intl_vs_intlayer-next-intl.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs @intlayer/next-intl: Mesma API, Bundle Diferente"
 description: O que muda quando as importações next-intl de um aplicativo Next.js são servidas pelo adaptador de compatibilidade @intlayer/next-intl. Tamanho do bundle, vazamento, tamanho do componente e hidratação medidos no mesmo código, além do que o adaptador mantém, ignora e não pode substituir.
 keywords:
@@ -26,6 +26,8 @@ author: aymericzip
 
 # next-intl VS @intlayer/next-intl | Mesma API, Bundle Diferente
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/next-intl` é um adaptador de compatibilidade: expõe a API `next-intl` (`useTranslations`, `getTranslations`, `useLocale`, `t.rich()`, plurais ICU, `NextIntlClientProvider`...) e a serve a partir de dicionários compilados pelo Intlayer. O código da aplicação não muda. O bundle muda.
 
 Este artigo compara os dois na mesma aplicação Next.js, construída uma vez com `next-intl` e outra com o adaptador. Os números vêm de [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), uma suite open-source que registra o que o navegador realmente baixa. Se você quiser a comparação `next-intl` vs Intlayer como bibliotecas, leia [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer). Este é sobre o que o adaptador muda quando você mantém seus componentes como estão.
@@ -109,6 +111,10 @@ Para cada build, a suite registra:
 
 ### Resultados no Next.js
 
+Escolha as métricas e bibliotecas do seu interesse:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Setup                     | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |   Hydration |
 | ------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ----------: |
 | **base** (sem i18n)       | -              |        0.0 KB |         141.0 KB |        0.0% |      0.0% |             0.9 KB |        13.4 ms |     11.8 ms |
@@ -129,6 +135,15 @@ Para cada build, a suite registra:
 - **Hidratação é 2 ms mais rápida** (12.8 vs 14.7 ms): não há objeto de mensagem para desserializar do payload RSC antes do React poder hidratar.
 - **O adapter não é o runtime nativo.** `next-intlayer` fica em **141.3 KB**, +0.3 KB sobre a app base, com um runtime de 5.5 KB. O adapter carrega a superfície de API do `next-intl` (`useFormatter`, `t.rich`, o resolver ICU) no topo do core do Intlayer, daí 8.0 KB e +6 KB por página. É a ponte, não o destino.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Tabela completa, cada biblioteca e cada estratégia, no [relatório de benchmark do Next.js](https://intlayer.org/pt/doc/benchmark/nextjs).
+
 ### Resultados em TanStack Start (`use-intl`)
 
 `use-intl` é o core agnóstico de framework do `next-intl`. Seu adapter, `@intlayer/use-intl`, segue o mesmo design com um plugin Vite (`@intlayer/use-intl/plugin`).
@@ -152,11 +167,24 @@ Para cada build, a suite registra:
 - **A alternância de locale é mais rápida.** As configurações otimizadas de `use-intl` levam **13-21 ms** para atualizar `html[lang]`; o adapter leva **4-9 ms**. Menos componentes são re-renderizados, e nada é re-selecionado de uma árvore de mensagens.
 - **`static` mantém cada locale.** A linha `static` do adapter mostra 49,7% de vazamento de locale, o mesmo que o Intlayer nativo em modo `static`: todos os locales são agrupados, apenas os dicionários da página. Uma linha de configuração (`importMode: 'dynamic'`) remove isso.
 
+<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;"
+/>
+
+> Tabela completa no [relatório de benchmark do TanStack Start](https://intlayer.org/pt/doc/benchmark/tanstack).
+
 ## Por que os números mudam
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Nada no componente mudou, então os ganhos vêm inteiramente do que `useTranslations` está vinculado.
 
-**Com `next-intl`**, a vinculação é o provedor. `NextIntlClientProvider` recebe o objeto `messages` inteiro para a localidade; cada `useTranslations("about")` lê a partir dele. O bundler vê um componente importando um hook que lê um contexto, e não pode saber que apenas a ramificação `about` é usada. As rotas abaixo compartilham o mesmo objeto de mensagens, então a coluna page-leak lê ~90% até você dividir o arquivo você mesmo.
+**Com `next-intl`**, a vinculação é o provedor. `NextIntlClientProvider` recebe o objeto `messages` inteiro para a localidade; cada `useTranslations("about")` lê a partir dele. O bundler vê um componente importando um hook que lê um contexto, e não pode saber que apenas a ramificação `about` é usada. As rotas abaixo compartilham o mesmo objeto de mensagens, então a coluna page-leak lê ~90% até você dividir o arquivo você mesmo, e o desperdício cresce em dois eixos ao mesmo tempo, páginas e idiomas:
+
+![Theoretical content leakage by architecture](https://github.com/aymericzip/intlayer/blob/main/docs/assets/theorical_content_leakage.webp?raw=true)
 
 ```bash
 .
@@ -280,25 +308,106 @@ export default withIntlayer(nextConfig);
 
 ## Limites a conhecer antes de começar
 
-- **Routing config move para `intlayer.config.ts`.** `createNavigation(routing)` e `createMiddleware(routing)` mantêm sua assinatura mas ignoram o argumento: locales, locale padrão e estratégia de prefixo vêm da config `routing` do Intlayer. Se você usa `pathnames` localizados do `next-intl` (`/about` → `/a-propos`), o adapter não interpola; o `routing.rewrite` do Intlayer cobre esse caso mas é uma mudança separada.
-- **`useTranslations()` sem namespace não é vinculado.** O passe de otimização precisa de um namespace estático para saber qual dicionário importar. Uma chamada simples ainda funciona, por meio de um registry de runtime que referencia cada dicionário, que é exatamente o vazamento que você estava tentando remover. Passe o namespace.
-- **O adaptador não é gratuito.** 8.0 KB de runtime versus 5.5 KB para `next-intlayer`, e +6-7 KB por página em relação ao build nativo. Isso é o custo da surface API do `next-intl`. Se você chegar ao ponto em que todos os componentes foram movidos para `useIntlayer`, descarte o adaptador.
-- **`messages`, `timeZone`, `now` no provider são ignorados.** Os formatadores são suportados pelo `Intl` nativo e apenas a locale influencia sua saída; se você depender de um fuso horário forçado ou um `now` fixo para datas estáveis em hidratação, trate isso no local da chamada.
+<AccordionGroup>
+<Accordion header="A configuração de roteamento se move para intlayer.config.ts">
+
+`createNavigation(routing)` e `createMiddleware(routing)` mantêm sua assinatura mas ignoram o argumento: idiomas, idioma padrão e estratégia de prefixo vêm da configuração `routing` do Intlayer. Se você usa os `pathnames` localizados do `next-intl` (`/about` para `/a-propos`), o adaptador não os interpola; o `routing.rewrite` do Intlayer cobre esse caso mas é uma mudança separada.
+
+</Accordion>
+<Accordion header="useTranslations() sem namespace não é vinculado">
+
+A etapa de otimização precisa de um namespace estático para saber qual dicionário importar. Uma chamada sem namespace ainda funciona através de um registro em tempo de execução que faz referência a cada dicionário, o que é exatamente o vazamento que você estava tentando remover. Passe o namespace.
+
+</Accordion>
+<Accordion header="O adaptador não é gratuito">
+
+8.0 KB de tempo de execução versus 5.5 KB para `next-intlayer`, e +6-7 KB por página em relação ao build nativo. Ele paga pela superfície de API do `next-intl`. Se você atingir o ponto em que cada componente foi migrado para `useIntlayer`, remova o adaptador.
+
+</Accordion>
+<Accordion header="messages, timeZone e now no provider são ignorados">
+
+Os formatadores são baseados no `Intl` nativo e apenas o idioma influencia sua saída. Se você depende de um fuso horário forçado ou de um `now` fixo para datas estáveis na hidratação, lide com isso no local da chamada. Veja [formatação de data, hora e número](https://intlayer.org/pt/blog/date-time-number-formatting-locales).
+
+</Accordion>
+</AccordionGroup>
 
 ## Quando usar qual?
 
-- **Mantenha-se em `next-intl`** se sua app é pequena, seu bundle não é uma preocupação, e seu time está confortável em gerenciar namespaces e `pick()` por página.
-- **Use `@intlayer/next-intl`** if you are on `next-intl` today and want the bundle, leakage and hydration gains, typed keys and the CLI / CMS tooling without a rewrite. This is the recommended entry point for any existing `next-intl` codebase.
-- **Go native (`next-intlayer`)** for new projects, or once the adapter has done its job. It is the lightest of the three (5.5 KB, +0.3 KB per page) and unlocks synchronous server components, per-component `.content.ts` files and the full feature set.
+<AccordionGroup>
+<Accordion header="Fique no next-intl">
+
+Seu aplicativo é pequeno, seu bundle não é uma preocupação e sua equipe lida bem gerenciando namespaces e `pick()` por página.
+
+</Accordion>
+<Accordion header="Use @intlayer/next-intl">
+
+Você já está no `next-intl` hoje e quer os ganhos de bundle, vazamento e hidratação, chaves tipadas e as ferramentas de CLI / CMS sem uma reescrita. Este é o ponto de entrada recomendado para qualquer base de código `next-intl` existente.
+
+</Accordion>
+<Accordion header="Vá para o nativo (next-intlayer)">
+
+Para novos projetos, ou assim que o adaptador tiver cumprido seu papel. É o mais leve dos três (5.5 KB, +0.3 KB por página) e desbloqueia componentes de servidor síncronos, arquivos `.content.ts` por componente e o conjunto completo de recursos. Comece com [Intlayer com Next.js](https://intlayer.org/pt/doc/environment/nextjs).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="O código da minha aplicação realmente permanece intocado?">
+
+No Next.js, sim para componentes: a compilação do benchmark alterou apenas `next.config.ts` e `intlayer.config.ts`. `getRequestConfig` em `src/i18n.ts`, a prop `messages` no provider e as chamadas `pick()` por página tornam-se código morto que você pode excluir depois.
+
+</Question>
+
+<Question title="O que acontece com as mensagens ICU?">
+
+Elas continuam funcionando. `t("key", { count })`, `t.rich()`, `t.markup()`, `select`, `selectordinal`, `#` e `{ts, date, long}` são resolvidos pelo resolvedor ICU do Intlayer. Veja [formato de mensagem ICU](https://intlayer.org/pt/blog/icu-message-format).
+
+</Question>
+
+<Question title="Por que o adaptador é mais pesado que o next-intlayer nativo?">
+
+Ele carrega a superfície da API do `next-intl` sobre o núcleo do Intlayer: `useFormatter`, `t.rich`, o resolvedor ICU, os helpers de navegação. Isso representa 8.0 KB contra 5.5 KB, e +6 KB por página. É a ponte, não o destino.
+
+</Question>
+
+<Question title="Posso migrar componente por componente?">
+
+Sim. Qualquer componente pode mudar de `useTranslations("about")` para `useIntlayer("about")` com um arquivo `.content.ts` colocalizado. Dicionários JSON e `.content.ts` coexistem e se fundem.
+
+</Question>
+
+<Question title="Os pathnames localizados funcionam?">
+
+Não através dos `pathnames` do `next-intl`: o adaptador os aceita para tipagem, mas não os interpola. Use em vez disso `routing.rewrite` do Intlayer, que emite os literais localizados no registro de tipos.
+
+</Question>
+
+</FAQ>
 
 ## Related comparisons
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (as bibliotecas, mesmo benchmark)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (mesma série de adapter)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (mesma série de adaptador)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n) (mesma série de adaptador)
-- [Guia de migração: next-intl para Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [Referência do adaptador de compatibilidade: next-intl](https://intlayer.org/doc/compatibility/next-intl)
+Mesma série de adaptadores:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/pt/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/pt/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/pt/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+As bibliotecas comparadas diretamente:
+
+- [next-intl vs Intlayer](https://intlayer.org/pt/blog/next-intl-vs-intlayer), mesmo benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/pt/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/pt/blog/is-next-intl-outdated)
+
+Documentação de referência:
+
+- [Compat adapter: next-intl](https://intlayer.org/pt/doc/compatibility/next-intl)
+- [Guia de migração: next-intl para Intlayer](https://intlayer.org/pt/doc/migration/next-intl)
+- [Relatório de benchmark do Next.js](https://intlayer.org/pt/doc/benchmark/nextjs) e [relatório de benchmark do TanStack Start](https://intlayer.org/pt/doc/benchmark/tanstack)
+- [Otimização de bundle](https://intlayer.org/pt/doc/concept/bundle-optimization) e [o compilador Intlayer](https://intlayer.org/pt/doc/compiler)
+- [Editor Visual](https://intlayer.org/pt/doc/concept/editor), [CMS](https://intlayer.org/pt/doc/concept/cms) e [tradução por IA](https://intlayer.org/pt/doc/concept/auto-fill)
 
 ## Conclusão