Перевод приложения Next.js с App Router

Добавьте префикс локали ко всем страницам, настройте перенаправление путей без префикса и рендерите переведённые серверные и клиентские компоненты с помощью @lingo.dev/react-next.

В App Router у каждой локали свой префикс URL, в том числе у исходной: читатели открывают /en/pricing и /de/pricing. @lingo.dev/react-next считывает локаль из сегмента маршрута app/[locale], загружает её каталог на сервере и передаёт серверным и клиентским компонентам одинаковые сообщения. В этом примере мы добавим немецкий и французский языки в англоязычное приложение.

Используйте Next.js 16 или новее с React 19. Точки входа считывают локаль через next/root-params. Установите пакеты:

sh
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest

Определение локалей #

Создайте i18n.ts рядом с app/ (src/i18n.ts, если приложение использует src/):

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";

export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });

export const localePath = (pathname: string, locale: string) =>
  locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);

Перечислите локали в .lingo/config.json, указав исходную в defaultLocale. exclude задаёт первые сегменты пути, которым не нужен префикс, например для обработчиков маршрутов в app/api/. Не передавайте slugs: сегмент URL каждой локали должен совпадать с её тегом в нижнем регистре (/pt-br для pt-BR), так как getLingo() определяет локаль только по этому сегменту. Если задать свой слаг, провайдер выдаст ошибку с его именем. Этот файл импортируют прокси, серверные и клиентские компоненты, поэтому не добавляйте в него другие импорты.

Перенаправление путей без префикса #

Создайте proxy.ts рядом с app/:

ts
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";

export const proxy = lingoProxy(locales);

export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };

lingoProxy(locales) обрабатывает два вида запросов:

ЗапросОтвет
Первый сегмент указывает локаль не через её слаг, а иначе, например /DE/about, /de-AT или /de_DE301 на канонический адрес.
Локализованный путь без локали, например /about307 на локаль, выбранную по Accept-Language, с Cache-Control: private, no-store и Vary: Accept-Language.
Всё остальноеundefined.

Перенаправления сохраняют строку запроса и basePath приложения. Next.js считывает правило сопоставления при сборке, поэтому задавайте его литералом и следите, чтобы его api соответствовал exclude. Если в приложении уже есть прокси, сначала вызовите lingoProxy. Если вызов вернёт undefined, продолжайте выполнять свою логику. middleware.ts — тот же файл под старым именем. Переименуйте его в proxy.ts, а его функцию — в proxy.

Перенос маршрутов в папку локали #

Переместите корневой макет и все страницы на один уровень глубже, в app/[locale]/. app/[locale]/layout.tsx станет корневым макетом, а app/layout.tsx больше не будет. Обработчики маршрутов в app/api/, globals.css, значки, robots.ts и sitemap.ts остаются на своих местах. Удалите ключ i18n из next.config, если он есть: App Router его не считывает.

tsx
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";

export function generateStaticParams() {
  return lingoStaticParams(locales);
}

export default async function RootLayout({ children }: { children: ReactNode }) {
  const l = await getLingo();
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoAppProvider locales={locales}>{children}</LingoAppProvider>
      </body>
    </html>
  );
}

lingoStaticParams возвращает по одному { locale } для каждой локали, поэтому при сборке каждая страница предварительно рендерится один раз для каждой локали. LingoAppProvider возвращает 404 для локали, которой нет в списке. Не добавляйте export const dynamicParams = false: Next.js не допускает его при включённом cacheComponents.

Перевод серверных и клиентских компонентов #

Серверные компоненты, страницы, макеты и generateMetadata вызывают await getLingo() из @lingo.dev/react-next/app/server. Клиентские компоненты вызывают useLingo() из @lingo.dev/react, а LingoAppProvider передаёт им локаль и каталог. Ни тем ни другим не нужно передавать локаль через свойства.

tsx
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";

export default async function Home() {
  const l = await getLingo();
  return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}

