@intlayer/docs 9.4.1 → 9.4.3

package/docs/es/bundle_optimization.md

@@ -43,139 +43,6 @@ Por ejemplo, una aplicación con 10 páginas traducidas a 10 idiomas podría pro
 
 <TOC />
 
-## Analiza tu paquete
-
-Analizar tu paquete es el primer paso para identificar archivos JSON "pesados" y oportunidades de división de código (code-splitting). Estas herramientas generan un treemap visual del código compilado de tu aplicación, permitiéndote ver exactamente qué bibliotecas consumen más espacio.
-
-<Tabs>
- <Tab value="vite">
-
-### Vite / Rollup
-
-Vite utiliza Rollup bajo el capó. El complemento `rollup-plugin-visualizer` genera un archivo HTML interactivo que muestra el tamaño de cada módulo en tu gráfico de dependencias.
-
-```bash
-npm install -D rollup-plugin-visualizer
-```
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { visualizer } from "rollup-plugin-visualizer";
-
-export default defineConfig({
-  plugins: [
-    visualizer({
-      open: true, // Abre automáticamente el informe en tu navegador
-      filename: "stats.html",
-      gzipSize: true,
-      brotliSize: true,
-    }),
-  ],
-});
-```
-
- </Tab>
- <Tab value="nextjs (turbopack)">
-
-### Next.js (Turbopack)
-
-Para proyectos que usan App Router y Turbopack, Next.js incluye un analizador experimental incorporado que no requiere dependencias adicionales.
-
-```bash packageManager='npm'
-npx next experimental-analyze
-```
-
-```bash packageManager='yarn'
-yarn next experimental-analyze
-```
-
-```bash packageManager='pnpm'
-pnpm next experimental-analyze
-```
-
-```bash packageManager='bun'
-bun next experimental-analyze
-```
-
- </Tab>
- <Tab value="nextjs (Webpack)">
-
-### Next.js (Webpack)
-
-Si estás usando el bundler predeterminado de Webpack en Next.js, usa el analizador de paquetes oficial. Actívalo definiendo una variable de entorno durante la compilación.
-
-```bash packageManager='npm'
-npm install -D @next/bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D @next/bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D @next/bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d @next/bundle-analyzer
-```
-
-```javascript fileName="next.config.js"
-const withBundleAnalyzer = require("@next/bundle-analyzer")({
-  enabled: process.env.ANALYZE === "true",
-});
-
-module.exports = withBundleAnalyzer({
-  // Tu configuración de Next.js
-});
-```
-
-**Uso:**
-
-```bash
-ANALYZE=true npm run build
-```
-
- </Tab>
- <Tab value="Webpack (CRA / Angular / etc)">
-
-### Webpack estándar
-
-Para Create React App (ejected), Angular, o configuraciones de Webpack personalizadas, utiliza el estándar de la industria `webpack-bundle-analyzer`.
-
-```bash packageManager='npm'
-npm install -D webpack-bundle-analyzer
-```
-
-```bash packageManager='yarn'
-yarn add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='pnpm'
-pnpm add -D webpack-bundle-analyzer
-```
-
-```bash packageManager='bun'
-bun add -d webpack-bundle-analyzer
-```
-
-```typescript fileName="webpack.config.ts"
-import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
-
-export default {
-  plugins: [
-    new BundleAnalyzerPlugin({
-      analyzerMode: "static",
-      reportFilename: "bundle-analyzer.html",
-      openAnalyzer: false,
-    }),
-  ],
-};
-```
-
- </Tab>
-</Tabs>
-
 ## Cómo funciona
 
 Intlayer utiliza un **enfoque por componente**. A diferencia de los archivos JSON globales, el contenido se define junto a o dentro de tus componentes. Durante el proceso de compilación, Intlayer:
@@ -189,59 +56,6 @@ Esto asegura que:
 - Si un componente no se importa, su contenido no se incluye en el paquete (Eliminación de código muerto o Dead Code Elimination).
 - Si un componente se carga mediante lazy loading, su contenido también se carga dinámicamente.
 
-## Referencia de Plugins
-
-La optimización de compilación de Intlayer se divide en varios complementos discretos, cada uno con una responsabilidad única. Entender lo que hace cada uno evita la confusión al configurarlos.
-
-### Plugins de Babel (`@intlayer/babel`)
-
-Se utilizan directamente en `babel.config.js` para configuraciones basadas en Webpack (Next.js con Babel, CRA, Webpack personalizado, etc.).
-
-La siguiente tabla los enumera en su orden de pipeline requerido (el mismo orden en que deben aparecer en `babel.config.js`):
-
-| Plugin                        | Qué hace                                                                                                                                    |
-| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
-| `intlayerExtractBabelPlugin`  | Analiza archivos `.content.ts` y escribe los diccionarios compilados en `.intlayer/`                                                        |
-| `intlayerPurgeBabelPlugin`    | Analiza todos los archivos fuente y elimina **los campos de contenido no utilizados** de los archivos JSON `.intlayer/**/*.json`            |
-| `intlayerMinifyBabelPlugin`   | **Renombra las claves de campos de contenido** por alias alfabéticos cortos (`title` → `a`) tanto en archivos JSON como en el código fuente |
-| `intlayerOptimizeBabelPlugin` | Reescribe `useIntlayer('key')` → `useDictionary(hash)` e inyecta la declaración `import` del diccionario correspondiente                    |
-
-> **El orden de los plugins es importante.** En tu `babel.config.js`, los complementos de purga (purge) y minificación (minify) deben aparecer **antes** del complemento de optimización. La fase de optimización reemplaza `useIntlayer('key')` con una llamada opaca `useDictionary(hash)`, lo que borra la información de clave del diccionario que las fases de purga y minificación necesitan para saber qué campos se usan.
-
-Cada complemento de Babel cuenta con una función auxiliar de opciones que lee tu `intlayer.config.ts` una vez en tiempo de carga y devuelve los valores pre-resueltos:
-
-| Helper de opciones           | Utilizado con                 |
-| :--------------------------- | :---------------------------- |
-| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
-| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
-
-### Plugins de Vite (`vite-intlayer`)
-
-Los usuarios de Vite **nunca los configuran directamente**. Se vinculan de forma automática al invocar `withIntlayer()` en `vite.config.ts`. Las variables `build.purge` y `build.minify` en `intlayer.config.ts` alternan el comportamiento correspondiente sin necesidad de registrar ningún otro complemento.
-
-| Plugin interno de Vite | Comportamiento equivalente                                                                                   |
-| :--------------------- | :----------------------------------------------------------------------------------------------------------- |
-| Analizador de uso      | Igual que la fase de análisis del `intlayerPurgeBabelPlugin`                                                 |
-| Poda de diccionarios   | Igual que la fase de escritura JSON del `intlayerPurgeBabelPlugin`                                           |
-| Minificar diccionario  | Igual que la fase de escritura JSON del `intlayerMinifyBabelPlugin`                                          |
-| Transformación Babel   | Igual que la fase de renombramiento en código de `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
-
-### Plugin SWC (`@intlayer/swc`)
-
-Los usuarios de Next.js **tampoco configuran esto directamente**. Desde la **v9.2.1**, `withIntlayer()` en `next.config.ts` ejecuta el pipeline completo — purga, minificación y reescritura de imports — únicamente a partir de las banderas `build.purge` y `build.minify`.
-
-El trabajo se divide en dos, porque un plugin Wasm de SWC transforma un archivo a la vez y sin acceso al sistema de archivos:
-
-| Pasada                                                 | Dónde se ejecuta                 | Qué hace                                                                                                  |
-| :----------------------------------------------------- | :------------------------------- | :-------------------------------------------------------------------------------------------------------- |
-| Análisis de uso + purga/minificación de JSON           | Node, dentro de `withIntlayer()` | Lee cada archivo fuente de componente, reescribe `.intlayer/**/*.json` y produce las tablas de renombrado |
-| Reescritura del código fuente (`content.title` → `.a`) | `@intlayer/swc` (Wasm)           | Aplica las tablas de renombrado a los accesos a propiedades correspondientes en tu código                 |
-| Reescritura de imports (`useIntlayer` → dict)          | `@intlayer/swc` (Wasm)           | Igual que `intlayerOptimizeBabelPlugin`                                                                   |
-
-Decidir _qué_ campos no se usan y _qué_ alias recibe cada uno requiere estado entre archivos y E/S de archivos, por lo que esa mitad se ejecuta en Node; el plugin SWC solo recibe las tablas resultantes.
-
 ## Configuración por plataforma
 
 <Tabs>
