@intlayer/docs 9.5.6 → 9.5.8

package/blog/es/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 y Comparación 2026"
 description: "Dos librerías i18n basadas en compiladores medidas en Next.js y TanStack Start. Tamaño de bundle, fuga de contenido, tamaño de componente, hidratación, reactividad de cambio de locale y experiencia de desarrollador."
 keywords:
@@ -24,6 +24,8 @@ author: aymericzip
 
 # Lingui VS Intlayer | Benchmark de Internacionalización (i18n) en React & Next.js
 
+![JavaScript i18n library ecosystem](https://github.com/aymericzip/intlayer/blob/main/docs/assets/cloud_i18n_logo.webp?raw=true)
+
 Lingui e Intlayer son las dos librerías en este benchmark que se basan en un **compilador** en lugar de un runtime puro. Lingui extrae mensajes de macros en tiempo de compilación y compila catálogos por locale. Intlayer compila diccionarios por componente y los tree-shake por locale. En teoría deberían ser similares. Los números muestran dónde divergen.
 
 Los datos provienen de [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), un suite de código abierto que construye la misma aplicación con cada librería y registra lo que el navegador realmente descarga y ejecuta.
@@ -96,6 +98,10 @@ Para cada build, la suite registra:
 
 ### Resultados en Next.js
 
+Selecciona las métricas y las bibliotecas que te interesen:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Librería            | Estrategia     | Tamaño Lib (gz) | JS por pág avg (gz) | Fuga locale | Fuga pág | Prom component (gz) | Reactividad E2E | Hidratación |
 | ------------------- | -------------- | --------------: | ------------------: | ----------: | -------: | ------------------: | --------------: | ----------: |
 | **base** (sin 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 build, la suite registra:
 - **El fallback del locale de origen tiene fugas.** Incluso en las configuraciones optimizadas, **3-15% de las cadenas `en` se envían dentro de las páginas `fr`**. Las macros de Lingui mantienen el mensaje de origen disponible como fallback, por lo que llega al bundle junto a la traducción. Intlayer resuelve los fallbacks en tiempo de compilación y envía solo el locale activo.
 - **El tamaño del componente se dispara en `scoped-dynamic`.** Cada componente compilado en aislamiento promedia **152.6 KB**, porque el catálogo de cada ruta es accesible desde el componente que lo importa. El mismo componente con `useIntlayer()` promedia **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;"
+/>
+
+> Tabla completa, cada biblioteca y cada estrategia, en el [informe de benchmark de Next.js](https://intlayer.org/es/doc/benchmark/nextjs).
+
 ### Resultados en TanStack Start
 
 | Librería                    | Estrategia     | Tamaño Lib (gz) | JS por pág avg (gz) | Fuga locale | Fuga pág | Prom component (gz) | Reactividad E2E | Hidratación |
@@ -135,8 +150,19 @@ Para cada build, la suite registra:
 - **La fila `static` de Intlayer ya tiene 0% de fuga de página** porque solo se empaquetan los diccionarios importados por los componentes de la página. Una línea de configuración (`importMode: 'dynamic'`) elimina también la fuga de locale.
 - **`@intlayer/lingui`** conserva la sintaxis de macros de Lingui y la sirve desde diccionarios de Intlayer. Intercambia algo de tamaño de página (137 KB, dado que el runtime de macros permanece) por componentes más pequeños (12.8 KB) y una hidratación más rápida que el Lingui nativo. Es un paso de migración, no el destino final.
 
+<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;"
+/>
+
+> Tabla completa en el [informe de benchmark de TanStack Start](https://intlayer.org/es/doc/benchmark/tanstack).
+
 ## ¿Por qué la diferencia? Dos compiladores, dos unidades de trabajo
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Ambas librerías compilan. La diferencia radica en **qué** compilan.
 
 **Lingui compila catálogos.** Las macros en tu código fuente se extraen en un archivo `.po` por locale, y luego se compilan en un módulo JS por locale. La unidad es el **locale**. Dividir aún más, por ruta o por componente, implica crear múltiples catálogos, configurar `lingui.config.ts` para extraer cada uno de un conjunto diferente de archivos y cargar el catálogo adecuado en cada ruta. La instancia runtime `I18n` es global; cada llamada a `useLingui()` suscribe el componente a ella.
@@ -176,7 +202,9 @@ Ambas librerías compilan. La diferencia radica en **qué** compilan.
             └── about.content.ts
 ```
 
-Por eso el patrón `scoped-dynamic` es una salida de compilación automática para Intlayer y un proyecto de configuración manual para Lingui.
+Por eso el patrón `scoped-dynamic` es una salida de compilación automática para Intlayer y un proyecto de configuración manual para Lingui. La brecha se amplía en dos ejes a la vez, 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 obtener los números de la fila `dynamic`, define `dictionary.importMode: 'dynamic'` en `intlayer.config.ts`. Consulta la [documentación de optimización de bundle](https://intlayer.org/es/doc/concept/bundle-optimization).
 
@@ -184,7 +212,8 @@ Por eso el patrón `scoped-dynamic` es una salida de compilación automática pa
 
 ### Configuración
 
-**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) => {
 
 Luego agrega `@lingui/babel-plugin-lingui-macro` (o `@lingui/swc-plugin`) al empaquetador, ejecuta `lingui extract` después de editar el código fuente, `lingui compile` antes de compilar y envuelve el árbol en `<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;
 
 Agrega `intlayer()` a `vite.config.ts` (o `withIntlayer()` a `next.config.ts`) y envuelve el árbol en `<IntlayerProvider>`. No se requiere ningún paso de extracción o compilación: los diccionarios se construyen cuando se ejecuta el empaquetador.
 
+</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 = () => {
 
 El texto en inglés vive en el componente; el francés vive en `src/locales/fr/messages.po` bajo un ID en hash, después de ejecutar `lingui extract`. Olvidar ejecutarlo o compilar recurre silenciosamente al inglés.
 
-**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 locales residen en un archivo junto al componente. Un valor faltante de `fr` es un error de compilación, una clave incorrecta es un error de TypeScript.
 
+</Tab>
+</Tabs>
 ### Fuera de los componentes
 
 Metadatos, loaders, funciones de servidor: en cualquier lugar sin un árbol de 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 } }) => {
 
 Una nueva instancia de `I18n` por llamada, el catálogo correcto cargado manualmente y `msg` + `i18n._()` en lugar de `t`. Como señalan las [notas del benchmark](https://github.com/intlayer-org/benchmark-bloom/blob/main/report/NOTE.md), saber cuándo usar `t`, `` t` ` ``, `i18n.t()`, `msg` o `<Trans>` "no es intuitivo".
 
-**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>
+
 ## Conserva las macros de Lingui, obtén los diccionarios de Intlayer
 
 `@intlayer/lingui` es un adaptador directo para `@lingui/core` y `@lingui/react`. Las macros continúan compilándose como antes; el runtime `i18n._()` al que se compilan es servido desde diccionarios de Intlayer, con plugins de sincronización `.po` manteniendo tus catálogos existentes como fuente de verdad. Los plurales y selecciones ICU se renderizan de forma idéntica.
@@ -353,16 +394,82 @@ Mantén `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` en la compila
 
 ## ¿Cuándo elegir cuál?
 
-- **Elige Lingui** si buscas **ICU MessageFormat** con macros tipadas, tus traductores trabajan con archivos **`.po`** dentro de un flujo TMS existente, prefieres cadenas de origen inline en JSX y tu equipo se siente cómodo gestionando el flujo de extracción, compilación y división de catálogos. Su JS por página es competitivo una vez configurada la carga diferida.
-- **Elige Intlayer** si buscas **contenido con alcance de componente**, **TypeScript estricto**, **errores de claves faltantes en tiempo de compilación**, **tree-shaking y lazy loading sin esfuerzo**, componentes ligeros, hidratación rápida, cambio instantáneo de idioma y herramientas editoriales integradas (Editor Visual, CMS, traducción con IA, servidor MCP). Especialmente relevante para bases de código modulares y sistemas de diseño a gran escala.
-- **Elige `@intlayer/lingui`** si ya utilizas Lingui y deseas migrar a los diccionarios de Intlayer gradualmente sin modificar tus macros.
+<AccordionGroup>
+<Accordion header="Elegir Lingui">
+
+Deseas **ICU MessageFormat** con macros tipadas, tus traductores trabajan en **`.po`** con un flujo TMS existente, prefieres cadenas fuente en línea en JSX y tu equipo gestiona cómodamente el flujo de extracción / compilación / división de catálogos. Su JS por página es competitivo una vez configurado el lazy loading.
+
+</Accordion>
+<Accordion header="Elegir Intlayer">
+
+Deseas **contenido con ámbito por componente**, **TypeScript estricto**, **errores de claves faltantes en tiempo de compilación**, **tree-shaking y lazy loading sin esfuerzo**, componentes pequeños, hidratación rápida, cambio instantáneo de idioma y herramientas editoriales integradas ([Editor Visual](https://intlayer.org/es/doc/concept/editor), [CMS](https://intlayer.org/es/doc/concept/cms), [traducción por IA](https://intlayer.org/es/doc/concept/auto-fill), [servidor MCP](https://intlayer.org/es/doc/mcp-server)). Especialmente relevante para bases de código modulares grandes y sistemas de diseño.
+
+</Accordion>
+<Accordion header="Elegir @intlayer/lingui">
+
+Ya usas Lingui y deseas migrar a los diccionarios de Intlayer gradualmente sin tocar las macros. Tus catálogos `.po` siguen siendo la fuente de la verdad gracias al [plugin de sincronización PO](https://intlayer.org/es/doc/compatibility/lingui). Medido lado a lado en [Lingui vs @intlayer/lingui](https://intlayer.org/es/blog/lingui-vs-intlayer-lingui).
+
+</Accordion>
+</AccordionGroup>
+
+## Preguntas frecuentes
+
+<FAQ>
+
+<Question title="Lingui también compila. ¿Por qué el resultado es tan diferente?">
+
+Porque la unidad de compilación difiere. Lingui compila **un catálogo por idioma**: todo lo que está por debajo (catálogos por ruta, lazy loading, excluir el fallback del bundle) requiere configuración. Intlayer compila **un diccionario por componente**, por lo que la división por rutas surge naturalmente de la compilación. Por eso un componente de Lingui compilado aisladamente pesa 58-153 KB frente a 6-8 KB en Intlayer.
+
+</Question>
+
+<Question title="¿Por qué la fuga de idioma nunca llega al 0% con Lingui?">
+
+Las macros mantienen el mensaje fuente disponible como fallback en tiempo de ejecución, por lo que la cadena en inglés se envía junto a su traducción. El benchmark mide **3-15% de cadenas `en` dentro de páginas `fr`** en cada configuración optimizada. Intlayer resuelve los fallbacks en tiempo de compilación y solo envía el idioma activo.
+
+</Question>
+
+<Question title="¿Es el JavaScript por página de Lingui realmente competitivo?">
+
+Sí, y en TanStack Start gana por muy poco: 115.2 KB en `dynamic` frente a 118.6 KB de Intlayer. Los catálogos compilados con identificadores hasheados son compactos. El coste aparece en otros aspectos: hidratación de 28-34 ms frente a 11-14 ms, y un cambio de idioma de **42 ms** en la configuración `scoped-dynamic`.
+
+</Question>
+
+<Question title="¿Tengo que renunciar a las macros para migrar?">
+
+No. `@intlayer/lingui` mantiene la compilación de `` t`...` ``, `<Trans>`, `msg`, `plural`, `select` y `selectOrdinal` exactamente como antes; solo cambia aquello contra lo que `i18n._()` resuelve. Mantén `@lingui/babel-plugin-lingui-macro` o `@lingui/swc-plugin` en la compilación. Consulta la [documentación de compatibilidad con Lingui](https://intlayer.org/es/doc/compatibility/lingui).
+
+</Question>
+
+<Question title="¿Qué pasa con los pasos de extracción y compilación?">
+
+Se mantienen para las macros y desaparecen para el contenido propio de Intlayer. Los diccionarios `.content.ts` se compilan cuando se ejecuta el empaquetador, sin ningún paso CLI independiente, y [`intlayer test`](https://intlayer.org/es/doc/concept/cli) falla en CI si falta una clave en lugar de recurrir silenciosamente a la cadena de origen.
+
+</Question>
+
+</FAQ>
 
 ## Comparaciones relacionadas
 
-- [next-intl vs Intlayer](https://intlayer.org/es/blog/next-intl-vs-intlayer) (mismo benchmark)
-- [i18next vs Intlayer](https://intlayer.org/es/blog/i18next-vs-intlayer) (mismo benchmark)
-- [vue-i18n vs Intlayer benchmark](https://intlayer.org/es/blog/vue-i18n-vs-intlayer-benchmark) (mismo benchmark)
-- [Compilador vs i18n declarativo](https://intlayer.org/es/blog/compiler-vs-declarative-i18n)
+Mismo benchmark, otras bibliotecas:
+
+- [next-intl vs Intlayer](https://intlayer.org/es/blog/next-intl-vs-intlayer)
+- [i18next vs Intlayer](https://intlayer.org/es/blog/i18next-vs-intlayer)
+- [vue-i18n vs Intlayer benchmark](https://intlayer.org/es/blog/vue-i18n-vs-intlayer-benchmark)
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/es/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/es/blog/react-i18next-vs-react-intl-vs-intlayer)
+
+Para profundizar:
+
+- [Lingui vs @intlayer/lingui](https://intlayer.org/es/blog/lingui-vs-intlayer-lingui), el adaptador medido en la misma aplicación
+- [Compiler-driven vs declarative i18n](https://intlayer.org/es/blog/compiler-vs-declarative-i18n)
+- [Per-component vs centralized i18n](https://intlayer.org/es/blog/per-component-vs-centralized-i18n)
+- [ICU message format explained](https://intlayer.org/es/blog/icu-message-format)
+
+Documentación de referencia:
+
+- [Informe de benchmark de Next.js](https://intlayer.org/es/doc/benchmark/nextjs) e [informe de benchmark de TanStack Start](https://intlayer.org/es/doc/benchmark/tanstack)
+- [Compat adapter: Lingui](https://intlayer.org/es/doc/compatibility/lingui)
+- [Optimización del bundle](https://intlayer.org/es/doc/concept/bundle-optimization) y [el compilador Intlayer](https://intlayer.org/es/doc/compiler)
 
 ## GitHub STARS
 

package/blog/es/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: Misma API, Diferentes Bundle"
 description: Qué cambia cuando las importaciones de next-intl de una aplicación Next.js se sirven mediante el adaptador de compatibilidad @intlayer/next-intl. Tamaño de bundle, fugas, tamaño de componentes e hidratación medidos en el mismo código, más lo que el adaptador mantiene, ignora y no puede reemplazar.
 keywords:
@@ -26,6 +26,8 @@ author: aymericzip
 
 # next-intl VS @intlayer/next-intl | Misma API, Diferentes Bundle
 
+![next-intl VS Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18next-next-intl-intlayer.webp?raw=true)
+
 `@intlayer/next-intl` es un adaptador de compatibilidad: expone la API de `next-intl` (`useTranslations`, `getTranslations`, `useLocale`, `t.rich()`, plurales ICU, `NextIntlClientProvider`...) y la sirve desde diccionarios compilados por Intlayer. El código de la aplicación no cambia. El bundle sí.
 
 Este artículo compara los dos en la misma aplicación Next.js, construida una vez con `next-intl` y otra con el adaptador. Los números provienen de [Benchmark Bloom](https://github.com/intlayer-org/benchmark-bloom), una suite open-source que registra lo que el navegador realmente descarga. Si quieres la comparación de `next-intl` vs Intlayer como librerías, lee [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer). Este es sobre lo que cambia el adaptador cuando mantienes tus componentes como están.
@@ -109,6 +111,10 @@ Para cada compilación, la suite registra:
 
 ### Resultados en Next.js
 
+Selecciona las métricas y las bibliotecas que te interesen:
+
+<I18nBenchmark framework="nextjs" vertical/>
+
 | Setup                     | Strategy       | Lib size (gz) | Page JS avg (gz) | Locale leak | Page leak | Component avg (gz) | E2E reactivity |   Hydration |
 | ------------------------- | -------------- | ------------: | ---------------: | ----------: | --------: | -----------------: | -------------: | ----------: |
 | **base** (no 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 compilación, la suite registra:
 - **La hidratación es 2 ms más rápida** (12.8 vs 14.7 ms): no hay un objeto de mensaje que deserializar de la carga útil de RSC antes de que React pueda hidratarse.
 - **El adaptador no es el runtime nativo.** `next-intlayer` se ubica en **141.3 KB**, +0.3 KB sobre la aplicación base, con un runtime de 5.5 KB. El adaptador lleva la superficie de la API de `next-intl` (`useFormatter`, `t.rich`, el resolutor de ICU) sobre el núcleo de Intlayer, por lo que consume 8.0 KB y +6 KB por página. Es el puente, no el 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;"
+/>
+
+> Tabla completa, cada biblioteca y cada estrategia, en el [informe de benchmark de Next.js](https://intlayer.org/es/doc/benchmark/nextjs).
+
 ### Resultados en TanStack Start (`use-intl`)
 
 `use-intl` es el núcleo agnóstico del framework de `next-intl`. Su adaptador, `@intlayer/use-intl`, sigue el mismo diseño con un plugin de Vite (`@intlayer/use-intl/plugin`).
@@ -152,11 +167,24 @@ Para cada compilación, la suite registra:
 - **El cambio de locale es más rápido.** Las configuraciones optimizadas de `use-intl` tardan **13-21 ms** en actualizar `html[lang]`; el adaptador tarda **4-9 ms**. Menos componentes se re-renderizan, y nada se vuelve a seleccionar de un árbol de mensajes.
 - **`static` mantiene cada locale.** La fila `static` del adaptador muestra 49.7% de fuga de locale, lo mismo que Intlayer nativo en modo `static`: todos los locales se empaquetan, solo se incluyen los diccionarios de la página. Una línea de configuración (`importMode: 'dynamic'`) lo elimina.
 
+<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;"
+/>
+
+> Tabla completa en el [informe de benchmark de TanStack Start](https://intlayer.org/es/doc/benchmark/tanstack).
+
 ## Por qué los números cambian
 
+![The Intlayer compiler extracts content from components](https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.webp?raw=true)
+
 Nada en el componente cambió, por lo que las ganancias provienen completamente de lo que `useTranslations` está vinculado.
 
-**Con `next-intl`**, el binding es el provider. `NextIntlClientProvider` recibe todo el objeto `messages` para la locale; cada `useTranslations("about")` lee desde él. El bundler ve un componente importando un hook que lee un contexto, y no puede saber que solo se usa la rama `about`. Las rutas de abajo comparten el mismo objeto de mensajes, por lo que la columna page-leak lee ~90% hasta que dividas el archivo tú mismo.
+**Con `next-intl`**, el binding es el provider. `NextIntlClientProvider` recibe todo el objeto `messages` para la locale; cada `useTranslations("about")` lee desde él. El bundler ve un componente importando un hook que lee un contexto, y no puede saber que solo se usa la rama `about`. Las rutas de abajo comparten el mismo objeto de mensajes, por lo que la columna page-leak lee ~90% hasta que dividas el archivo tú mismo, y el desperdicio crece en dos ejes a la vez, 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);
 
 ## Límites a conocer antes de comenzar
 
-- **La configuración de enrutamiento se traslada a `intlayer.config.ts`.** `createNavigation(routing)` y `createMiddleware(routing)` mantienen su firma pero ignoran el argumento: las locales, la locale predeterminada y la estrategia de prefijo provienen de la configuración `routing` de Intlayer. Si utilizas `pathnames` localizadas de `next-intl` (`/about` → `/a-propos`), el adaptador no las interpola; el `routing.rewrite` de Intlayer cubre ese caso pero es un cambio separado.
-- **`useTranslations()` sin namespace no está vinculado.** El paso de optimización necesita un namespace estático para saber qué diccionario importar. Una llamada sin argumentos sigue funcionando, a través de un registro en tiempo de ejecución que referencia cada diccionario, que es exactamente la fuga que intentabas eliminar. Pasa el namespace.
-- **El adaptador no es gratuito.** 8.0 KB de runtime versus 5.5 KB para `next-intlayer`, y +6-7 KB por página sobre la compilación nativa. Cubre la superficie de la API de `next-intl`. Si llegas al punto donde cada componente ha sido movido a `useIntlayer`, abandona el adaptador.
-- **`messages`, `timeZone`, `now` en el proveedor son ignorados.** Los formateadores están respaldados por `Intl` nativo y solo la locale influye en su salida; si dependes de una zona horaria forzada o un `now` fijo para fechas estables en hidratación, manéjalo en el sitio de la llamada.
+<AccordionGroup>
+<Accordion header="La configuración de enrutamiento se traslada a intlayer.config.ts">
+
+`createNavigation(routing)` y `createMiddleware(routing)` mantienen su firma pero ignoran el argumento: los idiomas, el idioma predeterminado y la estrategia de prefijo provienen de la configuración `routing` de Intlayer. Si utilizas los `pathnames` localizados de `next-intl` (`/about` a `/a-propos`), el adaptador no los interpola; `routing.rewrite` de Intlayer cubre ese caso pero es un cambio separado.
+
+</Accordion>
+<Accordion header="useTranslations() sin namespace no está vinculado">
+
+El paso de optimización necesita un namespace estático para saber qué diccionario importar. Una llamada sin namespace sigue funcionando a través de un registro de runtime que referencia cada diccionario, lo cual es exactamente la fuga que intentabas eliminar. Pasa el namespace.
+
+</Accordion>
+<Accordion header="El adaptador no es gratuito">
+
+8.0 KB de runtime frente a 5.5 KB de `next-intlayer`, y +6-7 KB por página sobre la compilación nativa. Paga por la superficie de la API de `next-intl`. Si llegas al punto en que cada componente se ha migrado a `useIntlayer`, elimina el adaptador.
+
+</Accordion>
+<Accordion header="messages, timeZone y now en el provider son ignorados">
+
+Los formateadores están respaldados por la API nativa `Intl` y solo el idioma influye en su salida. Si dependes de una zona horaria forzada o un `now` fijo para fechas estables en hidratación, manéjalo en el punto de llamada. Consulta [formateo de fechas, horas y números](https://intlayer.org/es/blog/date-time-number-formatting-locales).
+
+</Accordion>
+</AccordionGroup>
 
 ## ¿Cuándo usar cuál?
 
-- **Mantente en `next-intl`** si tu aplicación es pequeña, tu bundle no es una preocupación, y tu equipo se siente cómodo siendo propietario de los namespaces y `pick()` por página.
-- **Usa `@intlayer/next-intl`** si estás en `next-intl` hoy y quieres las ganancias de bundle, leakage e hidratación, claves tipadas y las herramientas CLI / CMS sin una reescritura. Este es el punto de entrada recomendado para cualquier codebase existente de `next-intl`.
-- **Ve nativo (`next-intlayer`)** para nuevos proyectos, o una vez que el adapter ha hecho su trabajo. Es el más ligero de los tres (5.5 KB, +0.3 KB por página) y desbloquea componentes de servidor síncronos, archivos `.content.ts` por componente y el conjunto completo de características.
+<AccordionGroup>
+<Accordion header="Quédate en next-intl">
+
+Tu aplicación es pequeña, el tamaño del bundle no es una preocupación y tu equipo se siente cómodo gestionando namespaces y `pick()` por página.
+
+</Accordion>
+<Accordion header="Usa @intlayer/next-intl">
+
+Hoy usas `next-intl` y quieres las ventajas de bundle, reducción de fugas e hidratación rápida, claves tipadas y las herramientas de CLI / CMS sin una reescritura. Este es el punto de entrada recomendado para cualquier base de código `next-intl` existente.
+
+</Accordion>
+<Accordion header="Pasa a nativo (next-intlayer)">
+
+Para nuevos proyectos, o una vez que el adaptador haya cumplido su función. Es el más ligero de los tres (5.5 KB, +0.3 KB por página) y desbloquea componentes de servidor síncronos, archivos `.content.ts` por componente y el conjunto completo de características. Comienza con [Intlayer con Next.js](https://intlayer.org/es/doc/environment/nextjs).
+
+</Accordion>
+</AccordionGroup>
+
+## Preguntas frecuentes
+
+<FAQ>
+
+<Question title="¿El código de mi aplicación realmente se mantiene intacto?">
+
+En Next.js, sí para los componentes: la compilación del benchmark solo modificó `next.config.ts` e `intlayer.config.ts`. `getRequestConfig` en `src/i18n.ts`, la prop `messages` en el provider y las llamadas `pick()` por página se convierten en código muerto que puedes eliminar después.
+
+</Question>
+
+<Question title="¿Qué ocurre con los mensajes ICU?">
+
+Siguen funcionando. `t("key", { count })`, `t.rich()`, `t.markup()`, `select`, `selectordinal`, `#` y `{ts, date, long}` son resueltos por el intérprete ICU de Intlayer. Consulta [formato de mensaje ICU](https://intlayer.org/es/blog/icu-message-format).
+
+</Question>
+
+<Question title="¿Por qué el adaptador es más pesado que next-intlayer nativo?">
+
+Transporta la superficie de la API de `next-intl` sobre el núcleo de Intlayer: `useFormatter`, `t.rich`, el intérprete ICU, los helpers de navegación. Eso representa 8.0 KB frente a 5.5 KB, y +6 KB por página. Es el puente, no el destino final.
+
+</Question>
+
+<Question title="¿Puedo migrar componente por componente?">
+
+Sí. Cualquier componente puede cambiar de `useTranslations("about")` a `useIntlayer("about")` con un archivo `.content.ts` coubicado. Los diccionarios JSON y `.content.ts` coexisten y se combinan, por lo que no hay interrupciones.
+
+</Question>
+
+<Question title="¿Funcionan las rutas (pathnames) localizadas?">
+
+No a través de los `pathnames` de `next-intl`: el adaptador los acepta para tipado pero no los interpola. Utiliza en su lugar `routing.rewrite` de Intlayer, que emite los literales localizados en el registro de tipos.
+
+</Question>
+
+</FAQ>
 
 ## Comparaciones relacionadas
 
-- [next-intl vs Intlayer](https://intlayer.org/blog/next-intl-vs-intlayer) (las librerías, el mismo benchmark)
-- [i18next vs @intlayer/i18next](https://intlayer.org/blog/i18next-vs-intlayer-i18next) (la misma serie de adaptadores)
-- [Lingui vs @intlayer/lingui](https://intlayer.org/blog/lingui-vs-intlayer-lingui) (misma serie de adaptadores)
-- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/blog/vue-i18n-vs-intlayer-vue-i18n) (misma serie de adaptadores)
-- [Guía de migración: next-intl a Intlayer](https://intlayer.org/doc/migration/next-intl)
-- [Referencia del adaptador de compatibilidad: next-intl](https://intlayer.org/doc/compatibility/next-intl)
+Misma serie de adaptadores:
+
+- [i18next vs @intlayer/i18next](https://intlayer.org/es/blog/i18next-vs-intlayer-i18next)
+- [Lingui vs @intlayer/lingui](https://intlayer.org/es/blog/lingui-vs-intlayer-lingui)
+- [vue-i18n vs @intlayer/vue-i18n](https://intlayer.org/es/blog/vue-i18n-vs-intlayer-vue-i18n)
+
+Las bibliotecas comparadas directamente:
+
+- [next-intl vs Intlayer](https://intlayer.org/es/blog/next-intl-vs-intlayer), mismo benchmark
+- [next-i18next vs next-intl vs Intlayer](https://intlayer.org/es/blog/next-i18next-vs-next-intl-vs-intlayer)
+- [Is next-intl outdated?](https://intlayer.org/es/blog/is-next-intl-outdated)
+
+Documentación de referencia:
+
+- [Compat adapter: next-intl](https://intlayer.org/es/doc/compatibility/next-intl)
+- [Guía de migración: next-intl a Intlayer](https://intlayer.org/es/doc/migration/next-intl)
+- [Informe de benchmark de Next.js](https://intlayer.org/es/doc/benchmark/nextjs) e [informe de benchmark de TanStack Start](https://intlayer.org/es/doc/benchmark/tanstack)
+- [Optimización del bundle](https://intlayer.org/es/doc/concept/bundle-optimization) y [el compilador Intlayer](https://intlayer.org/es/doc/compiler)
+- [Visual Editor](https://intlayer.org/es/doc/concept/editor), [CMS](https://intlayer.org/es/doc/concept/cms) y [traducción por IA](https://intlayer.org/es/doc/concept/auto-fill)
 
 ## Conclusión