Skip to main content

Module translation

Module translation 

Source
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 empty value is 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 on field_path. Single SELECT, materialized once per rendered request.
fetch_for_pages
Fetch translations for every page in page_ids under one locale_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 localizes page, 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 for field from 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.