@saasicat/ui-vue 0.15.1 → 0.17.0

package/dist/index.js

@@ -16,11 +16,14 @@ import {
   createAdminResourceClient,
   defaultSectionOrder,
   getJson,
+  isProductionBoot,
   postJson,
   resolveExtension,
+  resolveLoginBranding,
   trimTrailingSlashes
-} from "./chunk-66BUSVC5.js";
+} from "./chunk-XPSD5HKG.js";
 import {
+  SA_LOCALE_STORAGE_KEY,
   SUPER_ADMIN_ACTIONS_KEY,
   SUPER_ADMIN_BRAND_KEY,
   SUPER_ADMIN_ENDPOINTS_KEY,
@@ -34,20 +37,24 @@ import {
   createSuperAdminI18n,
   useSaMessages,
   useSuperAdminI18n
-} from "./chunk-TY2WYKME.js";
+} from "./chunk-247RJPU4.js";
 import {
   DEFAULT_SA_LOCALE,
   SA_INTL_LOCALES,
   SA_LOCALES,
+  SA_LOCALE_LABELS,
   SA_MESSAGES,
+  builtinLocaleOf,
+  createSaCatalog,
   defaultHttpClient,
   defaultKvStore,
   defineMessages,
   formatCurrency,
   formatMessage,
+  isSaBuiltinLocale,
   mergeMessages,
   resolveMessages
-} from "./chunk-TBLXKSTR.js";
+} from "./chunk-IZGFS5RS.js";
 
 // src/vue/use-super-admin-context.ts
 import { inject } from "vue";