Серверный компонент может получить l как свойство от родительского серверного компонента. Но никогда не передавайте l клиентскому компоненту: функции не передаются с сервера на клиент. Вызов getLingo() вне app/[locale]/ приводит к ошибке, так как сегмент [locale] не найден.

Добавление метаданных #

tsx
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";

export async function generateMetadata() {
  const l = await getLingo();
  return {
    title: l.text("Pricing", { context: "Title of the pricing page" }),
    ...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
  };
}

lingoMetadata({ locales, pathname, origin, ogLocale? }) возвращает alternates.canonical, alternates.languages для каждой локали вместе с x-default, а также openGraph.url и openGraph.locale. Передайте путь страницы без префикса локали, строки запроса и фрагмента. Динамический маршрут формирует его из своих параметров. Замените базовый адрес из примера на базовый адрес вашего сайта. В разделе Правила URL для локалей описаны lingoHead, который формирует эти значения, и переопределение ogLocale.

Добавьте префикс к каждой внутренней ссылке с помощью localePath("/pricing", l.locale) из i18n.ts. l.locale — обычная строка, поэтому localePath сужает её тип до одной из локалей маршрутизатора, прежде чем locales.prefix добавит префикс. Ссылка без префикса попадает в прокси, который перенаправляет на язык браузера, а не страницы. Это также относится к redirect(), router.push() и действиям форм, в которых указан путь.

tsx
"use client";

import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";

export function LocaleSwitcher() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </Link>
      ))}
    </nav>
  );
}

useLocaleSwitch(locales) возвращает по одному { locale, label, href, current } для каждой локали: текущую страницу для этой локали, название языка на нём самом и признак того, выбран ли он сейчас. Строка запроса добавляется после гидратации, поэтому страница с переключателем остаётся статической. При переходе по ссылке макет рендерится заново и загружает каталог новой локали.

Извлечение и загрузка каталогов #

Сервер считывает locales/<locale>.jsonc из папки, из которой запускается next, с помощью fs, поэтому оставьте для i18n.messagesPath значение по умолчанию — locales. Он отбрасывает записи, на которые больше нет ссылок, и заново считывает файл при каждом запросе, поэтому next dev отдаёт изменённый каталог уже при следующем запросе. Если файла нет, используется пустой каталог, а в режиме разработки выводится предупреждение. Если формат файла некорректен или значение не является строкой, возникает ошибка с именем файла. В рабочей среде каталог исходной локали не отправляется в браузер, так как её текст используется как запасной вариант.

Если app/ находится в корне проекта и папки src/ нет, задайте "i18n": { "src": "." } в .lingo/config.json, чтобы при извлечении сканировались app/ и components/. При извлечении пропускаются node_modules и папки, имена которых начинаются с точки, например .next. Для новой конфигурации:

sh
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Задайте i18n.src после init, так как эта команда перезаписывает раздел i18n. В монорепозитории .lingo/config.json находится в корне репозитория, и пути в нём отсчитываются оттуда. Поэтому messagesPath — это папка приложения вместе с locales, например apps/web/locales. См. карту именованных приложений i18n в разделе Конфигурация CLI. При этом сервер по-прежнему считывает locales/ из папки самого приложения.

После next build и next start откройте / и убедитесь, что происходит перенаправление на локаль. Затем откройте /de и проверьте немецкий текст в HTML.

Среда выполнения #

Предварительно отрендеренные страницы работают на любом хостинге. Страница, которая рендерится по запросу, считывает каталог с диска, поэтому ей нужна среда выполнения Node.js. Cloudflare Workers и среда выполнения Edge не могут его прочитать.

Экспортируемые сущности #

Точка входаЭкспортируемые сущности
@lingo.dev/react-next/app/servergetLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales).
@lingo.dev/react-next/app/clientuseLocaleSwitch(locales) и тип LocaleOption.
@lingo.dev/react-next/app/proxylingoProxy(locales).

После установки пакета агенты для работы с кодом могут следовать инструкциям lingo agent-guide react-next-app, а для перехода с next-intl — lingo agent-guide react-next-migrate. См. Настройка с помощью агента для работы с кодом.