Translate Like a Pro | 5810 — MODX Revolution Language Contexts, Babel Resource Links, Lexicons, Routing and Multilingual SEO QA

MODX Revolution multilingual website translation works best when editors understand how contexts, resources, lexicons and routing cooperate. This practical MODX localization guide explains how to build language-specific pages, connect equivalent resources with Babel, preserve template variables, translate interface strings, check language selection and test international SEO without confusing a different language with a different website. The intended readers are content teams, translators and developers responsible for reliable publishing across countries and languages.

Start by choosing a deliberate architecture: separate MODX contexts for languages, or a carefully selected single-context multilingual extension. In a multi-context design, a resource has an identity within its language context, while Babel helps relate counterpart resources. Lexicons carry reusable interface text; cultureKey and locale settings help the application select language and formatting. A visitor needs more than translated paragraphs: the correct route must lead to the correct resource, menus and forms must stay in the selected language, and translation links must never send readers to an unrelated page.

Quick guide: inventory languages and resources; identify the source of truth for each language; configure contexts and locale settings; choose and test routing; map Babel translation links; distinguish shared template variables from translated values; translate lexicons separately from editorial content; verify cache behaviour; inspect forms and protected identifiers; check localized titles, descriptions, canonicals and language alternates; review the complete visitor journey; and publish only when missing-language outcomes are controlled. The emphasis is on carrying meaning faithfully through MODX rather than merely filling a translation field.

Definition lock: what MODX localization does and does not guarantee

MODX is the content management system, a context is an execution and resource scope, a resource is a content item, a lexicon carries reusable interface strings, and Babel is an extra that relates translated resources across contexts. A language version is a content variant intended for readers in that language, not a second arbitrary article. A locale may include formatting expectations as well as language; a market may impose distinct facts or regulations. These boundaries prevent editors from treating a page copy as a completed translation or a language flag as evidence of approval.

Quick checklist

Identify languages and which contexts own them.
Confirm routing and resource counterparts before importing translations.
Protect IDs and facts; translate real reader-facing language.
Audit lexicons, TVs, forms and navigation separately.
Test missing languages, public routes and metadata.
Record approval and release evidence.

1. Understand the difference between a context and a language

A context in MODX is a separate execution and resource environment. It can represent a different language, but it can also represent another site, an extranet or a specialised application area. That distinction matters: creating a French context does not automatically produce French content. It gives the publisher a place in which French resources, routing and settings can be managed. If two contexts carry versions of the same article, the publisher needs an explicit relationship between them, an appropriate link strategy and a way to identify which one is the true translation. Decide which responsibilities belong to context settings and which belong to content records. Test this with a page whose title, navigation, form and footer all contain words. If the page body changes but the navigation remains English, the language context is incomplete rather than the translation finished.

A useful exercise is to write down what happens to a visitor who opens a French link directly, not through the homepage. Record which context handles that URL, which resource renders, which locale is active and where the language switcher points. The evidence is a full page and URL, not just a translated field.

2. Decide between multiple contexts and a single-context extension

MODX documentation describes two broad approaches. A multiple-context implementation can organise languages as separate resource trees, commonly with Babel to connect translated resources. A single-context strategy can instead use an extension such as Lingua. Neither is a universal answer. Multiple contexts can make language boundaries clear but increase resource and configuration management. A single context can reduce duplication but adds dependency on the extension’s field, caching and routing behaviour. Compare the actual editorial workflow, not a theoretical feature list: how does an editor add a language, publish a revision, remove an old page, change a URL, update a navigation label and audit a translation? Where are translated values stored? What happens during an upgrade? A team that cannot answer these questions should pilot before adopting either design across thousands of pages.

Make a decision table for the project: editorial ownership, URL strategy, forms, search, caching, fallback, migration cost and maintenance. Test one landing page, one article and one dynamic item before accepting the design. Keep the architecture decision visible in onboarding notes.

3. Give each context explicit language and routing settings

A multi-context build needs explicit, consistent settings. MODX context configuration can include cultureKey, locale, base_url, site_url, http_host and site_start, depending on the routing method. The names are not interchangeable: a locale influences language-related behaviour, while a base URL and host determine where resources are reached. A wrong base URL can generate links into the wrong context even when the current screen looks translated. Develop a configuration matrix showing every live host or prefix, source language, root resource and expected fallback. Include staging values separately from production. Do not paste production hosts into a test environment and hope a redirect hides the mistake. Clear or refresh caches after supported configuration changes and test both direct entry and internal navigation.

