@intlayer/docs 7.2.2 → 7.3.0-canary.0

package/blog/en-GB/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compiler vs. Declarative i18n
+description: Exploring the architectural trade-offs between "magic" compiler-based internationalisation and explicit declarative content management.
+keywords:
+  - Intlayer
+  - Internationalisation
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compiler
+  - Declarative
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# The Case for and Against Compiler-Based i18n
+
+If you have been building web applications for more than a decade, you know that Internationalisation (i18n) has always been a friction point. It is often the task no one wants to do—extracting strings, managing JSON files, and worrying about pluralisation rules.
+
+Recently, a new wave of "Compiler-based" i18n tools has emerged, promising to make this pain disappear. The pitch is seductive: **Just write text in your components, and let the build tool handle the rest.** No keys, no imports, just magic.
+
+But as with all abstractions in software engineering, magic comes with a price.
+
+In this blog post, we will explore the shift from declarative libraries to compiler-based approaches, the hidden architectural debts they introduce, and why the "boring" way might still be the best way for professional applications.
+
+## A Brief History of Translation
+
+To understand where we are, we have to look back at where we started.
+
+Around 2011–2012, the JavaScript landscape was vastly different. Bundlers as we know them (Webpack, Vite) did not exist or were in their infancy. We were gluing scripts together in the browser. In this era, libraries like **i18next** were born.
+
+They solved the problem the only way possible at the time: **Runtime Dictionaries**. You loaded a massive JSON object into memory, and a function looked up keys on the fly. It was reliable, explicit, and worked everywhere.
+
+Fast forward to today. We have powerful compilers (SWC, Rust-based bundlers) that can parse Abstract Syntax Trees (AST) in milliseconds. This power gave birth to a new idea: _Why are we manually managing keys? Why can't the compiler just see the text "Hello World" and swap it out for us?_
+
+Thus, Compiler-based i18n was born.
+
+## The Allure of the Compiler (The "Magic" Approach)
+
+There is a reason this new approach is trending. For a developer, the experience feels incredible.
+
+### 1. Speed and "Flow"
+
+When you are in the zone, stopping to think of a variable name (`home_hero_title_v2`) breaks your flow. With a compiler approach, you type `<p>Welcome back</p>` and keep moving. The friction is zero.
+
+### 2. The Legacy Rescue Mission
+
+Imagine inheriting a massive codebase with 5,000 components and zero translations. Retrofitting this with a manual key-based system is a months-long nightmare. A compiler-based tool acts as a rescue strategy, instantly extracting thousands of strings without you needing to touch a single file manually.
+
+### 3. The AI Era
+
+This is a modern benefit we shouldn't overlook. AI coding assistants (like Copilot or ChatGPT) naturally generate standard JSX/HTML. They don't know your specific translation key schema.
+
+- **Declarative:** You have to rewrite the AI's output to replace text with keys.
+- **Compiler:** You copy-paste the AI's code, and it just works.
+
+## The Reality Check: Why "Magic" is Dangerous
+
+While the "magic" is appealing, the abstraction leaks. Relying on a build tool to understand human intent introduces architectural fragility.
+
+### 1. Heuristic Fragility (The Guessing Game)
+
+The compiler has to guess what is content and what is code.
+
+- Does `className="active"` get translated? It's a string.
+- Does `status="pending"` get translated?
+- Does `<MyComponent errorMessage="An error occurred" />` get translated?
+- Does a product ID like `"AX-99"` get translated?
+
+You inevitably end up "fighting" the compiler, adding specific comments (like `// ignore-translation`) to prevent it from breaking your application logic.
+
+### 2. The Dynamic Data Hard Limit
+
+Compiler extraction relies on **static analysis**. It must see the literal string in your code to generate a stable ID.
+If your API returns an error code string like `server_error`, you cannot translate it with a compiler because the compiler doesn't know that string exists at build time. You are forced to build a secondary "runtime-only" system just for dynamic data.
+
+### 3. "Chunk Explosion" and Network Waterfalls
+
+To allow for tree-shaking, compiler tools often split translations per component.
+
+- **The Consequence:** A single page view with 50 small components might trigger **50 separate HTTP requests** for tiny translation fragments. Even with HTTP/2, this creates a network waterfall that makes your application feel sluggish compared to loading a single, optimised language bundle.
+
+### 4. Runtime Performance Overhead
+
+To make translations reactive (so they update instantly when you switch languages), the compiler often injects state management hooks into _every_ component.
+
+- **The Cost:** If you render a list of 5,000 items, you are initialising 5,000 `useState` and `useEffect` hooks solely for text. This consumes memory and CPU cycles that declarative libraries (which typically use a single Context provider) save.
+
+## The Trap: Vendor Lock-in
+
+This is arguably the most dangerous aspect of compiler-based i18n.
+
+In a declarative library, your source code contains explicit intent. You own the keys. If you switch libraries, you just change the import.
+
+In a compiler-based approach, **your source code is just English text.** The "translation logic" only exists inside the build plugin's configuration.
+If that library stops being maintained, or if you outgrow it, you are stuck. You cannot "eject" easily because you have zero translation keys in your source code. You would have to manually rewrite your entire application to migrate away.
+
+## The Other Side: Risks of the Declarative Approach
+
+To be fair, the traditional declarative way isn't perfect either. It has its own set of "footguns."
+
+1.  **Namespace Hell:** You often have to manually manage which JSON files to load (`common.json`, `dashboard.json`, `footer.json`). If you forget one, the user sees raw keys.
+2.  **Over-fetching:** Without careful configuration, it is very easy to accidentally load _all_ your translation keys for _all_ pages on the initial load, bloating your bundle size.
+3.  **Sync Drift:** It is common for keys to remain in the JSON file long after the component using them has been deleted. Your translation files grow indefinitely, filled with "zombie keys."
+
+## The Intlayer Middle Ground
+
+This is where tools like **Intlayer** are trying to innovate. Intlayer understands that while compilers are powerful, implicit magic is dangerous.
+
+Intlayer offers a unique **`transform` command`**. Instead of just doing magic in the hidden build step, it can actually **rewrite your component code**. It scans your text and replaces it with explicit content declarations in your codebase.
+
+This gives you the best of both worlds:
+
+1.  **Granularity:** You keep your translations close to your components (improving modularity and tree-shaking).
+2.  **Safety:** The translation becomes explicit code, not hidden build-time magic.
+3.  **No Lock-in:** Since the code is transformed into a standard declarative structure within your repo, you aren't hiding logic in a webpack plugin.
+
+## Conclusion
+
+So, which should you choose?
+
+**If you are a Junior Developer, a Solo Founder, or building an MVP:**
+The compiler-based approach is a valid choice. It allows you to move incredibly fast. You don't need to worry about file structures or keys. You just build. The technical debt is a problem for "Future You."
+
+**If you are building a Professional, Enterprise-Grade Application:**
+Magic is generally a bad idea. You need control.
+
+- You need to handle dynamic data from backends.
+- You need to ensure performance on low-end devices (avoiding hook explosions).
+- You need to ensure you aren't locked into a specific build tool forever.
+
+For professional apps, **Declarative Content Management** (like Intlayer or established libraries) remains the gold standard. It separates your concerns, keeps your architecture clean, and ensures that your application's ability to speak multiple languages isn't dependent on a "black box" compiler guessing your intentions.

package/blog/en-GB/intlayer_with_next-i18next.md

@@ -186,7 +186,6 @@ Exclude generated files from version control:
 ```plaintext fileName=".gitignore"
 # Ignore files generated by Intlayer
 .intlayer
