@object-ui/i18n 17.3.0 → 17.6.0

package/dist/provider.js

@@ -5,8 +5,8 @@
  */
 import React, { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { I18nextProvider, useTranslation } from 'react-i18next';
-import { createI18n, getDirection } from './i18n';
-import { builtInLocales } from './locales/index';
+import { createI18n, getDirection } from './i18n.js';
+import { builtInLocales } from './locales/index.js';
 /**
  * `localStorage` key holding the user's explicit language choice.
  *
@@ -59,46 +59,228 @@ function clearStoredLanguage() {
     }
 }
 /**
- * Languages `createI18n(config)` will know about: the built-in packs plus any
- * extra `config.resources`.
+ * `localStorage` key caching the TENANT's server-side locale — a *seed*, not a
+ * choice (objectui#4035).
+ *
+ * Deliberately a separate slot from {@link LOCALE_STORAGE_KEY}, and that
+ * separation is the whole point rather than a tidiness preference. The two
+ * values have different provenance and therefore different rights:
+ *
+ * - {@link LOCALE_STORAGE_KEY} is what the *user* picked. It outranks
+ *   everything and must survive a tenant reconfiguration.
+ * - This slot is what the *admin* configured, cached so the next boot can apply
+ *   it synchronously. It outranks only the environment (browser language).
+ *
+ * Writing the server seed into the explicit-choice slot would erase that
+ * difference permanently: the seed would then be indistinguishable from a
+ * deliberate user choice, so it would (a) outrank a later tenant change and pin
+ * the device to a stale locale forever, and (b) suppress browser detection for
+ * a user who never expressed a preference. Only a real switch promotes a
+ * language to the explicit slot — see the `languageChanged` choke point.
+ */
+export const LOCALE_SEED_STORAGE_KEY = 'objectui-locale-seed';
+/**
+ * Read the cached tenant locale seed, or `null` when nothing is cached.
+ *
+ * Same defensive posture as {@link readStoredLanguage}: `localStorage` is
+ * absent under SSR and *throws* in Safari private mode / partitioned iframes,
+ * and a language seed is never worth taking the app down for.
+ */
+export function readCachedLanguageSeed() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        return window.localStorage.getItem(LOCALE_SEED_STORAGE_KEY);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cache the tenant locale the server just answered with — the "revalidate" half
+ * of the stale-while-revalidate contract (objectstack#5419, ruling point 2).
+ *
+ * Call this with whatever `/auth/me/localization` actually returned for an
+ * authenticated caller. A `null`/`undefined` locale CLEARS the cache rather
+ * than leaving the old value: a tenant that unsets its locale must reach
+ * choice-less devices on their next boot, and "keep the last good seed forever"
+ * is precisely the being-pinned-by-a-stale-seed failure the ruling forbids.
+ *
+ * A *failed* fetch must simply not call this — the cache is then left intact,
+ * which is the correct stale-while-revalidate behaviour when revalidation
+ * cannot complete.
+ */
+export function cacheLanguageSeed(locale) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        if (typeof locale === 'string' && locale.length > 0) {
+            window.localStorage.setItem(LOCALE_SEED_STORAGE_KEY, locale);
+        }
+        else {
+            window.localStorage.removeItem(LOCALE_SEED_STORAGE_KEY);
+        }
+    }
+    catch {
+        // Storage blocked or full — this boot simply goes unseeded.
+    }
+}
+/**
+ * Languages `createI18n(config)` will know about *synchronously*: the built-in
+ * packs plus any extra `config.resources`.
  *
  * `hasOwnProperty` rather than `in`: a junk stored value like `constructor`
  * would pass an `in` check against the locale map's prototype.
  */