Open the deepest translated article by its exact URL in a clean browser session. Follow its breadcrumbs back to the home page. If the second click crosses language or domain unexpectedly, look at generated links and context settings before changing text. A writer cannot repair a routing error through better translation.

4. Understand Babel’s job and its limits

Babel is a MODX Revolution extra that helps manage multilingual resources using contexts and context groups. It maintains links between counterpart resources and provides a manager interface for moving between their translations; it can also synchronise selected template variables. Its central value is relationship management, not automatic linguistic correctness. A Babel link means that two resources have been associated, not that a target resource is complete, current or approved. Editors should establish a rule for creating counterparts, recording reviewers and handling missing versions. Do not assume that a machine-generated shell contains finished translation. If the source article changes, the related target resource must be assessed for semantic impact. A relationship that survives a rewrite without review can make a site appear synchronized while meanings diverge.

Choose one English resource and create its French counterpart in a test setup. Confirm the resource IDs and contexts, the reciprocal Babel relationship, the correct route and the translated content. Then deliberately remove the counterpart and observe the switcher’s behaviour. That negative test is as important as the happy path.

5. Keep resource identity independent of translated titles

Human-facing resource titles change frequently. A writer may improve an English heading, a French editor may use a more natural phrase, and a campaign may update its label without changing the underlying article. Translation identity must not depend on exact title matching. In MODX, build an inventory around resource IDs, context keys, canonical subject and Babel associations rather than assuming a translated alias proves equivalence. A French page about admissions is not the counterpart of an English page about tuition fees simply because both include the same school name. For major pages, record source revision, target revision, approval status and the date on which the equivalence was checked. When copying a resource, inspect its links and content before allowing it into the translation graph.

Exercise: rename a source title and confirm that the language relationship remains correct. Next, create two similarly titled resources and verify that the switcher still chooses the actual counterpart, not the first keyword match. Keep a mapping sheet that a new editor can audit without guessing.

6. Separate translated prose from MODX lexicons

MODX lexicons are designed for reusable language strings used by the system, themes or extras. Their job is different from a Resource’s main article. A login prompt, search placeholder or button caption might be better maintained as a lexicon entry, while a full page explanation belongs in editorial content. Identify which labels are already lexicon-driven and which are hard-coded in chunks or templates. Ensure the correct namespace, language and key are loaded for the active context. Keep placeholder syntax, HTML handling and variable names protected, because an apparently fluent label can break rendering when an identifier is translated. Where multiple extras have similar keys, namespacing prevents accidental collisions and makes ownership clear.

Review an entire page with a change of context. Ask a translator to identify every remaining source-language string, including validation messages, consent text and pagination. Trace each one to its owning lexicon, chunk or resource instead of making random replacements in a template. Test with a second target language to expose missing namespace assumptions.

7. Treat template variables as data with differing translation policies

Template variables, often called TVs, may hold a heading, an image reference, a button label, a product code or a layout option. Those are not all translation material. A shared image asset ID might remain unchanged across contexts; alt text and a promotional message may need translation; a legal notice might require market approval rather than literal equivalence. Babel’s ability to synchronise selected TVs is useful only if the field classification is correct. Synchronising a translatable promotional slogan would overwrite local meaning; failing to synchronise a stable technical ID could break consistency. Audit TV definitions with their real uses, then identify which values are shared, translated, inherited, market-specific or derived.

Build a field matrix for a representative landing page. Change a shared asset reference in the source and observe whether it propagates safely. Change a French call-to-action label and verify that synchronisation does not silently restore the English text. The correct policy belongs to each field’s semantic job.

8. Map language routes before translating hundreds of URLs

A translation project becomes fragile when URL decisions are made one page at a time. Choose whether languages use paths, subdomains or domains, how the default language is represented, which aliases are translated and what happens when a localized alias is missing. MODX can support different routing arrangements through configuration and extras; implementations differ, so test the actual route handler. Keep a record of old and new URLs during migration, including permanent redirects only where content remains equivalent. An English route should not become a French route through an automatic guess that ignores context or an existing target alias. The reader’s explicit language choice should survive refreshing a page and following a link.

Test a non-ASCII alias, a route with two nested path segments and a page that has no target-language counterpart. Observe URL encoding, redirects and the HTTP response. A clean 404 or honest fallback may be safer than quietly redirecting to a different subject. Document how search engines and people reach each locale.

9. Design the language switcher around real counterparts

