Webiny Headless CMS Localization and Multilingual QA

How do you translate Webiny Headless CMS content for an international audience without confusing language settings, editorial approval and what visitors actually see? This guide explains Webiny Headless CMS locales, generated GraphQL APIs and frontend translation delivery, starting with the practical route from a source claim to a reviewed target-language page. The central problem is not the difficulty of replacing words. It is ensuring that the right meaning, source revision and destination survive every system that carries the information.

If you need a Webiny Headless CMS multilingual website or localization workflow, begin with the quick checklist below. Then follow the examples, the technical decisions and the validation exercises to understand the difference between a configured language, a translated field, a reviewed item and a published visitor journey. These differences matter for worldwide readers, including people who depend on accurate dates, rules, accessibility labels and instructions before they can make a decision.

This practical Webiny Headless CMS translation tutorial is intended for developers, multilingual content editors and site operators. It covers Webiny Headless CMS locales, generated GraphQL APIs and frontend translation delivery with a worked example, release tests, common failures and links to official product documentation. It is a platform-specific implementation chapter, not a substitute for the larger subject of translation theory. Start with one real reader task and expand only after you can prove the result in an anonymous public browser.

Quick answer: a practical ten-step localization checklist

Confirm the software version, hosting arrangement and public frontend technology.
Identify the source language, target locales and responsible content owners.
Map which values are shared facts, translatable fields or regional policies.
Create a small test item and establish stable identity across languages.
Configure language or locale behavior using the documented workflow.
Translate complete reader journeys, including links, captions and forms.
Review claims, numbers, conditions and context against source evidence.
Compare editorial preview with published API or page delivery.
Test search, accessibility, route switching, caching and language metadata.
Release only approved language variants and preserve revision evidence.

A worked example: an international research library serving English, French and German articles through a public frontend while independent regional teams retain separate publishing responsibilities

Imagine an international research library serving English, French and German articles through a public frontend while independent regional teams retain separate publishing responsibilities. The team already has good information in its original language. New audiences need material that is natural to read and trustworthy enough to use. A software configuration can make a language available, but it cannot by itself decide which factual claims may be shared, which examples require localization or when an unfinished translation may go live.

The first useful artefact is a content map. Give every article or record an identifiable source and owner. Separate its stable data from descriptions that need a different language. Put dates, contact details and public actions in the map, even when they seem incidental. People often discover that a multilingual error is not a wrong dictionary choice: it is a page using an outdated source, the wrong market or the wrong linked destination.

Create a small Article model with source identity, factual content, an image description and a source-revision field. Populate one approved English entry and a linked French entry, then query each through its locale-aware Read API. Compare the Preview result with the anonymous published route, switch languages in the browser and confirm the same article is reached. Use a restricted editor account to prove that the French reviewer cannot publish the English source.

When the experiment works, resist turning its success into an unlimited claim. One translated item proves only that the tested content, locale, workflow and route behaved as expected. A public launch needs a repeatable standard for missing values, later revisions, fallback, search, assistive technology and who is allowed to publish. Use the chapters below to make those standards explicit and understandable to the people responsible for the site.

What counts as a complete translation?

A translated page is complete when the visitor can identify the subject, understand the same supported claim, see local adaptations clearly, follow each necessary link and act without being surprised by a different language. This includes visible headings, hidden accessibility text, captions, errors, menus and data supplied by external services. The test is not the number of translated words: it is whether the information remains useful and correct across the whole encounter.

A coverage matrix makes the answer concrete. Across the top place the intended languages and public routes. Down the side list the article body, title, media explanation, search result, navigation, form and important outbound references. In each cell record absent, draft, linguistically reviewed, factually reviewed or publicly verified. Distinguish deliberate reuse of universal facts from unintended English fallback.

Webiny Headless CMS localization in depth: 39 decisions and checks

1. Separate tenant and locale before designing

Webiny documents multi-tenancy as isolated content, assets, users and permissions. A locale is a language context inside a project, not automatically a separate customer or regional business tenant. Think about the ownership of the data before thinking about vocabulary. A shared fact should have one identifiable source; a local adaptation should have a named reason. Those are different editorial obligations.

An international charity runs several independent regional operations but publishes English and French within each operation. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Using tenants for every language without a business reason duplicates content structures and complicates cross-language editorial review. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Sketch the tenant boundary and the locale boundary on separate diagrams, then prove which content should be shared. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.

2. Understand content models and entries

