FAQ

Common questions and answers about Lingo.dev Compiler.

Can I translate string literals?

Lingo.dev Compiler follows the convention that everything in JSX is localizable. String literals outside of JSX components are not localized by design.

Current behavior:

// This will NOT be translated
const message = "Hello world";
const errorText = "Something went wrong";

// This WILL be translated
function Component() {
  return <h1>Hello world</h1>;
}

Making literals localizable:

You can make string literals localizable by wrapping them in JSX fragments:

// Before: Not localizable
const message = "Hello world";

// After: Localizable using fragments
const message = <>Hello world</>;

// Usage in your component
function Component() {
  return <div>{message}</div>;
}

Alternative approach:

// For dynamic messages
function getLocalizedMessage() {
  return <>Something went wrong</>;
}

// For conditional text
const statusText = isError ? <>Error occurred</> : <>Success</>;

This convention ensures consistent localization behavior while maintaining clear boundaries between localizable and non-localizable content.

We're exploring ways to extend this behavior to support more use cases in the future. Join our Discord to discuss specific patterns you'd like to see supported.

Which frameworks are supported?

Lingo.dev Compiler currently supports these React frameworks:

  • Next.js (App Router only)
  • React Router v6+
  • Remix (latest version)
  • Vite + React

We welcome contributors interested in implementing compiler support for other platforms. Join our Discord to discuss implementation strategies.

Can I add more languages?

Yes! You can extend language support by configuring custom models directly in your compiler configuration:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de", "pt", "it"],
  models: {
    "*:pt": "mistral-saba-24b",
    "en:it": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
};

lingoCompiler.next(compilerConfig)(nextConfig);

See advanced configuration for details.

Can I use custom prompts?

Yes! You can customize translation prompts directly in your compiler configuration:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "You are a professional translator specializing in technical documentation. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE} while maintaining technical accuracy.",
};

For custom glossaries, include terminology definitions in your prompt. Reference our default prompt for best practices.

Can I use more LLM providers?

Currently, Lingo.dev Compiler integrates with GROQ, but we'd love to support more LLM providers soon (talk to us or send us a pull request!).

Do I need GROQ API key in CI/CD?

Usually no. If you build your app locally all translations will be stored in lingo/ directory. Your CI/CD build will not need to call LLM to translate any strings.

Alternatively you can add GROQ_API_KEY variable to your CI/CD and do all the translations there at build, but we do not recomment this approach to keep more control over final translations.

Can I edit translations?

Yes! You can edit the lingo/dictionary.js file manually. It exports an object with translations for all files and entries. You can edit the text for each locale in content prop. Your edits will be preserved until the source text in React components is updated.

Not a fan of editing JavaScript objects? We are releasing editor to improve the editing experience soon. Let us know if you are interested!

How can I retranslate my whole app, specific file or language?

To retranslate your whole app delete the dictionary.js file from lingo/ directory.

To retranslate specific files only, you can delete their key (filename) from dictionary.js.

If you want to retranslate specific locale, you need to delete all records for that locale.

Why do I need to build the app locally?

Local builds normalize your lingo/ translation files by:

  • Removing unused translation keys
  • Updating content fingerprints
  • Ensuring consistent file formatting
  • Optimizing for production deployment

Always run npm run build before committing changes to maintain clean translation files.

There are missing translations!

If translations are missing:

  1. Build locally to normalize your lingo/ files:

    npm run build

  2. Check your API key is properly set:

    # Verify your .env file contains
GROQ_API_KEY=gsk_...

  3. Commit the updated files:

    git add lingo/
git commit -m "Update translations"

  4. Restart your development server after changes.

Can I setup a custom glossary?

Yes! Use custom prompts to define terminology and glossaries directly in your compiler configuration:

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "You are a professional translator. Use these terms consistently: 'Dashboard' should be 'Tableau de bord' in French, 'Settings' should be 'Configuración' in Spanish. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.",
};

How do I skip certain content from translation?

Use the data-lingo-skip attribute:

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

For conditional skipping based on content type:

<code data-lingo-skip>
  // Code blocks are automatically skipped const apiKey = "secret-key";
</code>

Can I override specific translations?

Yes! Use data-lingo-override- attributes for locale-specific overrides:

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

This is useful for:

  • Brand names that shouldn't be translated
  • Region-specific terminology
  • Marketing copy that needs manual review

How does the compiler handle pluralization?

The compiler automatically handles basic pluralization patterns, but for complex plural rules, you may need to structure your JSX accordingly:

// The compiler will handle this appropriately
<p>{count === 1 ? "1 item" : `${count} items`}</p>

What about performance in production?

Lingo.dev Compiler is optimized for production:

  • Zero runtime cost - translations are pre-compiled
  • Bundle splitting - only active locale is loaded
  • Tree shaking - unused translations are removed
  • CDN-friendly - static translation files cache efficiently

Can I use this with TypeScript?

Yes! The compiler works seamlessly with TypeScript projects. All provided React components are fully typed:

import { LocaleSwitcher } from "lingo.dev/react/client";

// Full TypeScript support
const locales: string[] = ["en", "es", "fr"];
<LocaleSwitcher locales={locales} />;

How do I report bugs or request features?

Next Steps