Intlayer

--- createdAt: 2025-11-24 updatedAt: 2025-11-24 title: Compilador vs. i18n Declarativo description: Explorando las compensaciones arquitectónicas entre la internacionalización "mágica" basada en compilador y la gestión explícita y declarativa de contenido. keywords: - Intlayer - Internacionalización - Blog - Next.js - JavaScript - React - i18n - Compilador - Declarativo slugs: - blog - compiler-vs-declarative-i18n --- # Argumentos a favor y en contra de la i18n basada en compilador 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 compilador"**, 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 las bibliotecas declarativas a los 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. ## Tabla de contenidos <TOC/> ## Una breve historia de la internacionalización Para entender dónde estamos, debemos mirar hacia atrás y ver dónde comenzamos. 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 uniendo scripts directamente en el navegador. En esta época, 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 enorme en memoria, y una función buscaba las claves sobre la marcha. Era fiable, explícito y funcionaba en todas partes. Avancemos 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 manualmente las claves? ¿Por qué el compilador no puede simplemente ver el texto "Hello World" y reemplazarlo por nosotros?_ Así nació la i18n basada en compiladores. > **Ejemplo de i18n basado en compiladores:** > > - Paraglide (Módulos tree-shaken que compilan cada mensaje en una pequeña función ESM para que los bundlers puedan eliminar automáticamente locales y claves no usadas. Importas los mensajes como funciones en lugar de hacer búsquedas por claves de cadena.) > - LinguiJS (Compilador de macro a función que reescribe macros de mensajes como `<Trans>` en llamadas a funciones JS simples en tiempo de compilación. Obtienes sintaxis ICU/MessageFormat con una huella de ejecución muy pequeña.) > - Lingo.dev (Se enfoca en automatizar la canalización de localización inyectando contenido traducido directamente durante la compilación de tu aplicación React. Puede generar traducciones automáticamente usando IA e integrarse directamente en CI/CD.) > - Wuchale (Preprocesador orientado a Svelte que extrae texto en línea en archivos .svelte y lo compila en funciones de traducción sin envoltorios. Evita las claves de cadena y separa completamente la lógica de extracción de contenido del runtime principal de la aplicación.) > - Intlayer (Compilador / CLI de extracción que analiza tus componentes, genera diccionarios tipados y puede opcionalmente reescribir código para usar contenido explícito de Intlayer. El objetivo es usar el compilador para velocidad manteniendo un núcleo declarativo y agnóstico al framework.) > **Ejemplo de i18n declarativo:** > > - i18next / react-i18next / next-i18next (El estándar maduro de la industria que utiliza diccionarios JSON en tiempo de ejecución y un extenso ecosistema de plugins) > - react-intl (Parte de la biblioteca FormatJS, enfocada en la sintaxis estándar de mensajes ICU y un formateo estricto de datos) > - next-intl (Optimizado específicamente para Next.js con integración para el App Router y React Server Components) > - vue-i18n / @nuxt/i18n (La solución estándar del ecosistema Vue que ofrece bloques de traducción a nivel de componente e integración estrecha con la reactividad) > - svelte-i18n (Un envoltorio ligero alrededor de las stores de Svelte para traducciones reactivas en tiempo de ejecución) > - angular-translate (La biblioteca heredada de traducción dinámica que se basa en búsquedas de claves en tiempo de ejecución en lugar de la fusión en tiempo de compilación) > - angular-i18n (El enfoque nativo de Angular, adelantado en tiempo, que fusiona archivos XLIFF directamente en las plantillas durante la compilación) > - Tolgee (Combina código declarativo con un SDK en contexto para edición "click-to-translate" directamente en la interfaz de usuario) > - Intlayer (Enfoque por componente, usando archivos de declaraciones de contenido que permiten tree-shaking nativo y validación en TypeScript) ## El Compilador de Intlayer Aunque **Intlayer** es una solución que fundamentalmente fomenta un **enfoque declarativo** para tu contenido, incluye un compilador para ayudar a acelerar el desarrollo o facilitar la creación rápida de prototipos. El compilador de Intlayer recorre el AST (Árbol de Sintaxis Abstracta) de tus componentes React, Vue o Svelte, así como otros archivos JavaScript/TypeScript. Su función es detectar cadenas de texto codificadas directamente y extraerlas en declaraciones dedicadas `.content`. > Para más detalles, consulta la documentación: [Documentación del Compilador Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compiler.md) ## 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 "Flow" Cuando estás en la zona, detenerte a pensar en un nombre de variable semántico (`home_hero_title_v2`) rompe tu flujo. Con un enfoque de 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. ### Fragilidad Heurística (El Juego de Adivinar) El compilador tiene que adivinar qué es contenido y qué es código. Esto conduce a casos límite donde terminas "luchando" contra la herramienta. Considera estos escenarios: - ¿Se extrae `<span className="active"></span>`? (Es una cadena, pero probablemente una clase). - ¿Se extrae `<span status="pending"></span>`? (Es un valor de prop). - ¿Se extrae `<span>{"Hello World"}</span>`? (Es una expresión JS). - ¿Se extrae `<span>Hello {name}. How are you?</span>`? (La interpolación es compleja). - ¿Se extrae `<span aria-label="Image of cat"></span>`? (Los atributos de accesibilidad necesitan traducción). - ¿Se extrae `<span data-testid="my-element"></span>`? (Los IDs de prueba NO deben traducirse). - ¿Se extrae `<MyComponent errorMessage="An error occurred" />`? - ¿Se extrae `<p>This is a paragraph{" "}\n containing multiple lines</p>`? - ¿Se extrae el resultado de la función `<p>{getStatusMessage()}</p>`? - ¿Se extrae `<div>{isLoading ? "The page is loading" : <MyComponent/>} </div>`? - ¿Se extrae un ID de producto como `<span>AX-99</span>`? Inevitablemente terminas agregando comentarios específicos (como `// ignore-translation`, o props específicos como `data-compiler-ignore="true"`) para evitar que rompa la lógica de tu aplicación. ### ¿Cómo maneja Intlayer esta complejidad? Intlayer utiliza un enfoque mixto para detectar si un campo debe ser extraído para traducción, intentando minimizar los falsos positivos: 1. **Análisis AST:** Verifica el tipo de elemento (por ejemplo, distinguiendo entre un `reactNode`, una `label` o una propiedad `title`). 2. **Reconocimiento de patrones:** Detecta si la cadena está en mayúscula o incluye espacios, lo que sugiere que probablemente sea texto legible por humanos en lugar de un identificador de código. ### El límite estricto de datos dinámicos La extracción del compilador se basa en el **análisis estático**. Debe ver la cadena literal en tu código para generar un ID estable. Si tu API devuelve una cadena de código de error como `server_error`, no puedes traducirla con un compilador porque el compilador no sabe que esa cadena existe en tiempo de compilación. Estás obligado a construir un sistema secundario "solo en tiempo de ejecución" únicamente para datos dinámicos. ### Falta de segmentación (chunking) Ciertos compiladores no segmentan las traducciones por página. Si tu compilador genera un archivo JSON grande por idioma (por ejemplo, `./lang/en.json`, `./lang/fr.json`, etc.), probablemente terminarás cargando contenido de todas tus páginas para una sola página visitada. Además, cada componente que use tu contenido probablemente será hidratado con mucho más contenido del necesario, lo que puede causar problemas de rendimiento. También tenga cuidado al cargar sus traducciones dinámicamente. Si esto no se hace, cargará contenido para todos los idiomas además del actual. > Para ilustrar el problema, considere un sitio con 10 páginas y 10 idiomas (todos 100% únicos). Cargaría contenido para 99 páginas adicionales (10 × 10 - 1). ### "Explosión de chunks" y cascadas de red Para resolver el problema del chunking, algunas soluciones ofrecen chunking por componente, o incluso por clave. Sin embargo, el problema solo se resuelve parcialmente. El argumento de venta de estas soluciones suele ser decir "Tu contenido está tree-shakeado." De hecho, si cargas contenido estáticamente, tu solución eliminará el contenido no utilizado, pero aún así terminarás con contenido de todos los idiomas cargado con tu aplicación. Entonces, ¿por qué no cargarlo dinámicamente? Sí, en ese caso cargarás más contenido del necesario, pero no está exento de compromisos. Cargar contenido dinámicamente aísla cada fragmento de contenido en su propio chunk, que solo se cargará cuando el componente se renderice. Esto significa que harás una solicitud HTTP por cada bloque de texto. ¿1,000 bloques de texto en tu página? → 1,000 solicitudes HTTP a tus servidores. Y para limitar el daño y optimizar el tiempo de la primera renderización de tu aplicación, necesitarás insertar múltiples límites de Suspense o Skeleton Loaders. > Nota: Incluso con Next.js y SSR, tus componentes aún se hidratarán después de la carga, por lo que las solicitudes HTTP seguirán realizándose. ¿La solución? Adoptar una solución que permita declarar declaraciones de contenido con ámbito, como lo hacen `i18next`, `next-intl` o `intlayer`. > Nota: `i18next` y `next-intl` requieren que gestiones manualmente las importaciones de tus namespaces / mensajes para cada página con el fin de optimizar el tamaño de tu bundle. Deberías usar un analizador de bundles como `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) o `webpack-bundle-analyzer` (React CRA / Angular / etc) para detectar si estás contaminando tu bundle con traducciones no usadas. ### Sobrecarga de Rendimiento en Tiempo de Ejecución Para hacer que las traducciones sean reactivas (de modo 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, estarás inicializando 5,000 hooks `useState` y `useEffect` únicamente para el texto. React debe identificar y volver a renderizar los 5,000 consumidores simultáneamente. Esto provoca un bloqueo masivo del "Main Thread", congelando la interfaz durante el cambio. Esto consume memoria y ciclos de CPU que las librerías declarativas (que típicamente usan un único proveedor de Context) ahorran. > Ten en cuenta que el problema es similar para otros frameworks que no sean React. ## La trampa: Vendor Lock-in Ten cuidado al elegir una solución i18n que permita la extracción o migración de las claves de traducción. En el caso de una biblioteca declarativa, tu código fuente contiene explícitamente tu intención de traducción: estas son tus claves, y tú las controlas. Si deseas cambiar de biblioteca, generalmente solo necesitas actualizar la importación. Con un enfoque de compilador, tu código fuente podría ser solo texto en inglés plano, sin rastro de lógica de traducción: todo está oculto en la configuración de la herramienta de construcción. Si ese plugin deja de mantenerse o quieres cambiar de solución, podrías quedarte atascado. No hay una forma fácil de "expulsar": no hay claves utilizables en tu código, y podrías necesitar regenerar todas tus traducciones para una nueva biblioteca. Algunas soluciones también ofrecen servicios de generación de traducciones. ¿No más créditos? No más traducciones. Los compiladores a menudo generan un hash del texto (por ejemplo, `"Hello World"` -> `x7f2a`). Tus archivos de traducción se ven como `{ "x7f2a": "Hola Mundo" }`. La trampa: si cambias de librería, la nueva librería ve `"Hello World"` y busca esa clave. No la encontrará porque tu archivo de traducción está lleno de hashes (`x7f2a`). ### Bloqueo de Plataforma Al elegir un enfoque basado en compilador, te encierras en la plataforma subyacente. Por ejemplo, ciertos compiladores no están disponibles para todos los bundlers (como Vite, Turbopack o Metro). Esto puede dificultar las migraciones futuras y es posible que necesites adoptar múltiples soluciones para cubrir todas tus aplicaciones. ## El Otro Lado: Riesgos del Enfoque Declarativo Para ser justos, la forma tradicional declarativa tampoco es perfecta. Tiene su propio conjunto de "peligros ocultos". 1. **Infierno de Namespaces:** A menudo tienes que gestionar manualmente qué archivos JSON cargar (`common.json`, `dashboard.json`, `footer.json`). Si olvidas uno, el usuario verá las claves sin traducir. 2. **Sobrecarga 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, lo que hincha el tamaño de tu paquete. 3. **Desincronizació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 enfoque mixto, que te permite beneficiarte de las ventajas de ambos enfoques: gestión declarativa de contenido, también compatible con su compilador para ahorrar tiempo de desarrollo. E incluso si no usas el compilador de Intlayer, Intlayer ofrece un comando `transform` (también accesible mediante la extensión de VSCode). En lugar de hacer magia en un 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 ofrece 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 dentro de tu repositorio, puedes fácilmente presionar tab, o usar el copilot de tu IDE, para generar tus declaraciones de contenido, no estás ocultando lógica en un plugin de webpack. ## Conclusión Entonces, ¿cuál deberías elegir? **Si estás construyendo un MVP, o quieres avanzar rápidamente:** El enfoque basado en compilador 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 eres un desarrollador junior, o no te importa la optimización:** Si quieres la menor gestión manual, probablemente el enfoque basado en compilador sea el mejor. No necesitarás manejar claves o archivos de traducción tú mismo; solo escribe texto y el compilador automatiza el resto. Esto reduce el esfuerzo de configuración y los errores comunes de i18n ligados a pasos manuales. **Si estás internacionalizando un proyecto existente que ya incluye miles de componentes para refactorizar:** Un enfoque basado en compilador puede ser una opción pragmática aquí. La fase inicial de extracción puede ahorrar semanas o meses de trabajo manual. Sin embargo, considera usar una herramienta como el comando `transform` de Intlayer, que puede extraer cadenas y convertirlas en declaraciones explícitas de contenido declarativo. Esto te brinda la velocidad de la automatización mientras mantienes la seguridad y portabilidad de un enfoque declarativo. Obtienes lo mejor de ambos mundos: una migración inicial rápida sin deuda arquitectónica a largo plazo. **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 los 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 compilación específica. Para aplicaciones profesionales, la **Gestión Declarativa de Contenido** (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.