-function isKnownLanguage(lang, config) {
+function isStaticallyKnownLanguage(lang, config) {
     const own = Object.prototype.hasOwnProperty;
     return own.call(builtInLocales, lang) || Boolean(config?.resources && own.call(config.resources, lang));
 }
+/** The built-in packs' codes, as a stable identity for consumers' dep arrays. */
+const BUILT_IN_LANGUAGE_CODES = Object.freeze(Object.keys(builtInLocales));
+/**
+ * Every language this renderer can produce *without asking the app*: the
+ * built-in packs plus `config.resources`.
+ *
+ * This is the offline/no-backend answer — the set the switcher offers when
+ * there is no `loadLocales` wiring, or when the app's locale endpoint cannot
+ * be reached (objectui#4039).
+ */
+function resolvableLanguages(config) {
+    const extra = Object.keys(config?.resources ?? {}).filter((code) => !BUILT_IN_LANGUAGE_CODES.includes(code));
+    return [...BUILT_IN_LANGUAGE_CODES, ...extra];
+}
 /**
- * Resolve the bootstrap config for a provider-owned i18next instance, applying
- * a stored language choice when there is a usable one.
- *
- * Applied at instance creation rather than through a post-mount
- * `changeLanguage`, because the very first render must already be in the right
- * locale: `<html lang>` seeds the `Accept-Language` header on every API call
- * (`createAuthenticatedFetch`, issue #1319), so a late switch would fetch the
- * first wave of server-resolved metadata labels in the wrong language and then
- * have to remount to fix it.
- *
- * A stored choice outranks browser detection (which itself outranks
- * `defaultLanguage` in `createI18n`) — otherwise a user who picked 中文 on a
- * `ja` browser would be handed `ja` back on every reload, and the preference
- * would be unusable for exactly the users who need it.
- *
- * A stored value the app no longer offers is dropped *and purged*, so one stale
- * entry can never lock the UI to a locale that has no translations.
+ * Whether `tag` is a well-formed BCP-47 language tag.
+ *
+ * `Intl.getCanonicalLocales` is the standard's own parser, so this rejects
+ * exactly what a locale code cannot be — `constructor`, `__proto__`, `en_US`,
+ * `''` all throw `RangeError` — while accepting codes no pack exists for yet
+ * (`th`, `pt-BR`). Guarded for runtimes that ship no `Intl`: a language
+ * preference is never worth taking the app down for.
  */
-function resolveBootstrapConfig(config, persist) {
+function isWellFormedLanguageTag(tag) {
+    if (typeof Intl === 'undefined' || typeof Intl.getCanonicalLocales !== 'function') {
+        return /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/.test(tag);
+    }
+    try {
+        return Intl.getCanonicalLocales(tag).length === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether this provider can end up rendering `lang` at all.
+ *
+ * Wider than {@link isStaticallyKnownLanguage} by exactly one case: when a
+ * dynamic {@link I18nProviderProps.loadLanguage} loader is wired, that loader
+ * *is* the mechanism that produces app-shipped locales, and nothing can
+ * enumerate what it will answer for synchronously — the app's pack for `th`
+ * lives behind `GET /api/v1/i18n/translations/th`, not in `config.resources`.
+ *
+ * This is the lockstep half of objectui#4039. The switcher now offers the
+ * app's own locales, so the restore validation had to grow with it or a
+ * user-picked app locale would be purged on the next reload — the exact bug
+ * objectstack#5418 predicted this fix would otherwise mint. The bound stays
+ * honest rather than absent: only well-formed tags qualify, and the app's own
+ * locale list adjudicates the choice for real once it lands (see the
+ * `provisional` self-heal in {@link I18nProvider}).
+ */
+function canResolveLanguage(lang, config, hasLoader = false) {
+    if (isStaticallyKnownLanguage(lang, config))
+        return true;
+    return hasLoader && isWellFormedLanguageTag(lang);
+}
+/**
+ * Adjudicate a tenant locale seed into a language this renderer can actually
+ * boot in, or `null` to fall through to the next tier (objectui#4035).
+ *
+ * {@link canResolveLanguage} is the verdict — the same predicate the language
+ * menu uses, deliberately not a second "do we have this locale" check
+ * (objectstack#5418 / objectui#4039). Two things are layered on top of it, both
+ * of which are about *which question to ask it*, not about second-guessing the
+ * answer:
+ *
+ * **1. Region subtags are normalised away as a fallback.** A tenant locale is a
+ * full BCP-47 tag — the platform answers `zh-CN`, not `zh` (see
+ * `LocalizationFetchProvider`'s fixtures) — while the packs are keyed by base
+ * language. Asking only about `zh-CN` would reject the single most common
+ * tenant configuration there is. The exact tag is tried first so a genuine
+ * `pt-BR` pack still wins over `pt`; this mirrors `createI18n`'s own browser
+ * detection (`navigator.language.split('-')[0]`) and `pickLocalized`'s
+ * documented exact-then-base order, so it is this codebase's existing
+ * convention rather than a new rule.
+ *
+ * **2. The seed does NOT get the dynamic loader's credit** (`hasLoader` is left
+ * at its default `false`). That credit exists for a *user-picked* value: the
+ * user chose it from a menu built out of the app's real locale list, and a
+ * stored choice that turns out unshippable is adjudicated afterwards by the
+ * `provisional` self-heal. A tenant seed has neither property — it is an
+ * arbitrary admin-authored string that passed through no menu, and there is no
+ * self-heal behind it. Extending the credit would mean booting into a locale we
+ * cannot confirm we ship and then retracting it, i.e. manufacturing exactly the
+ * flash that ruling point 3 bounds, on the very first-visit path it bounds it
+ * on. Falling through instead is what ruling point 4 asks for, and it is
+ * self-correcting in one step: the user switches once, and that switch is a
+ * real explicit choice which outranks the seed from then on.
+ */
+function resolveSeedLanguage(seed, config) {
+    if (canResolveLanguage(seed, config))
+        return seed;
+    const base = seed.split('-')[0];
+    if (base && base !== seed && canResolveLanguage(base, config))
+        return base;
+    return null;
+}
+/**
+ * The tenant tier: a cached server seed, applied only when the user has
+ * expressed no choice of their own (objectui#4035).
+ *
+ * Returns the bootstrap resolution for the seed, or `null` when there is no
+ * usable seed and the caller should fall through to browser detection.
+ *
+ * `provisional` is deliberately always `null` here: that flag marks a value
+ * accepted on the loader's optimistic credit so the app's locale list can
+ * adjudicate it later, and {@link resolveSeedLanguage} never extends that
+ * credit — a seed is either resolvable right now or it falls through.
+ */
+function resolveSeedBootstrap(config) {
+    const seed = readCachedLanguageSeed();
+    if (!seed)
+        return null;
+    const resolved = resolveSeedLanguage(seed, config);
+    if (!resolved)
+        return null;
+    return {
+        // `detectBrowserLanguage: false` is what makes the tenant tier outrank the
+        // environment tier. The admin's deliberate configuration beats the
+        // browser's incidental one — ruling point 1.
+        config: { ...config, defaultLanguage: resolved, detectBrowserLanguage: false },
+        provisional: null,
+    };
+}
+function resolveBootstrapConfig(config, persist, hasLoader) {
+    // `persistLanguage: false` surfaces (previews, demos, screenshot harnesses)
+    // must stay on a fixed language regardless of what is on this origin — that
+    // covers the tenant seed too, not just the user's choice.
     if (!persist)
-        return config;
+        return { config, provisional: null };
     const stored = readStoredLanguage();
+    // No explicit choice at all → the tenant seed gets its turn.
     if (!stored)
-        return config;
-    if (!isKnownLanguage(stored, config)) {
+        return resolveSeedBootstrap(config) ?? { config, provisional: null };
+    if (!canResolveLanguage(stored, config, hasLoader)) {
         clearStoredLanguage();
-        return config;
+        // A purged choice is no choice, so this falls to the same tenant tier —
+        // otherwise dropping one unshippable stored value would skip the seed and
+        // land straight on the browser language.
+        return resolveSeedBootstrap(config) ?? { config, provisional: null };
     }
-    return { ...config, defaultLanguage: stored, detectBrowserLanguage: false };
+    return {
+        config: { ...config, defaultLanguage: stored, detectBrowserLanguage: false },
+        provisional: isStaticallyKnownLanguage(stored, config) ? null : stored,
+    };
 }
 const ObjectI18nContext = createContext(null);
 /**
@@ -111,8 +293,19 @@ const ObjectI18nContext = createContext(null);
  * </I18nProvider>
  * ```
  */
-export function I18nProvider({ config, instance: externalInstance, loadLanguage, persistLanguage = true, children, }) {
-    const i18nInstance = useMemo(() => externalInstance || createI18n(resolveBootstrapConfig(config, persistLanguage)), [externalInstance, config, persistLanguage]);
+export function I18nProvider({ config, instance: externalInstance, loadLanguage, loadLocales, persistLanguage = true, children, }) {
+    // A boolean, not `loadLanguage` itself: an inline arrow would change identity
+    // every render and rebuild the i18next instance (and with it the language)
+    // on each one. What the bootstrap needs to know is only whether a loader
+    // exists at all.
+    const hasLoader = Boolean(loadLanguage);
+    const bootstrap = useMemo(() => {
+        if (externalInstance)
+            return { instance: externalInstance, provisional: null };
+        const resolved = resolveBootstrapConfig(config, persistLanguage, hasLoader);
+        return { instance: createI18n(resolved.config), provisional: resolved.provisional };
+    }, [externalInstance, config, persistLanguage, hasLoader]);
+    const i18nInstance = bootstrap.instance;
     const [language, setLanguage] = useState(i18nInstance.language || 'en');
     const direction = getDirection(language);
     // Track which languages have had app-specific translations loaded
@@ -172,6 +365,79 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
             console.warn(`[i18n] Failed to load app translations for '${currentLang}':`, err);
         });
     }, [i18nInstance, loadLanguage]);
+    // The app's own locale list (objectui#4039). `null` = not answered yet; `[]`
+    // = asked and got nothing usable, which is "I don't know", not "I ship no
+    // locales" — both degrade to the offline fallback below.
+    const [appLocales, setAppLocales] = useState(null);
+    // Asked exactly once per provider, guarded by a ref — the same shape as the
+    // `loadedAppLangs` guard on `loadLanguage` above, and for two reasons at
+    // once. An inline `loadLocales={() => …}` changes identity every render, so
+    // without the guard the answer would set state, the re-render would mint a
+    // new arrow, and the new arrow would re-run the effect: a fetch loop. And
+    // StrictMode's double-invoked effect must not fire a second request.
+    //
+    // Deliberately no `cancelled` flag: under StrictMode the cleanup would
+    // cancel the only in-flight request while the re-run declines to start
+    // another, leaving the list permanently unanswered and the switcher
+    // permanently blank. Settling state after unmount is a no-op in React 18 —
+    // which is exactly why the `loadLanguage` effect above does the same.
+    const hasLocaleLoader = Boolean(loadLocales);
+    const askedForLocales = useRef(false);
+    useEffect(() => {
+        if (!loadLocales || askedForLocales.current)
+            return;
+        askedForLocales.current = true;
+        loadLocales()
+            .then((codes) => setAppLocales(Array.isArray(codes) ? codes : []))
+            .catch((err) => {
+            // A language menu is not worth an unhandled rejection: fall back to the
+            // locales this renderer can produce on its own.
+            setAppLocales([]);
+            console.warn('[i18n] Failed to load the app locale list:', err);
+        });
+    }, [loadLocales]);
+    const offerableLanguages = useMemo(() => {
+        const fallback = resolvableLanguages(config);
+        // No wiring at all: the built-in packs are the whole truth, as before.
+        if (!hasLocaleLoader)
+            return fallback;
+        if (appLocales === null)
+            return null;
+        const offerable = appLocales.filter((code) => canResolveLanguage(code, config, hasLoader));
+        // An app that answers with nothing this renderer can produce leaves the
+        // user with no way to switch at all — strictly worse than the offline
+        // fallback, so the fallback wins.
+        return offerable.length > 0 ? offerable : fallback;
+    }, [config, hasLocaleLoader, appLocales, hasLoader]);
+    // Self-heal: a stored language accepted on the loader's credit alone is
+    // adjudicated by the app's real list once it lands. Without this, widening
+    // the restore validation would reintroduce exactly what it was written to
+    // stop — one stale entry locking the UI to a locale with no translations.
+    // Scoped to our own optimism: only the bootstrap language, only while the
+    // user has not moved on, and never on an empty/failed answer.
+    useEffect(() => {
+        const provisional = bootstrap.provisional;
+        if (!provisional || !appLocales || appLocales.length === 0)
+            return;
+        if (appLocales.includes(provisional))
+            return;
+        if ((i18nInstance.language || '') !== provisional)
+            return;
+        const revertTo = config?.defaultLanguage || config?.fallbackLanguage || 'en';
+        void (async () => {
+            await i18nInstance.changeLanguage(revertTo);
+            // Purge AFTER the switch, not before: every language change persists
+            // itself (that is the point of the single choke point in the
+            // `languageChanged` handler), so clearing first would just be overwritten
+            // with `revertTo` — recording a preference the user never expressed and
+            // suppressing browser detection from then on. Ending with nothing stored
+            // is what the bootstrap purge has always left behind.
+            // Guarded: if the user picked something in the meantime, that choice is
+            // theirs to keep.
+            if ((i18nInstance.language || '') === revertTo)
+                clearStoredLanguage();
+        })();
+    }, [bootstrap, appLocales, i18nInstance, config]);
     const contextValue = useMemo(() => ({
         language,
         changeLanguage: async (lang) => {
@@ -191,7 +457,8 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
         },
         direction,
         i18n: i18nInstance,
-    }), [language, direction, i18nInstance, loadLanguage]);
+        offerableLanguages,
+    }), [language, direction, i18nInstance, loadLanguage, offerableLanguages]);
     return React.createElement(ObjectI18nContext.Provider, { value: contextValue }, React.createElement(I18nextProvider, { i18n: i18nInstance }, children));
 }
 /**
@@ -219,6 +486,13 @@ export function useObjectTranslation(ns) {
         direction: context?.direction || 'ltr',
         /** The underlying i18next instance */
         i18n,
