Integrace s Next.js

Alfa

Compiler od Lingo.dev je ve fázi alfa. Je nestabilní, nedoporučuje se pro produkční nasazení a API se mezi verzemi může měnit.

Compiler od Lingo.dev se integruje s Next.js App Router pomocí konfiguračního wrapperu withLingo(), který upraví váš build pipeline tak, aby vytvářel bundle pro každý jazyk. Podporuje React Server Components, Webpack i Turbopack bez jakýchkoli změn v kódu komponent.

Požadavky#

Požadavky

Next.js 14+ s App Router
Node.js 18+
Nainstalovaný @lingo.dev/compiler

Instalace#

bash

pnpm install @lingo.dev/compiler

Nakonfigurujte next.config.ts#

Obalte konfiguraci Next.js pomocí withLingo. Konfigurační funkce musí být async — je to povinné, protože withLingo během buildu provádí asynchronní inicializaci.

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

Asynchronní konfigurace je povinná

Konfiguraci musíte exportovat jako funkci async, ne jako prostý objekt. Pokud exportujete prostý objekt, Compiler se nebude moci inicializovat a build selže. Podrobnosti najdete v části Řešení problémů.

Přidejte LingoProvider#

Obalte kořenový layout pomocí LingoProvider, aby byl kontext jazyka aktivní v celém stromu komponent:

tsx

// 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 zajišťuje určení jazyka, jeho zachování i načítání slovníků. Funguje se Server Components i Client Components.

Server Components a Client Components#

Compiler transparentně zpracovává oba typy komponent:

Typ komponenty	Jak překlady fungují
React Server Components	Překlady se vyhodnocují na serveru při zpracování požadavku. Bez režie klientského JS.
Client Components (`"use client"`)	Překlady jsou součástí klientského chunku. `useLingoContext()` je k dispozici pro přepínání jazyka.
Sdílené komponenty	Fungují v obou kontextech. Compiler automaticky rozpozná prostředí vykreslování.

tsx

// app/page.tsx - Server Component (default)
export default function Home() {
  return <h1>Welcome to our app</h1>;
  // Renders translated text with zero client JS
}

tsx

// app/components/greeting.tsx - Client Component
"use client";

export function Greeting() {
  return <p>Hello, world</p>;
  // Translations included in client bundle
}

Podpora bundlerů#

Wrapper withLingo() funguje s oběma bundlery, které Next.js podporuje:

Bundler	Podpora	Poznámky
Webpack	Plná	Výchozí bundler. Není potřeba žádná další konfigurace.
Turbopack	Plná	Aktivujete pomocí `next dev --turbopack`. Compiler Turbopack rozpozná automaticky.

Konfigurace sourceRoot#

Volba sourceRoot určuje Compileru, který adresář obsahuje přeložitelné komponenty. U projektů s Next.js App Router je to obvykle ./app:

{
  sourceRoot: "./app",
}

Pokud máte komponenty mimo ./app (například ve sdíleném adresáři components/), nastavte sourceRoot na jejich společný nadřazený adresář:

{
  sourceRoot: ".",
}

Širší sourceRoot znamená, že se bude procházet více souborů. U velkých projektů ho proto udržujte co nejužší, abyste zkrátili dobu buildu. Případně použijte useDirective: true a přidejte 'use i18n' jen do souborů, které překlad potřebují. Podrobnosti najdete v části Struktura projektu.

Další kroky#

Nastavení

Kompletní průvodce nastavením včetně ověřování

Configuration Reference

Všechny možnosti konfigurace

Přepínání jazyků

Přidejte do aplikace přepínač jazyka

Režimy buildu

Vývojové, CI a produkční Workflows