Alfa
El Compiler de Lingo.dev está en alfa. Es inestable, no se recomienda para uso en 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 soporte completo para Hot Module Replacement, así 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#
Agrega lingoCompilerPlugin a tu configuración de Vite. El plugin debe ir antes del plugin react(); este orden es obligatorio porque el compilador necesita transformar JSX antes de que el plugin de React lo procese.
// 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á JSX primero y el compilador no podrá identificar el texto traducible. Coloca siempre el plugin de Lingo primero en el arreglo plugins.
Agrega LingoProvider#
Envuelve la raíz de tu aplicación con LingoProvider en tu 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 fuente
Cambia cualquier texto en tu JSX; por ejemplo, actualiza un encabezado de "Welcome" 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 seudotraducción en modo de desarrollo).
El navegador se actualiza al instante
El componente traducido se vuelve a renderizar sin recargar toda la página. Los metadatos de traducción en .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. Para 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 |
Para bases de código grandes, un sourceRoot más acotado reduce los tiempos de compilación. Si solo necesitas traducciones en archivos específicos, habilita useDirective: true y agrega '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