+        /**
+         * Languages a switcher may offer (objectui#4039). `null` while the app's
+         * locale list is in flight. Outside a provider there is nobody to ask, so
+         * the built-in packs are the answer — not `null`, which would leave a
+         * standalone switcher permanently blank.
+         */
+        offerableLanguages: context ? context.offerableLanguages : BUILT_IN_LANGUAGE_CODES,
     };
 }
 /**

package/dist/useDisplayLocale.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * `useDisplayLocale` — the BCP-47 tag that field / cell / metric renderers
+ * format numbers and other `Intl` values with.
+ *
+ * This composes the two locale channels this repo already has; it does not add
+ * a third. The precedence, highest first:
+ *
+ *  1. **`useLocalization().locale`** — the tenant's resolved regional default
+ *     (ADR-0053, served by `GET /api/v1/auth/me/localization`). An org that has
+ *     explicitly configured a display locale means it, so it outranks the UI
+ *     language. Frequently `undefined`: the endpoint is
+ *     cosmetic and non-blocking, so an unconfigured or still-loading tenant
+ *     simply has no answer here (the state objectui#4033 was measured in — a
+ *     fresh database, console running `zh-CN`).
+ *
+ *  2. **`useObjectTranslation().language`** — the ACTIVE UI language, i.e. what
+ *     the user picked in the language switcher. This is the channel that makes
+ *     grouping and decimal marks follow the user's language when the tenant has
+ *     stated no regional preference.
+ *
+ *  3. **`'en'`** — a concrete last resort rather than `undefined`. `undefined`
+ *     would hand `Intl` the *machine's* locale, which is invisible in review and
+ *     non-deterministic in CI; `'en'` at least fails the same way everywhere.
+ *     Note this is `'en'`, not `'en-US'`: the point of objectui#4033 is that
+ *     `en-US` is not the world's default. In practice step 2 already answers,
+ *     since `useObjectTranslation` falls back to the react-i18next global
+ *     instance and ultimately reports `'en'` itself.
+ *
+ * Provider-safe at every step: `useLocalization` returns `{}` outside its
+ * provider and `useObjectTranslation` reads an optional context, so a renderer
+ * mounted standalone (tests, docs demos) degrades instead of throwing.
+ *
+ * **This composition is also the whole `'zh'` ↔ BCP-47 story** (objectui#4468).
+ * There is no mapping table anywhere and none is needed: the UI language codes
+ * this renderer ships (`'zh'`, `'ja'`, `'de'`, …) are already well-formed
+ * BCP-47 language subtags, so `Intl` accepts them verbatim. The one thing a
+ * caller must not do is reach past this hook for the raw tenant locale and hand
+ * `Intl` the `undefined` it gets on an unconfigured workspace — `undefined`
+ * means "the MACHINE's locale", which is neither channel. Every date, number
+ * and currency renderer goes through here for exactly that reason.
+ */
+export declare function useDisplayLocale(): string;

