Expand description
Per-field, per-locale translation overrides.
Design rationale lives in docs/i18n-decision.md. The
TL;DR: the canonical cms_page row holds the default-locale
content; cms_translation overrides individual fields per locale.
This table is the sole supported localization path — the
cms_page.locale_variant_of escape hatch was retired.
Storage rationale: a wide JSON blob per page works for
document-shaped DBs but is awkward in PG/MySQL where
ordinary SELECT + indexes want columns. The narrow tall table is
easier to query, easier to migrate, and keeps the canonical
cms_page row free of locale concerns.
Structs§
- Translation
- One row per
(page_id, locale_id, field_path). An emptyvalueis treated as “no override” and the canonical content shows through.
Functions§
- fetch_
for - Fetch every translation for
(page_id, locale_id)as a map keyed onfield_path. Single SELECT, materialized once per rendered request. - fetch_
for_ pages - Fetch translations for every page in
page_idsunder onelocale_id, materialized as{ page_id -> { field_path -> value } }. - overlay_
translations - Overlay seeded per-page scalar translations onto a JSON context value
so templates render localized content with no
t-filter calls — the engine localizespage,extension,children, and any handler-supplied card/list objects uniformly (the same “it just works” contract StreamField bodies already get via the stream prerender). - register_
tera_ filter - Tera filter
t(field=..., translations=...)— substitute the localized value forfieldfrom the supplied translations map, falling back to the original input on miss / empty. - resolve_
locale - Resolve a locale, taking precedence:
- validate_
field_ path - Validate a translation
field_path: ≤255 chars, ASCII alphanumeric plus_,., and-. The.allows dotted block-UUID paths into StreamFields (<field>.<uuid>.<name>); the-is required because block UUIDs are lowercase hex with hyphens. Returns the trimmed path on success. Pure — unit-tested + reused by the page translate handler’s “add new key” guard.