@burdenoff/fe-libs 2026.1021.8 → 2026.1021.9

package/scripts/i18n/types.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared types for the fleet i18n toolkit (`burdenoff-i18n`).
+ *
+ * The bundle shape is the one every app shell emits as `/i18n-bundle.json` and
+ * global-i18n-svc's `seed:translations` reads (gitops `--bundle-url`): one
+ * entry per key, with its value per locale. Everything here is the published
+ * contract, so a shell's own builder and this toolkit agree on what a row is.
+ */
+
+/** One key of an emitted bundle: its value per locale code. */
+export interface BundleKey {
+  key: string;
+  namespace?: string;
+  values: Readonly<Record<string, string>>;
+}
+
+/** The emitted `/i18n-bundle.json`. Only `keys` is read; the header is passed through. */
+export interface I18nBundle {
+  $schema?: string;
+  product?: { name?: string; displayName?: string };
+  languages?: ReadonlyArray<{ code: string }>;
+  keys: readonly BundleKey[];
+}
+
+/** One seeded row: `[key, locale, value]`. */
+export type BundleRow = readonly [key: string, locale: string, value: string];
+
+/**
+ * How row and key lines are ordered before hashing.
+ *
+ * - `utf8`  sorts by UTF-8 bytes (Buffer.compare), which is Unicode code-point
+ *   order. FluidGrids' served-bundle fixture was generated this way.
+ * - `utf16` sorts by JavaScript's default string comparison (UTF-16 code
+ *   units). VibeControls' seed-plan fixtures were generated this way.
+ *
+ * The two orders agree unless a line contains a character outside the Basic
+ * Multilingual Plane (an emoji, for example), so a digest names its order.
+ */
+export type DigestOrder = 'utf8' | 'utf16';
+
+/** Counts and set digests of a bundle: the served-bundle contract. */
+export interface BundleDigest {
+  keys: number;
+  rows: number;
+  order: DigestOrder;
+  /** sha256 of the keys, one per line, sorted in `order`. */
+  keySetSha256: string;
+  /** sha256 of `JSON.stringify([key, locale, value])` lines sorted in `order`. */
+  rowSetSha256: string;
+  rowsByLocale: Record<string, number>;
+}
+
+/** A row the proposed bundle changes relative to the base. */
+export interface RowChange {
+  key: string;
+  locale: string;
+  before: string | null;
+  after: string | null;
+}
+
+/** What seeding `proposed` over `base` would do, row by row. */
+export interface BundleDiff {
+  base: { keys: number; rows: number };
+  proposed: { keys: number; rows: number };
+  inserts: RowChange[];
+  updates: RowChange[];
+  deletions: RowChange[];
+  newKeys: string[];
+  removedKeys: string[];
+  insertsByLocale: Record<string, number>;
+}
+
+/** A key the shipped (compiled) code requests, with where it was found. */
+export interface ShippedKey {
+  pkg: string;
+  fallback: string;
+}
+
+/** What a shell's adapter returns when it builds its bundle in-process. */
+export interface AdapterBuild {
+  bundle: I18nBundle;
+  /**
+   * Keys the builder leaves out ON PURPOSE, with the reason. `verify-shipped`
+   * lists them and does not fail on them.
+   */
+  heldBack?: ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+}
+
+/**
+ * The shell-specific half of the toolkit. A shell points `adapter` in its
+ * `i18n.config.json` at a module exporting these (named exports or a default
+ * object). Both members are optional; a shell without an adapter can point
+ * `bundleFile` at its emitted bundle instead.
+ */
+export interface I18nAdapter {
+  /** Build the bundle exactly as the shell's build does. */
+  buildBundle?: () => Promise<AdapterBuild> | AdapterBuild;
+  /**
+   * Keys the shipped app requests that a scan of compiled `tr(key, fallback)`
+   * pairs cannot see (runtime-prefixed assistant keys, for example):
+   * key -> { source, fallback }.
+   */
+  requestedKeys?: () =>
+    | Promise<Readonly<Record<string, ShippedKey>>>
+    | Readonly<Record<string, ShippedKey>>;
+}
+
+/** `i18n.config.json`, as written by a shell. */
+export interface I18nToolsConfig {
+  /** Product slug, used in messages only. */
+  product: string;
+  /** Where production serves the bundle, e.g. `https://app.vibecontrols.com/i18n-bundle.json`. */
+  servedUrl?: string;
+  /** A built bundle on disk, relative to the config file (e.g. `dist/i18n-bundle.json`). */
+  bundleFile?: string;
+  /** Module implementing `I18nAdapter`, relative to the config file. */
+  adapter?: string;
+  shipped?: {
+    /** npm scope whose installed packages are scanned. Default `@burdenoff`. */
+    scope?: string;
+    /** Package names (without scope) to scan; a trailing `*` matches a prefix. Default `["microfe-*"]`. */
+    packages?: string[];
+  };
+  /** Whether the shell's fe-libs reads a branch's `_` slot (fe-libs >= 2026.919.1). Default true. */
+  readsLeafSlot?: boolean;
+  /** Line order for digests. Default `utf8`. */
+  digestOrder?: DigestOrder;
+}
+
+/** The config after defaults, with paths made absolute. */
+export interface ResolvedI18nToolsConfig {
+  product: string;
+  configDir: string;
+  servedUrl?: string;
+  bundleFile?: string;
+  adapter?: string;
+  shipped: { scope: string; packages: string[] };
+  readsLeafSlot: boolean;
+  digestOrder: DigestOrder;
+}