Intégration Vite + React

@lingo.dev/compiler s'intègre avec Vite via un plugin qui fonctionne avec les configurations SPA et SSR.

Configuration

1. Installer le package

pnpm install @lingo.dev/compiler

2. Configurer Vite

Ajoutez lingoCompilerPlugin à votre configuration Vite :

// 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"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

Ordre des plugins : Placez lingoCompilerPlugin avant le plugin react(). Cela garantit que le compilateur transforme votre JSX avant que React ne le traite.

3. Ajouter le provider

Enveloppez votre application avec LingoProvider dans votre point d'entrée :

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

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

Important : Placez LingoProvider aussi haut que possible dans votre arborescence de composants. Si vous utilisez TanStack Router ou React Router, placez LingoProvider au-dessus du provider de routeur.

Configuration SPA

Pour les applications monopage, la configuration ci-dessus est suffisante. La locale est gérée côté client.

Sélecteur de langue

"use client";

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

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

  return (
    <div>
      <label>Language:</label>
      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="de">Deutsch</option>
        <option value="fr">Français</option>
      </select>
    </div>
  );
}

Configuration SSR (React Router, Remix, TanStack Start)

Pour les frameworks SSR, vous devrez peut-être gérer la détection de locale côté serveur.

Détection de locale personnalisée

Créez .lingo/locale-resolver.server.ts pour la logique côté serveur :

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Access request context (framework-specific)
  // Example: parse cookies, headers, or database
  return "en"; // Return detected locale
}

Et .lingo/locale-resolver.client.ts pour le côté client :

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  return localStorage.getItem("locale") || "en";
}

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
}

Consultez Résolveurs de locale personnalisés pour des exemples spécifiques aux frameworks.

Intégration TanStack Router

Pour TanStack Router, placez LingoProvider au-dessus de RouterProvider :

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { RouterProvider, createRouter } from "@tanstack/react-router";
import { LingoProvider } from "@lingo.dev/compiler/react";
import { routeTree } from "./routeTree.gen";

const router = createRouter({ routeTree });

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <RouterProvider router={router} />
    </LingoProvider>
  </StrictMode>
);

Cela garantit que les traductions sont disponibles dans tous vos composants routés et que le contexte n'est pas rompu par le fractionnement du code.

Intégration React Router

Pour React Router v6/v7 :

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

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

HMR et développement

Le compilateur prend entièrement en charge le remplacement de module à chaud (HMR) de Vite. Lorsque vous mettez à jour du texte traduisible :

  1. Le compilateur détecte le changement
  2. Le serveur de traduction génère de nouvelles traductions (ou pseudo-traductions)
  3. HMR met à jour votre composant sans rechargement complet
  4. L'état du composant est préservé

Fast Refresh fonctionne normalement — le compilateur n'interfère pas avec le HMR de Vite.

Configuration de build

Build de développement

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
  }
}

Exécutez npm run dev pour un retour instantané avec des pseudo-traductions.

Build de production

{
  buildMode: "cache-only", // Use pre-generated translations
}

Exécutez npm run build. Les traductions proviennent de .lingo/metadata.json — aucun appel API nécessaire.

Bonne pratique : générez les vraies traductions en CI avant les builds de production. Voir Modes de build.

Fractionnement du code

Le compilateur respecte le fractionnement du code de Vite. Chaque chunk chargé en lazy loading inclut uniquement les traductions dont il a besoin.

// Lazy-loaded route
const Dashboard = lazy(() => import("./pages/Dashboard"));

// Dashboard component's translations are bundled with the Dashboard chunk

Les traductions sont automatiquement tree-shaken — seules les traductions utilisées sont incluses dans chaque chunk.

TypeScript

Le compilateur est entièrement typé :

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  sourceRoot: "src",
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
};

Variables d'environnement

Utilisez le système de variables d'environnement de Vite pour les clés API :

# .env
VITE_LINGO_API_KEY=your_key_here

Accès dans la configuration :

{
  models: "lingo.dev",
  // API key is automatically read from LINGODOTDEV_API_KEY env variable
}

Ne commitez jamais les clés API. Ajoutez .env à .gitignore.

Problèmes courants

« Cannot find module '@lingo.dev/compiler/react' » Assurez-vous que le package est installé : pnpm install @lingo.dev/compiler

Le HMR cesse de fonctionner après l'ajout de LingoProvider Vérifiez que lingoCompilerPlugin est placé avant le plugin react() dans votre configuration Vite.

Les traductions ne s'affichent pas en production Vérifiez buildMode: "cache-only" et que .lingo/metadata.json contient des traductions pour toutes les locales.

Le contexte est rompu avec le code splitting Assurez-vous que LingoProvider est placé au-dessus de votre fournisseur de routeur (TanStack Router, React Router, etc.). Sinon, les routes avec code splitting peuvent perdre le contexte.

Le port 60000 est déjà utilisé Le serveur de traduction trouve automatiquement les ports disponibles (60000-60099). Si tous sont utilisés, configurez manuellement :

{
  dev: {
    translationServerStartPort: 61000, // Use different port range
  }
}

Prochaines étapes