-intl
 ```
 
 These files are automatically regenerated during the build process and do not need to be committed to your repository.

package/blog/en-GB/intlayer_with_vue-i18n.md

@@ -175,7 +175,6 @@ Exclude generated files from version control:
 ```plaintext fileName=".gitignore"
 # Ignore files generated by Intlayer
 .intlayer
-intl
 ```
 
 These files are automatically regenerated during the build process and do not need to be committed to your repository.

package/blog/es/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compilador vs. i18n Declarativo
+description: Explorando los compromisos arquitectónicos entre la internacionalización "mágica" basada en compiladores y la gestión explícita y declarativa de contenido.
+keywords:
+  - Intlayer
+  - Internacionalización
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compilador
+  - Declarativo
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# El Caso a Favor y en Contra de la i18n Basada en Compiladores
+
+Si has estado desarrollando aplicaciones web por más de una década, sabes que la Internacionalización (i18n) siempre ha sido un punto de fricción. A menudo es la tarea que nadie quiere hacer: extraer cadenas, gestionar archivos JSON y preocuparse por las reglas de pluralización.
+
+Recientemente, ha surgido una nueva ola de herramientas de i18n "basadas en compiladores", que prometen hacer desaparecer este dolor. La propuesta es seductora: **Simplemente escribe texto en tus componentes y deja que la herramienta de compilación se encargue del resto.** Sin claves, sin importaciones, solo magia.
+
+Pero como con todas las abstracciones en la ingeniería de software, la magia tiene un precio.
+
+En esta publicación del blog, exploraremos el cambio de bibliotecas declarativas a enfoques basados en compiladores, las deudas arquitectónicas ocultas que introducen y por qué la forma "aburrida" podría seguir siendo la mejor para aplicaciones profesionales.
+
+## Una Breve Historia de la Traducción
+
+Para entender dónde estamos, tenemos que mirar hacia atrás y ver dónde empezamos.
+
+Alrededor de 2011–2012, el panorama de JavaScript era muy diferente. Los bundlers tal como los conocemos (Webpack, Vite) no existían o estaban en sus inicios. Estábamos pegando scripts directamente en el navegador. En esta era, nacieron bibliotecas como **i18next**.
+
+Resolvieron el problema de la única manera posible en ese momento: **Diccionarios en tiempo de ejecución**. Cargabas un objeto JSON masivo en memoria, y una función buscaba las claves al vuelo. Era confiable, explícito y funcionaba en todas partes.
+
+Avanzando hasta hoy. Contamos con compiladores potentes (SWC, bundlers basados en Rust) que pueden analizar Árboles de Sintaxis Abstracta (AST) en milisegundos. Este poder dio origen a una nueva idea: _¿Por qué gestionamos las claves manualmente? ¿Por qué el compilador no puede simplemente ver el texto "Hello World" y reemplazarlo por nosotros?_
+
+Así nació la i18n basada en compiladores.
+
+## El Atractivo del Compilador (El Enfoque "Mágico")
+
+Hay una razón por la cual este nuevo enfoque está en tendencia. Para un desarrollador, la experiencia se siente increíble.
+
+### 1. Velocidad y "Flujo"
+
+Cuando estás concentrado, detenerte a pensar en un nombre de variable (`home_hero_title_v2`) rompe tu flujo. Con un enfoque basado en compilador, escribes `<p>Welcome back</p>` y sigues adelante. La fricción es cero.
+
+### 2. La Misión de Rescate del Legado
+
+Imagina heredar una base de código masiva con 5,000 componentes y cero traducciones. Adaptar esto con un sistema manual basado en claves es una pesadilla que puede durar meses. Una herramienta basada en compilador actúa como una estrategia de rescate, extrayendo instantáneamente miles de cadenas sin que necesites tocar un solo archivo manualmente.
+
+### 3. La Era de la IA
+
+Este es un beneficio moderno que no deberíamos pasar por alto. Los asistentes de codificación con IA (como Copilot o ChatGPT) generan naturalmente JSX/HTML estándar. No conocen tu esquema específico de claves de traducción.
+
+- **Declarativo:** Tienes que reescribir la salida de la IA para reemplazar el texto con claves.
+- **Compilador:** Copias y pegas el código de la IA, y simplemente funciona.
+
+## La Verificación de la Realidad: Por Qué la "Magia" es Peligrosa
+
+Aunque la "magia" es atractiva, la abstracción tiene fugas. Confiar en una herramienta de compilación para entender la intención humana introduce fragilidad arquitectónica.
+
+### 1. Fragilidad Heurística (El Juego de Adivinar)
+
+El compilador tiene que adivinar qué es contenido y qué es código.
+
+- ¿Se traduce `className="active"`? Es una cadena.
+- ¿Se traduce `status="pending"`?
+- ¿Se traduce `<MyComponent errorMessage="An error occurred" />`?
+- ¿Se traduce un ID de producto como `"AX-99"`?
+
+Inevitablemente terminas "peleando" con el compilador, añadiendo comentarios específicos (como `// ignore-translation`) para evitar que rompa la lógica de tu aplicación.
+
+### 2. El Límite Rígido de los Datos Dinámicos
+
+La extracción del compilador se basa en **análisis estático**. Debe ver la cadena literal en tu código para generar un ID estable.
+Si tu API devuelve un código de error como `server_error`, no puedes traducirlo con un compilador porque este no sabe que esa cadena existe en tiempo de compilación. Te ves obligado a construir un sistema secundario "solo en tiempo de ejecución" solo para datos dinámicos.
+
+### 3. "Explosión de Chunks" y Cascadas en la Red
+
+Para permitir el tree-shaking, las herramientas del compilador a menudo dividen las traducciones por componente.
+
+- **La consecuencia:** Una vista de página única con 50 componentes pequeños podría desencadenar **50 solicitudes HTTP separadas** para pequeños fragmentos de traducción. Incluso con HTTP/2, esto crea una cascada de red que hace que tu aplicación se sienta lenta en comparación con cargar un único paquete de idioma optimizado.
+
+### 4. Sobrecarga de rendimiento en tiempo de ejecución
+
+Para hacer que las traducciones sean reactivas (para que se actualicen instantáneamente cuando cambias de idioma), el compilador a menudo inyecta hooks de gestión de estado en _cada_ componente.
+
+- **El costo:** Si renderizas una lista de 5,000 elementos, estás inicializando 5,000 hooks `useState` y `useEffect` únicamente para el texto. Esto consume memoria y ciclos de CPU que las librerías declarativas (que típicamente usan un único proveedor de Context) ahorran.
+
+## La trampa: Vendor Lock-in
+
+Este es, sin duda, el aspecto más peligroso de la i18n basada en compiladores.
+
+En una librería declarativa, tu código fuente contiene la intención explícita. Tú posees las claves. Si cambias de librería, solo cambias la importación.
+
+En un enfoque basado en compiladores, **tu código fuente es solo texto en inglés.** La "lógica de traducción" solo existe dentro de la configuración del plugin de compilación.
+Si esa biblioteca deja de mantenerse, o si la superas, quedas atrapado. No puedes "expulsar" fácilmente porque no tienes ninguna clave de traducción en tu código fuente. Tendrías que reescribir manualmente toda tu aplicación para migrar.
+
+## El Otro Lado: Riesgos del Enfoque Declarativo
+
+Para ser justos, la forma declarativa tradicional tampoco es perfecta. Tiene su propio conjunto de "peligros".
+
+1.  **Infierno de Espacios de Nombres:** A menudo tienes que gestionar manualmente qué archivos JSON cargar (`common.json`, `dashboard.json`, `footer.json`). Si olvidas uno, el usuario ve las claves sin procesar.
+2.  **Sobre-carga de Datos:** Sin una configuración cuidadosa, es muy fácil cargar accidentalmente _todas_ tus claves de traducción para _todas_ las páginas en la carga inicial, inflando el tamaño de tu paquete.
+3.  **Deriva de sincronización:** Es común que las claves permanezcan en el archivo JSON mucho después de que el componente que las usaba haya sido eliminado. Tus archivos de traducción crecen indefinidamente, llenos de "claves zombis".
+
+## El punto medio de Intlayer
+
+Aquí es donde herramientas como **Intlayer** están intentando innovar. Intlayer entiende que, aunque los compiladores son poderosos, la magia implícita es peligrosa.
+
+Intlayer ofrece un comando único **`transform`**. En lugar de hacer magia solo en el paso oculto de compilación, puede realmente **reescribir el código de tu componente**. Escanea tu texto y lo reemplaza con declaraciones explícitas de contenido en tu base de código.
+
+Esto te da lo mejor de ambos mundos:
+
+1.  **Granularidad:** Mantienes tus traducciones cerca de tus componentes (mejorando la modularidad y el tree-shaking).
+2.  **Seguridad:** La traducción se convierte en código explícito, no en magia oculta en tiempo de compilación.
+3.  **Sin dependencia:** Dado que el código se transforma en una estructura declarativa estándar dentro de tu repositorio, no estás ocultando lógica en un plugin de webpack.
+
+## Conclusión
+
+Entonces, ¿cuál deberías elegir?
+
+**Si eres un desarrollador junior, un fundador en solitario o estás construyendo un MVP:**  
+El enfoque basado en compiladores es una opción válida. Te permite avanzar increíblemente rápido. No necesitas preocuparte por la estructura de archivos o las claves. Simplemente construyes. La deuda técnica es un problema para el "Tú del futuro".
+
+**Si estás construyendo una aplicación profesional, de nivel empresarial:**  
+La magia generalmente es una mala idea. Necesitas control.
+
+- Necesitas manejar datos dinámicos desde backends.
+- Necesitas asegurar el rendimiento en dispositivos de gama baja (evitando explosiones de hooks).
+- Necesitas asegurarte de no quedar atrapado para siempre en una herramienta de construcción específica.
+
+Para aplicaciones profesionales, la **Gestión Declarativa de Contenidos** (como Intlayer o bibliotecas establecidas) sigue siendo el estándar de oro. Separa tus preocupaciones, mantiene tu arquitectura limpia y garantiza que la capacidad de tu aplicación para hablar múltiples idiomas no dependa de un compilador "caja negra" que adivine tus intenciones.

