Setting Up Multi-Locale Fallback Chains in a Headless CMS

You launched your site in English first and added French and German six months later. The translations are 80% complete, which means 20% of your pages show blank fields in non-English locales. A fallback chain fixes this: if a field has no French translation, ContentGrid returns the English value instead of null. Your site stays complete while editors catch up.

How Locale Fallbacks Work

ContentGrid stores a separate value for each field per locale. When you query a field with a locale specified, ContentGrid checks the field in that locale first. If the value is empty or missing, it walks the fallback chain until it finds a non-empty value. The chain is configurable per locale, so French can fall back to English while German falls back to French and then English.

• Primary locale: fr-FR — checked first.
• First fallback: en-US — used if the French field is empty.
• No second fallback needed for a two-language site.

For larger setups, you might have pt-BR → pt-PT → en-US to cover both Portuguese variants.

Configuring Fallbacks in ContentGrid

In the ContentGrid dashboard, go to Settings → Locales. For each locale you have enabled, you can set a fallback locale from a dropdown. The order matters — ContentGrid walks the chain in the order you define. Save the configuration and it applies immediately to all API responses.

You can also set this via the Management API if you manage your configuration as code:

• Send a PATCH request to /api/locales/fr-FR with a body containing { fallback: "en-US" }.
• Repeat for each locale that needs a fallback.
• Commit your locale config to your infrastructure-as-code repository so it is reproducible.

Querying Localized Content From Next.js

When fetching content from ContentGrid in your Next.js app, pass the locale from the router:

• Use params.lang (or router.locale in older setups) to get the current locale.
• Pass it as a header or query parameter to the ContentGrid SDK: client.entries({ locale: params.lang }).
• ContentGrid applies the fallback chain server-side and returns the best available value for every field.
• You do not need to write fallback logic in your application code — the API handles it.

Handling Locale-Specific Slugs

Slugs are a common edge case. If your French URL is /fr/produit/chaise-ergonomique and the English URL is /en/product/ergonomic-chair, they are different strings — fallback does not apply to slugs the same way. Store slugs as locale-specific fields and do not fall back. For pages with missing slugs, redirect to the English version at the router level rather than relying on CMS fallback.

Fallback chains are most useful for body copy, meta descriptions, and field values that are safe to show in another language temporarily. Slugs, dates, and currency values need locale-specific handling. The distinction keeps your content model clean and your URLs correct.