From 1173a5c5a230f174afdb2be9d5f0bafa50188ad4 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 20:42:06 +0100 Subject: [PATCH] docs(35): decision note superseding D-05 and the locale switcher contract --- .../2026-11-13-mail-template-locale-groups.md | 33 ++++++++++++++ .../35-UI-SPEC.md | 45 +++++++++++++++---- 2 files changed, 70 insertions(+), 8 deletions(-) create mode 100644 .planning/notes/2026-11-13-mail-template-locale-groups.md diff --git a/.planning/notes/2026-11-13-mail-template-locale-groups.md b/.planning/notes/2026-11-13-mail-template-locale-groups.md new file mode 100644 index 00000000..9b2f4162 --- /dev/null +++ b/.planning/notes/2026-11-13-mail-template-locale-groups.md @@ -0,0 +1,33 @@ +# Decision: one admin record per mail template, locale versions behind a switcher + +**Date:** 2026-11-13 +**Status:** Accepted (shipped in Phase 35 plan 35-05) +**Context:** `.planning/phases/35-mail-templates-and-layouts-editor/35-UAT.md` gap G-35-1 (UAT test 1, major): "each locale is a separate entry in backend is absolute disaster ... imagine site with 50 locales". User decision of 2026-11-13 confirming the gap-closure plans. +**Relates to:** `35-CONTEXT.md` D-05, D-06, D-07, D-13, D-16; `35-UI-SPEC.md` C16; `modules/postcard/README.md` ("Locale variants", "Index rows, drift and reset"); `modules/cabana/README.md` (mail screens). + +## Context + +D-05 ("locale variants stay separate templates") made `postcard.SyncIndex` write one `system_mail_templates` row per file (`activate.htm`, `activate-en.htm`), and the cabana Mail templates list showed each row with a locale column and a locale filter. There was no grouping key and no per-locale editing inside one record, so N locales gave N list rows per template, and a locale that ships no file could not be customized at all. + +## Decision + +D-05 is superseded. A mail template is one admin record; its locale versions are edited behind a locale switcher in the template form. As shipped: + +- **Group key.** `system_mail_templates.base_code` (migration `202611130001_mail_template_base_code`, nullable, indexed). It is the code with its locale suffix stripped, by the same rule as `postcard.TemplateLocale` (suffix after a dash in the last dotted segment, one of the mail locales): `postcard.TemplateBase`. A code without such a suffix is its own base. `postcard.SyncIndex` writes it on every template row. +- **Mail locales** (cabana). The phrasebook translator's `Locales("")` plus, when a `cabana.TranslationWriter` is published and answers, its `EnabledLocales`. The default locale is the writer's `DefaultLocale`, else the translator's `Locale()`. The index syncs again when this set changes, so a 50-locale site (locales enabled through a translate plugin) gets 50 entries in the switcher without a restart. +- **Fallback-locale rows.** `postcard.EnsureLocaleRows` gives every base template a row `-` for every mail locale except the default that ships no file: source, description, subject, body, layout and `file_hash` from the base file, `base_code` the base. The default locale gets no row: the unsuffixed file is its version. Rows are created at sync for all templates and on show for the shown template; nothing is deleted. +- **Variant set and order** (`cabana.RecordMeta.LocaleVariants`, `cabana.RecordLocaleVariant`, on the show and update responses of the mail templates screen only). Default (the unsuffixed file, label `mail.template.locale_default`), then by locale code: every locale with its own file, every other mail locale except the default, and any customized row of a locale that is no longer enabled. A group whose base has no file (only `x-en.htm` shipped) has no Default and no fallback rows. Labels and state words are translated on the server. +- **What a fallback row shows.** Until it is customized, its form shows the default-locale version as it is sent now (the base row's effective subject, body and layout, its customization when there is one). Saving makes it customized with `base_hash` = the base file's hash. +- **Per-locale customize / reset / drift (D-06, D-07).** Each version is its own row with its own `is_custom`, `base_hash` and `file_hash`. A fallback row's `file_hash` follows the base file, so "File changed" shows on it when the base file changes. `postcard.ResetOverride` accepts a fallback-locale code and returns it to the base file. Saves, preview and test send go through `postcard.Editor` exactly as before (D-13, D-16). +- **Send resolution** (postcard, independent of any locale list, so `queue:work` needs no cabana). A name with its own file renders exactly as before. A name the catalog does not hold, of the form `-` where `` is a registered template and `` is a two-letter language optionally followed by `-` or `_` and a 2-8 character alphanumeric subtag (case-insensitive, the longest registered base wins), renders the base file with: the name's own customized row, else the base's customized row, else the base file. Any other unknown name keeps the "postcard: unknown template " error. `postcard.Catalog.TemplateFor` exposes the resolved file. Core plugins are unaffected: sm-user-plugin and sm-paymentgateway-plugin send names that have files, and `scripts/check-phase35.sh --consumers` passes unchanged. +- **List.** One row per template (the base row, or the lowest code when only variants ship), a Customized locales column (Default and locale codes of the customized versions, at most three then +N), Customized / File changed badges aggregated over the group, and the status filter applied to the whole template. The locale filter is removed. + +## Rejected alternatives + +- **Multilingual fields (`mltext` / `mlmarkdown`) in one record.** One row would hold every locale's subject and body, but there would be no per-locale layout, reset or drift, and the send path would need a translate store. +- **A form-level `?locale=` query parameter.** The switcher would edit one record under a locale parameter; FormView would change for every controller, and the per-locale state would still need rows. +- **Rows for a locale created only on its first save.** A locale not yet customized could not be opened, so the switcher could not list it. + +## Follow-up (outside this phase) + +- Plugins that want per-locale admin versions pass `