@pie-players/pie-i18n-generated 0.0.0-stage → 1.0.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIE Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,273 @@
-# Temporary Holding Version
+# @pie-players/pie-i18n-generated
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Machine-generated, **unreviewed** interface locale catalogs for PIE players —
+the optional tier beneath the reviewed catalogs that
+[`@pie-players/pie-players-shared/i18n`](../players-shared/src/i18n/README.md)
+ships. Every catalog here is generated from the English source against a
+per-locale terminology brief, is provenance-marked, and is **not** presented
+as reviewed: the coverage number certifies structure (keys, placeholders,
+plural shape, freshness), never translation quality.
+
+Installing this package changes nothing on its own. A host opts in per
+deployment by wiring the loaders into the provider; a host that never sets a
+generated locale fetches nothing, because every catalog is a lazy chunk
+behind a static `import()` map and the default locale (`en-US`) is statically
+resident in `players-shared` and never hits a loader at all.
+
+The package depends on nothing: it is catalog data, and the provider it plugs
+into comes with the players, which install `@pie-players/pie-players-shared`.
+
+## Wiring
+
+```ts
+import {
+	BUNDLED_LOCALES,
+	createPieI18n,
+	loadBundledCatalog,
+} from "@pie-players/pie-players-shared/i18n";
+import {
+	GENERATED_LOCALES,
+	loadGeneratedCatalog,
+} from "@pie-players/pie-i18n-generated";
+
+const i18n = createPieI18n({
+	availableLocales: [...BUNDLED_LOCALES, ...GENERATED_LOCALES],
+	// Bundled first: a reviewed catalog silently wins over a generated one for
+	// the same tag, so promoting a locale out of this package into the
+	// reviewed set needs no host action.
+	loadCatalog: (locale) =>
+		loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale)),
+});
+
+// Hand the provider to the player; the element's `locale` names the locale
+// and is the only thing that drives it. Built without `locale` on purpose:
+// the factory names a tag without loading its catalog.
+document.querySelector("pie-section-player-splitpane").runtime = { i18n };
+```
+
+```html
+<pie-section-player-splitpane locale="th-TH" …></pie-section-player-splitpane>
+```
+
+Hosts may also override individual strings of a generated catalog the same
+way they override reviewed ones: `customMessages` is consulted ahead of any
+loaded catalog.
+
+## Locales
+
+| Tag | Status | Brief | Generated |
+| --- | --- | --- | --- |
+| `th-TH` | reviewed (agent pass in lieu of a native reader, 2026-11-03) | [`briefs/th-TH.md`](./briefs/th-TH.md) | 2026-10-19 |
+| `en-GB` | reviewed (agent verification pass, 2026-11-03; delta locale) | [`briefs/en-GB.md`](./briefs/en-GB.md) | 2026-10-19 |
+| `en-AU` | reviewed (agent verification pass, 2026-11-03; delta locale) | [`briefs/en-AU.md`](./briefs/en-AU.md) | 2026-10-19 |
+| `es` | reviewed (agent pass in lieu of a native reader, 2026-11-03; Latin-American neutral; serves `es*`) | [`briefs/es.md`](./briefs/es.md) | 2026-10-19 |
+| `fr` | reviewed (agent pass in lieu of a native reader, 2026-11-03; France flavour; serves `fr*`) | [`briefs/fr.md`](./briefs/fr.md) | 2026-10-19 |
+| `ar` | reviewed (agent pass in lieu of a native reader, 2026-11-04, after the RTL layout audit below landed; MSA; serves `ar*`; RTL) | [`briefs/ar.md`](./briefs/ar.md) | 2026-10-19 |
+| `pt` | reviewed (agent pass in lieu of a native reader, 2026-11-03; Brazilian; serves `pt*`) | [`briefs/pt.md`](./briefs/pt.md) | 2026-10-19 |
+| `ko` | reviewed (agent pass in lieu of a native reader, 2026-11-03) | [`briefs/ko.md`](./briefs/ko.md) | 2026-10-19 |
+| `ja` | reviewed (agent pass in lieu of a native reader, 2026-11-03) | [`briefs/ja.md`](./briefs/ja.md) | 2026-10-19 |
+| `zh` | reviewed (agent pass in lieu of a native reader, 2026-11-03; Simplified; serves `zh`, `zh-CN`, `zh-SG`; Traditional hosts supply `customMessages`) | [`briefs/zh.md`](./briefs/zh.md) | 2026-10-19 |
+| `cy` | reviewed (agent pass in lieu of a native reader, 2026-11-03; serves `cy`, `cy-GB`; six CLDR plural categories) | [`briefs/cy.md`](./briefs/cy.md) | 2026-10-19 |
+| `sv` | reviewed (agent pass in lieu of a native reader, 2026-11-03; serves `sv`, `sv-SE`, `sv-FI`) | [`briefs/sv.md`](./briefs/sv.md) | 2026-10-19 |
+| `ro` | reviewed (agent pass in lieu of a native reader, 2026-11-03; serves `ro`, `ro-RO`, `ro-MD`; three CLDR plural categories, `other` takes `de`) | [`briefs/ro.md`](./briefs/ro.md) | 2026-10-19 |
+| `vi` | reviewed (agent pass in lieu of a native reader, 2026-11-03; serves `vi`, `vi-VN`; one CLDR plural category) | [`briefs/vi.md`](./briefs/vi.md) | 2026-11-03 |
+| `nl-NL` | reviewed (**native-speaker audit** — the framework's audit language; carried over from `players-shared`'s bundled set on 2026-11-04, verbatim) | [`briefs/nl-NL.md`](./briefs/nl-NL.md) | 2026-10-18 |
+| `de` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; international deployment set; serves `de`, `de-AT`, `de-CH`) | [`briefs/de.md`](./briefs/de.md) | 2026-11-04 |
+| `it` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; international deployment set; serves `it`) | [`briefs/it.md`](./briefs/it.md) | 2026-11-04 |
+| `pl` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; international deployment set; serves `pl`; four CLDR plural categories) | [`briefs/pl.md`](./briefs/pl.md) | 2026-11-04 |
+| `tr` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; international deployment set; serves `tr`, `tr-CY`) | [`briefs/tr.md`](./briefs/tr.md) | 2026-11-04 |
+| `uk` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; international deployment set; serves `uk`; four CLDR plural categories) | [`briefs/uk.md`](./briefs/uk.md) | 2026-11-04 |
+| `el` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; international deployment set; serves `el`, `el-CY`) | [`briefs/el.md`](./briefs/el.md) | 2026-11-04 |
+| `ru` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; big-US wave; four CLDR plural categories) | [`briefs/ru.md`](./briefs/ru.md) | 2026-11-04 |
+| `fil` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; big-US wave; the `tl` tag aliases this catalog) | [`briefs/fil.md`](./briefs/fil.md) | 2026-11-04 |
+| `tl` | alias of `fil` (US systems label the language Tagalog) | [`briefs/fil.md`](./briefs/fil.md) | 2026-11-04 |
+| `ht` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; big-US wave) | [`briefs/ht.md`](./briefs/ht.md) | 2026-11-04 |
+| `ur` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; second RTL wave — inherits the audited RTL layout contract) | [`briefs/ur.md`](./briefs/ur.md) | 2026-11-04 |
+| `fa` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; second RTL wave) | [`briefs/fa.md`](./briefs/fa.md) | 2026-11-04 |
+| `he` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; second RTL wave; CLDR `two` category) | [`briefs/he.md`](./briefs/he.md) | 2026-11-04 |
+| `zh-Hant` | reviewed (agent generation-and-review pass in lieu of a native reader, 2026-11-04; Taiwan-register Traditional — regional tag, bare `zh` stays Simplified) | [`briefs/zh-Hant.md`](./briefs/zh-Hant.md) | 2026-11-04 |
+| `so` | reviewed (agent pass, 2026-11-04; state/regional wave — terminology partially standardized, **native review strongly advised**) | [`briefs/so.md`](./briefs/so.md) | 2026-11-04 |
+| `hmn` | reviewed (agent pass, 2026-11-04; state/regional wave — White Hmong RPA, CLDR-undersourced, **native review strongly advised**) | [`briefs/hmn.md`](./briefs/hmn.md) | 2026-11-04 |
+| `km` | reviewed (agent pass, 2026-11-04; state/regional wave — Khmer script, **native review strongly advised**) | [`briefs/km.md`](./briefs/km.md) | 2026-11-04 |
+| `lo` | reviewed (agent pass, 2026-11-04; state/regional wave — Lao script, **native review strongly advised**) | [`briefs/lo.md`](./briefs/lo.md) | 2026-11-04 |
+| `bn` | reviewed (agent pass, 2026-11-04; state/regional wave — Bengali script, **native review strongly advised**) | [`briefs/bn.md`](./briefs/bn.md) | 2026-11-04 |
+| `pa` | reviewed (agent pass, 2026-11-04; state/regional wave — Gurmukhi script, **native review strongly advised**) | [`briefs/pa.md`](./briefs/pa.md) | 2026-11-04 |
+| `ne` | reviewed (agent pass, 2026-11-04; state/regional wave — Devanagari script, **native review strongly advised**) | [`briefs/ne.md`](./briefs/ne.md) | 2026-11-04 |
+| `am` | reviewed (agent pass, 2026-11-04; state/regional wave — Ethiopic script, **native review strongly advised**) | [`briefs/am.md`](./briefs/am.md) | 2026-11-04 |
+
+Locale tags are chosen for variant reach: bare tags (`es`, `fr`, `ar`) let
+`es-MX`, `fr-CA` and `ar-SA` widen onto them through RFC 4647 lookup, while
+`en-GB`/`en-AU` are regional on purpose so bare `en` keeps resolving to the
+bundled English.
+
+Provenance — the exact `en-US` source hash each catalog was generated from,
+the generating model and date — is recorded in
+[`catalog-manifest.json`](./catalog-manifest.json).
+
+The `calibration/` directory holds a pipeline measurement against the one
+locale that has audited ground truth (Dutch), not a shippable catalog. See
+[`calibration/nl-NL-calibration.md`](./calibration/nl-NL-calibration.md) for
+what the pipeline does and does not deliver, and what that means for reviewing
+a generated locale.
+
+## Checks
+
+```bash
+bun run check:i18n-generated
+```
+
+runs `scripts/check-catalogs.ts`, which fails on:
+
+- **staleness** — per the locale's status: a `generated` locale whose recorded
+  `en-US` hash no longer matches the current English source (its untranslated
+  keys would silently fall back to English); a `reviewed` locale whose English
+  snapshot no longer matches current English, listing exactly the keys whose
+  English moved;
+- **key drift** — a missing key, or a key English no longer defines;
+- **placeholder drift** — a lost `{name}` slot or an invented one, in string
+  or plural-group leaves;
+- **plural shape** — a missing plural group, or a group without `other`;
+- **manifest disagreement** — a locale present in the loader map but not the
+  manifest, or the reverse.
+
+The check runs in the repository's pre-commit and CI gates: changing English
+fails the gate until the affected catalogs are regenerated — wholesale for
+`generated` locales, surgically for `reviewed` ones.
+
+## The review lifecycle
+
+**Agent passes in lieu of native readers.** On 2026-11-03 `es`, `en-GB` and
+`en-AU` were promoted on agent passes: no native readers were available, the
+maintainer accepted agent review for them, and each manifest entry's
+`reviewedBy` records exactly that. `reviewed` still means *a pass happened and
+its work is anchored* — the pass's nature lives in the manifest, the native
+pass remains open work, and because regeneration is surgical from here, a
+later native pass corrects in place instead of starting over.
+
+A locale moves through two statuses, recorded in `catalog-manifest.json`, and
+what regeneration may touch follows from the status:
+
+**`generated` — machine output, no reader behind it.** Regeneration is
+wholesale, and losing nothing makes that safe:
+
+1. Read `briefs/<locale>.md`, then regenerate `src/messages/<locale>.ts` from
+   the current `packages/players-shared/src/i18n/messages/en-US.ts`, keeping
+   every `{placeholder}` slot and the plural-group shape.
+2. Update `catalog-manifest.json`: the new `source.hash` (sha256 over the
+   JSON serialization of the `en-US` default export), and the locale's
+   `generatedAt` and `model`.
+3. Run `bun run check:i18n-generated` until it passes.
+
+**Taking a review pass** promotes the locale in place, and this is the step
+that makes iteration to audited quality a ratchet instead of a treadmill:
+
+1. A native reader goes through the catalog — the calibration report's
+   finding list is the checklist — correcting the file in place.
+2. Flip the locale's `status` to `reviewed` in the manifest, add `reviewedAt`
+   (and a `reviewedBy` note if wanted), and keep `sourceHash` as the
+   generation it started from.
+3. Run `bun run scripts/write-english-snapshot.ts <locale>`, which anchors
+   the corrections to the English they were reviewed against
+   (`src/messages/<locale>.english-snapshot.json`).
+4. `bun run check:i18n-generated` passes again — and from now on, changing a
+   translated string is preserved work: only keys whose *English* changed
+   ever need regenerating.
+
+**`reviewed` — regeneration is surgical, never wholesale.** When the gate
+lists keys whose English moved:
+
+1. Regenerate **only the listed keys**, against the brief and the new English
+   strings. Every translation the gate does not name stays exactly as the
+   review left it.
+2. Refresh the anchor:
+   `bun run scripts/write-english-snapshot.ts <locale>`.
+3. `bun run check:i18n-generated` until it passes.
+
+Wholesale regeneration of a `reviewed` locale discards review work; do it
+only deliberately, by flipping the status back to `generated` first.
+
+## The RTL layout audit (`ar`)
+
+Status: **landed 2026-11-04**, and `ar`'s promotion followed it. This section
+is the audit's record; the checks it added run in the suite.
+
+`ar` is the framework's first right-to-left interface locale, and the audit
+that gated its review pass was a layout audit, not a translation one: a native
+reviewer certifying strings that render mirrored would certify the wrong
+product. `direction` derives from `Intl.Locale.prototype.textInfo` and the
+shell stamps `lang`/`dir` on its own host
+([adoption record](../../docs/architecture/i18n-interface-locale-adoption.md)).
+
+`packages/section-player/tests/section-player-rtl-layout.spec.ts` holds seven
+rendered cases against the `ar` demo
+(`/interface-locale?locale=ar`), run outside the sandbox per the repository's
+Playwright rules:
+
+1. **Card header** (pre-existing): the item toolbar hugs the trailing edge,
+   under a forced `dir` and under the real `ar` stamps.
+2. **Card footer**: the check-answer button mirrors under the same
+   `margin-inline-start` trailing-edge rule (`/item-session-control`, forced
+   `dir` — the rule reads inherited direction, and case 1 proves the stamping
+   path end to end).
+3. **Split-pane layout**: pane *order* flips — passages pane leads in LTR,
+   trails in RTL; containment stays with the scroll contract.
+4. **Toolbar pane**: the shell's toolbar pane hugs the trailing viewport edge
+   and follows the direction (right under LTR, left under `ar`); the vertical
+   tool column's reading order is direction-independent by design and is
+   pinned as stable.
+5. **Tool windows at `document.body`**: the graph shell's contents mirror
+   (title leads from the right under `ar`) while its screen position and size
+   stay put — the adoption record's free-window rule.
+6. **Metrics**: no chrome control clips (`scrollWidth` past the box) and no
+   horizontal page overflow appears under `ar`; the sweep covers the chrome
+   subtrees through the custom elements' open shadow roots and excludes the
+   item players' content roots, which are the content-language channel.
+7. **Text-level rendered inspection** (recorded, not asserted): a full-page
+   screenshot of the `ar` demo was inspected — Arabic labels sit at the
+   trailing edges with Western digits per the brief, English content keeps
+   its own LTR inside the content root's `dir="auto"`, and no punctuation
+   strands on the wrong side of an embedded Latin run in the rendered chrome.
+
+**Defect found and repaired by the audit**: the toolbar pane's divider was a
+physical `border-left`/`border-right`
+(`SectionPlayerShell.svelte`), so under RTL the divider rendered on the
+pane's outer screen edge instead of the content side. It now uses
+`border-inline-start`/`border-inline-end`, and case 4's pane-flip assertion
+pins the geometry.
+
+**Recorded without assertions** — the surfaces the section demo cannot
+exercise: the toolbar scrolls rather than collapsing into an overflow menu
+when it overflows, and its tooltips are the browser's `title` rendering, so
+neither has an assertion to carry; Back/Next navigation chrome belongs to the
+assessment player (the reference assembly), not this building block; the
+standalone item player (`<pie-item-player>` on its own) has no locale-driven
+demo route, so its chrome mirror is covered only at the stamp level (the
+interface-locale spec asserts its content-root stamps) — a follow-up demo
+route would close that.
+
+## Adding a locale
+
+Add `briefs/<locale>.md` (register, glossary, untranslated product names —
+the th-TH brief is the template), translate `en-US` under it into
+`src/messages/<locale>.ts`, then register the tag in both `GENERATED_LOCALES`
+(`src/index.ts`) and `catalog-manifest.json`. The static `import()` map keeps
+each locale its own lazy chunk, exactly as `players-shared`'s `catalogs.ts`
+does.
+
+## Promoting a locale to the reviewed set
+
+A locale that has been through a review pass above can go further — into the
+audited set `players-shared` itself ships — and hosts need no migration
+either way:
+
+1. A native speaker with domain context reviews the catalog — the
+   calibration report's finding list is the review checklist.
+2. Move the corrected catalog into
+   `packages/players-shared/src/i18n/messages/<locale>.ts`, add the tag to
+   `BundledLocaleCode`, `catalogs.ts` and `COMPLETE_LOCALES` per that
+   package's README, and give it a changeset.
+3. Delete the catalog from this package and the tag from the loader map and
+   manifest.
+
+Because hosts compose the loaders bundled-first, the reviewed catalog wins
+from the moment it ships, whether or not the host has removed this package.

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Generated interface catalogs for PIE Players — the optional locale tier.
+ *
+ * Every catalog here is machine-generated against the terminology brief named
+ * in `catalog-manifest.json` and is **not reviewed** by a native speaker. The
+ * reviewed catalogs ship from `@pie-players/pie-players-shared/i18n`; this
+ * package is pure data a host opts into by installing it and wiring it into
+ * the provider alongside the bundled loaders:
+ *
+ * ```ts
+ * import {
+ * 	BUNDLED_LOCALES,
+ * 	createPieI18n,
+ * 	loadBundledCatalog,
+ * } from "@pie-players/pie-players-shared/i18n";
+ * import {
+ * 	GENERATED_LOCALES,
+ * 	loadGeneratedCatalog,
+ * } from "@pie-players/pie-i18n-generated";
+ *
+ * // Built without `locale`: the factory names a tag without loading its
+ * // catalog. The element's `locale` attribute drives the provider.
+ * const i18n = createPieI18n({
+ * 	availableLocales: [...BUNDLED_LOCALES, ...GENERATED_LOCALES],
+ * 	// Bundled first: a reviewed catalog silently wins over a generated one
+ * 	// for the same tag, which is what makes promotion from generated to
+ * 	// reviewed a no-op for a wired host.
+ * 	loadCatalog: (locale) =>
+ * 		loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale)),
+ * });
+ * // <pie-item-player locale="th-TH"> with `player.i18n = i18n`
+ * ```
+ *
+ * Nothing here loads unless a host asks for a generated locale: the loaders
+ * are never invoked for the default `en-US` (statically resident in
+ * `players-shared`), and each locale stays its own lazy chunk because `tsc`
+ * emits these `import()` calls verbatim — the same property
+ * `players-shared`'s `catalogs.ts` relies on.
+ *
+ * Provenance per locale — source hash, brief, model, generation date — lives
+ * in `catalog-manifest.json`. `scripts/check-catalogs.ts` fails when a catalog
+ * drifts from the English source or from its brief's structural rules.
+ *
+ * @module @pie-players/pie-i18n-generated
+ */
+import type { MessageCatalog } from "./message-catalog.js";
+/**
+ * Every locale tag this package ships a generated catalog for.
+ *
+ * `en-GB` and `en-AU` are regional on purpose: bare `en` must keep resolving
+ * to the statically bundled English, never to a regional variant.
+ */
+export declare const GENERATED_LOCALES: readonly string[];
+/**
+ * Load one generated catalog.
+ *
+ * Throws for a locale with no generated catalog; the provider treats that as
+ * "resolve through the fallback chain" rather than an error, mirroring
+ * `loadBundledCatalog`.
+ */
+export declare function loadGeneratedCatalog(locale: string): Promise<MessageCatalog>;

