Herramientas de desarrollo

@lingo.dev/compiler proporciona herramientas de desarrollo para acelerar tu flujo de trabajo y reducir los costos de API durante el desarrollo.

Pseudotraductor

El pseudotraductor genera traducciones falsas instantáneas sin llamadas a la API.

Habilitar

{
  dev: {
    usePseudotranslator: true,
  }
}

Qué hace

Transforma el texto con marcadores visuales:

Original:

Welcome to our app

Pseudotraducido:

[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]

Beneficios:

  1. Retroalimentación instantánea — Sin llamadas a la API, sin esperas
  2. Visualizar texto traducible — Ver exactamente qué se traduce
  3. Probar longitudes variables — Las pseudotraducciones son ~30% más largas, revelando problemas de diseño
  4. Costo cero — No se consumen créditos de API

Cómo funciona

El pseudotraductor:

  • Añade marcadores ([!!! y !!!])
  • Reemplaza caracteres con versiones acentuadas (a → ä, e → ë)
  • Extiende la longitud del texto en ~30%
  • Preserva las interpolaciones ({name} permanece como {name})
  • Mantiene la estructura HTML

Ejemplo con interpolaciones:

<p>Hello {name}, you have {count} items</p>
// Becomes: [!!! Ḧëļļö {name}, ÿöü ḧävë {count} ïẗëṁṡ !!!]

Cuándo usar

Durante el desarrollo:

  • Configuración inicial e integración
  • Pruebas de diseño con longitudes de texto variables
  • Depuración de problemas de traducción
  • Iteración rápida en la interfaz de usuario

Cuándo NO usar:

  • Revisar la calidad real de la traducción
  • Probar el formato específico de la configuración regional
  • Control de calidad final antes del despliegue

Deshabilitar para traducciones reales

{
  dev: {
    usePseudotranslator: false,
  }
}

Reinicia el servidor de desarrollo para generar traducciones reales usando tu proveedor de LLM configurado.

Servidor de traducción

El servidor de traducción gestiona la generación de traducciones bajo demanda durante el desarrollo.

Cómo funciona

Cuando ejecutas npm run dev:

  1. El compilador inicia un servidor HTTP local
  2. El servidor encuentra automáticamente un puerto disponible (60000-60099)
  3. Tu aplicación solicita traducciones del servidor
  4. El servidor genera traducciones (pseudo o reales)
  5. Las traducciones se almacenan en caché en .lingo/metadata.json

Configuración

{
  dev: {
    translationServerStartPort: 60000, // Starting port
    translationServerUrl: "http://localhost:60000", // Custom URL (advanced)
  }
}

Rango de puertos: El servidor prueba los puertos 60000-60099 secuencialmente hasta encontrar uno disponible.

Inicio manual (avanzado)

Puedes iniciar el servidor de traducción manualmente:

npx @lingo.dev/compiler translate-server \
  --port 60000 \
  --config ./lingo.config.json

Esto es útil para:

  • Ejecutar el servidor de traducción por separado del proceso de compilación
  • Depurar problemas de traducción
  • Flujos de trabajo personalizados de CI/CD

Compatibilidad con WebSocket

El servidor de traducción es compatible con WebSockets para comunicación en tiempo real con el widget de desarrollo.

Cuando las traducciones se actualizan, el servidor envía los cambios a los clientes conectados mediante WebSocket.

Widget de desarrollo

El widget de desarrollo es una superposición en el navegador para editar traducciones en tiempo real.

Características

  • Edita traducciones en el navegador — No es necesario editar archivos
  • Ve el contexto — Visualiza el texto fuente, ubicación del componente
  • Actualizaciones en tiempo real — Los cambios se aplican inmediatamente mediante WebSocket
  • Cambio de locale — Prueba diferentes locales rápidamente

Habilitar

{
  dev: {
    enableWidget: true, // Coming soon
  }
}

Estado: El widget de desarrollo está en desarrollo activo y estará disponible en una versión futura.

Cómo funcionará

  1. Presiona el atajo de teclado (p. ej., Cmd+Shift+L)
  2. Aparece la superposición del widget
  3. Haz clic en cualquier texto traducido para editarlo
  4. Cambia las traducciones para locales específicos
  5. Guarda—los cambios se sincronizan mediante WebSocket
  6. Las traducciones se actualizan instantáneamente en .lingo/metadata.json

Flujo de trabajo de desarrollo

Configuración recomendada

1. Configuración inicial:

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

Ejecuta npm run dev para ver pseudotraducciones al instante.

2. Pruebas de diseño:

Las pseudotraducciones revelan problemas de diseño:

  • Desbordamiento de texto
  • Etiquetas truncadas
  • Elementos desalineados
  • Puntos de interrupción responsivos incorrectos

Corrige los problemas de diseño antes de invertir en traducciones reales.

3. Revisión de traducción real:

{
  dev: {
    usePseudotranslator: false,
  }
}

Genera traducciones reales para revisar la calidad. Prueba:

  • Precisión de la traducción
  • Tono y formalidad
  • Manejo de términos técnicos
  • Preservación del nombre de marca

4. Ajuste fino:

Usa data-lingo-override para control de precisión:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

5. Compilación de producción:

{
  buildMode: "cache-only",
}

Usa traducciones pregeneradas para compilaciones rápidas y deterministas.

Depuración

Verificar servidor de traducción

El servidor de traducción registra en la consola:

[lingo] Translation server started on port 60001
[lingo] Pseudotranslator: enabled
[lingo] Watching for changes...

Verificar archivo de metadatos

Inspecciona .lingo/metadata.json para ver las traducciones en caché:

{
  "translations": {
    "abc123": {
      "source": "Welcome to our app",
      "locales": {
        "es": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]",
        "de": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]"
      }
    }
  }
}

Con el pseudotraductor deshabilitado, verás traducciones reales en su lugar.

Conflictos de puerto

Si los puertos 60000-60099 están todos en uso:

{
  dev: {
    translationServerStartPort: 61000, // Use different range
  }
}

O detén manualmente los procesos que usan esos puertos:

# Find process using port 60000
lsof -i :60000

# Kill process
kill -9 <PID>

Consejos de rendimiento

El pseudotraductor es rápido: úsalo por defecto en desarrollo.

Las traducciones reales son más lentas: úsalas solo cuando necesites revisar la calidad:

  • Generación inicial de traducción: se aplica latencia de API
  • Compilaciones posteriores: las traducciones están en caché, rápidas

El servidor de traducción es ligero: uso mínimo de memoria y CPU.

Preguntas frecuentes

¿Necesito iniciar el servidor de traducción manualmente? No. Se inicia automáticamente cuando ejecutas npm run dev.

¿Puedo usar el pseudotraductor en producción? No. El pseudotraductor es solo para desarrollo. Las compilaciones de producción siempre usan traducciones reales de .lingo/metadata.json.

¿Por qué el widget de desarrollo aún no está disponible? Está en desarrollo activo. Sigue las versiones de GitHub para actualizaciones.

¿Puedo personalizar las pseudotraducciones? Actualmente no. El pseudotraductor usa un algoritmo fijo optimizado para visualizar texto traducible.

¿Las pseudotraducciones funcionan con todos los conjuntos de caracteres? Sí. El pseudotraductor maneja Unicode correctamente, incluidos emoji, caracteres CJK e idiomas RTL.

Próximos pasos