Docs: string packs as a Store kind (licence and credits on every item), the delivery to site tabs, the Languages section and translate mode

This commit is contained in:
CRTkafa 2026-10-01 04:26:02 +07:00
parent 4c25fc0f4f
commit e2663d475e
2 changed files with 42 additions and 4 deletions

View file

@ -34,13 +34,15 @@ JSON Schema: `waybetter/store-catalog.schema.json` (npm package). The rules apps
| --- | --- | | --- | --- |
| `format` | `2`. An app that reads another format says "update the app". Format 1 (before `apps`) is gone. | | `format` | `2`. An app that reads another format says "update the app". Format 1 (before `apps`) is gone. |
| `apps` | 1–16 distinct app ids (`[a-z0-9-]{1,32}`), e.g. `"x"`; an item for several apps lists each. | | `apps` | 1–16 distinct app ids (`[a-z0-9-]{1,32}`), e.g. `"x"`; an item for several apps lists each. |
| `kind`, `id` | `theme` or `plugin`; `[a-z0-9-]{1,40}`, unique per app and kind. | | `kind`, `id` | `theme`, `plugin` or `strings` (a string pack, docs/STRING-PACKS.md); `[a-z0-9-]{1,40}`, unique per app and kind. |
| `name`, `author`, `version`, `description`, `category`, `tags` | plain text (no control characters), ≤ 60 / 60 / 32 / 600 / 32 characters, ≤ 12 tags of ≤ 32. Known categories show in the reader's language (`wb.store.category.*`). | | `name`, `author`, `version`, `description`, `category`, `tags` | plain text (no control characters), ≤ 60 / 60 / 32 / 600 / 32 characters, ≤ 12 tags of ≤ 32. Known categories show in the reader's language (`wb.store.category.*`). |
| `url`, `preview` | https; for the reading app's own items, on its download hosts (below). | | `url`, `preview` | https; for the reading app's own items, on its download hosts (below). |
| `file` | plugins only: `name.plugin.js` (letters, digits, `-_. `), unique per app ignoring case. | | `file` | plugins only: `name.plugin.js` (letters, digits, `-_. `), unique per app ignoring case. |
| `sha256`, `size` | of the exact file; size 1 byte … 2 MiB. | | `sha256`, `size` | of the exact file; size 1 byte … 2 MiB. |
| `permissions` | plugins only: the header's `@permissions` (`null` = no line, legacy). | | `permissions` | plugins only: the header's `@permissions` (`null` = no line, legacy). |
| `colors` | themes only: `#rrggbb` swatches for the card. | | `colors` | themes only: `#rrggbb` swatches for the card. |
| `language` | string packs only, required: the pack's language tag. |
| `license`, `credits` | any kind, optional: its licence (≤ 60 characters, e.g. an SPDX id) and who made, translated or reviewed it (≤ 600). The install screen shows them. |
Also refused: unknown fields anywhere, more than 500 items, a catalog over 1 MiB, a signature file Also refused: unknown fields anywhere, more than 500 items, a catalog over 1 MiB, a signature file
over 512 bytes. A malformed item for another app refuses the whole catalog (one file, one set of over 512 bytes. A malformed item for another app refuses the whole catalog (one file, one set of

View file

@ -1,9 +1,10 @@
# String packs # String packs
A string pack replaces the wrapped site's own UI strings with data: it adds a language the site A string pack replaces the wrapped site's own UI strings with data: it adds a language the site
does not offer, fixes its translation, or rewords it. This is phase 1: the formats, the validator, does not offer, fixes its translation, or rewords it. The framework has the formats, the validator,
the application engine, the hook interface and `waybetter strings check`. The Store kind, the the application engine, the hook interface, `waybetter strings check`, the Store kind `strings`
install screen and the settings UI are not built yet. with its install screen, the Languages section and translate mode. Sentences with element slots
(rich text) cannot be replaced yet.
## Rules ## Rules
@ -148,3 +149,38 @@ Prints what was refused and why, the unknown keys, and the coverage per group (t
translatable, and how many keys are not translatable yet). Exit 1 when anything would not be translatable, and how many keys are not translatable yet). Exit 1 when anything would not be
applied. Without `--inventory`, the inventories come from `waybetter.strings.json` applied. Without `--inventory`, the inventories come from `waybetter.strings.json`
(`{ "inventories": ["…"] }`) in the app's root. (`{ "inventories": ["…"] }`) in the app's root.
## Installing and turning packs on
String packs are a Store kind (`kind: "strings"`, with `language`; every item may also carry
`license` and `credits`) and install like themes and plugins: a dropped `*.strings.json`, a
`waybetter://install?kind=strings&url=…` link or the signed Store, always through the install screen.
The screen shows the pack's language, its coverage against the site's inventory, what is ignored
and what cannot be replaced yet, a sample of its text, that it is data only, and the pack file.
Native code (waybetter-host `store::strings`) only keeps data: it checks the envelope and that every
value is plain text, writes `<app data>/strings/<id>.json` and remembers the order and which packs
are on (at most 8). It never sees the inventory. Shell-only commands: `strings_list`,
`strings_read`, `strings_set {order, enabled}`, `strings_remove {id}`, `strings_apply {delivery}`.
The shell builds the delivery (`buildDelivery`: the packs that are on, in order, with the slice of
the inventory their keys need) and hands it to `strings_apply`. Native code stores it under a new
revision and puts it into every site tab's session storage (`wayBetter.stringPacks`) with a
data-only script that checks `https:` and the site's own hosts, then reloads the tab; a new tab
gets the same script as the first document-start layer. Safe mode leaves the layer out. A tab keeps
the newest revision it was given. The page runtime reads the delivery at document start, before
the site's scripts.
The Languages section of the panel (`createStringPacksSection({ inventory })`) lists the installed
packs with their coverage, turns them on and off, orders and removes them.
## Translate mode
Switched on in the Languages section. The delivery then carries the whole inventory, packs or not,
and the page runtime marks every replaceable string with an invisible marker naming its key
(`createMarker`). A bar at the bottom of each site tab says so; a click on a word opens an editor
with the key, the current text and its parameters. An edit is checked with the pack rules
(`checkEdit`) and kept in the tab's draft (`wayBetter.translateDraft`), which applies as the last
pack after a reload. "Copy pack file" copies the draft as a pack document. "Leave" turns the mode
off for that tab. The markers can reach places that compare text exactly (the window title), so the
mode is for authors only and is never on by default.