package/blog/es/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ Excluye los archivos generados del control de versiones:
 ```plaintext fileName=".gitignore"
 # Ignorar archivos generados por Intlayer
 .intlayer
-intl
 ```
 
 Estos archivos se regeneran automáticamente durante el proceso de compilación y no necesitan ser confirmados en tu repositorio.

package/blog/es/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Excluye los archivos generados del control de versiones:
 ```plaintext fileName=".gitignore"
 # Ignorar archivos generados por Intlayer
 .intlayer
-intl
 ```
 
 Estos archivos se regeneran automáticamente durante el proceso de compilación y no necesitan ser comprometidos en tu repositorio.

package/blog/fr/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: Compilateur vs. i18n déclaratif
+description: Exploration des compromis architecturaux entre l'internationalisation "magique" basée sur un compilateur et la gestion explicite et déclarative du contenu.
+keywords:
+  - Intlayer
+  - Internationalisation
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - Compilateur
+  - Déclaratif
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# Les arguments pour et contre l’i18n basée sur un compilateur
+
+Si vous développez des applications web depuis plus d’une décennie, vous savez que l’internationalisation (i18n) a toujours été un point de friction. C’est souvent la tâche que personne ne veut faire : extraire les chaînes, gérer les fichiers JSON, et se soucier des règles de pluriel.
+
+Récemment, une nouvelle vague d’outils i18n « basés sur un compilateur » a émergé, promettant de faire disparaître cette douleur. L’argument est séduisant : **Il suffit d’écrire le texte dans vos composants, et laissez l’outil de build gérer le reste.** Pas de clés, pas d’importations, juste de la magie.
+
+Mais comme pour toutes les abstractions en ingénierie logicielle, la magie a un prix.
+
+Dans cet article de blog, nous allons explorer le passage des bibliothèques déclaratives aux approches basées sur un compilateur, les dettes architecturales cachées qu’elles introduisent, et pourquoi la méthode « ennuyeuse » pourrait encore être la meilleure pour les applications professionnelles.
+
+## Une brève histoire de la traduction
+
+Pour comprendre où nous en sommes, il faut revenir à nos débuts.
+
+Vers 2011–2012, le paysage JavaScript était très différent. Les bundlers tels que nous les connaissons (Webpack, Vite) n’existaient pas ou étaient à leurs débuts. Nous collions les scripts ensemble dans le navigateur. C’est à cette époque que des bibliothèques comme **i18next** sont nées.
+
+Elles ont résolu le problème de la seule manière possible à l’époque : les **Dictionnaires à l’exécution**. Vous chargiez un énorme objet JSON en mémoire, et une fonction recherchait les clés à la volée. C’était fiable, explicite, et fonctionnait partout.
+
+Avançons jusqu’à aujourd’hui. Nous disposons de compilateurs puissants (SWC, bundlers basés sur Rust) capables d’analyser des arbres de syntaxe abstraite (AST) en quelques millisecondes. Cette puissance a donné naissance à une nouvelle idée : _Pourquoi gérer manuellement les clés ? Pourquoi le compilateur ne pourrait-il pas simplement voir le texte "Hello World" et le remplacer pour nous ?_
+
+Ainsi est née l’i18n basée sur un compilateur.
+
+## L’Attrait du Compilateur (L’Approche "Magique")
+
+Il y a une raison pour laquelle cette nouvelle approche est tendance. Pour un développeur, l’expérience est incroyable.
+
+### 1. Vitesse et "Flow"
+
+Quand vous êtes dans votre zone, vous arrêter pour réfléchir à un nom de variable (`home_hero_title_v2`) casse votre flow. Avec une approche compilateur, vous tapez `<p>Welcome back</p>` et continuez. La friction est nulle.
+
+### 2. La Mission de Sauvetage du Legacy
+
+Imaginez hériter d’une énorme base de code avec 5 000 composants et aucune traduction. Adapter cela avec un système manuel basé sur des clés est un cauchemar qui dure des mois. Un outil basé sur un compilateur agit comme une stratégie de sauvetage, extrayant instantanément des milliers de chaînes sans que vous ayez besoin de toucher un seul fichier manuellement.
+
+### 3. L’Ère de l’IA
+
+C’est un avantage moderne qu’il ne faut pas négliger. Les assistants de codage IA (comme Copilot ou ChatGPT) génèrent naturellement du JSX/HTML standard. Ils ne connaissent pas votre schéma spécifique de clés de traduction.
+
+- **Déclaratif :** Vous devez réécrire la sortie de l’IA pour remplacer le texte par des clés.
+- **Compilateur :** Vous copiez-collez le code de l’IA, et ça fonctionne tout simplement.
+
+## La Réalité : Pourquoi la "Magie" est Dangereuse
+
+Bien que la "magie" soit séduisante, l’abstraction fuit. Compter sur un outil de build pour comprendre l’intention humaine introduit une fragilité architecturale.
+
+### 1. Fragilité Heuristique (Le Jeu de Deviner)
+
+Le compilateur doit deviner ce qui est contenu et ce qui est code.
+
+- Est-ce que `className="active"` est traduit ? C’est une chaîne de caractères.
+- Est-ce que `status="pending"` est traduit ?
+- Est-ce que `<MyComponent errorMessage="An error occurred" />` est traduit ?
+- Est-ce qu’un identifiant produit comme `"AX-99"` est traduit ?
+
+Vous finissez inévitablement par « lutter » contre le compilateur, en ajoutant des commentaires spécifiques (comme `// ignore-translation`) pour l’empêcher de casser la logique de votre application.
+
+### 2. La limite stricte des données dynamiques
+
+L’extraction par le compilateur repose sur une **analyse statique**. Il doit voir la chaîne littérale dans votre code pour générer un ID stable.
+Si votre API renvoie une chaîne de code d’erreur comme `server_error`, vous ne pouvez pas la traduire avec un compilateur car celui-ci ne connaît pas cette chaîne au moment de la compilation. Vous êtes obligé de construire un système secondaire « runtime-only » uniquement pour les données dynamiques.
+
+### 3. « Explosion des chunks » et cascades réseau
+
+Pour permettre le tree-shaking, les outils de compilation divisent souvent les traductions par composant.
+
+- **La conséquence :** Une seule vue de page avec 50 petits composants peut déclencher **50 requêtes HTTP distinctes** pour de petits fragments de traduction. Même avec HTTP/2, cela crée un effet de cascade réseau qui rend votre application lente comparée au chargement d’un seul bundle de langue optimisé.
+
+### 4. Surcharge des performances à l’exécution
+
+Pour rendre les traductions réactives (afin qu’elles se mettent à jour instantanément lorsque vous changez de langue), le compilateur injecte souvent des hooks de gestion d’état dans _chaque_ composant.
+
+- **Le Coût :** Si vous affichez une liste de 5 000 éléments, vous initialisez 5 000 hooks `useState` et `useEffect` uniquement pour le texte. Cela consomme de la mémoire et des cycles CPU que les bibliothèques déclaratives (qui utilisent généralement un seul fournisseur Context) économisent.
+
+## Le Piège : Le Verrouillage Fournisseur
+
+C'est sans doute l'aspect le plus dangereux de l'i18n basée sur un compilateur.
+
+Dans une bibliothèque déclarative, votre code source contient une intention explicite. Vous possédez les clés. Si vous changez de bibliothèque, vous changez simplement l'import.
+
+Dans une approche basée sur un compilateur, **votre code source n'est que du texte en anglais.** La "logique de traduction" n'existe que dans la configuration du plugin de build.
+Si cette bibliothèque cesse d’être maintenue, ou si vous la dépassez, vous êtes bloqué. Vous ne pouvez pas facilement « éjecter » car vous n’avez aucune clé de traduction dans votre code source. Vous devriez réécrire manuellement toute votre application pour migrer.
+
+## L’autre côté : risques de l’approche déclarative
+
+Pour être juste, la méthode déclarative traditionnelle n’est pas parfaite non plus. Elle a ses propres « pièges ».
+
+1.  **L’enfer des namespaces :** Vous devez souvent gérer manuellement quels fichiers JSON charger (`common.json`, `dashboard.json`, `footer.json`). Si vous en oubliez un, l’utilisateur voit les clés brutes.
+2.  **Surcharge de requêtes :** Sans une configuration soigneuse, il est très facile de charger accidentellement _toutes_ vos clés de traduction pour _toutes_ les pages dès le chargement initial, ce qui alourdit la taille de votre bundle.
+3.  **Dérive de synchronisation :** Il est courant que des clés restent dans le fichier JSON bien après que le composant qui les utilise ait été supprimé. Vos fichiers de traduction grossissent indéfiniment, remplis de « clés zombies ».
+
+## Le juste milieu avec Intlayer
+
+C’est là que des outils comme **Intlayer** cherchent à innover. Intlayer comprend que, bien que les compilateurs soient puissants, la magie implicite est dangereuse.
+
+Intlayer propose une commande unique **`transform`**. Au lieu de faire simplement de la magie dans une étape de build cachée, elle peut en réalité **réécrire votre code de composant**. Elle analyse votre texte et le remplace par des déclarations de contenu explicites dans votre base de code.
+
+Cela vous offre le meilleur des deux mondes :
+
+1.  **Granularité :** Vous gardez vos traductions proches de vos composants (améliorant la modularité et le tree-shaking).
+2.  **Sécurité :** La traduction devient un code explicite, et non une magie cachée au moment de la compilation.
+3.  **Pas de verrouillage :** Puisque le code est transformé en une structure déclarative standard dans votre dépôt, vous ne cachez pas la logique dans un plugin webpack.
+
+## Conclusion
+
+Alors, que devriez-vous choisir ?
+
+**Si vous êtes un développeur junior, un fondateur solo, ou que vous construisez un MVP :**
+L'approche basée sur le compilateur est un choix valide. Elle vous permet d'avancer extrêmement vite. Vous n'avez pas besoin de vous soucier des structures de fichiers ou des clés. Vous construisez simplement. La dette technique est un problème pour le "Vous du futur".
+
+**Si vous construisez une application professionnelle de niveau entreprise :**
+La magie est généralement une mauvaise idée. Vous avez besoin de contrôle.
+
+- Vous devez gérer des données dynamiques provenant des backends.
+- Vous devez garantir la performance sur des appareils peu puissants (en évitant les explosions de hooks).
+- Vous devez vous assurer de ne pas être enfermé à jamais dans un outil de build spécifique.
+
+Pour les applications professionnelles, la **Gestion de Contenu Déclarative** (comme Intlayer ou des bibliothèques établies) reste la référence. Elle sépare vos préoccupations, maintient votre architecture propre, et garantit que la capacité de votre application à parler plusieurs langues ne dépend pas d'un compilateur "boîte noire" devinant vos intentions.