@@ -405,6 +219,59 @@ module.exports = {
  </Tab>
 </Tabs>
 
+## Referencia de Plugins
+
+La optimización de compilación de Intlayer se divide en varios complementos discretos, cada uno con una responsabilidad única. Entender lo que hace cada uno evita la confusión al configurarlos.
+
+### Plugins de Babel (`@intlayer/babel`)
+
+Se utilizan directamente en `babel.config.js` para configuraciones basadas en Webpack (Next.js con Babel, CRA, Webpack personalizado, etc.).
+
+La siguiente tabla los enumera en su orden de pipeline requerido (el mismo orden en que deben aparecer en `babel.config.js`):
+
+| Plugin                        | Qué hace                                                                                                                                    |
+| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
+| `intlayerExtractBabelPlugin`  | Analiza archivos `.content.ts` y escribe los diccionarios compilados en `.intlayer/`                                                        |
+| `intlayerPurgeBabelPlugin`    | Analiza todos los archivos fuente y elimina **los campos de contenido no utilizados** de los archivos JSON `.intlayer/**/*.json`            |
+| `intlayerMinifyBabelPlugin`   | **Renombra las claves de campos de contenido** por alias alfabéticos cortos (`title` → `a`) tanto en archivos JSON como en el código fuente |
+| `intlayerOptimizeBabelPlugin` | Reescribe `useIntlayer('key')` → `useDictionary(hash)` e inyecta la declaración `import` del diccionario correspondiente                    |
+
+> **El orden de los plugins es importante.** En tu `babel.config.js`, los complementos de purga (purge) y minificación (minify) deben aparecer **antes** del complemento de optimización. La fase de optimización reemplaza `useIntlayer('key')` con una llamada opaca `useDictionary(hash)`, lo que borra la información de clave del diccionario que las fases de purga y minificación necesitan para saber qué campos se usan.
+
+Cada complemento de Babel cuenta con una función auxiliar de opciones que lee tu `intlayer.config.ts` una vez en tiempo de carga y devuelve los valores pre-resueltos:
+
+| Helper de opciones           | Utilizado con                 |
+| :--------------------------- | :---------------------------- |
+| `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
+| `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
+| `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
+
+### Plugins de Vite (`vite-intlayer`)
+
+Los usuarios de Vite **nunca los configuran directamente**. Se vinculan de forma automática al invocar `withIntlayer()` en `vite.config.ts`. Las variables `build.purge` y `build.minify` en `intlayer.config.ts` alternan el comportamiento correspondiente sin necesidad de registrar ningún otro complemento.
+
+| Plugin interno de Vite | Comportamiento equivalente                                                                                   |
+| :--------------------- | :----------------------------------------------------------------------------------------------------------- |
+| Analizador de uso      | Igual que la fase de análisis del `intlayerPurgeBabelPlugin`                                                 |
+| Poda de diccionarios   | Igual que la fase de escritura JSON del `intlayerPurgeBabelPlugin`                                           |
+| Minificar diccionario  | Igual que la fase de escritura JSON del `intlayerMinifyBabelPlugin`                                          |
+| Transformación Babel   | Igual que la fase de renombramiento en código de `intlayerMinifyBabelPlugin` + `intlayerOptimizeBabelPlugin` |
+
+### Plugin SWC (`@intlayer/swc`)
+
+Los usuarios de Next.js **tampoco configuran esto directamente**. Desde la **v9.2.1**, `withIntlayer()` en `next.config.ts` ejecuta el pipeline completo — purga, minificación y reescritura de imports — únicamente a partir de las banderas `build.purge` y `build.minify`.
+
+El trabajo se divide en dos, porque un plugin Wasm de SWC transforma un archivo a la vez y sin acceso al sistema de archivos:
+
+| Pasada                                                 | Dónde se ejecuta                 | Qué hace                                                                                                  |
+| :----------------------------------------------------- | :------------------------------- | :-------------------------------------------------------------------------------------------------------- |
+| Análisis de uso + purga/minificación de JSON           | Node, dentro de `withIntlayer()` | Lee cada archivo fuente de componente, reescribe `.intlayer/**/*.json` y produce las tablas de renombrado |
+| Reescritura del código fuente (`content.title` → `.a`) | `@intlayer/swc` (Wasm)           | Aplica las tablas de renombrado a los accesos a propiedades correspondientes en tu código                 |
+| Reescritura de imports (`useIntlayer` → dict)          | `@intlayer/swc` (Wasm)           | Igual que `intlayerOptimizeBabelPlugin`                                                                   |
+
+Decidir _qué_ campos no se usan y _qué_ alias recibe cada uno requiere estado entre archivos y E/S de archivos, por lo que esa mitad se ejecuta en Node; el plugin SWC solo recibe las tablas resultantes.
+
 ## Configuración
 
 Puedes controlar cómo Intlayer optimiza el tamaño de tu paquete mediante la propiedad `build` en tu `intlayer.config.ts`.
@@ -650,3 +517,136 @@ const content = useDictionaryAsync({
 | **Llamadas de red (Fetch)** | 0 adicionales                               | 1 por key del diccionario                     |
 | **Tree Shaking**            | Presente desde el componente                | Desde el componente + Local                   |
 | **Mejor uso para:**         | Elementos visuales, Apps ligeras            | Enormes bloques de texto, Múltiples regiones  |
+
+## Analiza tu paquete
+
+Analizar tu paquete es la forma más directa de identificar archivos JSON "pesados" y oportunidades de división de código (code-splitting). Estas herramientas generan un treemap visual del código compilado de tu aplicación, permitiéndote ver exactamente qué bibliotecas consumen más espacio.
+
+<Tabs>
+ <Tab value="vite">
+
+### Vite / Rollup
+
+Vite utiliza Rollup bajo el capó. El complemento `rollup-plugin-visualizer` genera un archivo HTML interactivo que muestra el tamaño de cada módulo en tu gráfico de dependencias.
+
+```bash
+npm install -D rollup-plugin-visualizer
+```
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+
+export default defineConfig({
+  plugins: [
+    visualizer({
+      open: true, // Abre automáticamente el informe en tu navegador
+      filename: "stats.html",
+      gzipSize: true,
+      brotliSize: true,
+    }),
+  ],
+});
+```
+
+ </Tab>
+ <Tab value="nextjs (turbopack)">
+
+### Next.js (Turbopack)
+
+Para proyectos que usan App Router y Turbopack, Next.js incluye un analizador experimental incorporado que no requiere dependencias adicionales.
+
+```bash packageManager='npm'
+npx next experimental-analyze
+```
+
+```bash packageManager='yarn'
+yarn next experimental-analyze
+```
+
+```bash packageManager='pnpm'
+pnpm next experimental-analyze
+```
+
+```bash packageManager='bun'
+bun next experimental-analyze
+```
+
+ </Tab>
+ <Tab value="nextjs (Webpack)">
+
+### Next.js (Webpack)
+
+Si estás usando el bundler predeterminado de Webpack en Next.js, usa el analizador de paquetes oficial. Actívalo definiendo una variable de entorno durante la compilación.
+
+```bash packageManager='npm'
+npm install -D @next/bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D @next/bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D @next/bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d @next/bundle-analyzer
+```
+
+```javascript fileName="next.config.js"
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+
+module.exports = withBundleAnalyzer({
+  // Tu configuración de Next.js
+});
+```
+
+**Uso:**
+
+```bash
+ANALYZE=true npm run build
+```
+
+ </Tab>
+ <Tab value="Webpack (CRA / Angular / etc)">
+
+### Webpack estándar
+
+Para Create React App (ejected), Angular, o configuraciones de Webpack personalizadas, utiliza el estándar de la industria `webpack-bundle-analyzer`.
+
+```bash packageManager='npm'
+npm install -D webpack-bundle-analyzer
+```
+
+```bash packageManager='yarn'
+yarn add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='pnpm'
+pnpm add -D webpack-bundle-analyzer
+```
+
+```bash packageManager='bun'
+bun add -d webpack-bundle-analyzer
+```
+
+```typescript fileName="webpack.config.ts"
+import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
+
+export default {
+  plugins: [
+    new BundleAnalyzerPlugin({
+      analyzerMode: "static",
+      reportFilename: "bundle-analyzer.html",
+      openAnalyzer: false,
+    }),
+  ],
+};
+```
+
+ </Tab>
+</Tabs>

package/docs/es/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-22
+updatedAt: 2026-08-30
 title: Configuración (Configuration)
 description: Aprenda a configure Intlayer para su aplicación. Entienda los diversos ajustes y opciones disponibles para personalizar Intlayer según sus necesidades.
 keywords:
@@ -1124,3 +1124,101 @@ Ajustes que controlan el compilador de Intlayer, que extrae diccionarios directa
 | Campo     | Descripción                           | Tipo               |
 | --------- | ------------------------------------- | ------------------ |
 | `plugins` | Liste des plugins Intlayer à activer. | `IntlayerPlugin[]` |
+
+## Preguntas frecuentes
+
+<FAQ>
+
+<Question title="¿Dónde debe ubicarse el archivo intlayer.config.ts?">
+
+En la raíz de tu proyecto, junto a `package.json`. Intlayer también acepta `intlayer.config.js`, `intlayer.config.mjs`, `intlayer.config.cjs` y JSON, de modo que el archivo se adapta al sistema de módulos que use tu proyecto.
+
+</Question>
+
+<Question title="¿Cuánto añade la i18n al tamaño de mi bundle?">
+
+Mucho menos que una configuración basada en espacios de nombres, porque una página nunca descarga un catálogo que no renderiza. El marcado renderizado en el servidor resuelve 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. 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/index.md).
+
+</Question>
+
+<Question title="¿Puedo migrar desde `i18next`, `next-intl` o `react-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 i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/migration_from_i18next_to_intlayer.md) o 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 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 `i18next`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `use-intl`, `vue-i18n` y `Lingui`, 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 archivos fuente, 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. Consulta el [comando extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/extract.md).
+
+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 sobre código JSX, TSX, Vue y Svelte, generando los diccionarios en cada cambio para que no haya ninguna clave que mantener a mano. Funciona por análisis estático, así que las cadenas que solo existen en tiempo de ejecución quedan fuera de su alcance, y necesita unas pocas anotaciones para distinguir el texto visible para el usuario de la lógica de la aplicación.
+
+</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="¿Cómo añado un nuevo idioma a mi aplicación?">
+
+Añade el idioma a `internationalization.locales` y luego ejecuta `npx intlayer fill` para traducir a él el contenido existente. Los tipos generados se actualizan al mismo tiempo, así que cualquier archivo de contenido al que le falte el nuevo idioma se convierte en un error de tipo en lugar de un fallback silencioso.
+
+</Question>
+
+<Question title="¿Cómo elimino el prefijo de idioma de mis URL?">
+
+Establece `routing.mode`. El valor por defecto `"prefix-no-default"` da `/about` para el idioma por defecto y `/fr/about` para los demás. `"prefix-all"` pone prefijo a todos los idiomas. `"no-prefix"` mantiene el idioma completamente fuera de la ruta y lo resuelve a partir de una cookie, una cabecera o un dominio. `"search-params"` lo pone en la cadena de consulta como `/about?locale=fr`.
+
+</Question>
+
+<Question title="¿Puedo servir cada idioma desde su propio dominio?">
+
+Sí. `routing.domains` asigna un idioma a un nombre de host, por ejemplo `{ fr: 'example.fr', en: 'example.com' }`. El dominio identifica el idioma, así que no se añade prefijo a la ruta, y `getLocalizedUrl` devuelve una URL absoluta en el dominio correcto.
+
+</Question>
+
+<Question title="¿Cómo se detecta el idioma del usuario?">
+
+A través de `routing.storage`, que lista las fuentes que leer en orden, normalmente la URL, luego una cookie y luego la cabecera `Accept-Language`. Una elección explícita del usuario se conserva para que prevalezca en la siguiente visita.
+
+</Question>
+
+<Question title="¿Qué hace routing.enableProxy?">
+
+Controla el proxy de enrutamiento por idioma, el middleware que resuelve los prefijos y las redirecciones. Si no se establece, el proxy se ejecuta pero los servidores de desarrollo y de vista previa ignoran el idioma almacenado como fuente de redirección, lo que evita que te reboten a un idioma que no estás probando; en producción se comporta como si fuera `true`. Ponlo en `false` para gestionar tú mismo el enrutamiento por idioma.
+
+</Question>
+
+<Question title="¿Cuál es la diferencia entre importMode static, dynamic y fetch?">
+
+`"static"`, el valor por defecto, importa los diccionarios de forma estática para que se empaqueten y se lean de forma síncrona. `"dynamic"` los importa a través de Suspense, así que un idioma se descarga solo cuando un componente lo renderiza, que es lo que quieres para conjuntos de contenido grandes. `"fetch"` los recupera de la API de sincronización en vivo y recurre a `"dynamic"` si falla. Consulta la [optimización del bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/bundle_optimization.md) y los [diccionarios dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/index.md).
+
+</Question>
+
+<Question title="¿Dónde configuro el proveedor de IA y la clave de API para la traducción automática?">
+
+Ya sea en el archivo de configuración o en la línea de comandos con `--provider`, `--model` y `--api-key`. La clave sigue siendo tuya: las llamadas de traducción van desde tu máquina o tu runner de CI al proveedor que elijas, así que nada se enruta a través de un tercero. Consulta el [comando fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/cli/fill.md).
+
+</Question>
+
+<Question title="¿Necesito reiniciar el servidor de desarrollo tras cambiar la configuración?">
+
+Normalmente no. El watcher de Intlayer vigila el propio `intlayer.config.ts`: al guardar recarga la configuración y vuelve a preparar los diccionarios, así que añadir un idioma o cambiar un modo de enrutamiento se recoge como un cambio de contenido. Sin embargo, la configuración puede quedar cacheada por los sistemas. Reiniciar tu aplicación puede ser una buena solución.
+
+</Question>
+
+</FAQ>

