October CMS multilingual website localization requires coordinated site locale settings, translated content files, model fields, theme messages, URL routing and editorial approval. This October CMS translation guide explains RainLab.Translate, modern site definitions, Twig strings, translatable model attributes, language switchers, fallback and multilingual SEO quality assurance. It is designed for developers, translators and international content editors who need every public page, form and email to deliver the right language and the right meaning.
Start by establishing what owns each translation. A configured October CMS site can identify a language experience, but it does not automatically create translated articles. RainLab.Translate supports several localization workflows, and newer October CMS releases have additional core capabilities. Some old tutorials refer to language-picker controls and session handling that changed as native multisite support arrived. Inspect your installed versions before implementing an example from older documentation. The practical success criterion is that a visitor opening a target-language URL sees the correct article identity, readable strings, working links and trustworthy business facts.
Quick guide: inventory site definitions, active locales and URLs; distinguish core facilities from RainLab.Translate; classify translatable and protected fields; localize Twig theme strings; connect the correct model attributes and pages; map translated URL parameters; test SitePicker and missing-language handling; translate content and mail templates; inspect forms and asset labels; validate SEO titles, canonical URLs and actual alternate pages; and release a complete visitor journey with documented review. This article owns the October CMS implementation, not the general theory of translation.
Definition lock: the different objects in October CMS localization
A site definition determines a configured site and locale; a CMS page controls content and routing; a theme message provides reusable interface text; a model attribute stores business or editorial data; a plugin or native translation facility handles selected language variations; and a public translation is the actual approved page delivered to the reader. A source-language fallback is a substitution, not proof of reviewed translation. A market requirement may change business content without changing the language. These boundaries help teams locate errors at the correct layer.
Quick reference checklist
- Confirm the precise October CMS and plugin versions.
- Inventory sites, locale codes, target URLs and translation owners.
- Classify model fields and protect identifiers and business facts.
- Review theme messages, file variants, routes, SitePicker and fallback.
- Test forms, email, search, media and accessibility.
- Verify public metadata, source changes and missing-language handling.
1. Understand what an October CMS site definition does
A site definition selects a configured site experience, which may differ by locale, hostname, prefix or business context. It is not necessarily a second language: several sites may share English, and one market may need more than one language. Create an inventory showing the default site, language codes, target domains, publication responsibility and expected landing pages. Distinguish the site that handles a request from the model fields and template strings returned for that request. A French URL can select the right site while an individual content component still falls back to English. That discrepancy requires diagnosis at content level, not a new DNS setting.
Test a French homepage, a direct deep link and a bookmarked route. Record the active locale, visible page heading, route, footer and next click. Repeat in a clean session. If the language differs after navigation, the site selection contract is incomplete.
2. Audit the translation mechanism in your installed version
October CMS localization has evolved. RainLab.Translate historically manages theme messages, translated models and URLs, while modern multisite facilities have assumed some responsibilities. Documentation for the RainLab plugin notes that newer CMS versions can also provide native model translation options. Do not assume all code samples describe your deployment, especially when a tutorial references session-based language selection or older locale-picker widgets. Record the precise CMS and plugin versions and the installed packages that handle public content. Identify which module owns every relevant field before changing it. A stable architecture is based on observed behaviour and supported upgrade paths, not familiar screenshots.
On a staging copy, create one translated theme string, one localized model attribute and one language-specific page. Find the editing and retrieval path for each. Document whether its source is core, a plugin or custom application code.
3. Choose model localization according to content meaning
A model may contain a translatable title, an explanatory paragraph, a product code, a numeric price, a status flag and a category link. Only some of these are linguistic material. RainLab.Translate documents a TranslatableModel behavior for selected attributes. Newer installations may have native alternatives, but in either case the field classification must be explicit. A SKU should not be translated because its label is a string. An approved price should not change because a translator thinks local currency would be clearer. A marketing description may legitimately use natural target-language wording without changing the product identity.
Build a sample content model and identify which attributes are language-variable, market-variable, protected or generated. Change one description in French and confirm English is unaffected. Try changing a protected identifier and ensure the publishing process rejects or detects the mistake.
4. Keep site locale separate from market-specific business facts
French is a language, not a universal legal jurisdiction. A website serving France and Canada may share many French explanations while using different shipping, tax or eligibility conditions. October CMS site settings can help distinguish experiences, but the content model still needs separate ownership for language and market. Use a source-of-truth record for business facts, then attach language-specific descriptions and approved market adaptations. Do not let every site-specific editor retype dates, rates and legal notices from memory. A translated paragraph is not a licence to invent a different product offer.
Test two French market pages sharing one product but using different approved delivery terms. Confirm that the common terminology remains consistent and market facts follow the right route. Record who authorised the differences and when.
5. Define Twig theme strings as readable sentences
October CMS themes commonly use Twig, and RainLab.Translate documents a translation filter for interface phrases. Treat each phrase as meaningful language rather than merely a sequence of tokens. A string such as Open can mean a command, operating hours or an application status; it needs context. Avoid breaking an ordinary sentence into several translation keys solely because a link or bold span appears inside it. Protect Twig variable names, function calls and HTML structures from translation. Where a string appears in several contexts, explain whether a shared translation is appropriate or separate keys are necessary.
Translate a sample sentence containing a dynamic date and a link. Reorder it naturally in the target language without altering syntax. Render the result in two locales and check the clickable destination, not only the displayed text.
6. Inventory theme messages that are easy to miss
The most conspicuous text on a page is not the whole interface. A footer label, filter option, cookie notice, validation error, pagination message or search placeholder may be owned by a theme string or an extension. Build an inventory from a representative user journey. Locate the owner of each message and give it a translation policy. Hard-coded strings in templates are candidates for controlled extraction. Conversely, long articles should not be hidden in a theme message dictionary that lacks editorial structure and revision history. Keep meaningful ownership boundaries so changing one shared label has a predictable effect.
Ask a reviewer to enter the site as a new visitor, open an article, search, submit an invalid form and visit the footer. List every source-language phrase they encounter. Trace each to a file, model or extension before translating it.
7. Translate CMS content files with version-aware naming
RainLab.Translate documentation describes content templates with language suffixes, allowing a default file and target variants to be associated. The exact naming convention and integration should be checked against the installed version. A translated content file must keep the expected route and rendering structure while carrying complete target-language instructions. Do not create a target file from an obsolete source and assume that because its name matches, it is current. Record the source revision and the target review date. Separate ordinary prose from placeholders, embedded components and links that require technical protection.
Create a short help article in a test environment with a default file and one localized variant. Confirm which file the actual public site loads and what happens when the target is absent. Then revise the source and check how the editor knows the translation needs review.
8. Map translated mail templates to the visitor’s language
October CMS content and mail template translation is not complete unless outgoing messages use the intended locale. A registration form may load a French page while the mail-sending code selects an English template. Check the sender workflow, not just the template filenames. Preserve activation links, order codes, user identifiers and recipient addresses. Translated subject lines should accurately describe the action; a subject that promises confirmation while the email requests verification changes the message’s purpose. Internal staff notifications may deliberately remain in another language, but that decision should be documented.
Submit a non-sensitive test registration in two locales. Examine the visible confirmation, message subject, body, personalization, links and language of the landing page. Test missing templates and observe whether the fallback is labelled and acceptable.
9. Treat the language picker as a content-identity control
A dropdown that lists site languages is only the beginning. October CMS provides the SitePicker in contemporary multilingual workflows. When a visitor stands on a particular article, its alternate should normally lead to the true counterpart, not simply the target homepage. If the exact article is unavailable, use a declared missing-language outcome. Ensure the selected-language indicator reflects the delivered content. Avoid using flag icons as if one flag represented every speaker of a language. Language choice should be accessible from keyboard and understandable without relying solely on colour or symbols.
Begin at a deep French route, switch to English and back, follow a related link and refresh. Compare article identity, URL, heading and menu state. Repeat with one missing translation. A correct selector does not fabricate article equivalence.
10. Configure static page URLs as stable public promises
RainLab.Translate includes support for localized CMS page URL properties. A static page may have one source path and approved overrides for other locales. Choose a policy for localized slugs and whether the default language uses a prefix. Do not regenerate URLs merely because an editor improves a heading. Preserve redirects where content identity remains equivalent, and reject collisions where two pages would claim the same route. Non-ASCII paths deserve testing for encoding and copy-paste behaviour. An old English path should not accidentally display an unrelated French page after a routing change.
Test a contact page and a nested information page in each language. Open both directly, inspect the final URL and test a retired alias. Record which page or 404 the server actually returns, not what the editor preview suggests.
11. Resolve dynamic slug parameters to target records
Dynamic pages introduce a second layer of routing. The locale prefix may change successfully while the slug parameter still identifies an English model record. RainLab.Translate documentation describes hooks for overriding site-picker parameters, enabling applications to map the current item to its translated counterpart. The safe strategy begins with a stable record relationship and then retrieves the authorised target-language slug. Blindly machine-translating a route token can cause collisions, wrong products or links to nonexistent entries. When a target record is missing, the system should offer an honest alternative rather than guessing.
Make two similar product names with separate model identities and different language slugs. Switch from each English item to French and verify the exact record returned. Rename a title without changing the underlying identity and repeat the test.
12. Decide which query parameters survive a language switch
Search terms, filters, pagination, tracking tags and transient tokens do not all belong in the same preservation rule. RainLab documentation describes ways to override query handling when changing sites. Some parameters can carry user intent across languages, while others may expose state that is invalid or sensitive on the new route. A translated filter label is not necessarily a translated machine value. Preserve only parameters with documented meaning, and check whether target-language search queries should remain as written or be transformed by an approved mapping. Avoid automatic rewriting that silently changes the user’s requested result.
Switch language on a filtered course listing with page number and category set. Confirm that the result set still matches the selected criteria. Then test a one-time-looking token and verify that the application does not copy it indiscriminately into unrelated target URLs.
13. Understand fallback as a visible publishing decision
Untranslated fields may fall back to default-language values under documented model behaviour. That convenience can conceal incomplete localization. A shared brand name that appears identical across languages may be correct; a source-language safety warning on a French page may not be. The RainLab.Translate documentation also describes no-fallback access for inspection. Use it to distinguish a stored target value from a substituted default. Do not infer approval from a rendered value merely because the page looks populated. Classify fallback policy by content risk and require transparency where the visitor might misunderstand a mixed-language page.
Create a French model record without a description, then test the public output and a supported no-fallback retrieval. Record what is stored versus what is displayed. Decide whether the page is acceptable, needs a labelled warning or should remain unpublished.
14. Check identical source and target values carefully
Some documented RainLab.Translate model behaviour can treat a target value identical to the default as untranslated rather than storing a duplicate. That makes a visual test ambiguous. A brand or technical term might be intentionally identical in two languages, while a generic English sentence that was never translated is not. A professional workflow needs a way to record reviewed sameness independently from database fallback. Do not force translators to introduce unnatural wording merely to make a field appear different. Instead use an approval note or review record to distinguish intentional retention from omission.
Choose a product name that is identical in French and English and a description that should differ. Inspect storage and rendered results. Ask a reviewer to justify retained values. A correct outcome preserves natural language and makes the distinction auditable.
15. Localize settings models without touching operational secrets
Settings models may hold a company description, social link label, contact information or configuration value. Some text is appropriate for language variation, while operational identifiers, API keys, mail destinations and file paths must remain protected. A translated settings field should not alter how the application authenticates or sends requests. Where a footer’s legal statement differs by market, attach an approved local source rather than asking the translator to rewrite its conditions. Review how each translated settings value is retrieved so one site’s output does not unexpectedly leak into another site.
Create a test footer with name, description, address, API-related value and legal line. Classify fields and translate only the appropriate ones. Render all languages and verify that operational references remain unchanged.
16. Keep navigation both readable and destination-correct
A menu item is a label and a promise of a destination. October CMS navigation may be assembled from CMS pages, partials, custom components or static-page structures. Identify where each link is generated and whether it targets a published language counterpart. Translating a menu title while its URL points to English content makes the experience misleading. When a destination is deliberately shared, such as a third-party login, the link text can explain that behaviour. Test desktop and mobile navigation separately; they may use different partials and caching. Breadcrumbs are especially useful for revealing wrong parent relationships.
Travel from a French article to a category page, then a form and back. Record each URL and title. Repeat after unpublishing a target item. A menu that still advertises the missing page fails even when its text is fluent.
17. Test category listings and related-content queries
A correctly translated article can be inaccessible if listing components query source-language attributes or fail to filter by active site. Related cards can also select the wrong locale of a model record. Determine how the CMS queries localized fields and how missing translations are handled. Stable category identity may be shared across languages while the visible label changes. Do not duplicate concepts simply because their names need translation, but allow distinct classifications if business meanings really differ. Review search and category components after adding new English-only items, because uncontrolled fallback can reintroduce mixed-language listings.
Search for a phrase present only in the French version and click its result. Inspect the displayed title, excerpt, route and content record. Repeat after removing that translation. The release policy should define whether the item disappears or shows an explicit fallback.
18. Preserve meaningful data and structured identifiers
A model may display prices, dimensions, event dates, eligibility restrictions and references alongside prose. These facts need a source of truth independent from translation. A date can be formatted for Japanese readers without becoming a different day. A currency can be displayed using locale conventions without authorizing an unapproved conversion. Technical codes should not be translated. Conversely, natural-language explanations need full grammatical freedom, including different word order around protected tokens. Supply translator notes for facts that look like ordinary text but carry contractual meaning.
Build a course page with a code, deadline, price and warning. Compare every factual value after translation and check the authority for any legitimate market change. Do not publish a target merely because its sentence flows smoothly if the underlying conditions are wrong.
19. Translate assets, captions and accessible labels independently
An image may serve all languages while its description and caption need translation. A labelled diagram or screenshot containing English instructions might require a different image. October CMS may store media references in model fields, CMS content or custom components; inspect actual ownership. Keep image credits and rights information intact. A translated article that links to an English-only downloadable form should label that limitation or provide a translated asset when required. Alternative text must describe the image’s purpose for the target reader rather than repeat a mechanically translated filename.
Review a photograph, an annotated chart and a PDF from one target page. Inspect alt text, visible captions, embedded labels, download file and next action. A successful file download is not proof of translated meaning.
20. Include forms, validation and consent in every test
A multilingual form contains labels, helper text, validation messages, consent notices, success responses and follow-up emails. October CMS extensions may supply their own language messages, and theme phrase translations may not reach them. Keep field identifiers, CSRF tokens and internal email addresses protected. A privacy statement may be market-specific and require approval from a responsible owner. The administrative recipient’s language can differ from the visitor’s; that should not cause the user’s confirmation to arrive in the wrong language. Test a failing submission as well as a successful one.
Submit a safe enquiry with one missing required value, correct it and complete the form. Inspect the resulting message, email and redirect in two languages. Repeat on mobile. A project is not finished if people can read a page but cannot understand the task that follows.
21. Keep cache behaviour separated by locale
Language-sensitive fragments can be accidentally reused across sites if a cache entry fails to distinguish active locale. The defect may appear only after an English request warms the cache and a French visitor arrives later. Editor previews may also show newer text than public pages. Understand the CMS, application and infrastructure cache boundaries before troubleshooting. Do not solve persistent language leakage by turning off caching everywhere. Find the smallest missing locale variation or invalidation step, correct it and test the sequence that originally caused the error.
Alternate English and French deep requests in two independent sessions, comparing body, menu, footer and metadata. Repeat after a translation update. If visit order changes the language, preserve the exact reproduction steps and investigate the caching or selection layer.
22. Review search metadata at its actual output point
Translated titles and descriptions often come from CMS page properties, model fields or SEO extensions. Find the real owner of the rendered HTML. A French article with an English meta description presents a confusing search snippet, while an invented French claim can mislead readers. Translate naturally for target-language search intent without keyword stuffing. Keep titles aligned with the article’s real topic and maintain stable URL slugs under an explicit policy. Test special characters and non-ASCII route segments in the published HTML. An editor form can contain the right values while a theme still renders the source-language fields.
Open the public target URL while logged out and inspect the HTML title, description and main heading. Compare these with the model and page source. Test one page whose locale-specific title is longer than English to catch truncation or layout problems.
23. Emit international alternate tags only for actual equivalents
Hreflang and canonical output must describe real public pages. A site can have several configured languages even when some article translations are missing. Never loop through every site definition and generate alternate links unconditionally. Resolve each target counterpart, confirm it is published, and check its final URL after redirects. A target homepage is not the alternate for a source article unless it is genuinely the same content purpose, which is unusual. Decide how the global default or x-default works before implementation. Search metadata should not disguise an incomplete target page as ready.
Build a three-language test page with only two approved counterparts. Inspect all advertised alternates and open their destinations. Remove any reference to the missing version. Repeat after a target is unpublished to ensure the metadata updates.
24. Check accessibility and right-to-left layout
International localization is not only about language strings. Some target languages use right-to-left reading direction, different line-breaking conventions, longer words or different typographic punctuation. Review the active site’s document language and direction, form focus order, icons, breadcrumbs and mixed-direction codes. An Arabic sentence containing a protected SKU can be grammatically accurate yet visually confusing if punctuation and directionality are mishandled. Do not reverse numerical identifiers or make an icon’s meaning depend solely on its position. Use native-language reviewers and actual devices wherever possible.
Render a target page with a long heading, a form, a table and a technical code. Navigate by keyboard and inspect the reading order. Record whether each element is usable, not simply whether the text changed.
25. Track source revisions and reopen affected translations
A source-language editor may change a course’s deadline, rewrite a promise or remove a discontinued feature. Target translations need different responses depending on the semantic change. A punctuation fix may require no new translation, whereas a revised eligibility condition must be checked. Maintain source revision, target review state and public URL outside any single rendered field. If the installation does not provide a complete translation workflow, use a controlled editorial register. Do not silently keep old claims live because the language selector still works.
Simulate one minor heading correction and one changed application date. Record who reviews each target and why. Update the appropriate model or file, then check the actual public page and outgoing email for the new condition.
26. Maintain a missing-language and retirement policy
When a page or locale is withdrawn, the site may face bookmarks, search results and language switch links from the past. Decide whether an equivalent successor warrants a redirect, whether an archive is retained or whether a clear unavailable state is more accurate. Avoid redirecting everything to the global homepage merely to eliminate broken links. A retired French product page should not turn into an unrelated English sales page. Keep backups of translation relationships, model data, localized content files and route mappings before upgrades or migrations. Test return paths for readers who already have an old URL.
Remove one test target translation while leaving the English source intact. Observe the public page response, SitePicker and alternate metadata. Compare the outcome with your documented policy, then fix any mismatches before doing bulk retirement.
27. Plan plugin and core changes as content migrations
Version upgrades may change the way localized attributes are stored, retrieved or edited. RainLab’s maintained guidance addresses transitions in its localization approach and notes coexistence with newer core features. A migration should preserve meanings, IDs, field definitions, fallback behaviour, URL relationships and human approvals. Copying the last visible HTML is not enough. Perform a staged inventory and test representative items before moving production content. Review forms and mail because they often rely on different code paths from ordinary articles. Maintain a rollback plan appropriate to the site architecture.
Use a test set with one fully translated item, one intentional fallback, one Unicode slug and one missing counterpart. Compare those four cases before and after an upgrade. If the result differs, determine whether it is an intended platform change or a defect.
28. Release by walking a real visitor journey
The final quality gate should resemble what a visitor actually does. Enter through a search result or direct URL, read the localised page, switch language, browse related records, complete a form, open a download and return. Have a linguistic reviewer check meaning and tone, a domain reviewer check protected facts and a developer check routing and code. Keep precise public URLs, screenshots and revision identifiers in the release record. A page with perfect French wording may still fail when the next click opens English-only instructions or a hidden form error appears in a different language. A successful workflow is one another editor can repeat.
Test the same route on desktop and mobile, while logged out, with a fresh session. Change one target field after approval and ensure the release workflow catches it. Verification should measure what readers receive, not what the dashboard claims is complete.
Worked example: a three-language course catalogue
Consider an international course catalogue with English, French and Japanese versions. Its course model contains a code, name, duration, price, description, booking URL and promotional image. Classify the code as protected identity, name and description as translatable, duration as structured data and price as an approved market value. Select a supported translation mechanism for the model, configure each site locale and create a stable counterpart relationship so translated slugs refer to the correct course. Translate the Twig navigation phrases, course summaries and field labels separately. Do not assume that because the French page title exists, the payment instructions and email are ready.
Now an editor changes an enrolment deadline. The business owner updates the authoritative record and triggers language review. The French and Japanese reviewers check the meaning, while the developer verifies the route, form, confirmation email and metadata. A test reader arrives at a deep link and completes the intended action without losing language or encountering stale conditions. That complete path, not the field count, defines success.
Worked example: correcting a broken language switch
A visitor opens a product detail page in English and chooses French. The browser changes the route prefix but keeps an English product slug, producing a 404. Capture the original and destination URLs and inspect the active site. Check that the product has an approved French counterpart and corresponding slug. If the route uses a dynamic parameter, make sure the language-switch logic resolves the counterpart record rather than simply translating the prefix. Avoid adding a broad redirect to the French homepage as a shortcut, because that conceals the actual identity failure.
After correcting the mapping, repeat the switch in both directions and refresh each deep URL directly. Check alternate-language metadata and the related product card. The fix is complete only when a new visitor can reach the correct item without relying on an editor session or obsolete cookie.
Worked example: separating translation from market adaptation
A French business site serves two markets with different delivery restrictions. The descriptive product paragraph can be shared, but the shipping conditions must come from independently approved market data. A translator should not copy the first market’s legal wording into the second and assume that French means identical conditions. Configure the content model to represent language and market separately, and provide the translator with an explicit note identifying which facts are protected. Review what happens when the shared French description changes and when only one country’s delivery policy changes.
Test both market URLs and inspect the rendered terms, buttons and follow-up emails. Record why the wording legitimately differs. Without that provenance, a later editor may mistakenly harmonize the text and remove an important legal distinction.
Four-week learning and publication plan
In week one, inventory sites, locales, versions, models, theme messages, content files and public routes. In week two, build one complete multilingual article and one dynamic model item, including SitePicker behaviour and translated slugs. In week three, extend to forms, email, images, fallback, search and accessibility. In week four, test public SEO metadata, source revisions, missing counterparts and retirement procedures, then document a repeatable release checklist. Avoid expanding to dozens of pages until the first full journey is reliable.
As a final exercise, give a trainee an English product page with a protected SKU, an image containing labels, a changing deadline, a missing French model field and a mail template. Ask them to predict which values will be stored, translated, inherited or blocked, and then verify the actual public result. Each unexpected result becomes a documentation task.
Frequently asked questions
Does RainLab.Translate replace all core localisation facilities?
No. The relationship depends on the installed October CMS release. Modern versions have multisite and newer native translation options, while RainLab.Translate continues to provide supported functionality. Verify the current setup rather than following old examples blindly.
Why does a translated route still show English text?
The route may select the correct site while a model attribute, theme message, content file or cached component falls back to the default language. Inspect each owner separately.
Should a language picker always link to every language?
Only when a genuine equivalent page or an honest explicitly labelled alternative exists. A configured language does not prove that a particular item has been translated.
How can I check search SEO after translation?
Inspect the public page’s title, description, canonical URL and available alternate-language links; follow each link and check that the destination matches the same underlying content.
Official documentation and further learning
Consult the October CMS RainLab.Translate extension documentation for site selection, translatable model attributes, fallback, translated URLs, query overrides, localized templates and migration guidance. For newer implementations check the maintained RainLab.Translate repository and your installed October CMS release notes before adapting an older example.
For the wider translation process, visit Master Art of Translation: The Complete System or the Translate Like a Pro Series Index. This guide owns October CMS implementation, multilingual site delivery and QA rather than generic translation strategies or vocabulary explanations.