@nebulahome/package-sdk 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 The SDK's version is the version of the package API the platform implements: a minor version adds
 to it, a major one breaks it, and a patch leaves it as it is.
 
+## 1.2.0
+
+- **The past of the house.** `ctx.history.states()` and `ctx.history.telemetry()` on the server
+  read the recorded changes and the numeric readings of up to 64 entities over a window, with the
+  house's authority as `ctx.entities` has; `useStateHistory()` and `useTelemetry()` in
+  `@nebulahome/package-sdk/ui` read them with the viewer's, for a chart, an activity list or a
+  replay. Each entity's points come oldest first; a window that holds more than a read returns
+  loses its oldest points and names the entity in `truncated`. A window is two moments, or in the
+  interface the last so many milliseconds, which moves with each read; telemetry is read raw, or
+  in buckets of a minute, an hour or a day, `auto` picking by the window's length.
+  `createTestContext({ history })` and `test.setHistory()` give a unit test a past.
+- **The areas.** `useAreas()` lists the house, its floors (with their storey) and its rooms, each
+  naming its parent by key - the key `EntityView.areaId` holds - and the house its position.
+- **What an entity can do.** `EntityView.capabilities` holds the capabilities an entity declares,
+  with the device's limits: a cover's tilt, a thermostat's range and modes, a select's options.
+- **Pictures.** `useEntityPicture()` gives a camera's latest still, fetched again every so often,
+  or an image entity's picture, as an address an `<img>` shows.
+- **The sun.** `@nebulahome/package-sdk/sun`: `sunPosition`, `sunTimes`, `sunState` and
+  `sunPhaseLabel`, the platform's own formulas, for a moment the sun entities did not report.
+- A package's id may start with a digit (`3d-home`); its entities' object ids then do too.
+- **The MQTT broker is the platform's.** The hub runs the house's broker: `requires.services:
+["mqtt-broker"]` is always met, `{platform.mqtt.*}` and `NEBULA_PLATFORM_MQTT_*` name it, and a
+  package that `provides` `mqtt-broker` is refused at install.
+
+## 1.1.0
+
+- `useTranslation()` in `@nebulahome/package-sdk/ui`: a package's page, cards and entity views
+  say their strings with `t('clients.title', 'Clients')`, in the viewer's language. The English
+  is the fallback, and a plural takes `{ one, other }` with `count`; outside the interface - a
+  component's unit test - every string is its English.
+- Catalogues: `locales/<language>.json` beside `nebula.config.ts` (`it.json`, `pt-BR.json`), JSON
+  objects of strings nested as the keys are dotted, with i18next's plural suffixes and
+  `{{placeholders}}`. `nebula()` bundles each as a chunk of the interface, loaded only for a viewer
+  who reads that language; `validate` checks them (a language for a name, strings only, plurals
+  with their `_other`, at most 256 KB); `build` warns which strings a catalogue says in English
+  and which of its keys no string uses.
+- What `nebula.config.ts` declares - names, settings, entity types - stays English, as the
+  platform shows it everywhere.
+
 ## 1.0.1
 
 - `nebulahome-package --help`, and a mistyped command, work where Vite is not installed -

package/README.md

