ApostropheCMS Translation and Localization Guide

How do you use ApostropheCMS to create a reliable multilingual website without mixing up language settings, translated content, routes and publication status? This ApostropheCMS localization guide explains the actual platform features, practical editor and developer decisions, and the checks needed before visitors see a translated page. It is written for website editors, developers, localization teams and product owners building multilingual Apostrophe pages and pieces in any country.

The important distinction is that language availability is not the same as translation accuracy. A site can expose a locale selector yet show the wrong record, an untranslated component, an outdated claim or a draft that has not been approved. This walkthrough concentrates on the relationship between the @apostrophecms/i18n configuration, translated template strings, locale-specific page and piece documents, related content and per-locale publication. It separates text that readers may need adapted from codes, dates, references and actions that must keep their original factual meaning.

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

What this ApostropheCMS guide covers

The article gives a practical approach to the relationship between the @apostrophecms/i18n configuration, translated template strings, locale-specific page and piece documents, related content and per-locale publication. It does not promise universal functionality across every edition, tenant, plugin or historical version. The platform documentation named later is the reference for available features. Where a capability is described as a beta, optional extension or plan-dependent feature, the article treats it as something to verify rather than something every account already possesses.

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

Configure locales through @apostrophecms/i18n, with defaults and optional URL prefixes or hostnames
Separate static template strings from editor-managed pages and pieces
Keep localized documents linked while publication status stays independent
Understand action-menu localization of related documents versus blank inline-locale creation
Test visitor language switching, source revisions, incomplete locales, and right-to-left layouts

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

A worked world-facing project

A community science museum publishes exhibition pages, ticket advice and visiting information in English, French and Arabic. The French editorial team adapts opening-hour descriptions; Arabic requires right-to-left presentation; all languages must refer to the same actual admission conditions. A relationship field connects the exhibition to curator profiles and image captions. The project needs different words, not different facts about admission.

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

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

A safe division of responsibilities

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

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

The platform mechanisms that matter first

1. Configure locales through @apostrophecms/i18n, with defaults and optional URL prefixes or hostnames. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
2. Separate static template strings from editor-managed pages and pieces. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
3. Keep localized documents linked while publication status stays independent. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
4. Understand action-menu localization of related documents versus blank inline-locale creation. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.
5. Test visitor language switching, source revisions, incomplete locales, and right-to-left layouts. Ask how the corresponding configuration is represented in a test environment, what an editor can see, and what a signed-out visitor can retrieve.

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

1. Locale naming and planning

The i18n module defines locale keys such as en, fr and ar rather than inventing languages from each visitor request. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. The museum plans English general pages, French visitor copy, and Arabic information before a page is entered. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Creating content in an unintended implicit default locale can leave old documents invisible after configuration changes. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Choose explicit stable locale keys and record a source-content ownership policy before commissioning translation. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Create one document under each configured locale and confirm the intended editor sees it. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

2. Default locale selection

Apostrophe uses the configured defaultLocale or the first configured locale when a request has no more specific match. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A tourist visits the unprefixed exhibition URL after following a printed QR code. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Changing defaults after content entry can send visitors to a language where some pages were never created. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Use an intentional defaultLocale and inventory existing content before changing the project’s language configuration. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Visit the bare hostname in a clean browser and compare its contents with the expected default-language record. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

3. Path-prefix routing

Locale definitions can include prefixes such as /fr and /ar; the requested path then helps determine language. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A French guide links directly to /fr/expositions rather than asking visitors to select French after arriving. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. An incorrect localized path can appear to be a translated page while actually resolving through a default route. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Treat path prefixes as routing contracts; reserve them, test canonical destinations and map old public URLs carefully. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Open copied links, reload, remove cookies and confirm the content and HTML language remain French. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

4. Hostname routing

Apostrophe can associate a hostname with a locale, using matching priorities when hostname and prefix coexist. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A regional organization operates a country-facing domain and a second language path under its main brand. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Overlapping hostnames and prefixes can make two teams think they own the same localized destination. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Document the locale match priority, hostname configuration and base URL before configuring reverse proxies or DNS. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Request each hostname and prefix combination and check the active locale and intended document, including an unmatched host. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

5. The difference between route and translation

