Alfa
El Compiler de Lingo.dev está en fase alfa. Es inestable, no se recomienda para entornos de producción y las API pueden cambiar entre versiones.
El Compiler de Lingo.dev se integra con Vite a través de lingoCompilerPlugin, un plugin de Vite que transforma tus componentes de React en tiempo de compilación para inyectar traducciones. Ofrece compatibilidad total con Hot Module Replacement, por lo que las traducciones se actualizan al instante durante el desarrollo.
Requisitos previos#
Requisitos
- Vite 5+ con React
- Node.js 18+
@lingo.dev/compilerinstalado
Instalación#
pnpm install @lingo.dev/compilerConfigura vite.config.ts#
Añade lingoCompilerPlugin a tu configuración de Vite. El plugin debe colocarse antes del plugin react(); este orden es obligatorio porque el compilador necesita transformar el JSX antes de que lo procese el plugin de React.
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";
export default defineConfig({
plugins: [
lingoCompilerPlugin({
sourceRoot: "src",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
models: "lingo.dev",
dev: {
usePseudotranslator: true,
},
}),
react(),
],
});El orden de los plugins importa
Si lingoCompilerPlugin se coloca después de react(), el plugin de React procesará primero el JSX y el compilador no podrá identificar el texto traducible. Coloca siempre el plugin de Lingo en primer lugar dentro del array plugins.
Añade LingoProvider#
Envuelve la raíz de tu aplicación con LingoProvider en el archivo de entrada:
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<LingoProvider>
<App />
</LingoProvider>
</StrictMode>
);LingoProvider inicializa el contexto de idioma y carga el diccionario de traducción adecuado para el idioma activo.
Hot Module Replacement#
El plugin se integra con el sistema HMR de Vite. Cuando editas texto traducible en un componente:
Edita el texto de origen
Cambia cualquier texto de tu JSX; por ejemplo, actualiza un encabezado de "Bienvenida" a "Welcome back".
El Compiler detecta el cambio
El plugin intercepta la actualización de HMR, identifica la cadena modificada y genera una nueva traducción (o una pseudotraducción en modo desarrollo).
El navegador se actualiza al instante
El componente traducido se vuelve a renderizar sin necesidad de recargar toda la página. Los metadatos de traducción de .lingo/metadata.json se actualizan en disco.
Configuración de sourceRoot#
La opción sourceRoot determina qué archivos analiza el compilador en busca de texto traducible. En un proyecto estándar de Vite + React:
{
sourceRoot: "src",
}| Estructura del proyecto | sourceRoot recomendado |
|---|---|
Estándar (src/) | "src" |
| Monorepo con paquetes compartidos | "." (raíz del proyecto) |
| Directorio personalizado | Ruta al directorio de tus componentes |
En bases de código grandes, acotar sourceRoot reduce los tiempos de compilación. Si solo necesitas traducciones en archivos concretos, activa useDirective: true y añade 'use i18n' a esos archivos. Consulta Estructura del proyecto.
Ejemplo de estructura del proyecto#
my-vite-app/
src/
main.tsx # LingoProvider wraps <App />
App.tsx # Translatable components
components/
Header.tsx # Automatically scanned
Footer.tsx # Automatically scanned
.lingo/
metadata.json # Translation cache (commit this)
vite.config.ts # lingoCompilerPlugin configured here