Quick Start

Lingo.dev Compiler is designed to make any React app multilingual at build time without requiring changes to existing React components.

This quick start guide will help you add multilingual support to your React app in under 5 minutes.

Upon completion of this guide, you will:

  1. Install and configure Lingo.dev Compiler in your React app
  2. Set up automated translation extraction and injection
  3. Have a working multilingual app with optimized translations

Let's begin!

Prerequisites

Lingo.dev Compiler works with modern React frameworks. Before starting, ensure you have one of the supported setups:

  • Next.js (App Router)
  • React Router / Remix
  • Vite + React

Or explore our demo apps: Next.js, React Router, and Vite.

Step 1. Install the Package

Install the lingo.dev package in your project:

npm install lingo.dev

Step 2. Configure Your Framework

Choose your framework and follow the specific setup:

Next.js

Update your next.config.js:

import lingoCompiler from "lingo.dev/compiler";

export default lingoCompiler.next({
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  models: "lingo.dev", // Option 1: Lingo.dev Engine
  // models: {
  //   "*:*": "groq:mistral-saba-24b", // Option 2: GROQ
  // },
})(nextConfig);

React Router / Remix

Update your vite.config.ts:

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev", // Option 1: Lingo.dev Engine
    // models: {
    //   "*:*": "groq:mistral-saba-24b", // Option 2: GROQ
    // },
  })(viteConfig),
);

Vite

Update your vite.config.ts:

import lingoCompiler from "lingo.dev/compiler";

export default defineConfig(() =>
  lingoCompiler.vite({
    sourceRoot: "src",
    targetLocales: ["es", "fr", "de"],
    models: "lingo.dev", // Option 1: Lingo.dev Engine
    // models: {
    //   "*:*": "groq:mistral-saba-24b", // Option 2: GROQ
    // },
  })(viteConfig),
);

Step 3. Set Up Authentication

Lingo.dev Compiler sends your content to AI translation engines for localization, so we need to authenticate first.

Option 1. Lingo.dev Engine

Lingo.dev Compiler can use Lingo.dev Engine as your AI translation engine.

It provides dynamic model selection, auto-routing to different models for each language pair, automated model fallbacks, translation memory that considers past translations, and glossary support for your project's domain-specific terminology. There are both free and paid options, and the free Hobby tier should be sufficient for most projects.

To authenticate, run:

npx lingo.dev@latest login

Important detail. If you're using Brave browser, or your browser extensions are blocking the authentication flow, you can manually authenticate by adding a LINGODOTDEV_API_KEY environment variable to your .env file:

LINGODOTDEV_API_KEY=...

You will find the token in the Lingo.dev Engine Project Settings.

Option 2. GROQ

Alternatively, you can use GROQ models as AI translation engines. Create a free account at groq.com and get your API key.

Add your API key to your environment:

# .env
GROQ_API_KEY=gsk_...

Step 4. Add the Provider

Wrap your app with the LingoProvider to enable translations:

Next.js

In your layout.tsx:

import { LingoProvider, loadDictionary } from "lingo.dev/react/rsc";

export default function Layout({ children }) {
  return (
    <LingoProvider loadDictionary={(locale) => loadDictionary(locale)}>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

React Router / Remix

In your root.tsx:

import { LingoProvider } from "lingo.dev/react/client";
import { loadDictionary } from "lingo.dev/react/react-router";

export async function loader(args) {
  return { lingoDictionary: await loadDictionary(args.request) };
}

export default function Root() {
  const { lingoDictionary } = useLoaderData();
  return (
    <LingoProvider dictionary={lingoDictionary}>
      <html>
        <body>
          <Outlet />
        </body>
      </html>
    </LingoProvider>
  );
}

Vite

In your main.tsx:

import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

ReactDOM.createRoot(document.getElementById("root")).render(
  <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
    <App />
  </LingoProviderWrapper>,
);

Step 5. Build and Test

Run your development server:

npm run dev

The compiler will automatically:

  1. Scan your React components for translatable text
  2. Extract translation keys
  3. Generate translations using AI
  4. Create optimized translation files in the lingo/ directory

Your app is now multilingual! The compiler creates versioned dictionaries that track content changes and only retranslates modified content.

Optional: Add Language Switcher

Add a language switcher to let users change languages:

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

export function Header() {
  return (
    <header>
      <LocaleSwitcher locales={["en", "es", "fr", "de"]} />
    </header>
  );
}

Next Steps