Advanced Configuration

Lingo.dev Compiler provides extensive configuration options to customize translation behavior and optimize your localization workflow.

Configuration Settings

When implementing the compiler in your project, you can pass a settings object with the following options:

// Default configuration
const compilerConfig = {
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  debug: false,
  models: {
    // Custom model configuration
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are AI translator. You translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.",
};

// Next.js
lingoCompiler.next(compilerConfig)(nextConfig);

// Vite/React Router
lingoCompiler.vite(compilerConfig)(viteConfig);

Configuration Options

  • sourceRoot - Path to your source directory where the lingo/ directory will be stored
  • lingoDir - Name of the directory containing translation files (default: "lingo")
  • sourceLocale - The source language of your application (default: "en")
  • targetLocales - Array of target languages to translate into
  • rsc - Enable React Server Components support (default: false)
  • debug - Enable debug logging for troubleshooting (default: false)
  • models - Custom AI model configuration for specific language pairs (optional)
  • prompt - Custom translation prompt with placeholders (optional)

Suggested Groq Models

For best results we tested and validated quality of the following GROQ models for specific locales:

mistral-saba-24b

  • ar - Arabic
  • de - German
  • fr - French
  • pt-BR - Portuguese (Brazil)

meta-llama/llama-4-maverick-17b-128e-instruct

  • es - Spanish
  • ja - Japanese
  • ko - Korean
  • ru - Russian
  • zh - Chinese

File Processing Control

Skip Translations

Add the data-lingo-skip attribute to elements you don't want translated:

<div data-lingo-skip>This content will not be translated</div>

Translation Overrides

Override translations for specific locales using data-lingo-override- attributes:

<button data-lingo-override-es="¡Hola!" data-lingo-override-fr="Bonjour!">
  Hello
</button>

Custom Model Configuration

You can customize AI models and prompts directly in your compiler configuration:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: {
    "*:fr": "mistral-saba-24b",
    "en:es": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "es:fr": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
  prompt:
    "You are a professional translator specializing in technical documentation. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE} while maintaining technical accuracy.",
};

Model Configuration

  • Define locale pairs as source-locale:target-locale
  • Use * as wildcard for any locale
  • Use *:* as fallback for all translations
  • See GROQ models for available options

Custom Prompts

You can define custom translation prompts with placeholders:

  • {SOURCE_LOCALE} - Source language code
  • {TARGET_LOCALE} - Target language code

For building custom glossaries, include terminology in your prompt. Reference the default compiler prompt for best practices.

Build Normalization

Always run a production build locally before committing changes:

npm run build

This ensures meta.json and dictionary.js files in the lingo/ directory contain only strings present in your app and are properly formatted.

Pre-commit Hook Setup

Set up automatic normalization using husky:

# Install husky
npm install --save-dev husky

# Add pre-commit hook
npx husky add .husky/pre-commit "npm run build"

Environment-Specific Configuration

Development

const isDev = process.env.NODE_ENV === "development";

const compilerConfig = {
  debug: isDev,
  targetLocales: isDev ? ["es"] : ["es", "fr", "de", "ja"],
};

CI/CD Integration

For automated builds, ensure your CI environment has access to the GROQ API key:

# GitHub Actions
GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}

# Vercel
GROQ_API_KEY=gsk_...

# Netlify
GROQ_API_KEY=gsk_...

Performance Optimization

Incremental Builds

The compiler automatically:

  • Tracks content changes through file fingerprinting
  • Only translates new or modified content
  • Reuses existing translations for unchanged content

Bundle Optimization

  • Per-locale bundles - Only load translations for the active locale
  • Tree shaking - Remove unused translations from production builds
  • Code splitting - Load translations on demand for route-based apps

Troubleshooting

Debug Mode

Enable debug logging to troubleshoot issues:

const compilerConfig = {
  debug: true,
  // ... other options
};

Common Issues

Missing translations: Ensure you've run npm run build locally and committed the lingo/ directory. If you are using NextJS you might need to delete .next/ directory to ensure all files are rebuilt.

Build errors: Check that your GROQ_API_KEY is properly set in your environment variables.

Performance issues: Enable debug mode to identify bottlenecks in the compilation process.

Next Steps