Configuración avanzada

Lingo.dev Compiler proporciona amplias opciones de configuración para personalizar el comportamiento de traducción y optimizar su flujo de trabajo de localización.

Ajustes de configuración

Al implementar el compilador en tu proyecto, puedes pasar un objeto de configuración con las siguientes opciones:

// Configuración predeterminada
const compilerConfig = {
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  debug: false,
  models: {
    // Configuración de modelos personalizados
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are AI translator. You translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.",
};

// Next.js
lingoCompiler.next(compilerConfig)(nextConfig);

// Vite/React Router
lingoCompiler.vite(compilerConfig)(viteConfig);

Opciones de configuración

  • sourceRoot - Ruta a su directorio fuente donde se almacenará el directorio lingo/
  • lingoDir - Nombre del directorio que contiene los archivos de traducción (predeterminado: "lingo")
  • sourceLocale - El idioma fuente de su aplicación (predeterminado: "en")
  • targetLocales - Array de idiomas de destino para traducir
  • rsc - Habilitar soporte para React Server Components (predeterminado: false)
  • debug - Habilitar registro de depuración para solución de problemas (predeterminado: false)
  • models - Configuración personalizada de modelos de IA para pares de idiomas específicos (opcional)
  • prompt - Prompt de traducción personalizado con marcadores de posición (opcional)

Modelos Groq recomendados

Para obtener mejores resultados, hemos probado y validado la calidad de los siguientes modelos GROQ para locales específicos:

mistral-saba-24b

  • ar - Árabe
  • de - Alemán
  • fr - Francés
  • pt-BR - Portugués (Brasil)

meta-llama/llama-4-maverick-17b-128e-instruct

  • es - Español
  • ja - Japonés
  • ko - Coreano
  • ru - Ruso
  • zh - Chino

Control de procesamiento de archivos

Omitir traducciones

Añade el atributo data-lingo-skip a los elementos que no quieras traducir:

<div data-lingo-skip>Este contenido no será traducido</div>

Anulaciones de traducción

Anula traducciones para locales específicos utilizando atributos data-lingo-override-:

<button data-lingo-override-es="¡Hola!" data-lingo-override-fr="Bonjour!">
  Hello
</button>

Configuración personalizada de modelos

Puedes personalizar los modelos de IA y los prompts directamente en tu configuración del compilador:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: {
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "es:fr": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are a professional translator specializing in technical documentation. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE} while maintaining technical accuracy.",
};

Configuración de modelos

  • Define pares de locales como source-locale:target-locale
  • Usa * como comodín para cualquier locale
  • Usa *:* como respaldo para todas las traducciones
  • Consulta modelos GROQ para ver las opciones disponibles

Prompts personalizados

Puedes definir prompts de traducción personalizados con marcadores de posición:

  • {SOURCE_LOCALE} - Código del idioma de origen
  • {TARGET_LOCALE} - Código del idioma de destino

Para construir glosarios personalizados, incluye terminología en tu prompt. Consulta el prompt predeterminado del compilador para conocer las mejores prácticas.

Normalización de la compilación

Ejecuta siempre una compilación de producción localmente antes de confirmar cambios:

npm run build

Esto asegura que los archivos meta.json y dictionary.js en el directorio lingo/ contengan solo cadenas presentes en tu aplicación y estén formateados correctamente.

Configuración del hook pre-commit

Configura la normalización automática usando husky:


# Instalar husky

npm install --save-dev husky

# Añadir hook pre-commit

npx husky add .husky/pre-commit "npm run build"

Configuración específica del entorno

Desarrollo

const isDev = process.env.NODE_ENV === "development";

const compilerConfig = {
  debug: isDev,
  targetLocales: isDev ? ["es"] : ["es", "fr", "de", "ja"],
};

Integración CI/CD

Para compilaciones automatizadas, asegúrate de que tu entorno CI tenga acceso a la clave API de GROQ:


# GitHub Actions

GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}

# Vercel

GROQ_API_KEY=gsk_...

# Netlify

GROQ_API_KEY=gsk_...

Optimización del rendimiento

Compilaciones incrementales

El compilador automáticamente:

  • Rastrea cambios de contenido mediante huellas digitales de archivos
  • Solo traduce contenido nuevo o modificado
  • Reutiliza traducciones existentes para contenido sin cambios

Optimización del bundle

  • Paquetes por localización - Carga únicamente las traducciones para la localización activa
  • Tree shaking - Elimina las traducciones no utilizadas de las compilaciones de producción
  • Code splitting - Carga traducciones bajo demanda para aplicaciones basadas en rutas

Solución de problemas

Modo de depuración

Habilita el registro de depuración para solucionar problemas:

const compilerConfig = {
  debug: true,
  // ... otras opciones
};

Problemas comunes

Traducciones faltantes: Asegúrate de haber ejecutado npm run build localmente y haber confirmado el directorio lingo/. Si estás utilizando NextJS, es posible que necesites eliminar el directorio .next/ para asegurar que todos los archivos se reconstruyan.

Errores de compilación: Verifica que tu GROQ_API_KEY esté correctamente configurada en tus variables de entorno.

Problemas de rendimiento: Habilita el modo de depuración para identificar cuellos de botella en el proceso de compilación.

Próximos pasos