# Building a Multi-Locale Publishing Workflow with a Headless CMS > Advanced guide to multi-locale content architecture in a headless CMS: locale routing, translation workflows, fallback strategies, and preview per locale. - **Published:** 2025-08-15 - **Author:** Clixo - **Reading time:** 6 min read - **Tags:** headless-cms, localization, multi-locale, publishing-workflow - **Canonical URL:** https://clixo.sh/blog/multi-locale-headless-cms-publishing-workflow Supporting multiple languages in a headless CMS is not just a matter of toggling a localization setting and calling it done. Teams that treat it as an afterthought spend weeks untangling slug conflicts, missing translations, broken preview environments, and inconsistent fallback behavior across locales. The complexity compounds with every locale you add. This is a guide to designing a multi-locale publishing workflow from the ground up, covering the decisions that matter before you write the first field. ## Define Your Localization Strategy Before You Start The first decision — and the one that is hardest to change later — is *how* content is localized. There are two primary models: **Single-document localization:** One document per piece of content, with locale variants stored on individual fields. A `title` field becomes `title.en`, `title.fr`, `title.de`. The CMS handles the locale projection in the API. **Separate documents per locale:** One document per locale per piece of content. An English article and a French article are two separate documents, linked by a `translationGroup` or equivalent reference. **Tradeoffs:** - Single-document localization is easier to manage for content that is structurally identical across locales — same fields, same media, different text. - Separate documents per locale gives more flexibility when different locales need different structure, different media, or different related content. It also makes it easier to track translation completeness. Most headless CMS platforms (Sanity, Contentful, Hygraph) support both models. Pick based on whether your content is structurally homogeneous across locales or whether different markets need meaningfully different content experiences. ## Design Your URL and Slug Architecture Multi-locale sites require a clear URL strategy before any content is created: - **Subdirectory:** `example.com/en/blog/post-slug`, `example.com/fr/blog/post-slug` - **Subdomain:** `en.example.com`, `fr.example.com` - **Domain:** `example.com`, `example.fr` Subdirectory is the most common choice for product sites because it consolidates domain authority and is easiest to implement with Next.js `i18n` routing. Slug localization deserves its own attention. An English slug like `how-to-build-a-content-model` should not be the slug for the French version — `comment-construire-un-modele-de-contenu` is correct and better for SEO. Design your schema to store locale-specific slugs rather than sharing slugs across locales. ## Configure Locale Fallback Behavior Translations are never fully complete — editors finish English first, French is in progress, German is planned for next quarter. Your system needs a defined fallback strategy for when a requested locale does not have a translation. Common fallback strategies: - **Fallback to default locale:** Show the English content if French is missing. Clear and predictable, but can confuse users who see content in the wrong language. - **Fallback to partial content:** Show translated fields where available and default-locale content where not. Works well for short content but breaks for long-form articles. - **No fallback:** Return a 404 or a "not available in your language" page. Most honest, but requires complete translation coverage before content can be published. Define this per content type. Navigation and global site content usually needs to be fully translated before it appears. Blog posts might reasonably fall back to the default locale. ## Build Translation Completeness Tracking At scale, manually tracking which content has been translated is not sustainable. Build tracking into your content model: ```mermaid flowchart LR A["Author (default locale)"] --> B[Content published] B --> C[Webhook fires] C --> D[Translation task created] D --> E["Translator drafts locale version"] E --> F[Review and approve] F --> G[Locale version published] G --> H["hreflang tags updated"] ``` - A `translationStatus` field per locale — `draft`, `in-review`, `published` - A webhook that fires when content is published in the default locale, triggering a notification to the translation team - A dashboard view or filter in the CMS admin that shows untranslated content per locale Sanity and Contentful both support custom dashboards and computed fields that can serve this purpose. Payload makes it straightforward to add custom admin views. ## Implement Per-Locale Preview Your live preview setup needs to be locale-aware. A French editor previewing a French article should see the French frontend, with the French slug in the URL and the French locale applied to all shared content (navigation, footer, global labels). In Next.js, Draft Mode is locale-aware as long as your `[locale]` route segment is part of the preview URL. The preview API route needs to accept and pass through the locale parameter: ``` /api/preview?secret=TOKEN&slug=/fr/blog/mon-article&locale=fr ``` Configure your CMS's preview URL to include the locale dynamically — most platforms allow this in the preview URL template. ## Handle Locale-Specific Media Not all media is locale-neutral. Product screenshots may show UI in a specific language. Photography may need to reflect different markets. Legal documents are locale-specific by definition. Design your media fields to support locale variants where necessary. In Sanity, you can use conditional fields to allow locale-specific image overrides. In Contentful, the localization system applies to asset fields the same way it applies to text fields. Avoid the common mistake of using the same images everywhere and then discovering six months later that German marketing wants different visuals than the US site. ## Set Up Locale-Aware SEO Fields Every SEO field needs a locale-specific value: - `title` and `description` are obviously locale-specific - `canonicalUrl` needs to reflect the correct locale URL - `hreflang` tags need to be generated from the available locales for each document - `og:locale` needs to match the content locale The `hreflang` implementation is frequently missed. For every page that exists in multiple locales, the HTML head should contain `link rel="alternate" hreflang` tags for every available locale plus an `x-default` fallback. These are generated dynamically from your CMS data, not hardcoded. ## Publishing Coordination Across Locales For product launches or coordinated campaigns, different locale versions may need to go live simultaneously. A press release needs to publish in English, French, and German at the same time — not sequentially. Content release features in Sanity and Contentful support this: group multiple documents into a release, set a publish time, and all documents go live together regardless of which locale they belong to. For teams without this feature, scheduled webhooks triggered by a deployment pipeline can coordinate simultaneous publication across locales with some additional engineering. ## Test Before Adding Each New Locale Adding a locale to a running site is not a low-risk operation. Before enabling a new locale in production: - Verify all required fields have locale-specific values in the CMS - Test the locale URL routing with real slugs - Check that fallback behavior works as designed for partially translated content - Verify `hreflang` tags are correct across the existing locales - Run a full smoke test on the editorial preview for the new locale --- Multi-locale content architecture done right is largely invisible — editors publish efficiently, users see content in the right language, and adding the next locale is a configuration change rather than an engineering project. If you are building a multi-locale content system and want experienced engineers on the design and implementation, [Clixo builds content infrastructure for product teams](https://clixo.sh/#contact). --- Clixo · 1141 W Bryn Mawr Ave, Itasca, IL 60143, US · [hello@clixo.sh](mailto:hello@clixo.sh) [Start a build](https://clixo.sh/#contact) · [All services](https://clixo.sh/services) · [Agent guide (llms.txt)](https://clixo.sh/llms.txt)