Локализация Markdoc в Next.js
Настройте маршруты, загрузку, перевод и отображение документов Markdoc для разных локалей вместе с отдельными каталогами строк интерфейса в приложении Next.js с App Router.
Перевод статьи должен быть на том же языке, что и страница вокруг неё. На сайте Next.js локаль маршрута может определять и документ Markdoc, и отдельный каталог строк интерфейса для навигации. В этом руководстве мы подключим эти файлы к странице App Router, а затем переведём их с помощью CLI.
Используйте существующий проект Next.js с App Router и Markdoc. В примере локальные файлы читаются на сервере, без адаптера локализации для React.
Выберите структуру файлов для разных локалей #
Например, документы и каталоги строк интерфейса можно хранить вместе, сгруппировав по локалям:
src/content/
en/
pages/home.mdoc
blog/welcome.mdoc
ui.json
es/
pages/home.mdoc
blog/welcome.mdoc
ui.json
src/app/[lang]/Не меняйте слаги, если они служат идентификаторами контента. Перевод заголовка не требует переименования home.mdoc. Если вы намеренно локализуете слаги, явно задайте соответствия для навигации и ссылок на другие языковые версии. Перевод основного текста сам по себе не создаёт этих соответствий.
Прежде чем формировать путь в файловой системе, проверьте, что локаль маршрута и слаг документа входят в наборы допустимых значений. Решите, что делать, если перевода нет: возвращать ответ «Не найдено» или явно подставлять версию на исходном языке. В примере главной страницы ниже используется фиксированное имя документа. Если локаль не поддерживается или файла нет, возвращается ответ «Не найдено».
Выберите обработчик Markdoc и видимые метаданные #
Установите и привяжите CLI из корневой папки проекта:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo linkСохраните созданные ИД организации и движка локализации в .lingo/config.json, затем укажите все настройки выбора исходных файлов:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [
{
"pattern": "src/content/en/pages/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{
"pattern": "src/content/en/blog/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{ "pattern": "src/content/en/ui.json" }
]
}.mdoc автоматически выбирает Markdoc, а явное указание формата делает этот выбор понятным. Если в существующем проекте синтаксис Markdoc хранится в .md, явно задайте format: "markdoc". Иначе по расширению будет выбран обычный Markdown. Эта разница важна для пользовательских тегов и выбранных атрибутов компонентов.
Явно укажите, какие видимые поля frontmatter нужно переводить. Не меняйте даты, авторов, постоянные ИД и метаданные маршрутизации, если правила работы с контентом не требуют конкретного преобразования. Объявляйте свойства компонентов переводимыми, только если они содержат текст для читателей. О том, как работает обработчик, см. в разделе Markdoc, а названия параметров для файлов — в разделе Конфигурация CLI. Параметры API для документов используют другую схему.
Используйте отдельный каталог строк интерфейса для каждой локали. Другие варианты структуры для генераторов сайтов описаны в разделе Статический контент.
Отобразите главную страницу на исходном языке по маршруту с локалью #
Добавьте в src/content/en/pages/home.mdoc заголовок и описание в блоке метаданных YAML frontmatter, а после него — текст статьи. В src/content/en/ui.json добавьте {"home": "Home"} для подписи в навигации. Установите @markdoc/markdoc и yaml, если их ещё нет в зависимостях проекта.
В этом минимальном примере src/app/[lang]/page.tsx главная страница на исходном и целевом языках загружается одним и тем же способом. Параметры маршрута передаются через Promise, как принято в текущей версии App Router:
import { readFile } from "node:fs/promises";
import path from "node:path";
import React from "react";
import Markdoc from "@markdoc/markdoc";
import { parse as parseYaml } from "yaml";
import { notFound } from "next/navigation";
export const runtime = "nodejs";
export default async function Page({
params,
}: {
params: Promise<{ lang: string }>;
}) {
const { lang } = await params;
if (lang !== "en" && lang !== "es") notFound();
const root = path.join(process.cwd(), "src/content", lang);
let rawDocument: string;
let rawUi: string;
try {
[rawDocument, rawUi] = await Promise.all([
readFile(path.join(root, "pages/home.mdoc"), "utf8"),
readFile(path.join(root, "ui.json"), "utf8"),
]);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") notFound();
throw error;
}
const ast = Markdoc.parse(rawDocument);
const errors = Markdoc.validate(ast);
if (errors.some(({ error }) => ["error", "critical"].includes(error.level))) {
throw new Error("Invalid Markdoc document");
}
const metadata = parseYaml(ast.attributes.frontmatter ?? "");
const ui = JSON.parse(rawUi);
if (typeof metadata?.title !== "string" || typeof ui.home !== "string") {
throw new Error("Missing homepage title or navigation label");
}
const tree = Markdoc.transform(ast);
return (
<main lang={lang}>
<nav><a href={`/${lang}`}>{ui.home}</a></nav>
<h1>{metadata.title}</h1>
{Markdoc.renderers.react(tree, React)}
</main>
);
}Сначала откройте /en. В этом примере используются стандартные узлы Markdoc. Если на сайте есть пользовательские теги, передайте конфигурацию сайта и в Markdoc.validate, и в Markdoc.transform, а затем передайте именованные компоненты React в Markdoc.renderers.react. Необходимые переменные передавайте явно. Обработчик перевода сохраняет аннотации, но не предоставляет схему тегов сайта.
Используйте тот же загрузчик с проверками для генерации метаданных и других маршрутов. Для динамических слагов документов сначала найдите запись в известном списке контента и только затем читайте файл по пути. Загрузчику, который использует файловую систему Node, нужны файлы контента в составе развёртываемого приложения. Убедитесь, что они попадают в сборку для рабочей среды. Для развёртывания в среде Edge без доступа к файловой системе нужен другой способ чтения из хранилища.
Согласуйте выбор локали и навигацию #
Для маршрутов без локали используйте предпочтение, явно заданное в приложении, или выберите поддерживаемую локаль на основе Accept-Language. Разберите весовые коэффициенты предпочтений и региональные теги, затем перенаправьте запрос на соответствующий маршрут [lang], сохранив остальную часть пути.
Не перенаправляйте маршруты, в которых уже указана поддерживаемая локаль, запросы API, внутренние ресурсы Next.js и статические файлы. Слишком широкое условие сопоставления может вызвать циклы перенаправлений или направить запросы изображений на маршруты документов. Задайте исключения, которые поддерживает API перехвата маршрутов в установленной версии Next.js. В более ранних проектах используется middleware, а в новых версиях может применяться новое название — proxy. Настраивайте поведение и тесты под установленную версию, а не копируйте старое имя файла как универсальное решение.
Создавайте внутренние ссылки и ссылки на другие языковые версии на основе известных соответствий маршрутов. Прежде чем добавлять целевую страницу в переключатель языка, убедитесь, что она существует. Проверьте и ссылки на заголовки внутри страницы: после перевода заголовков автоматически созданные ИД могут измениться.
Генерируйте только маршруты, для которых есть документы #
Для статической генерации составьте список поддерживаемых пар «локаль и слаг» по фактически доступному контенту. Включите их в процесс generateStaticParams проекта и проверьте созданные маршруты. При динамической загрузке сверяйтесь с тем же списком во время запроса и явно обрабатывайте отсутствие файлов. Не генерируйте все целевые маршруты по списку локалей в расчёте на то, что перевод уже существует.
Создайте недостающие файлы перевода с помощью lingo push --backfill-missing --wait. После завершения убедитесь, что src/content/es/pages/home.mdoc и src/content/es/ui.json существуют, затем откройте /es через тот же загрузчик. Проверьте переведённые заголовок, описание, основной текст, ссылки, блоки кода с ограждениями и структуру пользовательских тегов. Примеры кода и атрибуты, управляющие поведением, должны сохранять исходный смысл и значения.
Если локальные правки перевода нужно защитить от перезаписи при расхождениях, отправьте запрос без --wait и проверьте lingo pull --dry-run перед получением результатов. Прямая запись с ожиданием завершения не предусматривает такой проверки. Следуйте руководству Как сохранить проверенные переводы.
Проверьте страницу, прежде чем переводить её регулярно #
Откройте маршрут целевой локали напрямую, а затем перейдите на него через сайт. Убедитесь, что заголовок, элементы интерфейса, метаданные и переключатель языка используют нужную локаль. Проверьте пользовательский компонент и пример кода, перейдите по внутренней ссылке и ссылке на заголовок внутри страницы. Запустите сборку Next.js, настроенную в проекте, и проверку Markdoc для переведённых файлов.
Храните вместе исходные файлы, принятые переводы, конфигурацию и Lockfile CLI. Для последующих изменений исходного текста используйте обычный рабочий процесс lingo push --wait. Когда страница заработает, выберите управляемый перевод через GitHub или сценарий запуска с возможностью проверить результаты перед записью. Оставьте в этом цикле проверки загрузчика контента и сборку Next.js: lingo check не гарантирует полноту набора документов или корректное отображение пользовательских тегов.