Localization

A RHEA site can serve several languages from one EDS site: one AEM site tree, one site configuration, one Cloudflare worker and one domain, with a folder per language. This page describes that pattern, and what a site adds to use it.
RHEA itself ships English only, and none of this is built into the template. It is a pattern for consuming sites: a site that needs another language adds the configuration and code described below.

Structure

Each language is a folder under the site root, named with its ISO 639-1 language code. English is the master and is served at the root, so English URLs carry no prefix, and an English-only site keeps its URLs when it adds a language.

/content/<site>
├── en/                    English master          → /
│   ├── index              home page               → /
│   ├── nav, footer, isi, cookie-consent-banner, fragments/404
│   ├── placeholders       UI strings sheet        → /placeholders.json
│   └── products/…                                 → /products/…
├── fr/                    Language Copy of en     → /fr/
├── es/                    Language Copy of en     → /es/
└── metadata               bulk metadata sheet     → /metadata.json
Inside each language folder At the site root
Every page a visitor reads, including the fragments RHEA loads by fixed path (nav, footer, isi, cookie-consent-banner, fragments/404) and the placeholders sheet. Each language has its own copy of each. The metadata sheet, and anything that is never translated, such as an archive or test pages. Outside a language folder, AEM never adds them to a translation project, and they keep their URLs.
AEM path Public URL
/content/<site>/en/index /
/content/<site>/en/products/overview /products/overview
/content/<site>/fr/index /fr/
/content/<site>/fr/products/overview /fr/products/overview
/content/<site>/es/nav /es/nav

The master copy

The English folder, /en, is the master. No separate language-masters folder is needed, and neither is a country level such as /us/en.

  • AEM finds languages by name. A page is a language root when its name is an ISO 639-1 code, optionally with a country (fr-ca). That is the only requirement. The language-masters folder in Adobe's WKND example is a naming convention.
  • Language copies sit beside the master. AEM looks for a language root's other languages next to it, or at most one grouping level below. /en, /fr and /es as siblings is the layout it expects, and it is also the layout the site serves.
  • A country level changes the model. Copies of /us/en would land beside it, under /us. Country sites such as /fr/fr and /es/es instead need a language-masters tree that is translated and never published, plus an MSM live copy per country. That is more trees for authors to manage, and Adobe's guidance advises against putting the market before the language in URLs.

If a market variant is needed later, such as French for Canada, add it as another language root (fr-ca) beside the others.

Path mapping

A second mapping in the site's configuration puts English at the root. It goes in .public.paths of the env's site.json in abbvie-migrated/eds-site-config:

"paths": {
  "mappings": ["/content/<site>/:/", "/content/<site>/en/:/"],
  "includes": ["/content/<site>/"]
}

When several mappings match, the last one wins. English pages match both rules and take the second; every other language, and the pages at the site root, fall through to the first.

EDS applies the mapping when a page is published, so links, fragment references and path metadata in the published HTML are already public paths. The CDN only ever sees public URLs, so the Cloudflare routing worker and DNS need no change when a language is added. See Environment Access Control for how the worker routes each hostname.

Per-language settings

A bulk metadata sheet at the site root sets each language's page language and fragment paths, so authors never set them page by page:

