Setup

Max Prilutskiy·Updated 5 days ago·2 min read

Alpha

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

Add multilingual support to your React application in under 5 minutes.

Prerequisites

Node.js 18+ and a React application using Next.js (App Router) or Vite.

Install#

bash

pnpm install @lingo.dev/compiler

Configure your framework#

Make your config async and wrap it with withLingo:

// next.config.ts
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, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true,
    },
  });
}

Add LingoProvider#

tsx

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

Authenticate#

bash

npx lingo.dev@latest login

This opens your browser for authentication. The free Hobby tier works for most projects.

If browser auth is blocked, add the key to .env manually:

bash

LINGODOTDEV_API_KEY=your_key_here

Run the dev server#

bash

npm run dev

The compiler scans your JSX, generates pseudotranslations (instant fake translations to visualize what gets translated), and injects them into your components. Metadata is stored in .lingo/metadata.json - commit this to version control.

Add a language switcher (optional)#

tsx

"use client"; // For Next.js

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Espanol</option>
      <option value="de">Deutsch</option>
    </select>
  );
}

Generate real translations#

When ready, disable pseudotranslator:

{
  dev: {
    usePseudotranslator: false,
  }
}

Restart the dev server. The compiler generates real AI translations for new or changed text.

Next Steps#

How It Works

The build-time transformation pipeline

Next.js

Next.js-specific setup and features

Vite + React

Vite-specific setup and features

Configuration Reference

All configuration options

Was this page helpful?

Setup

Max Prilutskiy·Updated 5 days ago·2 min read

Alpha

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

Add multilingual support to your React application in under 5 minutes.

Prerequisites

Node.js 18+ and a React application using Next.js (App Router) or Vite.

Install#

bash

pnpm install @lingo.dev/compiler

Configure your framework#

Make your config async and wrap it with withLingo:

// next.config.ts
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, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true,
    },
  });
}

Add LingoProvider#

tsx

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

Authenticate#

bash

npx lingo.dev@latest login

This opens your browser for authentication. The free Hobby tier works for most projects.

If browser auth is blocked, add the key to .env manually:

bash

LINGODOTDEV_API_KEY=your_key_here

Run the dev server#

bash

npm run dev

Add a language switcher (optional)#

tsx

"use client"; // For Next.js

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Espanol</option>
      <option value="de">Deutsch</option>
    </select>
  );
}

Generate real translations#

When ready, disable pseudotranslator:

{
  dev: {
    usePseudotranslator: false,
  }
}

Restart the dev server. The compiler generates real AI translations for new or changed text.

Next Steps#

How It Works

The build-time transformation pipeline

Next.js

Next.js-specific setup and features

Vite + React

Vite-specific setup and features

Configuration Reference

All configuration options

Was this page helpful?