package/dist/useDisplayLocale.js

@@ -0,0 +1,55 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useLocalization } from './LocalizationContext.js';
+import { useObjectTranslation } from './provider.js';
+/**
+ * `useDisplayLocale` — the BCP-47 tag that field / cell / metric renderers
+ * format numbers and other `Intl` values with.
+ *
+ * This composes the two locale channels this repo already has; it does not add
+ * a third. The precedence, highest first:
+ *
+ *  1. **`useLocalization().locale`** — the tenant's resolved regional default
+ *     (ADR-0053, served by `GET /api/v1/auth/me/localization`). An org that has
+ *     explicitly configured a display locale means it, so it outranks the UI
+ *     language. Frequently `undefined`: the endpoint is
+ *     cosmetic and non-blocking, so an unconfigured or still-loading tenant
+ *     simply has no answer here (the state objectui#4033 was measured in — a
+ *     fresh database, console running `zh-CN`).
+ *
+ *  2. **`useObjectTranslation().language`** — the ACTIVE UI language, i.e. what
+ *     the user picked in the language switcher. This is the channel that makes
+ *     grouping and decimal marks follow the user's language when the tenant has
+ *     stated no regional preference.
+ *
+ *  3. **`'en'`** — a concrete last resort rather than `undefined`. `undefined`
+ *     would hand `Intl` the *machine's* locale, which is invisible in review and
+ *     non-deterministic in CI; `'en'` at least fails the same way everywhere.
+ *     Note this is `'en'`, not `'en-US'`: the point of objectui#4033 is that
+ *     `en-US` is not the world's default. In practice step 2 already answers,
+ *     since `useObjectTranslation` falls back to the react-i18next global
+ *     instance and ultimately reports `'en'` itself.
+ *
+ * Provider-safe at every step: `useLocalization` returns `{}` outside its
+ * provider and `useObjectTranslation` reads an optional context, so a renderer
+ * mounted standalone (tests, docs demos) degrades instead of throwing.
+ *
+ * **This composition is also the whole `'zh'` ↔ BCP-47 story** (objectui#4468).
+ * There is no mapping table anywhere and none is needed: the UI language codes
+ * this renderer ships (`'zh'`, `'ja'`, `'de'`, …) are already well-formed
+ * BCP-47 language subtags, so `Intl` accepts them verbatim. The one thing a
+ * caller must not do is reach past this hook for the raw tenant locale and hand
+ * `Intl` the `undefined` it gets on an unconfigured workspace — `undefined`
+ * means "the MACHINE's locale", which is neither channel. Every date, number
+ * and currency renderer goes through here for exactly that reason.
+ */
+export function useDisplayLocale() {
+    const { locale } = useLocalization();
+    const { language } = useObjectTranslation();
+    return locale || language || 'en';
+}

