Alfa
El Compiler de Lingo.dev está en fase alfa. Es inestable, no se recomienda para producción y las API pueden cambiar entre versiones.
El Compiler de Lingo.dev crea y mantiene un directorio .lingo/ en la raíz de tu proyecto para almacenar metadatos de traducción y caché. Entender esta estructura te ayuda a gestionar traducciones en el control de versiones, depurar traducciones faltantes y optimizar el rendimiento de compilación.
El directorio .lingo/#
El Compiler crea este directorio automáticamente en la primera compilación. Contiene todos los metadatos de traducción que usa el pipeline de compilación:
.lingo/
metadata.json # Translation cache and content hashes
locale-resolver.server.ts # Optional: custom server-side locale resolver
locale-resolver.client.ts # Optional: custom client-side locale resolvermetadata.json#
Este es el archivo principal del directorio .lingo/. Almacena:
- Hashes de contenido: identificadores estables basados en hash para cada cadena traducible
- Traducciones en caché: traducciones generadas para cada par de idiomas
- Instantáneas del texto fuente: el texto fuente al momento de la traducción, usado para detectar cambios
El Compiler lee este archivo al inicio de cada compilación. Las cadenas con hashes coincidentes reutilizan las traducciones en caché. Las cadenas con hashes modificados o faltantes se envían al proveedor de traducción configurado.
Haz commit al control de versiones
Haz siempre commit de .lingo/metadata.json en tu repositorio. Las compilaciones de producción en modo cache-only leen las traducciones exclusivamente de este archivo. Si no se incluye en el commit, las compilaciones de producción fallarán.
Consideraciones sobre .gitignore#
No agregues .lingo/ a .gitignore. Este directorio debe mantenerse bajo control de versiones. Un .gitignore típico en un proyecto que usa el Compiler:
# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.envsourceRoot#
La opción sourceRoot define qué directorio escanea el Compiler para encontrar componentes React traducibles:
{
sourceRoot: "./app", // Next.js App Router
// or
sourceRoot: "src", // Vite + React
}El Compiler escanea de forma recursiva todos los archivos .tsx, .ts, .jsx y .js dentro de sourceRoot en busca de contenido JSX traducible. Los archivos fuera de este directorio no se procesan.
| Valor de sourceRoot | Qué se escanea |
|---|---|
"./app" | Todos los archivos del directorio app/ (convención de Next.js) |
"src" | Todos los archivos del directorio src/ (convención de Vite) |
"." | Todos los archivos en la raíz del proyecto (útil para monorepos con paquetes compartidos) |
Un sourceRoot más amplio escanea más archivos, lo que aumenta el tiempo de compilación. Mantenlo lo más acotado posible. Si solo algunos archivos necesitan traducción, usa la opción useDirective en su lugar.
Modo opt-in con 'use i18n'#
De forma predeterminada, el Compiler traduce todo el texto JSX en sourceRoot. Para cambiar al modo opt-in, configura useDirective: true:
{
useDirective: true,
}En el modo opt-in, solo se procesan los archivos que comienzan con la directiva 'use i18n':
'use i18n';
export function Welcome() {
return <h1>Welcome to our app</h1>;
// This text IS translated
}Los archivos sin esa directiva se omiten:
export function InternalAdmin() {
return <h1>Admin Dashboard</h1>;
// This text is NOT translated
}Cuándo usar el modo opt-in#
| Escenario | Modo recomendado |
|---|---|
| Aplicación pequeña donde todo el contenido debe traducirse | Predeterminado (useDirective: false) |
| Base de código grande con solo algunas páginas visibles para el usuario | Opt-in (useDirective: true) |
| Monorepo con componentes internos y externos compartidos | Opt-in (useDirective: true) |
| Adopción gradual: agregar i18n a una aplicación existente | Opt-in (useDirective: true) |
lingoDir#
La opción lingoDir cambia la ubicación del directorio de metadatos:
{
lingoDir: ".lingo", // Default
// or
lingoDir: ".translations", // Custom location
}Esto resulta útil si .lingo/ entra en conflicto con un directorio existente en tu proyecto.
