dotCMS Translation and Localization Guide

How do you use dotCMS to create a reliable multilingual website without mixing up language settings, translated content, routes and publication status? This dotCMS multilingual content guide explains the actual platform features, practical editor and developer decisions, and the checks needed before visitors see a translated page. It is written for CMS administrators, content editors, frontend developers and release reviewers managing multi-language dotCMS sites in any country.

The important distinction is that language availability is not the same as translation accuracy. A site can expose a locale selector yet show the wrong record, an untranslated component, an outdated claim or a draft that has not been approved. This walkthrough concentrates on dotCMS contentlet language versions, global Language Variables, default-language fall-through, preview, language IDs and release workflows. It separates text that readers may need adapted from codes, dates, references and actions that must keep their original factual meaning.

If you are searching for how to translate dotCMS content, begin with the quick steps below, then use the detailed examples, troubleshooting cases and release checks to build your own workflow. You will learn what to configure, what to translate, what should remain stable, how to recognize a genuine defect, and what evidence to collect before launching another language.

What this dotCMS guide covers

The article gives a practical approach to dotCMS contentlet language versions, global Language Variables, default-language fall-through, preview, language IDs and release workflows. It does not promise universal functionality across every edition, tenant, plugin or historical version. The platform documentation named later is the reference for available features. Where a capability is described as a beta, optional extension or plan-dependent feature, the article treats it as something to verify rather than something every account already possesses.

The fast route: from one source page to a trustworthy translated release

Configure languages, locale identifiers and the default language intentionally
Create and preview separate language versions of contentlets, pages and files
Use Language Variables for global UI strings rather than storing copy in every page
Test independent page, widget, file and content fallback controls
Understand push-publishing behavior and preserve each language’s draft or live state

A good first launch is deliberately small. Choose one real page and one reusable content item, then include a visible interface label, a long paragraph, a date, an external link and a field that must remain unchanged. Translate the copy, review it in context, publish only the approved locale, and follow the experience from an ordinary visitor’s browser. Keep the failed examples as part of the team’s test set; they are as educational as the successful cases.

A worked world-facing project

A public research library operates websites for visitors in English, German and Spanish. Research descriptions and individual event listings are translated by different editors; shared labels such as ‘Search catalogue’ appear across site templates. The library has a strict requirement that an unpublished Spanish notice remain unpublished while the English event listing goes live. A configurable fallback must never disguise the fact that a critical notice is not yet localized.

The immediate editorial question is not ‘How many words can we translate today?’ It is ‘Which version of this fact will each reader actually receive?’ Build a small inventory with a source URL, content identity, locale, editorial owner, approval state, references and public delivery route. When an issue occurs, the team should be able to identify exactly whether the problem came from a missing localized record, an outdated translation, an incorrect component, a live-versus-draft mismatch, or a frontend language decision.

Use three categories of content. Translate explanations and visitor-facing labels in natural language. Localize regional conventions such as addresses, examples, date presentation and approved calls to action only when the underlying purpose permits it. Preserve invariant facts: record identifiers, unconverted numerical values, study codes, unique references and the actual state of an action. Sometimes a sentence must be rewritten to express the same instruction; sometimes it must not be changed until the local owner has checked whether the procedure itself is different.

A safe division of responsibilities

A content editor owns whether the page says something appropriate and up to date. A language reviewer owns whether the target-language reader will understand the same decision. A developer owns route resolution, locale parameters, rendering, caching and technical accessibility. A publisher owns the moment the work becomes visible and the record of its approval. In a small team one person may hold more than one role, but the checks should remain separate; software does not automatically merge their responsibilities.

A short release specification can fit on one page: the exact supported locales; the authoritative source version; who can edit which content; the deliberate fallback behavior; what counts as a completed translation; which public routes should exist; and how an urgent correction is handled. Write it before expanding to dozens of languages. This saves repeated arguments later because the team’s actual choices have been recorded.

The platform mechanisms that matter first

1. Configure languages, locale identifiers and the default language intentionally. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
2. Create and preview separate language versions of contentlets, pages and files. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
3. Use Language Variables for global UI strings rather than storing copy in every page. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
4. Test independent page, widget, file and content fallback controls. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
5. Understand push-publishing behavior and preserve each language’s draft or live state. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.

The sections that follow use individual problems rather than a single idealized happy path. Each explains an implementation decision, a worked situation, a likely failure, a repair principle and a proof test. They are not a substitute for checking the installed dotCMS version. They are a structured way to avoid producing multilingual content that looks polished in the editor but fails in the visitor’s real workflow.

