Modos de compilación

@lingo.dev/compiler admite dos modos de compilación que controlan cuándo y cómo se generan las traducciones.

Descripción de los modos

ModoCuándo usarLlamadas APIComportamiento
translateDesarrollo, CISíGenera traducciones faltantes usando el LLM configurado
cache-onlyCompilaciones de producciónNoUsa solo traducciones en caché de .lingo/metadata.json

Modo translate

Propósito: Generar traducciones bajo demanda durante las compilaciones.

{
  buildMode: "translate"
}

Comportamiento:

  • Escanea el código en busca de texto traducible
  • Verifica .lingo/metadata.json para traducciones existentes
  • Genera traducciones faltantes mediante el proveedor LLM configurado
  • Actualiza .lingo/metadata.json con nuevas traducciones
  • Falla la compilación si la generación de traducciones falla

Cuándo usar:

  • Desarrollo local (con usePseudotranslator: true)
  • Pipelines CI/CD (con proveedores LLM reales)
  • Configuración inicial y generación de traducciones

Requiere:

  • Clave API válida para el proveedor configurado (o pseudotranslator habilitado)
  • Conexión de red al proveedor LLM

Modo cache-only

Propósito: Compilar usando solo traducciones pregeneradas.

{
  buildMode: "cache-only"
}

Comportamiento:

  • Lee traducciones de .lingo/metadata.json
  • No se realizan llamadas API
  • Falla la compilación si faltan traducciones para algún locale
  • Compilaciones rápidas y deterministas

Cuándo usar:

  • Compilaciones de producción
  • Despliegues sin claves API
  • Entornos con acceso de red restringido

Requiere:

  • .lingo/metadata.json con traducciones para todos los locales
  • Traducciones pregeneradas en CI o desarrollo

Flujo de trabajo recomendado

1. Desarrollo local

Usa pseudotranslator para retroalimentación instantánea:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

Beneficios:

  • Traducciones falsas instantáneas
  • Sin costos de API
  • Ver exactamente qué se traduce
  • Probar la UI con longitudes de texto variables

2. Pipeline CI/CD

Genera traducciones reales en CI:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

Configuración en CI:

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

Beneficios:

  • Traducciones reales generadas una vez por despliegue
  • Confirmadas en el control de versiones
  • Las compilaciones de producción no necesitan claves API

3. Compilación de producción

Usar solo traducciones en caché:

{
  buildMode: "cache-only",
}

Beneficios:

  • No se necesitan claves API
  • Compilaciones rápidas
  • Determinista: la misma entrada siempre produce la misma salida
  • Sin dependencias de red externas

Anulación de variable de entorno

Anular el modo de compilación mediante variable de entorno:

# Force cache-only mode
LINGO_BUILD_MODE=cache-only npm run build

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

Esto es útil para entornos de despliegue donde deseas forzar el modo cache-only sin modificar la configuración.

Manejo de traducciones faltantes

En modo translate

Si la traducción falla:

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

Solución: Corregir la clave API, volver a ejecutar la compilación.

En modo cache-only

Si faltan traducciones:

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

Solución: Ejecutar una compilación con el modo translate para generar las traducciones faltantes, luego confirmar .lingo/.

Traducción incremental

El compilador utiliza hashing de contenido para determinar qué necesita traducción:

  1. Cada cadena traducible obtiene un hash estable
  2. El hash se basa en el texto fuente + contexto
  3. Si el hash existe en .lingo/metadata.json, se reutiliza la traducción
  4. Solo el texto nuevo o modificado activa una nueva traducción

Resultado: Solo pagas por las traducciones una vez. Las compilaciones posteriores reutilizan las traducciones en caché.

Ejemplos de configuración de CI

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

Preguntas frecuentes

¿Necesito claves de API en producción? No. Usa buildMode: "cache-only" en producción. Las traducciones se generan previamente en CI.

¿Qué pasa si olvido generar las traducciones en CI? La compilación de producción fallará con un error claro que lista las traducciones faltantes. Genera las traducciones en CI, haz commit y vuelve a desplegar.

¿Puedo usar el modo translate en producción? Sí, pero no se recomienda. Hace que las compilaciones no sean deterministas y requiere claves de API en producción. Es mejor generar las traducciones en CI.

¿Cómo pruebo el modo cache-only localmente?

  1. Genera las traducciones con el modo translate
  2. Cambia al modo cache-only
  3. Ejecuta la compilación: debería tener éxito usando las traducciones en caché

¿Qué pasa si mi texto fuente cambia? El hash cambia, por lo que se genera una nueva traducción (en modo translate). La traducción antigua se mantiene en .lingo/metadata.json para el historial.

¿Debo hacer commit de .lingo/ en git? Sí. El directorio .lingo/ debe estar bajo control de versiones. Contiene tu caché de traducciones.

Próximos pasos