Referencia de configuración

Referencia completa de todas las opciones de configuración de @lingo.dev/compiler.

Opciones principales

Ejemplo

{
  sourceRoot: "./app",
  lingoDir: ".lingo",
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "ja"],
  useDirective: false,
  models: "lingo.dev",
  buildMode: "translate",
}

Opciones de desarrollo

Configura el comportamiento específico de desarrollo mediante el objeto dev:

Ejemplo

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
    translationServerStartPort: 60000, // Default port range
  }
}

¿Por qué pseudotranslator? Es instantáneo (sin llamadas a API), muestra exactamente qué se traduce y prueba tu interfaz con longitudes de texto variables, todo sin costes de API.

Persistencia de idioma

Configura cómo se persisten los cambios de idioma:

Ejemplo

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "user-locale",
      maxAge: 31536000, // 1 year
    },
  },
}

¿Persistencia personalizada? Implementa resolvedores de configuración regional personalizados para usar localStorage, parámetros de URL o persistencia en base de datos.

Pluralización

Configura la detección automática de pluralización:

Ejemplo

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

Cómo funciona: El compilador detecta formas plurales en tu texto (por ejemplo, "Tienes 5 elementos") y las convierte a ICU MessageFormat ({count, plural, one {1 item} other {# items}}).

Deshabilita para mejorar el rendimiento: Si no usas formas plurales, deshabilita esto para omitir las llamadas LLM para pluralización.

Proveedores de traducción

La opción models configura qué proveedor(es) LLM usar para las traducciones.

Configuración simple

Usa un único proveedor para todas las traducciones:

{
  models: "lingo.dev" // Recommended: Lingo.dev Engine
}

Configuración avanzada

Usa mapeo de pares de configuraciones regionales para control granular:

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // English to Spanish
    "en:de": "google:gemini-2.0-flash",      // English to German
    "*:fr": "openai:gpt-4o",                 // Any locale to French
    "*:*": "anthropic:claude-3-5-sonnet",    // Fallback for all others
  }
}

Patrones:

• "source:target": Par de configuraciones regionales específico (por ejemplo, "en:es")
• "*:target": Cualquier origen a destino específico (por ejemplo, "*:de")
• "source:*": Origen específico a cualquier destino (por ejemplo, "en:*")
• "*:*": Respaldo para todos los pares

Consulta proveedores de traducción para la sintaxis de proveedores y configuración de claves API.

Prompts de traducción personalizados

Personaliza el prompt de traducción usando marcadores de posición:

{
  prompt: `Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.
Use a formal tone and preserve all technical terms.
Do not translate brand names or product names.`
}

Marcadores de posición disponibles:

• {SOURCE_LOCALE}: Código de configuración regional de origen (por ejemplo, "en")
• {TARGET_LOCALE}: Código de configuración regional de destino (por ejemplo, "es")

El compilador añade contexto sobre el texto que se está traduciendo (ubicación del componente, elementos circundantes) a tu prompt personalizado.

Anulación mediante variable de entorno

Anula la configuración mediante variables de entorno:

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

# Set API key
LINGODOTDEV_API_KEY=your_key_here
GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=...

Ejemplo completo

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    // Core
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,

    // Build mode
    buildMode: process.env.NODE_ENV === "production" ? "cache-only" : "translate",

    // Models
    models: {
      "en:es": "groq:llama-3.3-70b-versatile",
      "*:*": "lingo.dev",
    },

    // Custom prompt
    prompt: "Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}. Use a professional tone.",

    // Development
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },

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

    // Pluralization
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

Tipos de TypeScript

Importa los tipos de configuración para seguridad de tipos:

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  // ...config
};

Preguntas frecuentes

¿Necesito configurar todas las opciones? No. Solo sourceLocale y targetLocales son obligatorios. Todos los demás tienen valores predeterminados razonables.

¿Cuál es la diferencia entre sourceRoot y lingoDir? sourceRoot es donde se encuentra tu código fuente (por ejemplo, ./app, src). lingoDir es donde se almacenan los metadatos de traducción (predeterminado: .lingo).

¿Puedo usar diferentes modelos por locale? Sí. Usa el mapeo de pares de locales en la opción models. Consulta Proveedores de traducción.

¿Debo hacer commit de .lingo/ en git? Sí. El directorio .lingo/ contiene metadatos de traducción y caché. Debe estar bajo control de versiones junto con tu código.

¿Cómo desactivo la pluralización? Establece pluralization.enabled: false. Esto omite la detección de formas plurales y reduce las llamadas al LLM.

Próximos pasos

• Proveedores de traducción — Configura proveedores de LLM
• Modos de compilación — Comprende translate vs cache-only
• Resolvers de locale personalizados — Implementa detección de locale personalizada
• Mejores prácticas — Configuraciones recomendadas