package/dist/useObjectLabel.d.ts

@@ -88,13 +88,27 @@ export declare function useObjectLabel(): {
         description?: string;
     }) => string | undefined;
     /**
-     * Resolve translated label for a navigation group within an app.
-     * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+     * Read `{ns}.apps.{appName}.navigation.{groupId}.label` out of the loaded
+     * CLIENT translation resources, falling back to `fallback`.
      *
-     * Mirrors `objectLabel`/`dashboardLabel` so app metadata can keep
-     * English fallbacks while translation packs supply localised
-     * sidebar group labels (e.g. "Sales" → "销售") without explicit
-     * I18nLabel `{ key, defaultValue }` annotations.
+     * ⚠️ This does NOT localize the sidebar, and adding a translation pack
+     * keyed this way will not change a single rendered nav label.
+     * **App-navigation localization is owned solely by the server-side
+     * `/meta` boundary**: `translateApp` in `@objectstack/spec`
+     * (`src/system/i18n-resolver.ts`) rewrites every navigation node's
+     * `label` by id, and `@objectstack/rest` applies it before the metadata
+     * reaches this client — so nav labels arrive already localized. One
+     * owner, not two. To translate a sidebar group, translate it there.
+     *
+     * History (objectui#5197): until then this docstring promised
+     * `"Sales" → "销售"` for sidebar groups, and `NavigationRenderer`
+     * accepted `resolveGroupLabel`/`resolveItemLabel` to wire it up. Those
+     * props could never fire — the renderer's `isCustomized` guard compared a
+     * node's authored label against its own `id` (`Workspace` vs
+     * `grp_workspace`), which never match, so the guard was true for every
+     * real entry. The props are gone; the promise was false, not merely
+     * unused. This helper is kept as a plain key reader for a consumer that
+     * renders navigation itself — it has no first-party caller.
      */
     navGroupLabel: (appName: string, groupId: string, fallback: string) => string;
     /**
@@ -133,6 +147,29 @@ export declare function useObjectLabel(): {
      * Returns undefined when neither metadata nor translation provides one.
      */
     widgetDescription: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