package/dist/index.js

@@ -0,0 +1,178 @@
+/**
+ * Generated interface catalogs for PIE Players — the optional locale tier.
+ *
+ * Every catalog here is machine-generated against the terminology brief named
+ * in `catalog-manifest.json` and is **not reviewed** by a native speaker. The
+ * reviewed catalogs ship from `@pie-players/pie-players-shared/i18n`; this
+ * package is pure data a host opts into by installing it and wiring it into
+ * the provider alongside the bundled loaders:
+ *
+ * ```ts
+ * import {
+ * 	BUNDLED_LOCALES,
+ * 	createPieI18n,
+ * 	loadBundledCatalog,
+ * } from "@pie-players/pie-players-shared/i18n";
+ * import {
+ * 	GENERATED_LOCALES,
+ * 	loadGeneratedCatalog,
+ * } from "@pie-players/pie-i18n-generated";
+ *
+ * // Built without `locale`: the factory names a tag without loading its
+ * // catalog. The element's `locale` attribute drives the provider.
+ * const i18n = createPieI18n({
+ * 	availableLocales: [...BUNDLED_LOCALES, ...GENERATED_LOCALES],
+ * 	// Bundled first: a reviewed catalog silently wins over a generated one
+ * 	// for the same tag, which is what makes promotion from generated to
+ * 	// reviewed a no-op for a wired host.
+ * 	loadCatalog: (locale) =>
+ * 		loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale)),
+ * });
+ * // <pie-item-player locale="th-TH"> with `player.i18n = i18n`
+ * ```
+ *
+ * Nothing here loads unless a host asks for a generated locale: the loaders
+ * are never invoked for the default `en-US` (statically resident in
+ * `players-shared`), and each locale stays its own lazy chunk because `tsc`
+ * emits these `import()` calls verbatim — the same property
+ * `players-shared`'s `catalogs.ts` relies on.
+ *
+ * Provenance per locale — source hash, brief, model, generation date — lives
+ * in `catalog-manifest.json`. `scripts/check-catalogs.ts` fails when a catalog
+ * drifts from the English source or from its brief's structural rules.
+ *
+ * @module @pie-players/pie-i18n-generated
+ */
+/**
+ * An explicit static map rather than a bundler macro, for the same reason
+ * `catalogs.ts` gives: `tsc` emits the `import()` calls verbatim, so `dist`
+ * evaluates under every ESM runtime, and every bundler keeps each locale its
+ * own chunk. String-keyed: the generated set is open, and a host adding a
+ * locale adds one line here alongside the file.
+ */
+const GENERATED_CATALOG_LOADERS = {
+    "th-TH": () => import("./messages/th-TH.js"),
+    "en-GB": () => import("./messages/en-GB.js"),
+    "en-AU": () => import("./messages/en-AU.js"),
+    // Bare tags on purpose: the provider's RFC 4647 lookup plus
+    // primary-subtag widening lands `es-MX`, `es-419`, `fr-CA`, `pt-BR` and
+    // `ar-SA` on these, and a host wanting a different national flavour
+    // overrides per key through `customMessages`. `zh` is Simplified Chinese
+    // and catches `zh-CN`/`zh-SG`; Traditional-Chinese hosts supply their own
+    // messages.
+    es: () => import("./messages/es.js"),
+    fr: () => import("./messages/fr.js"),
+    ar: () => import("./messages/ar.js"),
+    pt: () => import("./messages/pt.js"),
+    ko: () => import("./messages/ko.js"),
+    ja: () => import("./messages/ja.js"),
+    zh: () => import("./messages/zh.js"),
+    // Bare tags: `cy-GB` widens to `cy`, `sv-SE`/`sv-FI` to `sv`, and
+    // `ro-RO`/`ro-MD` to `ro`.
+    cy: () => import("./messages/cy.js"),
+    sv: () => import("./messages/sv.js"),
+    ro: () => import("./messages/ro.js"),
+    // Bare tag: `vi-VN` widens to `vi`.
+    vi: () => import("./messages/vi.js"),
+    // Regional on purpose, like en-GB/en-AU: the framework's audit language,
+    // native-speaker-reviewed, carried over from players-shared's bundled set
+    // on 2026-11-04. A bare `nl` widens onto it through the host's composed
+    // availableLocales, and its absence from the bundled set means a host that
+    // never wires this package never fetches it.
+    "nl-NL": () => import("./messages/nl-NL.js"),
+    // Bare tags: `de-AT`/`de-CH` widen to `de`, `tr` covers `tr-TR`, `el` covers
+    // Greece and Cyprus, `uk` covers Ukrainian everywhere.
+    de: () => import("./messages/de.js"),
+    it: () => import("./messages/it.js"),
+    pl: () => import("./messages/pl.js"),
+    tr: () => import("./messages/tr.js"),
+    uk: () => import("./messages/uk.js"),
+    el: () => import("./messages/el.js"),
+    // The big-US wave: `ru` carries the Slavic four-category set; `ht` is
+    // Haitian Creole; `fil` is Filipino — one catalog. A host labeling delivery
+    // Tagalog names `fil` (the modern stack name) or aliases `tl` in its own
+    // composition; this package ships the single authored catalog.
+    ru: () => import("./messages/ru.js"),
+    fil: () => import("./messages/fil.js"),
+    ht: () => import("./messages/ht.js"),
+    // The second RTL wave: the framework's RTL layout contract is audited and
+    // pinned by section-player's geometry spec (see the ar locale), so these
+    // inherit a verified mirroring path. `he` carries a CLDR `two` category.
+    ur: () => import("./messages/ur.js"),
+    fa: () => import("./messages/fa.js"),
+    he: () => import("./messages/he.js"),
+    // Regional on purpose, like nl-NL: Taiwan-register Traditional Chinese.
+    // Bare `zh` stays Simplified; `zh-TW`/`zh-HK` widen onto this.
+    "zh-Hant": () => import("./messages/zh-Hant.js"),
+    // The state/regional US wave: mostly one/other or other-only plurals, and
+    // several non-Latin scripts (Khmer, Lao, Bengali, Gurmukhi, Ethiopic,
+    // Devanagari; White Hmong in RPA Latin). Briefs flag where assessment
+    // terminology is not standardized — native review strongly advised.
+    so: () => import("./messages/so.js"),
+    hmn: () => import("./messages/hmn.js"),
+    km: () => import("./messages/km.js"),
+    lo: () => import("./messages/lo.js"),
+    bn: () => import("./messages/bn.js"),
+    pa: () => import("./messages/pa.js"),
+    ne: () => import("./messages/ne.js"),
+    am: () => import("./messages/am.js"),
+};
+/**
+ * Every locale tag this package ships a generated catalog for.
+ *
+ * `en-GB` and `en-AU` are regional on purpose: bare `en` must keep resolving
+ * to the statically bundled English, never to a regional variant.
+ */
+export const GENERATED_LOCALES = [
+    "th-TH",
+    "en-GB",
+    "en-AU",
+    "es",
+    "fr",
+    "ar",
+    "pt",
+    "ko",
+    "ja",
+    "zh",
+    "cy",
+    "sv",
+    "ro",
+    "vi",
+    "nl-NL",
+    "de",
+    "it",
+    "pl",
+    "tr",
+    "uk",
+    "el",
+    "ru",
+    "fil",
+    "ht",
+    "ur",
+    "fa",
+    "he",
+    "zh-Hant",
+    "so",
+    "hmn",
+    "km",
+    "lo",
+    "bn",
+    "pa",
+    "ne",
+    "am",
+];
+/**
+ * Load one generated catalog.
+ *
+ * Throws for a locale with no generated catalog; the provider treats that as
+ * "resolve through the fallback chain" rather than an error, mirroring
+ * `loadBundledCatalog`.
+ */
+export async function loadGeneratedCatalog(locale) {
+    const loader = GENERATED_CATALOG_LOADERS[locale];
+    if (!loader) {
+        throw new Error(`No generated i18n catalog for locale: ${locale}`);
+    }
+    const module = await loader();
+    return module.default;
+}

