@nebulahome/package-sdk 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.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,47 @@ 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.
+
 ## 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, 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, its strings; navigation inside the package's page and the platform's. |
+| `/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/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/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 { 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.1.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,

package/dist/chunks/version.js

@@ -7,6 +7,6 @@
 * 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.1.0";
 //#endregion
 export { SDK_VERSION as t };

package/dist/ui.d.ts

@@ -128,6 +128,27 @@ type Locale = {
   readonly locale: string;
   readonly timeZone: string;
 };
+/** A plural's English: the form for one, and the form for any other number. */
+type PluralEnglish = {
+  readonly one: string;
+  readonly other: string;
+};
+/** What fills a string's `{{placeholders}}`; `count` also picks a plural's form. */
+type TranslationValues = Readonly<Record<string, string | number>>;
+/**
+ * Says one of the package's strings in the viewer's language.
+ *
+ * The key is looked up in the package's catalogue for that language (`locales/it.json`); when it
+ * is not there, the English given here is said instead. A plural takes its English as
+ * `{ one, other }` and the number as `count`: each language's catalogue holds the forms it needs.
+ */
+type Translate = (key: string, english: string | PluralEnglish, values?: TranslationValues) => string;
+/** The package's strings, in the viewer's language. */
+type Translation = {
+  readonly t: Translate;
+  /** The language they are said in, `it`: the viewer's, whether or not the package has it. */
+  readonly locale: string;
+};
 /** Which theme the interface draws in. */
 type Theme = {
   readonly scheme: 'light' | 'dark';
@@ -185,6 +206,8 @@ type UiHost = {
   readonly usePackageSettings: <TSettings extends SettingsDefinition | undefined = undefined>(settings?: TSettings) => PackageSettings<TSettings>;
   readonly useViewer: () => Viewer;
   readonly useLocale: () => Locale;
+  /** Since 1.1. */
+  readonly useTranslation: () => Translation;
   readonly useTheme: () => Theme;
   readonly usePortalContainer: () => HTMLElement | null;
   readonly usePackageRoute: () => PackageRoute;
@@ -272,6 +295,17 @@ export declare function useViewer(): Viewer;
  * @returns Them, for `Intl`.
  */
 export declare function useLocale(): Locale;
+/**
+ * The package's strings in the viewer's language, from the catalogues in its `locales` folder
+ * (PACKAGES_DOCS.md 6.5).
+ *
+ * `t('clients.title', 'Clients')` says the key from the viewer's catalogue, and its English when
+ * the catalogue lacks it; outside an interface that lends this - a component's unit test - every
+ * string is its English.
+ *
+ * @returns `t`, and the language it speaks.
+ */
+export declare function useTranslation(): Translation;
 /**
  * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
  *
@@ -317,4 +351,4 @@ export declare function PackageLink(props: PackageLinkProps): ReactElement;
  */
 export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
 //#endregion
-export type { CardProps, CustomEntityState, EntitiesFilter, EntityView, EntityViewProps, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PlatformLinkProps, PlatformNavigate, PlatformTarget, RpcOptions, RpcState, SendCommand, SettingsPatch, Theme, UiHost, Viewer, VisibleSettings };
+export type { CardProps, CustomEntityState, EntitiesFilter, EntityView, EntityViewProps, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageProps, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, Theme, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -1,5 +1,45 @@
-import { n as UI_MODULE, r as hostMember } from "./chunks/host.js";
+import { i as lentMember, n as UI_MODULE, r as hostMember } from "./chunks/host.js";
 import { createElement } from "react";
+//#region src/ui/english.ts
+/** A `{{placeholder}}`, as i18next writes it. */
+const PLACEHOLDER = /\{\{\s*(\w+)\s*\}\}/g;
+/**
+* Fills a string's placeholders.
+*
+* @param text - The string.
+* @param values - What fills them; a placeholder with no value is left as written.
+* @returns The string, filled.
+*/
+function interpolate(text, values) {
+	return text.replaceAll(PLACEHOLDER, (whole, name) => {
+		const value = values?.[name];
+		return value === void 0 ? whole : String(value);
+	});
+}
+/**
+* Says a string's English, its plural form chosen by `count`.
+*
+* @param english - The English, or a plural's two forms.
+* @param values - What fills it.
+* @returns The English, filled.
+*/
+function englishOf(english, values) {
+	return interpolate(typeof english === "string" ? english : values?.["count"] === 1 ? english.one : english.other, values);
+}
+/** The package's strings in English. */
+const ENGLISH = {
+	/**
+	* Says a string's English.
+	*
+	* @param key - Its key, unused: there is no catalogue here.
+	* @param english - Its English.
+	* @param values - What fills it.
+	* @returns The English, filled.
+	*/
+	t: (key, english, values) => englishOf(english, values),
+	locale: "en"
+};
+//#endregion
 //#region src/ui/index.ts
 /**
 * `@nebulahome/package-sdk/ui`: what a package's page, cards and entity views are written with
@@ -119,6 +159,20 @@ function useLocale() {
 	return ui("useLocale", "1.0")();
 }
 /**
+* The package's strings in the viewer's language, from the catalogues in its `locales` folder
+* (PACKAGES_DOCS.md 6.5).
+*
+* `t('clients.title', 'Clients')` says the key from the viewer's catalogue, and its English when
+* the catalogue lacks it; outside an interface that lends this - a component's unit test - every
+* string is its English.
+*
+* @returns `t`, and the language it speaks.
+*/
+function useTranslation() {
+	const lent = lentMember(UI_MODULE, "useTranslation");
+	return lent === void 0 ? ENGLISH : lent();
+}
+/**
 * The theme the interface draws in, for what draws its own colours: a canvas, a chart.
 *
 * @returns Light or dark.
@@ -177,4 +231,4 @@ function PlatformLink(props) {
 	return createElement(ui("PlatformLink", "1.0"), props);
 }
 //#endregion
-export { PackageLink, PlatformLink, useCommand, useCustomEntity, useEntities, useEntity, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useTheme, useViewer };
+export { PackageLink, PlatformLink, useCommand, useCustomEntity, useEntities, useEntity, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useTheme, useTranslation, useViewer };

package/dist/vite.d.ts

@@ -52,8 +52,8 @@ type CheckedPackage = {
   readonly generated: GeneratedPackage;
 };
 /**
- * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -96,10 +96,10 @@
     "vitest": "^4.1.11",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@nebulahome/eslint-config": "0.0.0",
-    "@nebulahome/tsconfig": "0.0.0",
     "@nebulahome/contracts": "0.0.0",
-    "@nebulahome/ui": "0.0.0"
+    "@nebulahome/tsconfig": "0.0.0",
+    "@nebulahome/ui": "0.0.0",
+    "@nebulahome/eslint-config": "0.0.0"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",