i18n & localisation
Purpose: Translate component UI strings and structure multilingual content correctly.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| Frontend engineers | String translation in HTL |
| All engineers | Language tree conventions |
Two different problems
| Problem | Mechanism |
|---|---|
| Static UI strings ("Read more", "per month") | i18n dictionaries + HTL i18n |
| Content in multiple languages | Language copies / translation projects |
UI string translation
Dictionaries are repo nodes (sling:MessageEntry) under e.g. /apps/phi-academy/i18n/<lang>. In HTL:
<span>${'per month' @ i18n}</span>
<span>${'benefits.covered.count' @ i18n, format=[model.coveredCount]}</span>The active language comes from the page/request locale. Keep keys semantic (benefits.covered.count), not the English sentence, once strings grow beyond trivial.
Content language structure
/content/phi/en/plans/gold-hospital ← language root "en"
/content/phi/de/plans/gold-hospital ← language copy- Language roots follow ISO codes directly under the site root; much AEM tooling (translation integration, language copy) assumes this shape.
- Language copies are created/updated via translation projects (machine or vendor connectors) — content flows through a translation workflow, not manual copy-paste.
- Combine with MSM when you have region × language matrices (blueprint per language, live copies per region) — design this with the architecture owner.
Developer notes
- Never concatenate translated fragments in HTL/models; use parameterised messages (
format=[…]). - Dates, numbers and currency formatting belong in the model using the page locale, not hardcoded in templates.