docs(35): decision note superseding D-05 and the locale switcher contract
This commit is contained in:
33
.planning/notes/2026-11-13-mail-template-locale-groups.md
Normal file
33
.planning/notes/2026-11-13-mail-template-locale-groups.md
Normal file
@@ -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 `<base>-<locale>` 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 `<base>-<tag>` where `<base>` is a registered template and `<tag>` 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 <name>" 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 `<template>-<locale>` for every locale they serve. sm-user-plugin's `classes.MailTemplate` maps only `en` today; postcard already resolves a locale without a file to the default-locale version, so passing the suffix for every locale is safe. This belongs to the plugin follow-up after the framework tag.
|
||||
@@ -282,8 +282,9 @@ Both codes go in the existing permission tab `permissions.tab_system` ("System")
|
||||
| Column / search: code | `mail.code` | Code | Kod |
|
||||
| Column: subject | `mail.template.subject` | Subject | Temat |
|
||||
| Column: description | `mail.template.description` | Description | Opis |
|
||||
| Column / filter: locale | `mail.template.locale` | Locale | Język |
|
||||
| Locale value for a file without a suffix | `mail.template.locale_default` | Default | Domyślny |
|
||||
| Column / filter: locale (superseded by C16: no locale column or filter) | `mail.template.locale` | Locale | Język |
|
||||
| Locale value for a file without a suffix (superseded by C16: now the Default label of the switcher and of Customized locales) | `mail.template.locale_default` | Default | Domyślny |
|
||||
| Column: customized locales (C16) | `mail.template.customized_locales` | Customized locales | Dostosowane języki |
|
||||
| Column: layout | `mail.template.layout` | Layout | Układ |
|
||||
| Column (invisible): customized at | `mail.customized_at` | Customized | Dostosowano |
|
||||
| Column: name (layouts, partials) | `mail.name_field` | Name | Nazwa |
|
||||
@@ -659,7 +660,7 @@ Partials list: `title: mail.partial.list_title`, `toolbar.buttons: []`, no check
|
||||
- messages `update: mail.template.name`, `saved: messages.form.saved`;
|
||||
- Save and close returns to the list.
|
||||
|
||||
Record title (h1, breadcrumb, `:name`): the template code, for example `golem15.user::mail.activate-en` (truncated). Subtitle: `mail.template.name`.
|
||||
Record title (h1, breadcrumb, `:name`): the template code, for example `golem15.user::mail.activate-en` (truncated). Subtitle: `mail.template.name`. (superseded by C16: the title is the template's base code, `golem15.user::mail.activate`, for every locale version.)
|
||||
|
||||
| Field | Type | Span | Tab | Notes |
|
||||
|-------|------|------|-----|-------|
|
||||
@@ -681,10 +682,10 @@ Templates list (`config_list.yaml`):
|
||||
|
||||
| Column | Type | Visible | Searchable / sortable | Notes |
|
||||
|--------|------|---------|----------------------|-------|
|
||||
| `code` | text | yes | searchable, sortable | First column; carries the badges. The default sort is `code` ascending, so a base template and its locale variants sit together (D-05: separate rows, no grouping) |
|
||||
| `code` | text | yes | searchable, sortable | First column; carries the badges. The default sort is `code` ascending, so a base template and its locale variants sit together (D-05: separate rows, no grouping; superseded by C16: one row per template) |
|
||||
| `subject` | text | yes | searchable | The effective subject (the override's, if any) |
|
||||
| `description` | text | yes | searchable | From the file |
|
||||
| `locale` | text | yes | sortable | The suffix (`en`), or `mail.template.locale_default` for a file without a suffix |
|
||||
| `locale` | text | yes | sortable | The suffix (`en`), or `mail.template.locale_default` for a file without a suffix (superseded by C16: replaced by `customized_locales`) |
|
||||
| `layout` | text | yes | — | The effective layout's name |
|
||||
| `customized_at` | datetime | invisible | sortable | |
|
||||
|
||||
@@ -692,7 +693,7 @@ Filters (existing `scope` type with options, like the 19.6.1 `trashed` filter):
|
||||
|
||||
| Scope | Label | Options |
|
||||
|-------|-------|---------|
|
||||
| `locale` | `mail.template.locale` | `default` (`mail.template.locale_default`) plus one option per suffix found in the catalog, labelled with the suffix |
|
||||
| `locale` | `mail.template.locale` | `default` (`mail.template.locale_default`) plus one option per suffix found in the catalog, labelled with the suffix (superseded by C16: the locale filter is removed) |
|
||||
| `status` | `mail.filter_status` | `customized`, `not_customized`, `outdated` (labels `mail.filter_customized`, `mail.filter_not_customized`, `mail.filter_outdated`) |
|
||||
|
||||
### C7. Info and File version partials (server-rendered, `.summer-partial`)
|
||||
@@ -882,6 +883,33 @@ Five `pact.SettingsItem` entries in category `backend::lang.settings.category_ma
|
||||
|
||||
Note: the delete refusal must be a `ForbiddenError` with `Message` set. The SPA delete toast reads `error.message`, and a `ValidationError` would show "Validation failed" (the same finding as 19.6.1 C8).
|
||||
|
||||
### C16. Template locale switcher (gap closure G-35-1, supersedes the D-05 parts of C3b)
|
||||
|
||||
Decision note: `.planning/notes/2026-11-13-mail-template-locale-groups.md`. A mail template is one record; its locale versions (rows grouped by `base_code`) are opened through a switcher in the template form.
|
||||
|
||||
**Markup** (`admin/src/components/form/LocaleVariantSwitcher.vue`): a labelled native select, classes copied from MLField's locale select (`rounded-control border border-border-strong bg-surface px-2 py-1 text-[13px]`), attribute `data-locale-variant` on the select, a `<label for>` with `form.locale_variant` (`text-[13px] text-muted`). One option per variant; the option text is the label, or "Label — state, state" when the version has states (the server's translated `mail.state_customized`, `mail.state_outdated`). The current version is selected.
|
||||
|
||||
**Data:** `meta.localeVariants` on the show and update responses (`cabana.RecordMeta.LocaleVariants`): `{id, locale, label, states, current}` per version, labels and states already translated. Other controllers send no key.
|
||||
|
||||
**Placement:** the form header, under the title (and subtitle), only when there are two or more versions and the record has loaded.
|
||||
|
||||
**Navigation:** choosing a version router-pushes the same route with that version's id (FormView remounts with a fresh load). The navigation goes through FormView's existing `onBeforeRouteUpdate` unsaved-changes confirm (`form.unsaved_confirm`); when it is refused the select returns to the open version.
|
||||
|
||||
**Variant order:** Default (the template's own file, label `mail.template.locale_default`), then by locale code: every locale with its own file, every other application locale except the default (no file: a fallback row), and any customized version of a locale that is no longer enabled. A template whose base ships no file has no Default.
|
||||
|
||||
**Locale without a file:** until it is customized its form shows what that locale sends now, the default version (the base's customization when there is one). Saving creates its own customized version; Reset to file version returns it to the default version; File changed shows when the base file changes.
|
||||
|
||||
**List changes:** one row per template (the base's row, or the lowest variant when only variants ship); the `locale` column is replaced by `customized_locales` (Default, then the locale codes of the customized versions, at most three then "+N"; empty when none); the Customized / File changed badges and the status filter apply to the whole template (any version); the locale filter is removed.
|
||||
|
||||
**Info lines** (`_info.htm`, only for a template with two or more versions): on Default `mail.info_locale_default`; on a locale without a file `mail.info_locale_fallback` with `:locale`, and the file line names the base file.
|
||||
|
||||
| Element | Key | EN | PL |
|
||||
|---------|-----|----|----|
|
||||
| Switcher label | `form.locale_variant` | Language | Język |
|
||||
| List column | `mail.template.customized_locales` | Customized locales | Dostosowane języki |
|
||||
| Info line, Default version | `mail.info_locale_default` | Default version: sent for every locale that has neither its own file nor a customized version. | Wersja domyślna: wysyłana dla każdego języka, który nie ma własnego pliku ani dostosowanej wersji. |
|
||||
| Info line, locale without a file | `mail.info_locale_fallback` | Locale :locale has no file of its own. Until you customize it, the default version is sent. | Język :locale nie ma własnego pliku. Dopóki go nie dostosujesz, wysyłana jest wersja domyślna. |
|
||||
|
||||
---
|
||||
|
||||
## UI Considerations
|
||||
@@ -895,9 +923,10 @@ Applicable state considerations resolved: 48 rows (42 covered, 6 backstop, 0 unr
|
||||
| empty | Partials list | ✅ covered | `mail.partial.list_empty`; the built-in button/panel/table partials mean the unfiltered list is never empty |
|
||||
| loading | All lists, forms, Branding, Mail images | ✅ covered | Existing skeletons and disabled footers in ListView/FormView/SettingsFormView; no new loading UI |
|
||||
| error | All lists, forms, Branding, Mail images | ✅ covered | Existing `list.load_failed` / `form.load_failed` alerts |
|
||||
| populated | Templates list | ✅ covered | Code, subject, description, locale, layout; base and locale variants adjacent by code sort; badges after the code |
|
||||
| populated | Templates list | ✅ covered | Code, subject, description, locale, layout; base and locale variants adjacent by code sort; badges after the code (superseded by C16: one row per template, Customized locales instead of locale, grouped badges) |
|
||||
| partial | Templates list (mixed states) | ✅ covered | Not-customized rows have no badge; customized rows show "Customized"; drifted rows show "Customized" + "File changed", in fixed order, as text (WCAG 1.4.1) |
|
||||
| zero-one-many | Locale filter | ✅ covered | The options are `Default` plus one per suffix in the catalog. An app with no locale variants shows only `Default` |
|
||||
| zero-one-many | Locale filter | ✅ covered | The options are `Default` plus one per suffix in the catalog. An app with no locale variants shows only `Default` (superseded by C16: the locale filter is removed) |
|
||||
| zero-one-many | Template locale switcher (C16) | ✅ covered | Shown from two versions; a template with one version (no locale variants, one mail locale) shows no switcher. A 50-locale site lists 50 entries in one native select, not 50 list rows |
|
||||
| overflow | All lists | ✅ covered | Existing pagination (20 per page) and horizontal table scroll; long codes truncate in the first column, with the badges kept (`shrink-0`) |
|
||||
| long-text | Template code in the form header and breadcrumb | ✅ covered | The h1 truncates (existing `truncate`); the full code also appears in `_info` as `code`, which wraps (`overflow-wrap:anywhere` inherited from `.summer-partial`) |
|
||||
| populated | Template form, not customized | ✅ covered | Filled from the file; `_info` says "Not customized…"; no Reset in the footer; Save creates the override |
|
||||
|
||||
Reference in New Issue
Block a user