Налаштування локалізації контенту 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: 'Ukrainian',
code: 'uk',
fallbackCode: 'en-US', // fallback на англійську
optional: true, // поле не обов'язково перекладати
});
Структура даних локалізованих полів
В API-відповіді кожне поле повертається у вигляді об'єкту з ключами по коду локалі:
{
"fields": {
"title": {
"en-US": "How to build a CMS",
"ru": "Как создать CMS",
"uk": "Як створити CMS"
},
"heroImage": {
"en-US": { "sys": { "type": "Link", "id": "abc123" } }
}
}
}
Поля, у яких вимкнена локалізація в Content Type, повертають одне значення без ключа локалі.
Запит з потрібною локаллю
// Запит контенту на конкретній мові
const entries = await client.getEntries<TypeBlogPostSkeleton>({
content_type: 'blogPost',
locale: 'uk', // SDK автоматично обере uk-значення
});
// entries.items[0].fields.title — уже строка, не об'єкт
Next.js i18n + Contentful
// next.config.ts
i18n: {
locales: ['en', 'ru', 'uk'],
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-поведінка: якщо uk-локаль не заповнена, Contentful автоматично повертає значення en-US при умові налаштування fallbackCode. На фронтенді це прозоро — немає потреби обробляти відсутні переводи.
Позначення полів як таких, що не вимагають перекладу
В Content Type Editor кожне поле має чекбокс Enable localization for this field. Поля типу slug, publishedAt, числові ідентифікатори — зазвичай не локалізуються. Це скорочує роботу перекладачів та зменшує розмір API-відповіді.
Типовий час налаштування локалізації для існуючого проекту з 3–5 локалями та 5–10 Content Types — 1–2 дні, включаючи оновлення фронтенд-логіки та налаштування маршрутизації.