+    /**
+     * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
+     * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
+     * Returns undefined when neither metadata nor translation provides one.
+     *
+     * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
+     * The KPI card renders two authored strings from two different fields — the
+     * shared card header's `widget.description`, and the sub-caption under the
+     * value, which is authored as `widget.options.description` — and the
+     * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
+     * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
+     * translation entry silently retarget the other field on any widget type
+     * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
+     * type except the self-contained `metric`).
+     *
+     * `subCaption` is the member objectstack#8056 added to the widget
+     * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
+     * The server-side resolver reads the SAME key and overlays it onto
+     * `options.description` (`translateDashboard`), so a document served
+     * through `/meta` and a document translated here land on the same string —
+     * this is the client half of one convention, not a second dialect.
+     */
+    widgetSubCaption: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated page label, falling back to pageDef.label.
      * Convention: `{ns}.pages.{pageName}.label`.
@@ -151,7 +188,10 @@ export declare function useObjectLabel(): {
     }) => string;
     /**
      * Resolve translated list-view label.
-     * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`.
+     * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`,
+     * where `{viewName}` is the **bare** view name — pass either the bare name or
+     * the qualified runtime id, the object prefix is stripped either way. A key
+     * that spells the prefix out does not resolve (see `viewSuffixes`).
      */
     viewLabel: (objectName: string, viewName: string, fallback: string) => string;
     /**
@@ -308,13 +348,27 @@ export declare function useSafeFieldLabel(): {
         description?: string;
     }) => string | undefined;
     /**
-     * Resolve translated label for a navigation group within an app.
-     * Convention: `{ns}.apps.{appName}.navigation.{groupId}.label`.
+     * Read `{ns}.apps.{appName}.navigation.{groupId}.label` out of the loaded
+     * CLIENT translation resources, falling back to `fallback`.
      *
-     * Mirrors `objectLabel`/`dashboardLabel` so app metadata can keep
-     * English fallbacks while translation packs supply localised
-     * sidebar group labels (e.g. "Sales" → "销售") without explicit
-     * I18nLabel `{ key, defaultValue }` annotations.
+     * ⚠️ This does NOT localize the sidebar, and adding a translation pack
+     * keyed this way will not change a single rendered nav label.
+     * **App-navigation localization is owned solely by the server-side
+     * `/meta` boundary**: `translateApp` in `@objectstack/spec`
+     * (`src/system/i18n-resolver.ts`) rewrites every navigation node's
+     * `label` by id, and `@objectstack/rest` applies it before the metadata
+     * reaches this client — so nav labels arrive already localized. One
+     * owner, not two. To translate a sidebar group, translate it there.
+     *
+     * History (objectui#5197): until then this docstring promised
+     * `"Sales" → "销售"` for sidebar groups, and `NavigationRenderer`
+     * accepted `resolveGroupLabel`/`resolveItemLabel` to wire it up. Those
+     * props could never fire — the renderer's `isCustomized` guard compared a
+     * node's authored label against its own `id` (`Workspace` vs
+     * `grp_workspace`), which never match, so the guard was true for every
+     * real entry. The props are gone; the promise was false, not merely
+     * unused. This helper is kept as a plain key reader for a consumer that
+     * renders navigation itself — it has no first-party caller.
      */
     navGroupLabel: (appName: string, groupId: string, fallback: string) => string;
     /**
@@ -353,6 +407,29 @@ export declare function useSafeFieldLabel(): {
      * Returns undefined when neither metadata nor translation provides one.
      */
     widgetDescription: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
