@intlayer/docs 9.4.1 → 9.4.3

package/blog/es/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Cómo probar traducciones sin escribir pruebas frágiles"
+description: Qué vale la pena probar en una aplicación i18n y qué no. Pruebas de renderizado con provider, pseudolocalización, cobertura RTL y plurales, y la trampa de los snapshots.
+keywords:
+  - probar traducciones
+  - pruebas i18n
+  - testing library i18n
+  - pseudolocalización
+  - prueba provider locale
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# Cómo probar traducciones sin escribir pruebas frágiles
+
+La mayoría de las suites de pruebas i18n fallan de dos formas. O bien realizan aserciones sobre el texto literal, de modo que cada cambio de redacción rompe cincuenta pruebas y el equipo termina eliminándolas. O bien renderizan todo en el locale predeterminado, sin verificar nada sobre los otros diecisiete. Ambos caminos conducen al mismo destino, una suite en la que nadie confía.
+
+## Tabla de contenidos
+
+<TOC/>
+
+## Los patrones son independientes de la biblioteca
+
+Cada patrón a continuación funciona en cualquier stack i18n. Cambia el provider por `I18nextProvider`, `NextIntlClientProvider` o `IntlProvider` y las pruebas permanecerán idénticas, ya que validan el resultado renderizado en lugar de una API de biblioteca.
+
+El soporte de cobertura también se adapta: con el [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-json.md) apuntando a tus catálogos actuales, o un [adaptador de compatibilidad](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/index.md) creando alias sobre tus imports actuales, la aserción de cobertura se ejecuta sobre el JSON que ya tienes.
+
+## Decide qué estás probando en realidad
+
+La calidad de la traducción no se comprueba con una aserción de código. Ninguna aserción puede validar si el alemán suena natural, y asumir lo contrario llena la suite de cadenas hardcodeadas.
+
+Lo que sí vale la pena probar es mecánico:
+
+| Vale la pena probar                         | No vale la pena probar           |
+| :------------------------------------------ | :------------------------------- |
+| Cada locale requerido tiene un valor        | Si la redacción suena bien       |
+| El locale correcto llega al componente      | El texto exacto de cada etiqueta |
+| Los plurales resuelven cada categoría       | Si el traductor hizo su trabajo  |
+| Locales RTL configuran dirección y espejo   | Cada cadena en cada locale       |
+| Fechas y números formateados usan el locale | La precisión interna de `Intl`   |
+
+La cobertura pertenece a una prueba orientada a datos, no a las pruebas de componentes. Eso se detalla en [cómo detectar traducciones faltantes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/detecting_missing_translations.md); este artículo se enfoca en el resto.
+
+## Renderiza dentro de un provider y busca por rol
+
+El patrón principal consiste en montar el componente dentro de un provider de locale y consultar por rol o identificador de prueba en lugar de por texto.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("renderiza el encabezado del resumen en francés", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Consultar `getByRole("heading")` sobrevive a un cambio de texto. `getByText("Récapitulatif")` no lo hace. Usa la cadena literal únicamente cuando el texto en sí sea el objeto de prueba, lo cual ocurre raramente.
+
+Para atributos como `aria-label`, necesitas la cadena sin procesar en lugar de un nodo renderizable. En React, las entradas de `useIntlayer` exponen un campo `.value` para este propósito.
+
+## Parametriza las pruebas entre locales
+
+Un único cuerpo de prueba evaluado en cada locale aporta mucho más valor que una prueba separada por locale.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("locale %s", (locale) => {
+  it("renderiza sin recurrir a la clave sin traducir", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // Una clave renderizada significa que la resolución falló.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("establece la dirección de texto correcta", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+La primera aserción es una ventaja genérica económica: si la resolución falla y tu biblioteca imprime la clave, el DOM contendrá un formato similar a `cart.summary.title`. Esto detecta una clase completa de errores sin evaluar una sola cadena.
+
+## La pseudolocalización revela lo que los catálogos no detectan
+
+Añade un locale ficticio que transforme cada texto, por ejemplo convirtiendo `Checkout` en `[!!! Çĥéçķöũţ !!!]`. Luego renderiza la página en ese locale.
+
+Cualquier elemento que permanezca en inglés estándar está hardcodeado en el código, y ninguna auditoría basada en catálogos puede percibirlo, ya que para las herramientas la cadena no existe. Los corchetes cumplen una segunda función: expanden el texto cerca de un 30 por ciento, exponiendo desbordes de interfaz antes de que ocurran en alemán.
+
+Conviene ejecutar esto como un paso visual o end-to-end antes que como una prueba unitaria, ya que el fallo se detecta visualmente.
+
+## Los plurales requieren una prueba por categoría, no por idioma
+
+Los errores de plurales pasan desapercibidos porque el inglés solo maneja dos formas y muchos desarrolladores se limitan a ellas. El polaco tiene cuatro, el árabe seis.
+
+```ts fileName="plural.test.ts"
+// El árabe evalúa zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("cantidad %i", (count) => {
+  it("produce una cadena no vacía en árabe", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Elige cantidades que cubran cada categoría CLDR para el idioma más complejo en lugar de verificar 1 y 2 en todas partes. `Intl.PluralRules` indica en qué categoría encaja un número, de modo que puedes deducir los valores de prueba en lugar de adivinarlos. Más detalles sobre las categorías en el [artículo sobre el formato de mensajes ICU](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/icu_message_format.md).
+
+## La trampa de los snapshots
+
+Los snapshots y la internacionalización son una mala combinación. Un snapshot de un componente localizado almacena cada cadena en su interior, de modo que un traductor corrigiendo un error ortográfico en portugués convierte una suite en verde en rojo, dentro de un archivo que ningún revisor puede evaluar. Tras varias falsas alarmas, alguien ejecuta `-u` sin revisar el diff y los snapshots pierden toda utilidad.
+
+Si deseas utilizar snapshots, captúralos en un solo locale y considéralos como una comprobación estructural y no de contenido. Todo lo específico de cada locale debe verificarse con aserciones explícitas.
+
+## Prueba la negociación de locale, no solo el renderizado
+
+El error de i18n más habitual en producción no es una cadena faltante. Es la selección de un locale incorrecto: una URL marca `/fr/`, el cliente lee `navigator.language`, y no coinciden.
+
+Prueba la lógica de resolución directamente, como una función pura independiente de los componentes:
+
+```ts fileName="locale-resolution.test.ts"
+it("prefiere la URL sobre la preferencia guardada", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("usa el header cuando la URL carece de prefijo", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+Esta es la prueba de i18n de mayor valor que suele faltar en los proyectos, y no requiere DOM.
+
+## Qué ejecutar y dónde
+
+- **Unitaria**: negociación de locales, formateadores, categorías de plurales. Rápida, sin DOM.
+- **Componente**: un renderizado con provider por locale, verificando roles y la ausencia de claves sin resolver.
+- **Cobertura**: una prueba basada en datos que garantice la ausencia de locales requeridos faltantes.
+- **Visual o end-to-end**: pase de pseudolocalización y una página RTL, pues esos fallos son visuales.
+
+Mantén las tres primeras en la integración continua en cada commit. La última es económica en ejecuciones nocturnas y costosa en cada push.
+
+## Errores comunes
+
+- **Aserciones sobre texto literal en todas partes.** Garantiza el abandono de la suite en pocos meses.
+- **Crear snapshots de componentes localizados.** Los traductores rompen el build y los revisores aprueban sin mirar.
+- **Probar únicamente el locale predeterminado.** El único locale que nunca puede faltar.
+- **Probar 1 y 2 para los plurales.** Pasa por alto las categorías que el inglés no posee.
+- **Crear mocks de la librería i18n.** En ese punto solo estás probando que el mock devuelve cadenas.
+- **No probar nunca la negociación de locales.** El fallo más común en entornos reales y el más sencillo de comprobar.
+
+## Para profundizar
+
+- [Probar tu contenido: auditoría CLI, API programática y aserciones UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/testing.md)
+- [Plugin de ESLint: detección de texto hardcodeado y contenido no utilizado](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/eslint.md)
+- [Formateadores y utilidades de locale, incluyendo `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/formatters.md)
+- [Informes de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/index.md)
+- [Adaptador de compatibilidad react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/react-i18next.md)
+- [Cómo detectar traducciones faltantes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/detecting_missing_translations.md)
+- [Formato de mensajes ICU: plurales, select y esqueletos](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/icu_message_format.md)

package/blog/es/intlayer_with_i18next.md

@@ -74,15 +74,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.

package/blog/es/intlayer_with_next-i18next.md

@@ -67,15 +67,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.

package/blog/es/intlayer_with_next-intl.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.

package/blog/es/intlayer_with_react-i18next.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.

package/blog/es/intlayer_with_react-intl.md

@@ -66,15 +66,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.

package/blog/es/intlayer_with_vue-i18n.md

@@ -68,15 +68,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > la bandera `--interactive` es opcional. Usa `intlayer-cli init` si eres un agente de IA.

package/blog/es/is_i18next_outdated.md

@@ -0,0 +1,315 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: ¿Está i18next obsoleto en 2026?
+description: i18next impulsa millones de sitios web, pero su arquitectura en tiempo de ejecución de 2011 muestra su antigüedad. Un vistazo al peso del bundle, los límites del tree-shaking y la falta de innovación.
+keywords:
+  - i18next
+  - react-i18next
+  - next-i18next
+  - Intlayer
+  - Internacionalización
+  - i18n
+  - Tamaño de bundle
+  - Blog
+slugs:
+  - blog
+  - is-i18next-outdated
+author: aymericzip
+---
+
+# ¿Está i18next obsoleto en 2026?
+
+`i18next` nació en 2011, mucho antes de que los componentes React, el empaquetado con Webpack o TypeScript se convirtieran en el estándar. Conquistó el ecosistema gracias a su flexibilidad y ubicuidad, ofreciendo plugins para cualquier tecnología y respuestas en StackOverflow para cada duda.
+
+No es un proyecto abandonado, recibe parches regularmente. Sin embargo, existe una gran diferencia entre mantener funcionando un motor clásico y evolucionar activamente con las arquitecturas frontend actuales.
+
+En los últimos años, el desarrollo frontend ha adoptado la compilación en tiempo de construcción, los React Server Components (RSC), el tree-shaking agresivo y los flujos guiados por IA. El núcleo de i18next sigue siendo lo que era hace más de una década: un singleton en tiempo de ejecución que resuelve claves textuales en el cliente.
+
+<TOC/>
+
+## Puntos clave
+
+**Modo mantenimiento:**
+
+Durante el último año, `next-i18next` registró ~63 commits (aproximadamente uno por semana) y `react-i18next` ~157, en su mayoría actualizaciones de dependencias y correcciones menores.
+
+**Sobrecarga notable en runtime:**
+
+`react-i18next` y `next-i18next` añaden ~17–18 KB gzipped (~60 KB minificados) antes de mostrar la primera palabra traducida, casi 4 veces más que `next-intlayer` (~4.7 KB).
+
+**Fuga severa de contenidos:**
+
+En configuraciones estáticas por defecto, hasta un **89.8%** de los datos de localización enviados a una página pertenece a otras rutas o idiomas no leídos.
+
+**Tree-shaking inviable:**
+
+Llamadas dinámicas como `t("home.hero.title")` no pueden ser analizadas por empaquetadores, forzando la inclusión completa de archivos JSON en el bundle del cliente.
+
+**Modelo de negocio comercial:**
+
+Los mantenedores operan Locize. Desarrollar un sistema de traducción local por IA sin coste en la CLI competiría directamente con su vía de ingresos principal.
+
+## Mantenimiento frente a evolución activa
+
+Las estrellas de GitHub reflejan la adopción histórica y no el impulso arquitectónico actual.
+
+| Repositorio             | Estrellas                                                                                                                                                  | Commits totales                                                                                                                                                         | Commits / año                                                                                                                                                          | Último commit                                                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `i18next/i18next`       | [![stars](https://img.shields.io/github/stars/i18next/i18next?style=for-the-badge&label=stars)](https://github.com/i18next/i18next/stargazers)             | [![commits](https://img.shields.io/github/commit-activity/t/i18next/i18next?style=for-the-badge&label=commits)](https://github.com/i18next/i18next/commits)             | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/i18next/commits)             | [![last](https://img.shields.io/github/last-commit/i18next/i18next?style=for-the-badge)](https://github.com/i18next/i18next/commits)             |
+| `i18next/react-i18next` | [![stars](https://img.shields.io/github/stars/i18next/react-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/react-i18next/stargazers) | [![commits](https://img.shields.io/github/commit-activity/t/i18next/react-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/react-i18next/commits) | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/react-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/react-i18next/commits) | [![last](https://img.shields.io/github/last-commit/i18next/react-i18next?style=for-the-badge)](https://github.com/i18next/react-i18next/commits) |
+| `i18next/next-i18next`  | [![stars](https://img.shields.io/github/stars/i18next/next-i18next?style=for-the-badge&label=stars)](https://github.com/i18next/next-i18next/stargazers)   | [![commits](https://img.shields.io/github/commit-activity/t/i18next/next-i18next?style=for-the-badge&label=commits)](https://github.com/i18next/next-i18next/commits)   | [![yearly](https://img.shields.io/github/commit-activity/y/i18next/next-i18next?style=for-the-badge&label=%2Fyear)](https://github.com/i18next/next-i18next/commits)   | [![last](https://img.shields.io/github/last-commit/i18next/next-i18next?style=for-the-badge)](https://github.com/i18next/next-i18next/commits)   |
+| `aymericzip/intlayer`   | [![stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=stars)](https://github.com/aymericzip/intlayer/stargazers)     | [![commits](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)     | [![yearly](https://img.shields.io/github/commit-activity/y/aymericzip/intlayer?style=for-the-badge&label=%2Fyear)](https://github.com/aymericzip/intlayer/commits)     | [![last](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)     |
+
+Actividad en los últimos doce meses:
+
+| Proyecto        | Commits históricos | Últimos 12 meses | Enfoque                                   |
+| --------------- | ------------------ | ---------------- | ----------------------------------------- |
+| `next-i18next`  | 1.311              | **63**           | Compatibilidad con Next.js y correcciones |
+| `react-i18next` | 1.988              | **157**          | Tipos y mantenimiento                     |
+| `i18next` core  | 2.626              | **259**          | Parches menores                           |
+| Intlayer        | 7.156              | **4.343**        | Compilador, herramientas IDE y motor IA   |
+
+[![Star History Chart](https://api.star-history.com/chart?repos=i18next%2Fi18next%2Ci18next%2Freact-i18next%2Ci18next%2Fnext-i18next%2Caymericzip%2Fintlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/i18next&i18next/react-i18next&i18next/next-i18next&aymericzip/intlayer)
+
+Una librería pequeña puede ser madura y confiable. Pero las herramientas de internacionalización continúan avanzando: los empaquetadores modernos eliminan contenido sin referenciar durante el build, los LLM automatizan traducciones en CI y los editores dependen de servidores de lenguaje (LSP) y agentes IA. La arquitectura puramente en runtime de i18next frena su capacidad de integración.
+
+## Medición del impacto en el bundle
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+<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;"
+/>
+
+> Medido en un build de producción con 10 rutas y 10 idiomas con compresión gzip. Más detalles en el [informe del benchmark i18n](https://intlayer.org/es/doc/benchmark).
+
+### Sobrecarga base de la librería
+
+Peso inicial antes de cargar cualquier texto traducido:
+
+| Librería               | Gzipped    | Minificado  |
+| ---------------------- | ---------- | ----------- |
+| `next-i18next@16.0.5`  | 17.8 KB    | 61.2 KB     |
+| `react-i18next@17.0.2` | 17.3 KB    | 59.8 KB     |
+| `intlayer@8.7.12`      | **4.7 KB** | **12.8 KB** |
+
+### Peso de página y fuga de contenido
+
+Probado en React / TanStack Start (estrategia estática):
+
+| Librería              | JS medio / pág (gz) | Fuga idiomas | Fuga otras págs | Componente medio (gz) | Hidratación |
+| --------------------- | ------------------- | ------------ | --------------- | --------------------- | ----------- |
+| `react-i18next`       | 180.3 KB            | **50.0%**    | **89.8%**       | 24.3 KB               | 85.1 ms     |
+| Intlayer              | **127.8 KB**        | 50.0%        | **0.8%**        | **7.1 KB**            | **24.1 ms** |
+| Intlayer (scoped dyn) | **118.1 KB**        | **0.0%**     | **0.8%**        | **4.6 KB**            | 23.7 ms     |
+
+En Next.js:
+
+| Librería        | JS medio / pág (gz) | Fuga otras págs | Componente medio (gz) |
+| --------------- | ------------------- | --------------- | --------------------- |
+| Base (sin i18n) | 150.8 KB            | 0.0%            | 0.7 KB                |
+| `next-i18next`  | **227.5 KB**        | **89.8%**       | 24.5 KB               |
+| `next-intlayer` | **152.1 KB**        | **0.0%**        | **7.2 KB**            |
+
+### Conclusiones clave
+
+**Peso de página:**
+
+En Next.js, `next-i18next` añade **76.7 KB gzipped** frente al proyecto base, un incremento de ~50%. `next-intlayer` apenas suma 1.3 KB.
+
+**Fuga de traducciones:**
+
+Por defecto, casi el **90% del texto traducido** enviado a una ruta pertenece a otras pantallas. La gestión manual mediante namespaces resulta compleja y propensa a fallos.
+
+**Tiempo de hidratación:**
+
+Los componentes con `react-i18next` requirieron **85 ms** para hidratarse frente a **24 ms** con Intlayer. Transferir grandes estructuras JSON a los componentes perjudica la interactividad inicial.
+
+## ¿Por qué i18next es pesado?
+
+### Acumulación de funciones en tiempo de ejecución
+
+Operar únicamente en el navegador exige entregar todas las características desde el inicio: interpolación, reglas plurales, contextos, registros de formateo y buses de eventos. Incluso una simple cadena de texto asume el coste del motor al completo.
+
+### Las claves dinámicas impiden el tree-shaking
+
+Dado que `"hero.title"` se evalúa dinámicamente en tiempo de ejecución, los empaquetadores no pueden prever qué textos se emplean realmente. Las cadenas innecesarias se incluyen invariablemente en los bundles.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```tsx fileName="Component.tsx"
+const { t } = useTranslation("home");
+
+return <h1>{t("hero.title")}</h1>;
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```tsx fileName="Hero.tsx"
+const { title } = useIntlayer("hero");
+
+return <h1>{title}</h1>;
+```
+
+  </Tab>
+</Tabs>
+
+El [compilador de Intlayer](https://intlayer.org/es/doc/compiler) analiza qué consume `Hero.tsx` y retira campos sin utilizar antes de crear los bundles del cliente. Consulta [optimización de bundle](https://intlayer.org/es/doc/concept/bundle-optimization) para conocer los detalles.
+
+## Experiencia de desarrollo
+
+### JSON aislados frente a co-ubicación
+
+Con i18next, el texto queda distribuido en carpetas JSON independientes del código. Intlayer agrupa las declaraciones de contenido junto a los propios componentes.
+
+<Tabs defaultTab="intlayer" group="techno">
+  <Tab label="i18next" value="i18next">
+
+```json fileName="locales/en/hero.json"
+{
+  "title": "Ship in every language"
+}
+```
+
+```json fileName="locales/es/hero.json"
+{
+  "title": "Lanza en todos los idiomas"
+}
+```
+
+```tsx fileName="Hero.tsx"
+import { useTranslation } from "react-i18next";
+
+export const Hero = () => {
+  const { t } = useTranslation("hero");
+  return <h1>{t("title")}</h1>;
+};
+```
+
+  </Tab>
+  <Tab label="Intlayer" value="intlayer">
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero",
+  content: {
+    title: t({
+      en: "Ship in every language",
+      es: "Lanza en todos los idiomas",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+```tsx fileName="Hero.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const Hero = () => {
+  const { title } = useIntlayer("hero");
+  return <h1>{title}</h1>;
+};
+```
+
+  </Tab>
+</Tabs>
+
+Al mover o eliminar `Hero.tsx`, sus declaraciones de contenido se trasladan o eliminan con él.
+
+### Autocompletado frente a seguridad de tipos estricta
+
+Extender `CustomTypeOptions` permite el autocompletado de claves en el IDE, pero no asegura la integridad del contenido. Suprimir una clave en `es/home.json` no romperá tu compilación; simplemente generará un fallback en runtime.
+
+Intlayer infiere tipos directamente de las declaraciones de contenido, y el [`strictMode`](https://intlayer.org/es/doc/concept/configuration) transforma traducciones ausentes en errores de compilación estrictos.
+
+### Comparación de herramientas
+
+| Característica             | Ecosistema i18next | Intlayer                                                                |
+| -------------------------- | ------------------ | ----------------------------------------------------------------------- |
+| **Extensión VS Code**      | Solo terceros      | ✅ [Extensión oficial](https://intlayer.org/es/doc/vs-code-extension)   |
+| **Language Server (LSP)**  | ❌ Ninguno         | ✅ [LSP dedicado](https://intlayer.org/es/doc/lsp)                      |
+| **Servidor MCP (para IA)** | ❌ Ninguno         | ✅ [Servidor MCP integrado](https://intlayer.org/es/doc/mcp-server)     |
+| **Habilidades de Agente**  | ❌ Ninguna         | ✅ [Skills listas para usar](https://intlayer.org/es/doc/agent_skills)  |
+| **CMS Visual en contexto** | Locize (SaaS pago) | ✅ [Gratuito y Open Source](https://intlayer.org/es/doc/concept/editor) |
+
+## Traducción y el modelo de Locize
+
+Locize es el servicio comercial oficial fundado por los creadores de i18next. La financiación sostenible en open source es vital, pero este esquema genera un dilema: un proyecto monetizado mediante una plataforma SaaS de pago difícilmente priorizará un sistema local de traducción por IA gratuito en su CLI.
+
+Intlayer adopta una postura abierta:
+
+- [`intlayer fill`](https://intlayer.org/es/doc/concept/auto-fill) completa las traducciones pendientes en tu terminal o CI empleando tus propias credenciales API de OpenAI, Anthropic, Mistral o Gemini.
+- El [CMS Intlayer](https://intlayer.org/es/doc/concept/cms) es código abierto y autoalojable con Docker Compose.
+- El compilador, la CLI, el editor y el CMS se publican bajo licencia Apache 2.0.
+
+## ¿Dónde sigue encajando i18next?
+
+<AccordionGroup>
+<Accordion header="Proyectos heredados estables">
+
+Si tu sistema funciona bien y la dimensión del bundle no es un cuello de botella, una migración no resulta urgente.
+
+</Accordion>
+<Accordion header="Entornos particulares">
+
+La amplia biblioteca de plugins de i18next admite arquitecturas específicas (Electron, jQuery clásico, puentes nativos personalizados) que los compiladores modernos no suelen contemplar.
+
+</Accordion>
+<Accordion header="Amplia base comunitaria">
+
+El histórico en StackOverflow y GitHub ayuda a solucionar situaciones atípicas con rapidez.
+
+</Accordion>
+</AccordionGroup>
+
+## ¿Cómo mejorar mi configuración de i18next existente?
+
+Intlayer ofrece paquetes de compatibilidad directa que replican con exactitud las firmas de funciones de las bibliotecas i18next (`i18next`, `react-i18next` y `next-i18next`). No necesitas reescribir tus componentes para beneficiarte de las optimizaciones de un compilador moderno.
+
+La configuración se realiza con un único comando:
+
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer init --interactive
+```
+
+Esta interfaz de línea de comandos interactiva:
+
+1. Instala el paquete de compatibilidad `@intlayer/i18next`.
+2. Configura los alias del empaquetador para que tus importaciones habituales (`useTranslation`, `Trans`, `t`) apunten directamente a Intlayer, permitiendo remover la biblioteca anterior de tu `package.json`.
+3. Activa de inmediato el soporte del servidor de lenguaje (LSP) en tu editor, la optimización de bundles en compilación (tree-shaking completo) y las herramientas locales de traducción con IA.
+
+Para consultar los detalles paso a paso, explora nuestras guías:
+
+- **Capas de compatibilidad:** Mantén tu sintaxis con los adaptadores para [i18next](https://intlayer.org/es/doc/compatibility/i18next), [react-i18next](https://intlayer.org/es/doc/compatibility/react-i18next) y [next-i18next](https://intlayer.org/es/doc/compatibility/next-i18next).
+- **Migración de catálogos:** Convierte archivos JSON en diccionarios tipados con nuestras guías: [desde i18next](https://intlayer.org/es/doc/migration/i18next), [desde react-i18next](https://intlayer.org/es/doc/migration/react-i18next) o [desde next-i18next](https://intlayer.org/es/doc/migration/next-i18next).
+- **Configuración híbrida:** Mantén el runtime de i18next mientras [usas Intlayer con i18next](https://intlayer.org/es/blog/intlayer-with-i18next) para generar tipos y autotraducir los catálogos.
+
+Analiza tu aplicación en producción con el [escáner SEO i18n gratuito](https://intlayer.org/i18n-seo-scanner):
+
+<ClickToOpenIframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## Lecturas recomendadas
+
+- [Benchmark Next.js i18n: análisis completo de rendimiento](https://intlayer.org/es/doc/benchmark/nextjs)
+- [react-i18next vs react-intl vs Intlayer](https://intlayer.org/es/blog/react-i18next-vs-react-intl-vs-intlayer)
+- [¿Está next-intl obsoleto en 2026?](https://intlayer.org/es/blog/is-next-intl-outdated)
+- [Arquitectura de compilación frente a i18n declarativa](https://intlayer.org/es/blog/compiler-vs-declarative-i18n)