Referencia de configuración

Alfa

Lingo.dev Compiler está en fase alfa. Es inestable, no se recomienda para entornos de producción y las API pueden cambiar entre versiones.

El objeto de configuración de Lingo.dev Compiler controla cómo se traduce tu aplicación React durante la compilación. Esta página documenta todas las opciones disponibles, con tipos, valores por defecto y ejemplos de uso.

Opciones principales#

Opción	Tipo	Por defecto	Descripción
`sourceRoot`	`string`	`"src"`	Directorio que contiene los componentes traducibles. Relativo a la raíz del proyecto.
`lingoDir`	`string`	`".lingo"`	Directorio para los metadatos de traducción y los archivos de caché.
`sourceLocale`	`string`	obligatorio	Código de idioma del contenido de origen (p. ej., `"en"`).
`targetLocales`	`string[]`	obligatorio	Array de códigos de idioma de destino (p. ej., `["es", "de", "fr"]`).
`useDirective`	`boolean`	`false`	Cuando es `true`, solo se traducen los archivos con la directiva `'use i18n'`. Cuando es `false`, se traducen todos los archivos de `sourceRoot`.
`models`	`string \| object`	`"lingo.dev"`	Configuración del proveedor de traducción. Una cadena establece el valor por defecto para todos los pares de idiomas. Un objeto asigna proveedores concretos a pares de idiomas específicos.
`prompt`	`string`	`undefined`	Prompt de sistema personalizado para el LLM de traducción. Admite los marcadores `{SOURCE_LOCALE}` y `{TARGET_LOCALE}`.
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Controla si el Compiler genera nuevas traducciones o si usa solo las traducciones almacenadas en caché.

Opciones de desarrollo#

Las opciones dentro de la clave dev controlan el comportamiento durante el desarrollo:

Opción	Tipo	Por defecto	Descripción
`dev.usePseudotranslator`	`boolean`	`false`	Genera traducciones ficticias al instante (p. ej., `[!!! Welcome !!!]`) en lugar de llamar a un LLM. No necesita clave de API.
`dev.translationServerStartPort`	`number`	`60000`	Puerto inicial del servidor local de traducción. El Compiler encuentra automáticamente un puerto disponible dentro del rango 60000-60099.
`dev.translationServerUrl`	`string`	`undefined`	Sobrescribe la URL del servidor de traducción. Es útil para configuraciones personalizadas o servidores de traducción remotos.

Persistencia del idioma#

Las opciones dentro de localePersistence controlan cómo se guarda y se recupera el idioma seleccionado por el usuario:

Opción	Tipo	Por defecto	Descripción
`localePersistence.type`	`string`	`"cookie"`	Mecanismo de persistencia. Actualmente admite `"cookie"`.
`localePersistence.config.name`	`string`	`"locale"`	Nombre de la cookie que se usa para almacenar el idioma.
`localePersistence.config.maxAge`	`number`	`31536000`	Tiempo máximo de vida de la cookie en segundos (por defecto, 1 año).

Para la lógica de persistencia personalizada (localStorage, basada en URL o encabezados), consulta Custom Locale Resolvers.

Pluralización#

Las opciones dentro de pluralization controlan la detección y la generación automáticas de formas plurales:

Opción	Tipo	Por defecto	Descripción
`pluralization.enabled`	`boolean`	`true`	Activa o desactiva la detección automática de pluralización.
`pluralization.model`	`string`	`"groq:llama-3.1-8b-instant"`	Modelo LLM que se usa para detectar formas plurales en el texto de origen. Se recomienda un modelo más pequeño y rápido, ya que la detección es una tarea más sencilla que la traducción.

Consulta Automatic Pluralization para ver en detalle cómo funciona la detección de plurales.

Variables de entorno#

Las variables de entorno sobrescriben o complementan la configuración:

Variable	Cuándo es obligatoria	Descripción
`LINGO_BUILD_MODE`	Opcional	Sobrescribe la opción de configuración `buildMode`. Establécela en `"translate"` o `"cache-only"`.
`LINGODOTDEV_API_KEY`	Al usar modelos `"lingo.dev"`	Clave de API del motor de localización de Lingo.dev. Consíguela a través de `npx lingo.dev@latest login`.
`OPENAI_API_KEY`	Al usar modelos `"openai:*"`	Clave de API de OpenAI.
`ANTHROPIC_API_KEY`	Al usar modelos `"anthropic:*"`	Clave de API de Anthropic.
`GOOGLE_API_KEY`	Al usar modelos `"google:*"`	Clave de API de Google AI.
`GROQ_API_KEY`	Al usar modelos `"groq:*"`	Clave de API de Groq.
`MISTRAL_API_KEY`	Al usar modelos `"mistral:*"`	Clave de API de Mistral.
`OPENROUTER_API_KEY`	Al usar modelos `"openrouter:*"`	Clave de API de OpenRouter.

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, {
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,
    models: {
      "*:*": "lingo.dev",
      "*:ja": "anthropic:claude-3-5-sonnet",
    },
    prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
    buildMode: "translate",
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

Siguientes pasos#

Translation Providers

Todos los proveedores de LLM compatibles y la asignación por pares de idiomas

Build Modes

Flujos de trabajo de desarrollo, CI y producción

Custom Locale Resolvers

Implementa una detección de idioma personalizada

Best Practices

Patrones recomendados para producción