Configuration Reference

Complete reference for all @lingo.dev/compiler configuration options.

Core Options

Example

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

Development Options

Configure development-specific behavior via the dev object:

Example

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

Why pseudotranslator? It's instant (no API calls), shows exactly what gets translated, and tests your UI with varying text lengths—all without API costs.

Locale Persistence

Configure how locale changes are persisted:

Example

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

Custom persistence? Implement Custom Locale Resolvers to use localStorage, URL parameters, or database persistence.

Pluralization

Configure automatic pluralization detection:

Example

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

How it works: The compiler detects plural forms in your text (e.g., "You have 5 items") and converts them to ICU MessageFormat ({count, plural, one {1 item} other {# items}}).

Disable for performance: If you don't use plural forms, disable this to skip LLM calls for pluralization.

Translation Providers

The models option configures which LLM provider(s) to use for translations.

Simple Configuration

Use a single provider for all translations:

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

Advanced Configuration

Use locale-pair mapping for granular control:

{
  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
  }
}

Patterns:

• "source:target": Specific locale pair (e.g., "en:es")
• "*:target": Any source to specific target (e.g., "*:de")
• "source:*": Specific source to any target (e.g., "en:*")
• "*:*": Fallback for all pairs

See Translation Providers for provider syntax and API key setup.

Custom Translation Prompts

Customize the translation prompt using placeholders:

{
  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.`
}

Available placeholders:

• {SOURCE_LOCALE}: Source locale code (e.g., "en")
• {TARGET_LOCALE}: Target locale code (e.g., "es")

The compiler appends context about the text being translated (component location, surrounding elements) to your custom prompt.

Environment Variable Override

Override configuration via environment variables:

# 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=...

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

TypeScript Types

Import configuration types for type safety:

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

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

Common Questions

Do I need to configure all options? No. Only sourceLocale and targetLocales are required. All others have sensible defaults.

What's the difference between sourceRoot and lingoDir? sourceRoot is where your source code lives (e.g., ./app, src). lingoDir is where translation metadata is stored (default: .lingo).

Can I use different models per locale? Yes. Use locale-pair mapping in the models option. See Translation Providers.

Should I commit .lingo/ to git? Yes. The .lingo/ directory contains translation metadata and cache. It should be version-controlled alongside your code.

How do I disable pluralization? Set pluralization.enabled: false. This skips plural form detection and reduces LLM calls.

Next Steps

• Translation Providers — Configure LLM providers
• Build Modes — Understand translate vs cache-only
• Custom Locale Resolvers — Implement custom locale detection
• Best Practices — Recommended configurations