Lingo.dev - Automated AI localization for web & mobile apps

Introduction

Lingo.dev Compiler is an AI-powered tool that enables you to localize React-based apps without making changes to existing components. You just configure a few things, wrap your app in a context provider, and that's it — your app is localized.

This guide explains how to set up Lingo.dev Compiler with v6 of React Router, a client-side routing library for React. If you're using v7, see Quickstart for React Router (v7).

What You'll Learn

How to initialize Lingo.dev Compiler in React Router
How to configure the compiler for compatibility with React Router
How to set up a locale switcher for switching between locales

Step 1. Set up an API Key

Lingo.dev Compiler uses large language models (LLMs) to localize apps with AI. To use one of these models, you need an API key from a supported provider.

To get up and running as quickly as possible, we recommend using Lingo.dev Engine — our own, hosted platform that offers 10,000 tokens of free, monthly usage.

To set up an API key:

Log in to Lingo.dev Engine.
Navigate to the Projects page.
Click API key > Copy.
Store the API key in an environment variable:
```
export LINGODOTDEV_API_KEY="<your_api_key>"
```

Alternative: Custom LLM Providers

You don't have to use Lingo.dev Engine. You can configure the compiler to integrate with a number of custom LLM providers, including:

Groq
Google
Mistral
Ollama
OpenRouter

Step 2. Install the Package

Lingo.dev Compiler is distributed as part of the lingo.dev npm package. To install it, use your preferred package manager:

npm install lingo.dev

Step 3. Initialize the Compiler

Lingo.dev Compiler integrates with Vite and runs at build time. To hook into Vite's build process, make the following changes to the vite.config.ts file:

Import the compiler:

import lingoCompiler from "lingo.dev/compiler";

Initialize the compiler with the vite method:

const withLingo = lingoCompiler.vite({
  sourceRoot: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

For compatibility with React Router, ensure that:

sourceRoot is set to "src"
rsc is set to false

To learn more about the available options, see Compiler Options.

Wrap your existing Vite configuration with the compiler:

const viteConfig: UserConfig = {
  plugins: [react()],
};

export default withLingo(viteConfig);

With this configuration in place, Lingo.dev Compiler will:

Traverse the codebase's Abstract Syntax Tree (AST)
Find localizable content (i.e., text in JSX elements and certain attribute values)
Use the configured AI model(s) to generate translations
Store the original and translated content in a dictionary.js file
Replace localized content with placeholders

Step 4. Load the Localized Content

After the compiler processes your app and generates translations, you need to load and serve this localized content to your users. This involves:

Loading the appropriate dictionary based on the user's locale preference
Providing the loaded translations to your app through a context provider

Loading the Dictionary

In your root route file:

Import the loadDictionary function from lingo.dev/react/react-router:
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
This function:
- Retrieves the current locale from the lingo-locale cookie
- Falls back to "en" when a locale isn't defined
- Loads the localized content from the dictionary.js file

Call the loadDictionary function from the loader function:

import { LoaderFunctionArgs } from "react-router-dom";

export async function loader({ request }: LoaderFunctionArgs) {
  const lingoDictionary = await loadDictionary(request);
  return {
    lingoDictionary,
  };
}

Providing the Translations

In your root component:

Import the LingoProvider component from lingo.dev/react/client:
```
import { LingoProvider } from "lingo.dev/react/client";
```
This component is a React context provider that replaces the compiler-created placeholders with the localized content.
In your root component, get the data from the data loader:
```
const data = useLoaderData<typeof loader>();
```

Wrap the app in the LingoProvider component:

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* Existing app code */}
</LingoProvider>

Step 5. Set up a Locale Switcher

To enable users to switch between locales, import the LocaleSwitcher from the lingo.dev package. This is an unstyled component that:

Renders a dropdown of available locales
Lets users select a locale
Remembers the selected locale for return visits

To use the component, embed it anywhere in your app and set the locales prop to an array that contains the configured source and target locales:

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

<LocaleSwitcher locales={["en", "es"]} />;

Alternative: Custom Locale Switcher

You don't have to use the LocaleSwitcher component. You can implement custom locale switching logic and UI. The only requirement is to read and write the active locale to the lingo-locale cookie.

Step 6. Run the App

To verify that Lingo.dev Compiler has been set up correctly:

Start the development server:
```
npm run dev
```
Navigate to localhost:5173.
Use the LocaleSwitcher component to switch between locales.

The page should reload and display the localized content.

Alternative: Set Cookies Manually

If you're not using the LocaleSwitcher component, an alternative way to verify that localization is working is by manually setting the lingo-locale cookie.

If you're using Google Chrome, follow these instructions:

Navigate to View > Developer > Developer Tools.
Go to the Application tab.
In the left sidebar, under Storage, expand Cookies and select the site's URL.
In the cookies table, right-click anywhere and select Add.
In the Name column, enter lingo-locale.
In the Value column, enter the desired locale (e.g., es).
Press Enter to save the cookie.
Refresh the page to apply the cookie.

Quickstart for React Router (v6)