Liferay DXP multilingual content translation brings together structured web content, content-page experiences, language permissions, XLIFF exports and publishing workflows. This Liferay localization guide explains how to translate web content articles and page text accurately, preserve field meaning, control translation status, import completed XLIFF files and check the public URLs that international readers use. It is intended for enterprise editors, localisation managers, translators and developers who need a disciplined multilingual release rather than a translated title that conceals incomplete content.
The most important distinction is between a web content article, a content page and the components that a page displays. Liferay supports translations of selected web-content fields, and its content-page translation interface covers page names and inline fragment text; widgets and mapped fragment fields have different ownership and are not automatically translated by that interface. XLIFF export and import can assist with transport, but a successful file import does not prove that every visible component, link, download or market-specific instruction is correct. Exact features depend on the Liferay DXP or Portal version.
Quick guide: inventory instances, sites and available languages; identify source and target content identities; classify localizable fields; review translation permissions; distinguish inline text from mapped content; export and import supported XLIFF versions carefully; inspect completion states and workflow; preserve facts and media; test all fragments and page experiences; check localized friendly URLs, titles, descriptions and alternate links; validate logged-out pages; and document the final approval. This guide focuses on Liferay implementation and reader journeys, while the wider translation theory remains with the Master Art of Translation system.
Definition lock: what is being translated in Liferay
A web content article is a structured editorial asset, a content page is a composed experience, an inline fragment holds text directly in the page, and mapped fragment fields display content owned elsewhere. XLIFF is an interchange format, not an automatic accuracy guarantee. Translation status indicates field completeness under particular version rules; review approval indicates human judgement; public publication indicates what visitors can actually obtain. A language is a linguistic choice, and a market can introduce distinct factual requirements. Keep these boundaries clear so the right person reviews the right record.
Practical starting checklist
- Locate the actual source record for every visible component.
- Confirm languages, localizable fields and translation permissions.
- Export XLIFF from the intended source version where supported.
- Review web-content fields and page fragments separately.
- Verify workflows, friendly URLs, assets, metadata and public rendering.
- Keep evidence for source changes and future upgrades.
1. Start with the content owner, not the visible screen
A Liferay page is often composed of several layers. A content page can hold inline fragment text, while a mapped fragment may display a field from a separate web content article. Widgets, documents, taxonomy labels and shared navigation may have yet other owners. Translating the page title does not translate everything the visitor reads. Before requesting translation, select a representative page and identify the record that owns each visible sentence, button, card and link. Keep a table with the content type, record ID, language, field, editor role and public route. Without this map, localization teams send the wrong material to translators and later struggle to explain why the rendered page is still partly English.
Use a public page containing a header, article body, related card and form. Click through its editing interfaces and note where each string originates. Create one English-to-French test translation per owner. When a sentence stays English, investigate its source component rather than translating another unrelated field.
2. Know which web-content fields the translation interface supports
Liferay’s official web-content translation documentation explains that the translation interface handles text, HTML and number fields; other field types do not appear in that interface even when marked localizable. That boundary prevents a dangerous assumption: a structure field can be configured for localisation without automatically becoming editable in every translation screen. Review the content structure and identify what will be exported, entered manually, inherited or handled by another workflow. A number field may need human judgment if it carries a market-specific value; allowing translation does not authorise changing a price, measurement or deadline. Preserve the semantic source of important facts rather than letting translators guess.
Make a test article with one plain text field, one HTML field, one numeric field and an asset reference. Open its translation interface and record what is available. Compare with the public page. This verifies the current deployed version rather than relying on a checklist written for a different release.
3. Configure available languages deliberately
Languages offered for content translation are determined by instance and virtual-instance localisation settings. A site can therefore have an available translation workflow that does not match the languages a particular visitor can select or the locales currently exposed by navigation. Write down the required language codes, their audience, default language, content owner and rollout status. Separate language variation from market variation: an English interface might serve multiple jurisdictions with different policies. Do not remove a language casually; official Liferay documentation notes that translations for a disabled language can become unavailable for viewing or editing until the language is re-enabled, with version-specific implications for subsequent edits.
Test adding a non-production target language, creating a translation and then disabling that language in a controlled setting. Confirm what becomes inaccessible and what returns when it is re-enabled. Use this exercise to document safe retirement procedures before a production localization programme expands.
4. Distinguish original language from target language
Every translation requires an origin. The source may be English, French or another language, and it can be wrong to assume the site’s default language is always the current editorial source for a particular asset. Track the original content identity, source version and target locale. When translators receive an XLIFF package, ensure it was exported from the intended source language. A second-hand translation can accumulate omissions or introduce new interpretations that the original does not support. When the source article changes, identify which target versions actually need review. The origin record and approved translation history should remain recoverable after editorial handovers.
Practice with a page originally authored in German and an English translation used as the public default on another site. Confirm which text is the authoritative source for a legal condition and why. Document that decision in the content record rather than assuming the language hierarchy reveals it.
5. Use translation permissions to protect editorial responsibility
Liferay permits users with appropriate Update permissions or language-specific Translation permissions to work on translated content, according to the feature and version. These are not equivalent to unlimited authority to change underlying product facts or publish company policy. Assign translators access to the languages and assets they actually handle, and ensure sensitive domains have subject-matter approval. A translator may know French perfectly but have no authority to revise a course’s eligibility rule. Clear permissions can prevent accidental source-language changes, but permissions cannot replace review. Maintain a separate record of who approves translations and who is allowed to release an asset or experience publicly.
Test the workflow using an account with target-language translation permissions but without broad site administration rights. Confirm that the person can edit the intended fields and cannot change unrelated site settings. After approval, repeat as a logged-out visitor; a correct permission model does not guarantee successful public publishing.
6. Translate web content articles as complete meaning units
A structured web content article might contain a title, description, summary, body, repeating facts, call to action and links. Translate natural-language fields in sufficient context to preserve their intended job. Do not fragment a sentence into disconnected word pairs simply because the structure separates a bold phrase or linked span. Preview the target as the audience will see it. A bilingual side-by-side interface helps editors compare source and target fields, but it does not automatically detect false friends, misleading qualifications or wrong references. Write translator notes for ambiguous labels and choose approved terms for recurring concepts. Where market policy differs, attach an authorised source rather than disguising adaptation as direct translation.
Give a reviewer an article about scholarship eligibility, including a date and document checklist. Have them compare the source and target for conditions, exceptions, named authorities and links. The test passes only if readers can take the same correct action from each language version.
7. Separate content-page experiences from web content articles
Liferay content pages can include different experiences and fragments. Official documentation describes translations of page names and inline fragment text, while widgets and mapped fragment fields are outside that particular translation interface. This distinction is essential when an editor believes that translating the page experience will translate all material visible on it. Mapped content still needs work at its source. Different page experiences may contain different text and deserve their own inventory. Before exporting, inspect which experience is selected and which page text is actually part of the package. Treat page composition as an assembly of independently owned translation responsibilities.
Build a page with an inline headline, a mapped web-content excerpt and a widget label. Translate the page experience, then inspect which pieces changed. Translate the mapped article separately where required. Record the remaining widget owner. This deliberate comparison prevents incomplete page translations being released as finished.
8. Understand XLIFF as interchange rather than approval
Liferay supports exporting web content and supported page text in XLIFF formats, including versions 1.2 and 2.0, subject to product version and feature. XLIFF helps move localizable data to translation tools and back, but the document is not a certificate of semantic accuracy. Source and target language codes, unit identity, protected tags and placeholders must remain valid. Translation software may reorder text while preserving inline markup; it must not rewrite machine identifiers or references. Different XLIFF versions have different capabilities, and Liferay does not guarantee that arbitrary third-party-generated files will import successfully. Prefer exports created by the target Liferay installation for compatibility.
Export one small article with formatting, a link and several distinct fields. Translate it with a compatible tool, preserving unit identities. Import it into staging and compare actual rendered output with the original. Keep the export, translated file and import result as evidence.
9. Read export options before sending a package
The export dialog asks for source language, target languages and format. Depending on the Liferay release and content type, batch export and multiple experiences may be available. Do not assume that one selected language means every article has been included. Confirm the list of assets, the number of files in any generated ZIP, and whether the package includes all required visible content. An omitted text field can be a model or feature boundary rather than a failure by the translator. Add a manifest that records content IDs, source revisions, locale, export date and intended publication batch. This makes it possible to detect stale packages when the source has changed during translation.
Before sending an export to an external translation team, compare the package inventory against the CMS record inventory. Include a screenshot or content context for short strings. If a critical warning is absent, stop and resolve its ownership rather than translating a partial package and hoping the renderer supplies the rest.
10. Import with strict round-trip validation
A file that passes an upload check may still create an unexpected web content revision, a target field value or a workflow transition. Liferay’s import process can accept XLIFF files and, in supported contexts, ZIP archives; errors may produce reports. After import, check each affected content identity, target locale, published state and rendered HTML. Do not treat a green success notification as proof that every target string survived unchanged. Preserve protected identifiers and test links that contain query parameters. If the import fails, inspect file format, units, language codes and source-version mismatch rather than editing XML at random. Make repairs in a reproducible way that future exports can survive.
Import a small batch containing one intentionally malformed unit in staging. Review the reported error and confirm the other contents’ actual state. Then repeat with a valid package and compare stored and rendered text. Keep the error report and final acceptance list for troubleshooting.
11. Interpret translation status without confusing it with quality
Newer Liferay releases distinguish states such as Not Translated, Translating and Translated and may show progress as translated fields over total fields. Official documentation also notes version-dependent changes in what counts toward complete status. These indicators describe field completion, not whether a competent reviewer found the meaning faithful or the page usable. A field can be populated by a fluent but incorrect sentence. Another field may remain source-language intentionally because it contains a protected name. Treat system status as a workflow signal and maintain semantic review separately. Avoid manually marking content complete simply to make a dashboard look green without recording why an exception is permitted.
Create a test target with one missing field and observe its completion indicator. Fill the field with an intentionally wrong instruction and see that the system may still report completion. The exercise shows why human approval and functional QA must be additional release gates.
12. Handle repeatable fieldsets and new content carefully
A structured article may contain repeatable sections such as FAQs, feature cards or steps. Adding a new item to the source does not always propagate automatically to existing translations; Liferay documentation warns about this in relevant versions. That is a useful safeguard against overwriting target edits, but it creates a review obligation. Translators must learn that the source gained a new semantic component and decide how it fits the target. Treat each repeatable entry as a structured element with stable purpose, not merely a positional row. When a source adds a warning before step three, the corresponding target needs the correct warning in the correct place.
Modify a test FAQ by adding a new question between existing items. Inspect the French translation before and after the source update. Compare the rendered order and fields, and document the process for reopening target content. Do not declare the page updated only because the source article version advanced.
13. Use localizable field settings precisely
Marking a field localizable tells the system that language variation is meaningful, but it should not be applied without understanding the field’s purpose. A headline or body paragraph normally deserves localised content. A stable product ID, tracking key or technical reference normally does not. An image reference might be global while its alt text varies. A price may require market-specific sourcing, not a translator choosing a different number. Document translatability at field level and explain it to both content modelers and translation reviewers. The correct classification reduces unnecessary translation work while protecting data that must remain identical across languages.
Review one content structure and write down why each field is or is not localizable. Then create a new target locale and see which controls can be changed. If the interface exposes a field that editors should not alter, consider model policy and permission controls before relying only on training.
14. Keep friendly URLs independent from translated prose
A translated heading and a friendly URL are related but distinct. Liferay documentation notes that a missing target friendly URL may cause the default-language friendly URL to be used, depending on the content and version. That fallback can be technically valid while undesirable for a polished multilingual strategy. Choose a stable policy for localized slugs and route uniqueness. Do not generate a new slug every time a headline is revised; bookmarks and search results have histories. Preserve redirects when retiring a route. Check non-ASCII characters and characters that need encoding. A link that resolves to a page in the correct language still deserves review if the route unexpectedly switches locale or points to an obsolete version.
Create a target article with no custom localized friendly URL, then supply one. Compare the public destination, rendered links and redirects. Record what is controlled by the content record and what is controlled by site routing. These are operational facts, not decisions translators should improvise.
15. Protect numbers, dates and contractual conditions
Liferay web content can carry numeric fields that are technically localizable, but the translator’s permission to edit a field does not give authority to invent factual differences. Preserve measured quantities, reference codes, eligibility dates, names, currency identity and contract terms unless the responsible source owner has approved a variation. Formatting a date for a language is different from changing its value. A displayed price may be generated from structured commerce data, or it may be editable text inside an article. Find out which. For high-risk content, subject-matter review should compare the source and target claims as structured facts, not only as sentences.
Use a training article with an application deadline, minimum age and payment amount. Ask one reviewer to assess natural language and another to check each fact against an authoritative record. A translation can pass the first review and fail the second; do not release it until both checks are complete.
16. Translate assets and their descriptions independently
A document library file may be shared across languages while its title, caption and alt text vary. In another situation, a PDF may contain language-dependent instructions and need a genuine translated edition. Do not assume that translating a page link translates the linked document. A user could follow a French page into an English-only form and miss a condition. The correct solution may be a localized asset, a clearly labelled English original or a block on publication for high-risk documents. Keep licence, credit and version information intact. Consider what screen-reader users hear when they encounter a translated page with unlocalized asset descriptions.
Open every high-priority download in the actual target route, not just from the asset editor. Compare file identity, page text, accessibility labels and user expectations. If the asset itself is English only, label its language plainly. A successful download is not a successful multilingual experience.
17. Review taxonomy, navigation and shared components
A site can have localized article bodies but source-language category labels, menus or related cards. These elements may live in different Liferay modules, asset vocabularies or page fragments. Map their owners and translation capabilities separately. If a taxonomy concept is shared across languages, protect stable classification identity while translating user-visible labels. If the classification genuinely differs by market, document why. Avoid duplicating taxonomies merely to change a name, because that can fragment filtering and reporting. Navigation links must point to approved target-language destinations, and related-content cards should not silently fall back to unrelated items.
Navigate through a translated article’s category page, site menu and related-card list. Record the displayed label, target URL and underlying content identity for each step. Repeat after one target article is unpublished. This reveals dangling links and over-eager fallback queries that page-body review misses.
18. Check every published page experience independently
One Liferay content page can support different page experiences, and the translated text available for each may differ. A review of only the default experience does not verify the others. Select actual audience conditions used by the site and inspect the resulting public experience. Remember that page translation of inline fragments is not the same as translation of widgets and mapped fields. If a conditional layout displays a French banner for one audience but an English card for another, the experience as a whole fails. Keep test cases grounded in the deployed configuration; do not assume audience rules just because the CMS feature exists.
Create a coverage matrix with experience, locale, key components, approval owner and public verification URL. Test at least one ordinary and one edge-case experience after each release. A screenshot of the editing view is supplementary evidence, not a replacement for the delivered page.
19. Handle target workflow states and publication cautiously
Translating a web content article may create a new version or enter an approval workflow if one is enabled. Content-page translations can have their own save and publication behaviour. Do not assume that clicking Publish in a translation dialog necessarily means the entire website experience is visible to all external visitors; inspect the actual state. Assign clear roles for language review, content accuracy, page assembly and release. Maintain source and target revision identifiers, plus a decision record for urgent corrections. If a source changes a legal condition, consider temporarily withholding a target route until reviewed rather than serving contradictory promises.
Run a test change through the configured workflow, beginning as a translator and ending as a logged-out visitor. Record which stage each role can perform and when the public version changes. Repeat with a rejected translation to verify that unapproved wording cannot leak into production.
20. Test translated content through public delivery and search
A translated article is not useful if the public page continues to render its default-language fields, or if search results point visitors to another language. Inspect how the site resolves locale by route, cookie, request header or user preference, and establish a precedence rule that honours explicit visitor choice. Test search indexing for target-language terms, result titles, snippets and click destinations. Some content might be technically present but not included in the site’s search or navigation. Verify language choice in a clean browser session, not solely while logged into Liferay as an administrator.
Choose one phrase that appears only in the French translation and search for it. Follow the result, change language, refresh and navigate to a related item. Record every URL and page heading. If the route switches languages unexpectedly, fix delivery or selection logic before asking translators to rewrite content.
21. Verify international SEO from the rendered experience
Search engines see actual URLs and HTML, not the translation completion badge. A target page needs an appropriate title, description, indexability choice, canonical URL and truthful alternate-language links if the site emits them. Page fragments and mapped content can cause the rendered headline or metadata to differ from fields an editor inspected. A language alternate must point to a real equivalent page, not a default-language homepage standing in for missing content. A hreflang relationship does not justify publishing an incomplete translation. Use natural target-language search phrases and avoid a literal keyword copy that sounds wrong to readers.
Inspect the final HTML of English and French counterpart pages while logged out. Compare canonical and alternate destinations, language selection, title and description with the visible content. Test one missing language and one redirecting route. Remove any alternate tag that advertises a page that does not exist.
22. Build a migration-safe maintenance and audit process
Long-lived enterprise content includes languages added later, site restructures, field-model changes and product upgrades. Each can affect localization behaviour. Record the Liferay version and edition when documenting features; permission systems and translation status details evolve. Backups and exports should preserve source and target identities, content structures, workflow states and related assets, not merely the last rendered HTML. When a translation is retired, handle redirects, archive policy and search visibility deliberately. Review old XLIFF packages before reuse, because the structure or source revision may have changed. A repeatable audit is more valuable than a one-time perfect launch.
Quarterly, test one new translation, one source revision, one removed target, one downloadable asset and one page experience. Keep evidence of what a visitor actually received. Use those findings to refine editor checklists and upgrade tests. If the team cannot explain how a source change reaches the correct translated public page, the system is not yet controlled.
Worked example: a multilingual international admissions portal
Suppose a university publishes an English admissions overview and needs French and Arabic editions. The overview is a structured web content article containing eligibility text, deadlines, programme codes and linked documents. The content page displays its excerpt in a mapped fragment, plus inline text and a contact widget. First, identify the source for every component. The language team translates the permitted web-content fields and reviews formatting and right-to-left presentation where applicable. Separately, the page editor handles inline fragment text. The widget owner ensures that its labels and messages appear in the requested language. A reviewer checks that programme codes and deadlines match the authoritative record.
Next, the admissions office changes the application deadline. The source owner records the approved value and triggers the translation review. Completed target text is imported or edited through the supported workflow; the reviewer checks translated instructions and the linked application document. The publisher verifies each public route, metadata, contact form and confirmation message. The release record proves that the user can act correctly in the chosen language. A translation-status badge alone would not have caught a still-English mapped fragment or outdated PDF.
Failure investigation: the import succeeds, but the page remains English
The translator provides a valid-looking XLIFF file and the import reports success, yet the public page still shows the source paragraph. Begin by checking the target locale and intended article identity. Then inspect its localizable fields and target revision. If those are correct, inspect the page assembly: perhaps a mapped fragment points to another article, the language selector resolves to the default locale, or an older public version remains active. Avoid translating the same paragraph again before identifying which component the visitor actually sees. Repeating a successful import into the wrong record can create more confusion.
Capture the public URL, the rendered component, its data owner, the imported unit and the workflow state. Fix the narrowest faulty relationship or publication step, then repeat the original visit in a clean browser session. This method separates translation exchange, content ownership and delivery instead of treating them as one black box.
Four-week implementation and review exercise
Week one inventories instances, sites, available languages, content structures, content pages, experiences, permissions and asset owners. Week two creates a multilingual pilot with one web content article, one content page, a mapped fragment and a small download. Week three tests XLIFF export/import, source-change handling, incomplete fields and workflow approval. Week four reviews public routes, search, accessibility, international metadata and missing-language behaviour before documenting the release gate. Expand to more locales only when the pilot is repeatable with ordinary editor permissions.
As a teaching exercise, give a trainee a page containing an inline headline, mapped eligibility text, a contact widget and a document. Ask them to identify every translation owner without opening the translator interface first. Then ask a reviewer to confirm that all four components behave correctly after a change to one eligibility condition. The exercise exposes the real difficulty of enterprise localization: coordinating meaning across components that share one screen.
Frequently asked questions
Can translating a content page translate every widget on it?
No. Liferay’s documented content-page translation scope includes the page name and inline fragment text, not widgets or mapped fragment fields. Those components require separate handling.
Which XLIFF versions are supported?
Liferay documents support for XLIFF 1.2 and 2.0 in relevant workflows, with feature differences across product releases. Use exports from the actual deployment and validate imports in staging.
Does Translated mean a reviewer approves the meaning?
No. It is a completeness status determined by fields and version-specific rules. Linguistic accuracy, factual integrity, layout and release must be reviewed independently.
Why are friendly URLs still in the source language?
A localized friendly URL can be missing, or the route may use the default-language value. Inspect the content record, routing configuration and rendered URL before changing the target title.
Official resources and architectural routes
See Liferay: Translating Web Content, Liferay: Translating Content Pages, and Liferay: Translating Content in the CMS. Product editions and versions have different features; verify the documented scope against the deployed installation.
For the complete reasoning framework, read Master Art of Translation: The Complete System and the Translate Like a Pro series index. This child guide owns the Liferay implementation and release workflow, not general XLIFF theory or translation vocabulary.