@intlayer/docs 9.5.6 → 9.5.7

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
 

package/blog/pt/next-intl_vs_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "next-intl vs Intlayer: Benchmark & Comparação 2026"
 description: Tamanho do bundle, vazamento de conteúdo, reatividade de alternância de locale e experiência do desenvolvedor medidos no Next.js e TanStack Start. Qual biblioteca i18n você deve escolher em 2026?
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # next-intl VS Intlayer | Benchmark de Internacionalização (i18n) do Next.js
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `next-intl` é a biblioteca i18n mais popular para Next.js. Intlayer é uma alternativa baseada em compilador e com escopo de componente. Ambas localizam uma aplicação App Router. A questão é quanto cada uma custa uma vez que a aplicação está compilada.
 
 Este artigo não é um tutorial. É uma comparação apoiada por números do [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), um conjunto de benchmark open-source que constrói a mesma aplicação com cada biblioteca e mede o que o navegador realmente faz download e executa.
@@ -96,6 +98,10 @@ Para cada build, a suite registra:
 
 ### Resultados no Next.js (App Router)
 
+Escolha as métricas e bibliotecas do seu interesse:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Library                        | 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 |
@@ -116,6 +122,15 @@ Para cada build, a suite registra:
 - **Tamanho do componente.** Um componente que chama `useTranslations()` compila para 21.8 KB em média; o mesmo componente com `useIntlayer()` compila para 6.9 KB. Na configuração `scoped-static`, os componentes `next-intl` saltam para 80.1 KB porque cada um internaliza seu catálogo de namespace.
 - **Reatividade e hidratação** estão no mesmo patamar para ambas as bibliotecas no Next.js (15-18 ms). Nenhuma delas é um gargalo aqui.
 
+<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 (`use-intl`)
 
 `use-intl` é o núcleo agnóstico de framework do `next-intl`. Mesma API, mesmo formato de mensagem. Comparar isso contra `intlayer` no TanStack Start remove as partes específicas do Next.js da equação.
@@ -139,8 +154,19 @@ Para cada build, a suite registra:
 - **O tamanho do componente é onde a arquitetura se manifesta**: 76-87 KB por componente com `use-intl` versus 6-8 KB com Intlayer. `useTranslations()` vincula cada componente à árvore de mensagens global; `useIntlayer()` vincula-o ao seu próprio dicionário.
 - **Mudança de locale** é 2x-4x mais rápida com Intlayer (3 ms vs 7-21 ms).
 
+<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 a diferença? Catálogos centralizados vs. dicionários compilados
 
+![Centralized catalogs versus per-component dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/assets/project_stucture_18n_vs_intlayer.png?raw=true)
+
 `next-intl` segue o modelo clássico: um JSON por locale, carregado em `getRequestConfig`, inserido em um `NextIntlClientProvider`, lido através de `t("namespace.key")`.
 
 ```bash
@@ -162,6 +188,10 @@ Para cada build, a suite registra:
 
 O runtime não consegue saber quais keys uma página usará, então o padrão seguro é enviar o catálogo completo. Otimizar significa **você** dividir o catálogo em namespaces, **você** decidir quais namespaces cada página precisa, e **você** manter esse mapeamento sincronizado conforme os componentes se movem. A linha `scoped-dynamic` do benchmark é a recompensa por esse trabalho, e a maioria das equipes nunca chega lá.
 
+O custo de não chegar lá 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)
+
 Intlayer inverte a responsabilidade. O conteúdo é declarado ao lado do componente:
 
 ```bash
@@ -189,7 +219,8 @@ No momento da compilação, o compilador (`@intlayer/swc` / `@intlayer/babel`) v
 
 ### Componente cliente
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```json fileName="messages/en.json"
 {
@@ -224,7 +255,8 @@ export const Counter = () => {
 
 > Lembrez-se de incluir o namespace `counter` nas mensagens passadas para `NextIntlClientProvider` em cada página que renderiza este componente.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```ts fileName="src/components/Counter/index.content.ts"
 import { t, type Dictionary } from "intlayer";