Webiny Headless CMS uses content models for structure and entries for records. The platform generates GraphQL APIs from those models, but schema design still determines how usable multilingual content becomes. Readers do not see the content-management boundaries. They experience a continuous page, so the review must follow the visible journey rather than stopping at the field editor.

A research archive defines Article, Author and Topic models before its French and German editorial work begins. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

A weak model that stores everything in one rich-text field makes translation export, attribution and targeted updates harder. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Create one article and inspect the generated API shape before scaling to hundreds of records. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.

3. Register a second locale intentionally

Webiny’s published multilingual tutorial shows adding a locale under Languages and switching the selected locale in the administration interface. Confirm exact controls in the deployed version. Treat the source statement as a claim that can be checked, not a string that merely needs different spelling. Dates, conditions and scope must survive the move between languages.

A university library introduces French after years of English publication and wants to preserve both histories. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Editors may confuse an interface language selector with the actual content locale they are editing and save material in the wrong place. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Record the intended locale code and open its content models and entries before any bulk creation. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.

4. Respect locale-scoped model behavior

A Webiny tutorial describes cloning a content model into another locale, then editing the translated model and adding localized entries. This illustrates locale context for models, not a universal automatic field-translation feature. Make the test observable: record the requested locale, the actual returned value, the source revision and the public URL. A green status badge without that evidence can mislead.

A global blog keeps parallel English and French article structures with different display copy but comparable record fields. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Assuming a model’s existence in one locale automatically creates fully translated records in another leaves empty public pages. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Create one content model and one real entry in each locale, and compare the GraphQL schema and published outputs. Check the same state on desktop and mobile, then verify that a keyboard user can complete the central task.

5. Keep model identifiers consistent

Readable titles may be translated, while machine-facing model and API identifiers must be predictable across application code. The published tutorial highlights configuring singular and plural API names in each locale. Separate configured capability from completed work. The existence of a locale option or a valid response says little about whether the reader has received a reviewed explanation.

A frontend is built to query English and French article records through documented endpoints. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

An editor changes a model API name casually, breaking a production query that relied on the old generated name. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Review model names and query identifiers with developers before changing them in any target locale. Ask a reviewer to explain the target-language claim in their own words before treating the translation as accepted.

6. Choose a stable translation relationship

If localized articles are separate entries, use an explicit relationship or stable translation-group key to connect their identities. Do not rely only on translated titles or coincidentally similar URLs. When the sample fails, isolate whether the cause is data modelling, editorial approval, route selection or delivery. Each cause requires a different repair and different owner.

A history article is renamed in French after a subject reviewer corrects the emphasis of its title. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Title matching can associate the wrong English and French articles or leave an orphan with no correct language switch target. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Give every corresponding entry a shared editorial identity and test lookup after a title change. Confirm what happens to deep links, back navigation and search results rather than testing only the landing page.

7. Explore APIs in the API Playground

Webiny’s documented API Playground exposes Read, Manage and Preview GraphQL API types and includes a locale selector when multiple locales are active. The best model is the simplest one that still expresses genuine regional differences and preserves stable identity. Extra duplication expands the number of revisions a team must reconcile.

A content manager wants to see exactly what anonymous visitors can read in French before connecting a live frontend. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Using the Manage schema as a model for public delivery can lead to accidental exposure of draft or privileged operations. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Select the read endpoint and locale explicitly, then compare the query against preview and management contexts. Keep a source snapshot so that the team can detect obsolete target wording after an upstream correction.

8. Distinguish Read, Manage and Preview APIs

The official GraphQL documentation describes three Headless CMS API types with different purposes. A translation workflow should never infer publication state from the wrong one. Assess the consequence to the person using the page. A wrong headline is inconvenient; a wrong deadline, payment rule or medical condition can change a real-world decision.

A German proofreader uses preview to review pending text while readers receive only approved content from the read API. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

If production uses preview endpoints, the public site may leak drafts or display unapproved corrections. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Test the same entry in all permitted contexts and document why each response differs. Use a lower-privilege account for the workflow test and a signed-out browser for the public delivery test.

9. Use locale-specific API routing deliberately

The Webiny multilingual tutorial demonstrates locale-scoped read paths, for example a read endpoint ending with en-US or fr-FR. Verify paths against your running version. Build one reversible experiment before implementing the policy across thousands of records. A small controlled example provides stronger evidence than assumptions based on an admin screen.

