Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

The locale list leaves the prose, and pt is logged as an open question (#401)

nyblnetfdb7aaee2892
diff --git a/AGENTS.md b/AGENTS.md
index 8b20b6c9..b80974ca 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -50,8 +50,27 @@ are in `docs/DECISIONS.md` — don't reopen them.
thumbnails (`kernel/src/save.ts`, `slides/src/preview.ts`); `bento/enc` decks
are vetoed and any existing preview is stripped. Run
`node scripts/test-preview.ts` after touching that path.
-6. **New UI strings go into ALL i18n catalogs** (ja, zh-Hans, zh-Hant, es, fr,
- de, it). English-string-as-key; never call `t()` in module-level consts.
+6. **New UI strings go into ALL i18n catalogs.** English-string-as-key; never
+ call `t()` in module-level consts. **Never take the locale list from prose —
+ including this file.** It is `LOCALES` in that app's `scripts/build-*-i18n.mjs`,
+ and `ls <app>/src/i18n/` is the check. This rule said seven for a month after
+ Portuguese made it eight, and #394 shipped an app one language short because
+ it believed the sentence you are reading.
+ - **Adding a locale touches three places**, not one: the catalogue file, the
+ app's `LOCALES`, and any rig with its own copy of the list. Only
+ `build-i18n.mjs` (slides) errors on a catalogue missing from `LOCALES`;
+ the others exit 0 and silently never pack it.
+ - **A rig must derive the list, never restate it.**
+ `scripts/test-i18n-coverage.mjs` reads `PACKED_LOCALES` out of the
+ generated `packed.ts` — copy that, and a fourth copy can never go stale.
+ **It covers slides ONLY** (`coreDir` is hardcoded to `slides/src/i18n`),
+ so spaces and type have no coverage rig at all. Do not assume your app's
+ catalogues are checked by anything.
+ - **A locale code is not always a language.** `pt` is Brazilian in
+ `slides/` and drifted European in `spaces/`; no check can see this,
+ because both files are correctly named `pt.ts`. See docs/DECISIONS.md,
+ 2026-08-29, before writing or reusing a catalogue for a language with
+ regional variants.
7. **Never edit `site/`** — it's generated. Sources are `site-src/` and the
`scripts/build-*.mjs` tooling. Same for `dist-single/`.
8. **No AI co-author trailers on commits** (no `Co-Authored-By: Claude` or
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index d1e57a8b..6bcaaed3 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -6126,3 +6126,122 @@ the session, which is not.
check belongs in the file people read BEFORE writing a rig; this log is what
they read after wondering why a standard exists. That text is queued for the
maintainer.
+## 2026-08-29 — the locale list leaves the prose; docs point at LOCALES
+
+**The rule that named the languages was wrong for a month and cost a shipped
+app a language.** `AGENTS.md` rule 6 listed seven catalogues (ja, zh-Hans,
+zh-Hant, es, fr, de, it) and `CLAUDE.md` said "7 locales"; Portuguese was added
+2026-07-25 and the docs did not follow. PR #394 added `type/src/i18n/` with
+seven catalogues and no `pt.ts`, and hard-coded the seven-locale list into its
+new build script. That session followed the written rule exactly. The rule was
+the defect.
+
+**So no document states the list any more.** Rule 6 and the `CLAUDE.md` i18n
+entry now name where the list lives — `LOCALES` in the app's
+`scripts/build-*-i18n.mjs`, with `ls <app>/src/i18n/` as the check — and carry
+the failure story, because a rule without one gets deleted by whoever finds it
+inconvenient. A count in prose is verified by nothing and is the only copy that
+can rot unnoticed; every other copy is load-bearing and fails visibly.
+
+**Three copies, not one, and the number is growing.** Adding a locale touches
+the catalogue file, the app's `LOCALES`, and any rig holding its own list.
+Saying "point at the build script" is true and incomplete: it leaves a rig's
+copy stale, which is what goes red. Measured on 2026-08-29:
+
+| | slides | spaces | type (#394) |
+|---|---|---|---|
+| `LOCALES` in build script | 8 | 8 | 7 |
+| catalogue files | 8 | 8 | 7 |
+| extra-file guard | **yes** | no | no |
+| rig with its own list | no | no | **yes** |
+
+**Only `build-i18n.mjs` errors on a catalogue missing from `LOCALES`.** On
+spaces and type, adding a catalogue without touching `LOCALES` exits 0, prints
+its locale count, and silently never packs the file — a translation that ships
+to nobody, announced by nothing. That is worse than a red build. Porting the
+guard to the sibling scripts is queued with ops and is not done here.
+
+**A rig must derive the list, never restate it.**
+`scripts/test-i18n-coverage.mjs` already does the right thing: it parses
+`PACKED_LOCALES` out of the generated `packed.ts`, so it cannot disagree with
+the build. #394's `test-type-i18n.ts` hard-codes a second list instead. The
+existing rig is the pattern to copy; a derived list is a copy that cannot rot.
+
+**Not fixed, deliberately:** this log's 2026-07-24 entry says "App UI i18n
+(7 locales)". It was true when written — one day before the entry that added
+Portuguese — and this log is append-only. It stays. Anyone grepping for stale
+counts will hit it; that is the cost of an honest record, not a defect.
+
+**The general rule, because this is not really about locales.** A count in
+prose is verified by nothing. Three files stated one today — `AGENTS.md`,
+`CLAUDE.md`, `docs/PARALLEL-WORK.md` — all three were true when written, all
+three went stale in silence, and one of them cost a shipped app a language.
+**Name the mechanism, never its current output:** the mechanism survives edits,
+the output has a half-life. That extends to this log — an append-only entry
+cannot be corrected, so a number belongs in one only when it is FROZEN. The test
+before writing one down: *could this change without the entry becoming wrong?*
+
+**A number is frozen by its framing, not by its value.** "Eleven cases went
+untested" is safe: it reports something that already happened and stays true
+forever. The same figure asserted as a standing fact — "there are eight
+catalogues" — is not, because the next locale makes it a lie nobody can edit.
+The table above says 8 twice and is safe for exactly this reason: it is stamped
+`Measured on 2026-08-29` and says the number is growing, so it reads as a
+reading taken at a moment rather than a claim about the present. Date a
+measurement and it becomes evidence; leave it undated and it becomes a fact with
+an expiry nobody sees. **The rule is not "avoid numbers" — that is unusable
+advice — it is "never write one that is still claiming to be current."**
+
+This is the same failure recorded elsewhere today from the rig side — a
+statement that was true when written, went stale without a sound, and had
+nothing checking it. Documentation and a green test suite fail identically here,
+and for the same reason: both are instruments, and an instrument nobody
+calibrates is believed longest.
+
+## 2026-08-29 — OPEN QUESTION: `pt` is two different languages in the suite
+
+**Not a decision. A question recorded because no rig can ask it.**
+
+**The facts, counted on 2026-08-29.** Both files are named `pt.ts` and both are
+correctly named, so every mechanical check passes:
+
+| | `arquivo` | `ficheiro` | `tela` | `guardar` | header declares |
+|---|---|---|---|---|---|
+| `slides/src/i18n/pt.ts` | 47 | 10 | 33 | 4 | Portuguese (**Brazilian**), explicit pt-BR terminology policy |
+| `spaces/src/i18n/pt.ts` | 9 | 58 | 3 | 7 | "Portuguese", no policy |
+
+So slides is Brazilian by declaration and spaces drifted European, under one
+locale code. A user running the suite in Portuguese meets two vocabularies.
+`type` followed slides while adding its catalogue and normalised the strings it
+reused.
+
+**The intent was Brazilian, but it was never written as a rule.** The
+2026-07-25 bundling entry adds Portuguese "because Brazil has a real
+English-proficiency gap"; `slides/src/i18n/pt.ts` states a pt-BR policy in its
+header and notes that European Portuguese "deserves its own catalog later".
+Neither is a suite-wide policy, and `spaces/` shows what happens without one.
+
+**Why this cannot be a rig.** The drift is vocabulary under an identical locale
+code. There is no signal to assert on short of a term blocklist per variant,
+and even that is not sufficient: bento/type reports that one reused string
+passed a `ficheiro`/`guardar`/`ecrã` sweep while remaining European in
+construction ("cada vez que guarda", "num computador") and had to be rewritten
+by hand. **A term-level sweep is not a conversion.**
+
+**Not clean anywhere, which is why this is a question and not a cleanup.**
+Slides violates its own stated policy 10 times (`ficheiro`) plus `guardar` and
+`ecrã`. Settling the question means retranslating a catalogue, which is
+translation work and a maintainer's call, not a documentation change.
+
+**What is actually being asked**, so it is not rediscovered:
+
+1. Is bundled `pt` pt-BR for the whole suite? The recorded reasoning says
+ Brazil, and two of three catalogues follow it.
+2. If yes, `spaces/src/i18n/pt.ts` needs converting by hand and every catalogue
+ should declare its variant in its header the way slides does.
+3. Does European Portuguese become a downloadable pack (`pt-PT`), which is what
+ the slides header anticipates and what the pack tier exists for?
+
+Until it is answered, **a new catalogue for a language with regional variants
+should state its variant in its header** and follow the sibling app that
+already declares one.
diff --git a/docs/PARALLEL-WORK.md b/docs/PARALLEL-WORK.md
index 6003b63f..d1617b7c 100644
--- a/docs/PARALLEL-WORK.md
+++ b/docs/PARALLEL-WORK.md
@@ -94,11 +94,17 @@ or detached checkout, for exactly that reason.
## 3. Known conflict magnets (pre-empt them)
- **`CHANGELOG.md`** — every feature branch appends to `[Unreleased]`. Keep
- entries as one self-contained block; when apps multiply, each app gets its
- own changelog (`slides/CHANGELOG.md`, …).
+ entries as one self-contained block. Each app has its own changelog now
+ (`spaces/`, `dash/`, `type/`); the ROOT `CHANGELOG.md` is **bento/slides'**
+ and has not moved to `slides/CHANGELOG.md` yet. Never append another app's
+ changes to it — release notes ride inside the signed update manifest, so a
+ file describing a second app tells a user about changes their document did
+ not get.
- **i18n catalogs** — append-only additions at the TOP of each catalog map;
- never reorder or reformat existing entries. All 7 catalogs in the same PR
- as the source string.
+ never reorder or reformat existing entries. Every catalogue in the same PR
+ as the source string — **the count is not written here**; it is `LOCALES` in
+ the app's `scripts/build-*-i18n.mjs`. This line said 7 while the apps packed
+ 8. See hard rule 6 in `AGENTS.md`.
- **`render.ts` / shared modules** — additive features must COMPOSE (blur +
blend + backdrop all coexist; gradient + stroke coexist). When resolving a
conflict between two features, the answer is almost always "keep both".