Selecting a locale changes which content may be rendered; it does not translate an English paragraph automatically. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. An editor adds Arabic to configuration and expects all English event details to appear in Arabic. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A functioning selector can mask untranslated or missing documents until someone tests a deeply nested URL. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Create target documents, translate the fields deliberately and set a completeness threshold per release. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Check an untranslated article URL directly; the outcome should match the deliberate missing-locale policy. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

6. Static template strings

The __t helper is used for static strings in templates, including headings that do not belong in each document. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. Every exhibit page displays a ‘Related exhibitions’ heading defined once in a template. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Copying the heading into each page makes one translation change require hundreds of editorial updates. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Use a stable static key and central JSON resource for repeated interface copy; leave editor-owned descriptions in documents. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Change the static phrase once in a test locale and confirm it updates everywhere without changing other texts. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

7. Module JSON resources

Apostrophe documentation places translation JSON under module i18n directories and resolves keys for active locales. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. The ticket module stores short strings for ‘Book a visit’, ‘Sold out’ and ‘Accessibility information’. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Duplicate keys across modules or missing files can replace meaningful labels with source language unexpectedly. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Name keys by function and keep dictionaries under the correct module or namespace; review resource loading after builds. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Render the same shared widget in three locales and inspect every visible status label. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

8. Interpolation and variables

Static translation helpers support placeholders so a sentence can reorder dynamic information naturally. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A banner says that the London office will close at a specified date; a different language may move the city name. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Constructing the sentence from separately translated fragments creates ungrammatical or misleading notices. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Translate the complete grammatical pattern and pass named values through supported interpolation rather than string concatenation. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Test city names with spaces, non-Latin characters and a long closure date without altering their factual values. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

9. Namespaced keys

Static resources can be namespaced to reduce collisions with core interface strings or unrelated modules. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A visitor-facing ‘open’ key means exhibit availability but the internal admin UI also uses ‘Open’ for a dialog. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A broad reusable key may silently borrow the wrong translation because context is not represented. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Choose module-specific names such as visitor.exhibitOpen and preserve administrative namespaces. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Search the resource tree for collisions and render the admin and visitor screens in the same locale. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

10. Editor interface strings

The CMS admin interface and visitor-facing frontend have different text sources and language audiences. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A French content editor works in the administrative UI while reviewing an Arabic visitor page. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. An editor’s interface language must not be mistaken for the language of the document being edited. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Treat adminLocales, editor preference and document locale as separate controls; document who switches which one. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Ask a multilingual editor to identify document locale and admin locale independently during a review. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

11. Schema field labels

Admin schema captions may require browser-available namespace resources when used in custom modules. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A piece type has fields called ‘Visitor instructions’, ‘Accessibility note’ and ‘Opening date’. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. An untranslated schema caption can cause an editor to put a legally required note in the wrong field. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Localize schema labels with appropriate namespaced keys and ensure client-side resources are enabled where required. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Open a piece editor in a non-default admin locale and check caption, help text and value behavior. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

12. Pages as localized documents

Localized page versions are distinct documents tied by locale identity, not one body with an automatic on-screen swap. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A temporary exhibition opens later in one region; the French page needs a different local transport paragraph. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Replacing an English page body with French text would remove the source for every other audience. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Create a linked target-language page document and record the source version used as its reference. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Edit an Arabic paragraph and verify the English and French versions remain unchanged. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

13. Pieces and structured content

Pieces are reusable managed documents and can have locale-specific versions just as pages do. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A curator profile appears in multiple exhibition pages and requires an approved French biography. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A page may be translated while its relationship still points to untranslated source-language biography. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Map relationship usage before localization and decide whether related pieces also need target versions. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Open the profile directly and through each exhibition page to confirm the same approved locale. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

14. Localize action menu

The documented action-menu localization workflow can clone a document with options for related documents. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A page includes event cards, an image item and a contributor profile related through widgets. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. An indiscriminate clone operation can create unwanted linked records or overwrite editorial work in a destination locale. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Choose ‘this document’ versus related-document options consciously; review the confirmation choices before executing. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. After localization, audit the created target pieces and compare relationships with the source graph. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

15. Related-document overwrites

Re-localizing material can overwrite existing target-locale edits depending on selected options. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. The Arabic team updated a venue-access paragraph after the original English exhibit page was cloned. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A later routine source relocalization may replace the localized safety wording with stale English content. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Keep a revision inventory, designate who may overwrite target copies and require a visible diff for destructive re-localization. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Introduce a harmless target-only sentence in staging and prove it survives the intended update workflow. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

