docs(35): decision note superseding D-05 and the locale switcher contract

This commit is contained in:
Jakub Zych
2026-11-13 20:42:06 +01:00
parent e114492bbe
commit 1173a5c5a2
2 changed files with 70 additions and 8 deletions

View 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.