Перевод приложения 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. Установите пакеты:
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/):
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/:
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_DE | 301 на канонический адрес. |
Локализованный путь без локали, например /about | 307 на локаль, выбранную по 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 его не считывает.
// 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 передаёт им локаль и каталог. Ни тем ни другим не нужно передавать локаль через свойства.
// 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] не найден.
Добавление метаданных #
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() и действиям форм, в которых указан путь.
"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. Для новой конфигурации:
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/server | getLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales). |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) и тип LocaleOption. |
@lingo.dev/react-next/app/proxy | lingoProxy(locales). |
После установки пакета агенты для работы с кодом могут следовать инструкциям lingo agent-guide react-next-app, а для перехода с next-intl — lingo agent-guide react-next-migrate. См. Настройка с помощью агента для работы с кодом.