16. Inline locale switcher

The inline switcher can create a linked but blank target document instead of copying all source text. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A French editor intentionally wants an original interview different from the English counterpart. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Assuming an inline switch automatically copies text may lead to publication of a mostly empty document. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Use inline creation for deliberate editorial divergence and use action-menu cloning when source structure is needed. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Switch to a missing locale and confirm exactly which fields are populated before drafting. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

17. Localized draft lifecycle

Newly localized documents begin as drafts and need their own publication action. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. A Spanish audio guide page is approved while the Arabic accessibility notes are still in review. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Publishing the original language never proves a newly created translation is visitor-visible. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Track publication status separately for every language and assign a release approver per target version. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Use a public signed-out session to confirm only the approved localized page is reachable. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

18. Source edits after localization

Source-language updates do not automatically guarantee target pages reflect the revised content. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. A ticket cancellation rule changes on Thursday after French and Arabic versions were translated. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Readers might see contradictory refund rules across locales even though every page is technically published. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Attach change ownership to shared factual claims and open translation-review tasks for affected target documents. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Change a sample fee rule in staging and test the alert and revision path for all related locales. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

19. Missing localized pages

Apostrophe documentation notes that missing localized page documents are not automatically served by default-locale fallback. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. The Arabic museum site has no localized page for a highly technical conservation lecture. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A visitor selector may link to a non-existent destination and falsely suggest the content is available. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Distinguish absent content from untranslated content and make the language switcher show only credible destinations. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Check available flags, direct deep links and a missing translation scenario from search results. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

20. Visitor locale switcher

Template localization data provides locale labels and destination information that can support a real visitor switcher. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A visitor on a French exhibit wants the corresponding Arabic page, not the Arabic homepage. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A switcher wired to generic home URLs destroys article context and interrupts the task. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Use the locale association data and only link where the localized counterpart exists and is published. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Move between languages on one exhibit, then use Back and bookmarks to confirm stable counterpart navigation. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

21. Directionality and RTL

Locale configuration includes a direction property and templates can apply it to RTL content. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. Arabic museum captions combine right-to-left prose with Latin catalogue identifiers and dates. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Mirroring all strings or reversing identifiers can make item numbers, URLs or ticket references incorrect. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Set logical direction in the HTML layout and isolate embedded Latin IDs where necessary without modifying stored strings. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Inspect long captions, forms, icons and mixed-script ticket numbers using a real Arabic reviewer. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

22. Locale-specific images and alt text

Dynamic content localization can adapt imagery and language-dependent captions, not just visible paragraphs. The safest workflow distinguishes editorial meaning from technical identity. A visitor can see a regionally natural expression while the application retains stable keys, links and record relationships.

Example. The English museum map contains labels printed inside an image and a French visitor page reuses it. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. A page can look translated while an inaccessible image or alt description remains English-only. Teams often discover this boundary only after a public complaint. Make it visible during planning by marking what may change with language and what must remain invariant between versions.

What to do instead. Audit images with embedded words; supply locale-appropriate accessible alternatives and confirm rights for replacement media. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Turn off images, inspect accessible names and compare localized map directions against the actual venue. Check the complete interaction on a staging or preview site first, and repeat the most important part from a signed-out public session. Those two views answer different questions.

23. Slug accents and SEO

The i18n module includes a stripUrlAccents option for new slugs, but slug changes may affect external links. Do not treat a populated translation field as proof that the reader’s task is complete. Follow where the information goes after it is saved, including its route, preview, dependent widgets and real public output.

Example. A French title produces a slug containing accents, and editors worry about URL display in printed materials. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Changing normalization after content has been indexed can accidentally break permanent links. This is where localization differs from editing an ordinary paragraph. Several software layers can contribute separate pieces of the final sentence or page, so one green status indicator is not enough.

What to do instead. Decide URL policy early and treat retroactive slug rewriting as a separately approved migration rather than a translation edit. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Open old and new URLs, check intended redirects and inspect localized title and canonical decisions. Record the observed state before fixing it. A wrong text value, missing locale record, unexpected fallback and stale cached page may look similar but require different remedies.

24. Permissions and responsibility

