@object-ui/i18n 17.3.0 → 17.6.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
 
@@ -136,20 +135,50 @@ 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)
+## Scope — the `engine.*` carve-out (metadata-admin / Studio)
+
+Not every user-facing string in this repository resolves through these packs.
+The metadata-admin (Studio) surface — the metadata directory, the inspectors,
+package management, the flow designer and their refusal messages — resolves its
+`engine.*` keys through a module-local **two-locale** table in
+[`packages/app-shell/src/views/metadata-admin/i18n.ts`](../app-shell/src/views/metadata-admin/i18n.ts):
+a plain `Record` lookup over `en-US` and `zh-CN`, not an i18next namespace.
+Roughly 1,300 keys per locale live there, and **no `engine.*` key exists in any
+of the ten packs.**
+
+That is design, not drift — the file's header records it as "Phase 3f". The
+server holds the primary path: the engine consumes `label` from the
+`/meta/types` response, sourced from the platform's metadata-type registry. The
+module-local table is a **fallback** for deployments with no translation bundles
+configured, and the interim source of truth for Chinese until the platform's
+`setup.translation.ts` ships zh-CN coverage. Copying the namespace into the
+packs would duplicate strings whose primary source is a server response.
+
+Two consequences follow, and both are accepted rather than outstanding work:
+
+- **Only `en` and `zh` are covered.** On an `ar` / `de` / `es` / `fr` / `ja` /
+  `ko` / `pt` / `ru` console, `engine.*` strings render English. That is the
+  price of the carve-out, not a backfill someone forgot.
+- **The i18n gates cannot see this namespace, by construction.** Key parity
+  ([`src/__tests__/all-locales-key-parity.test.ts`](./src/__tests__/all-locales-key-parity.test.ts))
+  compares pack against pack, and `engine.*` is in no pack — so it is not an
+  *exception* to that test, it is outside its subject. The call-site gate
+  ([`scripts/check-i18n-call-site-keys.mjs`](../../scripts/check-i18n-call-site-keys.mjs))
+  skips these call sites **by declaration**: the module is registered in its
+  `EXCLUDED_TRANSLATORS` list with a reason, and an imported `t` from any
+  unregistered module is a hard error there — so a second local table cannot
+  appear silently, and this carve-out cannot quietly widen.
+
+**When to revisit.** Migrating the namespace into the packs is mechanical but
+wide (~1,300 keys × 8 further locales) and argues against the server-driven
+design above, so it is not worth doing speculatively. The condition to reopen it
+is concrete: a stated demand for an admin console in a language other than `en`
+or `zh` — not a general wish for broader locale coverage, which the packs
+already serve on every other surface. See objectui#4662 for the measurement and
+the ruling.
 
 ## 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/i18n.d.ts

@@ -4,7 +4,7 @@
  * Wraps i18next with Object UI defaults and built-in locale support.
  */
 import { type i18n as I18nInstance } from 'i18next';
-import type { TranslationKeys } from './locales/en';
+import type { TranslationKeys } from './locales/en.js';
 export interface I18nConfig {
     /** Default language (default: 'en') */
     defaultLanguage?: string;

package/dist/i18n.js

@@ -5,7 +5,7 @@
  */
 import i18next from 'i18next';
 import { initReactI18next } from 'react-i18next';
-import { builtInLocales, isRTL } from './locales/index';
+import { builtInLocales, isRTL } from './locales/index.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
@@ -34,7 +34,6 @@ function createMissingKeyHandler() {
             return;
         seen.add(dedupeKey);
         const fb = fallbackValue ? `"${fallbackValue}"` : 'the key itself';
-        // eslint-disable-next-line no-console
         console.warn(`[object-ui i18n] Missing translation for "${key}" (language "${lng}") — falling back to ${fb}.`);
     };
 }

package/dist/index.d.ts

@@ -30,24 +30,26 @@
  *
  * @packageDocumentation
  */
-export { createI18n, getDirection, getAvailableLanguages, type I18nConfig, type TranslationKeys } from './i18n';
-export { I18nProvider, useObjectTranslation, useI18nContext, LOCALE_STORAGE_KEY, readStoredLanguage, type I18nProviderProps, } from './provider';
-export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation';
-export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel';
-export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index';
-export { default as en } from './locales/en';
-export { default as zh } from './locales/zh';
-export { default as ja } from './locales/ja';
-export { default as ko } from './locales/ko';
-export { default as de } from './locales/de';
-export { default as fr } from './locales/fr';
-export { default as es } from './locales/es';
-export { default as pt } from './locales/pt';
-export { default as ru } from './locales/ru';
-export { default as ar } from './locales/ar';
-export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from './utils/index';
-export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, type SpecPluralRule, type SpecDateFormat, type SpecNumberFormat, type SpecLocaleConfig, } from './utils/index';
-export { isSpecTranslationData, transformSpecTranslations, type SpecTranslationData, } from './utils/index';
-export { pickLocalized } from './pickLocalized';
-export { LocalizationProvider, useLocalization, type LocalizationValue } from './LocalizationContext';
-export { resolveFieldCurrency } from './currency';
+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 { createSafeTranslation, useSafeTranslate } from './useSafeTranslation.js';
+export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel.js';
+export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index.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 { LocalizationProvider, useLocalization, type LocalizationValue } from './LocalizationContext.js';
+export { resolveFieldCurrency } from './currency.js';
+export { useDisplayLocale } from './useDisplayLocale.js';
+export { formatDisplayNumber, shouldGroupDisplayNumber, type DisplayNumberFormatOptions, } from './utils/index.js';

package/dist/index.js

@@ -31,36 +31,46 @@
  * @packageDocumentation
  */
 // Core i18n setup
-export { createI18n, getDirection, getAvailableLanguages } from './i18n';
+export { createI18n, getDirection, getAvailableLanguages } 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, } from './provider';
+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.js';
 // Safe translation hook factory
-export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation';
+export { createSafeTranslation, useSafeTranslate } from './useSafeTranslation.js';
 // Convention-based object/field label i18n
-export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel';
+export { useObjectLabel, useSafeFieldLabel } from './useObjectLabel.js';
 // Locale packs
-export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index';
-export { default as en } from './locales/en';
-export { default as zh } from './locales/zh';
-export { default as ja } from './locales/ja';
-export { default as ko } from './locales/ko';
-export { default as de } from './locales/de';
-export { default as fr } from './locales/fr';
-export { default as es } from './locales/es';
-export { default as pt } from './locales/pt';
-export { default as ru } from './locales/ru';
-export { default as ar } from './locales/ar';
+export { builtInLocales, isRTL, RTL_LANGUAGES } from './locales/index.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';
+export { formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from './utils/index.js';
 // Spec-aligned formatters (v2.0.7)
-export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } from './utils/index';
+export { resolvePlural, formatDateSpec, formatNumberSpec, applyLocaleConfig, } from './utils/index.js';
 // Spec TranslationData → flat namespace transform (consumed by
 // `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';
-export { pickLocalized } from './pickLocalized';
-export { LocalizationProvider, useLocalization } from './LocalizationContext';
-export { resolveFieldCurrency } from './currency';
+export { isSpecTranslationData, transformSpecTranslations, } from './utils/index.js';
+export { pickLocalized, setLocalized } 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
+// 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.js';
+export { formatDisplayNumber, shouldGroupDisplayNumber, } from './utils/index.js';