A Contentful page may look translated in the editor and still show English on a French or German website. When people search for Contentful locale fallback , Contentful missing translation , Contentful localization API , or locale-based publishing , they usually need to know which text an API actually returns and why. The fastest useful answer is not to retranslate the paragraph. It is to locate the exact field, locale, fallback rule and publishing state that produced the visible result.
This guide explains how to diagnose a Contentful translation that is missing, unexpectedly replaced by a fallback, or not visible to a public visitor. Its single reader job is prove where one localized field came from and whether that field should be delivered publicly . The examples use a fictional school information website with English, French and Swiss German pages. The same investigation works for catalogs, course pages, help articles and other projects that read structured content from Contentful.
A quick Contentful localization QA workflow checks the space and environment, confirms the requested locale code, inspects whether the field is localizable, compares the raw values with a localized delivery response, and then verifies the relevant publication rules. Only after those steps should a team inspect caches, templates or SEO. That order matters: a polished translation is not a repair for a request that never asked for its language.
On this page
Quick answer: distinguish what exists from what is delivered
The reliable sequence is editorial value → field localization setting → requested locale → fallback chain → locale publication status → API response → rendered page . Each arrow is an opportunity for the wrong assumption. An editor can say that de-CH copy exists because it is visible in an entry; the consuming website might be querying de-DE, requesting the default locale, or displaying an old cached response. A content model can also mark the field as shared, making a language-specific value impossible by design.
Begin with one representative entry and one field. Record its entry ID, environment, content type, field identifier, intended target language and approved target sentence. Retrieve that field from the relevant API. A comparison that specifies IDs and locale codes can be repeated; a screenshot with no environment or URL cannot explain much. Do not modify the live entry simply to prove a point. Read first, save the output safely, and ask an editor to change content only when the evidence identifies an editorial defect.
Why fallback exists, and why it can mislead a reviewer
A multilingual site cannot always publish every sentence in every region at the same instant. Contentful therefore supports fallback locales: when a requested field has no value in one locale, delivery may use a configured alternative. Swiss German might fall back to standard German, and standard German might fall back to a source language. This prevents a missing paragraph from becoming a blank area, but it can also hide incomplete translation behind a page that appears healthy.
The key distinction is content resolution versus translation completion . A resolved value is merely a value the delivery layer could find. It does not certify that the field was written for the requested audience. A French page containing one English call-to-action may technically load successfully while failing the editorial promise of a fully French experience. QA should record both the requested locale and the language of the resolved text; otherwise the team may mistake graceful degradation for full readiness.
Build a locale map before inspecting individual entries
Start with the space’s supported locale codes. Record the display name, exact code, default marker and fallback target for each locale. Do not replace codes with flags or country names in working notes: fr-FR, fr-CA and fr are not interchangeable routing strings. A language is a linguistic category; a locale also establishes regional expectations. If the business intends Canadian French, a request for France French may return a grammatically fluent but commercially unsuitable version.
Next record which environment the website uses. A staging entry in one environment does not prove that the same content or locale configuration exists in production. Keep an explicit comparison such as production / fr-CA / entry 412 / productSummary. This modest discipline prevents elaborate investigations of a translation that was added to the wrong environment or was never moved through the team’s release process. It also gives developers a precise reproduction case.
The default locale is not a universal rescue language
Contentful has a default locale, used when a delivery request does not specify another locale. Separately, fallback relationships are defined for individual locales. Do not assume every missing translation inevitably falls back to the space default. A locale may have a designated fallback, a multi-step chain, or no usable fallback for a field. The correct behavior depends on the actual configuration and whether values are present at the examined positions.
Consider a fictitious de-CH → de-DE → en-US chain. If a Swiss German subtitle has not been supplied, the German version can appear. If neither German variant contains that field, the English version may appear if the chain and API behavior permit it. An editor who sees German text should ask whether it is Swiss-approved text or a German fallback. One delivered sentence can be acceptable temporarily, but a release report should not silently relabel it as a completed Swiss localization.
Confirm that the field is actually localizable
Contentful supports fields whose values vary by locale and fields that stay shared. The distinction is stored in the content-type definition, not inferred from the field’s display name. A title or article body usually benefits from localized values. A nonlinguistic identifier, immutable SKU, calculation flag or internal relationship may deliberately remain shared. Teams waste time when they expect a nonlocalized field to change with locale=fr-FR, or when they duplicate shared data just to make a translation test pass.
Review the field configuration before copying text into another entry. If a call-to-action label was modeled as a shared field, changing the source label could affect all languages. That is a modeling decision requiring deliberate coordination, not a routine translator edit. Record the content type, field ID and localization flag as part of the issue report. It is more useful than reporting only that the button appears in English.
Understand the two views of the same entry
The Content Management API is useful for seeing values maintained under their locale keys; delivery interfaces resolve the value intended for consumption. They answer related but different questions. A management response might show that en-US and fr-FR values were entered. A delivery request for fr-CA might legitimately provide a French fallback value rather than a separately authored Canadian one. Reading only one view confuses editorial existence with public resolution.
For investigation, compare an editor-visible source of truth with a production-like read through the Content Delivery API or the GraphQL Content API used by the application. Use credentials appropriate for read-only inspection and avoid pasting access tokens into public bug reports. Explicitly identify the locale parameter or API field argument. A response with no locale chosen may simply return the default version, which is not proof that fallback failed.
Use a three-column provenance ledger
A compact ledger is more useful than a large export. For each checked field, write: requested locale , stored locale value , and value observed by the visitor . Add a fourth column for the diagnosed origin if the observed text came from a fallback. The ledger forces reviewers to separate the language a user requested from the language a CMS had available. It also identifies which entries are awaiting real translation even though pages are visually populated.
For example, the row fr-CA / no separate value / French sentence identical to fr-FR / fr-FR fallback documents a deliberate or accidental substitution. A second row fr-CA / approved Canadian safety notice / old French notice visible / stale cache suspected directs investigation elsewhere. Without provenance, both rows get the unhelpful label “translation wrong.” With provenance, the first is a localization completeness decision and the second is a delivery freshness defect.
Worked example: an English course title on a French page
Imagine a school website whose French course page displays Mathematics Revision Programme in the hero but French body paragraphs underneath. The team finds that the hero is a reference to a separate CourseCard entry. The main Page entry has an approved French title, but the referenced card does not. The site is not inconsistently translating one field; it is rendering two independently managed records with different localization completeness.
A useful test requests the page and then its referenced card under the intended locale. Record each entry ID and field. If the card’s French title is absent and a fallback supplies English, create a translation task for the card. Do not overwrite the page title again. After the editor supplies the missing value and the relevant content is published, test the same public path. This example shows why one successful language check at the top-level entry cannot certify all referenced content.
Worked example: Swiss German quietly becomes standard German
A site offers a German-language course description for Switzerland. A parent notices the phrase used for a school grade is familiar in Germany but not in the intended Swiss context. The API has returned the de-DE text because de-CH was incomplete. This is not necessarily a software defect; it can be the consequence of an intentionally configured fallback chain. But its acceptability is an editorial question with local consequences.
Record the regional differences that matter: school-year labels, currencies, contact hours, address formatting, qualification names, and any legal or administrative terms. Prioritize these fields for market-specific writing rather than accepting every generic fallback. A team that reviews only spelling may miss a substantial change in meaning. The efficient remedy is to translate or adapt the high-consequence Swiss fields first, record the approved exceptions, and leave harmless shared descriptions to the agreed fallback policy.
Missing value, empty string and null are not identical
A missing field value, a deliberately blank string and a null value can behave differently. Contentful’s localization documentation explains that fallback is associated with a locale value not being set; values supplied as empty strings or null through management APIs can prevent fallback rather than invite it. The editorial interface may handle blank inputs more conservatively, which makes the distinction easy to overlook when integrations write directly to the API.
A developer investigating an empty call-to-action should inspect the actual stored representation. Do not simply assert that “blank means fall back.” If an integration wrote an empty target string to signal incomplete work, it may have created the opposite behavior from the intended fallback. Fix the integration’s missing-value convention in a controlled test, then verify the delivery response. Treat deletion and overwriting as changes requiring normal review, because they can alter content visible in multiple markets.
Trace fallback chains without guessing their end point
A fallback chain is a sequence of configured locale relationships, not a translation algorithm. It does not choose whichever language sounds closest. It follows the locale graph. When a value comes from somewhere unexpected, inspect every step in that graph and record whether the specific field was present. An editor may think es-MX should use es-ES, while the configured chain actually points to en-US or terminates without another value.
Use one miniature test entry containing distinguishable phrases in each locale, such as Source EN, Spanish Spain, and Spanish Mexico. Request one locale at a time in a safe environment and compare outputs. The goal is to establish what the current system does, not to create a giant matrix of hypothetical combinations. Once the fallback behavior is verified, use that known rule to interpret real content. If the configured chain violates editorial policy, escalate configuration changes rather than hiding the discrepancy in translation notes.
Locale-based publishing adds a second visibility question
Contentful added support for the X-Contentful-Locale-Based-Publishing: true request header to the Content Delivery and GraphQL Content APIs on June 15, 2026. In setups that use locale-based publishing, the header makes delivery respect per-locale publication status. A translated value may exist yet remain unpublished for that locale. With the opt-in behavior described by Contentful, a request for an unpublished locale can produce a 404 through CDA or a null result through GraphQL, rather than showing a language version that is not ready.
This matters because fallback alone cannot decide whether content is publicly releasable. A published fallback locale does not automatically authorize an unpublished requested locale. Record whether the application sends the header and whether the space uses locale-based or entry-level publishing. Do not conclude from a staging preview that a draft is available to ordinary visitors. Repeat tests against the same delivery mode used in production, with all secrets and customer records protected.
A safe comparison for publication modes
Construct a test table with one entry and two target locales: one published, one deliberately left unpublished. Query through a preview channel that is authorized for editors, then through the public delivery channel. When relevant, compare behavior with and without the locale-based-publishing header in a controlled environment. The expected result is not always identical across accounts and release configurations, so record the observed status code, API response and publication field state rather than memorizing one universal rule.
This test guards against a dangerous shortcut: seeing translated words in an internal preview and treating them as publicly approved. A preview proves that content can be retrieved with editorial permissions. A public response proves a different fact. Because teams often launch languages asynchronously, publishing must be a separate checkpoint from translation completeness. Review the specific locale’s approval record before correcting anything in production.
Why newly added locales can surprise a release team
Adding a locale to a Contentful space changes what the content system can represent, but it does not necessarily make every existing entry immediately deliverable in that language. Contentful’s locale-based publishing documentation notes that affected entries may need republishing before a newly added locale appears in CDA responses. That is easy to miss if a project begins by creating the locale, entering several translations and then testing only through an editorial channel.
Before escalating a supposed missing translation, ask when the locale was added and whether the relevant entry or locale has been published under the team’s chosen publishing model. Separate the action “add target language” from the actions “write translation,” “approve target content,” and “release target locale.” Each has a different owner. The fastest diagnosis is often finding which of those events has not happened, not reopening a complete translation for another round of wording edits.
Understand published content in referenced entries
A page can be published while a related promotional card, testimonial, image caption or navigation entry remains a draft or lacks an approved target value. Such references create mixed-language layouts that appear random until each record is checked separately. Build the smallest content graph that reproduces the symptom: page entry, referenced components, required assets, and any nested reference directly contributing the visible text. There is no reason to export the entire space to investigate one broken card.
If the card is the failure point, identify whether its target translation is missing, unpublished, or retrieved without the locale parameter. These defects require different owners. A writer supplies missing copy; an editor handles approval; a developer fixes query propagation. Document the graph boundary, not merely the visible string, so subsequent updates do not reintroduce the same mixed-language result through another component.
Images can contain embedded English words, locale-sensitive diagrams, dates or classroom terminology. In Contentful, asset fields can participate in localization strategies, but the actual visibility of language-specific media depends on the content model, asset handling and frontend rendering. A page may request French text yet reuse an English poster because the corresponding image reference or metadata did not vary by locale. A correct French caption cannot erase the words inside the image itself.
For each important visual, inspect whether the filename, alt text, caption and visual content are meant to differ. Record the license and editorial approvals as well as the translation status. If the art cannot be replaced immediately, prefer a clearly documented temporary solution over implying that the entire page is fully localized. Test alt text with assistive technology or its accessible representation; a visible screen check will not detect all language errors in nonvisual content.
Do not translate identifiers or accidentally localize prices
Contentful’s flexibility allows teams to mark many field types as localized, but not every piece of structured data should become a separate language value. A product ID, fixed booking code or enrollment record identifier often needs to remain stable across languages. Conversely, a displayed currency label or regional fee explanation may need a localized expression while the underlying numeric fee follows a different business rule. Mixing these concepts can produce a bilingual page that looks polished but shows the wrong price.
Before altering a model, distinguish stable system identity, regional business configuration and human-readable copy. If a translated label says “per term” where the actual billing interval is monthly, the problem is factual, not stylistic. A translator should flag it instead of repairing the data secretly. The appropriate owner must confirm the commercial fact; then the translated field can express it. Translation QA protects relationships and numbers as well as words.
Test locale propagation across application routes
A website can obtain a localized landing page correctly but issue secondary API requests without its locale parameter. The first hero paragraph then appears in French, while related cards arrive in English from default-locale delivery. Verify the language passed into every content query used to assemble the route. Record how the application derives that language from the URL, user setting or site routing rules. Do not assume a language selector automatically updates all data-fetching functions.
A small network trace is often enough. Open a target-language URL, inspect the content requests it triggers, and compare locale parameters and returned entry IDs. If one component is wrong, fix its locale propagation and rerun a localized smoke test. Avoid rewriting all cards as separate documents merely to compensate for a missing parameter. This distinction saves editorial work and preserves a coherent content model.
Caches can preserve an already-fixed error
When the stored target translation is correct and the API returns it in a fresh request, but the website still shows old source-language text, investigate the delivery cache and page build. Contentful may feed a server-rendered site, a static build, edge cache or application-level query cache. Each can make a language change appear ineffective. In particular, the cache key must distinguish locales: a response cached for English should not be reused as if it were the French response.
Compare a known-fresh API call with the public URL and note timestamps or deployment identifiers where available. Check whether a rebuild, cache invalidation or webhook is expected after publication. Clear or invalidate only the appropriate entry and locale scope through established procedures; indiscriminate purges can disrupt unrelated content. This is a delivery diagnosis, not a reason to submit the translation again.
Search appearance needs its own localized fields
A translated body is not enough if the search result title and description remain in the source language. Identify where the application obtains SEO title, description, canonical URL, and the language-alternate information supplied in its HTML. These may be Contentful fields, frontend constants or a separate SEO content type. If the visible page is French but the description is English, first establish ownership of the metadata rather than changing the hero headline in the hope that snippets will follow.
Check the rendered page source for its actual language tag, alternate language URLs and canonical decision. Search engines do not simply obey an editor-side locale label. Use Google’s documentation for localized versions when deciding hreflang relationships, and avoid linking a locale to a URL that is not actually published. The reader job here remains narrow: prove which Contentful translation reached the page, including the metadata that describes it.
The fastest troubleshooting matrix starts from symptoms
Different symptoms point to different layers. If every field appears in English, inspect the requested locale and its route mapping before anything else. If only one field is English, check that field’s localized flag and value. If several nested cards are English, inspect referenced entries and locale propagation. If a public page is absent but editors see the translation, check locale publication and delivery permissions. If the API is correct but the page is wrong, investigate rendering, cache and build state.
Write each symptom as an observable statement: “Public fr-FR page displays the English summary; direct CDA response with explicit fr-FR returns the approved French summary.” That sentence contains enough evidence to focus the developer on the consumer layer. A vague report such as “Contentful French broken” invites repeated translation work and unproductive debugging. Good localization QA is a method for shortening the path from symptom to responsible layer.
Failure mode: wrong environment and convincing screenshots
An editor may post a screenshot from a staging space to show the correct translation. The production website reads a separate environment where the change is absent. Both observations can be true. Names such as master, staging or production are deployment conventions; record the exact environment identifier connected to the live website rather than relying on labels in conversation. If environment aliases are in use, confirm their current target under the team’s release controls.
The practical check compares entry ID, revision or updated time, target locale value and publication state in the two environments. Move content through the normal release process when an environment mismatch is confirmed. Do not copy a sentence directly into live content just to make a screenshot agree. That can bypass reviews, break relationships and create divergent versions that are harder to maintain at the next update.
Failure mode: the right language, the wrong regional promise
A general French fallback may correctly translate the words “registration closes Friday,” but the deadline, timezone or eligibility conditions might differ for the Canadian audience. Mechanically resolved content can therefore be wrong even when its grammar is flawless. Contentful will not infer that regional policy changed. The localization model must preserve the distinction between language copy and market-specific business facts supplied by an authorized owner.
When a regional claim is important, make it a release-blocking check. Compare the translated display with the approved regional source data for date, amount, audience and legal meaning. If no market-specific version exists, label the state incomplete and ask the business owner whether fallback is permitted. Do not silently “correct” facts in the translated sentence; doing so can make translations diverge from authoritative records and hide who approved the promise.
Failure mode: duplicate entry rather than a language variant
Some teams resolve translation difficulty by copying the entire entry and changing its title. This can work under an intentional entry-level localization architecture, but it is a different strategy from using localized fields within one entry. Unplanned duplication can detach language versions, break references and confuse publishing. Two entries with similar titles are not automatically a legitimate multilingual pair.
Inspect the chosen localization strategy before adding a duplicate. If the project uses field-level localization, verify whether the target text belongs under the same entry’s locale key. If it uses entry-level localization, verify the relationship that joins versions and the page lookup logic. Changing strategies midstream to fix one missing field creates a larger class of errors. Treat modeling changes as design decisions with downstream query and governance consequences, not as quick copywriting corrections.
Failure mode: fallback masks ongoing translation debt
A site may run for months with many target-language fields falling back to English. Because pages load and no obvious broken layout appears, the backlog becomes invisible. The short-term benefit of fallback turns into a false completion signal. A translation QA report should therefore count values resolved from the requested locale separately from values resolved through fallback. This is about editorial coverage, not about banning fallback outright.
Group uncovered fields by business impact. Safety notices, registration instructions, fees and consent wording require higher priority than low-traffic archival labels. Record owners and review dates for temporary exceptions. A small weekly dashboard showing high-risk fallback use can be more effective than a huge once-a-year translation audit. The aim is to keep a graceful delivery behavior from becoming a permanent substitute for the localization work the organization promised.
Worked example: release English now, French next week
A team publishes an English school admissions notice on Monday and plans the French version for Friday. Field-level translations may exist in the same entry before French approval. If locale-based publishing is configured, the intended state is that the English version is public while French remains unpublished. Testing only the editor’s preview would miss the distinction. The release test must exercise the public API under the same locale-publishing behavior as the live site.
Create an approval record identifying the translated notice, its locale, reviewer and target release day. Before Friday, verify that the French public route does not expose unapproved copy. After approval, verify that the French route returns the approved target field and correct related entries. The method is not “publish everything and hope fallback takes care of it.” It is coordinated language release with explicit evidence for what users could read at each stage.
Worked example: a new subject field arrives late
A content team adds a short coursePrerequisites field after German and French translators finished the main article. The field is localizable but has only the English value. The page still loads in both languages because fallback provides the missing text. Later, users misunderstand the requirement because an English examination label is unfamiliar to them. Translation quality of the existing body was never the problem; a content-model change introduced a new untranslated surface.
A good change process compares the content-type schema before and after each release and flags newly localizable fields for translation intake. The reviewer examines whether the field can be temporarily hidden, whether fallback is acceptable, and whether release must wait for approved wording. Keep this decision with the actual owner of the field. Otherwise new field additions generate recurring mystery defects long after translators believe an entry was complete.
Worked example: locale code and path disagree
A website route /fr-ca/courses/algebra looks like Canadian French, but the backend query passes fr-FR because the routing library normalizes both under the same general language selection. The page reads coherently in French and may pass a superficial visual review. Yet its enrollment terms, regional vocabulary and metadata are not the intended Canadian version. A browser URL is not proof of the locale parameter sent to Contentful.
Record the path-to-locale mapping in one place and test a representative page for each supported variant. Confirm that the API request, HTML language tag, navigation links and visible content tell the same regional story. Repair the mapping instead of cloning whole page trees unnecessarily. Then run a regression check for adjacent variants; fixing one path by hardcoding a locale may quietly break the other French audience.
A practical ten-minute inspection plan
Minute one: capture the broken public URL, expected sentence, browser language and exact time. Minutes two and three: identify the entry and field that supply the sentence. Minutes four and five: verify the locale code, field-localization flag and fallback chain. Minutes six and seven: compare management-side values with an explicit localized delivery request. Minute eight: inspect the publication status and any locale-based publishing header. Minutes nine and ten: compare the API output to the rendered page and classify any remaining mismatch as a consumer problem.
This is a triage order, not a guarantee that every issue takes ten minutes. Complex deployments may need more time. Its advantage is that it prevents a common detour: editing translation strings before checking whether they are the strings being requested. End the triage with a short evidence summary. A diagnosed owner and next test are more useful than a speculative fix applied without a reproduction case.
Make a release-ready comparison table
Use a small matrix for high-visibility content. Rows might include hero title, introductory paragraph, course requirements, price explanation, enrollment button, confirmation message, navigation label and metadata description. Columns should identify the source entry and field, requested locale, approved target value, API-observed text, public-observed text, and action owner. Record fallback only where it is allowed, and distinguish planned reuse from an accidental missing translation.
A matrix with eight carefully chosen surfaces can catch more consequential errors than mechanically reviewing hundreds of low-value labels. Choose fields that represent different ownership boundaries: direct page text, referenced component, shared field, asset caption and metadata. When one row fails, trace that row to its source rather than reopening the entire translation project. This produces faster and more informative feedback for editors and developers.
Practical check: content hierarchy and connected fields
A content entry often sits inside a hierarchy of landing pages, collections, cards and callouts. A translation can be present at the leaf but not accessible because the parent route does not include the item or a reference points to an older entry. Although Contentful can resolve localized field values, a frontend still decides which entries to query and display. Locale-sensitive relationships and filters must be tested at the point of consumption.
Choose one typical browsing path: category page → course card → detail page → enrollment information. At every step compare the displayed label with the intended locale, noting where each field originates. A direct detail-page URL that works does not prove that category navigation correctly exposes it. Conversely, a translated category heading does not prove that a related course card is ready. A route-based check catches failures that entry-level review cannot.
Keep source changes and target maintenance in sync
A translation may be accurate when approved but become stale after the source entry changes. Suppose the English instructions now require an identity document, while the French version still lists an older process. The published French wording can be perfectly grammatical yet operationally wrong. CMS localization QA therefore needs a change signal, not only a one-time publication stamp. Record which source changes are substantive and which are harmless formatting adjustments.
A sensible workflow routes high-consequence changes to the target-language owner for review before the update goes live in that locale. Compare key claims and steps, not just character differences. When revisions are frequent, create a short changelog of changed obligations, dates, numbers and calls to action. This gives the translator enough context to update quickly without rereading every unchanged section. It also prevents fallback from obscuring a stale but present translation.
Preserve placeholders, links and structured meaning
A localized Rich Text field may contain links, embedded entries, headings, inline references and variables. Treat these as structured relationships, not as decorative prose. If a translator changes a visible link label while leaving its destination pointed at an English-only page, the journey becomes inconsistent. If a percentage or enrollment deadline changes during translation, the reader receives a different instruction. Rich Text QA should therefore include the rendered relationships and not only plain-text comparison.
Test important links in the target locale and note when there is no approved destination. Do not fabricate URLs or redirect readers to arbitrary pages. Check numerals, placeholders, quoted policy terms and heading hierarchy in the rendered result. For user-facing content, the final unit of correctness is the page a person can act on, not simply the Rich Text JSON that an editor submitted.
Distinguish one-page QA from an entire-language audit
For a single page, the goal is to isolate the specific field and release defect and prove a fix. For a language launch, the goal broadens to representative coverage of templates, content types, fallback paths and region-critical fields. Do not attempt to certify an entire site from the behavior of one carefully translated article. Conversely, do not demand a site-wide audit before repairing an isolated missing button. Choose the smallest meaningful scope that matches the consequence of the issue.
Document which content families were sampled and why. A school site might prioritize admissions, fees, program descriptions and contact routes before archive news. An e-commerce team might prioritize checkout promises and returns. This is a risk-based selection, not an excuse to ignore quieter pages indefinitely. It keeps the inspection effort proportionate while preserving a clear record of what was and was not tested.
How to file a bug that a developer can reproduce
A useful report contains the environment, entry ID, content type, field ID, requested locale, expected value, actual delivered value, public URL, timestamp, publishing mode and relevant request details with credentials removed. State whether the management view contains the target value. If a fallback is involved, note the configured chain and observed origin. Screenshots can support this report, but they should not replace the identifiers that make an API investigation reproducible.
Avoid writing “translation tool unreliable” or “French missing everywhere” without evidence. Classify the layer: editorial content, model, locale configuration, publication, API retrieval, reference, frontend rendering or cache. A developer can then check the exact boundary. Add one acceptance criterion, such as “the public fr-CA route returns the approved Canadian fee explanation without using the fr-FR fallback.” That criterion allows the fix to be verified independently of who first reported it.
What translators should check without needing backend access
A translator may not have permission to inspect production APIs, and that is reasonable. They can still record the approved source and target sentence, locale code, related entry name, whether the problem occurs in preview or public view, and whether nearby fields are affected. They should flag ambiguous region-specific terms or factual discrepancies rather than modifying structured data to make the page look consistent. Their evidence helps the CMS owner reproduce the issue securely.
When the tool exposes fallback indicators or localization views, use them to distinguish authored target text from inherited text. Ask for a developer’s read-only comparison when the presentation is ambiguous. The important competence is not mastering every API; it is knowing which observation proves translation work is complete and which observation only proves that a page rendered something. That distinction cuts unnecessary translation cycles.
What developers should not ask translators to fix
A translator cannot repair an HTTP request that omits its locale parameter, a cached response keyed incorrectly, a field that was modeled as nonlocalized, or a deployment that reads the wrong environment. These are system behaviors. Asking for the sentence again may appear to create progress, but it leaves the original failure active. Developers should first identify the source field and consumer path, then communicate precisely when an editorial change is required.
Similarly, developers should not decide the target wording of regional policy while adjusting code. If they discover that the French fee explanation differs from the approved finance record, the right action is to raise a content accuracy issue with the responsible business owner. A disciplined separation of responsibilities saves time because it prevents edits by people who cannot verify the underlying fact or configuration.
Transfer the method to another headless CMS
The transferable idea is provenance. For any multilingual content platform, ask which text was authored, which locale was requested, which fallback or inheritance rule applied, which version was allowed into the public response, and which version the page displayed. Platform-specific fields and APIs will differ. The reasoning remains stable. It is the opposite of debugging by replacing words at random and hoping the symptom disappears.
To practise, imagine a translated admissions article that works at its direct URL but appears in English on a category page. List the records and requests you would compare before contacting a translator. A strong answer names the category’s card query, its locale setting, the referenced entry, the target field and the publication status. That reasoning applies even when the next project uses a different CMS with different names for each component.
Summary: fast localization QA proves origin and release state
Contentful fallback is a delivery rule, not evidence that a translation is complete. Diagnose one field by recording its locale, stored value, fallback origin, public publication state and rendered result. Treat missing values, explicit empties, wrong environment, unpublished locales, stale cache and regional policy differences as distinct classes of failure. The quickest reliable fix follows the first broken boundary, not the first English word a reviewer sees.
Frequently asked questions
Why does Contentful return English when I request French?
The requested field may lack a French value, its fallback may lead to English, or the request may actually be using the default locale. Confirm the explicit locale argument, field-localization setting and configured fallback chain.
Can an unpublished localized entry be previewed by editors?
Editorial preview and public delivery have different permissions and publication behavior. Test both channels using the deployment’s actual publishing mode rather than treating preview visibility as a public release approval.
Does a blank translated string always trigger fallback?
No. Contentful documents important differences between absent locale values and explicit empty or null values entered through an API. Inspect the raw field representation before changing it.
What changed with locale-based publishing in 2026?
Contentful documented opt-in delivery behavior using the X-Contentful-Locale-Based-Publishing: true request header on June 15, 2026. Under the described behavior, publication status for a requested locale matters separately from fallback content resolution.
Should every field be localized?
No. Translate human-facing content that genuinely changes by language or region. Keep stable system identifiers shared unless the content architecture specifically requires variants. Regional business data may need distinct governance from text localization.
How can I tell whether the problem is in the website rather than Contentful?
Compare an explicit localized API response with the publicly rendered page. If the API returns approved target text but the website does not, inspect route parameters, data transformations, build output and caches.
Is fallback bad for multilingual websites?
Not inherently. It can be a deliberate continuity mechanism. The danger is calling fallback content a completed translation or using it for market-sensitive instructions without approval.
Official sources and further reading
