Configuration Reference

Alpha

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

The Lingo.dev Compiler configuration object controls how your React application is translated at build time. This page documents every available option with types, defaults, and usage examples.

Core options#

Option	Type	Default	Description
`sourceRoot`	`string`	`"src"`	Directory containing translatable components. Relative to project root.
`lingoDir`	`string`	`".lingo"`	Directory for translation metadata and cache files.
`sourceLocale`	`string`	required	Language code of your source content (e.g., `"en"`).
`targetLocales`	`string[]`	required	Array of target language codes (e.g., `["es", "de", "fr"]`).
`useDirective`	`boolean`	`false`	When `true`, only files with `'use i18n'` directive are translated. When `false`, all files in `sourceRoot` are translated.
`models`	`string \| object`	`"lingo.dev"`	Translation provider configuration. A string sets the default for all locale pairs. An object maps locale pairs to specific providers.
`prompt`	`string`	`undefined`	Custom system prompt for the translation LLM. Supports `{SOURCE_LOCALE}` and `{TARGET_LOCALE}` placeholders.
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Controls whether the compiler generates new translations or uses only cached translations.

Dev options#

Options under the dev key control development-time behavior:

Option	Type	Default	Description
`dev.usePseudotranslator`	`boolean`	`false`	Generate instant fake translations (e.g., `[!!! Welcome !!!]`) instead of calling an LLM. No API key needed.
`dev.translationServerStartPort`	`number`	`60000`	Starting port for the local translation server. The compiler auto-finds an available port in the range 60000-60099.
`dev.translationServerUrl`	`string`	`undefined`	Override the translation server URL. Useful for custom setups or remote translation servers.

Locale persistence#

Options under localePersistence control how the user's selected locale is stored and retrieved:

Option	Type	Default	Description
`localePersistence.type`	`string`	`"cookie"`	Persistence mechanism. Currently supports `"cookie"`.
`localePersistence.config.name`	`string`	`"locale"`	Cookie name used to store the locale.
`localePersistence.config.maxAge`	`number`	`31536000`	Cookie max-age in seconds (default is 1 year).

For custom persistence logic (localStorage, URL-based, headers), see Custom Locale Resolvers.

Pluralization#

Options under pluralization control automatic plural form detection and generation:

Option	Type	Default	Description
`pluralization.enabled`	`boolean`	`true`	Enable or disable automatic pluralization detection.
`pluralization.model`	`string`	`"groq:llama-3.1-8b-instant"`	LLM model used for detecting plural forms in source text. A smaller, faster model is recommended since detection is a simpler task than translation.

See Automatic Pluralization for details on how plural detection works.

Environment variables#

Environment variables override or supplement configuration:

Variable	When required	Description
`LINGO_BUILD_MODE`	Optional	Overrides the `buildMode` config option. Set to `"translate"` or `"cache-only"`.
`LINGODOTDEV_API_KEY`	When using `"lingo.dev"` models	API key for the Lingo.dev localization engine. Obtain via `npx lingo.dev@latest login`.
`OPENAI_API_KEY`	When using `"openai:*"` models	OpenAI API key.
`ANTHROPIC_API_KEY`	When using `"anthropic:*"` models	Anthropic API key.
`GOOGLE_API_KEY`	When using `"google:*"` models	Google AI API key.
`GROQ_API_KEY`	When using `"groq:*"` models	Groq API key.
`MISTRAL_API_KEY`	When using `"mistral:*"` models	Mistral API key.
`OPENROUTER_API_KEY`	When using `"openrouter:*"` models	OpenRouter API key.

Complete example#

// 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",
    },
  });
}

Next Steps#

Translation Providers

All supported LLM providers and locale-pair mapping

Build Modes

Dev, CI, and production workflows

Custom Locale Resolvers

Implement custom locale detection

Best Practices

Recommended patterns for production