@object-ui/i18n 17.2.0 → 17.5.0

package/dist/provider.js

@@ -6,6 +6,282 @@
 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';
+/**
+ * `localStorage` key holding the user's explicit language choice.
+ *
+ * Follows the console's existing preference-key convention
+ * (`objectui-favorites`, `objectui-recent-items`), and sits beside the theme
+ * preference the same avatar menu writes — a language switch is a preference,
+ * not ephemeral UI state, so it belongs in storage (AGENTS.md §5 #8).
+ *
+ * Exported so an app that builds its own i18next instance (and therefore owns
+ * its bootstrap language — see {@link I18nProviderProps.instance}) can honour
+ * the same preference, and so a sign-out flow can clear it.
+ */
+export const LOCALE_STORAGE_KEY = 'objectui-locale';
+/**
+ * Read the persisted language choice, or `null` when nothing is stored.
+ *
+ * Defensive by design: `localStorage` does not exist under SSR and *throws* on
+ * access in Safari private mode / partitioned iframes. A language preference is
+ * never worth taking the app down for, so every failure degrades to "nothing
+ * stored".
+ */
+export function readStoredLanguage() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        return window.localStorage.getItem(LOCALE_STORAGE_KEY);
+    }
+    catch {
+        return null;
+    }
+}
+function writeStoredLanguage(lang) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(LOCALE_STORAGE_KEY, lang);
+    }
+    catch {
+        // Storage blocked or full — the switch still applies for this session.
+    }
+}
+function clearStoredLanguage() {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.removeItem(LOCALE_STORAGE_KEY);
+    }
+    catch {
+        // Nothing readable means nothing to purge.
+    }
+}
+/**
+ * `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 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];
+}
+/**
+ * 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 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, provisional: null };
+    const stored = readStoredLanguage();
+    // No explicit choice at all → the tenant seed gets its turn.
+    if (!stored)
+        return resolveSeedBootstrap(config) ?? { config, provisional: null };
+    if (!canResolveLanguage(stored, config, hasLoader)) {
+        clearStoredLanguage();
+        // 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: { ...config, defaultLanguage: stored, detectBrowserLanguage: false },
+        provisional: isStaticallyKnownLanguage(stored, config) ? null : stored,
+    };
+}
 const ObjectI18nContext = createContext(null);
 /**
  * I18nProvider - Wraps your app with i18n support
@@ -17,8 +293,19 @@ const ObjectI18nContext = createContext(null);
  * </I18nProvider>
  * ```
  */
-export function I18nProvider({ config, instance: externalInstance, loadLanguage, children }) {
-    const i18nInstance = useMemo(() => externalInstance || createI18n(config), [externalInstance, config]);
+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
@@ -27,6 +314,14 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
     useEffect(() => {
         const handleLanguageChanged = (lng) => {
             setLanguage(lng);
+            // Remember the choice. This is the single choke point every switch runs
+            // through — i18next fires `languageChanged` for the context's
+            // `changeLanguage` and for a direct `i18n.changeLanguage()` alike — so no
+            // switcher can be wired in a way that silently forgets the preference.
+            // Bootstrap does NOT fire this event, so restoring a stored language
+            // never re-writes it.
+            if (persistLanguage)
+                writeStoredLanguage(lng);
             // Update document direction for RTL support
             if (typeof document !== 'undefined') {
                 document.documentElement.dir = getDirection(lng);
@@ -49,7 +344,7 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
         return () => {
             i18nInstance.off('languageChanged', handleLanguageChanged);
         };
-    }, [i18nInstance]);
+    }, [i18nInstance, persistLanguage]);
     // Load app-specific translations for the initial language on mount
     useEffect(() => {
         if (!loadLanguage)
@@ -70,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) => {
@@ -89,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));
 }
 /**
@@ -117,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';
+import { useObjectTranslation } from './provider';
+/**
+ * `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

@@ -151,7 +151,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;
     /**
@@ -371,7 +374,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;
     /**

package/dist/useObjectLabel.js

@@ -188,19 +188,36 @@ export function useObjectLabel() {
         /**
          * Build suffix candidates for a list-view scoped key.
          *
-         * The runtime uses qualified view ids (`<objectName>.<viewName>`) in URLs
-         * and metadata records, while translation bundles are keyed by the authored
-         * view name under `_views`. Resolve the unqualified name first so every
-         * surface can pass its canonical id without leaking the metadata fallback.
+         * The runtime uses qualified view ids (`<objectName>.<viewName>`) in URLs and
+         * metadata records, while translation bundles are keyed by the **bare** view
+         * name under `_views` — the runtime view identity's own name, stripped of the
+         * object prefix. That single spelling is canonical per the objectstack#5164
+         * ruling A (2026-08-06): the i18n extractor asks the view composer for the key
+         * (objectstack#6124) and `packages/lint` enforces exactly that spelling
+         * (objectstack#6038), so this resolver accepts exactly what those produce.
+         *
+         * Deliberately NOT a second candidate: the prefixed full name
+         * (`_views.<objectName>.<viewName>`). Accepting it made this client more
+         * lenient than the server-side resolver, which only ever reads the one key
+         * (objectstack#5165) — a bundle authored against the prefixed spelling showed
+         * translated labels in the Console while every consumer that does not run a
+         * second resolution pass (REST boundary, mobile, plain HTTP, SDUI) still got
+         * English. A prefixed key now simply misses, and the label falls back to the
+         * metadata default on every surface alike, so the authoring mistake is visible
+         * instead of half-hidden. It is caught at authoring time by `os lint`'s
+         * `translation-target-unknown`, not papered over here.
+         *
+         * The object-name candidates (`objects.<ns__obj>` then `objects.<obj>`) are a
+         * separate axis and stay: they let bundles written against short object names
+         * resolve when the runtime presents fully-qualified ones.
          */
         const viewSuffixes = (objectName, viewName, tail) => {
             const objectNames = [objectName, stripNamespace(objectName)];
             const matchedPrefix = objectNames
                 .map((name) => `${name}.`)
                 .find((prefix) => viewName.startsWith(prefix));
-            const shortViewName = matchedPrefix ? viewName.slice(matchedPrefix.length) : viewName;
-            const viewNames = shortViewName === viewName ? [viewName] : [shortViewName, viewName];
-            return viewNames.flatMap((name) => objectSuffixes(objectName, `_views.${name}.${tail}`));
+            const bareViewName = matchedPrefix ? viewName.slice(matchedPrefix.length) : viewName;
+            return objectSuffixes(objectName, `_views.${bareViewName}.${tail}`);
         };
         return {
             /**
@@ -309,7 +326,10 @@ export function useObjectLabel() {
             reportLabel: (reportDef) => resolve(reportSuffixes(reportDef.name, 'label'), reportDef.label ?? reportDef.name),
             /**
              * 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, viewName, fallback) => resolve(viewSuffixes(objectName, viewName, 'label'), fallback),
             /**