package/blog/fr/intlayer_with_next-i18next.md

@@ -176,7 +176,6 @@ Exclure les fichiers générés du contrôle de version :
 ```plaintext fileName=".gitignore"
 # Ignorer les fichiers générés par Intlayer
 .intlayer
-intl
 ```
 
 Ces fichiers sont automatiquement régénérés lors du processus de build et n'ont pas besoin d'être commités dans votre dépôt.

package/blog/fr/intlayer_with_vue-i18n.md

@@ -166,7 +166,6 @@ Exclure les fichiers générés du contrôle de version :
 ```plaintext fileName=".gitignore"
 # Ignorer les fichiers générés par Intlayer
 .intlayer
-intl
 ```
 
 Ces fichiers sont automatiquement régénérés lors du processus de build et n'ont pas besoin d'être commités dans votre dépôt.

package/blog/hi/compiler_vs_declarative_i18n.md

@@ -0,0 +1,138 @@
+---
+createdAt: 2025-11-24
+updatedAt: 2025-11-24
+title: कंपाइलर बनाम घोषणात्मक i18n
+description: "मैजिक" कंपाइलर-आधारित अंतरराष्ट्रीयकरण और स्पष्ट घोषणात्मक सामग्री प्रबंधन के बीच वास्तुशिल्पीय ट्रेड-ऑफ का अन्वेषण।
+keywords:
+  - Intlayer
+  - अंतरराष्ट्रीयकरण
+  - ब्लॉग
+  - Next.js
+  - JavaScript
+  - React
+  - i18n
+  - कंपाइलर
+  - घोषणात्मक
+slugs:
+  - compiler-vs-declarative-i18n
+  - blog
+  - i18n
+---
+
+# कंपाइलर-आधारित i18n के पक्ष और विपक्ष
+
+यदि आप एक दशक से अधिक समय से वेब एप्लिकेशन बना रहे हैं, तो आप जानते हैं कि अंतरराष्ट्रीयकरण (i18n) हमेशा एक संघर्ष का बिंदु रहा है। यह अक्सर वह कार्य होता है जिसे कोई करना नहीं चाहता — स्ट्रिंग्स निकालना, JSON फ़ाइलों का प्रबंधन करना, और बहुवचन नियमों की चिंता करना।
+
+हाल ही में, "कंपाइलर-आधारित" i18n टूल्स की एक नई लहर उभरी है, जो इस दर्द को गायब करने का वादा करती है। प्रस्तुति आकर्षक है: **बस अपने कंपोनेंट्स में टेक्स्ट लिखें, और बाकी काम बिल्ड टूल पर छोड़ दें।** न कोई कीज़, न कोई इम्पोर्ट्स, बस जादू।
+
+लेकिन सॉफ़्टवेयर इंजीनियरिंग में सभी अमूर्तताओं की तरह, जादू की भी एक कीमत होती है।
+
+इस ब्लॉग पोस्ट में, हम घोषणात्मक लाइब्रेरीज से कंपाइलर-आधारित दृष्टिकोण की ओर हुए बदलाव, उनके द्वारा लाए गए छिपे हुए वास्तुशिल्पीय ऋण, और क्यों "निरस" तरीका अभी भी पेशेवर एप्लिकेशन के लिए सबसे अच्छा तरीका हो सकता है, का अन्वेषण करेंगे।
+
+## अनुवाद का संक्षिप्त इतिहास
+
+यह समझने के लिए कि हम कहां हैं, हमें यह देखना होगा कि हमने कहां से शुरुआत की थी।
+
+2011–2012 के आसपास, JavaScript का परिदृश्य काफी अलग था। जैसे हम आज जानते हैं, वे बंडलर्स (Webpack, Vite) मौजूद नहीं थे या वे अपने प्रारंभिक चरण में थे। हम ब्राउज़र में स्क्रिप्ट्स को जोड़ रहे थे। इसी युग में, **i18next** जैसी लाइब्रेरीज का जन्म हुआ।
+
+उन्होंने उस समय संभव唯一 तरीके से समस्या का समाधान किया: **रनटाइम डिक्शनरीज़**। आप एक विशाल JSON ऑब्जेक्ट मेमोरी में लोड करते थे, और एक फ़ंक्शन तुरंत कीज़ को खोजता था। यह विश्वसनीय, स्पष्ट था, और हर जगह काम करता था।
+
+आज की ओर तेजी से बढ़ें। हमारे पास शक्तिशाली कंपाइलर हैं (SWC, Rust-आधारित बंडलर्स) जो Abstract Syntax Trees (AST) को मिलीसेकंड में पार्स कर सकते हैं। इस शक्ति ने एक नया विचार जन्म दिया: _हम मैन्युअली कीज़ क्यों प्रबंधित कर रहे हैं? क्यों कंपाइलर सीधे "Hello World" टेक्स्ट को देख कर हमारे लिए बदल नहीं सकता?_
+
+इस प्रकार, कंपाइलर-आधारित i18n का जन्म हुआ।
+
+## कंपाइलर का आकर्षण (The "Magic" Approach)
+
+इस नए दृष्टिकोण के ट्रेंड में आने का एक कारण है। एक डेवलपर के लिए, यह अनुभव अविश्वसनीय लगता है।
+
+### 1. गति और "फ्लो"
+
+जब आप काम में डूबे होते हैं, तो एक वेरिएबल नाम (`home_hero_title_v2`) सोचने के लिए रुकना आपके फ्लो को तोड़ देता है। कंपाइलर दृष्टिकोण के साथ, आप `<p>Welcome back</p>` टाइप करते हैं और आगे बढ़ते रहते हैं। कोई रुकावट नहीं होती।
+
+### 2. विरासत बचाव मिशन
+
+कल्पना करें कि आपको 5,000 कंपोनेंट्स वाला एक विशाल कोडबेस विरासत में मिला है जिसमें कोई अनुवाद नहीं है। इसे मैन्युअल की-आधारित सिस्टम से अनुकूलित करना महीनों लंबा दुःस्वप्न होगा। एक कंपाइलर-आधारित टूल एक बचाव रणनीति के रूप में काम करता है, जो बिना किसी फाइल को मैन्युअली छुए तुरंत हजारों स्ट्रिंग्स निकाल देता है।
+
+### 3. एआई युग
+
+यह एक आधुनिक लाभ है जिसे हमें नजरअंदाज नहीं करना चाहिए। AI कोडिंग असिस्टेंट्स (जैसे Copilot या ChatGPT) स्वाभाविक रूप से मानक JSX/HTML उत्पन्न करते हैं। वे आपके विशिष्ट अनुवाद कुंजी स्कीमा को नहीं जानते।
+
+- **Declarative:** आपको AI के आउटपुट को फिर से लिखना होता है ताकि टेक्स्ट को कुंजियों से बदला जा सके।
+- **Compiler:** आप AI का कोड कॉपी-पेस्ट करते हैं, और यह बस काम करता है।
+
+## वास्तविकता जांच: क्यों "मैजिक" खतरनाक है
+
+जबकि "मैजिक" आकर्षक है, लेकिन अमूर्तता लीक होती है। एक बिल्ड टूल पर मानव इरादे को समझने के लिए निर्भर रहना वास्तुशिल्पीय कमजोरी लाता है।
+
+### 1. हीयूरिस्टिक कमजोरी (अनुमान लगाने का खेल)
+
+कंपाइलर को यह अनुमान लगाना होता है कि क्या कंटेंट है और क्या कोड है।
+
+- क्या `className="active"` का अनुवाद होता है? यह एक स्ट्रिंग है।
+- क्या `status="pending"` का अनुवाद होता है?
+- क्या `<MyComponent errorMessage="An error occurred" />` का अनुवाद होता है?
+- क्या `"AX-99"` जैसे उत्पाद आईडी का अनुवाद होता है?
+
+आप अंततः "कंपाइलर से लड़ते" हुए पाएंगे, विशिष्ट टिप्पणियाँ (जैसे `// ignore-translation`) जोड़कर ताकि यह आपकी एप्लिकेशन लॉजिक को तोड़ने से रोका जा सके।
+
+### 2. डायनेमिक डेटा की कठोर सीमा
+
+कंपाइलर निष्कर्षण **स्थैतिक विश्लेषण** पर निर्भर करता है। इसे आपके कोड में सटीक स्ट्रिंग देखनी होती है ताकि एक स्थिर ID बनाई जा सके।
+यदि आपका API `server_error` जैसे त्रुटि कोड स्ट्रिंग लौटाता है, तो आप इसे कंपाइलर के साथ अनुवादित नहीं कर सकते क्योंकि कंपाइलर को बिल्ड समय पर उस स्ट्रिंग के अस्तित्व का पता नहीं होता। आपको डायनेमिक डेटा के लिए एक द्वितीयक "रनटाइम-केवल" सिस्टम बनाना पड़ता है।
+
+### 3. "चंक विस्फोट" और नेटवर्क वॉटरफॉल्स
+
+ट्री-शेकिंग की अनुमति देने के लिए, कंपाइलर टूल अक्सर अनुवादों को प्रत्येक कंपोनेंट के अनुसार विभाजित करते हैं।
+
+- **परिणाम:** 50 छोटे कंपोनेंट्स वाली एक ही पेज व्यू में **50 अलग-अलग HTTP अनुरोध** हो सकते हैं छोटे अनुवाद खंडों के लिए। HTTP/2 के बावजूद, यह एक नेटवर्क वॉटरफॉल बनाता है जो आपकी एप्लिकेशन को एकल, अनुकूलित भाषा बंडल की तुलना में धीमा महसूस कराता है।
+
+### 4. रनटाइम प्रदर्शन ओवरहेड
+
+अनुवादों को प्रतिक्रियाशील बनाने के लिए (ताकि जब आप भाषाएँ बदलें तो वे तुरंत अपडेट हों), कंपाइलर अक्सर _हर_ कंपोनेंट में स्टेट मैनेजमेंट हुक्स इंजेक्ट करता है।
+
+- **लागत:** यदि आप 5,000 आइटम की एक सूची रेंडर करते हैं, तो आप केवल टेक्स्ट के लिए 5,000 `useState` और `useEffect` हुक्स इनिशियलाइज़ कर रहे हैं। यह मेमोरी और CPU चक्रों को खपत करता है, जिन्हें डिक्लेरेटिव लाइब्रेरीज़ (जो आमतौर पर एकल Context प्रोवाइडर का उपयोग करती हैं) बचाती हैं।
+
+## जाल: विक्रेता लॉक-इन
+
+यह संभवतः कंपाइलर-आधारित i18n का सबसे खतरनाक पहलू है।
+
+एक डिक्लेरेटिव लाइब्रेरी में, आपके स्रोत कोड में स्पष्ट इरादा होता है। आप कुंजियों के मालिक होते हैं। यदि आप लाइब्रेरी बदलते हैं, तो आप केवल इम्पोर्ट बदलते हैं।
+
+कंपाइलर-आधारित दृष्टिकोण में, **आपका स्रोत कोड केवल अंग्रेज़ी टेक्स्ट होता है।** "अनुवाद लॉजिक" केवल बिल्ड प्लगइन की कॉन्फ़िगरेशन के अंदर मौजूद होता है।
+यदि वह लाइब्रेरी मेंटेन करना बंद कर देती है, या यदि आप उससे आगे बढ़ जाते हैं, तो आप फंसे हुए हैं। आप आसानी से "eject" नहीं कर सकते क्योंकि आपके स्रोत कोड में कोई ट्रांसलेशन कीज़ नहीं हैं। आपको मैन्युअली अपना पूरा एप्लिकेशन फिर से लिखना होगा ताकि आप माइग्रेट कर सकें।
+
+## दूसरी तरफ: डिक्लेरेटिव दृष्टिकोण के जोखिम
+
+सच कहें तो, पारंपरिक डिक्लेरेटिव तरीका भी परफेक्ट नहीं है। इसके अपने "footguns" होते हैं।
+
+1.  **Namespace Hell:** आपको अक्सर मैन्युअली यह प्रबंधित करना पड़ता है कि कौन से JSON फाइलें लोड करनी हैं (`common.json`, `dashboard.json`, `footer.json`)। यदि आप कोई फाइल भूल जाते हैं, तो उपयोगकर्ता को कच्ची कुंजियाँ दिखाई देती हैं।
+2.  **Over-fetching:** सावधानीपूर्वक कॉन्फ़िगरेशन के बिना, यह बहुत आसान है कि आप गलती से प्रारंभिक लोड पर _सभी_ पृष्ठों के लिए _सभी_ ट्रांसलेशन कीज़ लोड कर लें, जिससे आपके बंडल का आकार बढ़ जाता है।
+3.  **सिंक ड्रिफ्ट:** यह आम बात है कि JSON फाइल में कुंजियाँ तब तक बनी रहती हैं जब तक कि उन कुंजियों का उपयोग करने वाला कंपोनेंट डिलीट नहीं हो जाता। आपकी ट्रांसलेशन फाइलें अनंत तक बढ़ती रहती हैं, जो "ज़ॉम्बी कीज़" से भरी होती हैं।
+
+## Intlayer का मध्य मार्ग
+
+यहीं पर **Intlayer** जैसे टूल्स नवाचार करने की कोशिश कर रहे हैं। Intlayer समझता है कि जबकि कंपाइलर शक्तिशाली होते हैं, अप्रत्यक्ष जादू खतरनाक होता है।
+
+Intlayer एक अनोखा **`transform` कमांड** प्रदान करता है। छिपे हुए बिल्ड स्टेप में जादू करने के बजाय, यह वास्तव में **आपके कंपोनेंट कोड को फिर से लिख सकता है**। यह आपके टेक्स्ट को स्कैन करता है और इसे आपके कोडबेस में स्पष्ट कंटेंट डिक्लेरेशन से बदल देता है।
+
+यह आपको दोनों दुनिया का सर्वश्रेष्ठ देता है:
+
+1.  **ग्रैन्युलैरिटी:** आप अपनी ट्रांसलेशन्स को अपने कंपोनेंट्स के करीब रखते हैं (जो मॉड्यूलैरिटी और ट्री-शेकिंग में सुधार करता है)।
+2.  **सुरक्षा:** अनुवाद स्पष्ट कोड बन जाता है, छिपे हुए बिल्ड-टाइम जादू नहीं।
+3.  **कोई लॉक-इन नहीं:** चूंकि कोड आपके रिपॉजिटरी के भीतर एक मानक घोषणात्मक संरचना में परिवर्तित हो जाता है, आप लॉजिक को वेबपैक प्लगइन में छिपा नहीं रहे हैं।
+
+## निष्कर्ष
+
+तो, आपको क्या चुनना चाहिए?
+
+**यदि आप एक जूनियर डेवलपर, एक सोलो फाउंडर, या MVP बना रहे हैं:**
+कंपाइलर-आधारित दृष्टिकोण एक वैध विकल्प है। यह आपको बेहद तेज़ी से आगे बढ़ने की अनुमति देता है। आपको फाइल संरचनाओं या कुंजियों की चिंता करने की जरूरत नहीं है। आप बस निर्माण करते हैं। तकनीकी ऋण "भविष्य के आप" के लिए एक समस्या है।
+
+**यदि आप एक पेशेवर, एंटरप्राइज-ग्रेड एप्लिकेशन बना रहे हैं:**
+जादू आमतौर पर एक बुरा विचार है। आपको नियंत्रण की आवश्यकता है।
+
+- आपको बैकएंड से डायनेमिक डेटा को संभालना होगा।
+- आपको कम-श्रेणी के उपकरणों पर प्रदर्शन सुनिश्चित करना होगा (हुक विस्फोटों से बचते हुए)।
+- आपको यह सुनिश्चित करना होगा कि आप हमेशा के लिए किसी विशिष्ट बिल्ड टूल में लॉक न हों।
+
+पेशेवर ऐप्स के लिए, **घोषणात्मक कंटेंट मैनेजमेंट** (जैसे Intlayer या स्थापित लाइब्रेरी) स्वर्ण मानक बना रहता है। यह आपकी चिंताओं को अलग करता है, आपकी आर्किटेक्चर को साफ़ रखता है, और यह सुनिश्चित करता है कि आपकी एप्लिकेशन की बहुभाषी क्षमता किसी "ब्लैक बॉक्स" कंपाइलर पर निर्भर न हो जो आपकी मंशाओं का अनुमान लगाता हो।