Cómo funciona

@lingo.dev/compiler transforma tu aplicación React en una app multilingüe en tiempo de compilación mediante análisis inteligente de código y traducción impulsada por IA.

Transformación en tiempo de compilación

Las bibliotecas i18n tradicionales en tiempo de ejecución (i18next, react-intl) funcionan durante la ejecución: cargan traducciones, interpolan valores y formatean mensajes mientras tu app se ejecuta. Esto añade tamaño al bundle, sobrecarga en tiempo de ejecución y complejidad.

@lingo.dev/compiler funciona de manera diferente: transforma tu código durante el proceso de compilación. Tus componentes React permanecen limpios y las traducciones se precompilan en bundles optimizados.

Resultado: Cero sobrecarga en tiempo de ejecución, bundles más pequeños y sin gestión manual de claves de traducción.

El proceso

1. Análisis AST

El compilador utiliza Babel para analizar tu código React en un árbol de sintaxis abstracta (AST). Recorre tu JSX identificando contenido traducible:

  • Nodos de texto (<p>Hello</p>)
  • Atributos de cadena (<img alt="Logo" />)
  • Texto en expresiones de plantilla (<p>Hello {name}</p>)

El compilador comprende los límites de los componentes React y mantiene información contextual para traducciones precisas. Los identificadores técnicos, fragmentos de código y elementos no traducibles se filtran automáticamente.

2. Extracción de contenido

Para cada cadena traducible, el compilador:

  • Genera un identificador estable basado en hash
  • Preserva el contexto del componente (archivo, ubicación, elementos circundantes)
  • Extrae la estructura de texto enriquecido (maneja elementos anidados como <strong> y <em>)
  • Mantiene los marcadores de interpolación

Estos metadatos se almacenan en .lingo/metadata.json: un archivo versionado que rastrea todo el contenido traducible en tu app.

3. Generación de traducciones

Durante el desarrollo, el servidor de traducción gestiona la traducción bajo demanda:

  • Modo pseudotraductor (predeterminado): genera traducciones falsas instantáneas, útil para ver qué se traduce sin costes de API
  • Modo de traducción real: llama a tu proveedor de LLM configurado (Lingo.dev Engine o LLM directo)

El servicio de traducción no tiene estado y gestiona los fallos parciales de forma elegante: si algunas traducciones fallan, las traducciones en caché se siguen utilizando.

4. Inyección de código

El compilador inyecta búsquedas de traducción en tu JSX:

// Your source code
<p>Hello {name}</p>

// Transformed code (simplified)
<p>{t('abc123', { name })}</p>

La función t() está optimizada y se inyecta automáticamente. Realiza búsquedas basadas en hash en diccionarios de traducción precargados.

5. Optimización del bundle

En tiempo de compilación:

  • Se crean bundles por locale
  • Solo se incluyen las traducciones utilizadas
  • La eliminación de código muerto elimina las traducciones no utilizadas
  • Los diccionarios se optimizan mediante tree-shaking por componente

Flujo de trabajo de desarrollo

Modo de desarrollo

{
  dev: {
    usePseudotranslator: true,
  }
}

Cuando ejecutas npm run dev:

  1. El compilador inicia un servidor de traducción (encuentra automáticamente puertos 60000-60099)
  2. Tu aplicación realiza peticiones al servidor para obtener traducciones
  3. Pseudotranslator genera traducciones falsas instantáneas
  4. Las traducciones se almacenan en caché en .lingo/metadata.json
  5. HMR funciona normalmente: el estado se preserva

El widget de desarrollo (si está habilitado) te permite editar traducciones en el navegador y ver los cambios en tiempo real.

Modo de producción

{
  buildMode: "cache-only",
}

Cuando ejecutas npm run build:

  1. No se inicia ningún servidor de traducción
  2. Solo se utilizan las traducciones en caché de .lingo/metadata.json
  3. Si falta alguna traducción, la compilación falla con un error claro
  4. No se realizan llamadas a la API: no se necesitan claves de API

¿Por qué solo caché? En producción, quieres compilaciones deterministas. Las traducciones deben generarse en CI (donde tienes claves de API), no durante las compilaciones de producción.

Flujo de trabajo recomendado

Desarrollo local:

  • Usa pseudotranslator
  • Ciclo de retroalimentación rápido
  • Sin costes de API

CI/CD:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}
  • Genera traducciones reales
  • Ejecuta una vez por despliegue
  • Confirma los cambios de .lingo/

Compilación de producción:

{
  buildMode: "cache-only",
}
  • Usa traducciones pregeneradas
  • No se requieren claves de API
  • Compilaciones rápidas y deterministas

Arquitectura

El compilador está organizado en torno a una clara separación de responsabilidades:

Gestor de metadatos

  • Operaciones CRUD para .lingo/metadata.json
  • Seguro para hilos con bloqueo de archivos
  • Identificadores basados en hash para traducciones

Servicio de traducción

  • Orquesta el flujo de trabajo de traducción
  • Gestiona la estrategia de caché
  • Maneja fallos parciales
  • Devuelve tanto traducciones exitosas como errores

Traductores (sin estado)

  • Pseudotraductor: traducciones falsas instantáneas
  • Traductor LCP: integración con Lingo.dev Engine
  • Traductores LLM: integración directa con proveedores
  • Sin caché integrada: la capa de servicio se encarga de eso

Servidor de traducción

  • Servidor HTTP para desarrollo
  • Soporte WebSocket para actualizaciones de widgets en tiempo real
  • Gestión automática de puertos
  • Manejo de solicitudes por lotes

Consulta el documento de arquitectura del código fuente para detalles de implementación.

Integración con frameworks

Next.js

El compilador se integra mediante el wrapper withLingo():

  • Compatible con Webpack y Turbopack
  • Funciona con React Server Components
  • Configuración asíncrona para carga diferida de plugins
  • Enrutamiento automático basado en locale (si está configurado)

Vite

El compilador se integra mediante lingoCompilerPlugin:

  • Basado en Unplugin (funciona con Vite, Webpack, Rollup)
  • Soporte completo de HMR
  • Integración eficiente con servidor de desarrollo
  • Generación automática de módulos virtuales

Preguntas frecuentes

¿Funciona esto con Server Components? Sí. En Next.js, el compilador transforma tanto Server Components como Client Components. Las búsquedas de traducción funcionan de forma isomórfica.

¿Qué pasa con la división de código? Las traducciones se dividen automáticamente junto con tus componentes. Cada fragmento incluye solo las traducciones que necesita.

¿Cómo se almacenan en caché las traducciones? Todas las traducciones se almacenan en .lingo/metadata.json. Este archivo está bajo control de versiones y actúa como tu caché de traducciones. El compilador utiliza hashes de contenido: solo el texto nuevo o modificado activa una nueva traducción.

¿Qué pasa si falla una traducción? El servicio devuelve resultados parciales. Las traducciones exitosas se almacenan en caché y se utilizan, mientras que los errores se registran con contexto para depuración. Tu aplicación no se rompe: recurre a traducciones en caché o al texto fuente.

¿Puedo ver el código transformado? Sí. En la salida de compilación, busca los archivos transformados. Las transformaciones son mínimas: solo llamadas a funciones t() con búsquedas basadas en hash.

Próximos pasos