A language selector often looks correct on the homepage while failing on deeper pages. If the current MODX resource has a Babel-associated French counterpart, the selector should link to that exact target URL. If no counterpart exists, decide whether to hide the option, offer a labelled language landing page or display a clear unavailability message. Do not substitute a loosely related page and pretend it is the same article. A switcher can also lose search queries, anchors, pagination or a user’s place in a long form. Decide which query parameters are safe to preserve. Any language preference stored in a cookie or session must not override a deliberate direct link in a surprising way.

Open a long article at a deep URL and switch from English to French, then back. Confirm article identity and selected language in the menu, page body and metadata. Repeat with no translation, with a missing resource, and after browser refresh. Log each actual destination for future regression tests.

10. Translate chunks and templates without corrupting structure

MODX templates and chunks may combine HTML structure, placeholders, lexicon tags, snippet calls and ordinary visible words. Translators should change words that readers see while preserving the syntax used to render them. An innocent change to a placeholder name can make a card blank; translating a CSS class or snippet property can break layout. Extract translatable strings into a controlled location when practical, rather than distributing them across dozens of repeated chunks. Give translators a screenshot and an explanation of short labels. The same English phrase may need different equivalents when it is a button, a heading and a warning. Do not make grammatical fragments share one key merely because the words look similar.

Run a template comparison between source and target builds, checking that dynamic placeholders, links and accessibility attributes still resolve. Include a screen-reader view of a form where available. Mark programmatic tokens as protected in localization instructions and do not trust visual preview alone to find a broken hidden field.

11. Keep forms, email, and error messages inside the language boundary

A multilingual article may invite a visitor to complete a contact form. The form can contain a target-language label but still send source-language errors, confirmation emails or privacy statements. Inspect where the form extra gets its messages, which lexicon namespace it loads, and how email templates choose a locale. Distinguish user-selected language from the language of an administrator who receives the submission. Translation should never change email address keys, security tokens, field names, consent status, validation logic or delivery destinations. On a regulated form, privacy and consent claims need human review because their legal meaning is more important than visual consistency.

Submit a realistic but non-sensitive test request in each locale, including one invalid input. Record the visible prompt, validation, post-submit confirmation and user email. Repeat on mobile. A successful submit is not sufficient if the visitor cannot understand the error or if the form quietly uses different conditions.

12. Control caches, previews and context-sensitive output

Caching can make a localisation fault appear random. A string from the English context might be cached under a key later reused by the French request; a preview may reflect new text while the public route serves an old version. MODX provides different cached and uncached mechanisms, and extras add their own layers. Understand which content varies by context, visitor role and route before deciding cache boundaries. Do not solve every translation bug by disabling caches globally. Instead determine the smallest safe invalidation and verify that language selection is represented in relevant cache keys or resource paths. Distinguish template compilation errors, stale resource output and a missing translation at the source.

Use two browsers to request the same subject in two languages repeatedly, alternating the order of visits. Clear only the documented caches, then repeat. If changing order changes the language, investigate cache isolation. Note both editor preview and a logged-out public response in the release record.

13. Translate SEO fields as content, not afterthoughts

An article’s search title and description communicate a specific promise to people who have not reached the site yet. In MODX they may be stored in core resource fields, TVs, SEO extras or custom templates. Locate the actual output owner. A translated body with a source-language meta description creates a mixed-language search result. Translate the meaning and naturally adapt the query language; do not force identical source keywords into another language. Avoid creating a localized description that promises features not available to that market. Verify the rendered HTML title, meta description, main heading and visible introductory answer, not merely the values in the manager.

Open page source or an inspection tool on the public target URL and compare it with the resource record. Check one target page with a long title and one with special characters. Keep a record of the title and description actually emitted; a correct TV hidden behind the wrong template condition is not a completed SEO translation.

14. Generate canonical and hreflang signals only for genuine pages

International SEO metadata is a map of real alternatives, not a device for creating missing translations. Each localized MODX resource should normally have a sensible self-referencing canonical when it is the intended indexable page; locale alternates should point to real equivalent pages, not approximate topic neighbours. Test reciprocal alternates where used and define the treatment of the default-language page. An x-default destination can be useful when there is a true language-selection or global default experience, but it should not be invented as a replacement for correct page identity. Check that HTTP redirects and final URL forms agree with the metadata. Do not append alternate tags to a page that remains a translated shell.

Make a small equivalence graph: English source, French translation, German translation and one missing locale. Inspect the tags emitted by each public page. Remove any link to a missing resource, then retest after publication. The acceptance test concerns what a crawler can request, not what an editor believes exists.

