Démarrage rapide

Ajoutez la prise en charge multilingue à votre application React en moins de 5 minutes.

Prérequis

  • Node.js 18+
  • Application React utilisant Next.js (App Router) ou Vite

Installation

pnpm install @lingo.dev/compiler

Configuration

Next.js

Rendez votre configuration asynchrone et enveloppez-la avec 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, // Fake translations for development
    },
  });
}

Vite

Ajoutez le plugin Lingo à votre configuration Vite :

// vite.config.ts
import { defineConfig } from "vite";
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,
      },
    }),
    // ...other plugins
  ],
});

Configuration du provider

Next.js

Enveloppez votre application avec LingoProvider dans votre layout racine :

// 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>
  );
}

Vite

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";

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

Authentification

Le compilateur utilise Lingo.dev Engine par défaut pour les traductions.

Option 1 : Lingo.dev Engine (recommandé)

Inscrivez-vous sur lingo.dev et authentifiez-vous :

npx lingo.dev@latest login

Utilisateurs Windows : Si npx lingo.dev ne fonctionne pas dans votre environnement :

  1. Installez le package : npm install lingo.dev@latest
  2. Utilisez npx lingo à la place (par exemple, npx lingo login)

Cela enregistre votre clé API localement. Le niveau gratuit Hobby est suffisant pour la plupart des projets.

Problèmes d'authentification ? Si votre navigateur bloque le flux d'authentification, ajoutez manuellement votre clé API à .env :

LINGODOTDEV_API_KEY=your_key_here

Trouvez votre clé API dans les paramètres du projet Lingo.dev.

Option 2 : fournisseur LLM direct

Vous pouvez également utiliser directement n'importe quel fournisseur LLM pris en charge. Mettez à jour votre configuration :

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
    // or "google:gemini-2.0-flash"
    // or "openai:gpt-4o"
    // or "anthropic:claude-3-5-sonnet"
  }
}

Ajoutez la clé API correspondante à .env :

GROQ_API_KEY=your_key
# or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY

Consultez Fournisseurs de traduction pour tous les fournisseurs pris en charge.

Lancer le serveur de développement

Démarrez votre serveur de développement :

npm run dev

Le compilateur va :

  1. Analyser votre JSX pour détecter le texte traduisible
  2. Générer des pseudo-traductions (fausses traductions pour visualiser ce qui est traduit)
  3. Les injecter dans vos composants
  4. Stocker les métadonnées dans .lingo/metadata.json

Pourquoi des pseudo-traductions ? Elles sont instantanées (pas d'appels API), montrent exactement ce qui est traduit et aident à tester votre interface avec des longueurs de texte variables — le tout sans dépenser de crédits API.

Tester la traduction

Ajoutez un composant simple :

export function Welcome() {
  return (
    <div>
      <h1>Welcome to our app</h1>
      <p>This text will be translated automatically</p>
    </div>
  );
}

Aucune modification de code nécessaire — le texte est automatiquement extrait et traduit.

Ajouter un sélecteur de langue (optionnel)

Permettez aux utilisateurs de changer de langue :

"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">Español</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  );
}

Générer de vraies traductions

Lorsque vous êtes prêt pour de vraies traductions, mettez à jour votre configuration :

{
  dev: {
    usePseudotranslator: false, // Disable fake translations
  }
}

Redémarrez votre serveur de développement. Le compilateur va maintenant générer de vraies traductions IA pour tout texte nouveau ou modifié.

Soucieux des coûts ? Les pseudo-traductions sont gratuites et instantanées. Ne les désactivez que lorsque vous devez vérifier la qualité réelle des traductions.

Questions fréquentes

Dois-je marquer chaque chaîne traduisible ? Non. Le compilateur détecte automatiquement le texte JSX. Pour opter pour une approche explicite, définissez useDirective: true et ajoutez 'use i18n' en haut des fichiers que vous souhaitez traduire.

Qu'en est-il du contenu dynamique ou des props ? Le compilateur gère automatiquement les attributs de chaîne comme alt, aria-label et placeholder. Pour le texte dynamique, utilisez la syntaxe de template : <p>Hello {name}</p> fonctionne comme prévu.

Puis-je personnaliser des traductions spécifiques ? Oui. Utilisez l'attribut data-lingo-override :

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

Comment valider les traductions ? Validez le répertoire .lingo/ dans le contrôle de version. Il contient les métadonnées et les traductions en cache — sûr à valider et doit être versionné avec votre code.

Prochaines étapes