package/dist/message-catalog.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The shape of a locale catalog, as `@pie-players/pie-players-shared/i18n`
+ * defines `MessageCatalog`.
+ *
+ * Restated here because the generated catalogs are pure data: a declaration that
+ * named players-shared would make every host that installs them install it for
+ * one type. `test/message-catalog-contract.test.ts` fails the typecheck when the
+ * two stop accepting each other, which is what lets a host hand
+ * `loadGeneratedCatalog` straight to the provider's `loadCatalog`.
+ */
+/** A plural group; `other` is the one category every language has. */
+interface PluralTranslation {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/** A catalog node: a leaf string, a plural group, or a namespace. */
+type MessageNode = string | PluralTranslation | {
+    [key: string]: MessageNode;
+};
+/** A whole catalog, as one locale module default-exports it. */
+export type MessageCatalog = {
+    [key: string]: MessageNode;
+};
+export {};

package/dist/message-catalog.js

@@ -0,0 +1,11 @@
+/**
+ * The shape of a locale catalog, as `@pie-players/pie-players-shared/i18n`
+ * defines `MessageCatalog`.
+ *
+ * Restated here because the generated catalogs are pure data: a declaration that
+ * named players-shared would make every host that installs them install it for
+ * one type. `test/message-catalog-contract.test.ts` fails the typecheck when the
+ * two stop accepting each other, which is what lets a host hand
+ * `loadGeneratedCatalog` straight to the provider's `loadCatalog`.
+ */
+export {};