waybetter/docs/STRING-PACKS.md

String packs

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. The framework has the formats, the validator, the application engine, the hook interface, waybetter strings check, the Store kind strings with its install screen, the Languages section and translate mode. Sentences with element slots (rich text) are replaced with {e0}, {e1} placeholders for the site's own elements. A pack can also reword the site's own text by words (rewrite) and apply only while the site is in some languages (when).

Rules

1. Idempotent. The result is a pure function of (the site's own values, the ordered pack list). Applying twice equals applying once. Packs apply in the listed order; a later pack wins per key.
2. The site's own language is the fallback. A pack patches on top of whatever language the site shows. A key no pack changes keeps exactly the site's value.
3. An inventory of the site's known keys. A pack can change only inventory keys. An unknown key is reported and never applied.
4. Packs are data. Plain text in an ICU MessageFormat subset. Never HTML, never code.

The pack

{
  "format": 1,
  "site": "x",
  "catalog": "web",
  "language": "en-x-pirate",
  "name": "Pirate",
  "authors": ["Someone"],
  "base": "en",
  "strings": {
    "a0000001": "Home port",
    "b0000002": "{count, plural, one {# sighting} other {# sightings}}"
  }
}

• site and catalog name the inventory the pack is for. One site can have several catalogs (different builds of the site with different key spaces); each has its own inventory and packs.
• language is a BCP 47 tag; a private-use tag is fine. base is the language whose plural rules the pack follows when the runtime does not know language; without either, every number takes the other form.
• when (optional) is a condition: { "languages": ["en"] } applies the pack only while the site shows English (a tag matches itself and its regional forms: en matches en-GB; the match is case-insensitive). The site's language is the one its catalog registers (sink.matched), so a pack that rewords English never touches a Turkish page. Without when a pack always applies.
• rewrite (optional) rewords the site's own text instead of replacing keys: { "words": { "Post": "Tweet", "posts": "tweets" } }. Whole words only, case as written, 1 to 64 entries of plain letters and digits; applied to the text of every inventory key (plain strings, the result of messages, the pieces of rich sentences) that no later pack replaced. A parameter's value is never reworded (a user named "Post" stays "Post"). The pack carries none of the site's sentences, so it keeps working when the site rewords a string, and strings may be empty.
• strings maps a key id to text. The ids are the inventory's; a pack never carries the site's own text.

A value may use {name}, {name, plural, one {…} other {…}} (with # for the number and =0, =1 exact forms) and {name, select, a {…} other {…}}. A value is refused, and the site's text stays, when:

• it names a parameter the original does not take;
• it pluralizes a parameter the original does not pluralize, or selects on one the original does not select on (the original's plural parameters are the ones known to be numbers);
• a plural or select has no other;
• it uses a number or date format, selectordinal or a plural offset;
• it contains < or > (unless the inventory gives the key tag slots; then exactly those tags);
• it contains control or bidi-override characters, is empty or is longer than 2000 characters;
• the key's kind cannot be replaced by data yet (format, and rich entries the inventory gives no slots).

A rich value (a sentence with a link or button inside) uses the original's element slots: {e0} … {e<slots-1>} stand for the site's own elements, each exactly once (the last one may be left out: the element after the final piece is not always there), in any order your sentence needs. No plural, select, parameter or markup. A pack never carries HTML; the elements are the site's.

A parameter is inserted the way string concatenation would insert it (String(value)).

The inventory

{
  "format": 1, "site": "x", "catalog": "web", "base": "en", "build": "…",
  "entries": {
    "a0000001": { "kind": "text", "hash": "0k3j…" },
    "b0000002": { "kind": "message", "params": ["count"], "plural": ["count"], "hash": "…" },
    "c0000003": { "kind": "rich", "slots": 2, "group": "rich", "hash": "…" }
  }
}

Kind	The site's value	A pack can replace it
text	a string	yes
message	a function of parameters that returns a string	yes
rich	text with element slots (slots)	yes, when the inventory knows slots
format	a compiled number, date or currency formatter	no

slots (rich) is the number of element positions of the site's sentence: piece n is followed by the caller's element n. hash is a hash of the base-language value (hashText), for the drift report; the inventory holds no text of the site. group names the part of the catalog a key arrives with (default main).

driftReport(inventory, observed, loadedGroups) compares an inventory with a newer build: added, reworded (the hash changed), reshaped (kind or parameters changed) and vanished. A key is called vanished only when its group's base catalog was actually read.

packInventory(inventory) is the compact form: ids and shapes, no hashes. A page does not need the whole inventory: sliceInventory(inventory, ids) is the part that the packs' keys need, and it travels to the page together with the packs (isPageInventory checks its shape on arrival). The full inventory stays where packs are installed and checked.

The engine

const engine = createStringEngine(inventory, [compilePack(packA, inventory), compilePack(packB, inventory)]);
engine.resolve(id, siteValue);   // packB's value, else packA's, else exactly siteValue

resolve returns a string for a text key, a function with the original's call shape for a message key (closures over the parsed message; nothing is evaluated) and, for a rich key, a RichTemplate { pieces, order }: piece n is shown, then the site's element order[n] (the shape X's own sentence renderer reads; wiring it into a site's renderer is the adapter's part). A pack's rewrite is applied to whichever value results, so a reworded message is a function again. engine.setLanguage(language) tells the engine which language the site shows (the hook does it when the adapter reports matched); conditional packs wait for it. Feeding a value the engine produced back in returns the same value. It keeps the site's own value of every key it changed (engine.originals()), which is what a restore needs; applyPacks and restoreCatalog do both for a whole catalog object without changing it. A live value whose kind differs from the inventory's is left alone and listed in engine.stats().mismatched; a key the site has and the inventory lacks is listed in unlisted.

Hooking a site

How a site hands its strings to its own code is that site's implementation detail, so the hook is an adapter the app supplies:

const adapter: CatalogHookAdapter = {
  catalog: 'web',
  install(win, sink) {
    // At document start: arrange for the site's catalog to pass through
    //   sink.seen(group)              a catalog file is loading
    //   sink.matched(language, group) the hook matched
    //   sink.resolve(id, original)    the value to register
    return () => { /* remove the hook */ };
  },
};
const handle = installStringPacks(window, [{ adapter, inventory, packs }], { onStatus });

• The adapter must not change the site's objects: hand the site a shadow (Object.create(module)) instead.
• Everything fails open: an exception in a wrapper leaves the site's behaviour as it was.
• A catalog without a usable pack is not hooked at all.
• The self-check decides after settleMs: ok, not-matched (a catalog file was seen but the hook did not match: the site changed) or no-catalog (no catalog file was seen).

For a webpack site, watchChunkArray(win, name, onChunk) sees every chunk before the site's own push gets it and passes it on unchanged; mapChunkRequires(chunk, map) lets one identified chunk's modules receive a shadow of what they require.

installTextNet(win, { map }) is a DOM safety net for labels no catalog hook can reach (the server sends them already worded): exact text in text nodes, aria-label, placeholder and title, the site's value kept per node, restored on dispose(). It is secondary: it cannot see parameters or plural forms.

Checking a pack

waybetter strings check pack.strings.json --inventory strings/x.web.inventory.json

Prints what was refused and why, the unknown keys, and the coverage per group (translated of 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 ({ "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.

Built-in packs

An app can ship packs of its own (BuiltInPacks in panel/StringPacks.tsx: a function returning pack documents as text). They are delivered before the installed packs, so an installed pack wins where both change a word, they follow the app's settings and they are not listed or removable. syncStringPacks hands the tabs the delivery at start only when it differs from the one they were last given (every tab reloads for a change). wayBetter for X's Twitter wording (Post -> Tweet, Repost -> Retweet) is one: a rewrite pack for English that is delivered while its setting is on. A delivery with a rewording pack carries the whole page inventory (the engine needs every key's shape), not a slice.

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 bar's and the editor's words are the app's own (words option of installTranslateUi, a function that is asked again each time they are drawn, so a language switch shows at once); the English defaults are TRANSLATE_WORDS. 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.