Knowledge · Guidelines · architecture

Dynamic Content Localization

Canonical pattern for localizing DYNAMIC row content (entity field values) — per-row translations JSONB, base-column fallback, FTS folding, and the boundary against the UI-chrome i18n key system

Metadata

architecture mandatory

Procedures

Showing 3 of 6

  1. 1 Confirm this is CONTENT, not CHROME
    Apply LOC-005. If the string is developer-authored UI chrome, stop — use the
i18n key system. Only user-authored row values proceed here.
  2. 2 Add the storage (YAML-first, LOC-001)
    Add a `translations` attribute (JSONB, omitempty) to the entity's codegen-source
entity.yml FIRST, then the struct field (named type), then regenerate the mapper.
The base column is unchanged and remains the default-locale value + fallback.
Migration: ALTER TABLE ADD COLUMN translations JSONB. Down: drop the column.
  3. 3 Fold into FTS (LOC-003)
    Extend the search_vector sync trigger(s) to union translations values into the
tsvector at the base field's structured weight. Identify ALL triggers that write
search_vector for this entity (there may be one per dependent table) and update
each. Existing GIN index covers it — no new index. Down-migration restores the
prior trigger bodies.