Настройка локализации Payload CMS: поля, fallback, Next.js

Локализация контента в Payload CMS: от конфига до Next.js

Мы интегрируем локализацию в Payload CMS для мультиязычных проектов на Next.js. Типичная боль: дублирование контента в разных коллекциях, N+1 запросы для fallback-переводов и медленный TTFB из-за неоптимальной схемы. Payload CMS решает это на уровне полей, но без правильной настройки можно получить пустые страницы или лишние миграции.

Проблемы, которые решаем

Fallback-язык и пустые поля. Если перевод отсутствует, пользователь видит пустой блок. Настройка fallback: true в конфиге решает это: при запросе несуществующей локали подставляется значение из defaultLocale. Но важно учитывать, что fallback работает только для полей, помеченных localized. Нелокализованные поля остаются общими.

SEO-слагаемые для каждого языка. Нам часто приходилось генерировать уникальные URL для разных локалей, чтобы избежать дублей в Google. Payload позволяет локализовать поле slug, а Next.js App Router — создавать routes вида /en/posts/hello-world и /ru/posts/privet-mir. Это решает проблему hreflang и CLS при переключении языка.

Оптимизация запросов. Запрос locale: 'all' возвращает все переводы в одном документе — это поверхностное решение. Для производительности используйте отдельные запросы на каждую локаль с кэшированием через Redis или CDN, особенно при ISR в Next.js. Мы сокращаем время ответа API на 60% за счет индексного поиска в PostgreSQL.

Как настроить fallback для локализованных полей?

Конфигурация локалей в Payload CMS — это объект localization в payload.config.ts. Задайте defaultLocale и включите fallback: true. Тогда запрос на языке, для которого нет перевода, вернет значение из defaultLocale. Пример настройки:

// payload.config.ts
export default buildConfig({
  localization: {
    locales: [
      {
        label: 'Русский',
        code: 'ru',
      },
      {
        label: 'English',
        code: 'en',
      },
      {
        label: 'Українська',
        code: 'uk',
      },
    ],
    defaultLocale: 'ru',
    fallback: true,
  },
})

Локализованные поля объявляем точечно. Это даёт гибкость: например, featuredImage остаётся общим, а title и richText — переводимыми.

// collections/Posts.ts
fields: [
  {
    name: 'title',
    type: 'text',
    localized: true,
    required: true,
  },
  {
    name: 'content',
    type: 'richText',
    localized: true,
  },
  {
    name: 'slug',
    type: 'text',
    localized: true,
    unique: true,
  },
  {
    name: 'featuredImage',
    type: 'upload',
    relationTo: 'media',
    // НЕ localized
  },
]

Как запрашивать контент на разных языках через API?

REST-запросы просты: GET /api/posts?locale=en возвращает переводы на английском; ?locale=all — все локали сразу в виде объекта. В Next.js Server Component это выглядит так:

// app/[locale]/posts/[slug]/page.tsx
import { getPayload } from 'payload'
import { notFound } from 'next/navigation'

type Locale = 'ru' | 'en' | 'uk'

export default async function PostPage({
  params,
}: {
  params: { locale: Locale; slug: string }
}) {
  const payload = await getPayload({ config })
  const result = await payload.find({
    collection: 'posts',
    locale: params.locale,
    where: {
      and: [
        { slug: { equals: params.slug } },
        { _status: { equals: 'published' } },
      ],
    },
  })

  if (!result.docs[0]) notFound()

  return <PostPage post={result.docs[0]} />
}

export async function generateStaticParams() {
  const payload = await getPayload({ config })
  const locales: Locale[] = ['ru', 'en', 'uk']
  const params: { locale: Locale; slug: string }[] = []

  for (const locale of locales) {
    const posts = await payload.find({
      collection: 'posts',
      locale,
      limit: 1000,
    })
    posts.docs.forEach(post => {
      if (post.slug) params.push({ locale, slug: post.slug as string })
    })
  }

  return params
}

Этот паттерн даёт SSR, ISR и статическую генерацию для каждого языка. Под капотом Payload создаёт индексы в PostgreSQL, что ускоряет выборку на порядок.

Почему Payload CMS эффективнее Strapi для локализации?

В таблице ниже приведены ключевые отличия. Payload использует JSONB-объекты на уровне полей, что даёт миллисекундный отклик. Strapi же создаёт отдельные записи для каждого языка, что может приводить к N+1 запросам. Contentful принудительно локализует все поля, снижая гибкость.

Благодаря архитектуре Payload мы экономим до 40% времени на разработке локализации.

Процесс работы

1. Аналитика — определяем список языков, необходимость fallback, какие поля локализовать.
2. Проектирование — настройка localization в конфиге, миграции существующих коллекций.
3. Реализация — добавление localized: true к полям, написание кастомных запросов для Next.js.
4. Тестирование — проверка всех локалей вручную и автотестами, метрики Core Web Vitals.
5. Деплой — настройка DNS, CDN, кэширования на Edge.

Сравнение типов запросов в Payload

Что входит в работу

• Конфигурация локалей и fallback в Payload CMS
• Локализация выбранных полей (текст, richText, slug, select и др.)
• Создание API-эндпоинтов с поддержкой локалей
• Интеграция с Next.js App Router: роутинг, SSR, ISR, статическая генерация
• Тестирование и исправление ошибок (hydration mismatch, дубли slug)
• Документация по поддержке и добавлению новых языков
• Обучение контент-менеджеров работе с админкой Payload

Типичные ошибки при локализации

Сроки ориентировочно

Настройка локализации для трёх языков с адаптацией 5–10 коллекций и интеграцией с Next.js — от 1 до 2 дней. Если нужна миграция данных из существующей CMS — срок увеличивается на анализ и ETL.

Почему стоит доверить локализацию нам?

Мы работаем с Payload CMS более 5 лет, реализовали 30+ мультиязычных проектов на Next.js. Наш опыт включает интеграцию с Redis кэшированием, настройку SEO-метаданных для каждого языка и оптимизацию LCP/CLS. Гарантируем, что ваш сайт будет стабильно работать при переключении локалей, а Core Web Vitals не упадут.

Свяжитесь с нами, чтобы получить консультацию по вашей конфигурации. Оценим проект и предложим оптимальную архитектуру. Закажите расчёт стоимости для вашего проекта.