Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Docs: language packs — bundled core of 9, everything else signed packs

nyblnet1e461648d090
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index ea17917c..1c7b816d 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -14,6 +14,38 @@ Decision. Why. Pointers.
---
+## 2026-07-25 — i18n: a bundled core of 9 languages, everything else a signed pack
+
+The 7 non-English catalogs cost **115,572 B** of the shell even after key-once
+packing — more than any dependency, and an English-only shell is 28.8%
+smaller. But we want *more* languages, not fewer. So: **bundle a core, ship
+everything else as signed downloadable packs.**
+
+- **Bundled (9):** the existing 8 (en, ja, zh-Hans, zh-Hant, es, fr, de, it)
+ plus **Portuguese**. Nothing regresses for current users; Portuguese is
+ added because Brazil has a real English-proficiency gap and it is in the
+ cheapest cost tier.
+- **Everything else:** a pack, signed with the existing release key and
+ released centrally alongside each app release, fetched only on explicit user
+ action and spliced into the file.
+
+**No further languages get bundled by default** — demand declares itself
+through contributions (#17 offers Korean), and a pack can be revised without
+cutting an app release.
+
+Measured facts worth not re-deriving: cost is **~14 KB per language regardless
+of script** (CJK is the *cheapest* — 2.6× the bytes per character but a third
+of the characters). Simplified↔Traditional conversion on the fly does **not**
+pay: only 43.3% of characters match, because the difference is vocabulary
+(软件/軟體) not glyph form, and deflate already recovers the genuine redundancy.
+Rank candidate languages by the **English-proficiency gap in the segment that
+uses this tool**, not by speaker counts — which is why Hindi is not in the core
+despite 610M speakers.
+
+Full design, risks and status: **`docs/i18n-packs.md`**. The risk that will
+ship broken if ignored: **self-update must carry packs forward** — `update.ts`
+re-splices the document into a *new shell*, and packs live in the shell.
+
## 2026-07-25 — Every PR gets human review before merging to main (for now)
At this stage of development the maintainer reviews **every** PR before it
diff --git a/docs/PLATFORM.md b/docs/PLATFORM.md
index 77637a3a..9292eee4 100644
--- a/docs/PLATFORM.md
+++ b/docs/PLATFORM.md
@@ -110,11 +110,18 @@ templates, never code).
## 8. i18n
-~1KB `t()` with English-string-as-key (missing key = English). Catalogs are
-compiled in; new UI strings must land in **all** catalogs in the same PR.
-Never call `t()` at module scope (frozen at import). `select()` localizes
-display labels only — model values stay English words. Audit with
-`setLocale('x-pseudo')`.
+~1KB `t()` with English-string-as-key (missing key = English). Never call
+`t()` at module scope (frozen at import). `select()` localizes display labels
+only — model values stay English words. Audit with `setLocale('x-pseudo')`.
+
+Catalogs come in two tiers. A **bundled core** is compiled in — the per-locale
+files under `slides/src/i18n/` are the authored source, packed key-once into
+`packed.ts` by `scripts/build-i18n.mjs` (CI gates that it is current). New UI
+strings must land in **all** core catalogs in the same PR. Every other language
+is a **signed pack**, released centrally and spliced into the file on demand;
+see `i18n-packs.md`. Packs are additive — a file that never fetches one behaves
+exactly as before — and both tiers fall back per string to the English key,
+which is what lets a stale or partial pack degrade instead of break.
## 9. What is kernel vs what is app
diff --git a/docs/i18n-packs.md b/docs/i18n-packs.md
new file mode 100644
index 00000000..40a2b0f2
--- /dev/null
+++ b/docs/i18n-packs.md
@@ -0,0 +1,177 @@
+# Language packs — design
+
+*Design document, July 2026. Status: **agreed, not built**. Companion to
+`PLATFORM.md` §6 (signed self-update) and §8 (i18n). The bundled-core half is
+settled; the pack half is specified here and implemented incrementally.*
+
+## The problem
+
+Translations are the largest single thing in the shell — larger than any
+dependency. Measured on v1.0.10, after the key-once packing landed:
+
+| | stored in shell |
+|---|---|
+| all 7 non-English catalogs | **115,572 B** |
+| Moveable stack (croact-moveable + ~12 satellites) | ~240 KB minified |
+| Reveal.js | ~109 KB minified |
+
+An English-only shell is **426,358 B against 598,457 B — 28.8% smaller.**
+
+So every language we bundle is paid for by every user, in every saved file,
+forever — including the ~99% of readers who will never switch to it. But the
+languages we *don't* bundle are simply unavailable, and the format's whole
+premise is that a file works offline with no server. That tension is what
+packs resolve.
+
+### Cost per language (measured, not estimated)
+
+Marginal cost of each catalog, deflated then base64'd as the shell stores
+payloads:
+
+| language | chars | bytes/char | stored |
+|---|---|---|---|
+| zh-Hant | 8,436 | 2.60 | 11.4 KB |
+| zh-Hans | 8,432 | 2.60 | 11.6 KB |
+| Italian | 25,810 | 1.03 | 13.8 KB |
+| Spanish | 26,142 | 1.03 | 14.3 KB |
+| French | 27,004 | 1.05 | 15.3 KB |
+| German | 25,954 | 1.04 | 16.4 KB |
+| Japanese | 12,090 | 2.71 | 16.7 KB |
+
+Counter-intuitively **CJK is the cheapest**: 2.6× the bytes per character, but
+a third of the characters. The practical rule is that cost is flat —
+**~14 KB per language regardless of script** — so budget per language and
+don't agonise over which.
+
+Two consequences worth recording, because both look like free wins and aren't:
+
+- **Simplified↔Traditional conversion on the fly does not pay.** Only **43.3%**
+ of characters are identical between the two catalogs, because the difference
+ is largely *vocabulary*, not glyph form (软件/軟體, 鼠标/滑鼠, 网络/網路,
+ 打印/列印). Conversion is also not a bijection (发 → 發 or 髮; 干 → 乾/幹/干),
+ so it needs word segmentation — which is why OpenCC's dictionaries run to
+ hundreds of KB. Meanwhile deflate **already** recovers 2.2 KB of the genuine
+ redundancy for free, because key-once packing puts each string's two variants
+ adjacent, inside the 32 KB window. A conversion table would cost ~8–12 KB to
+ replace an 11.4 KB catalog and produce text that reads as machine-converted
+ to precisely the audience most sensitive to it.
+- **Speaker counts are the wrong ranking metric.** What matters is the
+ *English-proficiency gap in the segment that uses this tool* — professionals,
+ students, educators. Bento's users in India, the Netherlands or Scandinavia
+ are largely served by English already and often prefer an English UI, since
+ the technical vocabulary is English. Brazil, Russia and Indonesia are the
+ opposite. Hindi's 610M headline overstates its value here more than any other
+ language's; it is also not politically neutral within India, where English is
+ often the preferred link language in the south.
+
+## The decision
+
+**A bundled core, plus downloadable packs for everything else.**
+
+- **Bundled (9):** English, Japanese, Simplified Chinese, Traditional Chinese,
+ Spanish, French, German, Italian, **Portuguese**. The existing eight stay so
+ that nothing regresses for current users; Portuguese is added because Brazil
+ has a genuine English-proficiency gap and it is in the cheapest cost tier.
+- **Packs (everything else):** signed, released centrally alongside each app
+ release, fetched on demand and spliced into the file.
+
+The bundled core is what makes this safe. It preserves the property in
+`kernel/src/i18n.ts` — *"a deck authored in Tokyo opens with French chrome in
+Paris"* — for the languages most likely to be encountered, and it keeps
+bento.page's live demo working in those languages on first contact. Packs are
+purely additive: a file that has never fetched one behaves exactly as today.
+
+**No new languages get bundled by default.** Demand declares itself through
+contributions (issue #17 is a volunteer offering Korean); a pack can ship and
+be revised without cutting an app release.
+
+## Design
+
+### Pack format
+
+A pack is one language for one app at one app version:
+
+```
+bento-slides-1.0.11-ko.pack.json
+{ "app": "slides", "version": "1.0.11", "lang": "ko",
+ "label": "한국어", "strings": { "<english key>": "<translation>", … } }
+```
+
+Per-language maps, not the bundled positional-array shape: a pack is edited
+and reviewed as one language, and positional arrays would couple every pack to
+a column order.
+
+### Signing and release
+
+Packs reuse the existing release machinery **exactly** — ECDSA P-256 over the
+sha256, verified against the `PUBLIC_KEY_JWK` already embedded in every shell
+(`PLATFORM.md` §6). The private key stays offline; `release.mjs` emits and
+signs packs beside the shell, and the manifest gains a `packs` array listing
+`{lang, version, sha256, url}`. No new trust root, no second key.
+
+### Loading
+
+`registerI18n` already accepts a packed table (kernel). Pack loading adds a
+merge step: a pack's strings layer over the bundled core for its language.
+Lookup misses fall back per string to the English key, which is what makes a
+partial or stale pack degrade gracefully rather than break.
+
+### Incorporation into the file
+
+A pack is fetched **only on explicit user action** ("Add language…"), verified,
+then spliced into the shell as an additional payload block and written out as
+a new file — the same fetch → verify → re-splice flow `update.ts` already
+performs. Nothing phones home by default; a file that never adds a language
+never talks to the network. Once spliced, the pack travels with the file and
+works offline forever, like everything else.
+
+## Risks
+
+**Self-update must carry packs forward — this is the one that will ship broken
+if it isn't designed in.** `update.ts` fetches a *new shell* and re-splices the
+current *document* into it. Packs live in the shell, not the document, so the
+naive path hands a Korean user back an English file after an update, silently
+and with no error to describe. Pack migration is part of the update path, not
+a follow-up.
+
+**Pack/app version coupling.** Every release adds strings. A 1.0.10 pack in a
+1.1.0 shell must degrade per string to English, never fail to load. The
+manifest is versioned per pack; the policy for "pack older than app" is
+load-and-degrade.
+
+**Splice contract.** Packs are additional payload blocks. `#bento-doc` stays
+plaintext and the file must still survive `DOMParser → outerHTML`
+(`PLATFORM.md` §2). `shell-gate.mjs` must cover a shell carrying packs — the
+gate is what protects updaters already frozen in the wild.
+
+**RTL is not a pack.** Arabic, Urdu, Persian and Hebrew are among the largest
+gaps by population, but they need bidi and mirroring work in the CSS. Ranking
+them by catalog bytes flatters them badly. Treat RTL as its own project; a pack
+alone will not make the UI usable.
+
+**Translation quality is the real constraint, not size.** The catalogs are
+machine-drafted with "native review welcome" in their headers. Packs improve
+this: a pack can be corrected and re-released without an app release, which
+turns native review into a continuous process instead of a release blocker.
+
+## Open questions
+
+- Does bento.page's download page pre-splice the visitor's likely locale
+ (client-side, since Pages is static)? Optional given the bundled core, but it
+ would help first contact for pack-only languages.
+- Do packs cover kernel strings shared across apps, or is each app's pack
+ self-contained? Slides, Spaces and Dash have overlapping but distinct string
+ sets.
+- Should a saved deck record which packs it carries, for the People/About UI?
+
+## Status
+
+- [ ] Key-once packing of the bundled catalogs — **PR #75, in flight**. A
+ prerequisite: it shrinks the core and its kernel change (`registerI18n`
+ accepting a packed table) is the loading path packs will reuse.
+- [ ] Portuguese catalog, bundled
+- [ ] Pack format + `release.mjs` emitting and signing packs
+- [ ] Manifest `packs` array
+- [ ] In-app "Add language…" (fetch → verify → splice)
+- [ ] **Update carries packs forward**
+- [ ] `shell-gate.mjs` covers a pack-carrying shell