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:
- Install and configure Lingo.dev Compiler in your React app
- Set up automated translation extraction and injection
- 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:
- Scan your React components for translatable text
- Extract translation keys
- Generate translations using AI
- 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
- Framework-specific guides: Next.js, React Router, Vite
- How it Works: Understanding build-time processing
- Advanced Configuration: Customization options