A Vue website switches language and changes its GraphQL read URL to the corresponding configured locale endpoint. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Changing only on-screen labels while keeping the English content endpoint will produce a mixed-language page. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Capture network requests during a locale switch and confirm endpoint, query, entry identity and returned fields. Test a complete locale, a partial locale and an unsupported locale as distinct input states.

10. Do not leak privileged API keys to clients

Webiny’s tutorial uses API keys to demonstrate GraphQL access; production permission scope and secret handling must be more restrictive than a quick learning example. Record both what is intentionally shared and what is intentionally translated. The distinction helps a future editor understand whether the same visible value is correct or simply unfinished.

An education portal must let anonymous users read approved articles without being able to publish or delete them. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Shipping a privileged bearer token in a public frontend bundle risks unauthorized writes regardless of translation quality. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Review roles, allowed locales, endpoint types and server-side proxy design before publishing any client application. Do not equate a successful API response with a publishable page until the real rendered output has been inspected.

11. Limit access by locale where roles require it

Webiny’s security examples describe content permissions that can be specific to a locale and action. Translators may need edit permission without publication authority. Compare the page under an authenticated editorial session and a private anonymous session. Preview access, workflow state and caches frequently produce different visible outcomes.

A French reviewer can update French drafts but must not alter English source articles or publish unreviewed legal advice. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Giving broad rights to every translator can obscure ownership and allow accidental cross-locale damage. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Test permissions with actual low-privilege accounts rather than administrator sessions. Reproduce the result with caches warmed in the opposite language to expose mis-keyed multilingual delivery.

12. Plan a shared glossary outside the content schema

Model fields hold article content, not necessarily the explanation behind specialist terminology. Translation teams need definitions and context for stable meaning. Keep accessibility and search discoverability within scope. A translation is not complete if assistive technology or a direct incoming link presents a different language from the one promised.

A renewable-energy glossary distinguishes a power rating from the amount of energy generated over time. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

If reviewers see isolated field strings, they may choose correct-sounding words that change the technical statement. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Attach source context and preferred target expressions to each entry or translation task. Include a negative test: deliberately remove one translated field and inspect the visible fallback or error.

13. Design localized slugs explicitly

A headless frontend owns URL generation; translated titles do not automatically produce usable or stable public routes. Decide whether slugs are localized, shared or explicitly mapped. Think about the ownership of the data before thinking about vocabulary. A shared fact should have one identifiable source; a local adaptation should have a named reason. Those are different editorial obligations.

A history guide uses /fr/histoire/ on French routes but still needs a stable link to its English counterpart. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Regenerating slugs whenever translators revise a heading can break bookmarks, citations and inbound links. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Store immutable route IDs, approve slug changes and provide redirects only when a deliberate URL migration occurs. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.

14. Separate region from language in models

English in several countries may share most prose but differ in contact information, units or legal policy. These are market variables, not merely translation variants. Readers do not see the content-management boundaries. They experience a continuous page, so the review must follow the visible journey rather than stopping at the field editor.

An international study-abroad portal offers English information for Canada, India and Singapore with different visa instructions. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Selecting all content by preferred language alone may present the wrong jurisdiction-specific rules. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Model the market explicitly and test identical language preferences across more than one country. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.

15. Protect source provenance in every locale

Each translated article should keep a reference to the source claim, supporting document and revision it was based on. Webiny entries can be modelled to hold such editorial metadata. Treat the source statement as a claim that can be checked, not a string that merely needs different spelling. Dates, conditions and scope must survive the move between languages.

An English science article corrects a graph interpretation after external review, while its French variant has not been revisited. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

The translation stays fluent but factually inconsistent if editors cannot see the changed source evidence. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Add a source-revision field to an editorial test model and trigger an impact check when it changes. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.

16. Use rich text without losing structure

Headless content often includes rich-text lists, headings, links and inline media references. Reviewers must protect semantic structure, not simply the visible words. Make the test observable: record the requested locale, the actual returned value, the source revision and the public URL. A green status badge without that evidence can mislead.

A multilingual safety guide includes numbered operations and a bold warning within a translated article body. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Flattening structured content into an undifferentiated string can reorder steps or strip accessible link names. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Render two languages with the final frontend component and compare heading levels, list order and citations. Check the same state on desktop and mobile, then verify that a keyboard user can complete the central task.

17. Give image descriptions language-specific ownership

