How do you translate a DatoCMS website professionally without losing localized fields, breaking GraphQL queries or publishing a misleading multilingual page? This DatoCMS localization guide explains locale configuration, content models, optional translations, fallback locales, Content Delivery API requests and international SEO checks for a world-facing website.
A reliable DatoCMS multilingual workflow begins with a simple decision: which fields should change with language, which facts should remain shared and which target-language pages are genuinely ready for readers? Editors can manage localized fields in the CMS, but developers still need to retrieve the intended locale and render a usable public page. The two jobs must agree.
The practical path is to audit locales, localize only the appropriate fields, decide whether missing content may fall back, review text and linked records, request the right GraphQL values, and verify live routes, accessibility and search metadata. The lessons below show how to do each part without confusing editorial translation with application configuration.
Quick working summary. Use DatoCMS project locales and field-specific localization; define required and optional translations, request the right locale and ordered fallbacks through its Content Delivery API, and verify the rendered page, links, images and international SEO.
- Start with the locale and content model, not a translation button.
- Separate reader-facing wording from system identifiers and shared facts.
- Test the CMS response and the live page independently.
- Document fallback, approval, accessibility and search behavior before release.
- Keep source records stable and change only the intended localized fields.
What this guide teaches and what it does not claim
This is a complete practical guide for editors, translators, engineers and international website teams using DatoCMS. It focuses on DatoCMS rather than on general translation speed or abstract literary theory. Examples are illustrative, not a promise that any particular application has installed integrations or enabled a paid feature. Platform features evolve, so configuration must be checked against the linked official documentation before changes are made.
Our running example is a fictional public garden visitor guide with timed exhibition bookings. It has a title, concise description, long explanation, image description, related content, one action link and a search preview. We will preserve one content identity, approve natural target-language wording and test the public routes. An editor should be able to explain the result in ordinary language even if a developer manages the code.
There is a useful difference between translation, localization and publication. Translation conveys meaning between languages. Localization also handles local usage, conventions, navigation, images and cultural expectations. Publication makes the correct approved experience available through the public site. DatoCMS participates in this chain, but it does not replace the editorial judgment needed at the beginning or the independent checks needed at the end.
The central platform distinction
DatoCMS models localization at the field level. Project locales are configured in site settings; the editor can show locale tabs for localized fields. Models may require every locale or allow partial translations, and adding locales can affect validations on existing records. In the Content Delivery API, a query can request a locale and an ordered list of fallback locales, while particular fields can have their own locale arguments. These features make careful editorial policy essential: a valid GraphQL response is not necessarily an approved localized page.
A translation workflow is only as trustworthy as the agreement between its content model and its public behavior. In DatoCMS, begin by writing down the precise unit being localized, the locale key by which it is requested, the fallback rule and the way a target version becomes public. For every field, ask whether an absent translation should show a known fallback, remain empty or make the page unavailable. The answer depends on the purpose of the page, not merely on the default configuration.
A museum exhibit, for example, can sometimes show an English caption beneath a translated photograph, provided the bilingual presentation is honest. A medical instruction, legal condition, purchase consent or emergency warning may require a stricter rule. Do not silently claim that a whole page is translated when its most consequential section remains in another language. Test these cases as business decisions as well as software behavior.
The complete learning sequence
1. Inventory project locales
The set of available languages belongs to the DatoCMS project configuration, not to the translator’s preferred spelling of a locale code. The useful question is not whether a value exists in the editor; it is whether the intended reader receives the right value on the right route.
Open the locale settings, identify the actual codes and record which audience each serves; compare this list with the routes that the website already exposes. Work with one real document rather than an abstract feature checklist. Record the source state, the target-language decision and the public result before you call the job complete.
A label such as French cannot decide whether a project needs French for France, Canada or a more general audience. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The locale ledger matches the project settings and a tested target route. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
2. Choose fields instead of translating everything
DatoCMS fields are localized individually, so a title or body can vary while a stable booking identifier or relationship remains shared. It helps to separate an editorial choice from a software capability. A platform can store a translation correctly while a template, query or release process still serves the wrong version.
Mark the model’s reader-facing fields and explain why each is translated, shared or derived from data. Before scaling this change, use a small representative sample. Include an ordinary page, a difficult page, a missing value and a piece of content with linked records.
Localizing a product code or a venue identifier can separate facts that should continue referring to one object. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A model review identifies every localized field and every shared field. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
3. Understand required locales
A model can require all locales or allow some records to exist in only selected locales; that choice changes how editors save work. Think of the translation as part of a chain: authoring, storage, retrieval, rendering and discovery. Weakness at any link changes what a visitor actually understands.
Set a publication rule for optional translations and distinguish a record missing in one language from a field that is merely blank. A reliable team names the person who can approve the language, the person who can change the implementation and the person who can verify a published page. Those are different responsibilities.
An all-locales-required rule can block partial editorial workflows when a new market is introduced. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A deliberate partially translated record behaves as the team expects. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
4. Plan adding new locales
New languages can interact with existing field validations; previously valid records may require attention when localization requirements expand. The tempting shortcut is to inspect a successful English screen and assume that success transfers to the other languages. It often does not.
Test a locale addition in a safe environment and inspect required-field validation before introducing it into a busy production editorial schedule. Open the target-language page without the editor logged in. Follow its links, inspect the visible metadata and repeat the route through search or a direct deep link.
The assumption that adding a locale is always a harmless dropdown change may interrupt ordinary content edits. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The team has documented which records and validations change. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
5. Treat fallback as an editorial policy
An ordered fallback list is useful when translations are incomplete, but its convenience should not obscure the visitor’s actual language experience. Good localization preserves identity while allowing expression to change. The visitor should encounter natural wording without a second product, article or instruction accidentally being invented.
Write a fallback decision for each class of page and tell reviewers when mixed-language content is acceptable. Treat identifiers, prices, access rules and dates as controlled facts. Translate their explanations, but only modify the facts through the system that owns them.
A fallback can make an incomplete checkout instruction look superficially finished. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A missing field produces the documented result rather than an accidental language mixture. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
6. Request the locale in GraphQL
The DatoCMS Content Delivery API can return localized values using a locale argument, rather than requiring separate unrelated content entries. There are two different completion points: a translator finishes a sentence, and a reader receives a coherent experience. The second point is the one that matters.
Use the actual schema and configured locale code in a representative query; compare the localized result with the source result. A practical review should include mobile display, screen-reader labels where applicable, navigation between related pages and a rollback route for serious mistakes.
Fetching the default locale and displaying it under a translated URL gives a false impression of localization. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The query and browser agree on which locale was requested. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
7. Understand field-level locale arguments
DatoCMS GraphQL can request a locale at the query level and, where supported, another at an individual field, which is helpful for controlled comparisons. The first version may look convincing precisely because fallback content fills the gaps. That is convenient during development but dangerous when a page is described as fully translated.
Use explicit aliases for comparison fields during tests so reviewers can see both source and target text. Record which fields are intentionally untranslated. Distinguish permitted bilingual fallbacks from accidental leaks, especially in headings, calls to action and legal instructions.
A query that mixes locale arguments without clear names creates a response that is difficult to interpret. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A side-by-side source and target query produces clearly labelled values. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
8. Order fallback locales
The fallbackLocales argument is an ordered list; its sequence matters when more than one nearby language could provide a missing value. Multilingual publishing is easier when a team can explain why each field is localized, shared or generated. Without that explanation, reviewers confuse missing text with configuration errors.
Document whether a regional locale first tries its base language and then a carefully approved wider language. Use a miniature release ledger: item ID, locale, owner, review state, requested route, observed route and final decision. Evidence makes later corrections much faster.
An arbitrary order may show a distant region’s terminology before a suitable nearby variant. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A deliberately empty field resolves to the expected first available fallback. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
9. Inspect empty strings and arrays
Missing values need careful testing because empty strings and empty arrays can participate in fallback behavior, not merely database nulls. The useful question is not whether a value exists in the editor; it is whether the intended reader receives the right value on the right route.
Try a blank title, an empty list and an absent optional description in a staging record and compare results. Work with one real document rather than an abstract feature checklist. Record the source state, the target-language decision and the public result before you call the job complete.
A frontend may treat an empty value as intentional while the API resolves it through fallback. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
Tests record the distinction between no value and an intentionally blank presentation. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
10. Separate language from publication state
A translated draft and a translated published page are different experiences, regardless of whether both are visible to editors. It helps to separate an editorial choice from a software capability. A platform can store a translation correctly while a template, query or release process still serves the wrong version.
Audit which content is available through the delivery environment used by the public site and who approves releases. Before scaling this change, use a small representative sample. Include an ordinary page, a difficult page, a missing value and a piece of content with linked records.
Preview success can conceal a production endpoint that still serves an earlier translation. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The public delivery response contains only the intended approved version. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
11. Model translated titles and descriptions
Search titles, descriptions, headings and summaries should speak to the target reader’s task instead of mechanically mirroring English keywords. Think of the translation as part of a chain: authoring, storage, retrieval, rendering and discovery. Weakness at any link changes what a visitor actually understands.
Review the opening sentences and page metadata in the target language with a reader familiar with local search terms. A reliable team names the person who can approve the language, the person who can change the implementation and the person who can verify a published page. Those are different responsibilities.
Word-for-word SEO language often sounds foreign and can misstate what a service actually offers. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The metadata accurately describes the rendered page for that market. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
12. Protect stable relations
Relationships between an exhibit and its venue, or an article and its author, should continue to identify the same underlying object across languages. The tempting shortcut is to inspect a successful English screen and assume that success transfers to the other languages. It often does not.
Check related records and decide whether their display fields also need localization before rendering linked cards. Open the target-language page without the editor logged in. Follow its links, inspect the visible metadata and repeat the route through search or a direct deep link.
A translated article pointing to the wrong target-language relation can strand a visitor halfway through a journey. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The linked record retains identity and the visible label matches the requested locale. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
13. Review rich-text content
Long-form structured text contains emphasis, links, blocks and sometimes embedded content; translating its words alone may leave the surrounding behavior broken. Good localization preserves identity while allowing expression to change. The visitor should encounter natural wording without a second product, article or instruction accidentally being invented.
Ask a reviewer to traverse a representative rich-text page and test its embedded links, captions and inline labels. Treat identifiers, prices, access rules and dates as controlled facts. Translate their explanations, but only modify the facts through the system that owns them.
A translated heading above an unchanged instruction widget is a common partial-localization error. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The complete long-form page remains coherent when read from beginning to end. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
14. Handle images and alt text
A shared image can work in multiple countries, but text inside the image and its accessibility description may need language-specific review. There are two different completion points: a translator finishes a sentence, and a reader receives a coherent experience. The second point is the one that matters.
Inventory image captions, alternative text and graphics containing words before reusing source media. A practical review should include mobile display, screen-reader labels where applicable, navigation between related pages and a rollback route for serious mistakes.
A polished translated article can still show an English diagram that is crucial for comprehension. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
Images and alternative descriptions communicate the same intended meaning. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
15. Build locale routes
DatoCMS stores content; the site application is responsible for turning approved locale-aware data into understandable public URLs. The first version may look convincing precisely because fallback content fills the gaps. That is convenient during development but dangerous when a page is described as fully translated.
Document route patterns, language switch behavior, canonical decisions and localized slugs where the application supports them. Record which fields are intentionally untranslated. Distinguish permitted bilingual fallbacks from accidental leaks, especially in headings, calls to action and legal instructions.
A CMS locale alone does not guarantee that a URL has switched languages or preserved the same content identity. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
Deep links and language switches resolve to the intended page. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
16. Publish without false language coverage
A page should not appear in a site’s translated navigation solely because one localized title is available. Multilingual publishing is easier when a team can explain why each field is localized, shared or generated. Without that explanation, reviewers confuse missing text with configuration errors.
Establish a minimum content threshold and release policy for each content class, then mark unavailable target pages honestly. Use a miniature release ledger: item ID, locale, owner, review state, requested route, observed route and final decision. Evidence makes later corrections much faster.
Search engines and visitors can discover thin or incomplete pages when availability is inferred from a single field. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The navigation exposes only approved, useful experiences. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
17. Cache localized results correctly
GraphQL results and frontend caches may reuse data across routes unless locale is included in the retrieval and cache strategy. The useful question is not whether a value exists in the editor; it is whether the intended reader receives the right value on the right route.
Check request variables, cache keys and invalidation after a target-language edit in a staging environment. Work with one real document rather than an abstract feature checklist. Record the source state, the target-language decision and the public result before you call the job complete.
A stale cached headline can survive long after the translator has corrected the content. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
Two consecutive updates appear in the correct locale after publication. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
18. Check model migration consequences
Changing a model from shared to localized alters editorial expectations and may affect existing records or code that reads the field. It helps to separate an editorial choice from a software capability. A platform can store a translation correctly while a template, query or release process still serves the wrong version.
Inventory affected queries and content before changing field localization; migrate deliberately and test rollback. Before scaling this change, use a small representative sample. Include an ordinary page, a difficult page, a missing value and a piece of content with linked records.
An unplanned schema change can make old queries or integrations assume a value exists in the wrong shape. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
Both old content and new localized content work through the supported API. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
19. Work with regional wording
The same language can require different opening hours phrasing, cultural references, measurements and terms for different audiences. Think of the translation as part of a chain: authoring, storage, retrieval, rendering and discovery. Weakness at any link changes what a visitor actually understands.
Write a region note beside the termbase so reviewers know when one variant may inherit from another. A reliable team names the person who can approve the language, the person who can change the implementation and the person who can verify a published page. Those are different responsibilities.
Treating every regional difference as mere spelling can hide important service eligibility or legal distinctions. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A regional reader finds accurate and natural instructions. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
20. Control machine-assisted suggestions
Automatic translation suggestions, where a team uses them, should be treated as drafts requiring review rather than as evidence of target-language accuracy. The tempting shortcut is to inspect a successful English screen and assume that success transfers to the other languages. It often does not.
Protect numerals and entity names, maintain a short glossary and review consequential statements with a responsible human. Open the target-language page without the editor logged in. Follow its links, inspect the visible metadata and repeat the route through search or a direct deep link.
Fluent output can quietly change negation, scope or conditions even when a sentence looks natural. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A reviewer can trace final wording to an approved source meaning. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
21. Audit language-specific accessibility
The frontend should declare the appropriate document language and provide meaningful labels, alternative text and usable control order. Good localization preserves identity while allowing expression to change. The visitor should encounter natural wording without a second product, article or instruction accidentally being invented.
Run keyboard, screen-reader and narrow-screen checks in a target locale rather than using English as a proxy. Treat identifiers, prices, access rules and dates as controlled facts. Translate their explanations, but only modify the facts through the system that owns them.
A perfectly translated body does not fix an unlabelled language selector or unreadable embedded control. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A person can complete the page task without relying on source-language labels. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
22. Inspect hreflang and canonical behavior
International search presentation is implemented by the public site and must point to actual equivalent experiences. There are two different completion points: a translator finishes a sentence, and a reader receives a coherent experience. The second point is the one that matters.
Compare the target route, page title, canonical URL, alternate-language links and sitemap entry after publication. A practical review should include mobile display, screen-reader labels where applicable, navigation between related pages and a rollback route for serious mistakes.
Incorrect alternate links can send search users to missing, unrelated or wrong-language pages. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
Every advertised language URL returns useful corresponding content. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
23. Design a translation release ledger
Publishing across multiple locales creates a coordination problem: source edits, target reviews and cache invalidations need a traceable record. The first version may look convincing precisely because fallback content fills the gaps. That is convenient during development but dangerous when a page is described as fully translated.
Keep item ID, locale, field owner, source revision, translation approval, publishing time and test route together. Record which fields are intentionally untranslated. Distinguish permitted bilingual fallbacks from accidental leaks, especially in headings, calls to action and legal instructions.
Without a ledger, a team cannot tell whether a target page is stale or intentionally different. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
A reviewer can reproduce a change and its evidence from the log. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
24. Run regression tests on representative records
A multilingual regression suite should include ordinary fields, arrays, linked content, rich text, missing translations and a fallback order. Multilingual publishing is easier when a team can explain why each field is localized, shared or generated. Without that explanation, reviewers confuse missing text with configuration errors.
Build fixtures that distinguish default, explicit target and fallback responses, then run them before a rollout. Use a miniature release ledger: item ID, locale, owner, review state, requested route, observed route and final decision. Evidence makes later corrections much faster.
Testing only a successful title request misses the interactions that fail in actual production pages. The result can be subtle: the page still loads and looks polished, yet the visitor receives the wrong instruction, a missing piece of context or a misleading impression of completeness. Compare what was approved with what was retrieved, then compare both with what the public page displays. These are three different observations, not one test.
The same fixtures pass after model and application updates. Keep a short record of the exact document, selected locale, expected wording and observed output. Ask a reviewer who did not create the content to explain what the page says and where the next link goes. If that reviewer has to guess, the implementation needs another pass even if the API call succeeded.
Worked example: one document, three reader experiences
Worked step 1: Create the English source record
Create one authoritative a fictional public garden visitor guide with timed exhibition bookings record and give it a stable internal identity. Include a title, short description, detailed explanation, action label, linked item, image alternative text and a search description. Keep the factual constraints—such as eligibility and opening information—under the control of their proper owners.
To make this step teachable, show an editor a source screenshot or record, the expected localized text and the rendered target page side by side. Ask them which fields belong to the publisher, which belong to the translator and which are stable application data. Invite them to identify a realistic failure before they see the answer. That habit builds better reviewers than a checklist that everyone merely ticks.
Worked step 2: Prepare the first target locale
Choose a language and region because they serve real readers, not just because the CMS permits another code. Ask the translator to write for that audience while respecting the source facts. Review style, terminology, line length and links together; do not judge the output solely by whether every source sentence has an apparent counterpart.
To make this step teachable, show an editor a source screenshot or record, the expected localized text and the rendered target page side by side. Ask them which fields belong to the publisher, which belong to the translator and which are stable application data. Invite them to identify a realistic failure before they see the answer. That habit builds better reviewers than a checklist that everyone merely ticks.
Worked step 3: Handle a regional variant
Decide whether the second target needs wholly different content or only a few regional differences. When a fallback is appropriate, make the order explicit. When the regional version changes eligibility, contact details or legal expectations, preserve the distinction rather than inheriting the wrong words merely because the language is similar.
To make this step teachable, show an editor a source screenshot or record, the expected localized text and the rendered target page side by side. Ask them which fields belong to the publisher, which belong to the translator and which are stable application data. Invite them to identify a realistic failure before they see the answer. That habit builds better reviewers than a checklist that everyone merely ticks.
Worked step 4: Inspect missing content
Temporarily leave one noncritical localized field empty in a staging copy. Fetch the content through the same mechanism as the application and observe whether the value is blank, inherited or rejected. Repeat with a critical action label. These two results may need different release rules even if the database treats both fields alike.
To make this step teachable, show an editor a source screenshot or record, the expected localized text and the rendered target page side by side. Ask them which fields belong to the publisher, which belong to the translator and which are stable application data. Invite them to identify a realistic failure before they see the answer. That habit builds better reviewers than a checklist that everyone merely ticks.
Worked step 5: Follow the public route
Request the target URL directly in a clean browser session, including on a narrow mobile screen. Navigate from a related article, inspect the page title and description, and use the language switcher. A successful editor preview is not evidence that visitors, search engines or screen readers receive the intended content.
To make this step teachable, show an editor a source screenshot or record, the expected localized text and the rendered target page side by side. Ask them which fields belong to the publisher, which belong to the translator and which are stable application data. Invite them to identify a realistic failure before they see the answer. That habit builds better reviewers than a checklist that everyone merely ticks.
Worked step 6: Approve or roll back
Require named approval for language quality and implementation quality. If a serious mismatch appears, withdraw the affected target version or restore the last approved version using the site’s documented process. Record what changed and retest the failed route. Do not silently rewrite the source record to make a translation problem disappear.
To make this step teachable, show an editor a source screenshot or record, the expected localized text and the rendered target page side by side. Ask them which fields belong to the publisher, which belong to the translator and which are stable application data. Invite them to identify a realistic failure before they see the answer. That habit builds better reviewers than a checklist that everyone merely ticks.
A four-week implementation and teaching plan
Week 1 — Model and inventory
List supported locales, intended audiences, existing source records, field ownership, editorial approvals and public routes. Translate no large batches yet. Select five representative content items: a typical page, a long page, a linked page, a page with sensitive instructions and a page with intentional missing translations. Document what the platform can do and what the frontend must implement.
The deliverable is not simply a count of translated strings. Produce a concise evidence pack with approved wording, screenshots or response samples, route checks, unresolved issues and a named next action. A small project with strong evidence is a better foundation for scaling than a large project whose most difficult cases have never been tested.
Week 2 — Translate and review
Prepare a terminology sheet and reviewer brief, then localize the representative sample. Review meaning before punctuation, and punctuation before visual polish. Use a native or professionally qualified reviewer where stakes warrant it. Check headings, body copy, buttons, alt text, validation messages and any region-dependent claims. Keep recorded decisions so two translators do not invent competing names for the same feature.
The deliverable is not simply a count of translated strings. Produce a concise evidence pack with approved wording, screenshots or response samples, route checks, unresolved issues and a named next action. A small project with strong evidence is a better foundation for scaling than a large project whose most difficult cases have never been tested.
Week 3 — Integration and testing
Connect locale-aware retrieval to real routes and test fallback behavior, linked entries, cache refresh and publication state. Compare an API response with the browser result. Run direct-link, language-switch, mobile, keyboard and search-metadata checks. Include negative tests: an unsupported locale, an absent field, a deleted translation and an unpublished target version. Fix the system rather than masking failures with generic English copy.
The deliverable is not simply a count of translated strings. Produce a concise evidence pack with approved wording, screenshots or response samples, route checks, unresolved issues and a named next action. A small project with strong evidence is a better foundation for scaling than a large project whose most difficult cases have never been tested.
Week 4 — Controlled publication
Release a small set of reviewed pages, gather feedback from actual target-language users and confirm analytics can distinguish locales without recording unnecessary personal information. Keep a rollback owner and a review schedule. After launch, monitor changes to the source record; a translated page can become stale even when its original publication was completely correct.
The deliverable is not simply a count of translated strings. Produce a concise evidence pack with approved wording, screenshots or response samples, route checks, unresolved issues and a named next action. A small project with strong evidence is a better foundation for scaling than a large project whose most difficult cases have never been tested.
Twelve practical questions before a release
1. Is the locale real and consistently named?
Compare editor configuration, API parameter, frontend route, analytics grouping and alternate-language metadata. A mismatch can create two apparently different languages or route visitors back to the default experience. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
2. Is the content identity stable?
Changing a translated title should not create an unrelated record or break a relation. Follow a linked item and check that its identity and language behavior are documented. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
3. Is the translation complete enough for this page?
Define completion by reader tasks, not by string count. A translated headline above an English consent instruction is not a complete localized journey. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
4. What happens when a value is missing?
Test absence deliberately. Distinguish null data, blank editorial text, configured fallback and an application bug before choosing the release behavior. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
5. Can a translator edit only what they own?
Review permissions and editorial workflow. Stable identifiers, facts and publication controls should not all become editable merely because text needs translation. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
6. Are numbers and legal claims still correct?
Do not alter prices, eligibility, measured quantities, safety limits or contractual meaning through an unreviewed wording change. Send ambiguities to the authoritative owner. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
7. Do buttons and forms work in the target language?
Submit a safe test form, inspect validation feedback and follow the confirmation screen. Translation failures often occur after the first visible page. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
8. Does mobile presentation remain usable?
Longer words and different writing systems change wrapping. Check headings, navigation, input labels and narrow-screen controls with actual target-language strings. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
9. Does accessibility survive localization?
Check meaningful alternative text, visible focus, correct reading order and language declarations. A text field can be grammatically correct while the experience is inaccessible. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
10. Do search results describe the correct page?
Compare metadata, page content, canonical handling, alternate-language links and sitemap behavior. Search discovery belongs to the rendered site, not just the CMS. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
11. Can the team trace an error?
Preserve record ID, locale, requested URL, observed value, reviewer and time. Vague bug reports such as ‘French is broken’ are expensive to reproduce. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
12. Can the team safely reverse a release?
Practice reverting a single localized item without deleting approved content in other languages. The rollback path is part of quality, not an afterthought. For this check, write down one passing example and one plausible failing example drawn from your own application. The difference between the two should be visible to a reviewer who has not seen the code. If the result depends on a hidden assumption, document that assumption before publication.
Common questions
Is DatoCMS a machine translation service?
No. DatoCMS is the content-management context for this guide. Translation engines, human language work, permissions and publishing infrastructure may be separate. Verify a specific integration before promising automatic translation or automatic approval.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
Should every field be localized?
No. Translate reader-facing language when an audience needs it. Retain stable identifiers and shared facts where appropriate. Some fields require regional variants rather than linguistic translation; others should remain global.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
Should missing values always fall back to English?
No. Fallback can help on low-risk content but can mislead readers when essential instructions are absent. Choose an explicit, field- and context-aware policy and check what actually renders.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
Can a correct CMS response still result in the wrong webpage?
Yes. Routes, templates, caches, client state and links can all serve the wrong language after correct data retrieval. Check the public experience separately.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
Does localized content automatically create international SEO?
No. The frontend still has to expose useful locale-specific routes, appropriate titles and descriptions, honest canonical relationships and any alternate-language signals the site chooses to implement.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
What is the best way to start?
Use one representative item with all the awkward parts: long text, linked objects, a missing field, an image, a button and a regional difference. Make that complete before converting a thousand easy titles.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
How should a team measure quality?
Use meaning accuracy, field completeness, route correctness, user task completion, accessibility, critical-error count and the ability to reverse a bad release. Raw string counts are a narrow productivity measure.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
Who should approve the final page?
The responsible language reviewer checks meaning and audience fit; the technical reviewer confirms data, route and rendering; the content owner approves sensitive facts and the publication decision. These responsibilities can be combined in a small team but must not disappear.
When the answer is uncertain, reproduce the question with a named locale and one content record. Avoid choosing a global policy from a single screenshot. Write down the expected behavior, perform the check and make the policy visible to the next person who handles the same class of content.
Official documentation and related learning
DatoCMS localization concepts — official guidance on project locales, field localization and optional or required translations
DatoCMS Content Delivery API localization — official examples of locale queries and fallbackLocales
Translate Like a Pro | Series Index — the platform implementation guides in the wider translation learning architecture.
Master Art of Translation | TBX 3.0 and ISO 30042 — a deeper guide to controlled terminology and translation evidence.
Final understanding
The decisive question is simple: can someone who has never seen your source-language editor reach the correct DatoCMS content, understand it naturally, use its links and trust its instructions? If not, more translated strings will not solve the problem. Return to the content model, the chosen locale, the approval process or the public rendering step that failed. Good translation is a chain of reliable decisions, not a collection of attractive words.
A mature multilingual site has an owner for its language decisions, an auditable record of what was approved, a tested way to serve it, and a straightforward way to correct errors. Build those habits before expanding into more markets. They will save time, protect reader confidence and make every later translation more useful.