15. Preserve structured identifiers, numbers and claims

Translators must recognise the difference between linguistic material and protected factual content. A MODX resource may include product identifiers, dimensions, prices, dates, addresses, names, citation links and legal references. Altering one of those values can change the reader’s action or create an inaccurate claim. Provide a field-by-field inventory and lock technical tokens, but let the sentence around them take natural target-language order. If a factual value genuinely differs by market, it should come from an approved market source rather than a translator’s intuition. A date may need locale-appropriate presentation without changing the underlying day. Currency formatting does not authorise conversion or a new price.

Build an example page with a reference number, a deadline and a measured value. Compare the source and target as structured facts after translation. Ask a reviewer to identify every numerical and named entity from the source. Use explicit annotations when an approved market adaptation legitimately changes a field.

16. Manage images, downloads and alt text separately

An image may be usable globally while its alternative text and caption need translation. Conversely, a diagram with embedded English labels may require a different asset per locale. MODX media paths, TV references and editor HTML can store these relationships in different places; inspect the site-specific implementation. Do not duplicate large files only to translate a caption, and do not share an image that gives different instructions from the target article. A downloadable PDF may stay in English even when the link caption is French; if this is intentional, say so clearly and do not suggest the file itself is translated.

Test image links, alt text, captions and downloads on desktop and mobile. If one translated page refers to a globally shared asset, confirm that changing its metadata does not unexpectedly overwrite metadata used by another locale. Check the accessible name of icon-only links, not merely the visible photograph.

17. Build navigation from locale-aware resource ownership

A menu is not merely a list of words. It is a list of destinations that must correspond to the visitor’s selected language and content availability. A multilingual MODX implementation may use pdoMenu, Wayfinder, custom snippets or hand-built chunks. Determine how each menu source queries contexts, filters unpublished resources and constructs URLs. A French menu built from English resources will remain wrong even if every label is translated. Avoid hidden language mixing caused by a shared root node or a cached menu result. Decide which global links are intentionally common, such as an external service, and label their destination clearly.

Walk a complete route from home to an article, then to a category, then to a form in each language. Record the URLs and headings. Repeat after unpublishing one target resource to make sure the menu does not advertise a missing page. Include keyboard navigation for dropdown menus.

18. Handle publication and revision drift as explicit states

Two linked resources may have different publication histories. An English article can receive a corrected instruction while its French counterpart stays on an older revision. Babel association does not automatically provide a review process. Capture source change events and classify them: typo with no semantic consequence, changed description, new condition, withdrawn offer or safety correction. Each type warrants a different translation response. Where urgent changes affect safety or eligibility, consider temporarily withholding the target route until reviewed rather than displaying contradictory instructions. A formal state such as draft, needs review, approved and blocked is easier to reason about than an unexplained checkbox.

Simulate a source correction that changes a deadline and a second correction that changes only punctuation. Decide which target translations require human review and record why. Publish only the affected target versions when they are ready. Confirm logged-out live pages, because manager approval labels alone do not show what visitors receive.

19. Decide what fallback means for each content class

Fallback from an unavailable language to the source may be acceptable for a low-risk company biography but inappropriate for a safety warning, regulated policy or a purchasing commitment. A MODX system can implement fallback at routing, snippet, template or field level. These are not equivalent. A page that silently mixes one source-language warning into a target-language article may mislead readers into thinking all conditions were translated and approved. Write a fallback policy for complete pages, shared labels, product facts, legal modules and navigation separately. Prefer honest absence or a clear language notice when the target cannot safely convey the required meaning.

Create an intentionally incomplete French resource: missing title, one untranslated TV and one missing child link. Observe the real output and correct any silent substitution that violates policy. The evidence should state what the reader saw, which component produced it and the decision used to repair it.

20. Test search and filtering in the chosen language

A reader who searches a French MODX site should not receive an uncontrolled mixture of English and French pages. The search implementation may query MODX resources directly, use an extra or rely on an external index. Inspect how context and publication state limit results, how translated titles are indexed and whether synonyms or stemming exist for target languages. Avoid implying that language detection is equivalent to a reliable language-specific index. Review result titles, snippets, filters and empty-result messages. A correct French page can still be practically invisible if the index never ingests it or the menu leads to a source-language search page.

Test one target-language query using a phrase present only in the French article and one using a shared proper noun. Confirm the right resource IDs, context, snippets and click destinations. After unpublishing an item, check removal from the index or search results according to the documented refresh process.

21. Perform a release through a full reader journey