@@ -267,11 +299,14 @@ export const Counter = () => {
 
 Nada para registrar na página: o componente traz seu próprio conteúdo.
 
+</Tab>
+</Tabs>
 ### Componente de servidor síncrono
 
 Peças de design-system (navbar, footer, cards) são frequentemente componentes server renderizados como children de componentes client, então não podem ser `async`.
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 type ServerCounterProps = {
@@ -289,7 +324,8 @@ export const ServerCounter = ({ t, formattedCount }: ServerCounterProps) => (
 
 A página tem que `await getTranslations("counter")` e `await getFormatter()`, depois passar os resultados para baixo como props. O componente não é mais auto-contido.
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/components/ServerCounter.tsx"
 import { useIntlayer } from "next-intlayer/server";
@@ -308,9 +344,12 @@ export const ServerCounter = ({ count }: { count: number }) => {
 };
 ```
 
+</Tab>
+</Tabs>
 ### Metadados
 
-**next-intl**
+<Tabs defaultTab="intlayer" group="techno">
+<Tab label="next-intl" value="next-intl">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import type { Metadata } from "next";
@@ -343,7 +382,8 @@ export const generateMetadata = async ({
 };
 ```
 
-**Intlayer**
+</Tab>
+<Tab label="Intlayer" value="intlayer">
 
 ```tsx fileName="src/app/[locale]/about/page.tsx"
 import { getIntlayer, getMultilingualUrls } from "intlayer";
@@ -367,6 +407,9 @@ export const generateMetadata = async ({
 };
 ```
 
+</Tab>
+</Tabs>
+
 ## Mantenha a API do next-intl, obtenha a saída do Intlayer
 
 Você não precisa reescrever componentes para obter os números de benchmark acima. `@intlayer/next-intl` é um adaptador pronto para usar: mantém `useTranslations`, `getTranslations`, `useFormatter`, `t.rich()`, plurais ICU e os auxiliares `next-intl/navigation`, e os fornece a partir dos dicionários compilados do Intlayer pelo compilador Intlayer.
@@ -388,17 +431,84 @@ Veja o [guia de migração next-intl](https://intlayer.org/doc/migration/next-in
 
 ## Quando escolher qual?
 
-- **Escolha next-intl** se você quer o padrão de ecossistema para Next.js, depende de ICU MessageFormat, sua aplicação é pequena a média, ou você se integra com uma plataforma de tradução (Crowdin, Phrase, Lokalise...) que espera JSON centralizado. Considere o tempo para namespace de catálogos e selecione mensagens por página se o desempenho importa.
-- **Escolha Intlayer** se você quer **conteúdo com escopo de componente**, **TypeScript rigoroso**, **erros de chaves ausentes em tempo de build**, **tree-shaking e lazy loading sem esforço**, componentes de servidor síncronos, e ferramentas editoriais integradas (Visual Editor, CMS, tradução com IA, servidor MCP). Especialmente relevante para codebases grandes e modulares e design systems.
-- **Escolha `@intlayer/next-intl`** se você já está usando `next-intl` e quer ganhos de bundle sem uma reescrita.
+<AccordionGroup>
+<Accordion header="Escolha o next-intl">
+
+Você quer o padrão do ecossistema para Next.js, depende do formato ICU MessageFormat, seu aplicativo é de porte pequeno a médio, ou você integra com uma plataforma de tradução (Crowdin, Phrase, Lokalise...) que espera JSON centralizado. Reserve tempo para estruturar catálogos por namespace e selecionar mensagens com `pick()` por página se o desempenho for essencial.
+
+</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 de servidor síncronos 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/next-intl">
+
+Você já está usando o `next-intl` e quer os ganhos de tamanho de bundle sem uma reescrita completa. O [adaptador de compatibilidade](https://intlayer.org/pt/doc/compatibility/next-intl) mantém seus imports e seu arquivo `messages/{locale}.json` como a fonte da verdade. Medido lado a lado em [next-intl vs @intlayer/next-intl](https://intlayer.org/pt/blog/next-intl-vs-intlayer-next-intl).
+
+</Accordion>
+</AccordionGroup>
+
+## FAQ
+
+<FAQ>
+
+<Question title="O next-intl é mais lento que o Intlayer?">
+
+Não no momento da renderização. A diferença está no que é enviado ao cliente: o `next-intl` custa **+12.6 KB gzip** de runtime em cada página e, na maioria das configurações comuns, envia cerca de 90% das strings de páginas estrangeiras em cada página. A troca de idioma e a hidratação são comparáveis no Next.js (15-18 ms); no TanStack Start, o `use-intl` leva de 7 a 21 ms contra 3 a 4 ms do Intlayer.
+
+</Question>
+
+<Question title="Consigo atingir 0% de vazamento com o next-intl?">
+
+Sim, com a configuração `scoped-dynamic`: divida `messages/{locale}.json` em um namespace por rota, depois use `pick(messages, [...])` em cada página e mantenha esse mapeamento correto conforme os componentes mudam. As linhas `scoped-*` do benchmark representam exatamente esse esforço. O Intlayer atinge 0% por padrão sem nada disso, pois o compilador delimita o conteúdo por componente. Veja [otimização de bundle](https://intlayer.org/pt/doc/concept/bundle-optimization).
+
+</Question>
+
+<Question title="Preciso reescrever meus componentes para migrar?">
+
+Não. O `@intlayer/next-intl` mantém `useTranslations`, `getTranslations`, `useFormatter`, `t.rich()`, plurais ICU e os helpers de navegação, servindo-os a partir de dicionários compilados. Apenas uma linha de plugin no `next.config.ts`. Passo a passo no [guia de migração do next-intl](https://intlayer.org/pt/doc/migration/next-intl).
+
+</Question>
+
+<Question title="O Intlayer suporta ICU MessageFormat?">
+
+O suporte a ICU está em desenvolvimento na API nativa. Os adaptadores de compatibilidade (`@intlayer/next-intl`, `@intlayer/use-intl`) executam o ICU: plurais, `select`, `selectordinal`, `#` e `{ts, date, long}` passam pelo resolvedor ICU do Intlayer. Leia [formato de mensagem ICU](https://intlayer.org/pt/blog/icu-message-format) para mais detalhes.
+
+</Question>
+
+<Question title="Posso manter meus arquivos messages/{locale}.json?">
+
+Sim. O [plugin de sincronização JSON](https://intlayer.org/pt/doc/compatibility/next-intl) lê os arquivos, divide as chaves principais em dicionários e regrava as traduções nos mesmos arquivos quando a CLI ou o CMS os atualiza. O fluxo de trabalho de seus tradutores não muda.
+
+</Question>
+
+</FAQ>
 
 ## Comparações relacionadas
 
-- [i18next vs Intlayer](https://intlayer.org/blog/i18next-vs-intlayer) (mesmo benchmark)
-- [Lingui vs Intlayer](https://intlayer.org/blog/lingui-vs-intlayer) (mesmo benchmark)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (mesmo benchmark)
-- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer)
-- [next-intl está desatualizado?](https://intlayer.org/blog/is-next-intl-outdated)
+Mesmo benchmark, outras bibliotecas:
+
+- [i18next vs Intlayer](https://intlayer.org/pt/blog/i18next-vs-intlayer)
+- [Lingui vs Intlayer](https://intlayer.org/pt/blog/lingui-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 com next-intl:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/pt/blog/next-intl-vs-intlayer-next-intl), o adaptador medido no mesmo aplicativo
+- [Is next-intl outdated?](https://intlayer.org/pt/blog/is-next-intl-outdated)
+- [Using Intlayer with next-intl](https://intlayer.org/pt/blog/intlayer-with-next-intl)
+- [How to internationalize a Next.js app with next-intl](https://intlayer.org/pt/blog/nextjs-internationalization-using-next-intl)
+
+Documentos 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)
+- [Adaptador de compatibilidade: next-intl](https://intlayer.org/pt/doc/compatibility/next-intl) e [guia de migração](https://intlayer.org/pt/doc/migration/next-intl)
+- [Otimização de bundle](https://intlayer.org/pt/doc/concept/bundle-optimization) e [o compilador Intlayer](https://intlayer.org/pt/doc/compiler)
+- [i18n por componente vs centralizada](https://intlayer.org/pt/blog/per-component-vs-centralized-i18n)
+- [i18n orientada a compilador vs declarativa](https://intlayer.org/pt/blog/compiler-vs-declarative-i18n)
 
 ## GitHub STARs
 
@@ -409,3 +519,9 @@ As estrelas do GitHub são um forte indicador de popularidade de um projeto, con
 ## Conclusão
 
 `next-intl` é uma biblioteca sólida e bem mantida, e o benchmark confirma que está longe de ser a pior opção no Next.js. Mas seu modelo de catálogo centralizado coloca cada otimização nas mãos do desenvolvedor: a configuração ingênua vaza ~90% do conteúdo de páginas estrangeiras, e o runtime sozinho custa +12.6 KB gzip em cada página.
+
+Intlayer move esse trabalho para o compilador. Dicionários por componente, lazy loading por idioma e eliminação de conteúdo não utilizado são saídas da compilação, não convenções manuais. O resultado na mesma aplicação: **+0.3 KB por página**, **0% de vazamento**, componentes **3x menores**, e troca de idioma **2x-4x mais rápida** no TanStack Start.
+
+Todos os dados brutos, aplicações de teste e scripts estão no [repositório Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Execute você mesmo.
+
+Consulte a [documentação 'Por que Intlayer?'](https://intlayer.org/pt/doc/why) para mais detalhes.

package/blog/pt/vue-i18n_vs_intlayer-vue-i18n.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-09-13
-updatedAt: 2026-09-13
+updatedAt: 2026-09-22
 title: "vue-i18n vs @intlayer/vue-i18n: Mesma API, Bundle Diferente"
 description: O que muda quando uma aplicação Vue 3 mantém suas chamadas vue-i18n, mas as serve através do adaptador de compatibilidade @intlayer/vue-i18n. JavaScript por página, tamanho de runtime, tamanho de componente e vazamento medidos no mesmo código Vite + Vue, além do que o adaptador mantém, ignora e não consegue substituir.
 keywords:
@@ -25,6 +25,8 @@ author: aymericzip
 
 # vue-i18n VS @intlayer/vue-i18n | Mesma API, Bundle Diferente
 
+![Vue i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 `@intlayer/vue-i18n` é um adaptador de compatibilidade: expõe a API `vue-i18n` (`createI18n`, `useI18n`, `t()`, `d()`, `n()`, `$t`, `v-t`, `i18n.global.locale`...) e a serve a partir de dicionários compilados pelo Intlayer. Seus arquivos `.vue` não mudam. O que `t("footer.github")` está vinculado é que muda.
 
 Este artigo mede essa troca na mesma aplicação Vite + Vue 3, construída uma vez com `vue-i18n` e outra com o adapter. Os números vêm de [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Para `vue-i18n` e Intlayer comparados como bibliotecas, leia [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) e o [benchmark vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark). Este é sobre o que o adapter muda quando você mantém seus componentes como estão.
@@ -105,6 +107,10 @@ Para cada build, a suite registra:
 
 ### Resultados em Vite + Vue 3
 
+Escolha as métricas e as bibliotecas que importam para você:
+
+<I18nBenchmark framework="vite-vue" vertical/>
+
 | Setup                    | Strategy | Lib size (gz) | Lib size (min) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |  Page load |
 | ------------------------ | -------- | ------------: | -------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ---------: |
 | **base** (sem i18n)      | -        |        0.0 KB |         0.0 KB |          41.3 KB |        0.0% |         - |             1.1 KB |         1.8 ms |    10.8 ms |
@@ -124,11 +130,24 @@ Para cada build, a suite registra:
 - **Reatividade e carregamento de página.** A troca de locale é barata para ambas (1.5-2.8 ms); o sistema de reatividade do Vue torna isso possível uma vez que as mensagens estão na memória. O carregamento de página vai de 13.6 ms para **9.3 ms**, alinhado com 88 KB a menos de JavaScript para fazer parse.
 - **Sobre as linhas nativas.** `vue-intlayer` nesta execução agrupou cada locale em modo `static` e chegou a 57.1 KB com um runtime de 3.9 KB; os dicionários sincronizados do adaptador carregavam menos strings de locales estrangeiros, daí a figura mais baixa por página. O runtime nativo permanece o mais leve dos três, e seu modelo `.content.ts` é onde os blocos SFC `<i18n>` encontram seu equivalente.
 
+<ClickToOpenIframe
+src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-vite_vue.md"
+width="100%"
+height="600px"
+style="border:none;"
+/>
+
+> Tabela completa, cada biblioteca e cada estratégia, no [relatório de benchmark do Vue](https://intlayer.org/pt/doc/benchmark/vue).
+
 ## Por que os números se movem
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Nada em `src/components/` mudou, então os ganhos vêm do que `useI18n` está vinculado.
 
-**Com `vue-i18n`**, a ligação é a instância global. `createI18n({ messages: { en, fr, ... } })` é uma importação que contém tudo; cada componente que chama `useI18n()` pode acessar tudo isso, então o bundler não consegue dividir abaixo da instância. Otimizar significa que _você_ divide `en.json` por rota, chama `setLocaleMessage()` em um router guard, e mantém o mapa rota-para-arquivo correto conforme os componentes se movem.
+**Com `vue-i18n`**, a ligação é a instância global. `createI18n({ messages: { en, fr, ... } })` é uma importação que contém tudo; cada componente que chama `useI18n()` pode acessar tudo isso, então o bundler não consegue dividir abaixo da instância. Otimizar significa que _você_ divide `en.json` por rota, chama `setLocaleMessage()` em um router guard, e mantém o mapa rota-para-arquivo correto conforme os componentes se movem. O desperdício cresce em dois eixos simultaneamente, 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
 .
@@ -258,26 +277,107 @@ export const i18n = createI18n({ locale: "en" });
 
 ## Limites a conhecer antes de começar
 
-- **Blocos SFC `<i18n>` não são lidos.** Se suas mensagens vivem dentro de componentes, elas precisam se mover para os arquivos de locale (ou para `.content.ts`, que é a mesma ideia com tipos).
-- **Carregamento de mensagens em runtime acabou.** `setLocaleMessage()` e `mergeLocaleMessage()` emitem avisos e retornam. Traduções buscadas de um CMS em runtime precisam do CMS do Intlayer, ou dos comandos `intlayer pull` / `push`.
-- **`messages` é um fallback, não é gratuito.** Manter as importações JSON em `createI18n()` mantém os 75 KB no bundle. Delete-as assim que `intlayer test` passar.
-- **O adaptador não é o runtime nativo.** 7.9 KB contra 3.9 KB para `vue-intlayer`. Uma vez que todos os componentes migrarem para `useIntlayer`, remova-o.
+<AccordionGroup>
+<Accordion header="Blocos SFC <i18n> não são lidos">
+
+Se suas mensagens estão dentro dos componentes, elas precisam ser movidas para os arquivos de idioma ou para um arquivo `.content.ts`, que é a mesma ideia com tipos gerados.
+
+</Accordion>
+<Accordion header="O carregamento de mensagens em tempo de execução foi descontinuado">
+
+`setLocaleMessage()` e `mergeLocaleMessage()` exibem um aviso e retornam. Traduções obtidas de um CMS em tempo de execução precisam do [CMS do Intlayer](https://intlayer.org/pt/doc/concept/cms) ou dos comandos `intlayer pull` / `push`.
+
+</Accordion>
+<Accordion header="messages é um fallback, não gratuito">
+
+Manter as importações JSON no `createI18n()` mantém os 75 KB no bundle. Remova-as assim que o `intlayer test` passar com sucesso.
+
+</Accordion>
+<Accordion header="O adaptador não é o runtime nativo">
+
+7.9 KB contra 3.9 KB para o `vue-intlayer`. Assim que cada componente tiver migrado para o `useIntlayer`, remova-o.
+
+</Accordion>
+</AccordionGroup>
 
 ## Quando usar qual?
 
-- **Mantenha-se em `vue-i18n`** se sua aplicação depende de blocos SFC `<i18n>`, de fluxos de `setLocaleMessage()` em runtime, ou se 90 KB por página não é uma preocupação para seu público.
-- **Use `@intlayer/vue-i18n`** se você está em `vue-i18n` e quer os 88 KB, os componentes 23x menores, 0% vazamento de página, chaves tipadas e verificações de CI sem editar um arquivo `.vue`. Este é o ponto de entrada para um codebase `vue-i18n` existente.
-- **Vá nativo (`vue-intlayer`)** para novos projetos, ou uma vez que o adaptador tenha feito seu trabalho. Ele tem o runtime mais leve (3.9 KB) e o modelo `.content.ts` por componente que substitui blocos `<i18n>` com conteúdo tipado.
+<AccordionGroup>
+<Accordion header="Permanecer no vue-i18n">
+
+Sua aplicação depende dos blocos SFC `<i18n>`, de fluxos `setLocaleMessage()` em tempo de execução, ou 90 KB por página não é uma preocupação para o seu público.
+
+</Accordion>
+<Accordion header="Usar @intlayer/vue-i18n">
+
+Você está no `vue-i18n` e deseja os 88 KB economizados, componentes 23 vezes menores, 0% de vazamento de página, chaves tipadas e verificações no CI sem editar um arquivo `.vue`. Este é o ponto de entrada para uma base de código `vue-i18n` existente.
+
+</Accordion>
+<Accordion header="Tornar-se nativo (vue-intlayer)">
+
+Para novos projetos, ou assim que o adaptador cumprir seu papel. Possui o runtime mais leve (3.9 KB) e o modelo `.content.ts` por componente que substitui blocos `<i18n>` por conteúdo tipado. Comece com [Intlayer com Vue](https://intlayer.org/pt/doc/environment/vite-and-vue) ou [com Nuxt](https://intlayer.org/pt/doc/environment/nuxt-and-vue).
+
+</Accordion>
+</AccordionGroup>
+
+## Perguntas Frequentes
+
+<FAQ>
+
+<Question title="Preciso editar meus arquivos .vue?">
+
+Não. A compilação do benchmark modificou apenas o `vite.config.ts`, `intlayer.config.ts` e uma linha em `src/i18n.ts`, a importação de `messages`. Todas as chamadas para `useI18n()`, `$t`, `v-t` e Options API permaneceram inalteradas.
+
+</Question>
+
+<Question title="Por que o tamanho do componente é 23 vezes menor?">
+
+Porque o `useI18n()` deixa de acessar a instância global. O `createI18n({ messages })` contém todas as mensagens de todos os idiomas, então um componente compilado isoladamente arrasta 196 KB. Com o adaptador, ele acessa apenas seu próprio dicionário: 8.4 KB.
+
+</Question>
+
+<Question title="E quanto à formatação com d() e n()?">
+
+Mantida. As configurações `datetimeFormats` e `numberFormats` passadas para `createI18n()` são respeitadas, suportadas pela API nativa `Intl`. Consulte [formatação de data, hora e número](https://intlayer.org/pt/blog/date-time-number-formatting-locales).
+
+</Question>
+
+<Question title="Funciona com Nuxt?">
+
+O `@intlayer/vue-i18n` é voltado para Vite + Vue. Para `@nuxtjs/i18n`, use o [adaptador de compatibilidade Nuxt i18n](https://intlayer.org/pt/doc/compatibility/nuxtjs-i18n) e veja [Intlayer com Nuxt](https://intlayer.org/pt/doc/environment/nuxt-and-vue) para a configuração nativa.
+
+</Question>
+
+<Question title="Posso migrar componente por componente?">
+
+Sim. Qualquer componente pode mudar de `useI18n()` para `useIntlayer("footer")` com um arquivo de conteúdo co-localizado. Dicionários JSON e `.content.ts` coexistem e se mesclam.
+
+</Question>
+
+</FAQ>
 
 ## Comparações relacionadas
 
-- [vue-i18n vs Intlayer](https://intlayer.org/blog/vue-i18n-vs-intlayer) (recursos e DX)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/blog/vue-i18n-vs-intlayer-benchmark) (as bibliotecas, mesmo benchmark)
-- [next-intl vs @intlayer/next-intl](https://intlayer.org/blog/next-intl-vs-intlayer-next-intl) (mesma série de adaptadores)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (mesma série de adaptadores)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (mesma série de adaptadores)
-- [Guia de migração: vue-i18n para Intlayer](https://intlayer.org/doc/migration/vue-i18n)
-- [Referência do adaptador de compatibilidade: vue-i18n](https://intlayer.org/doc/compatibility/vue-i18n), [Nuxt i18n](https://intlayer.org/doc/compatibility/nuxtjs-i18n)
+Mesma série de adaptadores:
+
+- [next-intl vs @intlayer/next-intl](https://intlayer.org/pt/blog/next-intl-vs-intlayer-next-intl)
+- [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)
+
+Bibliotecas comparadas diretamente:
+
+- [vue-i18n vs Intlayer](https://intlayer.org/pt/blog/vue-i18n-vs-intlayer), features and DX
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/pt/blog/vue-i18n-vs-intlayer-benchmark)
+- [Is vue-i18n outdated?](https://intlayer.org/pt/blog/is-vue-i18n-outdated)
+- [How to pick a Vue i18n library](https://intlayer.org/pt/blog/how-to-pick-vue-i18n-library)
+
+Documentação de referência:
+
+- [Compat adapter: vue-i18n](https://intlayer.org/pt/doc/compatibility/vue-i18n) and [Nuxt i18n](https://intlayer.org/pt/doc/compatibility/nuxtjs-i18n)
+- [Guia de migração: vue-i18n para Intlayer](https://intlayer.org/pt/doc/migration/vue-i18n)
+- [Relatório de benchmark do Vue](https://intlayer.org/pt/doc/benchmark/vue)
+- [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
 
@@ -285,4 +385,4 @@ export const i18n = createI18n({ locale: "en" });
 
 Todos os dados brutos, os aplicativos de teste e os scripts estão no [repositório Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom). Execute você mesmo.
 
-Consulte a [documentação 'Por que Intlayer?'](https://intlayer.org/doc/why) para mais detalhes.
+Consulte a [documentação 'Por que Intlayer?'](https://intlayer.org/pt/doc/why) para mais detalhes.