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:
parent
4c25fc0f4f
commit
e2663d475e
2 changed files with 42 additions and 4 deletions
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue