Интеграция с Next.js

Альфа

Compiler от Lingo.dev находится в альфа-версии. Он нестабилен, не рекомендуется для production-использования, а API могут меняться от релиза к релизу.

Compiler от Lingo.dev интегрируется с Next.js App Router через конфигурационную обёртку withLingo(), которая преобразует пайплайн сборки и создаёт отдельные бандлы для каждой локали. Поддерживаются React Server Components, Webpack и Turbopack — без изменений в коде компонентов.

Что понадобится#

Требования

Next.js 14+ с App Router
Node.js 18+
Установленный @lingo.dev/compiler

Установка#

bash

pnpm install @lingo.dev/compiler

Настройте next.config.ts#

Оберните конфигурацию Next.js с помощью withLingo. Конфигурация должна быть оформлена как функция async — это обязательно, потому что 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", "ja"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true,
    },
  });
}

Требуется асинхронная конфигурация

Конфигурацию нужно экспортировать как функцию async, а не как обычный объект. Если экспортировать обычный объект, Compiler не сможет инициализироваться, и сборка завершится ошибкой. Подробности см. в разделе Устранение неполадок.

Добавьте LingoProvider#

Оберните корневой layout в LingoProvider, чтобы включить контекст локали во всём дереве компонентов:

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 отвечает за определение локали, её сохранение и загрузку словарей. Он работает и с Server Components, и с Client Components.

Server Components и Client Components#

Compiler прозрачно работает с обоими типами компонентов:

Тип компонента	Как работают переводы
React Server Components	Переводы определяются на сервере во время запроса. Без дополнительной нагрузки JS на клиенте.
Client Components (`"use client"`)	Переводы включаются в клиентский чанк. `useLingoContext()` доступен для переключения локали.
Общие компоненты	Работают в обоих контекстах. Compiler автоматически определяет среду рендеринга.

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
}

Поддержка сборщиков#

Обёртка withLingo() работает с обоими сборщиками, которые поддерживает Next.js:

Сборщик	Поддержка	Примечания
Webpack	Полная	Сборщик по умолчанию. Дополнительная настройка не требуется.
Turbopack	Полная	Включается с помощью `next dev --turbopack`. Compiler автоматически определяет Turbopack.

Конфигурация sourceRoot#

Опция sourceRoot указывает Compiler, в каком каталоге находятся компоненты с переводимым текстом. В проектах Next.js с App Router это обычно ./app:

{
  sourceRoot: "./app",
}

Если часть компонентов находится вне ./app (например, в общей директории components/), укажите в sourceRoot их общий родительский каталог:

{
  sourceRoot: ".",
}

Чем шире sourceRoot, тем больше файлов придётся сканировать. В крупных проектах лучше делать его как можно уже, чтобы сократить время сборки. Либо используйте useDirective: true и добавляйте 'use i18n' только в те файлы, где нужен перевод. Подробности см. в разделе Структура проекта.

Что дальше#

Настройка

Полное пошаговое руководство по настройке с аутентификацией

Справочник по конфигурации

Все параметры конфигурации

Переключение локали

Добавьте в приложение переключатель языка

Режимы сборки

Процессы для dev, CI и production