A shared illustration may be the same asset across locales while captions and alternative text need translation and cultural review. Separate configured capability from completed work. The existence of a locale option or a valid response says little about whether the reader has received a reviewed explanation.

An anatomy chart contains labels that are meaningful in English but have different standard terminology in French. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Copying the same asset reference without local text can leave part of the page inaccessible or incomprehensible. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Inspect the rendered alt text, captions and linked image descriptions in every supported locale. Ask a reviewer to explain the target-language claim in their own words before treating the translation as accepted.

18. Design optional translation states explicitly

A new locale may not have every article at launch. A product should distinguish missing, draft, reviewed and published rather than treating them as one blank value. When the sample fails, isolate whether the cause is data modelling, editorial approval, route selection or delivery. Each cause requires a different repair and different owner.

A public archive has forty English articles but only twelve approved German translations for its launch phase. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Inventing a German route for each English item can expose placeholder pages or misleading fallback content. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Store coverage in a review matrix and route visitors only to approved equivalents. Confirm what happens to deep links, back navigation and search results rather than testing only the landing page.

19. Create a preview review loop

Webiny’s Preview API supports editorial checks before release. It is a different delivery context from the production Read API. The best model is the simplest one that still expresses genuine regional differences and preserves stable identity. Extra duplication expands the number of revisions a team must reconcile.

A bilingual editor reviews an unpublished French explanation and compares it with the English source on a staging domain. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

An editor may sign off based on preview while the live GraphQL query returns an older entry version. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Record both the preview result and the published read result when closing the release task. Keep a source snapshot so that the team can detect obsolete target wording after an upstream correction.

20. Decide whether pages and CMS entries share localization

Webiny includes several applications and a headless CMS; content localized in one app does not automatically translate a separate page builder component or a third-party frontend. Assess the consequence to the person using the page. A wrong headline is inconvenient; a wrong deadline, payment rule or medical condition can change a real-world decision.

A global campaign page contains an article feed, a navigation banner and a signup form. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Translating only the feed entries can leave the call to action or form errors in English. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Inventory every visible text owner before claiming the full visitor experience is translated. Use a lower-privilege account for the workflow test and a signed-out browser for the public delivery test.

21. Connect the frontend i18n runtime separately

The official Vue example uses vue-i18n for interface text while Webiny supplies translated CMS content through GraphQL. Build one reversible experiment before implementing the policy across thousands of records. A small controlled example provides stronger evidence than assumptions based on an admin screen.

An alumni website has French buttons and menu labels together with French articles from the CMS. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

A frontend can be fully internationalized yet still retrieve English body text if the GraphQL locale is wrong. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Switch locales and inspect both application dictionaries and the network data source. Test a complete locale, a partial locale and an unsupported locale as distinct input states.

22. Keep locale state through navigation

A successful switcher should preserve the selected language when readers open deep links, use search, return from forms or reload a page. Record both what is intentionally shared and what is intentionally translated. The distinction helps a future editor understand whether the same visible value is correct or simply unfinished.

A German reader arrives via a shared article URL and navigates to a related research paper through a card component. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

If routes lose locale state, readers bounce unexpectedly to English although corresponding German content exists. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Test a complete user journey through three content types and browser history. Do not equate a successful API response with a publishable page until the real rendered output has been inspected.

23. Build a search index for the right language

Search implementation may need locale-specific indexing or explicit language fields, even when Webiny’s content APIs return the correct entries. Compare the page under an authenticated editorial session and a private anonymous session. Preview access, workflow state and caches frequently produce different visible outcomes.

A public library wants French queries to find French titles rather than only English source terminology. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Indexing source records without locale separation creates low-relevance results and false zero-result messages. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Search for a phrase unique to each language and verify the result titles and links stay in that language. Reproduce the result with caches warmed in the opposite language to expose mis-keyed multilingual delivery.

24. Test no-result and error messages

Application messages often come from a frontend dictionary and can be overlooked when teams focus on Headless CMS articles. Keep accessibility and search discoverability within scope. A translation is not complete if assistive technology or a direct incoming link presents a different language from the one promised.

A French visitor searches for an obscure term and receives a technically correct empty result screen. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

An untranslated or ambiguous empty-state message can make users believe the service is broken. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Exercise network failure, no results, permission denial and expired session states in each language. Include a negative test: deliberately remove one translated field and inspect the visible fallback or error.

25. Handle number and date formatting explicitly

