@intlayer/docs 9.4.1 → 9.4.2

package/docs/es/intlayer_with_nextjs_16.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-12-06
-updatedAt: 2026-06-23
+updatedAt: 2026-08-30
 title: "Next.js 16 i18n - Guía completa para traducir tu aplicación"
 description: "Sin más i18next. La guía 2026 para crear una aplicación Next.js 16 multilingüe (i18n). Traduce con agentes de IA y optimiza el tamaño del bundle, SEO y rendimiento."
 keywords:
@@ -76,7 +76,6 @@ Consulta la [Plantilla de Aplicación](https://github.com/aymericzip/intlayer-ne
 En comparación con soluciones principales como `next-intl` o `i18next`, Intlayer es una solución que viene con optimizaciones integradas como:
 
 <AccordionGroup>
-
 <Accordion header="Soporte completo de Next.js">
 
 Intlayer está optimizado para funcionar con **Componentes del servidor** para una representación eficiente y es totalmente compatible con [**Turbopack**](https://nextjs.org/docs/architecture/turbopack). No bloquea la representación estática y ofrece middleware, así como todas las funciones necesarias para escalar la internacionalización (i18n).
@@ -316,7 +315,7 @@ export default RootLayout;
 Para implementar el enrutamiento dinámico, proporciona la ruta para la localización añadiendo un nuevo layout en tu directorio `[locale]`:
 
 <Tabs>
- <Tab label='Intlayer >=9.4' value='>=9.4'>
+<Tab label='Intlayer >=9.4' value='>=9.4'>
 
 ```tsx fileName="src/app/[locale]/layout.tsx" codeFormat={["typescript", "esm"]}
 import { type NextLayoutIntlayer } from "next-intlayer";
@@ -342,8 +341,8 @@ export default LocaleLayout;
 
 > Un único `IntlayerProvider` cubre ambas mitades del árbol: alimenta el contexto del servidor con alcance de solicitud leído por los hooks del servidor, y monta el proveedor del cliente para que los componentes del cliente reciban la misma configuración regional.
 
- </Tab>
- <Tab label='Intlayer <9.4' value='<9.4'>
+</Tab>
+<Tab label='Intlayer <9.4' value='<9.4'>
 
 ```tsx fileName="src/app/[locale]/layout.tsx" codeFormat={["typescript", "esm"]}
 import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
@@ -368,7 +367,7 @@ const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
 export default LocaleLayout;
 ```
 
- </Tab>
+</Tab>
 </Tabs>
 
 > El segmento de ruta `[locale]` se utiliza para definir la configuración regional. Ejemplo: `/en-US/about` se referirá a `en-US` y `/fr/about` a `fr`.
@@ -448,7 +447,7 @@ export default pageContent;
 Accede a tus diccionarios de contenido en toda tu aplicación:
 
 <Tabs>
- <Tab label='Intlayer >=9.4' value='>=9.4'>
+<Tab label='Intlayer >=9.4' value='>=9.4'>
 
 ```tsx fileName="src/app/[locale]/page.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
@@ -482,8 +481,8 @@ export default Page;
 - **`IntlayerProvider`** se monta una sola vez, en el layout de locale. Proporciona el locale tanto a componentes del servidor como del cliente, por lo que las páginas ya no se envuelven a sí mismas.
 - Los hooks del servidor resuelven el locale en este orden: el locale pasado en el sitio de llamada, luego el contexto del servidor inicializado por el proveedor, luego el locale llevado por la solicitud (el encabezado `x-intlayer-locale` establecido por el proxy de Intlayer, luego la cookie de locale). Este último paso es lo que mantiene el contenido correcto en una navegación del lado del cliente que re-renderiza solo el segmento de página, donde el layout — y con él el proveedor — no se vuelve a ejecutar.
 
- </Tab>
- <Tab label='Intlayer <9.4' value='<9.4'>
+</Tab>
+<Tab label='Intlayer <9.4' value='<9.4'>
 
 ```tsx fileName="src/app/[locale]/page.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
@@ -526,6 +525,9 @@ export default Page;
 
   > El layout y la página no pueden compartir un contexto de servidor común porque el sistema de contexto de servidor se basa en un almacén de datos por solicitud (a través del mecanismo de [caché de React](https://react.dev/reference/react/cache)), lo que provoca que cada "contexto" se vuelva a crear para diferentes segmentos de la aplicación. Colocar el proveedor en un layout compartido rompería este aislamiento, impidiendo la correcta propagación de los valores del contexto del servidor a tus componentes del servidor.
 
+</Tab>
+</Tabs>
+
 ```tsx {4,7} fileName="src/components/ClientComponentExample.tsx" codeFormat={["typescript", "esm"]}
 "use client";
 
@@ -545,7 +547,7 @@ export const ClientComponentExample: FC = () => {
 ```
 
 <Tabs>
- <Tab label='Intlayer >=9.4' value='>=9.4'>
+<Tab label='Intlayer >=9.4' value='>=9.4'>
 
 ```tsx {2} fileName="src/components/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
@@ -565,8 +567,8 @@ export const ServerComponentExample: FC = () => {
 
 > `next-intlayer` es la ruta de importación isomórfica: la condición de exportación `react-server` proporciona a los componentes del servidor la implementación de locale ambiental, mientras que los componentes del cliente obtienen la respaldada por contexto. La misma llamada funciona en ambos lados.
 
- </Tab>
- <Tab label='Intlayer <9.4' value='<9.4'>
+</Tab>
+<Tab label='Intlayer <9.4' value='<9.4'>
 
 ```tsx {2} fileName="src/components/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import type { FC } from "react";
@@ -584,7 +586,7 @@ export const ServerComponentExample: FC = () => {
 };
 ```
 
- </Tab>
+</Tab>
 </Tabs>
 
 > Si quieres usar tu contenido en un atributo de tipo `string`, como `alt`, `title`, `href`, `aria-label`, etc., debes llamar al valor de la función, así:
@@ -728,36 +730,13 @@ export const generateMetadata = async ({
 
 > Tenga en cuenta que la función `getIntlayer` importada desde `next-intlayer` devuelve su contenido envuelto en un `IntlayerNode`, lo que permite la integración con el editor visual. En cambio, la función `getIntlayer` importada desde `intlayer` devuelve su contenido directamente sin propiedades adicionales.
 
-Alternativamente, puedes usar la función `getTranslation` para declarar tus metadatos. Sin embargo, se recomienda usar archivos de declaración de contenido para automatizar la traducción de tus metadatos y externalizar el contenido en algún momento.
-
-````typescript fileName="src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx" codeFormat={["typescript", "esm"]}
-import {
-  type IConfigLocales,
-  getTranslation,
-  getMultilingualUrls,
-} from "intlayer";
-import type { Metadata } from "next";
-import type { LocalPromiseParams } from "next-intlayer";
-
-export const generateMetadata = async ({
-  params,
-}: LocalPromiseParams): Promise<Metadata> => {
-  const { locale } = await params;
-  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);
-
-  return {
-    title: t<string>({
-      en: "My title",
-Alternativamente, puedes usar la función `getTranslation` para declarar tus metadatos. Sin embargo, se recomienda usar archivos de declaración de contenido para automatizar la traducción de tus metadatos y externalizar el contenido en algún momento.
-
-```typescript fileName="src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx" codeFormat="typescript"
-> Aprende más sobre la optimización de metadatos [en la documentación oficial de Next.js](https://nextjs.org/docs/app/building-your-application/optimizing/metadata).
+> Obtenga más información sobre la optimización de metadatos [en la documentación oficial de Next.js](https://nextjs.org/docs/app/building-your-application/optimizing/metadata).
 
 </Step>
 
-<Step number={9} title="Internacionalización de tu sitemap.xml y robots.txt" isOptional={true}>
+<Step number={9} title="Internacionalización de su sitemap.xml y robots.txt" isOptional={true}>
 
-Para internacionalizar tu `sitemap.xml` y `robots.txt`, puedes usar la función `getMultilingualUrls` proporcionada por Intlayer. Esta función te permite generar URLs multilingües para tu sitemap.
+Para internacionalizar su `sitemap.xml` y `robots.txt`, puede utilizar la función `getMultilingualUrls` proporcionada por Intlayer. Esta función le permite generar URLs multilingües para su mapa del sitio.
 
 ```tsx fileName="src/app/sitemap.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { getMultilingualUrls } from "intlayer";
@@ -885,18 +864,12 @@ export const LocaleSwitcher: FC = () => {
 ```tsx fileName="src/components/LocaleSwitcher.tsx"
 "use client";
 
-import { useRouter } from "next/navigation";
 import { useLocale } from "next-intlayer";
 import { getLocalizedUrl } from "intlayer";
 
 // ... Resto del código
 
-const router = useRouter();
-const { setLocale } = useLocale({
-  onLocaleChange: (locale) => {
-    router.push(getLocalizedUrl(pathWithoutLocale, locale));
-  },
-});
+const { setLocale } = useLocale();
 
 return (
   <button onClick={() => setLocale(Locales.FRENCH)}>Cambiar a francés</button>
@@ -1042,7 +1015,6 @@ bun add @intlayer/swc --dev
 > Nota: Este paquete no se instala por defecto porque los plugins SWC aún son experimentales en Next.js. Esto podría cambiar en el futuro.
 >
 > Nota: Si establece la opción como `importMode: 'dynamic'` o `importMode: 'fetch'` (en la configuración del diccionario), dependerá de Suspense, por lo que tendrá que envolver sus llamadas a `useIntlayer` en un límite de `Suspense`. Eso significa que no podrá usar `useIntlayer` directamente en el nivel superior de su componente Página / Layout.
-> </Step>
 
 </Step>
 
@@ -1086,7 +1058,7 @@ export default config;
 ```
 
 <Tabs>
- <Tab value='Comando de extracción'>
+<Tab value='Extract command'>
 
 Ejecuta el extractor para transformar tus componentes y extraer el contenido
 
@@ -1106,8 +1078,8 @@ yarn intlayer extract
 bun x intlayer extract
 ```
 
- </Tab>
- <Tab value='Compilador Babel'>
+</Tab>
+<Tab value='Babel compiler'>
 
 > Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
 
@@ -1158,7 +1130,7 @@ yarn build # O yarn dev
 bun run build # Or bun run dev
 ```
 
- </Tab>
+</Tab>
 </Tabs>
 </Step>
 
@@ -1231,4 +1203,122 @@ Para más detalles sobre cómo usar la extensión, consulta la [documentación d
 ### Ir más allá
 
 Para ir más allá, puedes implementar el [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md) o externalizar tu contenido usando el [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md).
-````
+
+## Preguntas frecuentes
+
+<FAQ>
+
+<Question title="¿Qué soluciones existen para internacionalizar una aplicación Next.js?">
+
+Next.js no tiene una capa de mensajes integrada desde que el campo `i18n` de `next.config.js` dejó de aplicarse al App Router, así que la capa de localización siempre es una elección de biblioteca:
+
+- **`next-intl`**, **`i18next` / `next-i18next`** y **`react-intl`**: las opciones históricas, basadas en catálogos de mensajes JSON o ICU cargados por espacio de nombres.
+- **`Lingui`**: basada en extracción, con mensajes ICU compilados en tiempo de compilación.
+- **`Intlayer`**: contenido declarado junto a cada componente, compilado en tiempo de compilación en diccionarios por componente, totalmente tipado, con traducción con IA, un editor visual y un CMS incluidos.
+
+La diferencia práctica es lo que llega al navegador. Las bibliotecas basadas en espacios de nombres entregan catálogos JSON completos a una página, mientras que Intlayer entrega solo el contenido que usan los componentes renderizados, lo que recorta el tamaño del bundle y de la página hasta en un 50%. Consulta [por qué Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/interest_of_intlayer.md) y el [benchmark de i18n de Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/nextjs.md).
+
+</Question>
+
+<Question title="¿Cuánto añade la i18n al tamaño del bundle de mi aplicación Next.js?">
+
+Mucho menos que una configuración basada en espacios de nombres, porque una página nunca descarga un catálogo que no renderiza. Los Server Components resuelven su contenido en el servidor, y el compilador de tiempo de compilación reemplaza las llamadas a `useIntlayer` por las entradas de diccionario exactas que usa un componente, de modo que se descartan las claves sin usar y los idiomas sin usar, y los [diccionarios dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md) reparten el resto por idioma. Frente a las alternativas habituales, Intlayer reduce el tamaño del bundle y de la página hasta en un 50%. Consulta la [optimización del bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/bundle_optimization.md) y el [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/nextjs.md).
+
+</Question>
+
+<Question title="¿Puedo migrar desde `next-intl`, `next-i18next` o `i18next` sin reescribir mis componentes?">
+
+Sí, y hay dos caminos. Puedes migrar el contenido de forma progresiva con la [guía de migración de next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/migration_from_next-intl_to_intlayer.md) o la [guía de migración de i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/migration_from_i18next_to_intlayer.md). O puedes mantener tu API actual por completo: los [adaptadores de compatibilidad](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/index.md) exponen exactamente la misma API que `next-intl`, `react-i18next` y `react-intl`, pero servida por diccionarios de Intlayer, así que cambian los imports y el código de los componentes no.
+
+</Question>
+
+<Question title="¿Puedo conservar mis archivos de traducción JSON existentes?">
+
+Sí. El [plugin de sincronización JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-json.md) mantiene tus archivos `/messages/{locale}/{namespace}.json` como fuente de verdad y genera diccionarios de Intlayer a partir de ellos, en ambas direcciones. Un [plugin de sincronización PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-po.md) hace lo mismo para los catálogos gettext, y los [archivos por idioma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/per_locale_file.md) te permiten dividir el contenido por idioma en lugar de agrupar los idiomas en un solo archivo.
+
+</Question>
+
+<Question title="¿Tengo que trasladar mi contenido clave por clave?">
+
+No. Ejecuta `npx intlayer extract` e Intlayer lee tus componentes, extrae las cadenas visibles para el usuario y escribe un archivo `.content` junto a cada uno, así que revisas un diff en lugar de copiar cadenas a un catálogo una por una. El paso 14 de esta guía lo explica paso a paso.
+
+Para una canalización totalmente automatizada, el [compilador de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compiler.md) hace lo mismo en tiempo de compilación: escanea tu código JSX, TSX, Vue y Svelte en cada cambio, genera los diccionarios y los mantiene sincronizados mediante el reemplazo de módulos en caliente, así que no hay ninguna clave que mantener a mano.
+
+Conviene conocer dos límites antes de activar el compilador. Funciona por análisis estático, así que las cadenas que solo existen en tiempo de ejecución, como los códigos de error de la API o los campos del CMS, quedan fuera de su alcance. Y tiene que distinguir el texto visible para el usuario de la lógica de la aplicación, como `className="active"` o un código de estado, lo que requiere unas pocas anotaciones en una base de código grande. El [comando extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/extract.md) evita ambos manteniéndote en el proceso.
+
+</Question>
+
+<Question title="¿Qué herramientas para editores y agentes de IA están disponibles?">
+
+Cinco piezas, todas opcionales:
+
+- **[Extensión de VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/vs_code_extension.md)**: salta de una clave `useIntlayer` al archivo de contenido que la declara, extrae contenido de un componente y ejecuta build, fill, test, push y pull desde la paleta de comandos o desde una pestaña de Intlayer dedicada.
+- **[Servidor LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/lsp.md)**: el mismo conocimiento en cualquier editor que hable LSP, con ir a la definición, buscar todas las referencias, vistas previas al pasar el cursor de un valor traducido, autocompletado de claves y campos, y un aviso cuando una clave no está declarada en ninguna parte. También resuelve las llamadas a `i18next`, `react-i18next`, `next-intl` y `use-intl`, lo que ayuda durante la migración.
+- **[Servidor MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/mcp_server.md)**: expone la documentación y la CLI de Intlayer a Cursor, VS Code, Claude Desktop, Claude Code y ChatGPT, para que un asistente responda a partir de la documentación actual en lugar de adivinar, y pueda ejecutar comandos como `intlayer fill` por sí mismo.
+- **[Habilidades para agentes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/agent_skills.md)**: habilidades específicas como `intlayer-config`, `intlayer-cli` e `intlayer-content`, además de una por framework, que enseñan a un agente tu configuración de enrutamiento y los tipos de nodo de contenido.
+- **[Plugin de ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/eslint.md)**: `no-raw-text` marca las cadenas codificadas de forma fija, con reglas adicionales para claves de diccionario estáticas y contenido sin usar.
+
+</Question>
+
+<Question title="¿Intlayer funciona con el App Router de Next.js y los React Server Components?">
+
+Sí. `next-intlayer` está construido para el App Router: el contenido se resuelve en el servidor dentro de los Server Components, así que no se envía ningún diccionario al cliente para el texto renderizado en el servidor. Los Client Components usan el mismo hook `useIntlayer` a través del proveedor. Intlayer no bloquea el renderizado estático, y es compatible con Turbopack.
+
+</Question>
+
+<Question title="¿Qué versiones de Next.js admite Intlayer?">
+
+Intlayer es compatible con Next.js 12, 13, 14, 15 y 16. Esta guía cubre Next.js 16. Para configuraciones más antiguas, sigue la [guía de Next.js 15](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_15.md), la [guía de Next.js 14](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_14.md) o la [guía del Pages Router](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_page_router.md).
+
+</Question>
+
+<Question title="¿Tengo que poner el idioma en la URL, como /fr/about?">
+
+No. El esquema de URL es una opción de configuración, no una restricción. `routing.mode` acepta:
+
+- `"prefix-no-default"` (por defecto): `/about` para el idioma por defecto, `/fr/about` para los demás.
+- `"prefix-all"`: todos los idiomas llevan prefijo, `/en/about` y `/fr/about`.
+- `"no-prefix"`: sin idioma en la ruta, resuelto a partir de una cookie, una cabecera o un dominio.
+- `"search-params"`: `/about?locale=fr`.
+
+También puedes asignar cada idioma a su propio dominio con `routing.domains`. Consulta la [referencia de configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md) y la [guía sin ruta de idioma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_no_locale_path.md).
+
+</Question>
+
+<Question title="¿Cómo añado etiquetas hreflang y metadatos localizados para SEO?">
+
+Usa la función `generateMetadata` de Next.js junto con `getMultilingualUrls` de Intlayer. Construye el mapa `alternates.languages` para cada idioma declarado, incluida la entrada `x-default`, para que los motores de búsqueda sirvan la versión de idioma correcta. La misma utilidad localiza `sitemap.ts` y `robots.ts`. El paso 8 y el paso 9 de esta guía muestran el código completo.
+
+</Question>
+
+<Question title="¿Cómo traduzco una aplicación Next.js automáticamente con IA?">
+
+Ejecuta `npx intlayer fill`. La CLI detecta las traducciones que faltan en tus archivos de contenido y las rellena con el LLM de tu elección, usando tu propio proveedor y tu clave de API, así que le pagas directamente al proveedor y nada pasa por un tercero. Consulta el [comando fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/fill.md) y la [integración de CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/CI_CD.md).
+
+</Question>
+
+<Question title="¿Intlayer admite plurales, género, condiciones y texto enriquecido?">
+
+Sí. Las declaraciones de contenido admiten [formas plurales](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/plurial.md), [contenido según el género](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/gender.md), condiciones, [inserciones](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/insertion.md) para valores interpolados, y [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/markdown.md) para texto enriquecido como páginas legales o cuerpos de blog. Los números, las fechas y las monedas los gestionan los [formateadores](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/formatters.md).
+
+</Question>
+
+<Question title="¿Cómo pueden editar el contenido los traductores y las personas que no programan?">
+
+Dos opciones, ambas opcionales. El [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md) se ejecuta en tu propia infraestructura y permite que cualquiera haga clic en el texto de tu sitio para editarlo en su sitio. El [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md) externaliza el contenido para que pueda actualizarse sin un despliegue, con la [sincronización en vivo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/live.md) reflejando los cambios en tiempo de ejecución.
+
+</Question>
+
+<Question title="¿Cómo detecto las traducciones que faltan antes de publicar?">
+
+Ejecuta `npx intlayer test` en CI. Falla la build cuando a un idioma declarado le falta contenido, así que una cadena sin traducir nunca llega a producción. La [extensión de VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/vs_code_extension.md) muestra los mismos errores mientras escribes, y el [plugin de ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/eslint.md) y su regla `no-raw-text` detectan las cadenas codificadas de forma fija. Consulta [probar tu contenido](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/testing.md).
+
+</Question>
+
+<Question title="¿Es Intlayer gratuito y de código abierto?">
+
+Sí. Intlayer es de código abierto bajo la licencia Apache 2.0, y toda la biblioteca, la CLI, el editor visual y el compilador son de uso gratuito, incluido el uso comercial. El CMS alojado es un servicio de pago opcional, y también puede [autoalojarse](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/self_hosting.md).
+
+</Question>
+
+</FAQ>

package/docs/es/intlayer_with_nextjs_compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-01-10
-updatedAt: 2026-06-23
+updatedAt: 2026-08-30
 title: "Next.js i18n - Guía completa para traducir tu aplicación"
 description: "Sin más i18next. La guía 2026 para crear una aplicación Next.js multilingüe (i18n). Traduce con agentes de IA y optimiza el tamaño del bundle, SEO y rendimiento."
 keywords:
@@ -293,7 +293,7 @@ Simplemente escriba sus componentes con cadenas de texto codificadas en su idiom
 Ejemplo de cómo podría verse su página:
 
 <Tabs>
-  <Tab value="Code">
+<Tab value="Code">
 
 ```tsx fileName="src/app/page.tsx"
 import type { FC } from "react";
@@ -320,8 +320,8 @@ export default async function Page() {
 }
 ```
 
-  </Tab>
-  <Tab value="Output">
+</Tab>
+<Tab value="Output">
 
 ```ts fileName="i18n/page-content.content.tsx"
 {
@@ -343,8 +343,11 @@ export default async function Page() {
 }
 ```
 
+</Tab>
+</Tabs>
+
 <Tabs>
-  <Tab label='Intlayer >=9.4' value='>=9.4'>
+<Tab label='Intlayer >=9.4' value='>=9.4'>
 
 ```tsx fileName="src/app/page.tsx"
 import { type FC } from "react";
@@ -376,7 +379,8 @@ export default async function Page() {
 - **`IntlayerProvider`** se monta una sola vez, en el layout raíz. Proporciona la locale tanto a componentes de servidor como de cliente, por lo que las páginas ya no se envuelven a sí mismas.
 - Sin un segmento de ruta `[locale]`, la locale siempre proviene de la solicitud — el encabezado `x-intlayer-locale` establecido por el proxy de Intlayer, luego la cookie de locale — que los hooks del servidor leen por su cuenta cuando el proveedor no se ha ejecutado.
 
-</Tabs>
+</Tab>
+<Tab label='Intlayer <9.4' value='<9.4'>
 
 ```tsx fileName="src/app/page.tsx"
 import { type FC } from "react";
@@ -410,7 +414,7 @@ export default async function Page() {
 
   > Layout and page cannot share a common server context because the server context system is based on a per-request data store (via [React's cache](https://react.dev/reference/react/cache) mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.
 
-  </Tab>
+</Tab>
 
 </Tabs>
 
@@ -475,7 +479,7 @@ export const config = {
 
 </Step>
 
-<Step number={8} title="Cambiar el idioma de su contenido" isOptional={true}>
+<Step number={9} title="Cambiar el idioma de su contenido" isOptional={true}>
 
 Para cambiar el idioma de su contenido en Next.js, la forma recomendada es utilizar el componente `Link` para redirigir a los usuarios a la página localizada correspondiente. El componente `Link` permite la pre-carga de la página, lo que ayuda a evitar una recarga completa de la página.
 
@@ -599,7 +603,7 @@ export default config;
 ```
 
 <Tabs>
- <Tab value='Comando de extracción'>
+<Tab value='Extract command'>
 
 Ejecuta el extractor para transformar tus componentes y extraer el contenido
 
@@ -619,8 +623,8 @@ yarn intlayer extract
 bun x intlayer extract
 ```
 
- </Tab>
- <Tab value='Compilador Babel'>
+</Tab>
+<Tab value='Babel compiler'>
 
 > Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
 
@@ -671,7 +675,7 @@ yarn build # O yarn dev
 bun run build # Or bun run dev
 ```
 
- </Tab>
+</Tab>
 </Tabs>
 </Step>
 
@@ -726,3 +730,109 @@ Para obtener más detalles sobre cómo usar la extensión, consulte la [document
 ### Ir más allá
 
 Para ir más allá, puede implementar el [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md) o externalizar su contenido utilizando el [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md).
+
+## Preguntas frecuentes
+
+<FAQ>
+
+<Question title="¿Qué soluciones existen para internacionalizar una aplicación Next.js?">
+
+El campo `i18n` de `next.config.js` no se aplica al App Router, así que la capa de localización siempre es una elección de biblioteca:
+
+- **`next-intl`**, **`next-i18next` / `i18next`** y **`react-intl`**: catálogos JSON o ICU cargados por espacio de nombres, con claves escritas a mano en cada punto de uso.
+- **`Lingui`**: basada en extracción, con mensajes ICU compilados en tiempo de compilación.
+- **`Intlayer`**: contenido compilado a partir de tus componentes en tiempo de compilación, totalmente tipado, con traducción con IA, un editor visual y un CMS.
+
+Esta guía usa la configuración con el compilador, donde sigues escribiendo cadenas normales en tus componentes y los diccionarios se generan por ti. Consulta [por qué Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/interest_of_intlayer.md) y el [benchmark de i18n de Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/nextjs.md).
+
+</Question>
+
+<Question title="¿Cuánto añade la i18n al tamaño del bundle de mi aplicación Next.js?">
+
+Mucho menos que una configuración basada en espacios de nombres, porque una página nunca descarga un catálogo que no renderiza. Los Server Components resuelven su contenido en el servidor, y el compilador de tiempo de compilación reemplaza las llamadas a `useIntlayer` por las entradas de diccionario exactas que usa un componente, de modo que se descartan las claves sin usar y los idiomas sin usar, y los [diccionarios dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md) reparten el resto por idioma. Frente a las alternativas habituales, Intlayer reduce el tamaño del bundle y de la página hasta en un 50%. Consulta la [optimización del bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/bundle_optimization.md) y el [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/nextjs.md).
+
+</Question>
+
+<Question title="¿Puedo migrar desde `next-intl`, `next-i18next` o `i18next` sin reescribir mis componentes?">
+
+Sí, y hay dos caminos. Puedes migrar el contenido de forma progresiva con la [guía de migración de next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/migration_from_next-intl_to_intlayer.md) o la [guía de migración de i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/migration_from_i18next_to_intlayer.md). O puedes mantener tu API actual por completo: los [adaptadores de compatibilidad](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/index.md) exponen exactamente la misma API que `next-intl`, `react-i18next` y `react-intl`, pero servida por diccionarios de Intlayer, así que cambian los imports y el código de los componentes no.
+
+</Question>
+
+<Question title="¿Puedo conservar mis archivos de traducción JSON existentes?">
+
+Sí. El [plugin de sincronización JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-json.md) mantiene tus archivos `/messages/{locale}/{namespace}.json` como fuente de verdad y genera diccionarios de Intlayer a partir de ellos, en ambas direcciones. Un [plugin de sincronización PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-po.md) hace lo mismo para los catálogos gettext, y los [archivos por idioma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/per_locale_file.md) te permiten dividir el contenido por idioma en lugar de agrupar los idiomas en un solo archivo.
+
+</Question>
+
+<Question title="¿Tengo que trasladar mi contenido clave por clave?">
+
+No, y eso es lo que configura esta guía. Escribes tus componentes con cadenas normales en tu idioma por defecto, y el [compilador de Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compiler.md) escanea el código en cada build, extrae el texto visible para el usuario y genera los diccionarios, así que no hay ninguna clave que crear ni mantener a mano.
+
+Conviene conocer dos límites. El compilador funciona por análisis estático, así que las cadenas que solo existen en tiempo de ejecución, como los códigos de error de la API o los campos del CMS, quedan fuera de su alcance y siguen necesitando un diccionario declarado. Y tiene que distinguir el texto visible para el usuario de la lógica de la aplicación, como `className="active"` o un código de estado, lo que requiere unas pocas anotaciones en una base de código grande.
+
+Si prefieres mantener el control, `npx intlayer extract` hace la misma extracción una sola vez, sobre los archivos que elijas, y escribe un archivo `.content` junto a cada componente para que lo revises. Consulta el [comando extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/extract.md).
+
+</Question>
+
+<Question title="¿Qué herramientas para editores y agentes de IA están disponibles?">
+
+Cinco piezas, todas opcionales:
+
+- **[Extensión de VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/vs_code_extension.md)**: salta de una clave `useIntlayer` al archivo de contenido que la declara, extrae contenido de un componente y ejecuta build, fill, test, push y pull desde la paleta de comandos o desde una pestaña de Intlayer dedicada.
+- **[Servidor LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/lsp.md)**: el mismo conocimiento en cualquier editor que hable LSP, con ir a la definición, buscar todas las referencias, vistas previas al pasar el cursor de un valor traducido, autocompletado de claves y campos, y un aviso cuando una clave no está declarada en ninguna parte. También resuelve las llamadas a `i18next`, `react-i18next`, `next-intl` y `use-intl`, lo que ayuda durante la migración.
+- **[Servidor MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/mcp_server.md)**: expone la documentación y la CLI de Intlayer a Cursor, VS Code, Claude Desktop, Claude Code y ChatGPT, para que un asistente responda a partir de la documentación actual en lugar de adivinar, y pueda ejecutar comandos como `intlayer fill` por sí mismo.
+- **[Habilidades para agentes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/agent_skills.md)**: habilidades específicas como `intlayer-config`, `intlayer-cli` e `intlayer-content`, además de una por framework, que enseñan a un agente tu configuración de enrutamiento y los tipos de nodo de contenido.
+- **[Plugin de ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/eslint.md)**: `no-raw-text` marca las cadenas codificadas de forma fija, con reglas adicionales para claves de diccionario estáticas y contenido sin usar.
+
+</Question>
+
+<Question title="¿Debería usar el compilador o declarar mi contenido yo mismo?">
+
+Usa el compilador cuando quieras añadir i18n a una base de código existente con el menor trastorno: tus componentes se quedan como están y los diccionarios los siguen. Declara el contenido tú mismo, como muestra la [guía estándar de Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_16.md), cuando quieras un control explícito sobre las claves, la estructura y la reutilización. Los dos pueden coexistir en la misma capa de diccionarios.
+
+</Question>
+
+<Question title="¿Por qué necesito configurar Babel?">
+
+Lo cubre el paso 4. El compilador lee tus componentes a través de una transformación de Babel, así que Next.js necesita un `babel.config.js` para que se ejecute la pasada de extracción. `npx intlayer init --interactive` lo genera por ti cuando eliges la configuración con el compilador.
+
+</Question>
+
+<Question title="¿Qué ocurre con las cadenas que el compilador no puede ver?">
+
+Se quedan sin traducir, porque el compilador funciona por análisis estático. Cualquier cosa montada en tiempo de ejecución, como un mensaje de error de la API, un campo del CMS o una cadena construida por concatenación, tiene que declararse en un archivo de contenido de la forma habitual. Ejecuta `npx intlayer test` para encontrar lo que falta.
+
+</Question>
+
+<Question title="¿Cómo relleno las traducciones que faltan?">
+
+Lo cubre el paso 7. `npx intlayer fill` envía el contenido extraído al LLM de tu elección, usando tu propio proveedor y tu clave de API, y `--git-diff` limita la ejecución a lo que cambió en la rama. Consulta el [comando fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/fill.md) y la [integración de CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/CI_CD.md).
+
+</Question>
+
+<Question title="¿Cómo se detecta el idioma?">
+
+El paso 5 lo lee en tus páginas y el paso 8 añade el proxy que lo resuelve a partir de la URL, una cookie o la cabecera `Accept-Language`. `routing.mode` decide si el idioma aparece siquiera en la ruta. Consulta la [referencia de configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md).
+
+</Question>
+
+<Question title="¿Intlayer admite plurales, género y texto enriquecido?">
+
+Sí: [formas plurales](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/plurial.md), [contenido según el género](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/gender.md), condiciones, [inserciones](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/insertion.md), [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dictionary/markdown.md) y [formateadores](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/formatters.md) para números, fechas y monedas.
+
+</Question>
+
+<Question title="¿Cómo pueden los traductores editar el contenido sin tocar el código?">
+
+A través del [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_visual_editor.md), que se ejecuta en tu propia infraestructura y permite que cualquiera edite texto en su sitio en la aplicación en ejecución, o del [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md), que externaliza el contenido para que pueda cambiar sin un despliegue.
+
+</Question>
+
+<Question title="¿Es Intlayer gratuito y de código abierto?">
+
+Sí, bajo la licencia Apache 2.0, uso comercial incluido. El CMS alojado es un servicio de pago opcional que también puede [autoalojarse](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/self_hosting.md).
+
+</Question>
+
+</FAQ>