Alpha
Le Compiler Lingo.dev est en version alpha. Il reste instable, n’est pas recommandé en production, et ses API peuvent évoluer d’une version à l’autre.
Le Compiler Lingo.dev s’intègre à Vite via lingoCompilerPlugin, un plugin Vite qui transforme vos composants React à la compilation pour y injecter les traductions. Il prend en charge l’intégralité du Hot Module Replacement, pour des traductions mises à jour instantanément pendant le développement.
Prérequis#
Configuration requise
- Vite 5+ avec React
- Node.js 18+
@lingo.dev/compilerinstallé
Installation#
pnpm install @lingo.dev/compilerConfigurer vite.config.ts#
Ajoutez lingoCompilerPlugin à votre configuration Vite. Le plugin doit être placé avant le plugin react() : cet ordre est indispensable, car le compilateur doit transformer le JSX avant son traitement par le plugin React.
// 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(),
],
});L’ordre des plugins est essentiel
Si lingoCompilerPlugin est placé après react(), le plugin React traite le JSX en premier et le compilateur ne peut plus identifier le texte traduisible. Placez toujours le plugin Lingo en tête du tableau plugins.
Ajouter LingoProvider#
Encapsulez la racine de votre application avec LingoProvider dans votre fichier 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>
);LingoProvider initialise le contexte de langue et charge le dictionnaire de traduction approprié pour la langue active.
Hot Module Replacement#
Le plugin s’intègre au système HMR de Vite. Lorsque vous modifiez du texte traduisible dans un composant :
Modifier le texte source
Modifiez n’importe quel texte dans votre JSX — par exemple, remplacez un titre de "Welcome" à "Welcome back".
Le compilateur détecte la modification
Le plugin intercepte la mise à jour HMR, identifie la chaîne modifiée et génère une nouvelle traduction (ou une pseudo-traduction en mode développement).
Le navigateur se met à jour instantanément
Le composant traduit est rerendu sans rechargement complet de la page. Les métadonnées de traduction dans .lingo/metadata.json sont mises à jour sur le disque.
Configuration de sourceRoot#
L’option sourceRoot détermine les fichiers que le compilateur analyse pour y repérer le texte traduisible. Pour un projet Vite + React standard :
{
sourceRoot: "src",
}| Structure du projet | sourceRoot recommandé |
|---|---|
Standard (src/) | "src" |
| Monorepo avec packages partagés | "." (racine du projet) |
| Répertoire personnalisé | Chemin vers votre répertoire de composants |
Sur les grandes bases de code, un sourceRoot ciblé réduit les temps de compilation. Si vous n’avez besoin de traductions que dans certains fichiers, activez useDirective: true et ajoutez 'use i18n' à ces fichiers. Voir Structure du projet.
Exemple de structure de projet#
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