Locale-scoped content delivery does not automatically make every numeric label, date or unit culturally appropriate in a frontend. Think about the ownership of the data before thinking about vocabulary. A shared fact should have one identifiable source; a local adaptation should have a named reason. Those are different editorial obligations.

An international events page displays the same webinar instant to French and English audiences in different time zones. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Translating month names but keeping the wrong time zone or date order can change attendance decisions. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Check actual timestamps, formatting and time-zone conversion independently from the CMS text. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.

26. Keep media rights and credits intact

Image licensing, quotations and attribution travel with meaning across locales even if visible captions are translated. Readers do not see the content-management boundaries. They experience a continuous page, so the review must follow the visible journey rather than stopping at the field editor.

A museum uses a licensed photograph whose photographer credit must appear in every version of the exhibit. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Rewriting a caption without carrying the rights notice can breach a licence or erase provenance. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Trace one asset from source record to each translated page and confirm its attribution survives. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.

27. Respect version differences in documentation

Webiny’s product evolves, and older blog examples show particular framework versions, deployment methods and model-cloning workflows. Treat tutorials as versioned examples rather than universal rules. Treat the source statement as a claim that can be checked, not a string that merely needs different spelling. Dates, conditions and scope must survive the move between languages.

A team running a current Webiny deployment follows a 2023 Vue tutorial verbatim and expects every control to appear in the same place. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Old package requirements and hosting assumptions may cause needless migration work or insecure shortcuts. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Check the running release and its documentation before using copied API URLs or code samples. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.

28. Avoid confusing multi-tenancy with automatic sharing

Webiny describes tenants as isolated. Sharing content across brands or languages therefore requires intentional architecture or a supported integration, not wishful assumptions. Make the test observable: record the requested locale, the actual returned value, the source revision and the public URL. A green status badge without that evidence can mislead.

A group of regional charities wants shared medical evidence while maintaining separate legal pages and donor data. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Copying content between isolated tenants without change tracking creates out-of-date duplicate claims. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Choose a central approved content source and test the process by updating one sample fact across target tenants. Check the same state on desktop and mobile, then verify that a keyboard user can complete the central task.

29. Test cache behavior on locale change

A GraphQL client cache may key entries by query and variables while the locale lives in the endpoint path. Incorrect cache separation can render stale content after switching. Separate configured capability from completed work. The existence of a locale option or a valid response says little about whether the reader has received a reviewed explanation.

A bilingual knowledge site switches English to French but keeps the previous English article until a full browser refresh. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

The API may be correct while the frontend reuses data fetched under a different language context. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Alternate language switches with cache enabled and disabled, then inspect returned entry IDs and cache policies. Ask a reviewer to explain the target-language claim in their own words before treating the translation as accepted.

30. Inspect publication permissions and audit records

Editorial authority is a meaning-preservation control: a translator drafts, a subject reviewer checks facts and a publisher releases approved content. When the sample fails, isolate whether the cause is data modelling, editorial approval, route selection or delivery. Each cause requires a different repair and different owner.

An international health page must separate linguistic review from medical evidence review for each locale. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

If any writer can publish every locale, a seemingly harmless translation can bypass the source owner’s correction. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Verify with restricted accounts who may draft, approve and publish, and keep dated review evidence. Confirm what happens to deep links, back navigation and search results rather than testing only the landing page.

31. Build accessible language switching

The switcher should identify languages in text and keyboard-accessible controls, not only flags or an ambiguous two-letter symbol. The best model is the simplest one that still expresses genuine regional differences and preserves stable identity. Extra duplication expands the number of revisions a team must reconcile.

A multilingual public service website is used by travellers with different assistive technologies and literacy levels. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

A mouse-only flag selector can hide the language choice from keyboard and screen-reader users. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Tab through the switcher, inspect its accessible name and verify the selected page announces the actual language. Keep a source snapshot so that the team can detect obsolete target wording after an upstream correction.

32. Create meaningful alternate-language SEO links

An alternate-language URL should lead to the equivalent approved record, not merely to a locale homepage or machine-generated placeholder. Assess the consequence to the person using the page. A wrong headline is inconvenient; a wrong deadline, payment rule or medical condition can change a real-world decision.

A French historical essay and an English source essay share identity while one German version remains in draft. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

Publishing an alternate link to the unreviewed German route misrepresents coverage and can confuse search discovery. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Crawl the public HTML, confirm canonical URLs and reciprocally linked language equivalents, and exclude unavailable versions. Use a lower-privilege account for the workflow test and a signed-out browser for the public delivery test.

