Mejores prácticas - Lingo.dev Compiler

Patrones y flujos de trabajo recomendados para @lingo.dev/compiler.

Flujo de trabajo de desarrollo

Usar Pseudotranslator por defecto

Hacer:

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

Por qué:

Retroalimentación instantánea: sin latencia de API
Costo cero: no se consumen créditos de API
Los marcadores visuales muestran qué se traduce
Prueba la interfaz con longitudes de texto variables

Desactívalo solo cuando revises la calidad real de la traducción.

Separar desarrollo, CI y producción

Desarrollo:

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

CI:

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

Producción:

{
  buildMode: "cache-only",
}

Este flujo de trabajo:

Mantiene el desarrollo rápido y económico
Genera traducciones reales en CI una vez por despliegue
Hace que las compilaciones de producción sean deterministas y rápidas

Estrategia de traducción

Dejar que la IA gestione la mayoría de las traducciones

Hacer:

<p>Welcome to our application</p>

No hacer:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

Usa los overrides con moderación, solo para:

Nombres de marca
Términos técnicos que requieren traducciones específicas
Texto legal que requiere certificación
Textos de marketing que necesitan revisión humana

Usar overrides de forma consistente

Hacer:

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

No hacer:

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

Configuración

Empezar de forma sencilla

Hacer:

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

No hacer:

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

Empieza con 2-3 configuraciones regionales de destino. Añade más según sea necesario. Evita la optimización prematura.

Usar Lingo.dev Engine

Hacer:

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

No hacer:

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

Lingo.dev Engine proporciona:

Selección automática de modelo
Gestión de respaldo
Memoria de traducción
Soporte de glosario

Usa proveedores de LLM directos solo si necesitas control total u optimización de costes.

Detección de configuración regional

Usar persistencia predeterminada basada en cookies

Hacer:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",
      maxAge: 31536000,
    },
  },
}

Cuándo personalizar:

Necesitas localStorage (preferencia de SPA)
Enrutamiento basado en URL (/en/about)
Enrutamiento por subdominio (es.example.com)
Preferencias de usuario respaldadas por base de datos

Solo implementa resolvedores de configuración regional personalizados cuando el predeterminado no se ajuste.

Control de versiones

Confirmar directorio .lingo/

Hacer:

git add .lingo/
git commit -m "chore: update translations"
git push

Por qué:

El control de versiones rastrea los cambios en las traducciones
El equipo comparte las traducciones
CI/CD utiliza las traducciones confirmadas
Las compilaciones de producción no necesitan claves de API

Confirmar después de ejecutar CI

Hacer (en CI):

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

Esto garantiza que las compilaciones de producción siempre tengan traducciones actualizadas.

CI/CD

Generar traducciones en CI

Hacer:

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

No hacer:

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

Genera las traducciones en CI donde tienes las claves de API. Las compilaciones de producción utilizan traducciones en caché.

Usar cache-only en producción

Hacer:

# Production build
LINGO_BUILD_MODE=cache-only npm run build

No hacer:

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

Rendimiento

Habilitar la pluralización de forma selectiva

Hacer (si usas formas plurales):

{
  pluralization: {
    enabled: true,
  }
}

Hacer (si no usas plurales):

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

La pluralización añade una pequeña sobrecarga (una llamada LLM por texto con números). Desactívala si no es necesaria.

Usar modelos rápidos para pluralización

Hacer:

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast, cheap
  }
}

No hacer:

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

Optimizar el mapeo de pares de idiomas

Hacer (optimización de costes):

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

Usa modelos rápidos/económicos para idiomas similares (romances, germánicos). Usa modelos de alta calidad para idiomas complejos (CJK, árabe).

Pruebas

Probar primero con pseudotraductor

Hacer:

Activar el pseudotraductor
Probar todos los componentes de la interfaz
Corregir problemas de diseño (desbordamiento, truncamiento)
Luego generar traducciones reales

Por qué:

Las pseudotraducciones son instantáneas
Revelan problemas de diseño temprano
Ahorra costes de API

Probar todos los idiomas de destino

Hacer:

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

Verificar cada idioma:

Las traducciones aparecen correctamente
El diseño se adapta a la longitud del texto
No hay texto sin traducir
Los idiomas RTL se renderizan correctamente (si aplica)

Manejo de errores

Manejar traducciones faltantes con elegancia

El compilador falla la compilación si faltan traducciones. Esto es intencional: es mejor detectar traducciones faltantes temprano que enviar una interfaz rota.

Si la compilación falla:

Ejecutar con buildMode: "translate" para generar las traducciones faltantes
Hacer commit de .lingo/metadata.json
Reintentar la compilación de producción con buildMode: "cache-only"

Monitorear fallos de traducción

En CI, verificar errores de traducción:

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

Mantenimiento

Limpieza regular

Elimina periódicamente las traducciones no utilizadas:

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

Monitorear el tamaño del archivo

.lingo/metadata.json crece con tu aplicación. Si se vuelve grande (>5 MB):

Considera dividirlo en múltiples aplicaciones
Archiva traducciones antiguas
Usa limpieza automatizada

Antipatrones comunes

No abuses de las anulaciones

Mal:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

Deja que la IA maneje el texto regular. Las anulaciones son para excepciones.

No confirmes claves de API

Mal:

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

Bien:

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

No uses el modo translate en producción

Mal:

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

Bien:

{
  buildMode: "cache-only", // Deterministic, no API keys
}

No omitas el control de versiones

Mal:

# .gitignore
.lingo/ # DON'T ignore translations

**Bien:

# .gitignore
.env # Ignore API keys only

Estrategia de migración

Despliegue gradual

Al añadir el compilador a una aplicación existente:

Comienza con 1-2 idiomas
Activa el pseudotraductor
Prueba todas las páginas
Corrige problemas de diseño
Añade más idiomas
Genera traducciones reales
Despliega

No intentes traducir 20 idiomas el primer día.

Adopción incremental

No necesitas traducir toda la aplicación de una vez:

{
  useDirective: true, // Opt-in per file
}

Añade la directiva 'use i18n' a los archivos que quieras traducir:

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

Los demás archivos permanecen sin traducir hasta que los incluyas.

Próximos pasos

Guía de migración — Migra desde el compilador antiguo
Solución de problemas — Problemas comunes y soluciones
Referencia de configuración — Todas las opciones explicadas