@object-ui/i18n 17.2.0 → 17.5.0

package/README.md

@@ -21,7 +21,6 @@ npm install @object-ui/i18n
 
 **Peer Dependencies:**
 - `react` ^18.0.0 || ^19.0.0
-- `react-dom` ^18.0.0 || ^19.0.0
 
 ## Quick Start
 
@@ -61,6 +60,32 @@ Wraps your application with i18n context:
 </I18nProvider>
 ```
 
+#### Language persistence
+
+The active language is a **user preference**, so it survives a reload: every
+language change is written to `localStorage` under `objectui-locale`
+(`LOCALE_STORAGE_KEY`), and the provider boots the next session in that
+language.
+
+Precedence at bootstrap: **stored choice → browser language → `defaultLanguage`**.
+An explicit choice outranks browser detection — otherwise a user who picked 中文
+on a `ja` browser would be handed `ja` back on every reload. A stored value the
+app no longer offers (not a built-in pack, not in `config.resources`) is ignored
+*and purged*, so a stale entry can never lock the UI to a locale with no
+translations.
+
+```tsx
+// Fixed-language surfaces (previews, demos, screenshot harnesses) opt out —
+// they neither restore nor write the preference.
+<I18nProvider config={{ defaultLanguage: 'en' }} persistLanguage={false}>
+  <Preview />
+</I18nProvider>
+```
+
+Bringing your own `instance`? Then its bootstrap language is yours to choose —
+read the preference with `readStoredLanguage()` and pass it to `createI18n`.
+Switching through such an instance is still persisted.
+
 ### useObjectTranslation
 
 Hook for translations and language management:
@@ -110,20 +135,8 @@ isRTL('ar'); // true
 isRTL('en'); // false
 ```
 
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
-
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/packages/i18n)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/i18n)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/index.d.ts

@@ -31,7 +31,7 @@
  * @packageDocumentation
  */
 export { createI18n, getDirection, getAvailableLanguages, type I18nConfig, type TranslationKeys } from './i18n';
-export { I18nProvider, useObjectTranslation, useI18nContext, type I18nProviderProps } from './provider';
+export { I18nProvider, useObjectTranslation, useI18nContext, LOCALE_STORAGE_KEY, readStoredLanguage, LOCALE_SEED_STORAGE_KEY, readCachedLanguageSeed, cacheLanguageSeed, type I18nProviderProps, } from './provider';
 export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation';
 export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel';
 export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index';
@@ -51,3 +51,5 @@ export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationD
 export { pickLocalized } from './pickLocalized';
 export { LocalizationProvider, useLocalization, type LocalizationValue } from './LocalizationContext';
 export { resolveFieldCurrency } from './currency';
+export { useDisplayLocale } from './useDisplayLocale';
+export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './utils/index';

package/dist/index.js

@@ -33,7 +33,15 @@
 // Core i18n setup
 export { createI18n, getDirection, getAvailableLanguages } from './i18n';
 // React integration
-export { I18nProvider, useObjectTranslation, useI18nContext } from './provider';
+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
+// bootstrap only when the user has chosen nothing themselves.
+LOCALE_SEED_STORAGE_KEY, readCachedLanguageSeed, cacheLanguageSeed, } from './provider';
 // Safe translation hook factory
 export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation';
 // Convention-based object/field label i18n
@@ -61,3 +69,8 @@ export { isSpecTranslationData, transformSpecTranslations, } from './utils/index
 export { pickLocalized } from './pickLocalized';
 export { LocalizationProvider, useLocalization } from './LocalizationContext';
 export { resolveFieldCurrency } from './currency';
+// The one number-display formatter (objectui#4033) and the locale it formats
+// in. Every field cell / widget / metric renderer goes through this pair —
+// see `utils/number-display.ts` for the grouping policy and its interim status.
+export { useDisplayLocale } from './useDisplayLocale';
+export { formatDisplayNumber, shouldGroupDisplayNumber, } from './utils/index';