33. Use locale-aware logging without storing secrets

Useful diagnostics include requested locale, resolved content model, publication status and response version. They should not log private tokens or personal visitor data. Build one reversible experiment before implementing the policy across thousands of records. A small controlled example provides stronger evidence than assumptions based on an admin screen.

A newsroom diagnoses why Italian users occasionally receive English headlines after a release. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Without locale metadata engineers blame translation quality for what is actually a routing or caching error. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Log a synthetic request identifier and locale outcome, then reproduce the issue using a disposable account. Test a complete locale, a partial locale and an unsupported locale as distinct input states.

34. Test partial failure safely

If one locale endpoint is temporarily unavailable, the frontend should show an explicit, understandable error or clearly labelled fallback rather than silently misrepresenting language. Record both what is intentionally shared and what is intentionally translated. The distinction helps a future editor understand whether the same visible value is correct or simply unfinished.

A charity’s German content API fails during a fundraising campaign while the English endpoint remains reachable. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

An unannounced fallback can make German visitors submit a form they no longer understand. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Simulate endpoint failure and verify the user sees a truthful recovery path without losing entered form data. Do not equate a successful API response with a publishable page until the real rendered output has been inspected.

35. Create acceptance tests from real reader goals

A translated site is successful when visitors can find, understand and act on information, not merely when queries return HTTP 200. Compare the page under an authenticated editorial session and a private anonymous session. Preview access, workflow state and caches frequently produce different visible outcomes.

A visitor needs to find a French health advisory, understand its date and reach the correct official contact. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

A snapshot test that checks only the heading misses wrong links, stale claims and inaccessible form errors. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Define five real tasks and require evidence that each works in every published locale. Reproduce the result with caches warmed in the opposite language to expose mis-keyed multilingual delivery.

36. Plan a source-revision propagation policy

Separate entries or models may need explicit work to synchronize meaning with the source. No software platform can infer every factual implication of a revised claim. Keep accessibility and search discoverability within scope. A translation is not complete if assistive technology or a direct incoming link presents a different language from the one promised.

A research article changes from may increase to has not been shown to increase after a correction. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

A target-language summary may continue to state certainty even though the source now expresses uncertainty. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Compare critical claims and revise each translation before promoting the new published revision. Include a negative test: deliberately remove one translated field and inspect the visible fallback or error.

37. Preserve slug and redirect history

Public documents acquire external links and citations. A translator’s stylistic improvement should not automatically destroy stable URLs. Think about the ownership of the data before thinking about vocabulary. A shared fact should have one identifiable source; a local adaptation should have a named reason. Those are different editorial obligations.

A German article slug is updated for readability after international sites have already linked to it. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Without controlled redirects, readers encounter a 404 and search engines lose the older evidence path. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.

Practical verification: Make URL changes an explicit release item with a redirect and a link integrity test. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.

38. Measure translation coverage by reader journey

Raw counts of entries are insufficient because a translated article may link to an untranslated form or have missing image descriptions. Readers do not see the content-management boundaries. They experience a continuous page, so the review must follow the visible journey rather than stopping at the field editor.

A multilingual public library reports 100 French articles but only 20 have accessible figure captions and working French search results. A developer should check the real rendered result as well as the administrative settings. Matching text in a test form is not enough when a route or integration can select a different record.

The count creates false confidence and directs investment away from the most harmful gaps. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.

Practical verification: Track reviewed text, media, routes, forms and real task completion for each language. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.

39. Document production delivery independently of preview

A reliable handoff contains locale endpoint, source revision, entry status, route, approved vocabulary and the exact public URL. Treat the source statement as a claim that can be checked, not a string that merely needs different spelling. Dates, conditions and scope must survive the move between languages.

A volunteer translator completes the final French corrections but a deployed frontend build still uses cached English content. An editor should identify the exact source record and intended audience before changing a language value. Make sure that the surrounding page does not change the scope of the statement.

Without delivery evidence the team cannot tell whether translation or deployment is responsible. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.

Practical verification: Check the live anonymous URL after cache clearing and save response snapshots with the release record. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.

A two-language release exercise you can reproduce

First select an ordinary content record whose source meaning can be verified. Give it a date, a numerical fact, a conditional sentence, an image with an explanation and one important internal link. The items are deliberately varied: a simple greeting is not a useful stress test. Assign a source revision, a target locale and a reviewer before anyone starts typing.

