Как перевести приложение 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 нет.

Настройте локали и обёртку приложения #

sh
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, сохранив остальные настройки:

js
export default {
  i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};

В pages/_app.tsx оберните приложение:

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:

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, выполните:

sh
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 из примера выше:

ts
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:

ts
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";

export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
  fallback: "blocking",
});

Значение fallback по умолчанию — "blocking". Также поддерживаются false и true. Такое расширение не переводит слаги и не проверяет, есть ли сообщения маршрута в каждом каталоге.

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

Разместите переключатель внутри обёртки приложения:

tsx
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, сохранив существующие настройки документа:

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 у обёртки нет. Собственный документ задаёт начальное направление текста независимо от этого скрипта. Проверьте политику выполнения скриптов приложения и во время навигации.

В завершение проверьте гидратацию с тем же каталогом и явно заданными значениями времени. Убедитесь, что при переключении языка сообщения и атрибуты документа меняются вместе.