URL html-lang navPath footerPath isiPath cookieConsentPath
/** en
/fr/** fr /fr/nav /fr/footer /fr/isi /fr/cookie-consent-banner
/es/** es /es/nav /es/footer /es/isi /es/cookie-consent-banner
  • Rows apply top to bottom, so the site-wide /** row comes first.
  • html-lang is an EDS special property: the server renders it as the page's lang attribute, with no script involved. Use a region tag such as fr-FR when the copy is written for one country.
  • English needs no fragment paths, because RHEA already defaults to /nav, /footer, /isi and /cookie-consent-banner.
  • EDS writes the column names in lower case (navpath). RHEA's metadata lookup reads every casing, so that needs no handling.

Translating content

  1. In the Sites console, select /en and choose Create → Language Copy.
  2. Pick the target languages and Create translation project(s). The project appears in the Projects console, where pages can be added later.
  3. Translate and review, then publish the language folder.
  • Translation rules. AEM translates the properties its translation rules name. Check that they include RHEA's custom field names, for example the ISI's fullContent and bannerContentCollapsed or the CTA's ctaContent, under Tools → General → Translation Configuration. Fields the rules miss stay in English. Adobe's reference demo also adds a reference rule for core/franklin/components/block/v1/block, so that content a block references is translated too.
  • Translation service. Machine translation sends page content to a third-party provider, so it needs an approved vendor. Without one, a translation project can export and import XLIFF files, or authors can translate the copy in the Universal Editor.
  • Keep the English page names. Language Copy keeps them by default, and the shared names are what pair /products/overview with /fr/products/overview for hreflang. Translated page names would need a primary-language-url metadata value on every page.
Translated ISI and safety text needs the same medical, legal and regulatory review as the English source before it is published. Machine translation does not change that.

What a site's code needs

Published pages need little code, because the mapping and the metadata sheet do most of the work. These are the gaps a site fills when it adds its first language:

Concern Change
Page language RHEA's loadEager sets the page language to en unconditionally. Keep the value the server rendered, and fall back to en only when there is none.
404 page 404.html is served from code and gets no page metadata. Load /fr/fragments/404 when the requested path starts with a language folder.
UI strings Button text and ARIA labels are hardcoded in block JavaScript. Move them to the placeholders sheet, read per language from /fr/placeholders.json, with today's English text as the fallback.
Universal Editor paths In the editor, RHEA sees raw JCR paths and removes /content/<site>/ with stripJcrPrefix. It must also remove the en/ root, or English fragment paths resolve to /en/… while editing.
Search Read the language's own query index (see below), or filter results by path prefix.
Language switcher Link to the same path under the other language's prefix, after checking that language's query index for the page. Adobe also recommends remembering the visitor's choice, in a cookie or local storage.

Each change does nothing on a site without language folders, so English-only sites are unaffected.

Search and sitemaps

One query index per language keeps search results and sitemaps from mixing languages. In the env's query.yaml:

  • /query-index.json for English: the existing rules, plus excluding /fr/** and /es/**.
  • /fr/query-index.json and /es/query-index.json, each including only its own folder and repeating the fragment excludes (/fr/nav, /fr/footer and so on).

The env's sitemap.yaml then lists each language. EDS pairs pages that share a path to write the hreflang alternates:

version: 1
sitemaps:
  site:
    origin: https://www.example.com
    default: en
    languages:
      en:
        source: /query-index.json
        destination: /sitemap-en.xml
        hreflang: en
      fr:
        source: /fr/query-index.json
        destination: /sitemap-fr.xml
        hreflang: fr
        alternate: /fr/{path}
      es:
        source: /es/query-index.json
        destination: /sitemap-es.xml
        hreflang: es
        alternate: /es/{path}

default adds the x-default alternate. Point robots.txt at the generated sitemap index, or give every language the same destination to keep a single /sitemap.xml.

Rules for the structure

  • Name folders with ISO 639-1 codes: es for Spanish, not sp. AEM does not recognise other names as languages, and hreflang uses the same codes.
  • Never give an English page a language code as its name. It would publish to the same URL as that language's folder.
  • Do not publish the language root pages. The home page is each folder's index child. A published /content/<site>/fr appears at /fr, separate from the real home page at /fr/.
  • Keep page names identical across languages, so hreflang pairing and the language switcher work without per-page metadata.

Converting an English-only site

An existing site first moves its pages into /en. Public URLs do not change, but the order matters:

  1. Deploy the mapping. It matches nothing until /en exists, so it can go live first. Check it at https://main--<site>--aa-pdcoe.aem.page/config.json.
  2. Ship the code changes from the table above.
  3. Record the status of every live URL, to compare against afterwards.
  4. Create /en and move the pages in with Adjust references on. Leave untranslated pages at the site root.
  5. Republish what was live. Move one low-risk page first: if a move unpublishes the old path, that is the same public URL as the new one. Move the fragments (nav, footer, isi, cookie-consent-banner, fragments/404) last, because every page depends on them.
  6. Compare. Every URL that returned 200 should still return 200. In the Universal Editor, check that a moved page still loads its header, footer and ISI.

Republishing also publishes any edits waiting on a moved page, so check with page owners first. Verify on aem.live before the custom domain, which can serve a cached copy for a few hours.

References

On this page
h3
true