+    /**
+     * Resolve a translated metric-widget SUB-CAPTION within a dashboard.
+     * Convention: `{ns}.dashboards.{dashboardName}.widgets.{widgetId}.subCaption`.
+     * Returns undefined when neither metadata nor translation provides one.
+     *
+     * Deliberately its OWN key, not a second reader of `widgets.{id}.description`.
+     * The KPI card renders two authored strings from two different fields — the
+     * shared card header's `widget.description`, and the sub-caption under the
+     * value, which is authored as `widget.options.description` — and the
+     * objectstack#5428 item-4 ruling (2026-08-06) settled that they get two
+     * keys, not one: 「两个作者字段两个 key」. Collapsing them would make one
+     * translation entry silently retarget the other field on any widget type
+     * that renders both at once (`kpi`, `gauge`, `bullet` — every metric-family
+     * type except the self-contained `metric`).
+     *
+     * `subCaption` is the member objectstack#8056 added to the widget
+     * translation node for exactly this, shipped in `@objectstack/spec@17.0.0`.
+     * The server-side resolver reads the SAME key and overlays it onto
+     * `options.description` (`translateDashboard`), so a document served
+     * through `/meta` and a document translated here land on the same string —
+     * this is the client half of one convention, not a second dialect.
+     */
+    widgetSubCaption: (dashboardName: string, widgetId: string, fallback?: string) => string | undefined;
     /**
      * Resolve translated page label, falling back to pageDef.label.
      * Convention: `{ns}.pages.{pageName}.label`.
@@ -371,7 +448,10 @@ export declare function useSafeFieldLabel(): {
     }) => string;
     /**
      * Resolve translated list-view label.
-     * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`.
+     * Convention (per @objectstack/spec): `{ns}.objects.{objectName}._views.{viewName}.label`,
+     * where `{viewName}` is the **bare** view name — pass either the bare name or
+     * the qualified runtime id, the object prefix is stripped either way. A key
+     * that spells the prefix out does not resolve (see `viewSuffixes`).
      */
     viewLabel: (objectName: string, viewName: string, fallback: string) => string;
     /**