Alpha
Le Compiler de Lingo.dev est en alpha. Il est instable, déconseillé en production, et les API peuvent évoluer d’une version à l’autre.
Le Compiler de Lingo.dev s’intègre à l’App Router de Next.js via un wrapper de configuration withLingo() qui transforme votre pipeline de build pour générer des bundles par langue. Il prend en charge React Server Components, Webpack et Turbopack, sans aucune modification du code de vos composants.
Prérequis#
Configuration requise
- Next.js 14+ avec App Router
- Node.js 18+
@lingo.dev/compilerinstallé
Installer#
pnpm install @lingo.dev/compilerConfigurer next.config.ts#
Enveloppez votre configuration Next.js avec withLingo. La fonction de configuration doit être async — c’est indispensable, car withLingo effectue une initialisation asynchrone pendant le build.
// 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", "ja"],
models: "lingo.dev",
dev: {
usePseudotranslator: true,
},
});
}Configuration async requise
La configuration doit être exportée sous la forme d’une fonction async, et non d’un simple objet. Si vous exportez un objet simple, le compiler ne pourra pas s’initialiser et le build échouera. Consultez Troubleshooting pour plus de détails.
Ajouter LingoProvider#
Enveloppez votre layout racine avec LingoProvider pour activer le contexte de langue dans tout l’arbre de composants :
// 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>
);
}LingoProvider gère la détection de la langue, sa persistance et le chargement des dictionnaires. Il fonctionne aussi bien avec les Server Components que les Client Components.
Server Components et Client Components#
Le compiler gère les deux types de composants en toute transparence :
| Type de composant | Fonctionnement des traductions |
|---|---|
| React Server Components | Traductions résolues au moment de la requête côté serveur. Aucun surcoût JS côté client. |
Client Components ("use client") | Traductions incluses dans le chunk client. useLingoContext() est disponible pour changer de langue. |
| Composants partagés | Fonctionnent dans les deux contextes. Le compiler détecte automatiquement l’environnement de rendu. |
// app/page.tsx - Server Component (default)
export default function Home() {
return <h1>Welcome to our app</h1>;
// Renders translated text with zero client JS
}// app/components/greeting.tsx - Client Component
"use client";
export function Greeting() {
return <p>Hello, world</p>;
// Translations included in client bundle
}Prise en charge des bundlers#
Le wrapper withLingo() fonctionne avec les deux bundlers pris en charge par Next.js :
| Bundler | Prise en charge | Remarques |
|---|---|---|
| Webpack | Complète | Bundler par défaut. Aucune configuration supplémentaire requise. |
| Turbopack | Complète | À activer avec next dev --turbopack. Le compiler détecte automatiquement Turbopack. |
Configuration de sourceRoot#
L’option sourceRoot indique au compiler quel répertoire contient vos composants traduisibles. Pour les projets Next.js App Router, il s’agit généralement de ./app :
{
sourceRoot: "./app",
}Si vous avez des composants en dehors de ./app (par exemple dans un répertoire partagé components/), définissez sourceRoot sur leur parent commun :
{
sourceRoot: ".",
}Un sourceRoot plus large signifie que davantage de fichiers seront analysés. Pour les projets volumineux, gardez-le aussi restreint que possible afin de réduire les temps de build. Vous pouvez aussi utiliser useDirective: true et n’ajouter 'use i18n' qu’aux fichiers qui nécessitent une traduction. Consultez Project Structure pour plus de détails.