1. Content versions and language identity

dotCMS can store multiple language versions of a contentlet without treating them as unrelated editorial items. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A Spanish description and English description refer to the same exhibition record and must not become duplicate exhibitions. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Duplicating the content item for each language can fragment references, analytics and update ownership. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Work through the language-version control on the existing item and maintain its identity while translating the appropriate content. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Retrieve the item in both languages and verify identifiers, relationships and language-specific descriptions. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

2. Locale setup and language codes

dotCMS locale tools use language and country information to identify regional versions. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. The library publishes German for Germany and a future German-language version intended for Austria. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A team may confuse the language code with the country code and attach an Austrian event notice to the wrong region. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Agree on locale nomenclature before creating many documents and store the exact codes alongside external application routing. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Inspect the locale list and reproduce one content request for each intended code. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

3. Choosing a default language

The system default influences content lookup and the direction of configured fall-through behavior. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A library begins with English, then proposes Spanish as the default before Spanish event records are complete. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Changing the default without target-language content can make previously visible pages disappear or become inconsistent. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Inventory content, assets and themes before changing a live default; treat the change as a migration with rollback. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Open a test site with no explicit language and confirm every critical page has a usable version. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

4. Adding a target-language content version

Editors can open a content item and create or switch to another language version. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A staff member adds German explanatory text to an English grant announcement. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A mistaken new item can sever the original relationship, while replacing the English field removes source evidence. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Use the language dropdown or supported editor flow, create the German version, and document the source revision. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Compare the same content ID across language views and ensure only intended fields differ. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

5. Populate from an existing language

On first creation dotCMS can offer to populate the new language version from another version. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A Spanish event page retains linked map files and contact references copied from the English source. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Unreviewed imported paragraphs can accidentally be published as if they were translated content. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Treat population as a structural starting point; mark every copied text field for translation and check linked assets. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Preview and inspect references before approving the target version. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

6. Page language versus content language

A page can exist in one language while the content it retrieves has separate language availability. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A German navigation shell contains an embedded library announcement whose German translation is not yet present. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. People may see a translated page title but an empty announcement widget depending on configuration. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Record page, contentlet and widget language states separately and test their combined rendering rather than one item alone. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Switch the page preview language and inspect each content region for empty or wrong-language material. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

7. Default content fall-through

The documented DEFAULT_CONTENT_TO_DEFAULT_LANGUAGE property controls fallback for individual content items. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A German events page requests a Spanish-only item when a translation is missing. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Default values for content fallback differ from page and widget fallback; assuming one global switch is inaccurate. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Decide whether absent translated content should be hidden, substituted or explained, and configure the content setting accordingly. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Request a missing item with and without implicit language context; compare with the documented intended result. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

8. Default page fall-through

The documented DEFAULT_PAGE_TO_DEFAULT_LANGUAGE property handles missing page-language versions. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A user navigates to a German campaign route whose page has no German version. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. The site may present an English page shell inside a German navigational context without a visible explanation. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Choose a page fallback based on reader task and content sensitivity, then test the exact URL behavior. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Open a missing page in a clean session and inspect status, heading, language metadata and navigation. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

9. Widget fall-through

DEFAULT_WIDGET_TO_DEFAULT_LANGUAGE is a separate configuration control for multilingual widgets. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. The footer has a reusable help widget that was translated for English and Spanish but not German. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A default-language widget may show a call-to-action that is inappropriate or outdated in Germany. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Own widget text like a product feature with locale coverage, not an optional decorative block. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Test the German footer in desktop and mobile views after changing the widget version. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

10. File fall-through

DEFAULT_FILE_TO_DEFAULT_LANGUAGE determines how missing translated files may be resolved. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A German visitor downloads a safety leaflet from a translated page but the link resolves to an English PDF. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A file may fall through independently of page or content settings and create a dangerous mismatch. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Audit downloadable files, explicit language labels and version approvals; never present an untranslated attachment as a translated one. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Click every target-language file link and inspect actual contents, name and language. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

11. Explicit language ID overrides

dotCMS documentation warns that specifying language_id explicitly can bypass general fall-through logic. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A custom frontend requests content with a fixed language ID for an international dashboard. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Developers may believe server fallback is active while API queries explicitly exclude it. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Document whether each API call is explicit or contextual and implement a conscious fallback path in the frontend. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Run an API request with explicit missing language_id and compare it with contextual page rendering. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

12. Global Language Variables

