@object-ui/i18n 17.3.0 → 17.5.0

package/dist/pickLocalized.d.ts

@@ -11,5 +11,26 @@
  *
  * Pure — pair it with `useObjectTranslation().language` (or any current-locale
  * source) at the call site.
+ *
+ * Every limb reads **own properties only** and accepts **only `string` values**
+ * (objectui#3907). Both guards used to hold on the regional and last-resort
+ * limbs alone, which left the other four able to resolve a locale against
+ * `Object.prototype` — `pickLocalized({ en: 'Pricing' }, 'constructor')`
+ * rendered the constructor's source text as the label — and able to
+ * short-circuit the chain with a non-string value, rendering `[object Object]`.
+ * Neither is reachable by an input the contract admits (no BCP-47 tag is an
+ * `Object.prototype` member, and `InlineLocaleMapSchema` is
+ * `z.record(<tag>, z.string())`), so applying them uniformly changes nothing
+ * for any real language tag. It makes this function agree limb for limb with
+ * the backend twin `resolveI18nLabel` (`@objectstack/spec`, objectstack#6765),
+ * whose locale can arrive from an untrusted `Accept-Language` header and which
+ * shipped with exactly these two narrowings recorded as deliberate departures.
+ * The only remaining difference between the two is how each spells a miss —
+ * `''` here for a text node, `undefined` there for a producer's `?? name` chain
+ * — pinned in `plugin-list/src/__tests__/i18nLabel-resolver-parity.test.ts`.
+ *
+ * A guard makes its limb **miss**; it never aborts the resolution. An unusable
+ * entry falls through to the next limb exactly as an absent one does, so
+ * `pickLocalized({ en: 'Pricing' }, 'constructor')` is `'Pricing'`, not `''`.
  */
 export declare function pickLocalized(value: unknown, language: string | undefined | null): string;

package/dist/pickLocalized.js

@@ -11,6 +11,27 @@
  *
  * Pure — pair it with `useObjectTranslation().language` (or any current-locale
  * source) at the call site.
+ *
+ * Every limb reads **own properties only** and accepts **only `string` values**
+ * (objectui#3907). Both guards used to hold on the regional and last-resort
+ * limbs alone, which left the other four able to resolve a locale against
+ * `Object.prototype` — `pickLocalized({ en: 'Pricing' }, 'constructor')`
+ * rendered the constructor's source text as the label — and able to
+ * short-circuit the chain with a non-string value, rendering `[object Object]`.
+ * Neither is reachable by an input the contract admits (no BCP-47 tag is an
+ * `Object.prototype` member, and `InlineLocaleMapSchema` is
+ * `z.record(<tag>, z.string())`), so applying them uniformly changes nothing
+ * for any real language tag. It makes this function agree limb for limb with
+ * the backend twin `resolveI18nLabel` (`@objectstack/spec`, objectstack#6765),
+ * whose locale can arrive from an untrusted `Accept-Language` header and which
+ * shipped with exactly these two narrowings recorded as deliberate departures.
+ * The only remaining difference between the two is how each spells a miss —
+ * `''` here for a text node, `undefined` there for a producer's `?? name` chain
+ * — pinned in `plugin-list/src/__tests__/i18nLabel-resolver-parity.test.ts`.
+ *
+ * A guard makes its limb **miss**; it never aborts the resolution. An unusable
+ * entry falls through to the next limb exactly as an absent one does, so
+ * `pickLocalized({ en: 'Pricing' }, 'constructor')` is `'Pricing'`, not `''`.
  */
 export function pickLocalized(value, language) {
     if (value == null)
@@ -21,18 +42,30 @@ export function pickLocalized(value, language) {
         return String(value);
     if (typeof value === 'object') {
         const o = value;
+        /**
+         * One entry, or `undefined` when this limb does not hit — which is what
+         * lets the limbs keep chaining through `??` in the same order as before.
+         */
+        const read = (key) => {
+            if (!Object.prototype.hasOwnProperty.call(o, key))
+                return undefined;
+            const entry = o[key];
+            return typeof entry === 'string' ? entry : undefined;
+        };
         const lang = (language || 'en').trim();
         const base = lang.split('-')[0];
         // Runtime language is often a bare base code ('zh') while metadata authors
         // write full BCP-47 tags ('zh-CN') — upgrade to any key sharing the base.
-        const regional = Object.keys(o).find((k) => k.split('-')[0] === base && typeof o[k] === 'string');
-        const pick = o[lang] ??
-            o[base] ??
-            (regional !== undefined ? o[regional] : undefined) ??
-            o.default ??
-            o.en ??
+        // `Object.keys` is already own-and-enumerable, so `read` here is uniformity
+        // rather than a second guard.
+        const regional = Object.keys(o).find((k) => k.split('-')[0] === base && read(k) !== undefined);
+        const pick = read(lang) ??
+            read(base) ??
+            (regional !== undefined ? read(regional) : undefined) ??
+            read('default') ??
+            read('en') ??
             Object.values(o).find((v) => typeof v === 'string');
-        return pick == null ? '' : String(pick);
+        return pick == null ? '' : pick;
     }
     return String(value);
 }

package/dist/provider.d.ts

@@ -28,6 +28,50 @@ export declare const LOCALE_STORAGE_KEY = "objectui-locale";
  * stored".
  */
 export declare function readStoredLanguage(): string | null;
+/**
+ * `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 declare 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 declare function readCachedLanguageSeed(): string | 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 declare function cacheLanguageSeed(locale: string | null | undefined): void;
 interface I18nContextValue {
     /** Current language code */
     language: string;
@@ -37,6 +81,19 @@ interface I18nContextValue {
     direction: 'ltr' | 'rtl';
     /** The underlying i18next instance */
     i18n: I18nInstance;
+    /**
+     * The languages a switcher may offer (objectui#4039): the app's own locale
+     * list ∩ what this renderer can resolve. Computed here because only the
+     * provider knows both sides — the built-in packs, `config.resources` and
+     * whether a dynamic loader is wired.
+     *
+     * `null` means "still asking the app". Consumers render nothing (or a
+     * skeleton) rather than a list they will have to retract a tick later.
+     * Without {@link I18nProviderProps.loadLocales} wiring, or when the app's
+     * endpoint cannot be reached, this is the offline fallback: the built-in
+     * packs plus `config.resources`.
+     */
+    offerableLanguages: readonly string[] | null;
 }
 export interface I18nProviderProps {
     /** i18n configuration options */
@@ -61,6 +118,24 @@ export interface I18nProviderProps {
      * ```
      */
     loadLanguage?: (lang: string) => Promise<Record<string, unknown>>;
+    /**
+     * The app's own locale list — the codes it actually ships translations for
+     * (objectui#4039). Wired the same way as {@link I18nProviderProps.loadLanguage}:
+     * the app owns the transport, the provider owns what is done with the answer.
+     *
+     * The console reads `GET /api/v1/i18n/locales`; see
+     * `apps/console/src/loadLocales.ts`. Without this prop the switcher keeps
+     * offering the built-in packs (plus `config.resources`) exactly as before, so
+     * an app that never wires it is unaffected.
+     *
+     * @example
+     * ```tsx
+     * <I18nProvider loadLanguage={loadLanguage} loadLocales={loadLocales}>
+     *   <App />
+     * </I18nProvider>
+     * ```
+     */
+    loadLocales?: () => Promise<string[]>;
     /**
      * Remember the active language in `localStorage` ({@link LOCALE_STORAGE_KEY})
      * and restore it on the next mount. Default: `true`.
@@ -94,7 +169,7 @@ export interface I18nProviderProps {
  * </I18nProvider>
  * ```
  */
-export declare function I18nProvider({ config, instance: externalInstance, loadLanguage, persistLanguage, children, }: I18nProviderProps): React.FunctionComponentElement<React.ProviderProps<I18nContextValue | null>>;
+export declare function I18nProvider({ config, instance: externalInstance, loadLanguage, loadLocales, persistLanguage, children, }: I18nProviderProps): React.FunctionComponentElement<React.ProviderProps<I18nContextValue | null>>;
 /**
  * Hook to access Object UI i18n context
  *
@@ -117,6 +192,13 @@ export declare function useObjectTranslation(ns?: string): {
     direction: "ltr" | "rtl";
     /** The underlying i18next instance */
     i18n: I18nInstance;
+    /**
+     * 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: readonly string[] | null;
 };
 /**
  * Hook to access the i18n context directly

package/dist/provider.js

@@ -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;