Alfa
Lingo.dev Compiler está en fase alfa. Es inestable, no se recomienda para uso en producción y las API pueden cambiar entre versiones.
Lingo.dev Compiler funciona con dos modos de compilación que determinan si se generan nuevas traducciones durante la compilación. Entender cómo funcionan es clave para configurar un pipeline fiable de desarrollo, CI y producción.
Los dos modos#
| Modo | Comportamiento | Cuándo usarlo |
|---|---|---|
"translate" | Genera las traducciones que faltan llamando al proveedor de LLM configurado. Reutiliza las traducciones almacenadas en caché. | Desarrollo y CI: cuando hay que traducir texto nuevo o modificado. |
"cache-only" | Utiliza solo 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 el modo translate#
En el modo translate, el compilador comprueba cada cadena traducible en .lingo/metadata.json. Si existe una traducción en caché y el texto de origen no ha cambiado, se utiliza esa versión. Si la cadena es nueva o se ha modificado, 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 obtener traducciones simuladas al instante) como con proveedores LLM reales.
Cómo funciona el modo cache-only#
En el modo cache-only, el compilador lee las traducciones exclusivamente de .lingo/metadata.json. No se realiza ninguna llamada al LLM. Si falta alguna cadena traducible en la caché, la compilación falla con un error que enumera las cadenas que faltan.
.lingo/metadata.json debe confirmarse 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 haya generado en local.
{
buildMode: "cache-only",
}Este modo genera compilaciones deterministas: el mismo código fuente y la misma caché siempre producen el mismo resultado. 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: modo translate
Ejecuta con buildMode: "translate" y un proveedor LLM real. El job de CI genera traducciones para cualquier cadena nueva o modificada y confirma el .lingo/metadata.json actualizado de vuelta en el repositorio.
# CI environment
LINGO_BUILD_MODE=translate npm run buildProducción: modo cache-only
Despliega con buildMode: "cache-only" para usar solo traducciones generadas previamente. No hacen falta claves de API en el entorno de producción.
# Production environment
LINGO_BUILD_MODE=cache-only npm run buildAnulación mediante 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"Confirma siempre .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á.
