Troubleshooting

Common issues and solutions when using @lingo.dev/compiler.

Installation Issues

"Cannot find module '@lingo.dev/compiler'"

Cause: Package not installed or installed incorrectly.

Solution:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

Verify installation:

ls node_modules/@lingo.dev/compiler

"Module not found: Can't resolve '@lingo.dev/compiler/react'"

Cause: Importing from wrong path or outdated package.

Solution:

  1. Check import statement: 
    import { LingoProvider } from "@lingo.dev/compiler/react"; // Correct
  2. Reinstall package: 
    rm -rf node_modules
npm install

Configuration Issues

"Config must be async function" (Next.js)

Cause: Next.js config isn't wrapped in async function.

Solution:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale is required"

Cause: Missing sourceLocale in configuration.

Solution:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales must be an array"

Cause: targetLocales is not an array or is empty.

Solution:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

Translation Issues

Translations Not Showing

Symptoms: Text appears in source language only.

Causes & Solutions:

1. LingoProvider not added or in wrong location

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. Missing translations in metadata Check .lingo/metadata.json:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

If empty or missing, run with buildMode: "translate":

npm run dev # or build

3. Build mode is cache-only without cached translations

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

Translations Are All "[!!! ...]"

Cause: Pseudotranslator is enabled.

Solution:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

Restart dev server.

Some Text Not Being Translated

Causes:

1. Dynamic content or props

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

Solution: The compiler is being enhanced to support string literals. For now, put text directly in JSX.

2. Text in attributes requires specific handling

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective is enabled If useDirective: true, files without 'use i18n' aren't translated.

Solution: Add directive:

'use i18n';

export function Component() { ... }

Build Issues

"Missing translations for locale X"

Cause: buildMode: "cache-only" but translations are missing.

Solution:

  1. Generate translations: 
    npm run dev # or
LINGO_BUILD_MODE=translate npm run build
  2. Commit .lingo/metadata.json
  3. Retry with cache-only

"Failed to generate translation"

Causes:

1. Invalid API key

# Check .env file
cat .env | grep API_KEY

Ensure API key is correct for your provider.

2. Network issues Test API connection:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. Rate limiting Slow down translation generation or upgrade API tier.

4. Invalid model configuration

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

Build is Slow

Causes:

1. Generating many translations First build with new text is slow. Subsequent builds are fast (cached).

2. Pseudotranslator disabled in development

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. Pluralization enabled unnecessarily

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

HMR Issues

HMR Not Working

Cause: LingoProvider placement or framework config.

Solutions:

Next.js: Ensure LingoProvider is in root layout, not nested layouts.

Vite: Ensure lingoCompilerPlugin is placed before react() plugin:

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

State Resets on Translation Change

Cause: Page reload triggered by locale change.

Expected behavior: setLocale() reloads page by default to apply new locale.

To avoid reload: Implement custom persistLocale without reload:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

Note: This requires pre-loading translations for all locales.

API/Auth Issues

"API key invalid"

Solutions:

1. Check environment variable name

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. Verify API key is active Login to provider dashboard and check key status.

3. Restart dev server after adding key

npm run dev

Environment variables are loaded on startup.

"Authentication failed" (Lingo.dev)

Solutions:

1. Re-authenticate

npx lingo.dev@latest login

2. Manual API key

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

Get key from lingo.dev project settings.

Browser Blocking Auth Flow

Cause: Brave browser or extensions blocking authentication.

Solution: Manually add API key to .env:

LINGODOTDEV_API_KEY=...

Server Issues

"Translation server failed to start"

Cause: Ports 60000-60099 all in use.

Solutions:

1. Configure different port range

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. Kill existing processes

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

"Port 60000 already in use"

Cause: Another process using that port.

Solution: The server auto-finds next available port. Check console for actual port:

[lingo] Translation server started on port 60001

If all ports busy, see "Translation server failed to start" above.

Type Errors

"Property 'data-lingo-override' does not exist"

Cause: TypeScript doesn't recognize the attribute.

Solution: Add type declaration:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

Or use quotes:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

"Type error: Config must return Promise"

Cause: Next.js config not properly typed.

Solution:

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

Production Issues

Translations Missing in Production

Causes:

1. .lingo/ not committed

git add .lingo/
git commit -m "chore: add translations"
git push

2. Production build mode is wrong

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI didn't generate translations Check CI logs—ensure translations were generated and committed.

Different Translations in Dev vs Prod

Cause: Pseudotranslator enabled in production.

Solution:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

Getting Help

If you're still stuck:

  1. Check logs — Look for error messages in console
  2. Check .lingo/metadata.json — Verify structure and contents
  3. Test with pseudotranslator — Isolate API issues
  4. Check GitHub issues — github.com/lingodotdev/lingo.dev/issues
  5. Ask on Discord — discord.gg/lingo

When asking for help, include:

  • Error message (full stack trace)
  • Configuration (next.config.ts or vite.config.ts)
  • Package versions (npm list @lingo.dev/compiler)
  • Steps to reproduce

Common Questions

Q: Do I need API keys in production? A: No, with buildMode: "cache-only". Translations are pre-generated in CI.

Q: Why is my build failing? A: Check error message. Common causes: missing translations, invalid API key, network issues.

Q: Can I use multiple LLM providers? A: Yes, with locale-pair mapping in models config.

Q: How do I test without API costs? A: Enable usePseudotranslator: true in development.

Next Steps