@object-ui/i18n 17.5.0 → 17.7.0

package/dist/pickLocalized.d.ts

@@ -34,3 +34,70 @@
  * `pickLocalized({ en: 'Pricing' }, 'constructor')` is `'Pricing'`, not `''`.
  */
 export declare function pickLocalized(value: unknown, language: string | undefined | null): string;
+/**
+ * Write `next` back into a possibly-localized value as the `language` entry,
+ * preserving every other locale — the write-side inverse of
+ * {@link pickLocalized}.
+ *
+ * An authoring surface that shows one locale in one text input has to answer
+ * two questions, and they are not the same question: which entry to DISPLAY
+ * (`pickLocalized`) and which entry a save REPLACES. Answering the second with
+ * "the whole value" is the data-loss shape this function exists to remove —
+ * `onChange(e.target.value)` straight back over `{ en, zh-CN }` destroys every
+ * locale the author was not looking at, silently, on the first keystroke.
+ *
+ * - Plain string / `null` / `undefined` / array input: there is no map to
+ *   preserve, so the result is `next` itself. A string-valued label keeps
+ *   behaving exactly as it always has.
+ * - Inline locale map: the result is the same map with exactly one entry
+ *   replaced (or added — see {@link localeWriteKey}). Non-string entries and
+ *   unrelated locales are carried across untouched.
+ *
+ * The pairing with `pickLocalized` is the invariant that matters and it is
+ * pinned in `__tests__/setLocalized.test.ts`: for any map and any language,
+ * `pickLocalized(setLocalized(map, lang, s), lang) === s`. If the two functions
+ * ever drift apart, an edit lands in an entry the panel does not display and
+ * the "saved" string vanishes — which is why they live in one file.
+ *
+ * ⚠️ This is the minimal non-destructive write for a SINGLE-locale editor. It
+ * is not a multi-locale authoring UI and does not pretend to be: an author can
+ * only ever reach the entry for the locale they are in.
+ *
+ * Authoring every locale from one surface remains an OPEN product question, and
+ * is deliberately not deferred to a tracker here: the deferral this replaced
+ * named objectui#4163, which closed as completed on 2026-08-15 with the question
+ * still unanswered. A comment pointing at a closed card reads as though the
+ * question were settled somewhere, which is how the previous stale premise in
+ * this area survived unread.
+ */
+export declare function setLocalized(value: unknown, language: string | undefined | null, next: string): string | Record<string, unknown>;
+/**
+ * Remove the `language` entry from a possibly-localized value — the CLEAR arm
+ * of the same editor {@link setLocalized} serves, and the reason it cannot be
+ * spelled as `setLocalized(value, language, '')`.
+ *
+ * A single-line authoring input has three actions, not two: type, retype, and
+ * clear. `setLocalized` answers the first two. Answering the third with "write
+ * the empty string" stores `{ en: '' }` — an entry that claims "English has a
+ * title and it is blank", which then SHADOWS every display fallback: a viewer
+ * in `en` sees nothing where the map's other locales would have been offered.
+ * Answering it with "drop the whole value" is the objectui#9274 data loss
+ * itself, arriving through the clearing door instead of the typing door.
+ *
+ * So clearing removes exactly one entry — the same entry {@link setLocalized}
+ * would have written, chosen by the same {@link localeWriteKey} limbs, which is
+ * what keeps the cleared entry the one the author was actually looking at.
+ *
+ * - Plain string / `null` / `undefined` / array: there is no map, so there is
+ *   nothing localized left — `undefined`. The caller decides how its own field
+ *   spells empty (`undefined` for an optional key, `''` for a required one).
+ * - Map with the active entry present: that entry is removed and every other
+ *   locale is carried across untouched. When it was the LAST entry the result
+ *   is `undefined` rather than `{}`, because an empty map is not a title.
+ * - Map WITHOUT an entry for the active locale: returned unchanged. The box was
+ *   showing a display fallback borrowed from another locale, and clearing a
+ *   borrowed string must not delete the locale it was borrowed from — the same
+ *   refusal {@link localeWriteKey} enforces on the write side, which is why
+ *   both read the same limbs from the same file.
+ */
+export declare function clearLocalized(value: unknown, language: string | undefined | null): Record<string, unknown> | undefined;

