@intlayer/docs 8.7.4 → 8.7.5

package/docs/en-GB/benchmark/tanstack.md

@@ -0,0 +1,193 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: Best i18n solution for TanStack Start in 2026 - Benchmark Report
+description: Compare TanStack Start internationalisation libraries like react-i18next, use-intl, and Intlayer. Detailed performance report on bundle size, leakage, and reactivity.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - performance
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n-tanstack-start-template
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Init benchmark"
+---
+
+# TanStack Start i18n Libraries — 2026 Benchmark Report
+
+This page is a benchmark report for i18n solutions on TanStack Start.
+
+## Table of Contents
+
+<Toc/>
+
+## Interactive Benchmark
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+## Results reference:
+
+<iframe 
+  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;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md
+
+See complete benchmark repository [here](https://github.com/intlayer-org/benchmark-i18n/tree/main).
+
+## Introduction
+
+Internationalisation solutions are among the heaviest dependencies in a React app. On TanStack Start, the main risk is shipping unnecessary content: translations for other pages and other locales in a single route’s bundle.
+
+As your app grows, that problem can quickly blow up the JavaScript sent to the client and slow down navigation.
+
+In practice, for the least optimised implementations, an internationalised page can end up several times heavier than the version without i18n.
+
+The other impact is on developer experience: how you declare content, types, namespace organisation, dynamic loading, and reactivity when the locale changes.
+
+## Test your app
+
+To quickly spot i18n leakage issues, I set up a free scanner available [here](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## The problem
+
+Two levers are essential to limit the cost of a multilingual app:
+
+- Split content by page / namespace so you do not load whole dictionaries when you do not need them
+- Load the right locale dynamically, only when needed
+
+Understanding the technical limitations of these approaches:
+
+**Dynamic loading**
+
+Without dynamic loading, most solutions keep messages in memory from the first render, which adds significant overhead for apps with many routes and locales.
+
+With dynamic loading, you accept a trade-off: less initial JS, but sometimes an extra request when switching language.
+
+**Content splitting**
+
+Syntaxes built around `const t = useTranslation()` + `t('a.b.c')` are very convenient but often encourage keeping large JSON objects at runtime. That model makes tree-shaking hard unless the library offers a real per-page split strategy.
+
+## Methodology
+
+For this benchmark, we compared the following libraries:
+
+- `Base App` (No i18n library)
+- `react-intlayer` (v8.7.5-canary.0)
+- `react-i18next` (v17.0.2)
+- `use-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `react-intl` (v10.1.1)
+- `wuchale` (v0.22.11)
+- `gt-react` (vlatest)
+- `lingo.dev` (v0.133.9)
+
+The framework is `TanStack Start` with a multilingual app of **10 pages** and **10 languages**.
+
+We compared **four loading strategies**:
+
+| Strategy            | No namespaces (global)                       | With namespaces (scoped)                                             |
+| :------------------ | :------------------------------------------- | :------------------------------------------------------------------- |
+| **Static loading**  | **Static**: Everything in memory at startup. | **Scoped static**: Split by namespace; everything loaded at startup. |
+| **Dynamic loading** | **Dynamic**: On-demand loading per locale.   | **Scoped dynamic**: Granular loading per namespace and locale.       |
+
+## Strategy summary
+
+- **Static**: Simple; no network latency after the initial load. Downside: large bundle size.
+- **Dynamic**: Reduces initial weight (lazy-loading). Ideal when you have many locales.
+- **Scoped static**: Keeps code organised (logical separation) without complex extra network requests.
+- **Scoped dynamic**: Best approach for _code splitting_ and performance. Minimises memory by loading only what the current view and active locale need.
+
+## Results in detail
+
+### 1 — Solutions to avoid
+
+Some solutions, such as `gt-react` or `lingo.dev`, are clearly ones to steer clear of. They combine vendor lock-in with polluting your codebase. Worse: despite many hours trying to implement them, I never got them working properly on TanStack Start (similar to Next.js with `gt-next`).
+
+Issues encountered:
+
+**(General Translation)** (`gt-react@latest`):
+
+- For an app around 110kb, `gt-react` can add more than 440kb extra (order of magnitude seen on the Next.js implementation in the same benchmark).
+- `Quota Exceeded, please upgrade your plan` on the very first build with General Translation.
+- Translations are not rendered; I get the error `Error: <T> used on the client-side outside of <GTProvider>`, which seems to be a bug in the library.
+- While implementing **gt-tanstack-start-react**, I also came across an [issue](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) with the library: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, which was making the application break. After reporting this issue, the maintainer fixed it within 24 hours.
+- These libraries use an anti-pattern through the `initializeGT()` function, blocking the bundle from tree-shaking cleanly.
+
+**(Lingo.dev)** (`lingo.dev@0.133.9`):
+
+- AI quota exceeded (or blocking server dependency), making build / production risky without paying.
+- The compiler was missing almost 40% of the translated content. I had to rewrite all `.map` into flat component blocks to make it work.
+- Their CLI is buggy and used to reset the config file for no reason.
+- At build, it totally erased the generated JSONs when there was new content added. As a result, you could end up with only a few keys erasing hundreds of existing keys.
+- I met reactivity issues with the library on TanStack Start: on locale change I had to force rerendering of the provider to make it work.
+
+### 2 — Experimental solutions
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+The idea behind `Wuchale` is interesting but not yet a viable solution. I hit reactivity issues with the library and had to force rerendering of the provider to get the app working on TanStack Start. The documentation is also fairly unclear, which makes onboarding harder.
+
+### 3 — Acceptable solutions
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` offers an innovative, well-thought-out approach. Even so, in this benchmark the tree-shaking their company advertises did not work for my Next.js implementation or for TanStack Start. The workflow and DX are also more complex than other options. Personally I am not a fan of having to regenerate JS files before every push, which creates constant merge conflict risk for developers via PRs.
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` addresses many of the issues mentioned earlier. I found it harder to get started with than other tools with similar approaches. It does not provide type safety, which also makes catching missing keys at compile time much harder. I had to wrap Tolgee’s APIs with my own to add missing-key detection.
+
+On TanStack Start I also had reactivity problems: on locale change I had to force the provider to rerender and subscribe to locale-change events so loading in another language behaved correctly.
+
+**(use-intl)** (`use-intl@4.9.1`):
+
+`use-intl` is the most fashionable “intl” piece in the React ecosystem (same family as `next-intl`) and is often pushed by AI agents, but in my view wrongly so in a performance-first setting. Getting started is fairly simple. In practice, the process to optimise and limit leakage is quite complex. Likewise, combining dynamic loading + namespacing + TypeScript types slows development a lot.
+
+On TanStack Start you avoid Next.js-specific traps (`setRequestLocale`, static rendering), but the core issue is the same: without strict discipline, the bundle quickly carries too many messages and per-route namespace maintenance becomes painful.
+
+**(react-i18next)** (`react-i18next@17.0.2`):
+
+`react-i18next` is probably the most popular option because it was among the first to serve JavaScript app i18n needs. It also has a wide set of community plugins for specific problems.
+
+Still, it shares the same major downsides as stacks built on `t('a.b.c')`: optimisations are possible but very time-consuming, and large projects risk bad practices (namespaces + dynamic loading + types).
+
+Message formats also diverge: `use-intl` uses ICU MessageFormat, while `i18next` uses its own format—which complicates tooling or migrations if you mix them.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+`Lingui` is often praised. Personally I found the workflow around `lingui extract` / `lingui compile` more complex than other approaches, without a clear upside in this TanStack Start benchmark. I also noticed inconsistent syntaxes that confuse AIs (e.g. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+**(react-intl)** (`react-intl@10.1.1`):
+
+`react-intl` is a performant implementation from the Format.js team. The DX stays verbose: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` adds complexity, extra JavaScript work, and ties the global i18n instance to many nodes in the React tree.
+
+### 4 — Recommendations
+
+This TanStack Start benchmark has no direct equivalent to `next-translate` (Next.js plugin + `getStaticProps`). For teams that really want a `t()` API with a mature ecosystem, `react-i18next` and `use-intl` remain “reasonable” choices, but expect to invest a lot of time optimising to avoid leakage.
+
+**(Intlayer)** (`react-intlayer@8.7.5-canary.0`):
+
+I will not personally judge `react-intlayer` for objectivity’s sake, since it is my own solution.
+
+### Personal note
+
+This note is personal and does not affect the benchmark results. Still, in the i18n world you often see consensus around a pattern like `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` for translated content.
+
+In React apps, injecting a function as a `ReactNode` is, in my view, an anti-pattern. It also adds avoidable complexity and JavaScript execution overhead (even if it is barely noticeable).

package/docs/es/benchmark/index.md

@@ -0,0 +1,29 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-20
+title: Comparativa de librerías i18n
+description: Descubre cómo se compara Intlayer con otras librerías i18n en términos de rendimiento y tamaño del bundle.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - tanstack
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Inicio del benchmark"
+---
+
+# Benchmark - Informe
+
+Benchmark Bloom es una suite de benchmarks de rendimiento que mide el impacto real de las librerías i18n (internacionalización) en varios frameworks de React y estrategias de carga.
+
+A continuación encontrarás los informes detallados y la documentación técnica de cada framework:
+
+- [**Informe de benchmark de Next.js**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/nextjs.md)
+- [**Informe de benchmark de TanStack Start**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/tanstack.md)

package/docs/es/benchmark/nextjs.md

@@ -0,0 +1,226 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: La mejor solución i18n para Next.js en 2026 - Informe de Benchmark
+description: Compara librerías de internacionalización (i18n) para Next.js como next-intl, next-i18next e Intlayer. Informe detallado de rendimiento sobre tamaño del bundle, fugas y reactividad.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - nextjs
+  - rendimiento
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - nextjs
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Inicio del benchmark"
+---
+
+# Librerías i18n para Next.js — Informe de Benchmark 2026
+
+Esta página es un informe comparativo de soluciones i18n en Next.js.
+
+## Tabla de Contenidos
+
+<Toc/>
+
+## Benchmark Interactivo
+
+<I18nBenchmark framework="nextjs" vertical/>
+
+## Referencia de resultados:
+
+<iframe 
+  src="https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md" 
+  width="100%" 
+  height="600px"
+  style="border:none;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-nextjs.md
+
+Consulta el repositorio completo del benchmark [aquí](https://github.com/intlayer-org/benchmark-i18n).
+
+## Introducción
+
+Las librerías de internacionalización tienen un gran impacto en tu aplicación. El principal riesgo es cargar contenido para cada página y cada idioma cuando el usuario solo visita una página.
+
+A medida que tu aplicación crece, el tamaño del bundle puede aumentar exponencialmente, lo que puede perjudicar notablemente el rendimiento.
+
+Como ejemplo, en los peores casos, una vez internacionalizada, tu página puede terminar siendo casi 4 veces más grande.
+
+Otro impacto de las librerías i18n es la ralentización del desarrollo. Transformar componentes en contenido bilingüe o multilingüe requiere mucho tiempo.
+
+Debido a que el problema es difícil, existen muchas soluciones: algunas enfocadas en la DX (experiencia del desarrollador), otras en el rendimiento o la escalabilidad, y así sucesivamente.
+
+Intlayer intenta optimizar en todas estas dimensiones.
+
+## Pon a prueba tu aplicación
+
+Para sacar a la luz estos problemas, he creado un escáner gratuito que puedes probar [aquí](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## El problema
+
+Existen dos formas principales de limitar el impacto de una aplicación multilingüe en tu bundle:
+
+- Dividir tu JSON (o contenido) en archivos / variables / namespaces para que el bundler pueda aplicar tree-shaking al contenido no utilizado en una página determinada.
+- Cargar dinámicamente el contenido de tu página solo en el idioma del usuario.
+
+Limitaciones técnicas de estos enfoques:
+
+**Carga dinámica**
+
+Incluso cuando declaras rutas como `[locale]/page.tsx`, con Webpack o Turbopack, e incluso si se define `generateStaticParams`, el bundler no trata `locale` como una constante estática. Eso significa que puede incluir el contenido de todos los idiomas en cada página. La forma principal de limitar esto es cargar el contenido a través de un import dinámico (por ejemplo, `import('./locales/${locale}.json')`).
+
+Lo que sucede en tiempo de compilación es que Next.js emite un bundle JS por idioma (por ejemplo, `./locales_fr_12345.js`). Una vez que el sitio se envía al cliente, cuando la página se ejecuta, el navegador realiza una petición HTTP adicional para el archivo JS necesario (por ejemplo, `./locales_fr_12345.js`).
+
+> Otra forma de abordar el mismo problema es usar `fetch()` para cargar el JSON dinámicamente. Así es como funciona `Tolgee` cuando el JSON reside en `/public`, o `next-translate`, que se basa en `getStaticProps` para cargar el contenido. El flujo es el mismo: el navegador realiza una petición HTTP adicional para cargar el recurso.
+
+**División de contenido (Content splitting)**
+
+Si usas una sintaxis como `const t = useTranslation()` + `t('mi-objeto.mi-subobjeto.mi-clave')`, normalmente todo el JSON tiene que estar en el bundle para que la librería pueda analizarlo y resolver la clave. Gran parte de ese contenido se envía incluso cuando no se utiliza en la página.
+
+Para mitigar esto, algunas librerías te piden declarar por página qué namespaces cargar (por ejemplo, `next-i18next`, `next-intl`, `lingui`, `next-translate`, `next-international`).
+
+Por el contrario, `Paraglide` añade un paso adicional antes de la compilación para convertir el JSON en símbolos planos como `const en_my_var = () => 'mi valor'`. En teoría, esto permite el tree-shaking del contenido no utilizado en la página. Como veremos, este método todavía tiene sus compromisos.
+
+Finalmente, `Intlayer` aplica una optimización en tiempo de compilación para que `useIntlayer('mi-clave')` se reemplace directamente con el contenido correspondiente.
+
+## Metodología
+
+Para este benchmark, comparamos las siguientes librerías:
+
+- `Base App` (Sin librería i18n)
+- `next-intlayer` (v8.7.5)
+- `next-i18next` (v16.0.5)
+- `next-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `next-translate` (v3.1.2)
+- `next-international` (v1.3.1)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `@lingo.dev/compiler` (v0.4.0)
+- `wuchale` (v0.22.11)
+- `gt-next` (v6.16.5)
+
+Utilicé la versión `16.2.4` de `Next.js` con el App Router.
+
+Construí una aplicación multilingüe con **10 páginas** y **10 idiomas**.
+
+Comparé **cuatro estrategias de carga**:
+
+| Estrategia         | Sin namespaces (global)                     | Con namespaces (segmentado)                                        |
+| :----------------- | :------------------------------------------ | :----------------------------------------------------------------- |
+| **Carga estática** | **Static**: Todo en memoria al inicio.      | **Scoped static**: Dividido por namespace; todo cargado al inicio. |
+| **Carga dinámica** | **Dynamic**: Carga bajo demanda por idioma. | **Scoped dynamic**: Carga granular por namespace e idioma.         |
+
+## Resumen de estrategias
+
+- **Static**: Simple; sin latencia de red tras la carga inicial. Desventaja: gran tamaño de bundle.
+- **Dynamic**: Reduce el peso inicial (lazy-loading). Ideal cuando se tienen muchos idiomas.
+- **Scoped static**: Mantiene el código organizado (separación lógica) sin peticiones de red adicionales complejas.
+- **Scoped dynamic**: El mejor enfoque para el _code splitting_ y el rendimiento. Minimiza el uso de memoria cargando solo lo que la vista actual y el idioma activo necesitan.
+
+### Qué he medido:
+
+He ejecutado la misma aplicación multilingüe en un navegador real para cada stack y he anotado qué se enviaba realmente por la red y cuánto tiempo tardaba. Los tamaños se reportan **después de la compresión web normal**, ya que es lo más cercano a lo que los usuarios descargan realmente.
+
+- **Tamaño de la librería de internacionalización**: Después del bundling, tree-shaking y minificación, el tamaño de la librería i18n es el tamaño de los proveedores (ej. `NextIntlClientProvider`) + el código de los hooks (ej. `useTranslations`) en un componente vacío. No incluye la carga de los archivos de traducción. Responde a cuánto "cuesta" la librería antes de que entre el contenido.
+
+- **JavaScript por página**: Para cada ruta del benchmark, cuánto script descarga el navegador para esa visita, promediado entre las páginas de la suite (y entre idiomas donde el informe los agrupa). Las páginas pesadas son páginas lentas.
+
+- **Fuga desde otros idiomas (Leakage from other locales)**: Es el contenido de la misma página pero en otro idioma que se carga por error en la página auditada. Este contenido es innecesario y debe evitarse (ej. el contenido de la página `/fr/about` en el paquete de la página `/en/about`).
+
+- **Fuga desde otras rutas**: La misma idea para **otras pantallas** de la aplicación: si sus textos se incluyen cuando solo has abierto una página (ej. el contenido de la página `/en/about` en el paquete de la página `/en/contact`). Una puntuación alta sugiere una división débil o paquetes excesivamente amplios.
+
+- **Tamaño medio de bundle por componente**: Las piezas comunes de la interfaz se miden **una por una** en lugar de esconderse dentro de una cifra gigante de la aplicación. Muestra si la internacionalización infla silenciosamente los componentes cotidianos. Por ejemplo, si tu componente se vuelve a renderizar, cargará todos esos datos desde la memoria. Adjuntar un JSON gigante a cualquier componente es como conectar un gran almacén de datos no utilizados que ralentizará el rendimiento de tus componentes.
+
+- **Responsividad al cambiar de idioma**: Cambio el idioma usando el control propio de la aplicación y cronometro cuánto tiempo pasa hasta que la página ha cambiado claramente, lo que un visitante notaría, no un paso de laboratorio microscópico.
+
+- **Trabajo de renderizado tras un cambio de idioma**: Un seguimiento más específico: cuánto esfuerzo le costó a la interfaz volver a dibujarse para el nuevo idioma una vez que el cambio está en marcha. Útil cuando el tiempo "percibido" y el coste del framework divergen.
+
+- **Tiempo de carga inicial de la página**: Desde la navegación hasta que el navegador considera la página completamente cargada para los escenarios que probé. Útil para comparar arranques en frío (cold starts).
+
+- **Tiempo de hidratación**: Cuando la aplicación lo expone, cuánto tiempo tarda el cliente en convertir el HTML del servidor en algo en lo que realmente se puede hacer clic. Un guion en las tablas significa que esa implementación no proporcionó una cifra de hidratación fiable en este benchmark.
+
+## Resultados en detalle
+
+### 1 — Soluciones a evitar
+
+Algunas soluciones, como `gt-next` o `lingo.dev`, deben evitarse claramente. Combinan el bloqueo del proveedor (vendor lock-in) con la contaminación de tu base de código. A pesar de pasar muchas horas intentando implementarlas, nunca logré que funcionaran, ni en TanStack Start ni en Next.js.
+
+Problemas encontrados:
+
+**(General Translation)** (`gt-next@6.16.5`):
+
+- Para una aplicación de 110kb, `gt-react` añade más de 440kb extra.
+- `Quota Exceeded, please upgrade your plan` en la primerísima compilación con General Translation.
+- Las traducciones no se renderizan; obtengo el error `Error: <T> used on the client-side outside of <GTProvider>`, lo que parece ser un bug de la librería.
+- Mientras implementaba **gt-tanstack-start-react**, también encontré un [problema](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) con la librería: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, que hacía que la aplicación se rompiera. Tras informar de este problema, el mantenedor lo solucionó en 24 horas.
+- La librería bloquea el renderizado estático de las páginas de Next.js.
+
+**(Lingo.dev)** (`@lingo.dev/compiler@0.4.0`):
+
+- Cuota de IA excedida, bloqueando la compilación por completo, por lo que no puedes desplegar en producción sin pagar.
+- El compilador omitía casi el 40% del contenido traducido. Tuve que reescribir todos los `.map` en bloques de componentes planos para que funcionara.
+- Su CLI tiene fallos y solía resetear el archivo de configuración sin motivo.
+- Al compilar, borraba totalmente los JSON generados cuando se añadía nuevo contenido. Como resultado, un puñado de claves podía eliminar más de 300 claves existentes.
+
+### 2 — Soluciones experimentales
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+La idea detrás de `Wuchale` es interesante pero aún no es viable. Experimenté problemas de reactividad y tuve que forzar el renderizado del proveedor para que la aplicación funcionara. La documentación también es bastante confusa, lo que dificulta la adopción.
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` ofrece un enfoque innovador y bien pensado. Aun así, en este benchmark, el tree-shaking que su empresa anuncia no funcionó para mis configuraciones de Next.js o TanStack Start. El flujo de trabajo y la DX son más complejos que otras opciones. Personalmente, no me gusta tener que regenerar archivos JS antes de cada push, lo que crea un riesgo constante de conflictos de fusión a través de las PR. La herramienta también parece más enfocada en Vite que en Next.js.
+Finalmente, en comparación con otras soluciones, Paraglide no usa un almacén (ej. contexto de React) para recuperar el idioma actual y renderizar el contenido. Por cada nodo analizado, solicita el idioma al localStorage / cookie, etc. Esto provoca la ejecución de lógica innecesaria que afecta a la reactividad del componente.
+
+### 3 — Soluciones aceptables
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` aborda muchos de los problemas mencionados anteriormente. Me resultó más difícil de adoptar que herramientas similares. No proporciona seguridad de tipos (type safety), lo que también dificulta detectar claves faltantes en tiempo de compilación. Tuve que envolver las funciones de Tolgee con las mías propias para añadir la detección de claves faltantes.
+
+**(Next Intl)** (`next-intl@4.9.1`):
+
+`next-intl` es la opción más de moda y la que más recomiendan los agentes de IA, pero en mi opinión, equivocadamente. Empezar es fácil. En la práctica, optimizar para limitar la fuga es complejo. Combinar carga dinámica + nombres de espacios + tipos de TypeScript ralentiza mucho el desarrollo. El paquete también es bastante pesado (~13kb para `NextIntlClientProvider` + `useTranslations`, que es más del doble de `next-intlayer`). **next-intl** solía bloquear el renderizado estático de las páginas de Next.js. Proporciona un asistente llamado `setRequestLocale()`. Eso parece haberse abordado parcialmente para archivos centralizados como `en.json` / `fr.json`, pero el renderizado estático sigue fallando cuando el contenido se divide en namespaces como `en/shared.json` / `fr/shared.json` / `es/shared.json`.
+
+**(Next I18next)** (`next-i18next@16.0.5`):
+
+`next-i18next` es probablemente la opción más popular porque fue una de las primeras soluciones i18n para aplicaciones JavaScript. Tiene muchos plugins comunitarios. Comparte las mismas desventajas principales que `next-intl`. El paquete es especialmente pesado (~18kb para `I18nProvider` + `useTranslation`, casi el triple que `next-intlayer`).
+
+Los formatos de los mensajes también difieren: `next-intl` usa ICU MessageFormat, mientras que `i18next` usa su propio formato.
+
+**(Next International)** (`next-international@1.3.1`):
+
+`next-international` también aborda los problemas anteriores, pero no difiere mucho de `next-intl` o `next-i18next`. Incluye `scopedT()` para traducciones específicas de un namespace, pero su uso apenas tiene impacto en el tamaño del bundle.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+A menudo se elogia a `Lingui`. Personalmente, encontré el flujo de trabajo `lingui extract` / `lingui compile` más complejo que otras alternativas, sin una ventaja clara. También noté sintaxis inconsistentes que confunden a las IAs (ej. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+### 4 — Recomendaciones
+
+**(Next Translate)** (`next-translate@3.1.2`):
+
+`next-translate` es mi recomendación principal si te gusta una API de estilo `t()`. Es elegante a través de `next-translate-plugin`, cargando namespaces mediante `getStaticProps` con un cargador de Webpack / Turbopack. También es la opción más ligera aquí (~2.5kb). Para la segmentación por espacios de nombres, definirnamespaces por página o ruta en la configuración está bien pensado y es más fácil de mantener que las principales alternativas como **next-intl** o **next-i18next**. En la versión `3.1.2`, noté que el renderizado estático no funcionaba; Next.js recurría al renderizado dinámico.
+
+**(Intlayer)** (`next-intlayer@8.7.5`):
+
+No seré yo quien juzgue personalmente a `next-intlayer` por objetividad, ya que es mi propia solución.
+
+### Nota personal
+
+Esta nota es personal y no afecta los resultados del benchmark. En el mundo del i18n, a menudo se ve un consenso en torno al patrón `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>`.
+
+En las aplicaciones React, inyectar una función como un `ReactNode` es, en mi opinión, un antipatrón. También añade una complejidad evitable y una sobrecarga de ejecución de JavaScript (aunque sea apenas perceptible).

package/docs/es/benchmark/tanstack.md

@@ -0,0 +1,193 @@
+---
+createdAt: 2026-04-20
+updatedAt: 2026-04-21
+title: La mejor solución i18n para TanStack Start en 2026 - Informe de Benchmark
+description: Compara librerías de internacionalización para TanStack Start como react-i18next, use-intl e Intlayer. Informe detallado de rendimiento sobre tamaño del bundle, fugas y reactividad.
+keywords:
+  - benchmark
+  - i18n
+  - intl
+  - tanstack
+  - rendimiento
+  - intlayer
+slugs:
+  - doc
+  - benchmark
+  - tanstack
+author: Aymeric PINEAU
+applicationTemplate: https://github.com/intlayer-org/benchmark-i18n-tanstack-start-template
+history:
+  - version: 8.7.5
+    date: 2026-01-06
+    changes: "Inicio del benchmark"
+---
+
+# Librerías i18n para TanStack Start — Informe de Benchmark 2026
+
+Esta página es un informe comparativo de soluciones i18n en TanStack Start.
+
+## Tabla de Contenidos
+
+<Toc/>
+
+## Benchmark Interactivo
+
+<I18nBenchmark framework="tanstack" vertical/>
+
+## Referencia de resultados:
+
+<iframe 
+  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;">
+</iframe>
+
+> https://intlayer.org/markdown?url=https%3A%2F%2Fraw.githubusercontent.com%2Fintlayer-org%2Fbenchmark-i18n%2Fmain%2Freport%2Fscripts%2Fsummarize-tanstack.md
+
+Consulta el repositorio completo del benchmark [aquí](https://github.com/intlayer-org/benchmark-i18n/tree/main).
+
+## Introducción
+
+Las soluciones de internacionalización se encuentran entre las dependencias más pesadas en una aplicación de React. En TanStack Start, el riesgo principal es enviar contenido innecesario: traducciones de otras páginas y de otros idiomas en el paquete de una sola ruta.
+
+A medida que tu aplicación crece, ese problema puede disparar rápidamente la cantidad de JavaScript enviado al cliente y ralentizar la navegación.
+
+En la práctica, en las implementaciones menos optimizadas, una página internacionalizada puede terminar siendo varias veces más pesada que la versión sin i18n.
+
+El otro impacto es en la experiencia del desarrollador: cómo declaras el contenido, los tipos, la organización de los namespaces, la carga dinámica y la reactividad cuando cambia el idioma.
+
+## Pon a prueba tu aplicación
+
+Para detectar rápidamente problemas de fuga de i18n, he configurado un escáner gratuito disponible [aquí](https://intlayer.org/i18n-seo-scanner).
+
+<iframe src="https://intlayer.org/i18n-seo-scanner" width="100%" height="600px" style="border:none;"/>
+
+## El problema
+
+Dos palancas son esenciales para limitar el coste de una aplicación multilingüe:
+
+- Dividir el contenido por página / namespace para no cargar diccionarios completos cuando no se necesitan.
+- Cargar el idioma adecuado de forma dinámica, solo cuando sea necesario.
+
+Entendiendo las limitaciones técnicas de estos enfoques:
+
+**Carga dinámica**
+
+Sin carga dinámica, la mayoría de las soluciones mantienen los mensajes en memoria desde el primer renderizado, lo que añade una sobrecarga significativa para aplicaciones con muchas rutas e idiomas.
+
+Con la carga dinámica, aceptas un compromiso: menos JS inicial, pero a veces una petición extra al cambiar de idioma.
+
+**División de contenido (Content splitting)**
+
+Las sintaxis basadas en `const t = useTranslation()` + `t('a.b.c')` son muy cómodas pero a menudo fomentan el mantenimiento de grandes objetos JSON en tiempo de ejecución. Ese modelo dificulta el tree-shaking a menos que la librería ofrezca una estrategia real de división por página.
+
+## Metodología
+
+Para este benchmark, comparamos las siguientes librerías:
+
+- `Base App` (Sin librería i18n)
+- `react-intlayer` (v8.7.5-canary.0)
+- `react-i18next` (v17.0.2)
+- `use-intl` (v4.9.1)
+- `@lingui/core` (v5.3.0)
+- `@inlang/paraglide-js` (v2.15.1)
+- `tolgee` (v7.0.0)
+- `react-intl` (v10.1.1)
+- `wuchale` (v0.22.11)
+- `gt-react` (vlatest)
+- `lingo.dev` (v0.133.9)
+
+El framework es `TanStack Start` con una aplicación multilingüe de **10 páginas** y **10 idiomas**.
+
+Comparamos **cuatro estrategias de carga**:
+
+| Estrategia         | Sin namespaces (global)                     | Con namespaces (segmentado)                                        |
+| :----------------- | :------------------------------------------ | :----------------------------------------------------------------- |
+| **Carga estática** | **Static**: Todo en memoria al inicio.      | **Scoped static**: Dividido por namespace; todo cargado al inicio. |
+| **Carga dinámica** | **Dynamic**: Carga bajo demanda por idioma. | **Scoped dynamic**: Carga granular por namespace e idioma.         |
+
+## Resumen de estrategias
+
+- **Static**: Simple; sin latencia de red tras la carga inicial. Desventaja: gran tamaño de bundle.
+- **Dynamic**: Reduce el peso inicial (lazy-loading). Ideal cuando se tienen muchos idiomas.
+- **Scoped static**: Mantiene el código organizado (separación lógica) sin peticiones de red adicionales complejas.
+- **Scoped dynamic**: El mejor enfoque para el _code splitting_ y el rendimiento. Minimiza el uso de memoria cargando solo lo que la vista actual y el idioma activo necesitan.
+
+## Resultados en detalle
+
+### 1 — Soluciones a evitar
+
+Algunas soluciones, como `gt-react` o `lingo.dev`, son claramente opciones de las que alejarse. Combinan el bloqueo del proveedor con la contaminación de tu base de código. Peor aún: a pesar de pasar muchas horas intentando implementarlas, nunca logré que funcionaran correctamente en TanStack Start (similar a Next.js con `gt-next`).
+
+Problemas encontrados:
+
+**(General Translation)** (`gt-react@latest`):
+
+- Para una app de unos 110kb, `gt-react` puede añadir más de 440kb extra (orden de magnitud visto en la implementación de Next.js en este mismo benchmark).
+- `Quota Exceeded, please upgrade your plan` en la primerísima compilación con General Translation.
+- Las traducciones no se renderizan; obtengo el error `Error: <T> used on the client-side outside of <GTProvider>`, lo que parece ser un bug de la librería.
+- Mientras implementaba **gt-tanstack-start-react**, también encontré un [problema](https://github.com/generaltranslation/gt/issues/1210#event-24510646961) con la librería: `does not provide an export named 'printAST' - @formatjs/icu-messageformat-parser`, que hacía que la aplicación se rompiera. Tras informar de este problema, el mantenedor lo solucionó en 24 horas.
+- Estas librerías usan un antipatrón a través de la función `initializeGT()`, impidiendo que el bundle se limpie adecuadamente mediante tree-shaking.
+
+**(Lingo.dev)** (`lingo.dev@0.133.9`):
+
+- Cuota de IA excedida (o dependencia del servidor bloqueada), lo que hace que la compilación / producción sea arriesgada sin pagar.
+- El compilador omitía casi el 40% del contenido traducido. Tuve que reescribir todos los `.map` en bloques de componentes planos para que funcionara.
+- Su CLI tiene fallos y solía resetear el archivo de configuración sin motivo.
+- Al compilar, borraba totalmente los JSON generados cuando se añadía nuevo contenido. Como resultado, podrías terminar con solo unas pocas claves eliminando cientos de claves existentes.
+- Tuve problemas de reactividad con la librería en TanStack Start: al cambiar de idioma, tuve que forzar el renderizado del proveedor para que funcionara.
+
+### 2 — Soluciones experimentales
+
+**(Wuchale)** (`wuchale@0.22.11`):
+
+La idea detrás de `Wuchale` es interesante pero todavía no es una solución viable. Experimenté problemas de reactividad con la librería y tuve que forzar el renderizado del proveedor para que la aplicación funcionara en TanStack Start. La documentación también es bastante confusa, lo que dificulta la adopción.
+
+### 3 — Soluciones aceptables
+
+**(Paraglide)** (`@inlang/paraglide-js@2.15.1`):
+
+`Paraglide` ofrece un enfoque innovador y bien pensado. Aun así, en este benchmark, el tree-shaking que su empresa publicita no funcionó para mi implementación en Next.js ni para TanStack Start. El flujo de trabajo y la DX también son más complejos que otras opciones. Personalmente, no soy fan de tener que regenerar archivos JS antes de cada push, lo que crea un riesgo constante de conflictos de fusión para los desarrolladores a través de las PR.
+
+**(Tolgee)** (`tolgee@7.0.0`):
+
+`Tolgee` aborda muchos de los problemas mencionados anteriormente. Me resultó más difícil empezar con ella que con otras herramientas con enfoques similares. No proporciona seguridad de tipos, lo que también dificulta mucho detectar claves faltantes en tiempo de compilación. Tuve que envolver las API de Tolgee con las mías propias para añadir la detección de claves faltantes.
+
+En TanStack Start también tuve problemas de reactividad: al cambiar de idioma, tuve que forzar el renderizado del proveedor y suscribirme a eventos de cambio de idioma para que la carga en otro idioma se comportara correctamente.
+
+**(use-intl)** (`use-intl@4.9.1`):
+
+`use-intl` es la pieza "intl" más de moda en el ecosistema de React (de la misma familia que `next-intl`) y a menudo la recomiendan los agentes de IA, pero en mi opinión, equivocadamente en una configuración donde el rendimiento es lo primero. Empezar es bastante sencillo. En la práctica, el proceso para optimizar y limitar la fuga es bastante complejo. Del mismo modo, combinar la carga dinámica + namespaces + tipos de TypeScript ralentiza mucho el desarrollo.
+
+En TanStack Start evitas las trampas específicas de Next.js (`setRequestLocale`, renderizado estático), pero el problema principal es el mismo: sin una disciplina estricta, el bundle transporta rápidamente demasiados mensajes y el mantenimiento de los namespaces por ruta se vuelve pesado.
+
+**(react-i18next)** (`react-i18next@17.0.2`):
+
+`react-i18next` es probablemente la opción más popular porque fue una de las primeras en satisfacer las necesidades i18n de las aplicaciones JavaScript. También tiene un amplio conjunto de plugins comunitarios para problemas específicos.
+
+Aun así, comparte las mismas desventajas principales que los stacks basados en `t('a.b.c')`: las optimizaciones son posibles pero consumen mucho tiempo, y los proyectos grandes corren el riesgo de caer en malas prácticas (namespaces + carga dinámica + tipos).
+
+Los formatos de los mensajes también divergen: `use-intl` usa ICU MessageFormat, mientras que `i18next` usa su propio formato, lo que complica las herramientas o las migraciones si se mezclan.
+
+**(Lingui)** (`@lingui/core@5.3.0`):
+
+A menudo se elogia a `Lingui`. Personalmente, encontré el flujo de trabajo en torno a `lingui extract` / `lingui compile` más complejo que otros enfoques, sin una ventaja clara en este benchmark de TanStack Start. También noté sintaxis inconsistentes que confunden a las IAs (ej. `t()`, `t''`, `i18n.t()`, `<Trans>`).
+
+**(react-intl)** (`react-intl@10.1.1`):
+
+`react-intl` es una implementación de alto rendimiento del equipo de Format.js. La DX sigue siendo verbosa: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` añade complejidad, trabajo extra de JavaScript y vincula la instancia global de i18n a muchos nodos en el árbol de React.
+
+### 4 — Recomendaciones
+
+Este benchmark de TanStack Start no tiene un equivalente directo a `next-translate` (plugin de Next.js + `getStaticProps`). Para los equipos que realmente quieren una API `t()` con un ecosistema maduro, `react-i18next` y `use-intl` siguen siendo opciones "razonables", pero prepárate para invertir mucho tiempo optimizando para evitar fugas.
+
+**(Intlayer)** (`react-intlayer@8.7.5-canary.0`):
+
+No seré yo quien juzgue personalmente a `react-intlayer` por objetividad, ya que es mi propia solución.
+
+### Nota personal
+
+Esta nota es personal y no afecta los resultados del benchmark. Aun así, en el mundo del i18n, a menudo se ve un consenso en torno a un patrón como `const t = useTranslation('xx')` + `<>{t('xx.xx')}</>` para el contenido traducido.
+
+En las aplicaciones React, inyectar una función como un `ReactNode` es, en mi opinión, un antipatrón. También añade una complejidad evitable y una sobrecarga de ejecución de JavaScript (aunque sea apenas perceptible).