Vite + React

Alpha

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

The Lingo.dev Compiler integrates with Vite through lingoCompilerPlugin, a Vite plugin that transforms your React components at build time to inject translations. It supports full Hot Module Replacement, so translations update instantly during development.

Prerequisites#

Requirements

Vite 5+ with React
Node.js 18+
@lingo.dev/compiler installed

Install#

bash

pnpm install @lingo.dev/compiler

Configure vite.config.ts#

Add lingoCompilerPlugin to your Vite config. The plugin must be placed before the react() plugin - this ordering is required because the compiler needs to transform JSX before the React plugin processes it.

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr", "ja"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

Plugin order matters

If lingoCompilerPlugin is placed after react(), the React plugin processes JSX first and the compiler cannot identify translatable text. Always place the Lingo plugin first in the plugins array.

Add LingoProvider#

Wrap your application root with LingoProvider in your entry file:

tsx

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>
);

LingoProvider initializes the locale context and loads the appropriate translation dictionary for the active locale.

Hot Module Replacement#

The plugin integrates with Vite's HMR system. When you edit translatable text in a component:

Edit source text

Change any text in your JSX - for example, update a heading from "Welcome" to "Welcome back".

Compiler detects the change

The plugin intercepts the HMR update, identifies the changed string, and generates a new translation (or pseudotranslation in dev mode).

Browser updates instantly

The translated component re-renders without a full page reload. Translation metadata in .lingo/metadata.json is updated on disk.

sourceRoot configuration#

The sourceRoot option determines which files the compiler scans for translatable text. For a standard Vite + React project:

{
  sourceRoot: "src",
}

Project structure	Recommended sourceRoot
Standard (`src/`)	`"src"`
Monorepo with shared packages	`"."` (project root)
Custom directory	Path to your components directory

For large codebases, a narrow sourceRoot reduces build times. If you only need translations in specific files, enable useDirective: true and add 'use i18n' to those files. See Project Structure.

Example project structure#

text

my-vite-app/
  src/
    main.tsx          # LingoProvider wraps <App />
    App.tsx           # Translatable components
    components/
      Header.tsx      # Automatically scanned
      Footer.tsx      # Automatically scanned
  .lingo/
    metadata.json     # Translation cache (commit this)
  vite.config.ts      # lingoCompilerPlugin configured here

Next Steps#

Setup

Full setup walkthrough with authentication

Configuration Reference

All configuration options

Locale Switching

Add a language switcher to your app

Development Tools

Pseudotranslator and dev server