How do you translate Squidex content for an international audience without confusing language settings, editorial approval and what visitors actually see? This guide explains Squidex localizable fields, ordered language fallbacks and REST API language headers, 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 Squidex 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 Squidex translation tutorial is intended for content architects, editors and frontend developers. It covers Squidex localizable fields, ordered language fallbacks and REST API language headers 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: a worldwide scientific museum catalog that publishes English evidence notes first, then Swedish and Finnish visitor descriptions without duplicating object identities
Imagine a worldwide scientific museum catalog that publishes English evidence notes first, then Swedish and Finnish visitor descriptions without duplicating object identities. 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.
Choose one published object with a stable inventory ID, a language-specific title, a long description, an illustrated caption and a source reference. Create an optional Finnish variant, populate only two fields and request its content with the normal REST API. Then request the raw data without fallback and compare the two outputs. Finally change an English factual sentence, rerun the comparison and decide whether the Swedish and Finnish versions still communicate the same claim.
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.
Squidex localization in depth: 39 decisions and checks
1. Understand partitions before translating
Squidex stores fields as partitions: a localized description has language-keyed values while invariant fields use an iv key. That storage distinction shapes every API response and should be explained to editors. 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 food-cooperative directory has one founding date and separate English, Swedish and Finnish descriptions for the same organisation. 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.
Treating invariant data as language-specific creates needless drift; treating customer-facing descriptions as invariant leaves readers with an unexpected foreign-language paragraph. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Open one representative content item and label every field as shared or localized before a team enters translations. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.
2. Decide which fields are localizable at schema creation
The Squidex localization guide states that a field’s localizable setting is chosen when it is added and cannot simply be toggled afterwards. This is an early modelling decision, not cosmetic administration. 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 exhibition site wants its visitor instructions localized but its catalogue inventory code kept common across regions. 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 a team discovers the mistake after hundreds of records exist, changing the data model may require a carefully planned migration and testing. 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 a pilot schema, inspect the property settings, and confirm future translation needs with a content owner before importing production records. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.
3. Choose the master language consciously
A Squidex app has one master language. The documentation describes it as the default source of fallback when other languages lack a value. 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 science charity initially publishes English evidence pages and gradually introduces Swedish and Finnish versions with different translators. 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.
Making the master language an arbitrary regional variant can make incomplete pages display culturally inappropriate spellings or instructions. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Write down which language owns the authoritative assertion, which editorial team reviews changes, and what readers should see if a translation is absent. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.
4. Configure optional languages for staged rollouts
Squidex marks target languages optional to let required fields remain empty while a new translation is being prepared. Required source data and complete localized coverage are therefore different tests. 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 public museum adds Italian but cannot translate its entire archive on launch day. Editors need to save ongoing improvements without accidentally promising a complete Italian library. 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 optional locale may pass form validation even while a crucial safety notice has not been translated for visitors. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Report language completeness separately and define an explicit publish rule for essential notices, emergency text and transactional instructions. Check the same state on desktop and mobile, then verify that a keyboard user can complete the central task.
5. Design a fallback chain in a deliberate order
The Languages settings allow several fallback languages ordered by priority. Fallback is not inherently a translation: it is an editorial decision to borrow another locale’s words. 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 Finnish page could request Finnish first, then Swedish, before master English if a particular field is missing. 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.
If Swedish uses different regulations or local services, a technically successful fallback can create a false claim for Finnish visitors. 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 a missing sentence at each level of the chain and record the exact language from which the rendered field came. Ask a reviewer to explain the target-language claim in their own words before treating the translation as accepted.
6. Preserve invariant identifiers
Non-localizable values appear under the iv key in the documented API representation. Stable record identifiers, evidence references and machine codes usually belong here. 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 environmental dataset is indexed by a species ID and geographic coordinates while titles and descriptions vary by language. 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 an identifier into attractive human-readable prose may break joins, historical references or downstream reporting. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Query the same record through two languages and verify the invariant values compare exactly, including punctuation and numerical representation. Confirm what happens to deep links, back navigation and search results rather than testing only the landing page.
7. Keep regional policy distinct from language
Language partitions are useful for text, but a country-specific legal obligation is not always determined by the visitor’s preferred language. 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 Spanish-language reader in Belgium may need Belgian return information rather than the consumer rules for Spain. 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.
Conflating language and jurisdiction can send customers to the wrong policy and create compliance risk despite flawless vocabulary. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Model country or market rules explicitly, then test Spanish readers under multiple market contexts. Keep a source snapshot so that the team can detect obsolete target wording after an upstream correction.
8. Add languages through the app’s settings
The documented Squidex management interface places language configuration under Settings and Languages. Adding a code there enables new localized values for the app. 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 local history project adds French after an English launch while keeping its existing object identities and relationships. 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.
Entering French into a custom content field without registering the locale does not establish a supported language variant in the CMS. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: Use a test app to add the locale, enter one translated field, retrieve it, and inspect its configured fallback behavior. Use a lower-privilege account for the workflow test and a signed-out browser for the public delivery test.
9. Understand the X-Languages request header
The Squidex REST API uses X-Languages to select requested language partitions. The official guide explicitly distinguishes this from relying on Accept-Language for the documented behavior. 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 mobile client sends X-Languages with Swedish while an administrator retrieves several partitions for comparison. 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.
Assuming browser language headers automatically select the same content can make the app appear correctly localized in preview but wrong in production. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Make two REST requests with distinct X-Languages values and inspect whether the expected field partitions are present. Test a complete locale, a partial locale and an unsupported locale as distinct input states.
10. Understand X-Flatten response shaping
X-Flatten can simplify fields that have only one result value, making a single-language delivery payload easier for a frontend to consume. It changes representation, not editorial approval. 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 public landing page consumes one locale per request and prefers a plain string over a map of translated strings. 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.
Frontend code written for the flattened shape may fail if an integration suddenly requests multiple locales and receives a different structure. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Capture a sample response with and without X-Flatten, then document the contract expected by the frontend. Do not equate a successful API response with a publishable page until the real rendered output has been inspected.
11. Combine X-Languages and X-Flatten carefully
Both Squidex REST headers can be combined, according to the localization documentation, when the team wants a selected locale and simpler single-value fields. 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 city guide asks for French on one route and English on another, using the same template and data model. 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.
If a client assumes a selected language always exists, silent fallback can mask incomplete translations while the page remains apparently normal. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: Log requested and resolved locale in a diagnostic build, and exercise one complete and one deliberately incomplete record. Reproduce the result with caches warmed in the opposite language to expose mis-keyed multilingual delivery.
12. Distinguish unsupported languages from missing translations
The documented REST endpoint ignores unsupported language codes and may return master-language content if none of the requested codes is supported. That differs from a configured locale with some empty fields. 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.
An application receives a malformed locale code after a language switcher or a browser-language normalization error. 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.
Calling the fallback an approved translation would be misleading, especially when the UI still announces the unsupported target language. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Test supported, partially populated and unrecognized locale codes as three separate cases. Include a negative test: deliberately remove one translated field and inspect the visible fallback or error.
13. Disable server-side language resolution when diagnosing gaps
The localization guide documents X-NoResolveLanguages=1 for obtaining raw language values rather than automatically resolving fallback. It is valuable for coverage auditing. 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 translation manager needs to know whether Finnish wording genuinely exists rather than merely seeing English words rendered beneath a Finnish route. 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 fallback-enabled response alone overstates completeness and can conceal unpaid or unfinished translation work. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Compare normal and no-resolution responses for the same record and produce a field-level gap report before approving the locale. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.
14. Use field-level completeness instead of page-level optimism
Squidex can localize selected fields inside one item. A record may have a translated title while body text, caption, call to action and error copy still need work. 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 art gallery’s French exhibit record has a title and short introduction but lacks an accessible image description. 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 page-level green tick based only on the title may wrongly advertise accessibility and complete understanding. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: List every required reader-facing field and assign a reviewed, missing or intentionally shared status per locale. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.
15. Audit media descriptions as content
An image asset may be reused across languages while its alternative text, caption and licensing explanation need natural local-language wording. Asset identity does not imply copy identity. 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 climate chart keeps the same graphic but needs German text that explains the axes, uncertainty and units. 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 only a visible caption can leave assistive-technology users without the factual meaning carried by the figure. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Inspect both the rendered alt text and any structured description returned through the active API query. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.
16. Keep structured facts separate from free prose
Dates, identifiers, coordinates and sourced measurements should remain typed and stable while nearby language explains what those facts mean. 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 health information portal displays a universal numeric measurement alongside an explanation that changes for each language. 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 an editor copies a number into every translated paragraph, later corrections can miss some copies and create inconsistent claims. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Change a harmless sample number at source and confirm every locale displays the same underlying value with correctly localized formatting. Check the same state on desktop and mobile, then verify that a keyboard user can complete the central task.
17. Model rich text for translation and accessibility
Localized rich text may contain headings, hyperlinks, citations, emphasis and lists. A translated paragraph is not complete if it loses the structure that lets readers navigate it. 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 legal-aid explainer includes a numbered sequence and a link to an authoritative help page in every locale. 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 source HTML into a new language without verifying link targets and accessible names can produce misleading or broken instructions. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: Read each language version with a keyboard and screen reader, and compare heading order and destination meaning. Ask a reviewer to explain the target-language claim in their own words before treating the translation as accepted.
18. Create stable content identity across languages
Squidex field partitions make it possible to preserve one content item while maintaining several language variants. This is useful for traceable source revisions. 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 museum object has one catalogue identity even though the public caption appears in four languages. 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.
Creating a new unrelated record for each language can make relations, change tracking and alternate-language links hard to reconcile. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Trace a translated field back to its shared record ID and document any exception requiring distinct market content. Confirm what happens to deep links, back navigation and search results rather than testing only the landing page.
19. Treat editorial approval independently from schema validation
A schema can enforce data shape without knowing whether a translator preserved a claim. Optional languages in particular may validate with empty localized fields. 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 volunteer translates an emergency preparation article and submits well-formed content that still contains an inaccurate evacuation instruction. 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.
Passing a CMS form and GraphQL request is technical evidence, not evidence that safety-critical meaning has survived. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Require language review against the exact source revision and attach a reviewer decision to the release ticket. Keep a source snapshot so that the team can detect obsolete target wording after an upstream correction.
20. Use explicit translation status fields when needed
A team can model editorial metadata for locale owners, source revision, review state and approval date without presenting that metadata as public article copy. 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 science publisher must tell whether a localized description reflects the latest peer-reviewed 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.
Without provenance, editors see a plausible translation but cannot prove it came from the current evidence. 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 a small review record and check that a source change can identify the translated fields that need reapproval. Use a lower-privilege account for the workflow test and a signed-out browser for the public delivery test.
21. Design a source-change impact check
When source prose changes, field-level language partitions do not decide which targets still mean the same thing. Human review is needed for changed claims. 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 product support article updates the battery requirement; English changes immediately while a Swedish translation remains linguistically polished but obsolete. 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 site can quietly distribute contradictory technical advice across languages while every page returns status 200. 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 previous source value and compare every translated equivalent before moving the source revision live. Test a complete locale, a partial locale and an unsupported locale as distinct input states.
22. Prefer structured examples over blind machine replacement
Automated assistance can draft translations but will not know all brand meanings, local procedures or unstated technical context in a Squidex entry. 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 word such as charge refers to a fee on one page and an electrical quantity on another. 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 bulk substitution that looks efficient can alter a reader’s decision or invalidate an instruction. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Supply terminology notes and inspect the rendered page in context before marking each target field reviewed. Do not equate a successful API response with a publishable page until the real rendered output has been inspected.
23. Separate content API auth from public identity
A CMS API token authenticates access to content; it should not be exposed merely to switch languages on a website. Public delivery requires an intentional security design. 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 knowledge base needs anonymous visitors to select French while editors retain privileges to write unpublished records. 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.
Embedding high-privilege credentials in browser code can expose content management operations to unauthorized users. 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 client bundle and API permissions; verify the public route needs only read access to approved content. Reproduce the result with caches warmed in the opposite language to expose mis-keyed multilingual delivery.
24. Test published versus draft data paths
A headless website may have separate preview and published content retrieval paths. The selected language must be checked on the exact delivery endpoint used by visitors. 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 translated article looks complete to editors but a public page still shows its older caption because the frontend consumes the published revision. 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.
Confusing previews with delivery creates false release sign-offs even when the API itself is working. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Compare preview and anonymous published responses for the same item and explain any intentional difference. Include a negative test: deliberately remove one translated field and inspect the visible fallback or error.
25. Build locale-aware routes outside the CMS
Squidex returns content data; the site’s routing layer still decides whether URLs such as /fr/guide/ reach the matching translated item. 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 charity’s French landing page should retain the visitor’s language when they open related articles and return to the index. 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.
Hard-coded English paths can pull readers back into another language even though the translated fields exist. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Start on a deep French URL, follow three internal links, refresh the browser and inspect the language context. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.
26. Mark the real language in the output HTML
The frontend should set the document language for each page or component rather than inferring it from a visual flag icon. 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 screen reader encounters a Swedish title, an English citation and a Latin species name on one page. 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.
Incorrect language metadata can make pronunciation confusing and harm navigation for assistive-technology readers. 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 html lang attribute and any inline language changes across the complete page. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.
27. Keep canonical and alternate-language URLs honest
Localized routes need meaningful canonical targets and reciprocal alternate links when appropriate. A missing translation is not the same as an equivalent published page. 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 museum object has French and German translations but the Finnish version is still in editorial review. 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.
Declaring a Finnish alternate URL that actually serves English may mislead search engines and readers about available language coverage. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Crawl the published alternatives, confirm substantive language content and fix incorrect alternate mappings. Use a test item containing a number, an exception and a link, because these expose errors hidden by a friendly one-sentence greeting.
28. Separate search indexing from fallback behavior
A field may resolve through a fallback yet still produce a page whose primary text is not in its advertised locale. Indexing policy is a separate decision. 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 food guide uses Finnish navigation but English body text for most of its new Finnish routes. 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.
Indexing thousands of near-duplicate fallback routes as translated pages can weaken information quality and reader trust. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Sample every language directory and decide whether incomplete routes should be withheld, redirected or transparently offered as fallback. Check the same state on desktop and mobile, then verify that a keyboard user can complete the central task.
29. Test cache keys for each locale
The same item ID and route pattern can serve different language partitions. Shared caches must vary on the information that determines the selected language. 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 CDN caches the Swedish response to an English request because the cache configuration ignores the custom language header. 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.
Visitors then receive the wrong language unpredictably even when direct origin requests return correct values. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: Request two languages in alternating order after cache warming and compare response headers, bodies and cache keys. Ask a reviewer to explain the target-language claim in their own words before treating the translation as accepted.
30. Validate search and filter labels
A localized document body does not guarantee that search facets, filter names and empty-state messages are translated by the frontend. 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 global museum search returns correct French records but displays English category labels and an untranslated no-results message. 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.
Users may interpret a missing result as absent content when the fault is actually inconsistent locale handling. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Search for an uncommon translated phrase, filter results and test the empty state while recording the actual language. Confirm what happens to deep links, back navigation and search results rather than testing only the landing page.
31. Protect numbers and units within translations
Localized wording can change without changing the measurement or its significance. Units require clear formatting, conversion policy and editorial checking. 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 travel guide displays 18 kilometres in one locale and an optionally converted distance in another. 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 translation that drops a unit or switches decimal punctuation incorrectly changes the information, not merely the style. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Compare source and target numerical claims, and verify unit conversion independently wherever a genuine conversion is offered. Keep a source snapshot so that the team can detect obsolete target wording after an upstream correction.
32. Test plural and grammatical alternatives in the frontend
A headless CMS often stores content copy while interface pluralization is handled by application code. Squidex localizable fields do not automatically make every runtime message grammatically sound. 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.
An event site says one seat remains or five seats remain, with different inflection rules in different languages. 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.
Building plural copy from English singular-plus-s can produce wrong or disrespectful messages in several languages. 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 zero, one, two and larger counts with the actual target-language runtime messages. Use a lower-privilege account for the workflow test and a signed-out browser for the public delivery test.
33. Check directional text and mixed scripts
Some locales use right-to-left scripts, but product codes, email addresses and measurements may remain left-to-right. Field translation alone cannot fix layout directionality. 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 Arabic page includes a registration code, a URL and an English source citation alongside Arabic instructions. 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.
Unisolated mixed text may render in confusing visual order and cause errors when readers copy identifiers. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Use a real device and assistive technology to inspect order, punctuation and copy-paste results. Test a complete locale, a partial locale and an unsupported locale as distinct input states.
34. Build a locale-aware content export
Translation suppliers may need only translatable content, structured context and stable identifiers rather than an entire database dump. 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 Finnish translator receives a list of titles, descriptions and image explanations, matched to record IDs and source revisions. 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.
Sending invariant data as if it were prose wastes work and risks accidentally modifying codes and citations. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Export one model with locale fields, source references and context; then re-import into a disposable test environment. Do not equate a successful API response with a publishable page until the real rendered output has been inspected.
35. Stage a reversible migration before changing schema
Because localizable selection matters at field creation, schema improvements should be rehearsed with both raw data and consumer applications. 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 publisher migrates an invariant summary to a new localized field and must keep old public clients functioning during transition. 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 rushed rename can break queries, deindex pages or lose translations that had been manually entered. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: Document mapping, backups, read-compatibility, rollback and integrity checks before committing. Reproduce the result with caches warmed in the opposite language to expose mis-keyed multilingual delivery.
36. Use a bilingual glossary tied to reader tasks
A useful translation glossary explains what readers are trying to do as well as how terms are rendered. The same word may mean different things in different parts of a product. 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 museum uses collection for a curated group, while its payments page uses collection for receiving money. 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.
One universal replacement could make either explanation confusing despite matching a dictionary entry. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Provide context, rejected alternatives and an example sentence to each reviewer for ambiguous recurring terms. Include a negative test: deliberately remove one translated field and inspect the visible fallback or error.
37. Run a clean-device end-to-end language test
The reliable final test starts with an anonymous visitor rather than an authenticated editor. It includes deep links, search, fallback and mobile display. 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 Swedish visitor opens a shared link, changes to Finnish, uses a form and returns through browser history. 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 happy-path editor preview might never expose stale caches, incorrect canonical tags or lost route language. This is why editorial review and technical testing must be independent: a valid configuration does not guarantee a valid statement.
Practical verification: Record the path from first URL to final action and capture the content language at each step. Save the expected outcome next to the observed outcome; if they differ, identify the owning team before changing configuration.
38. Set a measured launch threshold
Completeness is a coverage decision: count approved fields and reader journeys rather than simply enabled locales. A pilot release can be narrower but must be transparent. 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 charity may safely launch ten fully reviewed Swedish pages before translating its entire historical archive. 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.
Declaring the whole site Swedish-ready when critical notices remain English makes promises the product has not met. If a reader acts on the content, the cost of that mistake is measured in understanding and decisions, not merely visual inconsistency.
Practical verification: Publish a coverage matrix by content family, language, review owner and effective source version. Repeat the experiment after a small source edit to prove that your update policy continues to work when content evolves.
39. Keep release evidence after launch
Translation quality changes when source items, linked pages or public policies change. A one-time successful launch test is not enough. 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 emergency guide is updated months after its Finnish variant was reviewed and cached at the edge. 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 saved evidence the team cannot distinguish a newly introduced regression from a long-standing unreviewed gap. An error can survive an attractive layout and a successful HTTP response, making it especially important to test the underlying meaning.
Practical verification: Store accepted URLs, sample API payloads, reviewer decisions and a dated change log for follow-up checks. 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 Squidex localizable fields, ordered language fallbacks and REST API language headers, 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.