The most useful final review is not a spreadsheet tick beside every translated field. It is a reader journey: enter through a search result, understand the page, follow its links, complete the intended task and return without losing language or meaning. Choose one ordinary page and one high-risk page. Have a language reviewer evaluate tone and sense, a developer evaluate resource routing and placeholders, and an editor evaluate facts and claims. Record visible URLs, publication states, approval names and defects. A page that looks fluent can still be functionally broken when the next click opens an English-only form or the downloaded file contradicts the article.

Use a short release gate covering language identity, connected resources, routing, lexicons, menus, form strings, numbers, consent, metadata, page alternatives, cache and mobile rendering. Retest after any correction because one shared template change can affect multiple languages. A screenshot and URL should accompany important approvals.

22. Maintain multilingual resources without losing their history

Long-lived localization is a maintenance problem as much as a publishing problem. Set a review cadence for high-traffic pages, stale translations, discontinued languages, obsolete resources and deprecated extras. Back up the relationship mapping between contexts and Babel-linked IDs before a migration. If a language is removed, decide what happens to bookmarks, redirects and archived content. If a site changes from Babel to another approach, migrate semantic identities and approval histories rather than transferring only HTML. Keep documentation for the exact MODX version and extras installed, because behaviour may differ after upgrades.

Close each quarter with a small audit: one newly created counterpart, one revised article, one removed page, one multi-language form and one search query. Record defects and assign owners. These five cases reveal far more operational risk than simply counting the number of stored translations.

Worked example: a multilingual university programme guide

Imagine a university with an English programme guide that explains eligibility, course dates, fees and an enquiry form. The French edition must convey exactly the same programme identity while preserving the authoritative numeric facts. Create separate resources in the chosen contexts, connect them through Babel and classify the page fields. The course code and approved fee may be shared values; explanatory language, alt text and button labels are translated. A market-specific bursary condition must be reviewed as a policy difference, not translated from a guess. Open both resources through their final public paths. Confirm that menus remain in language, the form validates in French and the language selector returns to the English counterpart rather than the programme list.

The editor then changes the start date in the English source. The translation owner marks the French version as requiring factual review, confirms the new date in the source system and republishes the affected language resource. The QA reviewer checks the course page, its linked timetable, confirmation email and metadata. A reader arriving from a search result now sees consistent eligibility and dates across the entire journey. The record of what changed is as valuable as the updated sentence.

Failure investigation: the page changes language after a second click

A visitor opens a French deep link successfully. The first menu item leads to an English page. Begin by capturing both URLs and the generated menu link. Check which context produced the menu, what resources its snippet queried, and whether the menu output was cached without respecting context. Do not try to repair the error by rewriting the French article. After correcting the appropriate context or navigation configuration, repeat the original sequence in a fresh session. Check browser back and refresh because some routing problems only show up after navigation history changes.

The same discipline applies when a language switcher leads to a generic home page. Inspect counterpart resource associations first, then the route builder and missing-resource policy. The failure is not necessarily a translation failure. The goal is to trace the actual path from published resource identity through URL generation to the browser.

Four-week practice plan and editorial exercise

During week one, inventory languages, resources, contexts, route settings, lexicon ownership and current extras; build the field classification matrix. During week two, implement a small complete path containing one article, its source-and-target relationship, a menu and a form. During week three, translate that path with a reviewer, check metadata and missing-version behaviour, and test caching and direct deep links. During week four, publish the pilot, log defects and document the repeatable steps for adding a resource or responding to a source revision.

For a useful exercise, give an editor a two-paragraph programme page with a deadline, a downloadable form and a single shared image. Ask them to describe which values are protected, which are localised, which come from a market authority and which fields are generated. Then have another person attempt to reproduce the publication from the documentation alone. Where they must guess, the workflow is not yet ready to scale.

Frequently asked questions

Does Babel translate my entire MODX site automatically?

No. Babel helps manage relationships among resource translations and can synchronise selected TVs. Human-language quality, routing, menus and publishing decisions still need separate work.

Can every MODX site use a single context?

Some multilingual strategies use a single context with additional tooling, but others benefit from multiple contexts. The right choice depends on routing, editorial ownership, extension compatibility, content structure and maintenance.

Should the source language appear when French is missing?

Only under an explicit fallback policy. For high-risk content, a transparent unavailable state may be safer than silently displaying an English instruction.

How do I test SEO translations?

Request public target URLs, inspect their real title, description, canonical and alternate-language output, and verify every alternate points to equivalent published content.