В небольшой продуктовой команде по фрахтовой логистике столкнулся с задачей — локализовать около 30 маркетинговых MDX-страниц на немецкий и испанский. Переводчики работают через Crowdin и не имеют доступа к git. На первый взгляд всё просто — загрузил MDX, получил переведённый файл, но… компонентные пропсы тоже перевелись, и сборка упала. В итоге вопрос: как лучше организовать i18n для такого объёма контента? И стоит ли вообще тащить маркетинг в CMS или проще использовать отдельный hosted сервис?
Расскажу, что пробовал и что понял на практике.
Где болит: переводчики не работают с git, а контент — MDX в монорепозитории
На проекте Next.js с App Router и next-intl для i18n уже есть JSON-файлы с сообщениями, которые синхронизируются с Crowdin без проблем. Но маркетинговые страницы — это MDX-файлы, которые лежат в том же репозитории, и с ними сложнее.
Переводчики не хотят и не могут править файлы напрямую в git — это понятно, им проще и привычнее работать в Crowdin или другом редакторе переводов, где виден только текст, а не код.
Попытка прогнать MDX через Crowdin с дефолтными настройками привела к тому, что перевели не только тексты, но и пропсы компонентов — например, в <RouteMap region="midwest" /> регион превратился в “Mittlerer Westen”. Это сломало сборку.
Проблема в том, что MDX — это смесь Markdown и JSX, и переводчики не отделяют UI-пропсы от контента. Значит, нужен более аккуратный подход.
Вариант 1: Headless CMS с document-level i18n
Один из вариантов — подключить headless CMS, например Sanity, и сделать i18n на уровне документов. То есть для каждой страницы есть английская “главная” версия, а переводы — это отдельные документы, связанные ссылкой с оригиналом.
Плюсы:
- Чистое разделение языков, каждый язык — свой документ.
- Переводчики работают в UI CMS, не трогая код.
- Можно легко управлять slug-ами и метаданными.
Минусы:
- Нужно писать логику для связывания документов в Next.js, чтобы по slug отдавать правильный язык.
- Придётся синхронизировать структуру страниц между языками.
- Для 30 страниц — возможно, overkill, если CMS не используется для остального контента.
Вариант 2: Headless CMS с field-level i18n
Так делают Payload, Storyblok и другие — у каждой страницы есть один объект, а у полей есть локализованные значения. Например, поле title содержит английский, немецкий и испанский варианты.
Плюсы:
- Всё в одном объекте, проще получить сразу все языки.
- Можно управлять локализацией прямо на уровне полей.
- Легко менять slug и метаданные через CMS.
Минусы:
- В UI CMS переводчики видят все языки вместе, это иногда сбивает с толку.
- Сложнее мигрировать и обновлять контент, если структура меняется.
- Для MDX-контента не всегда удобно — либо нужно хранить Markdown в полях, либо придумывать кастомные решения.
Вариант 3: Отдельный hosted localization builder
Есть сервисы (например, Lokalise, Phrase, Crowdin с редактором локализации), которые умеют работать с Markdown и даже MDX, и предоставляют UI для перевода, но не связываются напрямую с git.
Можно вынести маркетинговые страницы из основного репозитория и держать их в таком сервисе, а в Next.js подтягивать переводы через API или экспортировать готовые файлы.
Плюсы:
- Переводчики работают в удобном UI.
- Нет риска сломать сборку из-за перевода пропсов.
- Можно быстрее организовать workflow и разделить обязанности.
Минусы:
- Дополнительный источник правды — нужно синхронизировать с основным приложением.
- Возможно, потеря контроля над версионностью.
- Нужно реализовать механизм получения и обновления локализованного контента.
Локализованные слуги и hreflang: что с этим делать?
Маркетинг хочет не просто переводы текста, но и локализованные URL — например, /de/frachtkostenrechner вместо /de/freight-cost-calculator.
next-intl умеет конфигурировать pathnames для статических роутов и через generateMetadata задавать alternates.languages. Но если слуги живут в CMS или в JSON, нужно, чтобы переключатель языка знал сопоставления всех страниц.
Это значит, что при использовании headless CMS или hosted решений надо:
- Хранить и отдавать все локализованные URL для каждой страницы.
- Реализовать логику language switcher, которая умеет переключаться по правильному пути.
- Продумать, нужны ли региональные варианты (
de-DE,de-AT,de-CH) или достаточно простоde.
В App Router это не слишком больно, но требует аккуратной архитектуры.
Превью для переводчиков: самая больная точка
Сейчас у нас workflow такой: изменения делаются через PR, и есть preview-ссылка на Vercel. Но переводчики обычно не заходят туда, и не видят, как контент выглядит в контексте.
Если переводчики не видят страницы, они не могут проверить, как работает перевод и не ломает ли разметку.
Решения, которые пробовал или видел:
- CMS с превью: многие headless CMS умеют показывать страницу с локализованным контентом в UI.
- Hosted сервисы с preview: некоторые поставщики локализации дают возможность “проглядывать” контент.
- Генерация статических preview-страниц для переводчиков, которые можно шарить.
В нашем случае, когда Markdown в git, а переводчики вне репо, превью — это главный риск. Потому что если переводы лезут в JSX-пропсы, сборка падает.
Практический пример: как отделить пропсы от текста в MDX
Чтобы избежать перевода пропсов, можно вынести их в JSON и передавать в компонент через props, а в MDX писать только ключи для текста.
// data/routes.json
{
"midwest": {
"en": "Midwest",
"de": "Mittlerer Westen",
"es": "Medio Oeste"
}
}
// RouteMap.tsx
interface RouteMapProps {
regionKey: string;
locale: string;
}
export const RouteMap = ({ regionKey, locale }: RouteMapProps) => {
const labels = require('./data/routes.json');
const region = labels[regionKey]?.[locale] || regionKey;
return <div>{region}</div>;
}
// marketing-page.mdx
import { RouteMap } from './RouteMap';
<RouteMap regionKey="midwest" locale="de" />
Так переводчики редактируют JSON с текстом, а не пропсы в MDX. Это безопаснее и легче контролировать.
Итоги
Если у вас 30 маркетинговых MDX-страниц, переводчики не работают с git, и нужен i18n на несколько языков с локализованными URL, то:
-
Если у вас уже есть headless CMS и опыт работы c ней — document-level i18n проще поддерживать. Каждый язык — своя страница, можно гибко управлять slug-ами и метаданными.
-
Если CMS нет, а в проекте много статического MDX — попробуйте вынести тексты в JSON и пушить переводы туда, чтобы не ломать сборку.
-
Hosted локализационные платформы помогут быстро организовать workflow, но добавят сложность в синхронизацию и превью.
-
Локализованные слуги и hreflang требуют дополнительной логики в роутинге и language switcher.
-
Превью для переводчиков — самая хрупкая часть. Без него риски получить переводы с ошибками, которые ломают сборку.
В нашем случае, на фоне ограниченного времени (немецкий и испанский к концу квартала), я склоняюсь к простому решению с JSON-локалями и аккуратным разграничением пропсов и текстов, плюс минимальный CMS для маркетинга с document-level i18n, чтобы маркетинг мог править без devов. Hosted платформы пока рассматриваю как запасной вариант.
Если интересно, могу потом поделиться, как интегрировал next-intl с Sanity и как строил language switcher с локализованными URL.
Если вы сталкивались с похожими задачами, напишите, какой подход у вас лучше сработал и почему.
Попробуй сам: Vercel — Edge Functions и serverless деплой.
Источник: https://www.reddit.com/r/nextjs/comments/1x9rspe/nextjs_i18n_for_30_mdx_marketing_pages_which_cms/