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 donde guarda los metadatos de traducción y la caché. Entender esta estructura te ayuda a gestionar las traducciones en el control de versiones, depurar traducciones que faltan y optimizar el rendimiento de las compilaciones.
El directorio .lingo/#
El Compiler crea este directorio automáticamente en la primera compilación. Contiene todos los metadatos de traducción que utiliza 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 en el momento de la traducción, que se usa 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 cuyos hashes han cambiado o faltan se envían al proveedor de traducción configurado.
Haz commit en el 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 repositorio, las compilaciones de producción fallarán.
Consideraciones sobre .gitignore#
No añadas .lingo/ a .gitignore. Este directorio debe versionarse. 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 determina qué directorio escanea el Compiler en busca de 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 que quedan fuera de ese 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 de la raíz del proyecto (útil en monorepos con paquetes compartidos) |
Cuanto más amplio sea sourceRoot, más archivos se escanean y más tiempo tarda la compilación. Mantenlo lo más acotado posible. Si solo algunos archivos necesitan traducción, usa la opción useDirective en su lugar.
Modo opcional con 'use i18n'#
De forma predeterminada, el Compiler traduce todo el texto JSX de sourceRoot. Para cambiar al modo opcional, configura useDirective: true:
{
useDirective: true,
}En el modo opcional, solo se procesan los archivos que empiezan con la directiva 'use i18n':
'use i18n';
export function Welcome() {
return <h1>Welcome to our app</h1>;
// This text IS translated
}Los archivos sin la directiva se omiten:
export function InternalAdmin() {
return <h1>Admin Dashboard</h1>;
// This text is NOT translated
}Cuándo usar el modo opcional#
| Escenario | Modo recomendado |
|---|---|
| Aplicación pequeña en la que debe traducirse todo el contenido | Predeterminado (useDirective: false) |
| Base de código grande con solo algunas páginas orientadas al usuario | Opcional (useDirective: true) |
| Monorepo con componentes internos y externos compartidos | Opcional (useDirective: true) |
| Adopción gradual: añadir i18n a una aplicación existente | Opcional (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 que ya existe en tu proyecto.
