Как перевести приложение Next.js Pages
Загрузите переведённые сообщения страницы, выведите их через обёртку Pages и добавьте переключение локали и ссылки на альтернативные версии.
Маршрут Next.js Pages уже определяет локаль запроса. @lingo.dev/react-next использует её, чтобы передать сообщения в React и хранить данные страницы вместе с переведённым текстом. В этом примере мы выведем страницу «О нас» на английском и французском и сохраним выбор маршрута, даже если в переведённом JSONC больше нет метаданных.
Используйте существующее приложение Pages с React 19. В пакете указаны peer-зависимости Next.js 13+ и React 18/19, но текущий провайдер использует сокращённый синтаксис контекста React 19 во время выполнения. Пакет экспортирует /pages, /pages/client и /pages/server. Корневого экспорта и точки входа для App Router нет.
Настройте локали и обёртку приложения #
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latestДобавьте i18n в существующий next.config.mjs, сохранив остальные настройки:
export default {
i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};В pages/_app.tsx оберните приложение:
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";
function App({ Component, pageProps }: AppProps) {
const { locale, defaultLocale } = useRouter();
useEffect(() => {
document.documentElement.lang = locale ?? defaultLocale ?? "en";
}, [locale, defaultLocale]);
return <Component {...pageProps} />;
}
export default withLingoApp(App);Обёртка читает pageProps.__lingoMessages, определяет активную локаль Next и передаёт LingoProvider. Правила формирования URL задают настройки i18n самого Next. Если английский — язык по умолчанию, его путь обычно не содержит префикса.
Создайте страницу и загрузите её сообщения #
Сначала добавьте функцию loadMatchedMessages из раздела «Загрузка каталогов» как lib/catalog.ts. Она проверяет JSONC со строковыми значениями и сопоставляет переводы с активными ключами исходного каталога.
Затем создайте pages/about.tsx:
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";
export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
if (!["en", "fr"].includes(locale)) return { notFound: true };
const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
const target =
locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
const messages = loadMatchedMessages(source, target, (entry) => {
const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
});
return { props: { __lingoMessages: messages } };
};
export default function About() {
const l = useLingo();
return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}Этот предикат оставляет записи самой страницы и сообщения общих компонентов. Он убирает расширения и старые суффиксы с номерами строк из метаданных исходного кода. Если страница находится в src/pages/about.tsx, измените и путь импорта, и условие сравнения маршрута.
Собственный загрузчик намеренно завершает работу с ошибкой, если нужный файл отсутствует или имеет неверный формат. Так сборка не сможет незаметно подставить английский каталог вместо ожидаемого французского. Отдельные отсутствующие ключи перевода не добавляются — для них работает обычная подстановка во время выполнения.
Извлеките сообщения, переведите их и откройте оба маршрута #
Запустите npx lingo extract --src pages --source-locale en из корня проекта. Чтобы создать новую конфигурацию проекта Lingo.dev, выполните:
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitЕсли проект уже настроен, сохраните его привязку и остальные параметры файлов. После извлечения выполните обычные обновления для существующих целевых локалей, получите и проверьте результаты. Затем добавьте fr и заполните недостающие переводы, не меняя эту ревизию исходного текста. Шаги настройки описаны в разделе «Загрузка каталогов», а нужный порядок — в разделе «Как добавить язык». Если общие компоненты находятся вне pages, извлекайте сообщения из каталога со всеми вызовами сообщений либо разместите компоненты в общем дереве src и используйте --src src.
Получив locales/fr.jsonc, запустите обычную команду Next для разработки или сборки. Откройте /about и /fr/about. Первый маршрут использует английский исходный текст, второй — французский перевод для того же ключа заголовка. Проверьте сам французский текст и подстановку исходного текста для намеренно пропущенной записи.
Встроенная загрузка статических свойств #
Если в каждом файле локали сохранены корректные метаданные @src и @orphan, серверная вспомогательная функция может заменить собственный загрузчик getStaticProps из примера выше:
import { withLingoProps } from "@lingo.dev/react-next/pages/server";
export const getStaticProps = withLingoProps({ route: "pages/about" });withLingoProps({ route, handler? }) читает файлы по фиксированным путям locales/<locale>.jsonc относительно рабочего каталога. Функция отфильтровывает записи без соответствующего исходного ключа и записи других страниц. При этом источники, не относящиеся к страницам, и записи без @src считаются общими. Обычный перевод JSONC сохраняет отметки @orphan, но удаляет комментарии @src. Поэтому для такого результата используйте описанное выше сопоставление по ключам исходного каталога: вспомогательная функция не восстанавливает метаданные.
Если файл отсутствует, функция возвращает {} и выводит предупреждение в режиме разработки. Если существующий файл некорректен, возможно исключение. Необязательный асинхронный обработчик добавляет свойства или возвращает результат перенаправления либо отсутствия страницы. При успешном выполнении результат сохраняет поля, например revalidate, и добавляет __lingoMessages. Публичные типы функции используют контекст и результаты статических свойств. Не считайте, что у произвольных серверных обработчиков запросов тот же контракт. Переопределение путей каталогов в CLI тоже не меняет фиксированную папку этого загрузчика.
Расширьте набор статических путей для динамического маршрута #
Для динамического маршрута серверная вспомогательная функция создаёт варианты каждой записи параметров для всех локалей, настроенных в Next:
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
fallback: "blocking",
});Значение fallback по умолчанию — "blocking". Также поддерживаются false и true. Такое расширение не переводит слаги и не проверяет, есть ли сообщения маршрута в каждом каталоге.
Добавьте переключение языка и ссылки на альтернативные версии #
Разместите переключатель внутри обёртки приложения:
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
export function Languages() {
const switchLocale = useLocaleSwitch();
return (
<nav aria-label="Language">
<LingoHead baseUrl="https://example.com" />
<button onClick={() => switchLocale("en")}>English</button>
<button onClick={() => switchLocale("fr")}>Français</button>
</nav>
);
}Замените базовый адрес из примера абсолютным базовым адресом рабочего сайта. LingoHead создаёт ссылки на альтернативные версии для настроенных локалей и x-default без префикса локали по умолчанию. Компонент не создаёт канонические ссылки или метаданные Open Graph. Проверьте итоговые URL с учётом правил маршрутизации и параметров запроса.
Функция обратного вызова переключателя записывает NEXT_LOCALE на один год в / с SameSite=Lax, затем выполняет переход через маршрутизатор Next с текущим asPath. Передавайте настроенные локали, как показано выше: функция не сверяет произвольные входные значения со списком поддерживаемых локалей.
Задайте начальные атрибуты документа #
Задайте начальные атрибуты в pages/_document.tsx, сохранив существующие настройки документа:
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";
export default class LocalizedDocument extends Document {
render() {
const locale = this.props.__NEXT_DATA__.locale ?? "en";
return (
<Html lang={locale} dir={createLingo(locale).direction}>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}withLingoApp задаёт направление текста после смены локали и добавляет встроенный скрипт RTL для начального отображения, но не задаёт lang. Эффект _app из примера выше обновляет lang во время навигации, а собственный документ задаёт оба начальных атрибута. Строгая политика безопасности контента может блокировать встроенный скрипт обёртки, а параметра nonce у обёртки нет. Собственный документ задаёт начальное направление текста независимо от этого скрипта. Проверьте политику выполнения скриптов приложения и во время навигации.
В завершение проверьте гидратацию с тем же каталогом и явно заданными значениями времени. Убедитесь, что при переключении языка сообщения и атрибуты документа меняются вместе.