Referencia de configuración

Alfa

Lingo.dev Compiler está en alfa. Es inestable, no se recomienda para usarlo en 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 de React durante la compilación. En esta página se documentan todas las opciones disponibles, con tipos, valores predeterminados y ejemplos de uso.

Opciones principales#

Opción	Tipo	Predeterminado	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	Arreglo 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 dentro de `sourceRoot`.
`models`	`string \| object`	`"lingo.dev"`	Configuración del proveedor de traducción. Una cadena establece el valor predeterminado para todos los pares de idiomas. Un objeto asigna proveedores específicos a pares de idiomas concretos.
`prompt`	`string`	`undefined`	Prompt del sistema personalizado para el LLM de traducción. Admite los placeholders `{SOURCE_LOCALE}` y `{TARGET_LOCALE}`.
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Controla si el compilador genera traducciones nuevas o si usa únicamente las traducciones en caché.

Opciones de desarrollo#

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

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

Persistencia de idioma#

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

Opción	Tipo	Predeterminado	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 guardar el idioma.
`localePersistence.config.maxAge`	`number`	`31536000`	Tiempo máximo de vida de la cookie en segundos (el valor predeterminado es 1 año).

Para implementar una 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 generación automáticas de formas plurales:

Opción	Tipo	Predeterminado	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 de 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 detectar es una tarea más simple que traducir.

Consulta Automatic Pluralization para conocer cómo funciona la detección de plurales.

Variables de entorno#

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

Variable	Cuándo se requiere	Descripción
`LINGO_BUILD_MODE`	Opcional	Sobrescribe la opción de configuración `buildMode`. Configúrala como `"translate"` o `"cache-only"`.
`LINGODOTDEV_API_KEY`	Al usar modelos `"lingo.dev"`	Clave de API para el motor de localización de Lingo.dev. Obtenla en `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",
    },
  });
}

Próximos pasos#

Proveedores de traducción

Todos los proveedores de LLM compatibles y el mapeo por pares de idiomas

Modos de compilación

Flujos de trabajo de desarrollo, CI y producción

Custom Locale Resolvers

Implementa una detección de idioma personalizada

Mejores prácticas

Patrones recomendados para producción