Contentful Localization: Where Multilingual Content Breaks
In Contentful, multilingualism is a property of the model, not a separate module: each entry field is either localizable or shared across all locales.
The first failure grows precisely from this—the title and body are marked as localizable, while part of the URL, the cover image and meta fields remain shared. The English version opens, but its URL and preview are Russian: this is no longer a translation but a mix of languages.
Next comes translation desynchronization. An editor edits text in the default locale, the translation is updated manually and lags behind; the more frequently edits ship, the wider the divergence, and a month later no one can say which version is current.
The fallback locale masks the problem: the visitor sees substituted default-language text and doesn't understand why half the page is foreign.
A separate story is duplicate entries.
If localization wasn't configured from the start, the team creates an entry per language and links them manually: links break on the first rename, assets are duplicated, the registry grows faster than the content, and two versions begin to conflict on the same URL.
On top of that sits the language switcher.
It is built from the list of locales in the space, not from whether a translation actually exists, so clicking another language leads to an empty page or a broken version URL—part of the URL is not localized, and the route was assembled from an old template. Below we examine how this is addressed at the model, routing and build levels.
What Managed Website Multilingualism Delivers
A language version is not a copy of a page but a separate entry with a locale and a fallback rule.
When the version scheme is described in the content model, not in templates, the editor fills a page in a new language using the same fields as in the default one, and the developer does not migrate markup manually.
In Contentful, locales, relationships between versions and change history live in a single repository—hence the manageability.
Four effects visible in metrics.
- Page release time. A new language is assembled from ready blocks: text is translated, structure and components are reused. Instead of deploying a separate copy with its own layout—publishing a locale in the same tree.
- Volume of manual edits. Fallback is configured per field: an empty translation shows the default language value. The section opens without waiting for a full translation, and text edits do not diverge across copies.
- Failure class. Language URLs and relationships between versions are built from data, not manual lists. Eliminates the typical failure when after release some locales serve the default language or lose a page.
- Share of foreign traffic. A visitor lands in their own language on the first visit and stays in it. The share of visits to the local version and page depth grow because there is no need to switch languages manually.
The version scheme also sets the workflow: a new locale is enabled by configuration, not as a separate project.
Contentful Localization Models: Comparing Options
Contentful stores language versions in two different ways: field-level translation within an entry or a separate entry for each language.
Localization models differ not only in storage—the URL scheme, fallback for missing translations and editor permissions depend on them, and changing the model mid-project requires more effort than choosing at the start.
| Option | When it fits | Limitations |
|---|---|---|
| Language as an entry field | The set of fields is the same for all languages, translations are published synchronously | One schema for all languages: a field for a specific market cannot be added, per-language permissions cannot be assigned |
| Separate entry per language | Markets have their own fields, their own publication dates and their own relationships | Cross-language relationships are duplicated manually and desynchronize, content volume grows proportionally to the number of languages |
| Separate space per language | Isolation is needed: own models, permissions and an independent release schedule | The schema is synchronized manually, media is duplicated, cross-language search does not work |
The model choice is driven by three factors: whether schemas diverge between markets, who is responsible for publication, and how many languages are planned for the coming year.
The model then determines fallback behavior: with field-level localization, a missing translation returns the default locale per field individually, while with separate entries, cross-language relationships have to be maintained manually.
Stages of Implementing a Multilingual Framework
A multilingual framework breaks not on translations but on the data model: until a locale is built into the structure, every new language turns into manual entry duplication and version divergence. Below are six steps, each relying on the previous one, so rework does not surface midway.
- Content model audit. We review Contentful content types and fields: where there is text, where there are references to other entries, where values are hardcoded in a template. We mark fields required for translation and those shared across all languages—images, integration keys, service values.
- Language scheme design. We fix the list of locales, the default locale and regional variants with unified codes. Separately we decide whether right-to-left writing variants are needed and how this affects layout—mockups and line length depend on it.
- Fallback rules. We define the chain: no translation—take the regional variant value, then the default locale. We determine fields where fallback is acceptable and those requiring full translation, otherwise foreign text will surface on the storefront.
- Configuration and connection to rendering. We bind locales to URLs, add language alternates for search engines, the switcher and metadata. Shared elements—menu, footer, date and number formats—are translated with dictionaries, not duplicated entries.
- Switching checks. We run all routes in each locale: empty fields, broken links, truncated buttons, cache behavior and indexing. We review not only the homepage but also cards, forms and error pages.
- Acceptance and handover. We hand over a checklist for adding a locale, guidelines for editors and a list of required fields. After that, a new language is added according to the instructions, without code changes.
What We Hand Over After Implementation: Configurations and Policies
We hand over not a set of scattered settings but a working model of multilingual content: each artifact has an owner in your team and a clear change procedure. Below is what remains with you after launch and the points by which the engineer accepts the work.
- Language configuration. List of locales, default language and fallback chain "language-region → language → default": an empty field shows meaningful text, not an empty block in the layout.
- Entry relationship schemas. A map of content types and references between them: what is translated as a separate entry and what remains shared (images, reference data, characteristics). Separately—how relationships do not break when adding a new language.
- Draft access policies. Roles of translator, editor and developer, permissions to preview unpublished content, and a prohibition on publishing to the main channel for external authors.
- Translation release policy. The process "draft → proofreading → publication", the person responsible for approval and the rule for partially translated materials.
- Routing rules. Formation of URLs by language, redirects from old URLs, visitor language detection—at the application router level.
- Automated completeness checks. A build-time task reports a locale with empty required fields: a missed translation does not reach the user.
- Documentation. A map of content models, editor instructions, a role and access token scheme.
- Handover and support. A record of discussions of disputed points, a publication log and a channel for questions after launch.
Describe the task—we'll come back with an estimate and plan, including a list of artifacts for your setup.
Case: 12 Languages and Growth in the Share of Foreign Traffic
What It Was Before
Content for each language was stored in a separate table, and UI strings were placed directly in components.
A new locale meant edits in four dozen files, and none was linked to the others: the translation arrived later than the layout, and we manually checked that no empty blocks remained.
A missing key was returned as an empty string—the user saw a hole in the markup instead of English text.
Release time for a language version was about three weeks: half for edits, half for regression checks.
What Changed
Content moved to Contentful, localizable fields are described at the model level: an entity has one set of fields and values by locale, not parallel copies of entries. The fallback chain is set explicitly—if there is no Polish text, English is returned.
The build generates a static page for each locale, and language alternates and the sitemap are generated from the same list of locales. Dictionary completeness checking is built into the build: an incomplete translation blocks the merge and does not reach users.
What Became
Release time for a new locale is two days: the translator works in the editor interface, the developer connects the route and fallback. The volume of manual edits during a language release fell by about eight times—key reconciliation was removed from the process.
The error class "empty block instead of translation" is structurally closed. The share of foreign visitors grew from 4% to 19% after the first six languages and to 27% by twelve.
What to Do If Content Is Already Translated but the Language Scheme Is Changing
Partially configured multilingualism in Contentful is the most common case: two or three locales are set up, some fields are localized, some are pulled from the default via fallback, and the language code is hardcoded into the route.
Changing the language scheme here is not "toggling a setting" but a data migration: each entry's set of localized fields and relationships changes.
We start with an inventory: which content types are actually translated, where a translation lies in a non-localizable field, which locales are enabled but empty, and what fallback chain is currently used.
Separately we review reference fields and media links—when the schema changes, these are what break, not the texts.
We perform content migration with a script via the Management API: export entries with all locales, map old language codes to new ones, and write back.
We work on a copy of the environment; the script is idempotent and restartable: first we migrate reference data, then the content that references it. Before the run we capture a snapshot—it also serves as a rollback point.
We preserve URLs through a locale-to-route mapping table, not through a language code in the path. Old paths continue to respond with a permanent redirect, and new ones are added alongside—external links and search results are not lost.
The main transition risk is silent empty fields: after the fallback chain changes, an entry builds but returns emptiness.
Therefore we build the chain explicitly, run the build and cache invalidation before switching, and change the schema itself in one pass so as not to remain in a half-transitioned state.
Technical Doubts About the Multilingual Scheme
When agreeing on the scope of work for Contentful localization, the same five decision points come up repeatedly. We answer them before the start—so that disputed points do not surface in the middle of implementation, when it is already too late to change the decision.
What should be shown in a language where there is no translation yet?
For each field we define a source language. An empty value does not leave a hole in the layout: the visitor sees meaningful text, and fallback works at the field level—a partially translated page remains intact.
What about page URLs in each language?
We build URLs from the localized title or keep a stable neutral URL with a language prefix. The second option has lower maintenance overhead: links don't break when text is edited, and redirects are needed only when the structure changes.
Is it mandatory to translate all fields at once?
No. We divide fields into required-to-translate and auxiliary—service labels, technical descriptions, default values. Partial translation shortens the first stage, and completeness is visible in the language report.
Will multilingualism slow down the build?
The build runs only for changed languages and fields; everything else is taken from cache. Adding a language adds seconds, not minutes—if the content schema was designed in advance rather than patched onto ready-made pages.
Who is responsible for translation quality?
We are responsible for the schema, fallback, URLs and build. Texts are on the side of the client or their translator; on our side we provide a glossary, a list of required fields and a gap report so omissions are visible before publication.
Let's Discuss the Task: Language Scheme, Timelines and Work Order
To come back with a timeline estimate and implementation plan rather than generalities, we need input data: the list of locales and their priority, who translates and who publishes content, the current schema of types and fields, and how language routing is arranged in the application. This forms the scope of work, and from it we calculate timelines by stage.
We structure the work order so that each step relies on a verified previous one:
- fix the locale scheme and fallback chains: which language is substituted when there is no translation, and what the user sees;
- adjust the content model: where a field is localizable, where it is shared, which relationships cannot be duplicated by language;
- configure language switching and page URLs, including correct metadata for search engines;
- describe editor roles and publication order: who translates, who reviews, and in what order a locale goes live;
- catch incomplete translations, mixed languages within one document and cache behavior when a locale is updated;
- hand over documentation: locale scheme, field conventions and editor instructions.
Each item receives a separate estimate, so part of the scope can be closed in stages—for example, first two locales, then the rest. Describe the task and current content state—we'll come back with an implementation plan, scope of work and timelines.