Editors may have separate permissions and workflows even if locale UI controls are visible to everyone. Use a small controlled example first, then scale only after its behavior is understood. One record with known identifiers and a predictable approval state is more useful than a hundred unverified translations.

Example. A volunteer translator is allowed to edit exhibit prose but not change publishing or ticket-sale rules. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Giving translators general publishing rights may let unreviewed information reach visitors. Ask a second reviewer to check what the user is being told, not just whether each dictionary entry sounds natural. The question is whether the action, obligation or explanation still means the same thing.

What to do instead. Design role boundaries for translation, review, source ownership and final publication; test with a real least-privilege account. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. Attempt a translation edit and a publish action with the translator role and record the expected access result. Retest the original language as well as the target language. A localization change that improves one page while damaging the default site is not a successful release.

25. Regression and launch evidence

A working multilingual site needs end-to-end evidence for content, links, errors and business actions. Begin with a real reader journey rather than an abstract language toggle. The source decision has to be intelligible after localization, and the content owner should know exactly which fields and linked resources are involved.

Example. An updated ticket widget is deployed shortly before a school-holiday exhibition launch. Before applying the change, write down the content identity, requested target locale, expected public result and source of factual truth. If the page contains links or reused content, include those dependencies in the same record so the example remains testable after the next release.

Common failure. Screenshot-only approval may miss a destination page that opens in the wrong language or an empty translated relationship. This is a content-model question as much as a linguistic one. A correct noun in the wrong object, or an approved phrase attached to the wrong version, still creates a misleading result.

What to do instead. Run a small route matrix across language, role, device, document and release version; capture failures with a reproducible URL. Avoid solving this by inserting extra translated words into a place where the underlying record, route or permission is wrong. Correct the appropriate system layer, then ask the reviewer whether the result remains accurate and helpful.

Evidence of success. For every approved locale, complete one public visitor journey and confirm source facts, target wording and live links. A useful defect report gives the locale, record, public route and the action that exposed the error. That makes the repair reproducible and prevents a superficially successful text edit from hiding the original fault.

A release plan readers can actually use

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

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

Frequently asked questions

Does the locale switcher translate a page automatically?

No. Locale configuration and routing identify language-specific documents; editorial translation and publication remain separate work. An optional automatic-translation extension can assist where installed and permitted, but it does not replace target-language review.

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

Should static strings and pages be translated the same way?

No. Repeated template labels belong in static translation resources; editor-managed descriptions, pages and reusable pieces belong in localized documents. Confusing them causes duplicated work and unpredictable updates.

What happens if an Arabic page is missing?

Do not assume Apostrophe substitutes the English document. Check the published localized document and the visitor route; design a clear unavailable-content experience or deliberate alternative route.

Can a translation overwrite the French editor’s changes?

Re-localization options may overwrite an existing target copy. Inspect related-document selections and maintain revision evidence and approval boundaries before replacing localized documents.

How is the best default locale chosen?

Choose it by audience and route policy before content entry rather than relying on implicit configuration. Verify the unprefixed domain and direct links in a clean browser.

Can a visitor switch to the same article in another language?

Yes when the target page exists and is published. Build the switcher from locale counterpart information, not simply by constructing arbitrary prefixed URLs.

Do Arabic and Hebrew require extra engineering?

Yes. Language-specific content is only one part: direction, mixed-script identifiers, alignment, keyboard order and image alternatives all need contextual testing.

How should publishers prioritize defects?

Start with misleading prices, consent, accessibility and visitor instructions; then fix missing routes or major readability issues; finish with cosmetic terminology variations. Record the change and test the live result.

Official documentation and further reading

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

Where this article belongs in the eduKate translation library

Architecture: EDKSG-TRANS-MASTER-WORLD-6210. This child owns the relationship between the @apostrophecms/i18n configuration, translated template strings, locale-specific page and piece documents, related content and per-locale publication. The Master Art of Translation is the canonical owner of general translation principles, such as moving meaning between languages and controlling semantic quality. The Translate Like a Pro series index is the discovery route to sibling software-specific guides. Other Translate families cover their own language, task and quality questions; this guide deliberately stays with ApostropheCMS implementation, delivery and testing.

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

Translate Like a Pro | 6210 — ApostropheCMS Localization, Locale Routes, Static Strings, Linked Documents and Draft QA