package/docs/es/dictionary/content_file.md

@@ -366,15 +366,15 @@ Transforma el diccionario en un diccionario por localización donde cada campo d
 
 **Ejemplo:**
 
-```json
+```jsonc
 // Diccionario por idioma
 {
   "key": "about-page",
   "locale": "en",
   "content": {
     "title": "About Us", // Esto se convierte en un nodo de traducción para 'en'
-    "description": "Learn more about our company"
-  }
+    "description": "Learn more about our company",
+  },
 }
 ```
 
@@ -443,7 +443,7 @@ Instrucciones para rellenar automáticamente el contenido del diccionario desde
 
 **Ejemplos:**
 
-```json
+```jsonc
 // Habilitar para todas las locales
 {
   "autoFill": true

package/docs/es/dictionary/markdown.md

@@ -51,6 +51,7 @@ Puede declarar contenido Markdown usando la función `md` o simplemente como una
 
 <Tabs>
   <Tab label=".content.md" value=".content.md">
+
     A partir de la versión `8.10.0`, puede declarar contenido Markdown directamente en archivos `.content.md`. Intlayer detectará y analizará automáticamente el contenido Markdown.
 
     ```md fileName="markdown-file.en.content.md"
@@ -96,6 +97,7 @@ Puede declarar contenido Markdown usando la función `md` o simplemente como una
     ```
 
   </Tab>
+
   <Tab label="Archivos Externos" value="external-files">
     Importe archivos `.md` directamente usando la función `file`.
 
@@ -129,6 +131,7 @@ Puede declarar contenido Markdown usando la función `md` o simplemente como una
     ```
 
   </Tab>
