@intlayer/docs 7.5.13 → 7.5.14

package/blog/en-GB/per-component_vs_centralized_i18n.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: Per-Component vs. Centralized i18n: A New Approach with Intlayer
+description: A deep dive into internationalization strategies in React, comparing centralized, per-key, and per-component approaches, and introducing Intlayer.
+keywords:
+  - i18n
+  - React
+  - Internationalization
+  - Intlayer
+  - Optimization
+  - Bundle Size
+slugs:
+  - blog
+  - per-component-vs-centralized-i18n
+---
+
+# Per-Component vs. Centralized i18n
+
+The per-component approach is not a new concept. For example, in the Vue ecosystem, `vue-i18n` supports [Single File Component (SFC) i18n](https://vue-i18n.intlify.dev/guide/advanced/sfc.html). Nuxt also offers [per-component translations](https://i18n.nuxtjs.org/docs/guide/per-component-translations), and Angular employs a similar pattern through its [Feature Modules](https://v17.angular.io/guide/feature-modules).
+
+Even in a Flutter app, we can often find this pattern:
+
+```bash
+lib/
+└── features/
+    └── login/
+        ├── login_screen.dart
+        └── login_screen.i18n.dart  # <- Translations live here
+```
+
+```dart fileName='lib/features/login/login_screen.i18n.dart'
+import 'package:i18n_extension/i18n_extension.dart';
+
+extension Localization on String {
+  static var _t = Translations.byText("en") +
+      {
+        "Hello": {
+          "en": "Hello",
+          "fr": "Bonjour",
+        },
+      };
+
+  String get i18n => localize(this, _t);
+}
+```
+
+However, in the React world, we mainly see different approaches, that I will group in three categories:
+
+<Columns>
+  <Column>
+
+**Centralized approach** (i18next, next-intl, react-intl, lingui)
+
+- (with no namespaces) considers a single source to retrieve content. By default, you load the content from all pages when your app loads.
+
+  </Column>
+  <Column>
+
+**Granular approach** (intlayer, inlang)
+
+- fine-grain the content retrieval per key, or per-component.
+
+  </Column>
+</Columns>
+
+> In this blog, I won't focus on compiler-based solutions, which I already covered here: [Compiler vs Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/compiler_vs_declarative_i18n.md).
+> Note that compiler-based i18n (e.g., Lingui) simply automates the extraction and loading of content. Under the hood, they often share the same limitations as others approaches.
+
+> Note that the more you fine-grain how you retrieve your content, the more you risk inserting additional state and logic into your components.
+
+Granular approaches are more flexible than centralized ones, but it's often a tradeoff. Even if "tree shaking" is advertised by that libraries, in practice, you'll often end up loading a page in every language.
+
+So, broadly speaking, the decision breaks down like this:
+
+- If your application has more pages than languages, you should favor a granular approach.
+- If you have more languages than pages, you should lean toward a centralized approach.
+
+Of course, the library authors are aware of these limitations and provide workarounds.
+Among them: splitting into namespaces, dynamically loading JSON files (`await import()`), or purging content at build time.
+
+At the same time, you should know that when you dynamically load your content, you introduce additional requests to your server. Each extra `useState` or hook means an extra server request.
+
+> To fix this point, using dynamic import mode, Intlayer suggests grouping multiple content definitions under a same key, Intlayer will then merge that content. In parallel, Intlayer provide a proxy to group multiple content retrieval under a same request.
+
+But from all that solution, it's clear that the most popular approach is the centralized one.
+
+### So why is the Centralized approach so popular?
+
+- First, i18next was the first solution to become widely used, following a philosophy inspired by PHP and Java architectures (MVC), which rely on a strict separation of concerns (keeping content separate from code). It arrived in 2011, establishing its standards even before the massive shift toward Component-Based Architectures (like React).
+- Then, once a library is widely adopted, it becomes difficult to shift the ecosystem to other patterns.
+- Using a centralized approach also makes things easier in Translation Management Systems such as Crowdin, Phrase, or Localized.
+- The logic behind a per-component approach is more complex than a centralized one and takes extra time to develop, especially when you have to solve problems like identifying where the content is located.
+
+### Ok, but why not just stick to a Centralized approach?
+
+Let me tell you why it can be problematic for your app:
+
+- **Unused Data:**
+  When a page loads, you often load the content from all other pages. (In a 10-page app, that's 90% unused content loaded). You lazy load a modal? The i18n library doesn't care, it loads the strings first anyway.
+- **Performance:**
+  For each re-render, every single one of your components is hydrated with a massive JSON payload, which impacts your app's reactivity as it grows.
+- **Maintenance:**
+  Maintaining large JSON files is painful. You have to jump across files to insert a translation, ensuring no translations are missing and no **orphan keys** are left behind.
+- **Design-system:**
+  It creates incompatibility with design systems (e.g., a `LoginForm` component) and constrains component duplication across different apps.
+
+**"But we invented Namespaces!"**
+
+Sure, and that's an massive move forward. Let's look at the comparison of the main bundle size of a Vite + React + React Router v7 + Intlayer setup. We simulated a 20-page application.
+
+The first example does not include lazy-loaded translations per locale and no namespace splitting. The second includes content purging + dynamic loading for translations.
+
+| Optimized bundle                                                                                                         | Bundle not optimized                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| ![no optimized bundle](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle_no_optimization.png?raw=true) | ![optimized bundle](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true) |
+
+So thanks for namespaces, we moved from this structure:
+
+```bash
+locale/
+├── en.json
+├── fr.json
+└── es.json
+```
+
+To this one:
+
+```bash
+locale/
+├── en/
+│   ├── common.json
+│   ├── navbar.json
+│   ├── footer.json
+│   ├── home.json
+│   └── about.json
+├── fr/
+│   └── ...
+└── es/
+    └── ...
+
+```
+
+Now you have to finely manage what part of your app content should be loaded, and where. Conclusion, the vast majority of projects just skip this part due to the complexity (see [next-i18next guide](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18n_using_next-i18next.md) for instance to see the challenges that represents (just) following good practices).
+Consequently, those projects end up with the massive JSON loading problem explained earlier.
+
+> Note that this problem is not specific to i18next, but to all centralized approaches listed above.
+
+However, I want to remember your that not all granular approaches solve this. For instance, `vue-i18n SFC`'s or `inlang` approaches do not inherently lazy load the translations per locale, so you simply trade the bundle size problem for another one.
+
+Moreover, without proper separation of concerns, it becomes much more difficult to extract and provide your translations to translators for review.
+
+### How Intlayer's per-component approach solves this
+
+Intlayer proceeds in several steps:
+
+1. **Declaration:** Declare your content anywhere in your codebase using `*.content.{ts|jsx|cjs|json|json5|...}` files. This ensures separation of concerns while keeping content colocated. A content file can be per-locale or multilingual.
+2. **Processing:** Intlayer runs a build step to process JS logic, handle missing translation fallbacks, generate TypeScript types, manage duplicated content, and fetch content from your CMS, and more.
+3. **Purging:** When your app builds, Intlayer purges unused content (a bit like how Tailwind manages your classes) by replacing the content as follows:
+
+**Declaration:**
+
+```tsx
+// src/MyComponent.tsx
+export const MyComponent = () => {
+  const content = useIntlayer("my-key");
+  return <h1>{content.title}</h1>;
+};
+```
+
+```tsx
+// src/myComponent.content.ts
+export const {
+  key: "my-key",
+  content: t({
+    en: { title: "My title" },
+    fr: { title: "Mon titre" }
+  })
+}
+
+```
+
+**Processing:** Intlayer builds the dictionary based on the `.content` file and generates:
+
+```json5
+// .intlayer/dynamic_dictionary/en/my-key.json
+{
+  "key": "my-key",
+  "content": { "title": "My title" },
+}
+```
+
+**Replacement:** Intlayer transforms your component during the application build.
+
+**- Static Import Mode:**
+
+```tsx
+// Representation of the component in JSX-like syntax
+export const MyComponent = () => {
+  const content = useDictionary({
+    key: "my-key",
+    content: {
+      nodeType: "translation",
+      translation: {
+        en: { title: "My title" },
+        fr: { title: "Mon titre" },
+      },
+    },
+  });
+
+  return <h1>{content.title}</h1>;
+};
+```
+
+**- Dynamic Import Mode:**
+
+```tsx
+// Representation of the component in JSX-like syntax
+export const MyComponent = () => {
+  const content = useDictionaryAsync({
+    en: () =>
+      import(".intlayer/dynamic_dictionary/en/my-key.json", {
+        with: { type: "json" },
+      }).then((mod) => mod.default),
+    // Same for other languages
+  });
+
+  return <h1>{content.title}</h1>;
+};
+```
+
+> `useDictionaryAsync` uses a Suspense-like mechanism to load the localized JSON only when needed.
+
+**Key benefits of this per-component approach:**
+
+- Keeping your content declaration close to your components allows better maintainability (e.g moving a components to another app or design system. Deleting the component folder remove the related content too, as you probably already do for your `.test`, `.stories`)
+
+- A per-component approach prevents AI agents from needing to jump across all your different files. It treats all translations in one place, limiting the complexity of the task, and the amount of tokens used.
+
+### Limitations
+
+Of course, this approach comes with trade-offs:
+
+- It is harder to connect to other l10n systems and extra tooling.
+- You get locked in (which is basically already the case with any i18n solution due to their specific syntax).
+
+That's the reason why Intlayer tries to provide a complete toolset for i18n (100% free and OSS), including AI translation using your own AI Provider and API keys. Intlayer also provides tooling to synchronize your JSON, functioning like ICU / vue-i18n / i18next message formatters to map the content to their specific formats.

package/blog/es/per-component_vs_centralized_i18n.md

@@ -0,0 +1,245 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: i18n por componente vs. centralizado: Un nuevo enfoque con Intlayer
+description: Un análisis profundo de las estrategias de internacionalización en React, comparando enfoques centralizados, por clave y por componente, e introduciendo Intlayer.
+keywords:
+  - i18n
+  - React
+  - Internacionalización
+  - Intlayer
+  - Optimización
+  - Tamaño del bundle
+slugs:
+  - blog
+  - per-component-vs-centralized-i18n
+---
+
+# i18n por componente vs. centralizado
+
+El enfoque por componente no es un concepto nuevo. Por ejemplo, en el ecosistema Vue, `vue-i18n` admite [i18n SFC (Single File Component)](https://vue-i18n.intlify.dev/guide/advanced/sfc.html). Nuxt también ofrece [traducciones por componente](https://i18n.nuxtjs.org/docs/guide/per-component-translations), y Angular emplea un patrón similar a través de sus [Feature Modules](https://v17.angular.io/guide/feature-modules).
+
+Incluso en una app Flutter, a menudo encontramos este patrón:
+
+```bash
+lib/
+└── features/
+    └── login/
+        ├── login_screen.dart
+        └── login_screen.i18n.dart  # <- Las traducciones residen aquí
+```
+
+```dart fileName='lib/features/login/login_screen.i18n.dart'
+import 'package:i18n_extension/i18n_extension.dart';
+
+extension Localization on String {
+  static var _t = Translations.byText("en") +
+      {
+        "Hello": {
+          "en": "Hello",
+          "fr": "Bonjour",
+        },
+      };
+
+  String get i18n => localize(this, _t);
+}
+```
+
+Sin embargo, en el mundo React, principalmente vemos diferentes enfoques, que agruparé en tres categorías:
+
+<Columns>
+  <Column>
+
+**Enfoque centralizado** (i18next, next-intl, react-intl, lingui)
+
+- (sin namespaces) considera una única fuente para obtener el contenido. Por defecto, cargas el contenido de todas las páginas cuando tu app se inicia.
+
+  </Column>
+  <Column>
+
+**Enfoque granular** (intlayer, inlang)
+
+- afina la recuperación de contenido por clave o por componente.
+
+  </Column>
+</Columns>
+
+> En este blog, no me centraré en soluciones basadas en compiladores, que ya cubrí aquí: [Compilador vs i18n declarativa](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/compiler_vs_declarative_i18n.md).
+> Ten en cuenta que la i18n basada en compiladores (por ejemplo, Lingui) simplemente automatiza la extracción y la carga de contenido. Bajo el capó, a menudo comparten las mismas limitaciones que otros enfoques.
+
+> Ten en cuenta que cuanto más granularices la forma en que recuperas tu contenido, mayor es el riesgo de introducir estado y lógica adicional en tus componentes.
+
+Los enfoques granulares son más flexibles que los centralizados, pero a menudo implican un compromiso. Incluso si esas bibliotecas publicitan "tree shaking", en la práctica frecuentemente terminarás cargando una página en cada idioma.
+
+Entonces, en términos generales, la decisión se desglosa así:
+
+- Si tu aplicación tiene más páginas que idiomas, deberías favorecer un enfoque granular.
+- Si tienes más idiomas que páginas, deberías inclinarte por un enfoque centralizado.
+
+Por supuesto, los autores de las librerías son conscientes de estas limitaciones y ofrecen soluciones alternativas.
+Entre ellas: dividir en namespaces, cargar dinámicamente archivos JSON (`await import()`), o purgar el contenido en tiempo de compilación.
+
+Al mismo tiempo, debes saber que cuando cargas tu contenido dinámicamente, introduces solicitudes adicionales a tu servidor. Cada `useState` adicional o hook significa una solicitud extra al servidor.
+
+> Para solucionar este punto, Intlayer sugiere agrupar múltiples definiciones de contenido bajo la misma clave; Intlayer luego fusionará ese contenido.
+
+Pero de entre todas esas soluciones, está claro que el enfoque más popular es el centralizado.
+
+### ¿Por qué es tan popular el enfoque centralizado?
+
+- Primero, i18next fue la primera solución en volverse ampliamente usada, siguiendo una filosofía inspirada en arquitecturas PHP y Java (MVC), que se basan en una estricta separación de responsabilidades (mantener el contenido separado del código). Llegó en 2011, estableciendo sus estándares incluso antes del gran cambio hacia arquitecturas basadas en componentes (como React).
+- Luego, una vez que una librería se adopta ampliamente, se vuelve difícil mover el ecosistema a otros patrones.
+- Usar un enfoque centralizado también facilita las cosas en Sistemas de Gestión de Traducciones como Crowdin, Phrase o Localized.
+- La lógica detrás de un enfoque por componente es más compleja que la de uno centralizado y requiere más tiempo para desarrollarse, especialmente cuando hay que resolver problemas como identificar dónde está ubicado el contenido.
+
+### Ok, ¿pero por qué no optar simplemente por un enfoque centralizado?
+
+Déjame explicarte por qué puede ser problemático para tu app:
+
+- **Datos no usados:** Cuando se carga una página, a menudo se carga el contenido de todas las demás páginas. (En una app de 10 páginas, eso supone un 90% de contenido cargado que no se usa). ¿Haces lazy load de un modal? A la biblioteca i18n no le importa: de todas formas carga las cadenas primero.
+- **Rendimiento:** En cada re-renderizado, todos y cada uno de tus componentes se hidratan con una enorme carga JSON, lo que afecta la reactividad de tu app conforme crece.
+- **Mantenimiento:** Mantener archivos JSON grandes es doloroso. Tienes que saltar entre archivos para insertar una traducción, asegurándote de que no falten traducciones y de que no queden **claves huérfanas**.
+- **Sistema de diseño:**
+  Crea incompatibilidades con los design systems (por ejemplo, un componente `LoginForm`) y limita la duplicación de componentes entre distintas aplicaciones.
+
+**"¡Pero inventamos los Namespaces!"**
+
+Claro, y eso es un gran avance. Veamos la comparación del tamaño del bundle principal de una configuración Vite + React + React Router v7 + Intlayer. Simulamos una aplicación de 20 páginas.
+
+El primer ejemplo no incluye traducciones lazy-loaded por locale ni separación de namespaces. El segundo incluye purgado de contenido + carga dinámica de traducciones.
+
+| Bundle optimizado                                                                                                         | Bundle no optimizado                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| ![bundle no optimizado](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle_no_optimization.png?raw=true) | ![bundle optimizado](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true) |
+
+Así que, gracias a los namespaces, pasamos de esta estructura:
+
+```bash
+locale/
+├── en.json
+├── fr.json
+└── es.json
+```
+
+A esta:
+
+```bash
+locale/
+├── en/
+│   ├── common.json
+│   ├── navbar.json
+│   ├── footer.json
+│   ├── home.json
+│   └── about.json
+├── fr/
+│   └── ...
+└── es/
+    └── ...
+
+```
+
+Ahora tienes que gestionar con precisión qué parte del contenido de tu aplicación debe cargarse y dónde. En conclusión, la gran mayoría de proyectos simplemente omite esta parte debido a la complejidad (véase la [guía de next-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/i18n_using_next-i18next.md) por ejemplo para comprobar los retos que supone (solo) seguir las buenas prácticas).
+En consecuencia, esos proyectos acaban con el problema de la carga masiva de JSON explicado anteriormente.
+
+> Ten en cuenta que este problema no es específico de i18next, sino de todos los enfoques centralizados mencionados arriba.
+
+Sin embargo, quiero recordarte que no todos los enfoques granulares solucionan esto. Por ejemplo, los enfoques `vue-i18n SFC` o `inlang` no realizan de forma inherente lazy load de las traducciones por locale, por lo que simplemente cambias el problema del tamaño del bundle por otro.
+
+Además, sin una separación adecuada de responsabilidades, se vuelve mucho más difícil extraer y proporcionar tus traducciones a los traductores para su revisión.
+
+### Cómo el enfoque por componente de Intlayer resuelve esto
+
+Intlayer procede en varios pasos:
+
+1. **Declaración:** Declara tu contenido en cualquier parte de tu codebase usando archivos `*.content.{ts|jsx|cjs|json|json5|...}`. Esto asegura la separación de responsabilidades mientras mantiene el contenido co-localizado. Un archivo de contenido puede ser por-locale o multilingüe.
+2. **Procesamiento:** Intlayer ejecuta un paso de build para procesar la lógica JS, gestionar los fallbacks de traducción faltantes, generar tipos de TypeScript, manejar contenido duplicado, obtener contenido desde tu CMS, y más.
+3. **Purgado:** Cuando tu app se builda, Intlayer purga el contenido no usado (un poco como Tailwind gestiona tus clases) reemplazando el contenido de la siguiente manera:
+
+**Declaración:**
+
+```tsx
+// src/MyComponent.tsx
+export const MyComponent = () => {
+  const content = useIntlayer("my-key");
+  return <h1>{content.title}</h1>;
+};
+```
+
+```tsx
+// src/myComponent.content.ts
+export const {
+  key: "my-key",
+  content: t({
+    es: { title: "Mi título" },
+    en: { title: "My title" },
+    fr: { title: "Mon titre" }
+  })
+}
+
+```
+
+**Procesamiento:** Intlayer construye el diccionario basado en el archivo `.content` y genera:
+
+```json5
+// .intlayer/dynamic_dictionary/en/my-key.json
+{
+  "key": "my-key",
+  "content": { "title": "Mi título" },
+}
+```
+
+**Reemplazo:** Intlayer transforma tu componente durante la compilación de la aplicación.
+
+**- Modo de importación estática:**
+
+```tsx
+// Representación del componente en sintaxis similar a JSX
+export const MyComponent = () => {
+  const content = useDictionary({
+    key: "my-key",
+    content: {
+      nodeType: "translation",
+      translation: {
+        en: { title: "Mi título" },
+        fr: { title: "Mon titre" },
+      },
+    },
+  });
+
+  return <h1>{content.title}</h1>;
+};
+```
+
+**- Modo de importación dinámica:**
+
+```tsx
+// Representación del componente en sintaxis similar a JSX
+export const MyComponent = () => {
+  const content = useDictionaryAsync({
+    en: () =>
+      import(".intlayer/dynamic_dictionary/en/my-key.json", {
+        with: { type: "json" },
+      }).then((mod) => mod.default),
+    // Same for other languages
+  });
+
+  return <h1>{content.title}</h1>;
+};
+```
+
+> `useDictionaryAsync` utiliza un mecanismo similar a Suspense para cargar el JSON localizado únicamente cuando es necesario.
+
+**Beneficios clave de este enfoque por componente:**
+
+- Mantener la declaración de tu contenido cerca de tus componentes permite una mejor mantenibilidad (p. ej., mover un componente a otra app o design system. Eliminar la carpeta del componente también elimina el contenido relacionado, como probablemente ya haces con tus `.test`, `.stories`)
+
+- Un enfoque por componente evita que los agentes de IA tengan que saltar entre todos tus distintos archivos. Trata todas las traducciones en un solo lugar, limitando la complejidad de la tarea y la cantidad de tokens utilizados.
+
+### Limitaciones
+
+Por supuesto, este enfoque conlleva compromisos:
+
+- Es más difícil conectarlo con otros sistemas de l10n y herramientas adicionales.
+- Quedas atado a la solución (lock-in), que básicamente ya ocurre con cualquier solución i18n debido a su sintaxis específica.
+
+Esa es la razón por la que Intlayer intenta proporcionar un conjunto de herramientas completo para i18n (100% gratuito y OSS), incluyendo traducción por IA usando tu propio AI Provider y claves de API. Intlayer también ofrece herramientas para sincronizar tus JSON, funcionando como formateadores de mensajes de ICU / vue-i18n / i18next para mapear el contenido a sus formatos específicos.