Alfa
El Compiler de Lingo.dev está en alfa. Es inestable, no se recomienda para producción y las API pueden cambiar entre versiones.
El Compiler de Lingo.dev funciona con dos modos de compilación que determinan si se generan nuevas traducciones durante el build. Entender cómo funciona cada uno es clave para configurar un flujo confiable de desarrollo, CI y producción.
Los dos modos#
| Modo | Comportamiento | Cuándo usarlo |
|---|---|---|
"translate" | Genera las traducciones faltantes llamando al proveedor de LLM configurado. Reutiliza las traducciones en caché. | Desarrollo y CI: cuando hay texto nuevo o modificado que necesita traducirse. |
"cache-only" | Usa únicamente las traducciones de .lingo/metadata.json. Falla si falta alguna traducción. | Compilaciones de producción: salida determinista sin llamadas a API externas. |
Cómo funciona translate mode#
En el modo translate, el compilador revisa cada cadena traducible en .lingo/metadata.json. Si ya existe una traducción en caché y el texto de origen no cambió, usa esa versión. Si la cadena es nueva o fue modificada, el compilador llama al proveedor de traducción configurado para generarla y actualiza la caché.
{
buildMode: "translate",
}Este es el modo predeterminado. Funciona tanto con el pseudotraductor (para generar traducciones simuladas al instante) como con proveedores LLM reales.
Cómo funciona cache-only mode#
En el modo cache-only, el compilador lee las traducciones exclusivamente de .lingo/metadata.json. No se hace ninguna llamada al LLM. Si falta alguna cadena traducible en la caché, la compilación falla con un error que enumera las cadenas faltantes.
.lingo/metadata.json debe versionarse en el control de versiones. Las compilaciones de producción en modo cache-only dependen de que este archivo esté presente en el repositorio, no solo de que se genere localmente.
{
buildMode: "cache-only",
}Este modo produce compilaciones deterministas: el mismo código fuente y la misma caché siempre generan la misma salida. Además, elimina las dependencias de API externas durante las compilaciones de producción.
flujo de trabajo recomendado#
Desarrollo: pseudotraductor
Activa el pseudotraductor para obtener feedback inmediato sin llamadas a API:
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}Las pseudotraducciones aparecen como [!!! Welcome !!!], lo que facilita detectar cadenas sin traducir y probar el diseño con distintas longitudes de texto.
CI: translate mode
Ejecuta con buildMode: "translate" y un proveedor LLM real. El job de CI genera traducciones para cualquier cadena nueva o modificada y hace commit de .lingo/metadata.json actualizado al repositorio.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProducción: cache-only mode
Haz el despliegue con buildMode: "cache-only" para usar únicamente traducciones pregeneradas. No se necesitan claves de API en el entorno de producción.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildAnulación con variable de entorno#
La variable de entorno LINGO_BUILD_MODE prevalece sobre la opción de configuración buildMode. Esto te permite usar el mismo archivo de configuración en distintos entornos:
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run buildLa variable de entorno tiene prioridad sobre el valor del archivo de configuración.
Ejemplos de CI#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"Haz siempre commit de .lingo/metadata.json en el control de versiones. Las compilaciones de producción en modo cache-only dependen de este archivo. Si falta o está incompleto, la compilación fallará.