package/dist/pickLocalized.js

@@ -69,3 +69,117 @@ export function pickLocalized(value, language) {
     }
     return String(value);
 }
+/**
+ * The map key an edit made in `language` must be WRITTEN to — the write-side
+ * twin of {@link pickLocalized}'s read limbs.
+ *
+ * It deliberately implements only the first three limbs (exact tag, base
+ * language, region-qualified sibling) and then STOPS. `pickLocalized` continues
+ * into `default` -> `en` -> first value, and those last three limbs must never
+ * be write targets: they are DISPLAY fallbacks that hand back *another*
+ * locale's string. Following them would mean an author editing in `fr`, shown
+ * the `en` entry because the map has no French, saves and overwrites English.
+ * When no entry for the active locale exists the edit ADDS one under the active
+ * tag and every stored entry survives untouched.
+ *
+ * The first three limbs are followed exactly because they identify the entry
+ * the author was actually looking at. Writing `zh` when the map stores `zh-CN`
+ * would leave the edited-away `zh-CN` string in place — invisible in the panel
+ * that just "changed" it, still live for any consumer that asks for `zh-CN`.
+ *
+ * Own properties only, `string` values only, for the same reason every
+ * `pickLocalized` limb narrowed that way in objectui#3907: a locale tag that
+ * names an `Object.prototype` member is not an entry, so it cannot be the entry
+ * the author edited.
+ */
+function localeWriteKey(o, language) {
+    const lang = (language || 'en').trim() || 'en';
+    const base = lang.split('-')[0];
+    const has = (key) => Object.prototype.hasOwnProperty.call(o, key) && typeof o[key] === 'string';
+    if (has(lang))
+        return lang;
+    if (has(base))
+        return base;
+    return Object.keys(o).find((k) => k.split('-')[0] === base && has(k)) ?? lang;
+}
+/**
+ * Write `next` back into a possibly-localized value as the `language` entry,
+ * preserving every other locale — the write-side inverse of
+ * {@link pickLocalized}.
+ *
+ * An authoring surface that shows one locale in one text input has to answer
+ * two questions, and they are not the same question: which entry to DISPLAY
+ * (`pickLocalized`) and which entry a save REPLACES. Answering the second with
+ * "the whole value" is the data-loss shape this function exists to remove —
+ * `onChange(e.target.value)` straight back over `{ en, zh-CN }` destroys every
+ * locale the author was not looking at, silently, on the first keystroke.
+ *
+ * - Plain string / `null` / `undefined` / array input: there is no map to
+ *   preserve, so the result is `next` itself. A string-valued label keeps
+ *   behaving exactly as it always has.
+ * - Inline locale map: the result is the same map with exactly one entry
+ *   replaced (or added — see {@link localeWriteKey}). Non-string entries and
+ *   unrelated locales are carried across untouched.
+ *
+ * The pairing with `pickLocalized` is the invariant that matters and it is
+ * pinned in `__tests__/setLocalized.test.ts`: for any map and any language,
+ * `pickLocalized(setLocalized(map, lang, s), lang) === s`. If the two functions
+ * ever drift apart, an edit lands in an entry the panel does not display and
+ * the "saved" string vanishes — which is why they live in one file.
+ *
+ * ⚠️ This is the minimal non-destructive write for a SINGLE-locale editor. It
+ * is not a multi-locale authoring UI and does not pretend to be: an author can
+ * only ever reach the entry for the locale they are in.
+ *
+ * Authoring every locale from one surface remains an OPEN product question, and
+ * is deliberately not deferred to a tracker here: the deferral this replaced
+ * named objectui#4163, which closed as completed on 2026-08-15 with the question
+ * still unanswered. A comment pointing at a closed card reads as though the
+ * question were settled somewhere, which is how the previous stale premise in
+ * this area survived unread.
+ */
+export function setLocalized(value, language, next) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return next;
+    const o = value;
+    return { ...o, [localeWriteKey(o, language)]: next };
+}
+/**
+ * Remove the `language` entry from a possibly-localized value — the CLEAR arm
+ * of the same editor {@link setLocalized} serves, and the reason it cannot be
+ * spelled as `setLocalized(value, language, '')`.
+ *
+ * A single-line authoring input has three actions, not two: type, retype, and
+ * clear. `setLocalized` answers the first two. Answering the third with "write
+ * the empty string" stores `{ en: '' }` — an entry that claims "English has a
+ * title and it is blank", which then SHADOWS every display fallback: a viewer
+ * in `en` sees nothing where the map's other locales would have been offered.
+ * Answering it with "drop the whole value" is the objectui#9274 data loss
+ * itself, arriving through the clearing door instead of the typing door.
+ *
+ * So clearing removes exactly one entry — the same entry {@link setLocalized}
+ * would have written, chosen by the same {@link localeWriteKey} limbs, which is
+ * what keeps the cleared entry the one the author was actually looking at.
+ *
+ * - Plain string / `null` / `undefined` / array: there is no map, so there is
+ *   nothing localized left — `undefined`. The caller decides how its own field
+ *   spells empty (`undefined` for an optional key, `''` for a required one).
+ * - Map with the active entry present: that entry is removed and every other
+ *   locale is carried across untouched. When it was the LAST entry the result
+ *   is `undefined` rather than `{}`, because an empty map is not a title.
+ * - Map WITHOUT an entry for the active locale: returned unchanged. The box was
+ *   showing a display fallback borrowed from another locale, and clearing a
+ *   borrowed string must not delete the locale it was borrowed from — the same
+ *   refusal {@link localeWriteKey} enforces on the write side, which is why
+ *   both read the same limbs from the same file.
+ */
+export function clearLocalized(value, language) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const key = localeWriteKey(o, language);
+    if (!Object.prototype.hasOwnProperty.call(o, key))
+        return o;
+    const rest = Object.fromEntries(Object.entries(o).filter(([k]) => k !== key));
+    return Object.keys(rest).length > 0 ? rest : undefined;
+}

