@object-ui/i18n 17.6.0 → 17.7.0

package/dist/provider.js

@@ -5,8 +5,9 @@
  */
 import React, { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { I18nextProvider, useTranslation } from 'react-i18next';
-import { createI18n, getDirection } from './i18n.js';
-import { builtInLocales } from './locales/index.js';
+import { createI18n, getDirection, pickInitialLanguage } from './i18n.js';
+import { interpolateFallback, optionsOf } from './fallbackInterpolation.js';
+import { BUILT_IN_LANGUAGE_CODES as BUILT_IN_CODES, isBuiltInLanguage, loadBuiltInLocale, matchLanguageTag, } from './locales/registry.js';
 /**
  * `localStorage` key holding the user's explicit language choice.
  *
@@ -18,6 +19,22 @@ import { builtInLocales } from './locales/index.js';
  * 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.
+ *
+ * ⚠️ **What this slot means changed for a SIGNED-IN user (objectui#10059).**
+ * A signed-in user's language has one source of truth and it is not on the
+ * device: it is the server column `sys_user.locale`, read back through
+ * `GET /auth/me/localization` and written by both the profile page's language
+ * card and the console's globe menu. For that user this slot is a CACHE of the
+ * column — it still decides the first paint, because the column cannot be read
+ * synchronously, and it is then overwritten by whatever the column says. It
+ * decides on its own only BEFORE sign-in, which is the case this provider can
+ * see and the only one it adjudicates.
+ *
+ * This provider deliberately does not implement that rule: reading a `sys_user`
+ * row needs an authenticated data adapter, which is a host concern and not a
+ * dependency a renderer package takes. The host applies the column through
+ * {@link I18nContextValue.changeLanguage} like any other switch — in this
+ * repository, `@object-ui/app-shell`'s `useUserLocale`.
  */
 export const LOCALE_STORAGE_KEY = 'objectui-locale';
 /**
@@ -59,28 +76,53 @@ function clearStoredLanguage() {
     }
 }
 /**
- * `localStorage` key caching the TENANT's server-side locale — a *seed*, not a
- * choice (objectui#4035).
+ * `localStorage` key caching the server's resolved locale for the signed-in
+ * caller — a *seed*, not a choice (objectui#4035).
+ *
+ * ⚠️ **The value is per-USER; the slot is per-DEVICE (objectui#10193).**
+ * `GET /auth/me/localization` answers `locale` as the caller's own
+ * `sys_user.locale` when set, else the request's `Accept-Language`, else the
+ * deployment default — and answers no locale at all before sign-in. It is not
+ * a tenant setting, whatever earlier prose here said. The slot is deliberately
+ * NOT keyed by user: the boot reads it before anyone is signed in, when no
+ * user id exists to key by. What bounds it to one owner is
+ * `@object-ui/auth`'s change-of-owner purge (objectui#5664), which deletes it
+ * when a different user adopts the browser, and which the host answers by
+ * re-resolving the live language (`@object-ui/app-shell`'s
+ * `useSignedInUserLocale`).
+ *
+ * **What a visitor who is not signed in reads**, declared as device behaviour:
+ * the language the LAST signed-in owner of this browser was served, until
+ * someone else signs in. That is the only server answer this device has ever
+ * received — the endpoint gives none before sign-in — and the sign-in page is
+ * the one surface it paints.
  *
  * 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).
+ * - {@link LOCALE_STORAGE_KEY} is what the *user* picked on this device. It
+ *   outranks everything this provider can see and must survive a change in
+ *   what the server answers for the seed below. ⚠️ It does NOT outrank the signed-in user's own
+ *   `sys_user.locale`, which no tier here represents — see that key's own
+ *   docblock (objectui#10059).
+ * - This slot is what the server resolved for the signed-in caller, 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
+ * deliberate user choice, so it would (a) outrank a later server-side 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.
+ * Read the cached locale seed — the server's last resolved locale for this
+ * browser's last signed-in caller (see {@link LOCALE_SEED_STORAGE_KEY}) — 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,
@@ -97,12 +139,13 @@ export function readCachedLanguageSeed() {
     }
 }
 /**
- * Cache the tenant locale the server just answered with — the "revalidate" half
- * of the stale-while-revalidate contract (objectstack#5419, ruling point 2).
+ * Cache the locale the server just resolved for the signed-in caller — 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
+ * than leaving the old value: a server answer that drops the 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.
  *
@@ -126,18 +169,27 @@ export function cacheLanguageSeed(locale) {
     }
 }
 /**
- * Languages `createI18n(config)` will know about *synchronously*: the built-in
- * packs plus any extra `config.resources`.
+ * Languages this renderer ships or was handed: a built-in catalogue, or an
+ * entry in `config.resources`.
+ *
+ * ⚠️ Since objectui#7479 a built-in catalogue is FETCHED, not statically
+ * resident, so "known" here no longer means "renderable on the very next
+ * frame" — it means this provider can produce it without asking the app, which
+ * is the question every caller of this predicate is actually asking (may this
+ * stored value be restored; may this seed be honoured). The one caller that
+ * needs the stricter reading is the bootstrap itself, and it gets it by
+ * AWAITING {@link preloadBootstrapLocale} before render rather than by asking a
+ * different predicate.
  *
  * `hasOwnProperty` rather than `in`: a junk stored value like `constructor`
- * would pass an `in` check against the locale map's prototype.
+ * would pass an `in` check against a plain object's prototype.
  */
 function isStaticallyKnownLanguage(lang, config) {
     const own = Object.prototype.hasOwnProperty;
-    return own.call(builtInLocales, lang) || Boolean(config?.resources && own.call(config.resources, lang));
+    return isBuiltInLanguage(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));
+const BUILT_IN_LANGUAGE_CODES = BUILT_IN_CODES;
 /**
  * Every language this renderer can produce *without asking the app*: the
  * built-in packs plus `config.resources`.
@@ -193,7 +245,10 @@ function canResolveLanguage(lang, config, hasLoader = false) {
     return hasLoader && isWellFormedLanguageTag(lang);
 }
 /**
- * Adjudicate a tenant locale seed into a language this renderer can actually
+ * Adjudicate the locale seed — the last signed-in owner's cached server
+ * answer (their `sys_user.locale`, else `Accept-Language`, else the deployment
+ * default), bounded to that one owner by the objectui#5664 purge; see
+ * {@link LOCALE_SEED_STORAGE_KEY} — 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
@@ -202,23 +257,23 @@ function canResolveLanguage(lang, config, hasLoader = false) {
  * 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.
+ * **1. Exact tag first, then its base language** — the registry's
+ * `matchLanguageTag`, the one implementation of that order in this package
+ * (objectui#11326). A seed is a full BCP-47 tag — the platform answers
+ * `zh-CN`, not `zh` (see `LocalizationFetchProvider`'s fixtures). Since
+ * objectui#11326 the built-in packs answer a region-tagged code themselves
+ * (`zh-CN` is served by the `zh` catalogue), so for them the exact step
+ * already succeeds and the seed boots in the tag the server stated; the base
+ * step is what still reaches an app-supplied `config.resources` pack keyed by
+ * base language. Exact first, so a genuine `pt-BR` pack still wins over `pt`.
  *
  * **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
+ * `provisional` self-heal. A seed has neither property — it is whatever the
+ * server resolved (a stored column, a request header, a deployment default),
+ * it 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
@@ -226,16 +281,12 @@ function canResolveLanguage(lang, config, hasLoader = false) {
  * 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;
+    return matchLanguageTag(seed, (code) => canResolveLanguage(code, config));
 }
 /**
- * The tenant tier: a cached server seed, applied only when the user has
- * expressed no choice of their own (objectui#4035).
+ * The seed tier: the last signed-in owner's cached server answer (see
+ * {@link LOCALE_SEED_STORAGE_KEY}), applied only when nobody has expressed a
+ * choice on this device (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.
@@ -253,9 +304,9 @@ function resolveSeedBootstrap(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.
+        // `detectBrowserLanguage: false` is what makes the seed tier outrank the
+        // environment tier. What the server resolved for this device's signed-in
+        // owner beats the browser's incidental setting — ruling point 1.
         config: { ...config, defaultLanguage: resolved, detectBrowserLanguage: false },
         provisional: null,
     };
@@ -263,16 +314,16 @@ function resolveSeedBootstrap(config) {
 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.
+    // covers the 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.
+    // No explicit choice at all → the 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 —
+        // A purged choice is no choice, so this falls to the same seed tier —
         // otherwise dropping one unshippable stored value would skip the seed and
         // land straight on the browser language.
         return resolveSeedBootstrap(config) ?? { config, provisional: null };
@@ -282,7 +333,106 @@ function resolveBootstrapConfig(config, persist, hasLoader) {
         provisional: isStaticallyKnownLanguage(stored, config) ? null : stored,
     };
 }
+/**
+ * The language {@link I18nProvider} will boot in, computed WITHOUT creating an
+ * i18next instance (objectui#7479).
+ *
+ * The full precedence chain, unchanged: explicit choice → seed →
+ * browser language → `defaultLanguage` → `en`.
+ */
+export function resolveBootstrapLanguage(options = {}) {
+    const { config, persistLanguage = true, hasLoader = false } = options;
+    const resolved = resolveBootstrapConfig(config, persistLanguage, hasLoader);
+    return pickInitialLanguage(resolved.config);
+}
+/**
+ * Fetch the catalogue {@link I18nProvider} will boot in, BEFORE you render it.
+ *
+ * ## Why a host would await this
+ *
+ * Built-in catalogues are lazy since objectui#7479, so the provider can be in
+ * one of two states on its first render, and the difference is visible:
+ *
+ *   - **catalogue already resident** — the first paint is in the user's
+ *     language, exactly as it was when all ten packs shipped eagerly;
+ *   - **catalogue still in flight** — the first paint renders through
+ *     `fallbackLng: 'en'` and re-renders in the user's language when the fetch
+ *     lands. Correct, never blank, and a flash of English for a `zh-CN` viewer.
+ *
+ * ⇒ any host that owns an await before `createRoot().render()` should spend it
+ * here; `apps/console/src/main.tsx` does, alongside the runtime-config and auth
+ * preflight round-trips it already waits on. A host that has no such seam gets
+ * the documented `en`-while-loading behaviour instead, which is why this is a
+ * function a host CALLS rather than a requirement the provider imposes.
+ *
+ * Never rejects: a catalogue that will not download must not take the boot
+ * down, and the provider retries on mount.
+ */
+export async function preloadBootstrapLocale(options = {}) {
+    try {
+        await loadBuiltInLocale(resolveBootstrapLanguage(options));
+    }
+    catch (err) {
+        console.warn('[i18n] Failed to preload the bootstrap locale catalogue:', err);
+    }
+}
 const ObjectI18nContext = createContext(null);
+/**
+ * Re-render a reader when the store GAINS translations, not only when the
+ * language changes (objectui#10382).
+ *
+ * react-i18next re-renders a `useTranslation` reader on the events its
+ * `bindI18n` / `bindI18nStore` options name, and `bindI18nStore` defaults to
+ * none. So a bundle added after mount — the `loadLanguage` answer, a built-in
+ * catalogue that lands late — reached nobody who had already rendered: they
+ * kept drawing the fallback until something unrelated re-rendered them. The
+ * provider's old remedy, setting its `language` state to the value it already
+ * held, was a same-value update React bails out of.
+ *
+ * With `added` bound, every store write bumps react-i18next's own revision and
+ * hands each reader a NEW `t`. That is more than a re-render: a reader that
+ * memoises on `t`, or on a resolver built from it (`useObjectLabel`'s return
+ * value, the column memo in `ObjectDataTable`), recomputes too — a re-render
+ * alone would leave it on the fallback.
+ *
+ * Passed per call rather than set on the instance, so it holds for an instance
+ * the host built itself (the `instance` prop) and does not leak into
+ * react-i18next's process-wide defaults. `useTranslation` spreads this argument
+ * over the instance's `react` options before its `subscribe` reads
+ * `bindI18nStore` (measured in `react-i18next@17.0.11`, `useTranslation.js`).
+ * The hook's typings do not list the key, so the type borrows it from i18next's
+ * `ReactOptions`, where it is declared. Module-level so its identity is stable:
+ * `useTranslation` keys its options memo, and with it the subscription, on it.
+ *
+ * ⚠️ The price: every store write re-renders every reader and re-runs whatever
+ * keys on `t`. So the provider writes a built-in catalogue only when the merge
+ * adds something ({@link mergeAddsKeys}), and writes silently where
+ * `languageChanged` follows and re-renders once anyway.
+ */
+const STORE_WRITES_RERENDER = Object.freeze({ bindI18nStore: 'added' });
+/** For the switch path's writes: `changeLanguage` announces them, once, in the new language. */
+const SILENT_WRITE = Object.freeze({ silent: true });
+function isNested(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Whether `addResourceBundle(…, deep: true, overwrite: false)` of `source` into
+ * `target` would write anything — a key `target` lacks, at any depth where
+ * both sides hold objects. Mirrors i18next's `deepExtend` with `overwrite` off,
+ * which leaves a key present on both sides alone when either value is not an
+ * object, so such a key adds nothing.
+ */
+function mergeAddsKeys(target, source) {
+    for (const key of Object.keys(source)) {
+        if (!(key in target))
+            return true;
+        const into = target[key];
+        const from = source[key];
+        if (isNested(into) && isNested(from) && mergeAddsKeys(into, from))
+            return true;
+    }
+    return false;
+}
 /**
  * I18nProvider - Wraps your app with i18n support
  *
@@ -345,6 +495,52 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
             i18nInstance.off('languageChanged', handleLanguageChanged);
         };
     }, [i18nInstance, persistLanguage]);
+    // Fetch the BUILT-IN catalogue for whatever language this instance booted
+    // into (objectui#7479). A host that awaited `preloadBootstrapLocale` finds it
+    // already resident and this resolves without a network round-trip; a host
+    // that did not gets the documented `en`-while-loading render and this is what
+    // ends it.
+    //
+    // ⛔ `overwrite: false` on the merge, unlike the app-specific bundle below.
+    // `createI18n` has already deep-merged `config.resources` over an EMPTY
+    // built-in bundle, so overwriting here would let a catalogue that arrives
+    // late silently undo the caller's own overrides — a precedence inversion
+    // whose only symptom is that it depends on network timing.
+    //
+    // The write is what re-renders anything already on screen in the `en`
+    // fallback ({@link STORE_WRITES_RERENDER}); ⛔ never a `setLanguage` here,
+    // which would set the state this effect was keyed on and bail out
+    // (objectui#10382). And ⛔ never an unconditional write: this effect re-runs
+    // on every language change, and after a switch through `changeLanguage`
+    // (which already merged the catalogue), or for a catalogue that was resident
+    // when the instance was created, the write would add nothing and still
+    // re-render every reader.
+    useEffect(() => {
+        const currentLang = i18nInstance.language || 'en';
+        if (!isBuiltInLanguage(currentLang))
+            return;
+        let cancelled = false;
+        void loadBuiltInLocale(currentLang)
+            .then((catalogue) => {
+            if (cancelled || !catalogue)
+                return;
+            const bundle = i18nInstance.getResourceBundle(currentLang, 'translation');
+            if (isNested(bundle)) {
+                if (!mergeAddsKeys(bundle, catalogue))
+                    return;
+                i18nInstance.addResourceBundle(currentLang, 'translation', catalogue, true, false);
+            }
+            else {
+                i18nInstance.addResourceBundle(currentLang, 'translation', catalogue);
+            }
+        })
+            .catch((err) => {
+            console.warn(`[i18n] Failed to load the built-in catalogue for '${currentLang}':`, err);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [i18nInstance, language]);
     // Load app-specific translations for the initial language on mount
     useEffect(() => {
         if (!loadLanguage)
@@ -355,9 +551,13 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
         loadedAppLangs.current.add(currentLang);
         loadLanguage(currentLang).then((resources) => {
             if (resources && Object.keys(resources).length > 0) {
+                // The write itself re-renders every reader already on screen
+                // ({@link STORE_WRITES_RERENDER}). ⛔ No `setLanguage(currentLang)`
+                // after it (objectui#10382): on the first load that sets the state to
+                // the value it already holds, which React bails out of; and when the
+                // user switched while this was in flight, it set the context back to
+                // the boot language while i18next stayed on the new one.
                 i18nInstance.addResourceBundle(currentLang, 'translation', resources, true, true);
-                // Force re-render so components pick up newly loaded translations
-                setLanguage(currentLang);
             }
         }).catch((err) => {
             // Allow retry on failure by removing from loaded set
@@ -441,12 +641,36 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
     const contextValue = useMemo(() => ({
         language,
         changeLanguage: async (lang) => {
+            // The built-in catalogue first (objectui#7479): a switch to a language
+            // whose pack has never been fetched must RESOLVE it, not render the
+            // `en` fallback and hope the mount effect catches up. Awaited before
+            // `changeLanguage` so the switch and the strings land on the same
+            // frame — the whole point of doing it here rather than reactively.
+            //
+            // Both writes below are SILENT. The `changeLanguage` that follows emits
+            // `languageChanged` — i18next emits it for every language it resolves,
+            // the current one included (measured in `i18next@26.4.0`,
+            // `changeLanguage`) — and that re-renders every reader once, in the
+            // new language. An `added` event here would re-render each of them in
+            // the OLD language first ({@link STORE_WRITES_RERENDER}).
+            const builtIn = await loadBuiltInLocale(lang).catch((err) => {
+                console.warn(`[i18n] Failed to load the built-in catalogue for '${lang}':`, err);
+                return null;
+            });
+            if (builtIn) {
+                if (i18nInstance.hasResourceBundle(lang, 'translation')) {
+                    i18nInstance.addResourceBundle(lang, 'translation', builtIn, true, false, SILENT_WRITE);
+                }
+                else {
+                    i18nInstance.addResourceBundle(lang, 'translation', builtIn, false, false, SILENT_WRITE);
+                }
+            }
             // Dynamic language pack loading (v2.0.7)
             if (loadLanguage && !loadedAppLangs.current.has(lang)) {
                 loadedAppLangs.current.add(lang);
                 try {
                     const resources = await loadLanguage(lang);
-                    i18nInstance.addResourceBundle(lang, 'translation', resources, true, true);
+                    i18nInstance.addResourceBundle(lang, 'translation', resources, true, true, SILENT_WRITE);
                 }
                 catch (err) {
                     loadedAppLangs.current.delete(lang);
@@ -474,7 +698,68 @@ export function I18nProvider({ config, instance: externalInstance, loadLanguage,
  */
 export function useObjectTranslation(ns) {
     const context = useContext(ObjectI18nContext);
-    const { t, i18n } = useTranslation(ns);
+    // Subscribed to store writes as well as language changes, so translations
+    // added after this reader rendered reach it (objectui#10382).
+    const { t: boundT, i18n } = useTranslation(ns, STORE_WRITES_RERENDER);
+    // Whether react-i18next found an i18next instance at all — from props,
+    // from an `I18nextProvider` above, or from the module-level global that
+    // `createI18n` installs via `initReactI18next`.
+    //
+    // Read off the returned instance rather than the `ready` flag, and that is
+    // the load-bearing part. `useTranslation` returns `i18n || {}`, so a plain
+    // object with no `t` is exactly and only the no-instance case; `ready` is
+    // ALSO false for a real instance whose namespace is still loading, and there
+    // `t` is i18next's own `getFixedT` result, which interpolates already.
+    // Keying on `ready` would run a second interpolation pass over a string
+    // i18next had already filled — measured in
+    // `react-i18next@17.0.11/dist/es/useTranslation.js`, where `getSnapshot`
+    // returns `notReadySnapshot` under `if (!i18n)` and nothing else.
+    const hasInstance = typeof i18n?.t === 'function';
+    // objectui#6219. With no instance, react-i18next hands back `notReadyT`,
+    // which returns `options.defaultValue` **verbatim**: an inline default
+    // written `'Deleted {{count}} rows'` reached the user with the braces intact
+    // on every host that embeds an ObjectUI component without `I18nProvider` —
+    // the configuration `createSafeTranslation` exists for (objectui#3865), so a
+    // supported one rather than a hypothetical.
+    //
+    // This is the ONE seam: 68 inline defaults across 24 files were rendering
+    // through it, and every one of them is fixed here instead of at the call
+    // sites. It is deliberately NOT a rewrite of those call sites — at a bare
+    // `useObjectTranslation()` the pre-interpolated template literal
+    // (`` `Deleted ${n} rows` ``) is the CORRECT spelling and stays correct
+    // (there is no hole left to fill), so both shapes now render right and
+    // neither is residue. objectui#4905 specified the opposite rewrite and it
+    // would have introduced this defect at 29 more sites.
+    //
+    // Scope, stated as narrowly as it is implemented: this widens WHICH BINDINGS
+    // interpolate on the provider-less path. It does not widen WHICH SPELLINGS
+    // resolve — that fork is objectui#3512's, which ruled deliberately against
+    // teaching the fallback i18next's other three dialects, and this change
+    // keeps that ruling by routing through the same one interpolator
+    // (`fallbackInterpolation.ts`) that `createSafeTranslation`'s `fallbackT`
+    // uses. With an instance present, `boundT` is returned untouched: i18next
+    // does its own interpolation and must never be double-processed.
+    const t = useMemo(() => {
+        if (hasInstance)
+            return boundT;
+        const interpolating = (...args) => {
+            const rendered = boundT(...args);
+            // `notReadyT` can also answer with a key array's last member or `''` for
+            // a function key. Only a string can carry a hole; anything else is
+            // handed back exactly as react-i18next produced it.
+            if (typeof rendered !== 'string')
+                return rendered;
+            return interpolateFallback(rendered, optionsOf(args));
+        };
+        // The cast restores react-i18next's `TFunction` overloads for the ~700
+        // call sites that destructure `t` — the wrapper is argument-transparent by
+        // construction (it forwards `...args` untouched), so the declared type
+        // still describes it.
+        return interpolating;
+        // `notReadyT` is a module constant in react-i18next, so on this path
+        // `boundT` is referentially stable and so is the wrapper — which matters,
+        // because call sites put `t` in `useMemo`/`useCallback` dependency arrays.
+    }, [boundT, hasInstance]);
     return {
         /** Translation function */
         t,

package/dist/translateFn.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/**
+ * i18next's `t`, narrowed to the one call shape a plain helper needs: a key,
+ * optional interpolation / `defaultValue` options, and a string back.
+ *
+ * ⭐ This is the ONE authority for the name (objectui#8261, executing the
+ * maintainer's ruling on objectui#8165, option A). A module that is handed a
+ * `t` rather than calling a translation hook itself — a toast emitter, a size
+ * guard, a message builder — types that parameter with this and imports it.
+ * ⛔ It does not declare its own copy: `@object-ui/app-shell` and
+ * `@object-ui/fields` each carried a byte-identical one until this change, and
+ * both now re-export this declaration instead
+ * (`export type { TranslateFn } from '@object-ui/i18n'`).
+ *
+ * `scripts/__tests__/one-authority-per-exported-name-6273.test.ts` is what
+ * re-derives that there is one authority: it reads such a re-export as a
+ * re-export, and a second `export type TranslateFn = …` anywhere in a
+ * published package's source as a collision.
+ *
+ * Why this package and not `@object-ui/types`: it is a translation-function
+ * shape, not a schema type — the ruling's own ground.
+ */
+export type TranslateFn = (key: string, options?: Record<string, unknown>) => string;

package/dist/translateFn.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};

package/dist/useDisplayLocale.d.ts

@@ -33,6 +33,17 @@
  *     since `useObjectTranslation` falls back to the react-i18next global
  *     instance and ultimately reports `'en'` itself.
  *
+ *     ⚠️ This last resort is the rule for THIS HOOK — a React renderer whose
+ *     provider chain yielded no tag at all — and not for every caller that has
+ *     no tag. A non-React display caller cannot call a hook, and
+ *     `@object-ui/core` deliberately gives it a different answer:
+ *     `DisplayNumberFormatOptions.locale`
+ *     (`packages/core/src/utils/number-display.ts`) says `undefined` there
+ *     means the runtime default, because the viewer's own environment is the
+ *     honest locale for a user-facing display. The two rules govern different
+ *     callers and do not contradict each other (objectui#10098); that docblock
+ *     names this one in return.
+ *
  * 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.

package/dist/useDisplayLocale.js

@@ -35,6 +35,17 @@ import { useObjectTranslation } from './provider.js';
  *     since `useObjectTranslation` falls back to the react-i18next global
  *     instance and ultimately reports `'en'` itself.
  *
+ *     ⚠️ This last resort is the rule for THIS HOOK — a React renderer whose
+ *     provider chain yielded no tag at all — and not for every caller that has
+ *     no tag. A non-React display caller cannot call a hook, and
+ *     `@object-ui/core` deliberately gives it a different answer:
+ *     `DisplayNumberFormatOptions.locale`
+ *     (`packages/core/src/utils/number-display.ts`) says `undefined` there
+ *     means the runtime default, because the viewer's own environment is the
+ *     honest locale for a user-facing display. The two rules govern different
+ *     callers and do not contradict each other (objectui#10098); that docblock
+ *     names this one in return.
+ *
  * 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.