Prompt
How do I set up localization in a headless CMS?
Latest observation
Setting up localization in a headless CMS usually means making your content model support multiple languages, then deciding how to store, query, and deliver the right locale to your frontend.
Here’s a practical way to approach it.
1) Decide your localization strategy
There are two common models:
A. One entry per locale
Example:
About Us (en)About Us (fr)À propos (fr)
Pros
- Simple to understand
- Easy to publish only one language independently
Cons
- Harder to keep content in sync
- Duplicate entries everywhere
B. One entry with localized fields
Example:
title:{ en: "About Us", fr: "À propos" }body:{ en: "...", fr: "..." }
Pros
- Easier to manage translations together
- Better for fallback logic
- Cleaner querying in many CMSs
Cons
- More complex content model
- Some fields may not translate cleanly
Most headless CMSs support some version of the second approach, either natively or via plugins.
2) Define your locales
Pick your supported languages and regions early.
Examples:
enfresen-USen-GB
Tips:
- Use BCP 47 locale codes if possible.
- Decide whether region matters. If not, use language-only codes.
- Establish a default locale, usually
en.
3) Mark which fields are translatable
Not every field should be localized.
Usually translatable:
- Title
- Body copy
- SEO title / description
- CTA labels
- Alt text
- Slugs, if you need localized URLs
Usually not translatable:
- IDs
- Timestamps
- Internal references
- Sort order
- Technical settings
- Some product SKUs or numeric data
A good CMS setup lets you specify localized vs non-localized fields at the schema level.
4) Plan content relationships carefully
Localization gets tricky with references.
For example, if a page references:
- a hero image
- a category
- related articles
Decide whether:
- the reference is shared across all locales, or
- each locale has its own referenced content
Common approach
- Shared assets like images are global
- Page copy is localized
- Some linked entries, like blog posts or categories, may also be localized
5) Handle slugs and URLs
You need to decide whether URLs are localized.
Examples:
/en/about/fr/a-propos
Or:
/about/a-propos
If localized URLs matter, store a localized slug per locale.
Also decide:
- Can slugs differ completely by language?
- Should URLs auto-generate from the title?
- What happens if a slug conflicts?
6) Implement fallback behavior
Users should not see empty pages if a translation is missing.
Typical fallback order:
- Requested locale
- Default locale
- Secondary fallback locale
- Hidden/untranslated state or placeholder
Example:
- User requests
fr frtitle is missing- Show
entitle instead
Be careful with fallback for legal, pricing, or support content where incorrect language can be a problem.
7) Localize the frontend too
Localization is not just CMS content. Your frontend should also handle:
- Language switching
- URL routing
- Date/number formatting
- Currency formatting
- Directionality for RTL languages
- Translation of UI labels, menus, error messages
Example:
- Content from CMS in French
- UI strings from app translation files or i18n system
Use tools like:
- i18next
- next-intl
- react-intl
- vue-i18n
- lingui
8) Provide a good editorial workflow
Editors need a smooth way to manage translations.
Good CMS features to use:
- Duplicate content from default locale
- Show translation status per field or entry
- Draft/publish per locale
- Preview locale-specific content
- Track missing translations
- Restrict publishing until required locales are ready
If your CMS doesn’t support this natively, you may need custom workflow rules.
9) Expose locale in your API queries
Your frontend should request content by locale.
Examples:
?locale=frAccept-Language: fr- GraphQL locale argument
You may also want:
fallback=truelocale=allfor preview or admin use- separate endpoints for preview versus production
10) Optimize for SEO
If localized pages are public, SEO matters.
Best practices:
- Use locale-specific URLs
- Add
hreflangtags - Ensure translated meta title and description
- Translate canonical pages carefully
- Avoid duplicate content across locales
Example:
<link rel="alternate" hreflang="en" href="https://example.com/en/about" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/a-propos" />
11) Consider automation
Useful automation includes:
- Auto-create new locale entries from default language
- Flag untranslated fields
- Send notifications when content is ready for translation
- Connect to translation services like Lokalise, Crowdin, Phrase, or Smartling
Some teams use machine translation for drafts, then human review before publish.
12) Test edge cases
Make sure to test:
- Missing translations
- Mixed-language content
- RTL support
- Pluralization rules
- Date/currency formatting
- Slug conflicts
- Locale switching on dynamic routes
- SEO metadata per locale
Example content model
A simple localized “Page” model might look like this:
{
"id": "about-page",
"title": {
"en": "About Us",
"fr": "À propos"
},
"slug": {
"en": "about",
"fr": "a-propos"
},
"body": {
"en": "We are a global company...",
"fr": "Nous sommes une entreprise internationale..."
},
"seoTitle": {
"en": "About Us | Example",
"fr": "À propos | Example"
},
"published": {
"en": true,
"fr": true
}
}
A simple implementation checklist
- Choose locales and default locale
- Decide per-field localization rules
- Set up fallback logic
- Localize slugs/URLs if needed
- Localize SEO fields
- Wire locale into CMS API queries
- Add frontend language routing
- Handle UI translations separately
- Set editorial workflows
- Test missing translations and SEO
If you want, I can also show you:
- a Contentful/Sanity/Strapi-specific setup, or
- a data model example with GraphQL or REST.