package/dist/provider.d.ts

@@ -5,7 +5,7 @@
  */
 import React from 'react';
 import type { i18n as I18nInstance } from 'i18next';
-import { type I18nConfig } from './i18n';
+import { type I18nConfig } from './i18n.js';
 /**
  * `localStorage` key holding the user's explicit language choice.
  *
@@ -17,6 +17,22 @@ import { type I18nConfig } from './i18n';
  * 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 declare const LOCALE_STORAGE_KEY = "objectui-locale";
 /**
@@ -29,28 +45,53 @@ export declare const LOCALE_STORAGE_KEY = "objectui-locale";
  */
 export declare function readStoredLanguage(): string | null;
 /**
- * `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 declare 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,
@@ -58,12 +99,13 @@ export declare const LOCALE_SEED_STORAGE_KEY = "objectui-locale-seed";
  */
 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).
+ * 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.
  *
@@ -72,6 +114,53 @@ export declare function readCachedLanguageSeed(): string | null;
  * cannot complete.
  */
 export declare function cacheLanguageSeed(locale: string | null | undefined): void;
+/**
+ * Options shared by {@link resolveBootstrapLanguage} and
+ * {@link preloadBootstrapLocale}. Each field mirrors the {@link I18nProvider}
+ * prop of the same name, because the two must answer identically — a host that
+ * preloads one catalogue while the provider boots into another has bought a
+ * flash of `en` instead of avoiding one.
+ */
+export interface BootstrapLocaleOptions {
+    /** The `config` you will pass to {@link I18nProvider}. */
+    config?: I18nConfig;
+    /** The `persistLanguage` you will pass to {@link I18nProvider}. Default `true`. */
+    persistLanguage?: boolean;
+    /** Whether you will pass a `loadLanguage` loader. Default `false`. */
+    hasLoader?: boolean;
+}
+/**
+ * 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 declare function resolveBootstrapLanguage(options?: BootstrapLocaleOptions): string;
+/**
+ * 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 declare function preloadBootstrapLocale(options?: BootstrapLocaleOptions): Promise<void>;
 interface I18nContextValue {
     /** Current language code */
     language: string;