@saasicat/ui-vue 0.15.1 → 0.17.0

package/README.md

@@ -15,12 +15,12 @@ The package is layered so that each entry only loads what it names.
 Lower layers never import upward; ESLint (`no-restricted-imports`, repo
 root config) enforces the boundaries in CI.
 
-| Entry | Source | May import | Contents |
-| --- | --- | --- | --- |
-| `@saasicat/ui-vue/client` | `src/client/` | `@saasicat/types` only | Framework-free core: `BootLoader`, `ManifestLoader` (ETag cache), nav builder, action registry, batch column fetcher, `HttpClient`/`KvStore` contract. Usable from any framework or plain Node/TypeScript. |
-| `@saasicat/ui-vue` (main) | `src/vue/` (+ client re-exports) | Vue, `vue-router`, Pinia — **no Quasar** | Composables (`useTenants`, `usePlanEditor`, …), router guards, injection keys + shell contract, notify-port type, optional Pinia store factory. |
-| `@saasicat/ui-vue/quasar` | `src/quasar/` | everything above + Quasar | `createSuperAdminApp()` bootstrap and the Quasar notify-port implementation. |
-| `@saasicat/ui-vue/pages-standard/*`, `/pages-tenant/*`, `/components/*` | SFC directories | everything | The Quasar reference UI, shipped as raw `.vue` from `src/` (compiled by the consumer's Vite). |
+| Entry                                                                   | Source                           | May import                               | Contents                                                                                                                                                                                                   |
+| ----------------------------------------------------------------------- | -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@saasicat/ui-vue/client`                                               | `src/client/`                    | `@saasicat/types` only                   | Framework-free core: `BootLoader`, `ManifestLoader` (ETag cache), nav builder, action registry, batch column fetcher, `HttpClient`/`KvStore` contract. Usable from any framework or plain Node/TypeScript. |
+| `@saasicat/ui-vue` (main)                                               | `src/vue/` (+ client re-exports) | Vue, `vue-router`, Pinia — **no Quasar** | Composables (`useTenants`, `usePlanEditor`, …), router guards, injection keys + shell contract, notify-port type, optional Pinia store factory.                                                            |
+| `@saasicat/ui-vue/quasar`                                               | `src/quasar/`                    | everything above + Quasar                | `createSuperAdminApp()` bootstrap and the Quasar notify-port implementation.                                                                                                                               |
+| `@saasicat/ui-vue/pages-standard/*`, `/pages-tenant/*`, `/components/*` | SFC directories                  | everything                               | The Quasar reference UI, shipped as raw `.vue` from `src/` (compiled by the consumer's Vite).                                                                                                              |
 
 Rules of thumb when contributing:
 
@@ -49,7 +49,7 @@ createSuperAdminApp({
 ```
 
 Confirm dialogs inside the reference pages intentionally keep using Quasar's
-`Dialog` — the pages *are* the Quasar layer.
+`Dialog` — the pages _are_ the Quasar layer.
 
 ## Usage
 
@@ -92,9 +92,12 @@ createSuperAdminApp({
 });
 ```
 
-Pass a `Ref<SaLocale>` instead of a literal to switch at runtime, and
-`i18n.overrides` to replace individual strings per locale. Components read the
-catalog via `useSaMessages('<namespace>')` / `useSuperAdminI18n()`.
+Users switch languages themselves through the shell's `LocaleSwitcher` (header
+and login page); the pick is remembered. Which languages an app offers is its
+own call: `i18n.locales` narrows the set, `i18n.additionalLocales` adds
+languages the platform does not ship, `i18n.overrides` replaces individual
+strings, and `i18n.switcher: false` drops the control entirely. Components read
+the catalog via `useSaMessages('<namespace>')` / `useSuperAdminI18n()`.
 See [handbook §8.6](https://github.com/uelker70/saasicat/blob/main/docs/handbook.md#86-ui-language-i18n).
 
 ## Build

package/dist/{messages-BIYw32u1.d.ts → catalog-C4Gv2_KM.d.cts}

@@ -1,4 +1,4 @@
-import { AdminManifest, TenantActionDef, StandardPageKey } from '@saasicat/types';
+import { StandardPageKey, AdminManifest, TenantActionDef } from '@saasicat/types';
 
 /**
  * Minimal abstraction over `fetch`. Consumers may pass their own
@@ -25,8 +25,11 @@ interface KvStore {
     remove(key: string): void;
 }
 /**
- * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
- * Tests may pass an in-memory stub.
+ * Returns a `KvStore` wrapper around `localStorage`, or a no-op store when the
+ * environment has none or refuses access. Tests may pass an in-memory stub.
+ *
+ * Every persistence built on this is a convenience — losing it must never take
+ * the app down, so no failure mode is allowed to escape.
  */
 declare function defaultKvStore(): KvStore;
 /**
@@ -35,11 +38,49 @@ declare function defaultKvStore(): KvStore;
  */
 declare function defaultHttpClient(): HttpClient;
 
-type SaLocale = 'de' | 'en';
-declare const SA_LOCALES: readonly SaLocale[];
-declare const DEFAULT_SA_LOCALE: SaLocale;
-/** BCP-47 tags used for `Intl`/`toLocaleString` formatting per UI locale. */
-declare const SA_INTL_LOCALES: Record<SaLocale, string>;
+/** Locales the platform itself ships a catalog for. */
+type SaBuiltinLocale = 'de' | 'en';
+/**
+ * Any locale the shell can run in: the built-ins plus whatever an app adds via
+ * `i18n.additionalLocales`. The `string & {}` arm keeps autocompletion for the
+ * built-ins while leaving the set open.
+ */
+type SaLocale = SaBuiltinLocale | (string & {});
+/** The locales the platform ships. Apps narrow or extend this, see `i18n`. */
+declare const SA_LOCALES: readonly SaBuiltinLocale[];
+declare const DEFAULT_SA_LOCALE: SaBuiltinLocale;
+/** BCP-47 tags used for `Intl`/`toLocaleString` formatting per built-in locale. */
+declare const SA_INTL_LOCALES: Record<SaBuiltinLocale, string>;
+/**
+ * Names for the language switcher. Endonyms — a language is listed in its own
+ * language, so the entries stay readable no matter which locale is active and
+ * never need translating.
+ */
+declare const SA_LOCALE_LABELS: Record<SaBuiltinLocale, string>;
+/** Narrows untrusted input to a locale the platform ships a catalog for. */
+declare function isSaBuiltinLocale(value: unknown): value is SaBuiltinLocale;
+/**
+ * The built-in catalog a locale reads from. Helper modules that index the raw
+ * catalogs (rather than the resolved one from `useSaMessages`) need this: a
+ * language an app added has no entry there, and indexing it would yield
+ * `undefined` and take the page down.
+ *
+ * Strings resolved this way stay in the fallback language for an app-supplied
+ * locale — migrating those helpers to the resolved catalog is tracked
+ * separately.
+ */
+declare function builtinLocaleOf(locale: SaLocale | undefined, fallback?: SaBuiltinLocale): SaBuiltinLocale;
+
+type SaNavMessages = {
+    readonly pages: Record<StandardPageKey, string>;
+    readonly sections: {
+        readonly overview: string;
+        readonly catalog: string;
+        readonly customers: string;
+        readonly system: string;
+    };
+};
+declare const navMessages: Record<SaBuiltinLocale, SaNavMessages>;
 
 /** Consumer implementation; receives the action inputs as a generic object. */
 type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
@@ -104,7 +145,7 @@ type PartialMessages<T> = {
  * Couples the German reference catalog with its English translation. Missing
  * or extra keys in the English object are compile errors.
  */
-declare function defineMessages<T extends MessageTree>(de: T, en: TranslationOf<T>): Record<SaLocale, T>;
+declare function defineMessages<T extends MessageTree>(de: T, en: TranslationOf<T>): Record<SaBuiltinLocale, T>;
 /**
  * Recursively overlays `overrides` onto `base` without mutating either side.
  * Only string leaves are replaced; keys not present in `base` are ignored —
@@ -112,7 +153,7 @@ declare function defineMessages<T extends MessageTree>(de: T, en: TranslationOf<
  */
 declare function mergeMessages<T extends MessageTree>(base: T, overrides: PartialMessages<T> | undefined): T;
 
-declare const auditMessages: Record<SaLocale, {
+declare const auditMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitle: string;
     filterButton: string;
@@ -132,7 +173,7 @@ declare const auditMessages: Record<SaLocale, {
     };
 }>;
 
-declare const bundlesMessages: Record<SaLocale, {
+declare const bundlesMessages: Record<SaBuiltinLocale, {
     fields: {
         masterData: string;
         label: string;
@@ -338,7 +379,7 @@ declare const bundlesMessages: Record<SaLocale, {
     };
 }>;
 
-declare const commonMessages: Record<SaLocale, {
+declare const commonMessages: Record<SaBuiltinLocale, {
     save: string;
     cancel: string;
     close: string;
@@ -409,14 +450,14 @@ declare const commonMessages: Record<SaLocale, {
     noChanges: string;
 }>;
 
-declare const dashboardMessages: Record<SaLocale, {
+declare const dashboardMessages: Record<SaBuiltinLocale, {
     title: string;
     emptyKpiCards: string;
     shortcutsTitle: string;
     deltaVsPreviousPeriod: string;
 }>;
 
-declare const discoveryMessages: Record<SaLocale, {
+declare const discoveryMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitleLead: string;
     subtitleEmphasis: string;
@@ -521,7 +562,7 @@ declare const discoveryMessages: Record<SaLocale, {
     };
 }>;
 
-declare const emailMessages: Record<SaLocale, {
+declare const emailMessages: Record<SaBuiltinLocale, {
     sender: string;
     recipient: string;
     errorAction: string;
@@ -581,7 +622,7 @@ declare const emailMessages: Record<SaLocale, {
     };
 }>;
 
-declare const marketingMessages: Record<SaLocale, {
+declare const marketingMessages: Record<SaBuiltinLocale, {
     topFeatures: string;
     tabs: {
         preview: string;
@@ -710,18 +751,7 @@ declare const marketingMessages: Record<SaLocale, {
     };
 }>;
 
-type NavNamespace = {
-    readonly pages: Record<StandardPageKey, string>;
-    readonly sections: {
-        readonly overview: string;
-        readonly catalog: string;
-        readonly customers: string;
-        readonly system: string;
-    };
-};
-declare const navMessages: Record<SaLocale, NavNamespace>;
-
-declare const pilotsMessages: Record<SaLocale, {
+declare const pilotsMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitleCount: string;
     createAction: string;
@@ -815,7 +845,7 @@ declare const pilotsMessages: Record<SaLocale, {
     };
 }>;
 
-declare const planDetailMessages: Record<SaLocale, {
+declare const planDetailMessages: Record<SaBuiltinLocale, {
     header: {
         noDescription: string;
         nameEditHint: string;
@@ -943,7 +973,7 @@ declare const planDetailMessages: Record<SaLocale, {
     };
 }>;
 
-declare const planEditorMessages: Record<SaLocale, {
+declare const planEditorMessages: Record<SaBuiltinLocale, {
     perMonthShort: string;
     perYearShort: string;
     sections: {
@@ -1028,7 +1058,7 @@ declare const planEditorMessages: Record<SaLocale, {
     };
 }>;
 
-declare const planVersionsMessages: Record<SaLocale, {
+declare const planVersionsMessages: Record<SaBuiltinLocale, {
     compareEnd: string;
     status: {
         draft: string;
@@ -1081,7 +1111,7 @@ declare const planVersionsMessages: Record<SaLocale, {
     };
 }>;
 
-declare const plansMessages: Record<SaLocale, {
+declare const plansMessages: Record<SaBuiltinLocale, {
     page: {
         loading: string;
         toastPlanCreated: string;
@@ -1297,7 +1327,7 @@ declare const plansMessages: Record<SaLocale, {
     };
 }>;
 
-declare const promosMessages: Record<SaLocale, {
+declare const promosMessages: Record<SaBuiltinLocale, {
     title: string;
     createAction: string;
     apiErrorHttpStatus: string;
@@ -1396,7 +1426,7 @@ declare const promosMessages: Record<SaLocale, {
     };
 }>;
 
-declare const shellMessages: Record<SaLocale, {
+declare const shellMessages: Record<SaBuiltinLocale, {
     emailLabel: string;
     passwordLabel: string;
     invalidEmail: string;
@@ -1405,6 +1435,7 @@ declare const shellMessages: Record<SaLocale, {
         subtitle: string;
         roleBadge: string;
         logout: string;
+        language: string;
     };
     drawer: {
         docs: string;
@@ -1464,7 +1495,7 @@ declare const shellMessages: Record<SaLocale, {
     };
 }>;
 
-declare const tenantsMessages: Record<SaLocale, {
+declare const tenantsMessages: Record<SaBuiltinLocale, {
     tenant: string;
     plan: string;
     list: {
@@ -1514,7 +1545,7 @@ declare const tenantsMessages: Record<SaLocale, {
     };
 }>;
 
-declare const usersMessages: Record<SaLocale, {
+declare const usersMessages: Record<SaBuiltinLocale, {
     title: string;
     filterQuery: string;
     filterTenant: string;
@@ -1575,11 +1606,67 @@ type SaMessages = {
 /** Shape of app-side string overrides (deep partial of the catalog). */
 type SaMessagesOverrides = PartialMessages<SaMessages>;
 /** Complete, immutable message catalogs per locale. */
-declare const SA_MESSAGES: Record<SaLocale, SaMessages>;
+declare const SA_MESSAGES: Record<SaBuiltinLocale, SaMessages>;
 /**
  * Returns the platform catalog for `locale`, optionally overlaid with
  * app-side overrides.
  */
-declare function resolveMessages(locale: SaLocale, overrides?: SaMessagesOverrides): SaMessages;
+declare function resolveMessages(locale: SaBuiltinLocale, overrides?: SaMessagesOverrides): SaMessages;
+
+/** A language an app brings along, on top of the two the platform ships. */
+interface SaLocaleDefinition {
+    /**
+     * Name for the switcher, written in the language itself (`'Français'`) —
+     * that way the entry stays readable whatever locale is currently active.
+     */
+    label: string;
+    /** BCP-47 tag for `Intl`/`toLocaleString`, e.g. `'fr-FR'`. */
+    intlLocale: string;
+    /**
+     * Built-in catalog that fills whatever `messages` leaves out, default
+     * `'en'`. A partial translation therefore renders — untranslated keys fall
+     * back instead of showing blanks.
+     */
+    basedOn?: SaBuiltinLocale;
+    /** The translation. Every key is optional; see `basedOn`. */
+    messages: SaMessagesOverrides;
+}
+interface SaCatalogOptions {
+    /**
+     * Locales offered in the switcher, in the order given. Default: the
+     * built-ins plus everything in `additionalLocales`. Narrow it to ship a
+     * single language; entries without a catalog are ignored.
+     */
+    locales?: readonly SaLocale[];
+    /** Languages the app adds, keyed by locale code (`'fr'`, `'pt-BR'`, …). */
+    additionalLocales?: Readonly<Record<string, SaLocaleDefinition>>;
+    /** Per-locale wording changes layered on top of whatever catalog applies. */
+    overrides?: Readonly<Partial<Record<SaLocale, SaMessagesOverrides>>>;
+}
+/** One entry of the switcher. */
+interface SaLocaleOption {
+    code: SaLocale;
+    label: string;
+}
+interface SaCatalog {
+    /** Locales to offer, in switcher order. Never empty. */
+    readonly locales: readonly SaLocaleOption[];
+    /**
+     * Whether the app offers this locale. Deliberately not "can it be
+     * rendered": an app that narrowed to English must not be pushed back into
+     * German by a stored pick from before, even though German is still shipped.
+     */
+    has(locale: SaLocale): boolean;
+    /** Locale to start from when nothing else is known. */
+    readonly defaultLocale: SaLocale;
+    messagesFor(locale: SaLocale): SaMessages;
+    intlLocaleFor(locale: SaLocale): string;
+    labelFor(locale: SaLocale): string;
+}
+/**
+ * Builds the catalog an app runs on. Resolution is cached per locale, so
+ * switching back and forth does not re-merge the message tree.
+ */
+declare function createSaCatalog(options?: SaCatalogOptions): SaCatalog;
 
-export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaMessagesOverrides as b, ActionRegistry as c, ActionDefNotInManifestError as d, type HttpResponse as e, MissingHandlerError as f, SA_INTL_LOCALES as g, SA_LOCALES as h, SA_MESSAGES as i, defaultHttpClient as j, defaultKvStore as k, defineMessages as l, mergeMessages as m, resolveMessages as r };
+export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaLocaleOption as b, type SaLocaleDefinition as c, type SaMessagesOverrides as d, ActionRegistry as e, ActionDefNotInManifestError as f, type HttpResponse as g, MissingHandlerError as h, SA_INTL_LOCALES as i, SA_LOCALES as j, SA_LOCALE_LABELS as k, SA_MESSAGES as l, type SaBuiltinLocale as m, type SaCatalog as n, type SaCatalogOptions as o, builtinLocaleOf as p, createSaCatalog as q, defaultHttpClient as r, defaultKvStore as s, defineMessages as t, isSaBuiltinLocale as u, mergeMessages as v, resolveMessages as w, type SaNavMessages as x };

package/dist/{messages-BIYw32u1.d.cts → catalog-C4Gv2_KM.d.ts}

@@ -1,4 +1,4 @@
-import { AdminManifest, TenantActionDef, StandardPageKey } from '@saasicat/types';
+import { StandardPageKey, AdminManifest, TenantActionDef } from '@saasicat/types';
 
 /**
  * Minimal abstraction over `fetch`. Consumers may pass their own
@@ -25,8 +25,11 @@ interface KvStore {
     remove(key: string): void;
 }
 /**
- * Returns a `KvStore` wrapper around `localStorage` (or `null` under SSR).
- * Tests may pass an in-memory stub.
+ * Returns a `KvStore` wrapper around `localStorage`, or a no-op store when the
+ * environment has none or refuses access. Tests may pass an in-memory stub.
+ *
+ * Every persistence built on this is a convenience — losing it must never take
+ * the app down, so no failure mode is allowed to escape.
  */
 declare function defaultKvStore(): KvStore;
 /**
@@ -35,11 +38,49 @@ declare function defaultKvStore(): KvStore;
  */
 declare function defaultHttpClient(): HttpClient;
 
-type SaLocale = 'de' | 'en';
-declare const SA_LOCALES: readonly SaLocale[];
-declare const DEFAULT_SA_LOCALE: SaLocale;
-/** BCP-47 tags used for `Intl`/`toLocaleString` formatting per UI locale. */
-declare const SA_INTL_LOCALES: Record<SaLocale, string>;
+/** Locales the platform itself ships a catalog for. */
+type SaBuiltinLocale = 'de' | 'en';
+/**
+ * Any locale the shell can run in: the built-ins plus whatever an app adds via
+ * `i18n.additionalLocales`. The `string & {}` arm keeps autocompletion for the
+ * built-ins while leaving the set open.
+ */
+type SaLocale = SaBuiltinLocale | (string & {});
+/** The locales the platform ships. Apps narrow or extend this, see `i18n`. */
+declare const SA_LOCALES: readonly SaBuiltinLocale[];
+declare const DEFAULT_SA_LOCALE: SaBuiltinLocale;
+/** BCP-47 tags used for `Intl`/`toLocaleString` formatting per built-in locale. */
+declare const SA_INTL_LOCALES: Record<SaBuiltinLocale, string>;
+/**
+ * Names for the language switcher. Endonyms — a language is listed in its own
+ * language, so the entries stay readable no matter which locale is active and
+ * never need translating.
+ */
+declare const SA_LOCALE_LABELS: Record<SaBuiltinLocale, string>;
+/** Narrows untrusted input to a locale the platform ships a catalog for. */
+declare function isSaBuiltinLocale(value: unknown): value is SaBuiltinLocale;
+/**
+ * The built-in catalog a locale reads from. Helper modules that index the raw
+ * catalogs (rather than the resolved one from `useSaMessages`) need this: a
+ * language an app added has no entry there, and indexing it would yield
+ * `undefined` and take the page down.
+ *
+ * Strings resolved this way stay in the fallback language for an app-supplied
+ * locale — migrating those helpers to the resolved catalog is tracked
+ * separately.
+ */
+declare function builtinLocaleOf(locale: SaLocale | undefined, fallback?: SaBuiltinLocale): SaBuiltinLocale;
+
+type SaNavMessages = {
+    readonly pages: Record<StandardPageKey, string>;
+    readonly sections: {
+        readonly overview: string;
+        readonly catalog: string;
+        readonly customers: string;
+        readonly system: string;
+    };
+};
+declare const navMessages: Record<SaBuiltinLocale, SaNavMessages>;
 
 /** Consumer implementation; receives the action inputs as a generic object. */
 type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
@@ -104,7 +145,7 @@ type PartialMessages<T> = {
  * Couples the German reference catalog with its English translation. Missing
  * or extra keys in the English object are compile errors.
  */
-declare function defineMessages<T extends MessageTree>(de: T, en: TranslationOf<T>): Record<SaLocale, T>;
+declare function defineMessages<T extends MessageTree>(de: T, en: TranslationOf<T>): Record<SaBuiltinLocale, T>;
 /**
  * Recursively overlays `overrides` onto `base` without mutating either side.
  * Only string leaves are replaced; keys not present in `base` are ignored —
@@ -112,7 +153,7 @@ declare function defineMessages<T extends MessageTree>(de: T, en: TranslationOf<
  */
 declare function mergeMessages<T extends MessageTree>(base: T, overrides: PartialMessages<T> | undefined): T;
 
-declare const auditMessages: Record<SaLocale, {
+declare const auditMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitle: string;
     filterButton: string;
@@ -132,7 +173,7 @@ declare const auditMessages: Record<SaLocale, {
     };
 }>;
 
-declare const bundlesMessages: Record<SaLocale, {
+declare const bundlesMessages: Record<SaBuiltinLocale, {
     fields: {
         masterData: string;
         label: string;
@@ -338,7 +379,7 @@ declare const bundlesMessages: Record<SaLocale, {
     };
 }>;
 
-declare const commonMessages: Record<SaLocale, {
+declare const commonMessages: Record<SaBuiltinLocale, {
     save: string;
     cancel: string;
     close: string;
@@ -409,14 +450,14 @@ declare const commonMessages: Record<SaLocale, {
     noChanges: string;
 }>;
 
-declare const dashboardMessages: Record<SaLocale, {
+declare const dashboardMessages: Record<SaBuiltinLocale, {
     title: string;
     emptyKpiCards: string;
     shortcutsTitle: string;
     deltaVsPreviousPeriod: string;
 }>;
 
-declare const discoveryMessages: Record<SaLocale, {
+declare const discoveryMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitleLead: string;
     subtitleEmphasis: string;
@@ -521,7 +562,7 @@ declare const discoveryMessages: Record<SaLocale, {
     };
 }>;
 
-declare const emailMessages: Record<SaLocale, {
+declare const emailMessages: Record<SaBuiltinLocale, {
     sender: string;
     recipient: string;
     errorAction: string;
@@ -581,7 +622,7 @@ declare const emailMessages: Record<SaLocale, {
     };
 }>;
 
-declare const marketingMessages: Record<SaLocale, {
+declare const marketingMessages: Record<SaBuiltinLocale, {
     topFeatures: string;
     tabs: {
         preview: string;
@@ -710,18 +751,7 @@ declare const marketingMessages: Record<SaLocale, {
     };
 }>;
 
-type NavNamespace = {
-    readonly pages: Record<StandardPageKey, string>;
-    readonly sections: {
-        readonly overview: string;
-        readonly catalog: string;
-        readonly customers: string;
-        readonly system: string;
-    };
-};
-declare const navMessages: Record<SaLocale, NavNamespace>;
-
-declare const pilotsMessages: Record<SaLocale, {
+declare const pilotsMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitleCount: string;
     createAction: string;
@@ -815,7 +845,7 @@ declare const pilotsMessages: Record<SaLocale, {
     };
 }>;
 
-declare const planDetailMessages: Record<SaLocale, {
+declare const planDetailMessages: Record<SaBuiltinLocale, {
     header: {
         noDescription: string;
         nameEditHint: string;
@@ -943,7 +973,7 @@ declare const planDetailMessages: Record<SaLocale, {
     };
 }>;
 
-declare const planEditorMessages: Record<SaLocale, {
+declare const planEditorMessages: Record<SaBuiltinLocale, {
     perMonthShort: string;
     perYearShort: string;
     sections: {
@@ -1028,7 +1058,7 @@ declare const planEditorMessages: Record<SaLocale, {
     };
 }>;
 
-declare const planVersionsMessages: Record<SaLocale, {
+declare const planVersionsMessages: Record<SaBuiltinLocale, {
     compareEnd: string;
     status: {
         draft: string;
@@ -1081,7 +1111,7 @@ declare const planVersionsMessages: Record<SaLocale, {
     };
 }>;
 
-declare const plansMessages: Record<SaLocale, {
+declare const plansMessages: Record<SaBuiltinLocale, {
     page: {
         loading: string;
         toastPlanCreated: string;
@@ -1297,7 +1327,7 @@ declare const plansMessages: Record<SaLocale, {
     };
 }>;
 
-declare const promosMessages: Record<SaLocale, {
+declare const promosMessages: Record<SaBuiltinLocale, {
     title: string;
     createAction: string;
     apiErrorHttpStatus: string;
@@ -1396,7 +1426,7 @@ declare const promosMessages: Record<SaLocale, {
     };
 }>;
 
-declare const shellMessages: Record<SaLocale, {
+declare const shellMessages: Record<SaBuiltinLocale, {
     emailLabel: string;
     passwordLabel: string;
     invalidEmail: string;
@@ -1405,6 +1435,7 @@ declare const shellMessages: Record<SaLocale, {
         subtitle: string;
         roleBadge: string;
         logout: string;
+        language: string;
     };
     drawer: {
         docs: string;
@@ -1464,7 +1495,7 @@ declare const shellMessages: Record<SaLocale, {
     };
 }>;
 
-declare const tenantsMessages: Record<SaLocale, {
+declare const tenantsMessages: Record<SaBuiltinLocale, {
     tenant: string;
     plan: string;
     list: {
@@ -1514,7 +1545,7 @@ declare const tenantsMessages: Record<SaLocale, {
     };
 }>;
 
-declare const usersMessages: Record<SaLocale, {
+declare const usersMessages: Record<SaBuiltinLocale, {
     title: string;
     filterQuery: string;
     filterTenant: string;
@@ -1575,11 +1606,67 @@ type SaMessages = {
 /** Shape of app-side string overrides (deep partial of the catalog). */
 type SaMessagesOverrides = PartialMessages<SaMessages>;
 /** Complete, immutable message catalogs per locale. */
-declare const SA_MESSAGES: Record<SaLocale, SaMessages>;
+declare const SA_MESSAGES: Record<SaBuiltinLocale, SaMessages>;
 /**
  * Returns the platform catalog for `locale`, optionally overlaid with
  * app-side overrides.
  */
-declare function resolveMessages(locale: SaLocale, overrides?: SaMessagesOverrides): SaMessages;
+declare function resolveMessages(locale: SaBuiltinLocale, overrides?: SaMessagesOverrides): SaMessages;
+
+/** A language an app brings along, on top of the two the platform ships. */
+interface SaLocaleDefinition {
+    /**
+     * Name for the switcher, written in the language itself (`'Français'`) —
+     * that way the entry stays readable whatever locale is currently active.
+     */
+    label: string;
+    /** BCP-47 tag for `Intl`/`toLocaleString`, e.g. `'fr-FR'`. */
+    intlLocale: string;
+    /**
+     * Built-in catalog that fills whatever `messages` leaves out, default
+     * `'en'`. A partial translation therefore renders — untranslated keys fall
+     * back instead of showing blanks.
+     */
+    basedOn?: SaBuiltinLocale;
+    /** The translation. Every key is optional; see `basedOn`. */
+    messages: SaMessagesOverrides;
+}
+interface SaCatalogOptions {
+    /**
+     * Locales offered in the switcher, in the order given. Default: the
+     * built-ins plus everything in `additionalLocales`. Narrow it to ship a
+     * single language; entries without a catalog are ignored.
+     */
+    locales?: readonly SaLocale[];
+    /** Languages the app adds, keyed by locale code (`'fr'`, `'pt-BR'`, …). */
+    additionalLocales?: Readonly<Record<string, SaLocaleDefinition>>;
+    /** Per-locale wording changes layered on top of whatever catalog applies. */
+    overrides?: Readonly<Partial<Record<SaLocale, SaMessagesOverrides>>>;
+}
+/** One entry of the switcher. */
+interface SaLocaleOption {
+    code: SaLocale;
+    label: string;
+}
+interface SaCatalog {
+    /** Locales to offer, in switcher order. Never empty. */
+    readonly locales: readonly SaLocaleOption[];
+    /**
+     * Whether the app offers this locale. Deliberately not "can it be
+     * rendered": an app that narrowed to English must not be pushed back into
+     * German by a stored pick from before, even though German is still shipped.
+     */
+    has(locale: SaLocale): boolean;
+    /** Locale to start from when nothing else is known. */
+    readonly defaultLocale: SaLocale;
+    messagesFor(locale: SaLocale): SaMessages;
+    intlLocaleFor(locale: SaLocale): string;
+    labelFor(locale: SaLocale): string;
+}
+/**
+ * Builds the catalog an app runs on. Resolution is cached per locale, so
+ * switching back and forth does not re-merge the message tree.
+ */
+declare function createSaCatalog(options?: SaCatalogOptions): SaCatalog;
 
-export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaMessagesOverrides as b, ActionRegistry as c, ActionDefNotInManifestError as d, type HttpResponse as e, MissingHandlerError as f, SA_INTL_LOCALES as g, SA_LOCALES as h, SA_MESSAGES as i, defaultHttpClient as j, defaultKvStore as k, defineMessages as l, mergeMessages as m, resolveMessages as r };
+export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaLocaleOption as b, type SaLocaleDefinition as c, type SaMessagesOverrides as d, ActionRegistry as e, ActionDefNotInManifestError as f, type HttpResponse as g, MissingHandlerError as h, SA_INTL_LOCALES as i, SA_LOCALES as j, SA_LOCALE_LABELS as k, SA_MESSAGES as l, type SaBuiltinLocale as m, type SaCatalog as n, type SaCatalogOptions as o, builtinLocaleOf as p, createSaCatalog as q, defaultHttpClient as r, defaultKvStore as s, defineMessages as t, isSaBuiltinLocale as u, mergeMessages as v, resolveMessages as w, type SaNavMessages as x };