Next create one complete translated version and one deliberately incomplete variant in a test environment. Retrieve the result through the path the public website actually uses. Compare missing values and fallback behavior, then record whether the system returns nothing, a default-language value, a draft or an explicitly labelled alternative. Decide in advance which of these outcomes readers may safely receive.

Now change the source condition in a harmless way—for example, change “registration closes on Friday” to “registration closes on Thursday” in a test article. The important observation is not whether the translated page still renders. It is whether the team can identify every language version that may now state an old deadline and prevent that statement from being presented as current.

Finally complete a reader journey: arrive from an external link, switch language, search for another item, inspect an image, open a form, trigger an error and return by browser history. Test with the relevant locale configuration and without an editor login. Record any place where the page silently changes language, loses its identity, shows an older claim or fails accessibility. Only then is the translated experience meaningfully tested.

Troubleshooting: symptoms and likely causes

The page exists but the visitor sees the source language: Inspect the public locale route, the actual content API request, the selected field or entry language and the approved release state.
The title is translated but the body is not: Check field-level or item-level coverage rather than assuming a language indicator refers to a complete page.
A link sends users to the wrong country: Separate market-specific destination policy from translation and review the target site’s authority and applicability.
An editor sees new copy but the public still sees old copy: Compare preview and public queries, publication workflow, deployed frontend data and cache invalidation.
One language appears after another was requested: Inspect the language selector, browser preferences, cache variation and explicit URL routing priorities.
A page has translated prose but English controls: Inventory application dictionaries, templates, plugins, form validation and external widgets separately from CMS text.
A translated page disappears from search: Verify public release, indexable status, canonical target, locale path, sitemap and the actual indexed language.
Translators keep correcting the same phrase: Add source context and approved terminology, and record whether the old wording is being reintroduced from a stale source version.
Numbers or dates disagree across languages: Compare underlying data, formatting, time zones and source corrections before blaming linguistic wording.
Mobile users cannot select a language: Test focus order, accessible labels, responsive layout and non-pointer controls on the final frontend.
A translation is approved but its image still reads in English: Review embedded text in the image, alt text, captions and any locale-specific media references.
The team cannot tell which version is current: Preserve source revision, translator review, factual approval, locale status and public URL as separate fields of evidence.

Frequently asked questions

Does adding a locale mean the website is translated?

No. A locale setting may create a place for a value or enable a route. It does not create reviewed content, translate every widget or establish that readers can complete a task.

Should missing translations fall back to the source language?

That depends on audience and risk. A transparent fallback can be useful in an internal reference tool, but a public instruction, law or safety notice may need to be withheld until approved.

Can machine translation be used in the first draft?

It can assist a defined workflow, but the output still needs review for terms, conditions, numerical facts, cultural context, links and the intended reader’s actions.

How should we measure completion?

Count meaningful reader-facing surfaces and approved actions, not just words or records. Include media, metadata, search, forms, language routing and direct public delivery.

What happens after the source is revised?

Identify every target affected by the changed assertion, compare old and new meanings, re-review the necessary translations and verify the updated public result.

Does a successful preview prove that the page is live?

No. Preview often has different permissions, content states or caching. Test the production route while signed out and confirm the exact language and source revision.

Can we use one language version for several countries?

Often yes for universal information, provided market-specific rules, units, addresses and services are separately modelled and presented accurately.

What is the most important acceptance test?

Ask someone in the target audience to follow a real task from entry link to final action, then compare their understanding with the source’s intended meaning.

Official documentation and version notes

The following product documentation is the primary starting point. Features, supported versions and administrative controls change. Check the release that your organization actually uses before copying configuration or API examples into production.

Continue through eduKate’s translation library

The broader Master Art of Translation explains why preserving claims, evidence and intended action matters across languages. The Translate Like a Pro series index links implementation guides across tools and systems. This chapter’s own focus is Webiny Headless CMS locales, generated GraphQL APIs and frontend translation delivery, so it complements rather than replaces those general guides.

The strongest multilingual implementation is not the one with the most enabled languages. It is the one that can explain exactly what a reader is seeing, where the information came from, who checked it and what happens after it changes. Start with one reliable journey, verify it from the outside, then extend that quality to every page and language you choose to publish.

Translate Like a Pro | 6300 — Webiny Headless CMS Locales, GraphQL Read APIs, Content Models and Frontend QA