+
 </Tabs>
 
 ## Renderización de Markdown
@@ -957,7 +960,21 @@ Estas utilidades renderizan **únicamente cadenas Markdown puras** y son indepen
   </Tab>
   <Tab label="Angular" value="angular">
 
-> MDX es compatible — cualquier nombre de componente utilizado dentro de tu Markdown (por ejemplo, `<MyCustomJSXComponent />`) se resuelve contra el mapa de `components`.
+    ```typescript fileName="app.config.ts"
+    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
+
+    export const appConfig: ApplicationConfig = {
+      providers: [
+        createIntlayerMarkdownProvider({
+          components: {
+            h1: { class: "text-2xl font-bold" },
+          },
+        }),
+      ],
+    };
+    ```
+
+    > MDX es compatible — cualquier nombre de componente utilizado dentro de tu Markdown (por ejemplo, `<MyCustomJSXComponent />`) se resuelve contra el mapa de `components`.
 
 También puedes usar tu propio renderizador de markdown:
 

package/docs/es/dictionary/plurial.md

@@ -35,9 +35,12 @@ To use plural content in Angular components, retrieve it via the `useIntlayer` h
 
 ## Cuándo usar `plural` vs `enu`
 
-To use plural content inside a React component, retrieve it via the `useIntlayer` hook and call it with a count. The active locale and the count are combined to pick the matching CLDR category.
+| Caso de uso                                                               | Helper   |
+| ------------------------------------------------------------------------- | -------- |
+| Formas plurales gramaticales según la locale (una manzana / dos manzanas) | `plural` |
+| Rangos numéricos personalizados (`<5`, `>=10`) o categorías fuera de CLDR | `enu`    |
 
-To use plural content in Next.js Client Components, retrieve it via the `useIntlayer` hook and call it with a count. Here's an example:
+Si solo apunta al inglés (que solo tiene `one` / `other`), cualquiera funciona. Para cualquier idioma con distinciones `few` / `many` / `two`, prefiera `plural`.
 
 ## Configuración del contenido en plural