@@ -2815,6 +2822,8 @@ export {
   PromotionsApiError,
   SA_INTL_LOCALES,
   SA_LOCALES,
+  SA_LOCALE_LABELS,
+  SA_LOCALE_STORAGE_KEY,
   SA_MESSAGES,
   SUPER_ADMIN_ACTIONS_KEY,
   SUPER_ADMIN_BRAND_KEY,
@@ -2832,11 +2841,13 @@ export {
   buildQuotaRegistry,
   buildRoutes,
   buildSidebar,
+  builtinLocaleOf,
   createAdminResourceClient,
   createAdminRoutes,
   createManifestStore,
   createPlatformLoaders,
   createProjectPageHostRoute,
+  createSaCatalog,
   createSuperAdminI18n,
   defaultHttpClient,
   defaultIconForActionKey,
@@ -2848,10 +2859,13 @@ export {
   formatCurrency,
   formatMessage,
   getJson,
+  isProductionBoot,
+  isSaBuiltinLocale,
   mergeMessages,
   postJson,
   provideEntitlement,
   resolveExtension,
+  resolveLoginBranding,
   resolveMessages,
   trimTrailingSlashes,
   useActions,

package/dist/quasar/index.cjs

@@ -33,6 +33,45 @@ var import_pinia = require("pinia");
 var import_vue_router = require("vue-router");
 
 // src/client/types.ts
+var NOOP_KV_STORE = {
+  get: () => null,
+  set: () => {
+  },
+  remove: () => {
+  }
+};
+function defaultKvStore() {
+  const ls = resolveLocalStorage();
+  if (!ls) return NOOP_KV_STORE;
+  return {
+    get: (k) => {
+      try {
+        return ls.getItem(k);
+      } catch {
+        return null;
+      }
+    },
+    set: (k, v) => {
+      try {
+        ls.setItem(k, v);
+      } catch {
+      }
+    },
+    remove: (k) => {
+      try {
+        ls.removeItem(k);
+      } catch {
+      }
+    }
+  };
+}
+function resolveLocalStorage() {
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
 function defaultHttpClient() {
   return (url, init) => fetch(url, init);
 }
@@ -93,11 +132,19 @@ var SUPER_ADMIN_NOTIFY_KEY = /* @__PURE__ */ Symbol.for(
 var import_vue = require("vue");
 
 // src/client/i18n/locale.ts
+var SA_LOCALES = ["de", "en"];
 var DEFAULT_SA_LOCALE = "de";
 var SA_INTL_LOCALES = {
   de: "de-DE",
   en: "en-US"
 };
+var SA_LOCALE_LABELS = {
+  de: "Deutsch",
+  en: "English"
+};
+function isSaBuiltinLocale(value) {
+  return typeof value === "string" && SA_LOCALES.includes(value);
+}
 
 // src/client/i18n/define.ts
 function defineMessages(de, en) {
@@ -270,7 +317,7 @@ var bundlesMessages = defineMessages(
       bundleKeyHint: "API-stabil \xB7 wird aus dem Label erzeugt",
       errorKeyFormat: "Nur A-Z, 0-9, Underscore; muss mit Buchstabe beginnen.",
       errorKeyExists: "Dieser Bundle-Key existiert bereits.",
-      descriptionPlaceholder: "z. B. Kampagnen, WhatsApp und Korrespondenz f\xFCr aktive Vereine.",
+      descriptionPlaceholder: "z. B. Kampagnen, WhatsApp und Korrespondenz.",
       sectionPricing: "v1 \xB7 Pricing & G\xFCltigkeit",
       pricingHint: "Monats- & Jahrespreis sowie Datum, ab dem das Bundle verkaufbar wird.",
       validFromImmediate: "\u2713 Bundle ist nach Anlage sofort live und verkaufbar.",
@@ -482,7 +529,7 @@ var bundlesMessages = defineMessages(
       bundleKeyHint: "API-stable \xB7 derived from the label",
       errorKeyFormat: "Only A-Z, 0-9, underscore; must start with a letter.",
       errorKeyExists: "This bundle key already exists.",
-      descriptionPlaceholder: "e.g. Campaigns, WhatsApp and correspondence for active clubs.",
+      descriptionPlaceholder: "e.g. Campaigns, WhatsApp and correspondence.",
       sectionPricing: "v1 \xB7 pricing & validity",
       pricingHint: "Monthly & yearly price plus the date from which the bundle becomes sellable.",
       validFromImmediate: "\u2713 The bundle is live and sellable right after creation.",
@@ -1156,7 +1203,7 @@ var marketingMessages = defineMessages(
       ctaOverrideLabel: "CTA-Text \xFCberschreiben (optional)",
       ctaOverrideHint: "leer lassen f\xFCr Auto-Text",
       topFeatureCount: "{count} Eintr\xE4ge",
-      featureLabelPlaceholder: "z. B. Beitragsverwaltung",
+      featureLabelPlaceholder: "z. B. Erweiterte Berichte",
       featureStrongPlaceholder: "Highlight, z. B. bis 100",
       moveUp: "Nach oben",
       moveDown: "Nach unten",
@@ -1284,7 +1331,7 @@ var marketingMessages = defineMessages(
       ctaOverrideLabel: "Override CTA text (optional)",
       ctaOverrideHint: "leave empty for the auto text",
       topFeatureCount: "{count} entries",
-      featureLabelPlaceholder: "e.g. Membership management",
+      featureLabelPlaceholder: "e.g. Advanced reporting",
       featureStrongPlaceholder: "Highlight, e.g. up to 100",
       moveUp: "Move up",
       moveDown: "Move down",
@@ -2777,7 +2824,8 @@ var shellMessages = defineMessages(
       productionWarning: "Aktionen wirken sich sofort auf alle Mandanten aus.",
       subtitle: "SuperAdmin \xB7 Plattform-Verwaltung",
       roleBadge: "SUPER ADMIN",
-      logout: "Abmelden"
+      logout: "Abmelden",
+      language: "Sprache"
     },
     drawer: {
       docs: "Doku \xF6ffnen"
@@ -2845,7 +2893,8 @@ var shellMessages = defineMessages(
       productionWarning: "Actions take effect immediately for all tenants.",
       subtitle: "SuperAdmin \xB7 Platform administration",
       roleBadge: "SUPER ADMIN",
-      logout: "Sign out"
+      logout: "Sign out",
+      language: "Language"
     },
     drawer: {
       docs: "Open documentation"
@@ -3113,22 +3162,69 @@ var SA_MESSAGES = {
   de: catalogFor("de"),
   en: catalogFor("en")
 };
-function resolveMessages(locale, overrides) {
-  if (!overrides) return SA_MESSAGES[locale];
-  return mergeMessages(SA_MESSAGES[locale], overrides);
+
+// src/client/i18n/catalog.ts
+function createSaCatalog(options = {}) {
+  const additional = options.additionalLocales ?? {};
+  const known = /* @__PURE__ */ new Set([...SA_LOCALES, ...Object.keys(additional)]);
+  const requested = options.locales?.filter((code) => known.has(code));
+  const offered = requested && requested.length > 0 ? requested : [...SA_LOCALES, ...Object.keys(additional)];
+  const labelFor = (locale) => additional[locale]?.label ?? (isSaBuiltinLocale(locale) ? SA_LOCALE_LABELS[locale] : locale);
+  const cache = /* @__PURE__ */ new Map();
+  const messagesFor = (locale) => {
+    const hit = cache.get(locale);
+    if (hit) return hit;
+    const definition = additional[locale];
+    const base = SA_MESSAGES[definition?.basedOn ?? (isSaBuiltinLocale(locale) ? locale : "en")];
+    const translated = definition ? mergeMessages(base, definition.messages) : base;
+    const resolved = mergeMessages(translated, options.overrides?.[locale]);
+    cache.set(locale, resolved);
+    return resolved;
+  };
+  const offeredSet = new Set(offered);
+  return {
+    locales: offered.map((code) => ({ code, label: labelFor(code) })),
+    has: (locale) => offeredSet.has(locale),
+    // The app's first offered locale beats the platform default: an app
+    // shipping English only must not start in German.
+    defaultLocale: offered.includes(DEFAULT_SA_LOCALE) ? DEFAULT_SA_LOCALE : offered[0],
+    messagesFor,
+    intlLocaleFor: (locale) => additional[locale]?.intlLocale ?? (isSaBuiltinLocale(locale) ? SA_INTL_LOCALES[locale] : locale),
+    labelFor
+  };
 }
 
 // src/vue/use-super-admin-i18n.ts
+var SA_LOCALE_STORAGE_KEY = "sa:locale";
 var SUPER_ADMIN_I18N_KEY = /* @__PURE__ */ Symbol.for(
   "@saasicat/ui-vue/SUPER_ADMIN_I18N"
 );
 function createSuperAdminI18n(options = {}) {
-  const locale = (0, import_vue.isRef)(options.locale) ? options.locale : (0, import_vue.ref)(options.locale ?? DEFAULT_SA_LOCALE);
-  const messages = (0, import_vue.computed)(
-    () => resolveMessages(locale.value, options.overrides?.[locale.value])
+  const catalog = createSaCatalog(options);
+  const locale = (0, import_vue.isRef)(options.locale) ? options.locale : createOwnedLocale(options, catalog);
+  const active = (0, import_vue.computed)(
+    () => catalog.has(locale.value) ? locale.value : catalog.defaultLocale
   );
-  const intlLocale = (0, import_vue.computed)(() => SA_INTL_LOCALES[locale.value]);
-  return { locale, messages, intlLocale };
+  const messages = (0, import_vue.computed)(() => catalog.messagesFor(active.value));
+  const intlLocale = (0, import_vue.computed)(() => catalog.intlLocaleFor(active.value));
+  const writable = !(0, import_vue.isReadonly)(locale);
+  return {
+    locale,
+    messages,
+    intlLocale,
+    switcherEnabled: (options.switcher ?? true) && writable && catalog.locales.length > 1,
+    availableLocales: catalog.locales
+  };
+}
+function createOwnedLocale(options, catalog) {
+  const initial = options.locale ?? catalog.defaultLocale;
+  if (options.persist === false) return (0, import_vue.ref)(initial);
+  const storage = options.storage ?? defaultKvStore();
+  const key = `${options.storageKeyPrefix ?? ""}${SA_LOCALE_STORAGE_KEY}`;
+  const stored = storage.get(key);
+  const locale = (0, import_vue.ref)(stored && catalog.has(stored) ? stored : initial);
+  (0, import_vue.watch)(locale, (next) => storage.set(key, next));
+  return locale;
 }
 
 // src/quasar/notify.ts

package/dist/quasar/index.d.cts

@@ -2,8 +2,8 @@ import { Component, App } from 'vue';
 import { QuasarPluginOptions } from 'quasar';
 import { Pinia } from 'pinia';
 import { RouteRecordRaw, RouterHistory, Router } from 'vue-router';
-import { H as HttpClient } from '../messages-BIYw32u1.cjs';
-import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-DL_qI1BY.cjs';
+import { H as HttpClient } from '../catalog-C4Gv2_KM.cjs';
+import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-BdPqeTHl.cjs';
 import '@saasicat/types';
 
 interface CreateSuperAdminAppOptions extends SuperAdminGuardOptions {

package/dist/quasar/index.d.ts

@@ -2,8 +2,8 @@ import { Component, App } from 'vue';
 import { QuasarPluginOptions } from 'quasar';
 import { Pinia } from 'pinia';
 import { RouteRecordRaw, RouterHistory, Router } from 'vue-router';
-import { H as HttpClient } from '../messages-BIYw32u1.js';
-import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-CWNu_W3u.js';
+import { H as HttpClient } from '../catalog-C4Gv2_KM.js';
+import { S as SuperAdminGuardOptions, a as SuperAdminBrand, b as SuperAdminEndpoints, E as ExtensionsMap, A as ActionsMap, c as SuperAdminLoginAdapter, U as UiNotify, I as InstallPlugin, d as SuperAdminI18nOptions, e as SuperAdminI18n } from '../use-super-admin-i18n-uteRCL9q.js';
 import '@saasicat/types';
 
 interface CreateSuperAdminAppOptions extends SuperAdminGuardOptions {

package/dist/quasar/index.js

@@ -10,10 +10,10 @@ import {
   SUPER_ADMIN_NOTIFY_KEY,
   buildNavigationGuard,
   createSuperAdminI18n
-} from "../chunk-TY2WYKME.js";
+} from "../chunk-247RJPU4.js";
 import {
   defaultHttpClient
-} from "../chunk-TBLXKSTR.js";
+} from "../chunk-IZGFS5RS.js";
 
 // src/quasar/create-super-admin-app.ts
 import { createApp } from "vue";

package/dist/{use-super-admin-i18n-DL_qI1BY.d.cts → use-super-admin-i18n-BdPqeTHl.d.cts}

@@ -1,7 +1,7 @@
 import { Component, App, InjectionKey, Ref, ComputedRef } from 'vue';
 import { NavigationGuardWithThis } from 'vue-router';
 import { ActionKey, ComponentKey, AdminManifest } from '@saasicat/types';
-import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaMessagesOverrides } from './messages-BIYw32u1.cjs';
+import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaLocaleOption, c as SaLocaleDefinition, d as SaMessagesOverrides, K as KvStore } from './catalog-C4Gv2_KM.cjs';
 
 /**
  * App-specific branding data that the platform `AdminLayout` and other
@@ -182,16 +182,62 @@ interface SuperAdminI18n {
     messages: ComputedRef<SaMessages>;
     /** BCP-47 tag for `Intl`/`toLocaleString` formatting in the active locale. */
     intlLocale: ComputedRef<string>;
+    /**
+     * Whether the shell renders its language switcher. `false` when the app
+     * opted out, when `locale` cannot be written to, or when only one language
+     * is on offer — a switcher that cannot change anything is worse than none.
+     */
+    switcherEnabled: boolean;
+    /** Locales the switcher offers, in order, with their display names. */
+    availableLocales: readonly SaLocaleOption[];
 }
 interface SuperAdminI18nOptions {
     /**
-     * Initial UI locale, default `'de'`. Pass a `Ref` when the app wants to
-     * keep control (e.g. a user-profile setting or a header switcher).
+     * Starting UI locale — the shell's switcher lets the user pick another one,
+     * and a stored pick outranks this. Defaults to `'de'` when offered,
+     * otherwise to the first entry of `locales`. Pass a `Ref` when the app wants
+     * to keep control (e.g. a user-profile setting).
      */
     locale?: SaLocale | Ref<SaLocale>;
-    /** Per-locale string overrides layered over the platform catalog. */
+    /**
+     * Languages to offer, in switcher order. Default: German, English and
+     * everything in `additionalLocales`. Narrow it to ship a single language —
+     * the switcher then hides itself.
+     */
+    locales?: readonly SaLocale[];
+    /**
+     * Languages the app adds on top of the two the platform ships, keyed by
+     * locale code. Untranslated keys fall back to `basedOn`, so a partial
+     * catalog is usable from the first key onwards.
+     */
+    additionalLocales?: Readonly<Record<string, SaLocaleDefinition>>;
+    /** Per-locale string overrides layered over whatever catalog applies. */
     overrides?: Partial<Record<SaLocale, SaMessagesOverrides>>;
+    /**
+     * Remembers the locale picked in the header switcher across reloads,
+     * default `true`. Ignored when `locale` is a `Ref`: the app owns that value
+     * and persists it wherever it belongs (user profile, its own store).
+     */
+    persist?: boolean;
+    /**
+     * Storage adapter for `persist`. Defaults to `defaultKvStore()`.
+     */
+    storage?: KvStore;
+    /**
+     * Prefix for the persisted key, mirroring `createPlatformLoaders`. Set it
+     * when several apps share one origin and must not inherit each other's
+     * language pick.
+     */
+    storageKeyPrefix?: string;
+    /**
+     * Renders the language switcher in the shell chrome, default `true`. Set
+     * `false` for a deployment that ships one language. A readonly `locale`
+     * ref disables it on its own — no need to set this as well.
+     */
+    switcher?: boolean;
 }
+/** `KvStore` key holding the locale the user picked in the switcher. */
+declare const SA_LOCALE_STORAGE_KEY = "sa:locale";
 declare const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n>;
 declare function createSuperAdminI18n(options?: SuperAdminI18nOptions): SuperAdminI18n;
 /**
@@ -207,4 +253,4 @@ declare function useSuperAdminI18n(): SuperAdminI18n;
  */
 declare function useSaMessages<K extends keyof SaMessages>(namespace: K): ComputedRef<SaMessages[K]>;
 
-export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SUPER_ADMIN_ACTIONS_KEY as g, SUPER_ADMIN_BRAND_KEY as h, SUPER_ADMIN_ENDPOINTS_KEY as i, SUPER_ADMIN_EXTENSIONS_KEY as j, SUPER_ADMIN_HTTP_KEY as k, SUPER_ADMIN_I18N_KEY as l, SUPER_ADMIN_LOGIN_ADAPTER_KEY as m, SUPER_ADMIN_MANIFEST_KEY as n, SUPER_ADMIN_NOTIFY_KEY as o, type SuperAdminAuthGuardOptions as p, type SuperAdminLoginResult as q, type SuperAdminManifestGuardOptions as r, type UiNotifyKind as s, type UiNotifyOptions as t, buildNavigationGuard as u, createSuperAdminI18n as v, useSaMessages as w, useSuperAdminI18n as x };
+export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SA_LOCALE_STORAGE_KEY as g, SUPER_ADMIN_ACTIONS_KEY as h, SUPER_ADMIN_BRAND_KEY as i, SUPER_ADMIN_ENDPOINTS_KEY as j, SUPER_ADMIN_EXTENSIONS_KEY as k, SUPER_ADMIN_HTTP_KEY as l, SUPER_ADMIN_I18N_KEY as m, SUPER_ADMIN_LOGIN_ADAPTER_KEY as n, SUPER_ADMIN_MANIFEST_KEY as o, SUPER_ADMIN_NOTIFY_KEY as p, type SuperAdminAuthGuardOptions as q, type SuperAdminLoginResult as r, type SuperAdminManifestGuardOptions as s, type UiNotifyKind as t, type UiNotifyOptions as u, buildNavigationGuard as v, createSuperAdminI18n as w, useSaMessages as x, useSuperAdminI18n as y };

package/dist/{use-super-admin-i18n-CWNu_W3u.d.ts → use-super-admin-i18n-uteRCL9q.d.ts}

@@ -1,7 +1,7 @@
 import { Component, App, InjectionKey, Ref, ComputedRef } from 'vue';
 import { NavigationGuardWithThis } from 'vue-router';
 import { ActionKey, ComponentKey, AdminManifest } from '@saasicat/types';
-import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaMessagesOverrides } from './messages-BIYw32u1.js';
+import { A as ActionHandler, H as HttpClient, S as SaLocale, a as SaMessages, b as SaLocaleOption, c as SaLocaleDefinition, d as SaMessagesOverrides, K as KvStore } from './catalog-C4Gv2_KM.js';
 
 /**
  * App-specific branding data that the platform `AdminLayout` and other
@@ -182,16 +182,62 @@ interface SuperAdminI18n {
     messages: ComputedRef<SaMessages>;
     /** BCP-47 tag for `Intl`/`toLocaleString` formatting in the active locale. */
     intlLocale: ComputedRef<string>;
+    /**
+     * Whether the shell renders its language switcher. `false` when the app
+     * opted out, when `locale` cannot be written to, or when only one language
+     * is on offer — a switcher that cannot change anything is worse than none.
+     */
+    switcherEnabled: boolean;
+    /** Locales the switcher offers, in order, with their display names. */
+    availableLocales: readonly SaLocaleOption[];
 }
 interface SuperAdminI18nOptions {
     /**
-     * Initial UI locale, default `'de'`. Pass a `Ref` when the app wants to
-     * keep control (e.g. a user-profile setting or a header switcher).
+     * Starting UI locale — the shell's switcher lets the user pick another one,
+     * and a stored pick outranks this. Defaults to `'de'` when offered,
+     * otherwise to the first entry of `locales`. Pass a `Ref` when the app wants
+     * to keep control (e.g. a user-profile setting).
      */
     locale?: SaLocale | Ref<SaLocale>;
-    /** Per-locale string overrides layered over the platform catalog. */
+    /**
+     * Languages to offer, in switcher order. Default: German, English and
+     * everything in `additionalLocales`. Narrow it to ship a single language —
+     * the switcher then hides itself.
+     */
+    locales?: readonly SaLocale[];
+    /**
+     * Languages the app adds on top of the two the platform ships, keyed by
+     * locale code. Untranslated keys fall back to `basedOn`, so a partial
+     * catalog is usable from the first key onwards.
+     */
+    additionalLocales?: Readonly<Record<string, SaLocaleDefinition>>;
+    /** Per-locale string overrides layered over whatever catalog applies. */
     overrides?: Partial<Record<SaLocale, SaMessagesOverrides>>;
+    /**
+     * Remembers the locale picked in the header switcher across reloads,
+     * default `true`. Ignored when `locale` is a `Ref`: the app owns that value
+     * and persists it wherever it belongs (user profile, its own store).
+     */
+    persist?: boolean;
+    /**
+     * Storage adapter for `persist`. Defaults to `defaultKvStore()`.
+     */
+    storage?: KvStore;
+    /**
+     * Prefix for the persisted key, mirroring `createPlatformLoaders`. Set it
+     * when several apps share one origin and must not inherit each other's
+     * language pick.
+     */
+    storageKeyPrefix?: string;
+    /**
+     * Renders the language switcher in the shell chrome, default `true`. Set
+     * `false` for a deployment that ships one language. A readonly `locale`
+     * ref disables it on its own — no need to set this as well.
+     */
+    switcher?: boolean;
 }
+/** `KvStore` key holding the locale the user picked in the switcher. */
+declare const SA_LOCALE_STORAGE_KEY = "sa:locale";
 declare const SUPER_ADMIN_I18N_KEY: InjectionKey<SuperAdminI18n>;
 declare function createSuperAdminI18n(options?: SuperAdminI18nOptions): SuperAdminI18n;
 /**
@@ -207,4 +253,4 @@ declare function useSuperAdminI18n(): SuperAdminI18n;
  */
 declare function useSaMessages<K extends keyof SaMessages>(namespace: K): ComputedRef<SaMessages[K]>;
 
-export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SUPER_ADMIN_ACTIONS_KEY as g, SUPER_ADMIN_BRAND_KEY as h, SUPER_ADMIN_ENDPOINTS_KEY as i, SUPER_ADMIN_EXTENSIONS_KEY as j, SUPER_ADMIN_HTTP_KEY as k, SUPER_ADMIN_I18N_KEY as l, SUPER_ADMIN_LOGIN_ADAPTER_KEY as m, SUPER_ADMIN_MANIFEST_KEY as n, SUPER_ADMIN_NOTIFY_KEY as o, type SuperAdminAuthGuardOptions as p, type SuperAdminLoginResult as q, type SuperAdminManifestGuardOptions as r, type UiNotifyKind as s, type UiNotifyOptions as t, buildNavigationGuard as u, createSuperAdminI18n as v, useSaMessages as w, useSuperAdminI18n as x };
+export { type ActionsMap as A, type ExtensionsMap as E, type InstallPlugin as I, type SuperAdminGuardOptions as S, type UiNotify as U, type SuperAdminBrand as a, type SuperAdminEndpoints as b, type SuperAdminLoginAdapter as c, type SuperAdminI18nOptions as d, type SuperAdminI18n as e, type ExtensionLoader as f, SA_LOCALE_STORAGE_KEY as g, SUPER_ADMIN_ACTIONS_KEY as h, SUPER_ADMIN_BRAND_KEY as i, SUPER_ADMIN_ENDPOINTS_KEY as j, SUPER_ADMIN_EXTENSIONS_KEY as k, SUPER_ADMIN_HTTP_KEY as l, SUPER_ADMIN_I18N_KEY as m, SUPER_ADMIN_LOGIN_ADAPTER_KEY as n, SUPER_ADMIN_MANIFEST_KEY as o, SUPER_ADMIN_NOTIFY_KEY as p, type SuperAdminAuthGuardOptions as q, type SuperAdminLoginResult as r, type SuperAdminManifestGuardOptions as s, type UiNotifyKind as t, type UiNotifyOptions as u, buildNavigationGuard as v, createSuperAdminI18n as w, useSaMessages as x, useSuperAdminI18n as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/ui-vue",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Vue 3 components, resource clients and composables for the SuperAdmin UI shell. Provides boot and manifest loaders, navigation, actions and standard pages.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -53,7 +53,7 @@
     "src"
   ],
   "dependencies": {
-    "@saasicat/types": "^0.15.1"
+    "@saasicat/types": "^0.17.0"
   },
   "peerDependencies": {
     "pinia": "^2.0.0 || ^3.0.0",
@@ -75,10 +75,14 @@
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "@types/node": "^25.6.0",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "@vue/test-utils": "^2.4.11",
+    "jsdom": "^30.0.1",
     "pinia": "^3.0.0",
-    "quasar": "^2.22.0",
+    "quasar": "^2.24.0",
     "tsup": "^8.0.0",
     "typescript": "^6.0.0",
+    "vitest": "^4.1.10",
     "vue": "^3.5.0",
     "vue-router": "^5.0.0",
     "vue-tsc": "^3.3.3"
@@ -102,6 +106,7 @@
     "typecheck": "vue-tsc --noEmit -p tsconfig.json",
     "pretest": "pnpm run build",
     "test": "node --test tests/**/*.test.js",
+    "test:component": "vitest run --config vitest.config.ts",
     "test:e2e": "playwright test"
   }
 }

package/src/client/i18n/catalog.ts

@@ -0,0 +1,120 @@
+// Resolves a locale to the three things the shell needs from it: the catalog to
+// render, the tag `Intl` formats with, and the name the switcher shows.
+//
+// The platform ships German and English and stops there. Which of them an app
+// offers, which languages it adds, and what wording it prefers is the app's
+// decision — this module is the single place all three are applied.
+
+import { mergeMessages } from './define.js';
+import {
+    DEFAULT_SA_LOCALE,
+    SA_INTL_LOCALES,
+    SA_LOCALES,
+    SA_LOCALE_LABELS,
+    isSaBuiltinLocale,
+    type SaBuiltinLocale,
+    type SaLocale,
+} from './locale.js';
+import { SA_MESSAGES, type SaMessages, type SaMessagesOverrides } from './messages.js';
+
+/** A language an app brings along, on top of the two the platform ships. */
+export 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;
+}
+
+export 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. */
+export interface SaLocaleOption {
+    code: SaLocale;
+    label: string;
+}
+
+export 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.
+ */
+export function createSaCatalog(options: SaCatalogOptions = {}): SaCatalog {
+    const additional = options.additionalLocales ?? {};
+    const known = new Set<string>([...SA_LOCALES, ...Object.keys(additional)]);
+
+    // An app that lists an unknown code would otherwise get a switcher entry
+    // that renders nothing; dropping it here keeps the failure visible in one
+    // place instead of at every call site.
+    const requested = options.locales?.filter((code) => known.has(code));
+    const offered: readonly SaLocale[] =
+        requested && requested.length > 0 ? requested : [...SA_LOCALES, ...Object.keys(additional)];
+
+    const labelFor = (locale: SaLocale): string =>
+        additional[locale]?.label ??
+        (isSaBuiltinLocale(locale) ? SA_LOCALE_LABELS[locale] : locale);
+
+    const cache = new Map<SaLocale, SaMessages>();
+    const messagesFor = (locale: SaLocale): SaMessages => {
+        const hit = cache.get(locale);
+        if (hit) return hit;
+        const definition = additional[locale];
+        const base =
+            SA_MESSAGES[definition?.basedOn ?? (isSaBuiltinLocale(locale) ? locale : 'en')];
+        const translated = definition ? mergeMessages(base, definition.messages) : base;
+        const resolved = mergeMessages(translated, options.overrides?.[locale]);
+        cache.set(locale, resolved);
+        return resolved;
+    };
+
+    const offeredSet = new Set<string>(offered);
+
+    return {
+        locales: offered.map((code) => ({ code, label: labelFor(code) })),
+        has: (locale) => offeredSet.has(locale),
+        // The app's first offered locale beats the platform default: an app
+        // shipping English only must not start in German.
+        defaultLocale: offered.includes(DEFAULT_SA_LOCALE) ? DEFAULT_SA_LOCALE : offered[0],
+        messagesFor,
+        intlLocaleFor: (locale) =>
+            additional[locale]?.intlLocale ??
+            (isSaBuiltinLocale(locale) ? SA_INTL_LOCALES[locale] : locale),
+        labelFor,
+    };
+}

package/src/client/i18n/currency.ts

@@ -2,7 +2,12 @@
 // grouping and decimal separator follow the active UI locale
 // (de → `12.345,60 €`, en → `€12,345.60`).
 
-import { DEFAULT_SA_LOCALE, SA_INTL_LOCALES, type SaLocale } from './locale.js';
+import {
+    DEFAULT_SA_LOCALE,
+    SA_INTL_LOCALES,
+    type SaBuiltinLocale,
+    type SaLocale,
+} from './locale.js';
 
 const DEFAULT_CURRENCY = 'EUR';
 
@@ -12,7 +17,7 @@ function formatterFor(locale: SaLocale, currency: string, decimals: number): Int
     const key = `${locale}:${currency}:${decimals}`;
     let formatter = formatters.get(key);
     if (!formatter) {
-        formatter = new Intl.NumberFormat(SA_INTL_LOCALES[locale], {
+        formatter = new Intl.NumberFormat(SA_INTL_LOCALES[locale as SaBuiltinLocale] ?? locale, {
             style: 'currency',
             currency,
             minimumFractionDigits: decimals,