Language Variables pair one stable key with values in different configured languages. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A site-wide ‘Renew membership’ label occurs in the header, account page and footer. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Copying the label into many content items causes inconsistent language updates and unnecessary editorial work. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Store shared interface terms as Language Variables and manage their translation coverage centrally. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Change the German value in staging and verify all page locations use the expected variable. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

13. Variable coverage monitoring

The Locales view may indicate how many language-variable translations exist per locale. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. The site has fifty interface variables but only thirty-two translated into Spanish. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. An apparently complete translated page can still show source-language navigation across the experience. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Use coverage as a diagnostic starting point, then prioritize critical variables by impact rather than percentage alone. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. List missing variables, review the visible UI and record which gaps block release. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

14. Language-specific navigation

Menus and pages may be driven by multilingual content and language-aware navigation APIs. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A Spanish user opens the research collections index and follows a category link to the correct locale. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A menu entry can lead to the English destination even when the label itself is in Spanish. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Test each nav target as an executable route, not merely a translated string. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Follow a representative child path through all menu levels and record final locale. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

15. Static endpoint language

The Navigation REST API accepts language-related parameters and returns published navigation content. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A frontend builds its menu from /api/v1/nav for a locale-specific library site. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. An omitted or incorrect languageId can show default labels and routes while the page body is localized. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Bind navigation retrieval to the resolved visitor locale and test its behavior with fall-through intentionally enabled or disabled. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Compare API response paths for two locale values and inspect the actual rendered menu. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

16. Page preview by language

Editors can preview a page with a chosen display language to examine composed content. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. The Spanish editor checks a grant information page before it is added to the public sitemap. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Previewing the contentlet alone cannot prove that the surrounding page selects the correct localized widgets and files. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Review a complete page in the Site Browser, including navigation, sidebar and download links. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Capture preview and live screenshots separately and compare critical text and content state. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

17. Draft and live language states

Different language versions may have different publication states even when sharing an item identity. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. The English library event is published while the German details remain a draft pending legal review. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Treating the item as globally approved may expose unreviewed target wording to a public API. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Record approval per language and review both item status and what the public visitor retrieves. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Use signed-out requests to confirm German draft copy is not visible while English remains published. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

18. Push Publishing bundles

dotCMS notes that pushing one contentlet language version may send all its language versions in their current states. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A deployment bundle includes an English published announcement and an unpublished Spanish draft. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Teams may equate ‘transferred to target server’ with ‘published live’, or accidentally rely on stale target versions. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Review every included language state, use a test destination and keep deployment evidence for the full contentlet. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. After pushing, confirm each target locale keeps its intended published or draft status. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

19. Selective release strategy

A multilingual launch may require releasing locales on different dates without changing the shared content identity. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A German campaign starts today, whereas Spanish legal review finishes next week. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Publishing every translation at one time can violate local approval requirements even if strings are accurate. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Use separate approval controls and verify deployment and public visibility independently for each market. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Test a future-locale direct URL before and after the intended release boundary. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

20. Template and theme languages

Themes, templates and pages may depend on assets created under a particular language configuration. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A site administrator proposes switching the default language after a new template rollout. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Previously existing theme files and pages may not exist under the new default and could fail unexpectedly. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Inventory site assets and template dependencies before locale migration and test a full staging copy. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Load a representative theme-heavy page in every locale and inspect assets, headers and footer. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

21. Translated metadata and snippets

Search titles, summaries and social preview fields need language-specific review alongside the page body. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A Spanish page description still carries the English headline in a search preview. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Technically correct on-page text does not prevent the wrong-language snippet or image description being indexed. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Store language-specific metadata where the site’s models support it and verify the frontend emits the correct version. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Inspect rendered HTML titles and description fields, then compare social preview data. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

22. Language switchers and URLs

The frontend must map the current item to its existing language versions rather than guessing parallel URLs. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A visitor reads a German research abstract and selects Spanish to compare the original context. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A switcher built by replacing only the URL prefix can reach an absent page or unrelated item. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Resolve language availability using content identity and provide a clear unavailable-version path. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Switch on nested pages, including one missing target version, and confirm the user knows what happened. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

23. Mixed-script and RTL pages

Language support may include Arabic or Hebrew alongside invariant identifiers and English research citations. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A laboratory catalogue displays Arabic explanations around Latin sample codes and chemical names. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Aggressive bidirectional changes can reverse or visually confuse sample identifiers. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Keep identifiers intact, isolate mixed-script spans and require a fluent UI tester when RTL is in scope. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Inspect sample IDs, punctuation, keyboard navigation and a printed catalogue view. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

24. Cache and content invalidation

