Alpha
Der Lingo.dev Compiler befindet sich in der Alpha-Phase. Er ist instabil, nicht für den Produktiveinsatz empfohlen, und APIs können sich zwischen Releases ändern.
Der Lingo.dev Compiler lässt sich über einen withLingo()-Config-Wrapper in den Next.js App Router integrieren. Dabei wird deine Build-Pipeline so angepasst, dass pro Sprache eigene Bundles erzeugt werden. React Server Components, Webpack und Turbopack werden ohne Änderungen an deinem Komponenten-Code unterstützt.
Voraussetzungen#
Anforderungen
- Next.js 14+ mit App Router
- Node.js 18+
@lingo.dev/compilerinstalliert
Installation#
pnpm install @lingo.dev/compilernext.config.ts konfigurieren#
Umschließe deine Next.js-Konfiguration mit withLingo. Die Config-Funktion muss async sein – das ist erforderlich, weil withLingo während des Builds asynchron initialisiert wird.
// 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,
},
});
}Asynchrone Config erforderlich
Die Config muss als async-Funktion exportiert werden, nicht als einfaches Objekt. Wenn du ein einfaches Objekt exportierst, kann der Compiler nicht initialisiert werden und der Build schlägt fehl. Weitere Details findest du unter Fehlerbehebung.
LingoProvider hinzufügen#
Umschließe dein Root-Layout mit LingoProvider, um den Sprachkontext im gesamten Komponentenbaum verfügbar zu machen:
// 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 übernimmt die Auflösung der Sprache, deren Persistenz und das Laden der Wörterbücher. Es funktioniert sowohl mit Server Components als auch mit Client Components.
Server Components und Client Components#
Der Compiler unterstützt beide Komponententypen nahtlos:
| Komponententyp | So funktionieren Übersetzungen |
|---|---|
| React Server Components | Übersetzungen werden zur Request-Zeit auf dem Server aufgelöst. Kein zusätzlicher clientseitiger JS-Overhead. |
Client Components ("use client") | Übersetzungen werden in den Client-Chunk gebündelt. useLingoContext() steht für den Sprachwechsel zur Verfügung. |
| Gemeinsam genutzte Komponenten | Funktionieren in beiden Kontexten. Der Compiler erkennt die Rendering-Umgebung automatisch. |
// 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
}Unterstützte Bundler#
Der Wrapper withLingo() funktioniert mit beiden von Next.js unterstützten Bundlern:
| Bundler | Support | Hinweise |
|---|---|---|
| Webpack | Vollständig | Standard-Bundler. Keine zusätzliche Konfiguration erforderlich. |
| Turbopack | Vollständig | Mit next dev --turbopack aktivieren. Der Compiler erkennt Turbopack automatisch. |
sourceRoot-Konfiguration#
Mit der Option sourceRoot teilst du dem Compiler mit, welches Verzeichnis deine übersetzbaren Komponenten enthält. In Next.js-App-Router-Projekten ist das in der Regel ./app:
{
sourceRoot: "./app",
}Wenn du Komponenten außerhalb von ./app hast, etwa in einem gemeinsam genutzten Verzeichnis components/, setze sourceRoot auf das gemeinsame übergeordnete Verzeichnis:
{
sourceRoot: ".",
}Je breiter sourceRoot gefasst ist, desto mehr Dateien werden gescannt. Halte den Wert bei großen Projekten daher so eng wie möglich, um die Build-Zeiten zu verkürzen. Alternativ kannst du useDirective: true verwenden und 'use i18n' nur in Dateien hinzufügen, die übersetzt werden müssen. Weitere Details findest du unter Projektstruktur.