@@ -86,17 +86,72 @@ import { nebula } from '@nebulahome/package-sdk/vite';
 export default defineConfig({ plugins: [react(), tailwindcss(), nebula()] });
 ```
 
+## Translating the interface
+
+The page, the cards and the entity views say their strings through `useTranslation()`, with the
+English beside each key; a catalogue per language goes in `locales/` next to `nebula.config.ts`:
+
+```tsx
+// src/ui/forecast-card.tsx
+import { useTranslation } from '@nebulahome/package-sdk/ui';
+
+const { t } = useTranslation();
+
+t('forecast.empty', 'No forecast yet');
+t('forecast.days', { one: '{{count}} day', other: '{{count}} days' }, { count: days.length });
+```
+
+```json
+// locales/it.json
+{
+  "forecast": {
+    "empty": "Ancora nessuna previsione",
+    "days_one": "{{count}} giorno",
+    "days_other": "{{count}} giorni"
+  }
+}
+```
+
+A string a catalogue lacks is said in English, and `nebulahome-package build` lists them. What
+`nebula.config.ts` declares (the package's name, its cards' and settings' names, its entity types)
+stays English: the platform shows it the same way to everyone.
+
+## The past, the areas and the sun
+
+```tsx
+// a sensor's chart: the last 6 hours, in minutes
+const day = useTelemetry({ entityIds: [entityId], window: { lastMs: 6 * 3_600_000 } });
+const points = day.series[entityId] ?? []; // oldest first: { time, value, min, max }
+
+// what a door did today, and the rooms of the house
+const today = useStateHistory({ entityIds: [door], window: { from: midnight, to: now } });
+const rooms = useAreas().filter((area) => area.kind === 'room');
+```
+
+```ts
+// on the server, with the house's authority
+const { series } = await ctx.history.states({ entityIds, from: yesterday, to: new Date() });
+```
+
+```ts
+// where the sun was, for a moment the sun entities did not report
+import { sunPosition } from '@nebulahome/package-sdk/sun';
+
+const { elevation, azimuth } = sunPosition(at, { latitude, longitude });
+```
+
 ## Entry points
 
-| Import                    | What                                                                                                                                                                                                    |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@nebulahome/package-sdk` | `definePackage`, `defineSettings`, `defineCard`, `defineEntityType`, `definePage`, `defineContainer`, `defineCompose`, `field`, entity id helpers, `SDK_VERSION`, the value types.                      |
-| `/server`                 | `defineServer`, and the context `start` is given: settings (live or restart), devices and entities, typed custom entities, the rest of the house, methods for the interface, services between packages. |
-| `/ui`                     | The props of a page, a card and an entity view; hooks for the package, its methods, its settings, the house, the viewer, the theme; navigation inside the package's page and to the platform's places.  |
-| `/components`             | The part of the interface's design system a package may draw with.                                                                                                                                      |
-| `/vite`                   | `nebula()`, the Vite plugin that builds both halves: the interface in chunks with its CSS scoped to the package, the server bundled whole.                                                              |
-| `/testing`                | `createTestContext()`: run `start` in a unit test, every effect recorded.                                                                                                                               |
-| `/styles.css`             | The interface's Tailwind tokens, to `@reference`.                                                                                                                                                       |
+| Import                    | What                                                                                                                                                                                                                                            |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nebulahome/package-sdk` | `definePackage`, `defineSettings`, `defineCard`, `defineEntityType`, `definePage`, `defineContainer`, `defineCompose`, `field`, entity id helpers, `SDK_VERSION`, the value types.                                                              |
+| `/server`                 | `defineServer`, and the context `start` is given: settings (live or restart), devices and entities, typed custom entities, the rest of the house and its past, methods for the interface, services between packages.                            |
+| `/ui`                     | The props of a page, a card and an entity view; hooks for the package, its methods, its settings, the house, its areas, its past and its pictures, the viewer, the theme, its strings; navigation inside the package's page and the platform's. |
+| `/sun`                    | Where the sun is at any moment, by the platform's own formulas.                                                                                                                                                                                 |
+| `/components`             | The part of the interface's design system a package may draw with.                                                                                                                                                                              |
+| `/vite`                   | `nebula()`, the Vite plugin that builds both halves: the interface in chunks with its CSS scoped to the package, the server bundled whole.                                                                                                      |
+| `/testing`                | `createTestContext()`: run `start` in a unit test, every effect recorded.                                                                                                                                                                       |
+| `/styles.css`             | The interface's Tailwind tokens, to `@reference`.                                                                                                                                                                                               |
 
 The `nebulahome-package` command checks, builds and packs a package:
 

package/dist/chunks/context.d.ts

@@ -1,4 +1,5 @@
 import { G as CapabilityState, V as CapabilityCommand, X as EntityStateClass, Y as DeclaredCapabilities, a as SettingsOf, ct as EntityDomain, d as EntityTypeDefinition, et as ReportedCapabilityState, f as ValuesOf, i as SettingsDefinition, lt as EntityId, r as JsonValue, s as ArgsOf, t as JsonObject, u as CommandsOf } from "./json.js";
+import { a as TelemetryResolution, i as TelemetryPoint, n as HistorySeries, r as StateHistoryPoint } from "./history.js";
 //#region src/schema.d.ts
 /**
  * What checks a value that crosses into a package - a method's input, a service's answer: any
@@ -163,6 +164,28 @@ type EntityFilter = {
   readonly domain?: EntityDomain;
   readonly entityIds?: readonly EntityId[];
 };
+/** Which entities' past `ctx.history` reads, over which window. Since 1.2. */
+type HistoryRead = {
+  /** At most 64. */
+  readonly entityIds: readonly EntityId[];
+  /** Inclusive: a `Date` or ISO 8601. */
+  readonly from: Date | string;
+  /** Exclusive. */
+  readonly to: Date | string;
+  /** The most points of one entity, at most 10 000 (the default): the newest are kept. */
+  readonly limit?: number;
+};
+/** Which entities' readings `ctx.history.telemetry` reads: `auto` picks by the window's length. */
+type TelemetryRead = HistoryRead & {
+  readonly resolution?: TelemetryResolution | 'auto';
+};
+/** What a read of the past found. */
+type HistoryAnswer<TPoint> = {
+  /** Each entity's points, oldest first. */
+  readonly series: HistorySeries<TPoint>;
+  /** The entities whose window held more than the limit: their oldest points are gone. */
+  readonly truncated: readonly EntityId[];
+};
 /** Who may call a method: whoever may read packages, or whoever may configure them. */
 type RpcAccess = 'read' | 'configure';
 /** Who called a method of the package's interface. */
@@ -354,6 +377,28 @@ type ServerContext<TSettings = undefined> = {
      */
     readonly subscribe: (filter: EntityFilter, handler: (change: StateChange) => Awaitable<void>) => Unsubscribe;
   };
+  /**
+   * The past of the house's entities, read only, with the house's authority as `entities` has.
+   * Since 1.2.
+   */
+  readonly history: {
+    /**
+     * The recorded changes of some entities over a window.
+     *
+     * @param read - Which entities, which window, how many points each at most.
+     * @returns Each entity's changes, oldest first.
+     */
+    readonly states: (read: HistoryRead) => Promise<HistoryAnswer<StateHistoryPoint>>;
+    /**
+     * The numeric readings of some entities over a window, raw or in buckets.
+     *
+     * @param read - Which entities, which window, which resolution.
+     * @returns Each entity's readings, oldest first, and the resolution read.
+     */
+    readonly telemetry: (read: TelemetryRead) => Promise<HistoryAnswer<TelemetryPoint> & {
+      readonly resolution: TelemetryResolution;
+    }>;
+  };
   readonly rpc: {
     /** Registers a method its interface calls; a name registered twice throws. */
     readonly method: RpcMethod;
@@ -366,4 +411,4 @@ type ServerContext<TSettings = undefined> = {
   };
 };
 //#endregion
-export { StandardSchemaV1 as A, StateChange as C, Schema as D, SafeParser as E, SchemaIssue as O, SettingsChange as S, Unsubscribe as T, ServerContext as _, CustomEntityInput as a, ServiceCallFunction as b, EntityInput as c, Logger as d, ReportOptions as f, RpcMethod as g, RpcCaller as h, CustomEntities as i, StandardResult as k, EntitySnapshot as l, RpcCall as m, CapabilityEntityInput as n, DeviceInput as o, RpcAccess as p, CustomCommand as r, EntityFilter as s, Awaitable as t, LogMethod as u, ServerSettings as v, SyncResult as w, ServiceProvide as x, ServiceCall as y };
+export { Schema as A, ServiceProvide as C, TelemetryRead as D, SyncResult as E, StandardResult as M, StandardSchemaV1 as N, Unsubscribe as O, ServiceCallFunction as S, StateChange as T, RpcCaller as _, CustomEntityInput as a, ServerSettings as b, EntityInput as c, HistoryRead as d, LogMethod as f, RpcCall as g, RpcAccess as h, CustomEntities as i, SchemaIssue as j, SafeParser as k, EntitySnapshot as l, ReportOptions as m, CapabilityEntityInput as n, DeviceInput as o, Logger as p, CustomCommand as r, EntityFilter as s, Awaitable as t, HistoryAnswer as u, RpcMethod as v, SettingsChange as w, ServiceCall as x, ServerContext as y };

package/dist/chunks/history.d.ts

@@ -0,0 +1,39 @@
+import { G as CapabilityState, lt as EntityId, t as JsonObject } from "./json.js";
+//#region src/history.d.ts
+/** How finely readings are read: every one, or a bucket of a minute, an hour or a day. */
+type TelemetryResolution = 'raw' | '1m' | '1h' | '1d';
+/** What caused a change, when the platform knows it. */
+type ChangeCause = {
+  readonly type: 'automation' | 'scene' | 'user' | 'device' | 'alias' | 'startup';
+  /** Which run, scene or person; absent for a device and at startup. */
+  readonly id?: string;
+};
+/** One change of an entity's state. */
+type StateHistoryPoint = {
+  /** When it changed, ISO 8601. */
+  readonly time: string;
+  /** What it became. */
+  readonly state: CapabilityState;
+  /** What it was; null for the first report the platform recorded. */
+  readonly previousState: CapabilityState | null;
+  readonly attributes: JsonObject;
+  readonly isAvailable: boolean;
+  /** Which package, integration or engine reported it. */
+  readonly source: string;
+  readonly cause?: ChangeCause;
+};
+/** One reading, or one bucket of readings. */
+type TelemetryPoint = {
+  /** The reading's time, or the bucket's start, ISO 8601. */
+  readonly time: string;
+  /** The reading, or the bucket's average. */
+  readonly value: number;
+  /** A bucket's lowest, highest and how many readings it holds; absent for raw readings. */
+  readonly min?: number;
+  readonly max?: number;
+  readonly count?: number;
+};
+/** Each entity's points, oldest first: an entity never recorded, or not readable, has none. */
+type HistorySeries<TPoint> = Readonly<Record<EntityId, readonly TPoint[]>>;
+//#endregion
+export { TelemetryResolution as a, TelemetryPoint as i, HistorySeries as n, StateHistoryPoint as r, ChangeCause as t };

package/dist/chunks/host.js

@@ -23,15 +23,16 @@ function hostSdkVersion() {
 	return typeof version === "string" ? version : void 0;
 }
 /**
-* One member of a module the interface lends.
+* One member of a module the interface lends, when it lends it.
+*
+* For a member with a way of its own to do without the interface - `useTranslation` says the
+* English - where {@link hostMember} would refuse.
 *
 * @param module - The module's key.
 * @param name - The member.
-* @param since - The SDK version that added it.
-* @returns The interface's implementation of it.
-* @throws {Error} When there is no interface, or it does not implement the member.
+* @returns The interface's implementation of it, or undefined when there is none.
 */
-function hostMember(module, name, since) {
+function lentMember(module, name) {
 	const nebula = Reflect.get(globalThis, "__nebula");
 	const modules = isRecord(nebula) ? nebula["modules"] : void 0;
 	const lent = isRecord(modules) ? modules[module] : void 0;
@@ -45,9 +46,22 @@ function hostMember(module, name, since) {
 	* @returns True when it can be called or drawn.
 	*/
 	const isLent = (value) => typeof value === "function" || isRecord(value) && "$$typeof" in value;
-	if (isLent(member)) return member;
+	return isLent(member) ? member : void 0;
+}
+/**
+* One member of a module the interface lends.
+*
+* @param module - The module's key.
+* @param name - The member.
+* @param since - The SDK version that added it.
+* @returns The interface's implementation of it.
+* @throws {Error} When there is no interface, or it does not implement the member.
+*/
+function hostMember(module, name, since) {
+	const member = lentMember(module, name);
+	if (member !== void 0) return member;
 	const version = hostSdkVersion();
 	throw new Error(version === void 0 ? `${name} is lent by the NebulaHome interface, and there is none here` : `${name} needs package SDK ${since}; this interface implements ${version}`);
 }
 //#endregion
-export { UI_MODULE as n, hostMember as r, COMPONENTS_MODULE as t };
+export { lentMember as i, UI_MODULE as n, hostMember as r, COMPONENTS_MODULE as t };

package/dist/chunks/json.d.ts

@@ -33,7 +33,7 @@ declare function isEntityId(value: unknown): value is EntityId;
 //#region src/capabilities.d.ts
 /** Every capability an entity may declare. */
 type CapabilityName = 'on_off' | 'level' | 'color_hs' | 'color_temp' | 'cover' | 'lock' | 'thermostat' | 'sensor_numeric' | 'sensor_binary' | 'sensor_text' | 'media_player' | 'camera' | 'button' | 'update' | 'lawn_mower' | 'select' | 'number' | 'vacuum' | 'image' | 'custom';
-/** How a sensor's readings add up: Home Assistant's state classes, for statistics. */
+/** How a sensor's readings add up, for statistics: a reading, a running total, or a meter. */
 type EntityStateClass = 'measurement' | 'total' | 'total_increasing';
 /** The modes a thermostat may be set to. */
 type ThermostatMode = 'off' | 'heat' | 'cool' | 'auto' | 'fan_only' | 'dry';

package/dist/chunks/node-build.js

@@ -1,7 +1,7 @@
 import { t as PackageConfigError } from "./node-problems.js";
-import { a as isRecord$1, b as strictObject, i as generatePackage, l as packageIdSchema, n as keepingNodeEnv, r as RELEASE_PATHS, u as DEPENDENCY_ID_PATTERN, x as string, y as record } from "./node-config.js";
+import { a as isRecord$1, b as strictObject, i as generatePackage, l as DEPENDENCY_ID_PATTERN, n as keepingNodeEnv, p as packageIdSchema, r as RELEASE_PATHS, x as string, y as record } from "./node-config.js";
 import { createRequire } from "node:module";
-import { copyFile, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build, resolveConfig, runnerImport } from "vite";
 //#region \0rolldown/runtime.js
@@ -6850,7 +6850,143 @@ function composeFileProblems(text, settingKeys) {
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.0.1";
+const SDK_VERSION = "1.2.0";
+//#endregion
+//#region src/vite/catalogues.ts
+/**
+* A package's translation catalogues: `locales/<language>.json` beside `nebula.config.ts`
+* (PACKAGES_DOCS.md 6.5).
+*
+* Each is a JSON object of strings, nested as the keys are dotted - `{ "clients": { "title":
+* "Client" } }` for `t('clients.title', 'Clients')` - with i18next's plural suffixes (`_one`,
+* `_many`, `_other`) and `{{placeholders}}`. The build bundles each as a chunk of the interface,
+* loaded only for a viewer who reads that language; English needs no file, being the strings'
+* own fallback.
+*/
+/** The folder the catalogues are in, beside the config. */
+const LOCALES_FOLDER = "locales";
+/** A language tag a catalogue may be named by: `it`, `pt-BR`, `zh-Hant`. */
+const LANGUAGE_TAG = /^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|\d{3}))?$/;
+/** The plural suffixes i18next reads. */
+const PLURAL_SUFFIX = /_(?:zero|one|two|few|many|other)$/;
+/**
+* The catalogues beside a config, by file name: whether they hold together is
+* {@link catalogueProblems}'s to say.
+*
+* @param configDirectory - The folder of `nebula.config.ts`.
+* @returns Them, ordered by language; none when there is no `locales` folder.
+*/
+async function findCatalogues(configDirectory) {
+	const folder = path.join(configDirectory, LOCALES_FOLDER);
+	let names;
+	try {
+		names = await readdir(folder);
+	} catch {
+		return [];
+	}
+	return names.filter((name) => name.endsWith(".json")).map((name) => ({
+		language: name.slice(0, -5),
+		file: path.join(folder, name)
+	})).sort((left, right) => left.language.localeCompare(right.language));
+}
+/**
+* The catalogues whose name is a language: the ones the interface is given.
+*
+* @param catalogues - The catalogues found.
+* @returns The ones it can load.
+*/
+function namedCatalogues(catalogues) {
+	return catalogues.filter((catalogue) => LANGUAGE_TAG.test(catalogue.language));
+}
+/**
+* The keys of a catalogue, dotted, plural suffixes left on.
+*
+* @param value - The catalogue, or a part of it.
+* @param prefix - The key of the part.
+* @param problems - Where what does not hold is said.
+* @returns The keys.
+*/
+function keysOf(value, prefix, problems) {
+	if (typeof value === "string") return [prefix];
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		problems.push(`${prefix === "" ? "the catalogue" : prefix}: is not a string or an object of strings`);
+		return [];
+	}
+	return Object.entries(value).flatMap(([name, child]) => {
+		if (name === "" || name.includes(".")) {
+			problems.push(`${prefix === "" ? "" : `${prefix}.`}${name}: a key has no dots of its own - nest it instead`);
+			return [];
+		}
+		return keysOf(child, prefix === "" ? name : `${prefix}.${name}`, problems);
+	});
+}
+/**
+* Reads a catalogue's keys.
+*
+* @param file - The catalogue.
+* @returns Its keys, and what is wrong with it.
+*/
+async function readCatalogue(file) {
+	const problems = [];
+	if ((await stat(file)).size > 262144) return {
+		keys: [],
+		problems: ["a catalogue is at most 256 KB"]
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(file, "utf8"));
+	} catch {
+		return {
+			keys: [],
+			problems: ["is not JSON"]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		keys: [],
+		problems: ["is not an object of strings"]
+	};
+	const keys = keysOf(parsed, "", problems);
+	const plurals = new Set(keys.filter((key) => PLURAL_SUFFIX.test(key)).map((key) => key.replace(PLURAL_SUFFIX, "")));
+	for (const base of plurals) if (!keys.includes(`${base}_other`)) problems.push(`${base}: a plural needs its _other form`);
+	return {
+		keys,
+		problems
+	};
+}
+/**
+* What is wrong with a package's catalogues, file by file.
+*
+* @param catalogues - The catalogues found.
+* @param configDirectory - The folder of `nebula.config.ts`, for the names said.
+* @returns The problems; none when they hold together.
+*/
+async function catalogueProblems(catalogues, configDirectory) {
+	const problems = [];
+	for (const catalogue of catalogues) {
+		const name = path.relative(configDirectory, catalogue.file).replaceAll("\\", "/");
+		if (!LANGUAGE_TAG.test(catalogue.language)) {
+			problems.push(`${name}: is not named by a language, as it.json or pt-BR.json`);
+			continue;
+		}
+		const { problems: found } = await readCatalogue(catalogue.file);
+		problems.push(...found.map((problem) => `${name}: ${problem}`));
+	}
+	return problems;
+}
+/**
+* The strings a catalogue lacks and the keys no string uses.
+*
+* @param used - The keys the interface's code says, as `t('key', …)`.
+* @param keys - The catalogue's keys, plural suffixes left on.
+* @returns What is missing and what is left over, each ordered.
+*/
+function catalogueCoverage(used, keys) {
+	const present = new Set(keys.map((key) => key.replace(PLURAL_SUFFIX, "")));
+	return {
+		missing: [...used].filter((key) => !present.has(key)).sort(),
+		unknown: [...present].filter((key) => !used.has(key)).sort()
+	};
+}
 //#endregion
 //#region src/vite/load.ts
 /**
@@ -12735,8 +12871,9 @@ function sharedModuleCode(source) {
 * `nebula()`: the Vite plugin that builds a package's two halves (PACKAGES_DOCS.md 8.1).
 *
 * - **The interface** (`vite build`): one entry generated from the components bound in
-*   `nebula.config.ts`, one chunk per component, React read from the interface, the stylesheet
-*   scoped to the package's own elements; into `<outDir>/ui/`.
+*   `nebula.config.ts`, one chunk per component and per translation catalogue, React read from
+*   the interface, the stylesheet scoped to the package's own elements; into `<outDir>/ui/`. What
+*   each catalogue lacks of the strings the code says is reported, never refused.
 * - **The server** (`vite build --ssr`): the config's `server` module with every dependency inside
 *   it, for Node 22, into one `<outDir>/server/index.js`. The config's loaders are emptied there,
 *   and an import of `/ui` or `/components` refused: the interface is never part of the server.
@@ -12749,16 +12886,24 @@ const PLUGIN_NAME = "nebulahome:package";
 const UI_ENTRY = "virtual:nebulahome/ui";
 /** An import of a module, as the config's loaders are written: `import('./card.js')`. */
 const DYNAMIC_IMPORT = /\bimport\(\s*(['"`])[^'"`]+\1\s*\)/g;
+/**
+* A string the interface's code says, as `t('clients.title', …)`: a literal key, the way the
+* catalogues can be checked against it.
+*/
+const SAID_KEY = /\bt\(\s*(['"`])([\w.-]+)\1\s*,/g;
+/** The package's own modules, which say its strings: not its dependencies. */
+const OWN_MODULE = /^(?!.*[\\/]node_modules[\\/]).*\.[cm]?[jt]sx?$/;
 /** The SDK's entry points that belong to the interface. */
 const INTERFACE_ENTRIES = ["@nebulahome/package-sdk/ui", "@nebulahome/package-sdk/components"];
 /**
-* The code of the interface's entry: the components the config binds, as the interface reads
-* them.
+* The code of the interface's entry: the components the config binds, and a loader per
+* translation catalogue, as the interface reads them.
 *
 * @param configPath - The config's path.
+* @param catalogues - The catalogues, by language.
 * @returns The module.
 */
-function uiEntryCode(configPath) {
+function uiEntryCode(configPath, catalogues) {
 	return [
 		`import definition from ${JSON.stringify(configPath.replaceAll("\\", "/"))};`,
 		"const ui = definition.ui ?? {};",
@@ -12768,6 +12913,9 @@ function uiEntryCode(configPath) {
 		"  page: ui.page?.component,",
 		"  cards: ui.cards ?? {},",
 		"  entityViews: ui.entityViews ?? {},",
+		"  locales: {",
+		...catalogues.map((catalogue) => `    ${JSON.stringify(catalogue.language)}: () => import(${JSON.stringify(catalogue.file.replaceAll("\\", "/"))}),`),
+		"  },",
 		"};"
 	].join("\n");
 }
@@ -12802,7 +12950,9 @@ function nebula(options = {}) {
 				state = {
 					side: "server",
 					configPath,
-					packageId
+					packageId,
+					catalogues: [],
+					said: /* @__PURE__ */ new Set()
 				};
 				return {
 					build: {
@@ -12830,7 +12980,9 @@ function nebula(options = {}) {
 			state = {
 				side: "ui",
 				configPath,
-				packageId
+				packageId,
+				catalogues: namedCatalogues(await findCatalogues(path.dirname(configPath))),
+				said: /* @__PURE__ */ new Set()
 			};
 			return {
 				base: "./",
@@ -12884,23 +13036,42 @@ function nebula(options = {}) {
 		*/
 		load(id) {
 			if (state === void 0) return null;
-			if (id === `\0${UI_ENTRY}`) return uiEntryCode(state.configPath);
+			if (id === `\0${UI_ENTRY}`) return uiEntryCode(state.configPath, state.catalogues);
 			return id.startsWith("\0nebula-shared:") ? sharedModuleCode(id.slice(15)) : null;
 		},
 		/**
 		* Empties the config's loaders in the server: they load components the server never draws.
+		* In the interface, notes the keys the package's own code says, for the catalogues' report.
 		*
 		* @param code - The module's code.
 		* @param id - The module.
 		* @returns The code without them, or null to leave it.
 		*/
 		transform(code, id) {
+			if (state?.side === "ui") {
+				if (OWN_MODULE.test(id)) for (const match of code.matchAll(SAID_KEY)) state.said.add(match[2] ?? "");
+				return null;
+			}
 			if (state?.side !== "server" || path.resolve(id) !== state.configPath) return null;
 			return {
 				code: code.replace(DYNAMIC_IMPORT, "Promise.resolve(undefined)"),
 				map: null
 			};
 		},
+		/**
+		* Says, per catalogue, the strings it lacks and the keys no string uses: English stands in
+		* for the first, and the second are left over from strings that changed.
+		*/
+		async closeBundle() {
+			if (state?.side !== "ui") return;
+			for (const catalogue of state.catalogues) {
+				const { keys } = await readCatalogue(catalogue.file);
+				const { missing, unknown } = catalogueCoverage(state.said, keys);
+				const name = `locales/${catalogue.language}.json`;
+				if (missing.length > 0) this.warn(`${name}: ${String(missing.length)} of ${String(state.said.size)} strings are said in English (${missing.join(", ")})`);
+				if (unknown.length > 0) this.warn(`${name}: no string says ${unknown.join(", ")}`);
+			}
+		},
 		generateBundle: {
 			order: "post",
 			/**
@@ -12976,8 +13147,8 @@ async function pluginOptions(root, logLevel) {
 	};
 }
 /**
-* Checks a package without building it: its declaration against the platform's schemas, and the
-* files it names.
+* Checks a package without building it: its declaration against the platform's schemas, the
+* files it names, and its translation catalogues.
 *
 * @param options - Where the package is.
 * @returns The package, checked.
@@ -13003,6 +13174,7 @@ async function checkPackage(options = {}) {
 		if (Buffer.byteLength(text) > COMPOSE_LIMIT) missing.push(`${compose.from}: a compose file is at most 64 KB`);
 		else missing.push(...composeFileProblems(text, settingKeysOf(generated.setup)).map((problem) => `${compose.from}: ${problem}`));
 	}
+	missing.push(...await catalogueProblems(await findCatalogues(base), base));
 	if (missing.length > 0) throw new PackageConfigError(missing);
 	return {
 		root,