API and frontend caches can continue to serve older locale responses after editors publish revisions. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A corrected Spanish event date appears in the CMS but old Spanish text remains in the public header. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Cache invalidation based only on item identity can miss a locale-specific published variant. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Include locale in cache keys and invalidate affected route and content-version combinations when publishing changes. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Fetch before and after publish using independent sessions and compare headers, body and update evidence. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

25. Error and empty-state language

Search results, permission errors and empty collection states are content, not merely decorative notices. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A German visitor searches a narrow topic and gets zero results. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A source-language error may imply a search failed when it simply found no results. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Create message ownership for empty states and distinguish no-content, missing-language and genuine server errors. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Trigger each condition in target locales and verify recovery instructions are accurate. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

26. Release matrix and audit trail

An integrated multilingual test must cover content state, fallback, API behavior and related assets. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. The library prepares a three-language site relaunch with dozens of translated event pages. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A single ‘German completed’ checkbox hides differences among pages, contentlets, files and variables. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Build a matrix by locale, object type, state and visitor journey; save version evidence and assigned reviewer. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Execute one published and one missing-language journey for every major object type, then record outstanding defects. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

A release plan readers can actually use

A useful multilingual release is not a ceremony. It is a small set of facts that can be independently checked. Start by confirming which source version was approved and whether the selected language versions refer to that content. Review the most consequential instructions first: restrictions, dates, warnings, forms, money, permissions and promises. Then test the ordinary reading path, the missing-content path, and the action a visitor is most likely to take. Finish with the visible public result rather than a screenshot taken inside an editor.

Record the precise source revision, target locale and responsible editor.
Identify every public URL and API request that must resolve to that locale.
Check dynamic fields, related records, navigation labels, metadata and downloadable assets.
Verify number, date, currency and direction formatting without altering stored values.
Review one successful action, one validation error and one unavailable-content state.
Publish each approved language deliberately and verify from a signed-out client.
Keep a simple issue log with the actual observed failure and the correction tested.

Frequently asked questions

Does dotCMS automatically translate a new content language?

No. Adding a language provides a place to create and manage versions. The workflow may copy existing fields, but editors must translate and validate the intended content.

For a practical diagnosis, repeat the situation with one known record and two different locales. Note whether the failure appears in the editor, content API, rendered page or publishing state. That observation determines which owner should investigate and makes the answer useful in a real dotCMS project rather than a generic translation checklist.

Why does a localized page show blank content?

Pages and contentlets can use different language fallback settings. Test whether a translated contentlet exists and whether your configuration allows content fall-through.

Does explicit language_id obey default fall-through?

The official documentation warns that explicit language_id can override ordinary fall-through rules. Treat explicit API retrieval as a deliberate request for a particular version.

Should language variables be used for every paragraph?

No. They are valuable for reusable UI labels and repeated strings. Editorial articles and descriptions belong in appropriate language versions of managed content.

Does Push Publishing turn every language live?

A push may include all language versions of a contentlet, but each version preserves its own state according to the documented behavior. Transfer and live publication are separate concepts.

Can we safely change the default language after launch?

Only with a full content and asset inventory, staging tests and a rollback plan. A new default does not automatically translate or recreate existing language versions.

Is it enough to test the page editor preview?

No. Verify the public route, navigation, files, metadata, cache and the actual API responses, using signed-out users where possible.

What is the first priority when localization breaks?

Identify whether the defect is a missing language version, an inappropriate fallback setting, an API parameter, or a failed public release. Fix the actual layer rather than merely changing the displayed phrase.

Official documentation and further reading

The following links describe vendor features and their documented behavior. Interfaces and capabilities can change; use the documentation for the installed edition and verify optional or beta features in the actual account before depending on them.

Where this article belongs in the eduKate translation library

Architecture: EDKSG-TRANS-MASTER-WORLD-6220. This child owns dotCMS contentlet language versions, global Language Variables, default-language fall-through, preview, language IDs and release workflows. The Master Art of Translation is the canonical owner of general translation principles, such as moving meaning between languages and controlling semantic quality. The Translate Like a Pro series index is the discovery route to sibling software-specific guides. Other Translate families cover their own language, task and quality questions; this guide deliberately stays with dotCMS implementation, delivery and testing.

The practical finish line is straightforward: a visitor can find the intended page, read an accurate version in the chosen locale, follow the right link or action, and trust that the underlying facts and record state have not quietly changed in translation. A site achieves this through careful editorial decisions and observable technical behavior, not through a translation counter alone.

Translate Like a Pro | 6220 — dotCMS Multilingual Content, Language Variables, Fallback Rules and Publishing QA