@object-ui/i18n 17.6.0 → 17.7.0

package/dist/i18n.d.ts

@@ -10,7 +10,15 @@ export interface I18nConfig {
     defaultLanguage?: string;
     /** Fallback language (default: 'en') */
     fallbackLanguage?: string;
-    /** Additional translation resources to merge with built-in locales */
+    /**
+     * Additional translation resources, **deep-merged** over the built-in packs.
+     *
+     * The packs' top-level keys are the namespace groups (`common`, `calendar`,
+     * `list`, ...), so supplying a partial group merges into it and leaves the
+     * group's other keys in place:
+     * `{ en: { calendar: { today: 'Heute' } } }` overrides `calendar.today` only.
+     * Arrays are replaced wholesale, never concatenated (objectui#7572).
+     */
     resources?: Record<string, Record<string, unknown>>;
     /** Whether to detect browser language automatically (default: true) */
     detectBrowserLanguage?: boolean;
@@ -39,6 +47,24 @@ export interface I18nConfig {
  * API — shared between `i18n.ts` and `useObjectLabel.ts` to avoid drift.
  */
 export declare const I18N_PROBE_FLAG = "__ouiLabelProbe";
+/**
+ * The language {@link createI18n} will boot in for this config — `defaultLanguage`,
+ * overridden by a browser language this renderer can produce.
+ *
+ * Exported because the answer is needed BEFORE an instance exists
+ * (objectui#7479): with the catalogues lazy, a host that wants its first render
+ * to already be in the right language has to know which catalogue to await, and
+ * the only alternative — create an instance, read `.language`, throw it away —
+ * would boot i18next in the wrong locale to find out what the right one is.
+ * `I18nProvider` and {@link preloadBootstrapLocale} answer with THIS function,
+ * so the host and the provider cannot disagree about which catalogue is active.
+ *
+ * ⚠️ Browser detection is asked of {@link isBuiltInLanguage} rather than of the
+ * merged resource map: a catalogue that has not been fetched yet is still a
+ * language this renderer can produce, and asking the map would have made
+ * detection depend on load order.
+ */
+export declare function pickInitialLanguage(config?: I18nConfig): string;
 /**
  * Create and initialize an i18next instance with Object UI defaults
  */

package/dist/i18n.js

@@ -5,7 +5,8 @@
  */
 import i18next from 'i18next';
 import { initReactI18next } from 'react-i18next';
-import { builtInLocales, isRTL } from './locales/index.js';
+import { BUILT_IN_LANGUAGE_CODES, getLoadedBuiltInLocales, isBuiltInLanguage, } from './locales/registry.js';
+import { isRTL } from './locales/rtl.js';
 /**
  * Internal `t()` option flag set by `useObjectLabel` on its convention-key
  * probes. The missing-key handler skips any lookup carrying this flag, so the
@@ -37,19 +38,108 @@ function createMissingKeyHandler() {
         console.warn(`[object-ui i18n] Missing translation for "${key}" (language "${lng}") — falling back to ${fb}.`);
     };
 }
+/**
+ * A plain object — the only shape the resource merge recurses into. Arrays and
+ * `null` are excluded on purpose; see {@link deepMergeTranslations}.
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Deep-merge caller-supplied translations over a built-in language pack.
+ *
+ * A language pack's top-level keys ARE the namespace groups (`common`,
+ * `calendar`, `list`, ...), each a nested object, so the one-level merge this
+ * replaced made `resources: { en: { calendar: { today: 'Heute' } } }` **replace**
+ * the whole `calendar` group: `month` / `week` / `day` / `allDay` / `newEvent` /
+ * `moreEvents` / `unscheduled` left the instance, `t('calendar.allDay')` returned
+ * the bare key, and `calendar.allDay` reached the DOM as literal text
+ * (objectui#7572). Packs nest up to four levels below the group
+ * (`console.ai.empty.build.title`), so the merge recurses rather than adding one
+ * fixed extra level.
+ *
+ * ARRAYS ARE REPLACED, NOT CONCATENATED — a deliberate choice, not a library
+ * default. Measured: no built-in pack carries an array value today (every leaf
+ * in all ten packs is a string), so nothing observable rides on this; the rule
+ * decides what a future array means. An author who writes an array is naming the
+ * whole list, so replacement is the only rule that lets them shorten or reorder
+ * one, and the only one that is idempotent when the merge runs again. This is
+ * narrower than i18next's own `deepExtend` (which the provider's async
+ * `addResourceBundle` path uses): that recurses into arrays index-wise and would
+ * leave a longer base array's tail behind — the same silent-hybrid shape this
+ * issue is about.
+ *
+ * `__proto__` is skipped. Recursive assignment, unlike the object spread it
+ * replaces, would otherwise reach the prototype setter; i18next's `deepExtend`
+ * guards the same key.
+ */
+function deepMergeTranslations(base, override) {
+    const merged = { ...base };
+    for (const key of Object.keys(override)) {
+        if (key === '__proto__')
+            continue;
+        const incoming = override[key];
+        const existing = merged[key];
+        merged[key] =
+            isPlainObject(existing) && isPlainObject(incoming)
+                ? deepMergeTranslations(existing, incoming)
+                : incoming;
+    }
+    return merged;
+}
+/**
+ * The language {@link createI18n} will boot in for this config — `defaultLanguage`,
+ * overridden by a browser language this renderer can produce.
+ *
+ * Exported because the answer is needed BEFORE an instance exists
+ * (objectui#7479): with the catalogues lazy, a host that wants its first render
+ * to already be in the right language has to know which catalogue to await, and
+ * the only alternative — create an instance, read `.language`, throw it away —
+ * would boot i18next in the wrong locale to find out what the right one is.
+ * `I18nProvider` and {@link preloadBootstrapLocale} answer with THIS function,
+ * so the host and the provider cannot disagree about which catalogue is active.
+ *
+ * ⚠️ Browser detection is asked of {@link isBuiltInLanguage} rather than of the
+ * merged resource map: a catalogue that has not been fetched yet is still a
+ * language this renderer can produce, and asking the map would have made
+ * detection depend on load order.
+ */
+export function pickInitialLanguage(config = {}) {
+    const { defaultLanguage = 'en', resources = {}, detectBrowserLanguage = true } = config;
+    if (!detectBrowserLanguage || typeof navigator === 'undefined')
+        return defaultLanguage;
+    const browserLang = navigator.language?.split('-')[0];
+    if (!browserLang)
+        return defaultLanguage;
+    const known = isBuiltInLanguage(browserLang) ||
+        Object.prototype.hasOwnProperty.call(resources, browserLang);
+    return known ? browserLang : defaultLanguage;
+}
 /**
  * Create and initialize an i18next instance with Object UI defaults
  */
 export function createI18n(config = {}) {
-    const { defaultLanguage = 'en', fallbackLanguage = 'en', resources = {}, detectBrowserLanguage = true, interpolation, warnMissingKeys = isDevEnv(), } = config;
-    // Merge built-in locales with user-provided resources
+    const { fallbackLanguage = 'en', resources = {}, interpolation, warnMissingKeys = isDevEnv(), } = config;
+    // `defaultLanguage` and `detectBrowserLanguage` are read by
+    // {@link pickInitialLanguage}, which owns that precedence for this function
+    // AND for the hosts that must know the answer before an instance exists.
+    // Merge the catalogues that are RESIDENT with user-provided resources.
+    //
+    // ⛔ Every built-in code gets a bundle here even when its catalogue has not
+    // been fetched yet (objectui#7479). The empty bundle is load-bearing, not a
+    // placeholder: it keeps `instance.options.resources` — which
+    // {@link getAvailableLanguages}, the browser detection below and i18next's
+    // own `hasResourceBundle` all read — enumerating every language this package
+    // can produce, instead of shrinking to whatever happened to be loaded at
+    // instance-creation time. Until the catalogue lands, `fallbackLng` renders
+    // those keys through `en`; `I18nProvider` then deep-merges the real
+    // catalogue in WITHOUT overwriting anything `resources` put there, so the
+    // precedence below survives the async arrival.
     const mergedResources = {};
-    for (const [lang, translations] of Object.entries(builtInLocales)) {
+    const residentCatalogues = getLoadedBuiltInLocales();
+    for (const lang of BUILT_IN_LANGUAGE_CODES) {
         mergedResources[lang] = {
-            translation: {
-                ...translations,
-                ...(resources[lang] || {}),
-            },
+            translation: deepMergeTranslations((residentCatalogues[lang] ?? {}), resources[lang] || {}),
         };
     }
     // Add any additional languages from resources not in built-in locales
@@ -58,14 +148,7 @@ export function createI18n(config = {}) {
             mergedResources[lang] = { translation: translations };
         }
     }
-    // Detect browser language if enabled
-    let lng = defaultLanguage;
-    if (detectBrowserLanguage && typeof navigator !== 'undefined') {
-        const browserLang = navigator.language?.split('-')[0];
-        if (browserLang && mergedResources[browserLang]) {
-            lng = browserLang;
-        }
-    }
+    const lng = pickInitialLanguage(config);
     const instance = i18next.createInstance();
     // IMPORTANT: disable react-i18next Suspense. Otherwise `useTranslation()`
     // calls during bootstrap throw a Suspense promise (the i18n instance is

package/dist/index.d.ts

@@ -30,25 +30,19 @@
  *
  * @packageDocumentation
  */
-export { createI18n, getDirection, getAvailableLanguages, type I18nConfig, type TranslationKeys } from './i18n.js';
-export { I18nProvider, useObjectTranslation, useI18nContext, LOCALE_STORAGE_KEY, readStoredLanguage, LOCALE_SEED_STORAGE_KEY, readCachedLanguageSeed, cacheLanguageSeed, type I18nProviderProps, } from './provider.js';
+export { createI18n, getDirection, getAvailableLanguages, pickInitialLanguage, type I18nConfig, type TranslationKeys, } from './i18n.js';
+export { I18nProvider, useObjectTranslation, useI18nContext, LOCALE_STORAGE_KEY, readStoredLanguage, LOCALE_SEED_STORAGE_KEY, readCachedLanguageSeed, cacheLanguageSeed, resolveBootstrapLanguage, preloadBootstrapLocale, type BootstrapLocaleOptions, type I18nProviderProps, } from './provider.js';
 export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation.js';
+export { builtinAggregateLabels, type SafeTranslate } from './builtinAggregateLabels.js';
+export type { TranslateFn } from './translateFn.js';
 export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel.js';
-export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index.js';
+export { isRTL, RTL_LANGUAGES } from './locales/rtl.js';
+export { BUILT_IN_LANGUAGE_CODES, DEFAULT_BUILT_IN_LANGUAGE, getLoadedBuiltInLocales, isBuiltInLanguage, isBuiltInLocaleLoaded, loadBuiltInLocale, type LocaleCatalogue, } from './locales/registry.js';
 export { default as en } from './locales/en.js';
-export { default as zh } from './locales/zh.js';
-export { default as ja } from './locales/ja.js';
-export { default as ko } from './locales/ko.js';
-export { default as de } from './locales/de.js';
-export { default as fr } from './locales/fr.js';
-export { default as es } from './locales/es.js';
-export { default as pt } from './locales/pt.js';
-export { default as ru } from './locales/ru.js';
-export { default as ar } from './locales/ar.js';
 export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './utils/index.js';
 export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './utils/index.js';
 export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './utils/index.js';
-export { pickLocalized, setLocalized } from './pickLocalized.js';
+export { pickLocalized, setLocalized, clearLocalized } from './pickLocalized.js';
 export { LocalizationProvider, useLocalization, type LocalizationValue } from './LocalizationContext.js';
 export { resolveFieldCurrency } from './currency.js';
 export { useDisplayLocale } from './useDisplayLocale.js';

package/dist/index.js

@@ -31,33 +31,57 @@
  * @packageDocumentation
  */
 // Core i18n setup
-export { createI18n, getDirection, getAvailableLanguages } from './i18n.js';
+export { createI18n, getDirection, getAvailableLanguages, pickInitialLanguage, } from './i18n.js';
 // React integration
 export { I18nProvider, useObjectTranslation, useI18nContext, 
 // Language-preference persistence: the key the provider writes, and the
 // reader apps that bring their own i18next instance need to honour it.
 LOCALE_STORAGE_KEY, readStoredLanguage, 
-// Tenant locale seed (objectui#4035) — a SEPARATE slot from the explicit
-// choice above, and never a substitute for it. An app that fetches its
-// tenant's server-side locale caches it here; the provider applies it at
+// Locale seed (objectui#4035) — a SEPARATE slot from the explicit
+// choice above, and never a substitute for it. An app that fetches the
+// server's resolved locale for the last signed-in caller caches it here; the provider applies it at
 // bootstrap only when the user has chosen nothing themselves.
-LOCALE_SEED_STORAGE_KEY, readCachedLanguageSeed, cacheLanguageSeed, } from './provider.js';
+LOCALE_SEED_STORAGE_KEY, readCachedLanguageSeed, cacheLanguageSeed, 
+// Resolve the boot language, and fetch its catalogue, BEFORE first render
+// (objectui#7479). A host with an await before `createRoot().render()` spends
+// it here and paints in the user's language; a host without one gets the
+// documented `en`-while-loading render instead.
+resolveBootstrapLanguage, preloadBootstrapLocale, } from './provider.js';
 // Safe translation hook factory
 export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation.js';
+// objectui#7258 — locale labels for the server's built-in default measures,
+// handed to core's `buildChartSeries` as `builtinAggregateLabels`.
+export { builtinAggregateLabels } from './builtinAggregateLabels.js';
 // Convention-based object/field label i18n
 export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel.js';
-// Locale packs
-export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index.js';
+// Locale packs — ⛔ ONE catalogue is statically re-exported here, not ten
+// (objectui#7479).
+//
+// This entry used to re-export all ten packs and `builtInLocales`, which made
+// every one of them statically reachable from any import of this package. The
+// console measured the result: ~450 KB gzipped of translation data in the EAGER
+// closure, ten catalogues fetched before first paint for a viewer who reads
+// one, and every new key paid for by every visitor in every language.
+//
+// ⛔ Do not restore a static re-export of a second catalogue here, and do not
+// re-export `builtInLocales` from this entry. Both put all ten back:
+// `builtInLocales` names every pack in one object literal, so nothing can shake
+// it. `scripts/check-eager-locale-catalogues.mjs` fails the build if a
+// non-active catalogue reappears in the console's eager closure, and
+// `src/__tests__/entry-locale-shape-7479.test.ts` fails on the SOURCE shape so
+// the reason is legible without a console build.
+//
+// What replaced them:
+//   - `en` stays — it is `fallbackLng`, the source of `TranslationKeys`, and
+//     the synchronous dictionary the app-shell splash renders from before i18n
+//     is usable. See `./locales/registry.js` for the full argument.
+//   - `loadBuiltInLocale(code)` fetches any of the ten on demand.
+//   - `BUILT_IN_LANGUAGE_CODES` enumerates them at zero payload.
+//   - `@object-ui/i18n/locales` is the explicit, published door to all ten for
+//     a caller that genuinely wants them all resident (the parity suites do).
+export { isRTL, RTL_LANGUAGES } from './locales/rtl.js';
+export { BUILT_IN_LANGUAGE_CODES, DEFAULT_BUILT_IN_LANGUAGE, getLoadedBuiltInLocales, isBuiltInLanguage, isBuiltInLocaleLoaded, loadBuiltInLocale, } from './locales/registry.js';
 export { default as en } from './locales/en.js';
-export { default as zh } from './locales/zh.js';
-export { default as ja } from './locales/ja.js';
-export { default as ko } from './locales/ko.js';
-export { default as de } from './locales/de.js';
-export { default as fr } from './locales/fr.js';
-export { default as es } from './locales/es.js';
-export { default as pt } from './locales/pt.js';
-export { default as ru } from './locales/ru.js';
-export { default as ar } from './locales/ar.js';
 // Formatting utilities
 export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from './utils/index.js';
 // Spec-aligned formatters (v2.0.7)
@@ -66,7 +90,7 @@ export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } f
 // `useObjectLabel`). Exposed so apps don't have to copy/paste — see
 // `apps/console/src/loadLanguage.ts` for the canonical consumer.
 export { isSpecTranslationData, transformSpecTranslations, } from './utils/index.js';
-export { pickLocalized, setLocalized } from './pickLocalized.js';
+export { pickLocalized, setLocalized, clearLocalized } from './pickLocalized.js';
 export { LocalizationProvider, useLocalization } from './LocalizationContext.js';
 export { resolveFieldCurrency } from './currency.js';
 // The one number-display formatter (objectui#4033) and the locale it formats