diff --git a/CHANGELOG.md b/CHANGELOG.md index ff1b1a3..5587495 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,90 @@ Notable changes to Mallok. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +The admin speaks Simplified Chinese as well as English, and its pages were +reviewed and reworked for the operator who uses them every day +(`docs/ADMIN_I18N_AND_UI.md`). One schema migration runs on the first request +after deploying. Every API change is an addition: an `error` that was English +stays English, so the CLI and scripts read what they always did. + +### Added + +- **Interface languages: English and 简体中文** (`docs/ADMIN.md §4.3`). The + admin, the sign-in page and the setup wizard are translated, dates and + numbers follow the language, and it is chosen in the account menu, on the + sign-in page or on the wizard's first screen. It is kept in the browser and + with the account — migration `0010_admin_ui_locale`, `uiLocale` on + `GET`/`PATCH /_mallok/api/auth/me` and the sign-in response — and never in + a cookie, so the edge cache does not vary by it. It is not a content + language and neither defaults from the other. +- **The Worker's errors are named.** Beside the unchanged English `error`, an + error carries a `code` (`auth.invalid_credentials`) and `params`, and a + refused record or action carries `errorCodes` beside `errors`; 129 codes, + from sign-in and setup to content saves, media, settings, plugins and + purges. A save stored as a draft because its body is too long to render + says so with `warningCode` beside `warning`. The admin words each in its + language; a code it does not know is shown in the Worker's English. +- **Admin catalogs for themes and plugins**: an optional + `admin/.json` beside `theme.json` (`docs/THEME_FORMAT.md §10.1`), + and `adminCatalogs` in `definePlugin` (`docs/PLUGIN_API.md §7.8`), word + kinds, fields, options, panels, actions and badge values in the operator's + language. The five official themes and the `inquiry` plugin ship `zh-CN`. + Without one, the declared English is shown. The preview stays in the + content's language. +- **Plugin panels in the sidebar.** Each panel not attached to a content kind + is a page of its own (`/_mallok/app/plugins//`), listed + under Site by its label — Inquiries is one click away. "View site" in the + sidebar opens the public site in a new tab. +- **The editor on a phone**: one pane at a time ("Fields", "Write", + "Preview") with the save buttons pinned to the bottom. On a wide screen it + takes the whole window and the field pane folds to a rail. +- The setup wizard has numbered steps with Back, a password you can show, + and languages picked by name. + +### Changed + +- **"Saved" means saved.** A successful save is always the green "Saved", + followed by when visitors see it. Without a purge token it was an orange + badge that read as a problem; a draft no longer claims visitors will see + it. +- **Content languages are named** ("Chinese (zh)", "中文(zh)") wherever a + code stood alone — the content list's filter, the editor's language bar, + the Languages card, the wizard. A language is added from a list of names, + with "Another language…" for a code not listed. Other languages' taglines + are one field behind the content-language select, not a box per language. +- **The content list** shows the theme's label for each type and the date in + the interface language; "New content" (or "New Product", filtered to a + kind) says what it makes; empty and filtered-out lists say so and offer + the way on; a row on a phone is the title with type and status under it. +- **The editor's bar** shows the stored status, when it was last updated, + and "View on site" for a published item. +- **A plugin's card** puts its panels and settings first and its hooks, + client JavaScript and cache effect under "Technical details", closed. Row + actions wait for a selection, except a download. A filter on a named value + is a select. Empty panels, the media library and the Plugins page share + one empty state; a panel's pager is hidden when there is one page. +- **Settings.** Appearance puts the theme's options before its facts. + Advanced puts the backup first, and Diagnostics keeps orange for what + stops something working — a failed purge, an email key with no sender — + instead of for every optional thing not configured. The domain help says + what each domain is for without "noindex", "R2" or "Worker". The + no-token note is one line, linking to Diagnostics, which names + `CF_API_TOKEN` and `CF_ZONE_ID`. +- The `inquiry` plugin's setting labels lost their parentheses to help text, + and its autoreply body is a multi-line field. +- Every page shares one left edge and width with its header and the notice + above it. + +### Fixed + +- **Plurals**: "1 pages · 1 sample records" in the wizard, "used by 1 + items", "1 image(s) missing" and their like now agree with their number. +- A list of numbers in Chinese is separated (`Intl.ListFormat` with + `type: 'unit'` joined them with nothing), and a status badge no longer + breaks "已发布" one character per line in a narrow cell. + ## [0.1.0-rc.12] — 2026-11-05 Purges that take effect and say when they do not, the default language under diff --git a/biome.json b/biome.json index 9f58470..2e5487c 100644 --- a/biome.json +++ b/biome.json @@ -203,6 +203,7 @@ "includes": [ "vite.config.ts", "vitest.config.ts", + "lingui.config.ts", "playwright.config.ts", "scripts/e2e-global-setup.mjs", "src/worker/index.ts" diff --git a/docs/ADMIN.md b/docs/ADMIN.md index d38c677..6204d7a 100644 --- a/docs/ADMIN.md +++ b/docs/ADMIN.md @@ -44,7 +44,8 @@ From `TECH_STACK §6`, not re-argued here: | Markdown editing | CodeMirror 6 (`@codemirror/view`, `state`, `commands`, `lang-markdown`), themed from the design tokens | | Forms | The in-repository schema-driven generator (§7), on React Hook Form; Zod for the few forms with a fixed shape | | Preview | Reuses `src/core/`, rendering in the browser | -| Styling | Tailwind CSS 4 with shadcn/ui's design tokens and components on Radix; light, dark or the system's, chosen per browser. `styles.css` holds the tokens and nothing else | +| Styling | Tailwind CSS 4 with shadcn/ui's design tokens and components on Radix; light, dark or the system's, chosen per browser. `styles.css` holds the tokens and one type-size rule for Chinese, Japanese and Korean (§4.3) | +| Interface languages | Lingui: English in the source, a catalog per language loaded on demand (§4.3) | | Image processing | The browser's Canvas API | **0.1 does not include Tiptap.** Visual editing belongs to 0.2 @@ -57,10 +58,11 @@ Three top-level sections plus a user menu. **A new feature must fit one of them**; when it does not, the first question is whether it is internal complexity that should not be surfaced at all. -On screen they are a collapsible sidebar — Content, Media and Plugins under -"Site"; Site, Appearance, Email and Advanced under "Settings" — with the user -menu at its foot, and a breadcrumb above each page. On a narrow screen the -sidebar is a sheet. +On screen they are a collapsible sidebar — Content, Media, each plugin panel +by its label (Inquiries, say) and Plugins under "Site"; Site, Appearance, +Email and Advanced under "Settings" — with "View site" at its head, which +opens the public site in a new tab, the user menu at its foot, and a +breadcrumb above each page. On a narrow screen the sidebar is a sheet. ``` Content ├ All content (filter by kind, filter by language, search) @@ -77,22 +79,25 @@ Settings ├ Site details (name, tagline — one per language —, SEO defaul Plugins ├ Installed plugins (switch, version, what each affects) ├ Each plugin's settings and secrets form - └ Each panel a plugin declares, such as Inquiries + └ Each panel a plugin declares, such as Inquiries — a page of + its own, listed in the sidebar (§10) User menu ├ Account: change password, API token management + ├ Interface language (§4.3) ├ Colour scheme (the system's, light or dark) └ Sign out ``` ### 4.1 What Appearance does not contain -No theme list, no upload, no switch button. The page shows: +No theme list, no upload, no switch button. The page shows, in this order: -- the current theme's name, version and which content kinds it supports; +- the options form the theme exposes (`theme.json`'s `options`), which takes + effect immediately — first, because it is what the operator came to change; +- the current theme's name, version and which content kinds it supports, + named by the theme's own labels; - the `clientScripts` it declares — **stated honestly as "this theme injects N scripts"**, which is always zero for the official themes; -- the options form it exposes (`theme.json`'s `options`), which takes effect - immediately; - one sentence: **changing themes requires editing source and redeploying**, with a link to the documentation. @@ -119,6 +124,51 @@ A plugin may still carry a sender of its own — the `inquiry` plugin has an optional "From address" — and says on its own form that an empty field means the site sender is used. +### 4.3 The interface language + +The admin speaks English or Simplified Chinese (`ADMIN_I18N_AND_UI.md`). The +**interface language** is the operator's, not the site's: it never defaults +from a content language, nor they from it, and it is always labelled +"Interface language" so the two are not confused. Content languages are named +in the interface language with their code beside them — "Chinese (zh)", +"中文(zh)". + +- **Where it is chosen**: the account menu, the sign-in page and the setup + wizard's first screen, each language named in itself (English, 简体中文). +- **Where it is kept**: in this browser, and with the account + (`admin_user.ui_locale`); after sign-in the account's choice wins. With + neither, the browser's languages decide, and English is the fallback. It + is never a cookie, so the edge cache never varies by it. +- **What follows it**: every sentence the admin writes; dates, numbers and + lists (`Intl`, `src/admin/format.ts`); what themes and plugins declare — + kinds, fields, options, panels — through their optional + `admin/.json` (`THEME_FORMAT.md §10.1`, `PLUGIN_API.md §7.8`); + and the Worker's errors, which carry a `code` the admin words itself + while `error` stays English for the CLI. What has no translation is + shown in English, never as a key or a blank. +- **What does not**: content, the preview (it is the page a reader gets), + and errors a plugin's own code raises. +- **Chinese, Japanese and Korean** set the sidebar's group labels and the + badges at 13 px instead of 12 (`styles.css`), because Han characters at + 12 px lose strokes. + +**Adding an interface language.** The English sentence in the code is the +message, so a new language is a translation, not a change to any page: + +1. Add its tag to `locales` in `lingui.config.ts`, and to + `InterfaceLanguage`, `INTERFACE_LANGUAGES` (named in itself) and + `CATALOGS` in `src/admin/i18n.ts`. +2. Run `pnpm i18n:extract`, which writes `src/admin/locales/.po`, and + translate every entry. The Worker's sentences are in the same file, under + `server.`. +3. Optionally, give the official themes and plugins an + `admin/.json`; without one they show their declared English. +4. `pnpm lint` fails while any entry is untranslated. The browser tests run + in English; add the language to `05-accessibility`'s scan. + +Nothing on the Worker changes: it stores whatever tag the account chooses and +chooses a theme's or plugin's catalog by `Accept-Language`. + ## 5. The setup wizard At `/_mallok/setup`, and **permanently closed** once complete — a non-null @@ -129,10 +179,17 @@ At `/_mallok/setup`, and **permanently closed** once complete — a non-null | Step | What | Skippable | | --- | --- | --- | | 1 | Administrator email and password | No | -| 2 | Site name, default language, enabled languages | No | +| 2 | Site name, main language, other languages — each picked by name, a code typed only for one not listed | No | | 3 | Choose a starter: the site's own, if it brought any (`ARCHITECTURE §11.1`), listed first, then the official one. Each says how many pages and how many sample plugin records it brings | Yes; skipping gives an empty site | | 4 | Domain: detect whether a custom domain is bound, then done | Yes | +The steps are numbered and steps 2–4 have Back; the result screen is not a +step. Going back to step 1 says the account exists rather than offering to +create it again, and once a starter is installed step 3 has no Back, because +re-applying step 2 would drop the languages the starter added. The main +language starts as the interface language the wizard is read in, which is +chosen on its first screen and becomes the new account's. + **Media domain (`media.`) and email (the Resend key, the sending domain, the DNS records) are not wizard steps in 0.1** — deliberately: both need an account-scoped Cloudflare API token, a different credential from the @@ -156,18 +213,30 @@ unreachable, they are simply not part of the guided first run. Three things ### 6.1 Layout -Three collapsible columns: +The editor takes the whole window, beside the sidebar. A bar across the top, +then three panes: ``` -┌─────────────┬────────────────────────┬──────────────┐ -│ Field form │ Markdown source │ Live preview │ -│ (schema) │ (CodeMirror) │ (core) │ -├─────────────┴────────────────────────┴──────────────┤ -│ Status: draft/published/scheduled language group │ -│ translation Save View │ -└─────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ Stored status · Updated · View on site │ +│ English (en) · Create Chinese (zh) Save draft Publish │ +├─────────────┬────────────────────────┬───────────────────────┤ +│ Field form │ Markdown source │ Live preview │ +│ (schema) │ (CodeMirror) │ (core) │ +└─────────────┴────────────────────────┴───────────────────────┘ ``` +- The bar shows the status as stored, not as asked, and a new item says + "Not saved yet". "View on site" appears for a published item. +- The field pane folds to a rail ("Hide fields" / "Show fields"), and this + browser remembers the choice. +- Below `lg`, one pane is shown at a time, chosen with "Fields", "Write" + and "Preview", and the save buttons move to a bar pinned to the bottom of + the screen. +- A successful save is the green "Saved", followed in plain text by when + visitors see it ("now", or "within 1 minute" without a purge token); a + draft gets the badge alone. + ### 6.2 Markdown is the truth **`content.markdown` is the only truth** (`CONTENT_FORMAT §3`). The field form @@ -233,7 +302,10 @@ CPU-limit kill is not something the save request's own code can catch and turn into a clean error. So past `MAX_SAFE_RENDER_BYTES` (50 KB, `src/worker/admin-content.ts`), the save **skips rendering rather than risk it**: the body is stored as a draft regardless of the status requested, and -the response carries a warning explaining why, shown in the editor. Nothing +the response carries a warning explaining why, shown in the editor — in +English as `warning`, and named by `warningCode` (`content.saved_unrendered`, +with `warningParams.limitKb`) so the editor says it in the interface +language, as it does an error (`ADMIN_I18N_AND_UI.md`, D3). Nothing is lost — shortening the body and saving again renders and publishes normally. **It does not fail silently, and it does not pretend to have succeeded** (`AC-CONTENT-10`, `docs/ACCEPTANCE.md §14.2` item 7). @@ -247,9 +319,9 @@ succeeded** (`AC-CONTENT-10`, `docs/ACCEPTANCE.md §14.2` item 7). addresses redirecting (`ARCHITECTURE §9`); the editor's path preview follows it. -- The language switcher sits at the top of the editor, and switching to a - translation that does not exist yet offers "create the `` - version". That opens a new item in that language, in the original's +- The language switcher sits at the top of the editor, each language named + ("Chinese (zh)"), and a translation that does not exist yet is offered as + "Create Chinese (zh)". That opens a new item in that language, in the original's translation group and of its kind (`/content/new?locale=…&group=…&kind=…`, kept across a reload). If the group has that language by the time it is saved, the save is refused with 409 naming the item that holds it. @@ -337,13 +409,27 @@ See §4.1. Two additions: installing one means changing the repository and redeploying, with the concrete steps (`PLUGIN_API.md §2`). **It must not be dressed up as a one-click install.** -- Each plugin shows its version, which hooks it uses, whether it injects - client-side JavaScript, and whether it affects the cache. +- A plugin's card puts first what the operator uses: its warnings, then its + panels, its settings and its secrets. Its version, which hooks it uses, + whether it injects client-side JavaScript and whether it affects the cache + are under "Technical details", closed until opened. - A plugin declaring `onRequest` carries the extra note that it runs on every visitor request (`PLUGIN_API.md §5.1`). +- **A panel is a page of its own** (`/_mallok/app/plugins//`), + listed in the sidebar by its label, so the inquiries an operator opens + every day are one click away. Its heading is the label; the line under it + names the plugin and links to the plugin's card, where a button opens the + panel in turn. A panel is listed whether or not its plugin is on: switched + off, it says that nothing new arrives, and what was stored stays readable. - Panels render from `plugin.json`'s `panels` (`PLUGIN_API.md §7.5`): a table with the declared columns, filters and actions; a search box and - sortable headings where the panel declares them. + sortable headings where the panel declares them. A filter on a field whose + values the plugin's catalog names is a select. Row actions are disabled + until a row is selected, except a download, which with no selection + exports everything. An empty panel says "Nothing here yet." — offering + "Add the first one" on a `records` panel — or, when a filter or the search + is set, "Nothing matches these filters." with "Clear filters". The pager + is hidden when everything fits on one page. - **A `records` panel adds New and Edit.** The form is generated from the panel's `fields`. Two controls exist only there: `money` — an amount typed as `99.00` beside a currency, sent as whole minor units — and `rows`, a @@ -366,8 +452,15 @@ See §4.1. Two additions: ## 11. Advanced, under Settings -This is the only place lower-level vocabulary is allowed: +This is the only place lower-level vocabulary is allowed. **Backup** comes +first, then the rest: +- **Backup**: one-click export (`CONTENT_FORMAT §5`), with a prompt to export + before upgrading the Worker (`ARCHITECTURE §15`). The zip is built only if + every listed object downloads and matches its digest; a transient failure is + retried three times first, so one flaky response does not decide the + operator cannot have their data. Same contract as `mallok export` + (`CLI.md §7`). - **Usage**: D1 rows read and written today against the limits, R2 storage, Worker request count. **Exceeding D1's free tier makes it unavailable for the day** (`ARCHITECTURE §2`), so approaching the limit must be prominently @@ -378,15 +471,13 @@ This is the only place lower-level vocabulary is allowed: next request, at the cost of that one render. **Without a purge token, say honestly that nothing was purged and the cache will expire on its own. Never claim success.** -- **Backup**: one-click export (`CONTENT_FORMAT §5`), with a prompt to export - before upgrading the Worker (`ARCHITECTURE §15`). The zip is built only if - every listed object downloads and matches its digest; a transient failure is - retried three times first, so one flaky response does not decide the - operator cannot have their data. Same contract as `mallok export` - (`CLI.md §7`). - **Diagnostics**: whether a custom domain is bound, whether caching is in - effect, whether `CF_API_TOKEN` is configured, whether Resend is configured, - and the schema version. **Last failed purge** appears when a purge + effect, whether `CF_API_TOKEN` and `CF_ZONE_ID` are configured — the + sentence the admin's no-token note links to with "Why?" — whether Resend is + configured, and the schema version. Orange is kept for what stops something + working: a failed purge, or an email key with no sender. No custom domain, + no purge token, no email key and media served by the Worker are stated + neutrally, each with what it means. **Last failed purge** appears when a purge Cloudflare did not carry out is recorded (`ARCHITECTURE §6.2`): when, after what (a content change, a plugin by name, …), Cloudflare's status and answer, and what to check — for a 401 or 403, that the token needs Zone → @@ -423,7 +514,7 @@ The complete rules are in `SECURITY.md`. On the interface side: | Item | Requirement | | --- | --- | | Accessibility | Fully keyboard operable; every form control has a label; focus is visible; `@axe-core/playwright` reports nothing serious or critical | -| First load | Admin first-load JS ≤ 170 KiB gzip (React, React Router, TanStack Query, the shell; raised from 150 on 2026-11-03, `ADMIN_MIGRATION.md` D7). **Asserted by `pnpm admin:size`**, counting every script and stylesheet `index.html` references, the `modulepreload` chunks included (they were left out until 2026-10-31, `ADMIN_MIGRATION.md §8`); 161.7 KiB on React Router and TanStack Query on 2026-11-03; 124.1 KiB with the shadcn/ui shell on 2026-10-31; measured at 72.0 KB on 2026-09-06, up from 17.3 KB on Preact — real React+ReactDOM cost is ≈ 54 KB gzip in this project's own Vite build, not the ≈ 45 KB estimated from memory before switching | +| First load | Admin first-load JS ≤ 170 KiB gzip (React, React Router, TanStack Query, the shell; raised from 150 on 2026-11-03, `ADMIN_MIGRATION.md` D7). **Asserted by `pnpm admin:size`**, counting every script and stylesheet `index.html` references, the `modulepreload` chunks included (they were left out until 2026-10-31, `ADMIN_MIGRATION.md §8`); 166.2 KiB with the interface languages and the interface review on 2026-11-17 (`ADMIN_I18N_AND_UI.md §8`), no catalog included — each loads on demand; 161.7 KiB on React Router and TanStack Query on 2026-11-03; 124.1 KiB with the shadcn/ui shell on 2026-10-31; measured at 72.0 KB on 2026-09-06, up from 17.3 KB on Preact — real React+ReactDOM cost is ≈ 54 KB gzip in this project's own Vite build, not the ≈ 45 KB estimated from memory before switching | | CodeMirror | Chunked and loaded only when the editor opens. **The render pipeline — unified, remark, rehype, LiquidJS — is equally on demand**: the preview uses the real renderer, so it loads with the editor rather than on first load | | Importing from core | **A page on the first-load path must not import from the `src/core/index.ts` barrel**, not even for a single constant — the barrel drags the whole render pipeline into the first load. This happened once, on 2026-08-31: the Appearance page imported the barrel for one string constant and the first load went from 17 KB to 137 KB, caught by `pnpm admin:size`. Dependency-free constants live in `src/core/constants.ts` | | Offline | No offline support. A network failure produces a clear error and never silently discards a change | diff --git a/docs/ADMIN_I18N_AND_UI.md b/docs/ADMIN_I18N_AND_UI.md new file mode 100644 index 0000000..a7dd3cd --- /dev/null +++ b/docs/ADMIN_I18N_AND_UI.md @@ -0,0 +1,952 @@ +# Admin interface languages and interface review + +- Status: **implemented, phases 0–5**, on 2026-11-17, on + `feature/admin-i18n`. The owner took every recommendation in §3 as + written ("按照建议来"): D1 A (Lingui), D2 B built as A first, D3 C, D4 C, + D5 as an addition under plugin API 2, D6 unchanged, D7 the four rules, D8 + C. §8 records each phase as built and what is still the owner's: Windows + and Linux screenshots, the real-site check, two wording questions. +- Date: 2026-11-12 +- Asked for by the owner on 2026-11-12, in two parts: the admin and the setup + wizard have no multilingual support, and the admin's interface needs + adjusting. The second part named no page; §2.3 is what looking at every + screen found. + +## 1. Goal + +1. An operator chooses the language the admin and the setup wizard speak. + English and Simplified Chinese ship; a further language is a catalog and + one line in a list, with no change to a page. +2. The interface problems listed in §2.3 are fixed, page by page, without + changing what the admin does. + +Out of scope: any change to the public site or its language packs, the +content model's languages (`site.locales`, `locale`, `translation_group`), +starter content (it is content, not interface), automatic translation of +content, the CLI's messages, right-to-left layout, and any new admin feature. +Three places where `ADMIN.md` describes something the admin does not have +are listed in §9 as conflicts for the owner; this plan does not build them. + +## 2. Where it is today + +Measured in the repository on 2026-11-12, at `a4b10e0`. + +### 2.1 Language + +| Fact | Value | +| --- | --- | +| Translation mechanism | None. Every string is English, written in the JSX | +| Source to cover | 8,765 lines of TypeScript and TSX in `src/admin` outside `components/ui/` (11,184 with it) | +| Document language | `src/admin/index.html` has `lang="en"`, fixed | +| Sentences with markup inside them | 23 uses of `` and 8 of `` or a link inside running text (the wizard's setup-key help, the purge notice, the domain step) | +| Plurals | Seven, each hand-built with `=== 1 ? '' : 's'` or left wrong on purpose ("1 pages", which `01-wizard` asserts) | +| Number and date formatting | Four call sites, three behaviours: `Intl.NumberFormat('en', …)` in `components/record-editor.tsx`; `toLocaleString()` with the browser's locale in `pages/account.tsx` (twice) and `pages/settings-advanced.tsx`; the content list prints `updatedAt.slice(0, 10)` | +| Native dialogs | Two `window.confirm` calls with long English sentences (`pages/settings-site.tsx`) | +| First load | **161.7 KiB gzip of 170** (`node scripts/admin-size.mjs` on the existing build output): 8.3 KiB of headroom | +| Strings from themes | `theme.json`: `kinds.*.label`, each field's `label`, `help` and `group`, each option's `label`; `select` `choices` are bare strings that are both the stored value and the text shown. English only | +| Strings from plugins | `plugin.json`: `name`, `description`, each setting's and secret's `label`, each panel's `label`, column labels, action labels, a script's `purpose`; badge cells print the row's raw value. English only | +| Strings from the Worker | 146 `problem(status, message)` calls in `src/worker` and `src/plugins`; the body is `{ "error": "" }`, sometimes with `errors: { field: "" }`. **There are no error codes.** Many messages are assembled with values in them | +| Email | The inquiry notification to the operator is English only; the autoreply to a visitor has English and Chinese chosen by the *content* language of the page (`src/plugins/inquiry/emails.ts`) | +| Browser tests | 41 tests in 20 spec files; 176 selectors by role, 62 by label, 20 by text — all English | +| Where a preference could live | Nowhere yet. `admin_user` has `id`, `email`, `password_hash`, `password_params`, `created_at` (`DATA_MODEL.md §2.8`); the colour scheme and the sidebar's state are in `localStorage` | + +Two things already in the repository look reusable and are not, as they are: + +- **A theme's `locales/.json`** is the public site's text + (`THEME_FORMAT.md §10`): a flat map read by templates, keyed by the + *content* language (`zh`), with no interpolation. A few keys coincide with + field names (`moq`, `lead_time`, `grade` in Atelier's pack) but they are + what a visitor reads, not what an operator reads, and no option label + ("Hero headline") is there. See D4. +- **The content editor's language bar** switches which translation is being + edited. It is the control most likely to be mistaken for an interface + language switch. See D7. + +### 2.2 What the libraries cost, measured + +**Method.** A throwaway Vite 8.3.8 project (React 19.2.8, +`@vitejs/plugin-react` 6.3.0), outside the repository. One small screen was +written once per approach: a heading, a sentence with a value in it, a +plural, two buttons, and a switch that loads the other language's catalog +with a dynamic `import()`. The number is gzip of what `index.html` +references, as `pnpm admin:size` counts it; catalogs are separate chunks in +every variant and are not in it. **These are a scaffold's numbers**: good +for what a library adds, not for this admin's total, which phase 0 measures. + +| Approach | Versions | Adds to first load | +| --- | --- | ---: | +| React only | — | 58.0 KiB (base) | +| In-repository: a context, `{name}` substitution, plural forms picked with `Intl.PluralRules` | — | **+0.9** | +| The same with a splitter for `…` inside a message | — | **+1.0** | +| Lingui, runtime only, catalogs compiled by hand | `@lingui/core`, `@lingui/react` 6.12.0 | **+3.3** | +| Lingui as it is meant to be used: `Trans`, `Plural` and `t` macros, `lingui extract`, `.po` catalogs compiled by its Vite plugin | + `@lingui/vite-plugin`, `@lingui/cli` 6.12.0 | **+4.2** | +| An in-repository context around `intl-messageformat` | 12.1.5 | +10.3 | +| FormatJS | `react-intl` 12.1.7 | +14.6 | +| i18next, its own plural format | `i18next` 27.1.1, `react-i18next` 18.0.1 | +17.6 | +| i18next with ICU messages | + `i18next-icu` 2.7.0 | +29.8 | + +Also established by running it, not from memory: + +- **Lingui's macro build works on this stack without Babel or SWC.** + `lingui({ macroTransform: true })` beside `@vitejs/plugin-react` built + under Vite 8; its installation page (read 2026-11-12) says this path + "doesn't need `@lingui/babel-plugin-lingui-macro` or `@lingui/swc-plugin`". + That matters here: phase 5 of the last migration deleted the admin's Babel + transform because it could fail silently (`ADMIN_MIGRATION.md §8`). +- **Extraction works.** `lingui extract` found all six messages of the + screen, wrote `en.po` and `zh-CN.po`, and reported "zh-CN: 6 total, 6 + missing". A sentence with markup became one message with numbered + placeholders (`Printed once by <0>mallok create. …`), so a translator + can reorder it. +- **The built page ran in Chromium in both languages**, with the right + plural form, `` following the choice, and the second catalog + fetched only on the switch. The compiled Chinese catalog for the six + messages was 0.3 KiB. +- **Playwright's default context reports `navigator.language` as `en-US`** + on this (Chinese-language) machine, so a test that does not ask for a + locale gets English from browser detection. + +Read from current documentation on 2026-11-12, not measured: + +| | ICU plurals and select | Keys checked by the compiler | Extraction from source | +| --- | --- | --- | --- | +| In-repository | No. Plural forms only, by category | Yes, if catalogs are TypeScript objects of one type | None; keys are written by hand | +| Lingui | Yes ("ICU MessageFormat under the hood") | There are no keys to mistype with macros: the English sentence in the source is the message. Its docs also list a "Typed Message IDs" guide, not read here | `lingui extract`; `compile` produces the runtime catalogs and "ships no message parser" | +| FormatJS | Yes | Not established here | `formatjs extract` | +| i18next | Its own `_one` / `_other` suffixes on `Intl.PluralRules`; ICU through `i18next-icu` | Yes, by augmenting `CustomTypeOptions`; its docs warn of slower type checks and lost inference for template-literal keys | Separate tools; not examined | + +Lingui's installation page asks for Node 22.19 or higher; `.nvmrc` is +22.22.2. + +### 2.3 The interface, from screenshots + +A separate local instance (its own port and state directory, the +`trade-b2b` starter, the Atelier theme, three content languages) was driven +with Playwright through the wizard and every admin page at 1440 px and +390 px, light and dark: 86 screenshots, kept outside the repository. The +content list, the Site page, the plugins page and the editor were then +re-captured with their text replaced in the page by Chinese and by German +of realistic length. What follows is from those images; where a claim is +from code it says so. + +**What holds up.** Light and dark are consistent on every page. No page +scrolls sideways at 390 px. With Chinese or German text nothing overflowed +or was clipped in the sidebar (256 px wide; "Erweiterte Einstellungen" +fits), the buttons, the badges or the table headings. Chinese renders in the +system's CJK face through the existing stack at the existing sizes and line +heights (14 px on 20 px in controls and tables) and reads well — **on macOS, +the only system measured.** + +| # | Where | What is wrong | What it should become | +| --- | --- | --- | --- | +| U1 | Every page | The standing "Changes reach visitors within 1 minute" notice is three lines at 1440 px and **seven at 390 px, above every page, the editor included**. It names `CF_API_TOKEN`, `CF_ZONE_ID` and "Worker secrets" — the vocabulary `ADMIN.md §2` keeps to Advanced | One line: the sentence in its title and a "Why?" link to Advanced → Diagnostics, where the secret names already are. Still standing, still `role="note"` | +| U2 | Every page | Three widths on one screen: the notice spans the window; the content list and editor are 68 rem; settings pages are 56 rem **left-aligned inside the centred 68 rem column**, so at 1440 px they sit 84 px from the sidebar and 205 px from the right edge | One column rule: the notice, the page header and the page share a left edge and a width; forms cap their own fields, not the page | +| U3 | Sidebar | **Inquiries, the thing a trade site's operator opens every day, is the last block of the Plugins page**, about 1,500 px down, under nine settings and a secret. The last migration's D4 recommended "each plugin's panels listed under Plugins"; the sidebar that shipped has one Plugins link. There is also no way to open the public site from the admin | See D8 | +| U4 | Content list | The Type column prints the kind's id (`article`) while the Type filter, one row above, prints the theme's label ("Note"); statuses are raw lowercase values; languages are bare codes (`en`); the date is a sliced ISO string | Labels from the theme, status names from the catalog, language names from `Intl.DisplayNames` with the code beside them, dates through one formatter (§5.4) | +| U5 | Content list | A "Media" button duplicates the sidebar item beside it. "New" does not say what it makes. Previous and Next are drawn, disabled, when there is one page. "Nothing here yet." is shown both for an empty site and for a filter that matches nothing, with no action in either | Drop "Media". Hide the pager when there is nothing to page. Two empty states: an empty site offers "Create the first page"; an empty filter says so and offers "Clear filters" | +| U6 | Content list, 390 px | The table scrolls sideways and Path and Updated are off screen, so a phone shows title, type and status only — by accident, not by design | Below `md`, a row is the title with type and status under it; Path and Updated are dropped on purpose | +| U7 | Editor, 1440 px | The editor is held to 68 rem, so each pane is about 330 px while 350 px of the window is empty. Markdown wraps at about 35 characters and the preview shows the theme's phone layout. `ADMIN.md §10` says the editor "fills the window"; `§6.1` says the columns collapse, and the code has no collapse control | The editor route is full-bleed. The field pane collapses to a rail; the source and preview split what is left | +| U8 | Editor | Nothing says whether the open item is published, a draft or scheduled, or when it was last saved, and there is no link to it on the site. `ADMIN.md §6.1` draws a status bar with exactly those | A status badge and "Updated …" beside the title controls, and "View on site" for a published item | +| U9 | Editor, 390 px | Fields, then the whole source, then the preview, in one column about 2,000 px tall; Save draft and Publish scroll away with the top | Three tabs — Fields, Write, Preview — and the two buttons in a bar that stays on screen | +| U10 | Four places | The language of *content* is chosen with four different controls: a select in the list's filters, chips ("en", "Create zh") in the editor, an "Editing" select on Appearance, and a suffix on a label ("Tagline (zh)") on Site. All show bare codes | One component, always labelled "Content language", always showing the language's name and code. This is also what keeps it apart from the interface language (D7) | +| U11 | Plugins | The card opens with Hooks, Client JavaScript and a script URL; the settings follow; the panel is last. Help is written into labels ("From address for inquiry email (empty uses the sender in Settings → Email)") although fields have a `help` key. A Liquid body is typed into a one-line input. The Status filter is a free-text box with the placeholder "any". "Mark replied" and "Mark spam" are enabled with no row selected (from code: only the pager is ever disabled) | Order: panel link, settings, secrets, then "Technical details" (hooks, scripts, cache effect) closed by default — still there, as `ADMIN.md §10` requires. The inquiry manifest moves its parentheses into `help` and its body to `text`. A filter on a column with known values is a select. Bulk actions are disabled until a row is selected | +| U12 | Settings → Site | "Only this host is indexable. Without one, every page is served noindex and the edge cache does not apply." and "An R2 custom domain … through the Worker." are infrastructure wording on the first settings page. One textarea per extra language is stacked full-width (two here; six languages would be six). The first card has a Save button; the Languages card below acts at once — two models on one page with nothing telling them apart. A new language is typed as a code | Plain wording, with the detail under Advanced. Taglines for other languages behind the one content-language control (U10). Cards that act at once say "Applies immediately" where a Save button would be. Adding a language offers names, with a typed code still accepted | +| U13 | Settings → Appearance | 370 px of facts and a deploy notice stand between the heading and the first option an operator can change | Options first; the theme's facts and the deploy note after them | +| U14 | Settings → Advanced | The one action an operator needs here, "Export everything", is the fourth card. Storage rows are raw keys (`jobsPending`, `fragments`). On a fresh site five of five diagnostics are orange | Backup first. Labels for the storage rows. Orange only for what stops something working; "not set up yet" is neutral | +| U15 | Saving, everywhere | Success is an inline badge beside the button, failure is a toast, sign-in failure is an inline box. With no purge token, a *successful* save is the orange warning badge "Saved — visitors see it within 1 minute", which reads as a problem | Success is always the green badge "Saved"; the delay is plain text after it. Failures stay where they are | +| U16 | Wizard, step 2 | The first question a non-technical owner meets is "Main language" as a free-text code and "Other languages" as "zh, de", comma separated | A select of language names for the main language and a multi-select for the others, drawn from the active theme's packs first, with a typed code still accepted | +| U17 | Wizard | Five numbered dots for what `ADMIN.md §5` calls four steps: "Finish" is a result, not a step. There is no Back. The password is typed once, unseen, with no way to show it. Step 4 is two paragraphs of Cloudflare dashboard directions plus the secret names | Four steps and a result screen. Back on steps 2–4. A show-password toggle. Step 4 keeps its first, honest paragraph; the directions become a link to the documentation | +| U18 | Sign-in | "The site's admin" names no site, and there is nowhere to choose a language before signing in | The site's name where the session-less API can give it, otherwise as now; the interface-language control of D2 | +| U19 | Empty states | "Nothing here yet.", "No media yet." and "No rows yet." are three wordings in two dashed boxes that look like the upload drop zone next to them | One empty-state block: what is empty, and the one action that fills it | +| U20 | Type size in Chinese | Sidebar group labels and badges are 12 px. Latin survives that; Chinese at 12 px is at the edge of comfortable | Under a CJK interface language these two go to 13 px. No other size changes | + +## 3. Decisions the owner has to make + +### D1 — The translation mechanism + +| | A. Lingui | B. In the repository | C. FormatJS or i18next | +| --- | --- | --- | --- | +| First load (§2.2) | +4.2 KiB | +1.0 KiB | +14.6 to +29.8 KiB | +| Fits 170 KiB | Yes, with about 4 KiB left | Yes, with about 7 KiB left | **No.** The budget would have to be raised again, nine days after it was raised to 170 | +| What a page looks like | The English sentence stays in the JSX, wrapped: `Save draft` | Every sentence moves to a catalog and the JSX holds a key: `t('editor.saveDraft')` | Keys, as B | +| Plurals, sentences with markup | ICU; markup as numbered placeholders | Plural categories only; a hand-written splitter for markup | Yes | +| Missing translation | Reported by the extractor | A type error | Varies | +| Cost | Four packages; a build-time transform in `vite.config.ts` again; `.po` files | A formatter and a splitter written and owned here; ~8,700 lines re-keyed by hand | Size | + +**Recommended: A, Lingui, confirmed by phase 0 in this admin's own build.** +It fits, it was seen to work on this stack without Babel, and it leaves the +English in the source — so the browser tests' selectors and the code they +drive stay readable side by side. B is smaller, but it is writing the +library: `TECH_STACK.md §11` rule 6 says adding no dependency is not a +reason to hand-write what a mature ecosystem has solved, and that rule +names parsing. If phase 0 finds Lingui does not fit or its transform is +fragile here, B is the fallback and C is not. + +### D2 — Where the operator's choice lives + +| | A. This browser only | B. The account, mirrored in the browser | C. A site-wide default | +| --- | --- | --- | --- | +| Storage | `localStorage`, like the colour scheme | A nullable `admin_user.ui_locale` column (migration `0010`, additive), plus `localStorage` | A `site` column | +| Before sign-in (wizard, sign-in page) | Works | Works, from the mirror or the browser's language | Needs an unauthenticated read | +| A second browser or a phone | Asks again | Follows the operator | Follows the site, not the person | +| Gives the Worker a language for operator email | No | Yes | Yes | + +**Recommended: B, built as A first.** Phase 1 ships A: the choice in +`localStorage`, else the first of `navigator.languages` the admin has a +catalog for, else English. Phase 3 adds the column and one field on the +existing account endpoint; from then the account's value wins after sign-in +and is copied to the browser, so the next sign-in page is already in it. The +wizard's choice is carried into the account when it creates the +administrator. C is not recommended: 0.1 has one administrator, and a site +default would be a third place to look for no one's benefit. + +### D3 — The Worker's messages + +| | A. Codes, translated in the admin | B. `Accept-Language`, translated in the Worker | C. Codes where they exist, the Worker's English otherwise | +| --- | --- | --- | --- | +| API change | `code` and `params` added beside `error`; `errorCodes` beside `errors` | None in shape; the same request now answers in different languages | As A, additive | +| Catalogs | In the admin, on demand | In the Worker script, every language, on the render path's size budget | In the admin | +| The CLI and scripts | Unaffected: `error` stays English | Must send English or parse translated text | Unaffected | +| Work | All 146 sites before anything is translated | All 146 sites and a formatter in the Worker | Incremental | + +**Recommended: C.** `error` stays exactly as it is — the CLI prints it, and +it is the fallback. A site that gains a `code` also gains its `params`, and +the admin shows its own sentence when its catalog has that code and the +Worker's English when it does not. English is then the worst case, never a +blank or a key. Order of work: sign-in and setup, content save, media +upload, settings, then the rest. A plugin's own validation messages follow +D5. + +### D4 — Labels declared by themes + +Kinds, fields, groups, help text and options are English in `theme.json`. + +| | A. Leave them English | B. Reuse `locales/.json` | C. A separate, optional admin catalog per theme | +| --- | --- | --- | --- | +| Contract change | None | The public pack gains admin keys | `admin/.json` beside `theme.json`: a flat map keyed by declaration path (`kinds.product.label`, `kinds.product.fields.grade.label`, `options.hero_title.label`, `groups.Specification`) | +| Result | A Chinese interface with English field labels in the editor — the page an operator uses most | Visitor text and operator text in one file, keyed by content language (`zh`), not interface language (`zh-CN`) | Themes without the file work as today | + +**Recommended: C.** The file is optional, additive, validated at build time +like the public packs, and bundled the same way. The Worker overlays it on +the manifest it already serves from `GET /_mallok/api/theme`, choosing by +the `Accept-Language` the admin sends (§5.3) — the admin's code does not +change and no theme string enters the admin bundle. A missing key falls back +to the declared English. `THEME_FORMAT.md §10` gains a section; the five +official themes get `zh-CN`. **Not solved here:** a `select`'s `choices` are +stored values; showing a translated choice needs a value/label form of +`choices`, which is a change to the field schema and is left as an open +question (§9). + +### D5 — Labels declared by plugins + +The same shape as D4, for `plugin.json`: `admin/.json` in the +plugin's directory, keyed `name`, `description`, `settings..label`, +`settings..help`, `secrets..label`, `panels..label`, +`panels..columns.`, `actions.`, `values..` for +badge cells (`new`, `replied`, `spam`), and `errors.` for a plugin +that returns codes under D3. + +**Recommended: take it, as an addition under plugin API 2** +(`PLUGIN_API.md §13.1`: version 2 only adds). A plugin without the file is +shown in English, so the official `inquiry` plugin keeps running unedited as +the compatibility proof and gets its `zh-CN` file as a separate commit. A +site-level plugin such as Nundar's gets translated panels by adding one +file. + +### D6 — Email and what the wizard writes + +- **Starter content** stays as it is: it is content, in the content's + languages. +- **The visitor's autoreply** already follows the content language of the + page. Not touched. +- **The operator's inquiry notification** is the one message addressed to + the admin's reader. **Recommended: leave it English in this plan**, and + decide after D2's column exists whether it should follow the + administrator's `ui_locale`. It is sent from a visitor's request, where no + session says who will read it, and the recipient is an address in the + plugin's settings, not an account. + +### D7 — Keeping the interface language apart from content languages + +**Recommended, as rules:** + +1. The interface language is chosen in exactly three places: the account + menu (a radio group under "Colour scheme"), the sign-in page and the + wizard (a small menu in the corner). Never in a page's toolbar. +2. It is always called "Interface language" and lists each language in its + own name: "English", "简体中文". +3. A content language is always called "Content language" (or "Site + languages" in Settings), always through the one component of U10, and + always shows name and code: "German (de)". +4. In data they do not meet: interface languages are BCP 47 tags the admin + has catalogs for (`en`, `zh-CN`); content languages are whatever codes + the site declares. Neither defaults from the other, in either direction — + a Chinese-speaking operator of an English-only site is the common case. + +### D8 — How much of §2.3 to do, and the sidebar + +| | A. Translation only | B. Translation and the review's fixes | C. B, and plugin panels in the sidebar | +| --- | --- | --- | --- | +| Covers | Phases 0–3 | Phases 0–4: U1, U2, U4–U20 | B plus U3 | +| Changes behaviour | No | Layout and wording, no flow | A new route per declared panel | + +**Recommended: C.** U3 is the finding that matters most to a trade site: a +declared panel appears under Site in the sidebar by its label +("Inquiries"), at `/plugins//`, and the Plugins page keeps +the switch, settings and secrets with a link to the panel. A panel attached +to a content kind stays in that kind's editor and is not listed. A link to +the public site joins the sidebar's header. The order of the fixes inside +phase 4 is the owner's taste as much as anyone's; the proposed order is +there. + +## 4. Constraints that do not move + +| Constraint | Source | What it means here | +| --- | --- | --- | +| First load ≤ 170 KiB gzip | `ADMIN.md §13`, `pnpm admin:size` | 8.3 KiB of headroom. English is the fallback and is compiled into the entry only if phase 0 shows that costs less than a second request; every other catalog is a chunk fetched on demand. Each phase reports the number | +| Everything in the repository is English | `CONVENTIONS.md`, Style | Source strings, comments and tests stay English. A catalog in another language is a translation "where it serves a real user", the same footing as a theme's `zh.json` | +| No serious or critical axe violation, light and dark | `test/e2e/05-accessibility.spec.ts` | Run in both interface languages. `` follows the choice; an untranslated English fragment inside a Chinese page is acceptable to axe but is a catalog defect | +| The browser tests find controls by English role, label and text | `test/e2e` | English is what a context with no stored choice and an English browser gets. `playwright.config.ts` pins `locale: 'en-US'` rather than rely on the default seen in §2.2 | +| The Worker validates; the browser shows what comes back | `tasks/TASK-28.md` | D3 changes how an error is worded on screen, never who decides it | +| Errors carry no SQL, bucket names, ids or stack traces | `SECURITY.md` | `params` under D3 are the values already in today's message, nothing more | +| Migrations are additive and forward-compatible | `DATA_MODEL.md` | `ui_locale` is a nullable column; an older Worker ignores it | +| Themes and plugins ship no admin code | `ADMIN.md §7` | D4 and D5 add data files, not code | +| Version 1 plugins run unchanged | `PLUGIN_API.md §13.1` | D5 is optional and additive | +| Infrastructure words only under Advanced | `ADMIN.md §2` | Applies to the translations as much as to the English; U1 and U12 remove existing breaches | +| New dependencies are registered | `TECH_STACK.md §11` | Exact versions, licence, layer and measured size, in a dependency-only commit; released at least two weeks earlier, as the last migration held itself to | +| No release is implied | — | When to publish is the owner's call | + +## 5. Design + +### 5.1 Catalogs and loading + +`src/admin/locales/.po`, one per interface language, with `en` the +source. A list of supported tags and their own names lives in one module; +adding a language is a new `.po` and one entry. The provider sits above both +the router and the wizard in `main.tsx`, resolves the language before the +first render (D2's order), sets `document.documentElement.lang`, and loads +that language's chunk. Switching loads the other chunk and re-renders in +place: no reload, and nothing typed into a form is lost. + +Messages follow three rules. A sentence is one message, markup included, +never fragments joined in code. A count goes through a plural, including in +English ("1 page"). Nothing an operator reads is assembled from a server +value and a client word. + +### 5.2 What is not translated + +Values that are data: content titles, slugs, paths, language codes, plugin +and theme ids, token scopes, secret names. Words that are names: Mallok, +Markdown, Resend, Turnstile, Cloudflare. + +### 5.3 What the admin tells the Worker + +`src/admin/api.ts` is the one place requests are made; it sends the +interface language as `Accept-Language`. The Worker uses it for one thing +only: choosing the admin catalog of a theme or plugin to overlay on the +declarations it returns (D4, D5). Error text does not vary by it (D3). No +response under `/_mallok/` is cached, so the header creates no cache +variance. + +### 5.4 Formatting + +One module wraps `Intl.DateTimeFormat`, `Intl.NumberFormat`, +`Intl.RelativeTimeFormat` and `Intl.DisplayNames`, always called with the +interface language. The four call sites of §2.1 move to it, and +`saved-note.tsx`'s hand-built "1 minute" becomes a plural. Money in a +record keeps its declared currency and takes the interface language's +grouping. + +### 5.5 Typography + +The system stack stays; no font file is added. `lang="zh-CN"` on the +document is what lets a browser pick a Simplified Chinese face for Han +characters, so it is set before the first paint. U20 is the one size +change. **Windows and Linux were not measured**; phase 2's gate includes a +screenshot on each. + +## 6. Phases + +Sizes are relative — S under a day, M a few days, L a week or more — and +are estimates. + +### Phase 0 — Spike and numbers (S) + +Throwaway branch; only §8 of this file merges. + +1. Add the D1 choice to this admin's real build, wrap the shell and the + sign-in page, and record `pnpm admin:size`, with English in the entry + and with English as a chunk. +2. Confirm the build fails loudly, not silently, when the transform is + missing or a catalog does not compile. +3. Find how a missing translation fails the gate (the extractor reported + counts in §2.2; whether a flag turns that into an exit code was not + checked). +4. Count the messages: extract the whole admin once and record the total. + +**Gate:** the measured first load in §8, and D1 confirmed or switched to B. + +### Phase 1 — Foundation (S) + +The provider, the language list, the formatter module, the interface +language control in the account menu, the sign-in page and the wizard +(D7), ``, the choice in `localStorage` (D2, option A). +`playwright.config.ts` pins `en-US`. The shell and the sign-in page are +translated; every other page still reads English. + +**Gate:** all browser tests pass unchanged; a new spec switches to 简体中文 +from the account menu, sees the sidebar and `` change, reloads +and finds the choice kept, and finds no cookie set. + +### Phase 2 — Every string in the admin (L) + +One page per commit, in the last migration's order (settings, account, +content list, media, plugins and panels, record editor, content editor, +wizard), then the form generator's own messages ("This field is +required."). Each commit wraps the page's strings and adds its `zh-CN`. +The two `window.confirm` sentences move into the catalog. English wording +is not edited here, with one exception: "1 pages" becomes "1 page", and +`01-wizard`'s assertion changes with it and says why. + +**Gate:** the extractor reports nothing missing for `zh-CN`; a +pseudo-language run (every message replaced by a marked string) shows no +unmarked sentence on any page or overlay; axe is clean in both languages; +screenshots of every page in Chinese at both widths, on macOS, Windows and +Linux, reviewed by the owner — who is also the reviewer of the Chinese +wording. + +### Phase 3 — Strings from outside the bundle (M) + +- D2's column and the account endpoint's field; the wizard passes its + choice when it creates the administrator. +- D3: `code` and `params` on the Worker's errors, in the order given there; + the admin's catalog gains each code as it lands. +- D4 and D5: the admin catalog files, their build-time validation, the + overlay in the two endpoints, `zh-CN` for the five official themes and + the `inquiry` plugin. `THEME_FORMAT.md`, `PLUGIN_API.md` and + `DATA_MODEL.md` are revised in the same commits as the code. + +**Gate:** worker tests for the overlay (present, absent, a missing key) and +for an error's `code`; the Chinese spec opens the editor of a product and a +plugin panel and finds declared labels in Chinese; a deliberately failed +sign-in and a refused save are read in Chinese; the Worker's bundle size is +reported. + +### Phase 4 — The review's fixes (M–L), per D8 + +One finding or one page per commit, proposed order: U1 and U2 (every page +improves at once), U15, U10, U4–U6, U7–U9, U16–U18, U11–U14, U19, U20, +then U3 if D8 is C. A fix that changes English wording changes the catalog +and its translation in the same commit. + +**Gate:** per commit, the page's browser tests pass — a selector that has to +change says why in its diff — axe is clean in both languages, and a +before-and-after screenshot goes to the owner. + +### Phase 5 — Close (S) + +`ADMIN.md` gains a section on the interface language and is corrected where +phase 4 changed a page; `TECH_STACK.md §6` and `§11.1`; `THIRD_PARTY_NOTICES` +regenerated; the CHANGELOG; a short "adding an interface language" note. + +## 7. Verification + +- **The gate, every phase:** `pnpm lint && pnpm typecheck && pnpm test && + pnpm build && pnpm bundle:size && pnpm admin:size`, and `pnpm test:e2e`. +- **Behaviour:** the existing browser tests, in English, unchanged except + where §6 names a change. +- **The other language:** one ordered spec in 简体中文 covering the switch, + its persistence, a declared label, a translated error, and the wizard — + which, because the wizard runs once per database, is driven in Chinese in + a context of its own inside `01-wizard`'s run, or against a mocked setup + API as the last migration did for its screenshots. Phase 1 decides which. +- **Accessibility:** `05-accessibility` runs its page list once per + interface language. +- **Completeness:** the extractor's missing count and the pseudo-language + run of phase 2. +- **Size:** `pnpm admin:size` in every commit message of phases 1–4. +- **Looks:** screenshots for the owner; no visual-regression tooling is + added. + +## 8. Measurements + +Measured 2026-11-13 in this admin's real build (Vite 8.2.2, Rolldown), with +Lingui 6.11.0 — 6.12.0, which §2.2 measured, was ten days old, and §4 holds +new dependencies to two weeks. The shell, the account menu and the sign-in +page were wrapped: 25 messages. + +| Build | First load (gzip) | Change | +| --- | ---: | ---: | +| Before, `main` at `a4b10e0` | 161.7 KiB | — | +| Lingui, catalogs as chunks, `await` at the top of `main.tsx` | 173.1 KiB | **+11.4, over budget** | +| Lingui, catalogs as chunks, start-up as a promise | **165.4 KiB** | **+3.7** | +| The same with English compiled into the entry | 165.7 KiB | +4.0 | + +- **A top-level `await` in the entry costs 7.7 KiB.** Rolldown split the + entry into 22 small preloaded chunks instead of 6, and each pays its own + gzip framing. `main.tsx` starts the language with a promise and renders + in its `then`; the comment there says why. +- **English stays a chunk.** Compiled into the entry it cost 0.3 KiB for 25 + messages and grows with every one; as a chunk it is one small request + that starts before React renders. +- **The scaffold's +4.2 KiB was close**: the real figure is 3.7 KiB, leaving + 4.6 KiB of the 170. +- **A missing transform fails the build, loudly — but only because of a + guard.** Without the transform the `.po` imports fail to parse, which is + loud. With the transform switched off and the catalogs still compiling + (`macroTransform: false`), the build passed: `@lingui/react/macro`'s + browser build is empty functions, so `` renders nothing. A + `resolveId` guard in `vite.config.ts` now fails the build naming each + module that still imports a macro; tried with the option switched off. +- **A broken catalog fails the build** with a parse error naming the file. +- **A missing translation fails `pnpm lint`.** `lingui check missing` passes + by default even with a missing translation, because English fills it in; + `--mode catalog` is the one that fails (exit 1, "Found 1 missing + translation(s) before applying fallbackLocales"). `lingui check sync` + fails (exit 1) when a sentence in the source has changed and the catalogs + were not re-extracted. Both run in `pnpm lint` as `pnpm i18n:check`. +- **Extraction is reproducible**: catalogs carry origins without line + numbers, and a second `lingui extract` a minute later wrote identical + bytes. The admin build stayed reproducible across checkout paths + (`test/cli/admin-build-reproducibility.test.ts`, which now copies + `lingui.config.ts` too). +- **Not counted: the whole admin's messages.** The extractor counts only + wrapped messages, so step 4's total is known only once phase 2 has wrapped + them; it will be recorded there. +- **The rest of the gate:** `pnpm lint`, `typecheck`, `test` (1460 tests), + `build`, `bundle:size` (Worker 310.3 KiB gzip) and `admin:size` passed; + `pnpm test:e2e` passed, 47 specs, including the new + `20-interface-language.spec.ts`. One `pnpm test` run in three had one + failing test that two reruns did not repeat; it was not identified. + +Phase 1 as built: + +- `src/admin/i18n.ts`: the two languages and their own names, the choice in + `localStorage` (`mallok-admin-language`), else the browser's languages + matched exactly and then by primary subtag (`zh`, `zh-Hans-CN` → `zh-CN`), + else English; `` follows. `zh-TW` also matches `zh-CN` by that + rule — better than English for a reader of Traditional Chinese, and a + Traditional catalog would take it over. +- The account menu gains "Interface language" under "Colour scheme"; each + radio group is now named by its label, which `16-appearance` relied on + not needing — its selector changed and says why. +- `playwright.config.ts` pins `locale: 'en-US'`. +- Finished at the start of phase 2: a language control (a native + ``: these screens are on the first load, and a menu + * component would cost more than the choice is worth. + */ + +import { useLingui } from '@lingui/react/macro'; +import { Languages } from 'lucide-react'; +import type { JSX } from 'react'; +import { + NativeSelect, + NativeSelectOption, +} from '@/components/ui/native-select'; +import { + INTERFACE_LANGUAGES, + type InterfaceLanguage, + setInterfaceLanguage, + useInterfaceLanguage, +} from '../i18n.js'; + +export function LanguagePicker({ + className, +}: { + readonly className?: string; +}): JSX.Element { + const language = useInterfaceLanguage(); + const { t } = useLingui(); + return ( +
+
+ ); +} diff --git a/src/admin/components/markdown-editor.tsx b/src/admin/components/markdown-editor.tsx index b5547f7..67cab18 100644 --- a/src/admin/components/markdown-editor.tsx +++ b/src/admin/components/markdown-editor.tsx @@ -13,6 +13,7 @@ */ import type { DecorationSet } from '@codemirror/view'; +import { useLingui } from '@lingui/react/macro'; import type { JSX } from 'react'; import { useEffect, useRef, useState } from 'react'; @@ -74,14 +75,16 @@ function tokenTheme( } export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { + const { t } = useLingui(); + const label = t`Markdown source`; const host = useRef(null); const handle = useRef(null); const currentMissing = useRef([]); const [rich, setRich] = useState(false); // The newest props, so the mount effect never closes over stale values. - const latest = useRef(props); - latest.current = props; + const latest = useRef({ ...props, label }); + latest.current = { ...props, label }; useEffect(() => { let cancelled = false; @@ -163,7 +166,9 @@ export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { // focusable, and reported a long document's scroll area as one // the keyboard could not reach. view.EditorView.contentAttributes.of({ - 'aria-label': 'Markdown source', + // The language of the moment it mounted; an editor stays + // open for one sitting, not across a change of language. + 'aria-label': latest.current.label, tabindex: '0', }), view.EditorView.updateListener.of((update) => { @@ -234,7 +239,7 @@ export function MarkdownEditor(props: MarkdownEditorProps): JSX.Element { {rich ? null : (