Настройка локализации контента Contentful
Contentful поддерживает множественные локали на уровне платформы: каждое поле Entry хранит отдельное значение для каждого языка. Локали настраиваются в Space Settings, а не в Content Model — это важное архитектурное отличие от плагинной локализации в WordPress.
Настройка локалей в Space
В Contentful Web App: Settings → Locales → Add locale. Основная локаль (default locale) определяет fallback: если поле не переведено — показывается значение default-локали.
При программной настройке через CMA:
import { createClient } from 'contentful-management';
const env = await cmaClient.getSpace(spaceId).then(s => s.getEnvironment('master'));
// Добавление локали
await env.createLocale({
name: 'Russian',
code: 'ru',
fallbackCode: 'en-US', // fallback на английский
optional: true, // поле не обязательно переводить
});
Структура данных локализованных полей
В API-ответе каждое поле возвращается в виде объекта с ключами по коду локали:
{
"fields": {
"title": {
"en-US": "How to build a CMS",
"ru": "Как создать CMS",
"de": "Wie man ein CMS erstellt"
},
"heroImage": {
"en-US": { "sys": { "type": "Link", "id": "abc123" } }
}
}
}
Поля, у которых отключена локализация в Content Type, возвращают только одно значение без ключа локали.
Запрос с нужной локалью
// Запрос контента на конкретном языке
const entries = await client.getEntries<TypeBlogPostSkeleton>({
content_type: 'blogPost',
locale: 'ru', // SDK автоматически выберет ru-значения
});
// entries.items[0].fields.title — уже строка, не объект
Next.js i18n + Contentful
// next.config.ts
i18n: {
locales: ['en', 'ru', 'de'],
defaultLocale: 'en',
}
// app/[locale]/blog/page.tsx
export default async function BlogPage({ params }) {
const contentfulLocale = localeMap[params.locale]; // 'en' -> 'en-US'
const posts = await client.getEntries({
content_type: 'blogPost',
locale: contentfulLocale,
order: ['-fields.publishedAt'],
});
return <BlogList posts={posts.items} />;
}
Fallback-поведение: если ru-локаль не заполнена, Contentful возвращает значение en-US автоматически при условии настройки fallbackCode. На фронтенде это прозрачно — нет нужды обрабатывать отсутствующие переводы.
Пометка полей как не требующих перевода
В Content Type Editor каждое поле имеет чекбокс Enable localization for this field. Поля типа slug, publishedAt, числовые идентификаторы — обычно не локализуются. Это сокращает работу переводчиков и уменьшает размер API-ответа.
Типичное время настройки локализации для существующего проекта с 3–5 локалями и 5–10 Content Types — 1–2 дня, включая обновление фронтенд-логики и настройку маршрутизации.