@object-ui/i18n 17.6.0 → 17.7.0

package/README.md

@@ -1,15 +1,16 @@
 # @object-ui/i18n
 
-Internationalization for Object UI — 11 built-in locales, RTL support, and date/currency formatting.
+Internationalization for Object UI — 10 built-in locales, RTL support, and date/currency formatting.
 
 ## Features
 
-- 🌍 **11 Built-in Locales** - English, Chinese, Japanese, Korean, German, French, Spanish, Portuguese, Russian, Arabic, and more
+- 🌍 **10 Built-in Locales** - English, Chinese, Japanese, Korean, German, French, Spanish, Portuguese, Russian, Arabic
 - 🔄 **RTL Support** - Automatic right-to-left layout for Arabic and other RTL languages
 - 📅 **Date Formatting** - Locale-aware date, datetime, and relative time formatting
 - 💰 **Currency & Number Formatting** - Locale-aware currency and number formatting
 - 🎣 **React Hooks** - `useObjectTranslation` for translations, language switching, and direction
 - 🏗️ **I18nProvider** - Context provider for internationalized applications
+- 🪶 **Lazy catalogues** - only the active locale's catalogue is fetched; the other nine are separate chunks
 - 🔌 **Extensible** - Add custom locales and translation keys
 - 🎯 **Type-Safe** - Full TypeScript support with exported types
 
@@ -55,9 +56,15 @@ function MyComponent() {
 Wraps your application with i18n context:
 
 ```tsx
+import type { ReactNode } from 'react';
+import { I18nProvider } from '@object-ui/i18n';
+
+// Your app supplies the tree being wrapped.
+declare const App: () => ReactNode;
+
 <I18nProvider config={{ defaultLanguage: 'en', fallbackLanguage: 'en' }}>
   <App />
-</I18nProvider>
+</I18nProvider>;
 ```
 
 #### Language persistence
@@ -72,14 +79,21 @@ 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.
+translations. A region-tagged choice such as `zh-CN` is served by its base
+language's built-in pack (`zh`), so it is kept, and kept as written: the
+provider's `language`, `<html lang>` and the stored value all stay `zh-CN`.
 
 ```tsx
+import type { ReactNode } from 'react';
+import { I18nProvider } from '@object-ui/i18n';
+
+declare const Preview: () => ReactNode;
+
 // Fixed-language surfaces (previews, demos, screenshot harnesses) opt out —
 // they neither restore nor write the preference.
 <I18nProvider config={{ defaultLanguage: 'en' }} persistLanguage={false}>
   <Preview />
-</I18nProvider>
+</I18nProvider>;
 ```
 
 Bringing your own `instance`? Then its bootstrap language is yours to choose —
@@ -91,9 +105,47 @@ Switching through such an instance is still persisted.
 Hook for translations and language management:
 
 ```tsx
-const { t, language, changeLanguage, direction } = useObjectTranslation();
+import { useObjectTranslation } from '@object-ui/i18n';
+
+function LanguageBar() {
+  const { t, language, changeLanguage, direction } = useObjectTranslation();
+
+  return (
+    <div dir={direction}>
+      {t('common.save')} — {language}
+      <button onClick={() => changeLanguage('zh')}>中文</button>
+    </div>
+  );
+}
+```
+
+#### Count labels are i18next count families
+
+A label a word must agree with — `3 replies`, `Approve 3 requests?` — is one
+i18next count family: pass the number as `count` and let i18next pick the slot
+`Intl.PluralRules` selects for the language. Every pack spells out each
+category its language has (`en` `_one`/`_other`; `ru` adds `_few`/`_many`; `ar`
+has all six), plus a count-invariant base key for a call made without a count.
+
+```tsx
+import { useObjectTranslation } from '@object-ui/i18n';
+
+function ReplyCount({ replies }: { replies: readonly string[] }) {
+  const { t } = useObjectTranslation();
+
+  // "1 reply", "3 replies"; Russian «3 ответа», «5 ответов»
+  return <span>{t('detail.replyCount', { count: replies.length })}</span>;
+}
 ```
 
+Pass `count` as a **number** — i18next selects a slot for nothing else — and
+never choose the key yourself (`count === 1 ? 'xOne' : 'x'`): two keys give a
+language two forms, and Russian needs three, Arabic five. A
+`createSafeTranslation` defaults table answers the same way on a provider-less
+host: it reads a family's `_one` / `_other` row for a numeric `count`, then the
+base row. `count-families-11445.test.ts` holds every `{{count}}` value in the
+ten packs to this rule.
+
 ### createI18n
 
 Factory for creating an i18n instance outside React:
@@ -105,27 +157,128 @@ const i18n = createI18n({ defaultLanguage: 'de' });
 i18n.t('common.cancel'); // "Abbrechen"
 ```
 
+### TranslateFn — typing a `t` you are handed
+
+A helper that receives `t` from its caller, rather than calling a hook itself,
+types that parameter with `TranslateFn`: i18next's `t` narrowed to
+`(key: string, options?: Record<string, unknown>) => string`. This package is
+the one authority for that type — import it rather than declaring a local
+copy:
+
+```ts
+import type { TranslateFn } from '@object-ui/i18n';
+
+export function saveLabel(t: TranslateFn): string {
+  return t('common.save');
+}
+```
+
 ### Formatting Utilities
 
 Locale-aware formatting functions:
 
+Each formatter takes the value first and an **options object** second; the
+locale is a field on that object (`DateFormatOptions`, `CurrencyFormatOptions`,
+`NumberFormatOptions`), never a positional argument. `formatRelativeTime` is the
+one exception: it takes the locale directly, and derives the unit from how far
+the date is from now.
+
 ```tsx
 import { formatDate, formatCurrency, formatNumber, formatRelativeTime } from '@object-ui/i18n';
 
-formatDate(new Date(), 'en');            // "Jan 1, 2025"
-formatCurrency(99.99, 'USD', 'en');      // "$99.99"
-formatNumber(1234567, 'de');             // "1.234.567"
-formatRelativeTime(-3, 'days', 'en');    // "3 days ago"
+formatDate(new Date(2025, 0, 1), { locale: 'en' });              // "Jan 1, 2025"
+formatCurrency(99.99, { currency: 'USD', locale: 'en' });        // "$99.99"
+formatNumber(1234567, { locale: 'de' });                         // "1.234.567"
+formatRelativeTime(Date.now() - 3 * 86_400_000, 'en');           // "3 days ago"
 ```
 
-### Built-in Locales
+A date-only string such as `'2026-09-01'` names a calendar day: every date
+helper reads it as that day in every viewer's time zone (`formatDateTime` shows
+its midnight, and `formatRelativeTime` counts to the start of it). A string
+with a time part is an instant, read in the viewer's zone. `formatDateSpec`
+applies its `timeZone` to an instant only.
 
-Import individual locale packs:
+### Built-in locales — one is resident, nine are fetched on demand
+
+The package entry re-exports **`en` only**. It is `fallbackLng`, it is the
+source of the `TranslationKeys` type, and it is the synchronous dictionary the
+app-shell splash renders from before i18n is usable, so it has to be there
+without awaiting anything. The other nine catalogues are separate chunks your
+bundler emits once each and the browser fetches only when that locale is
+actually used — roughly 400 KB gzipped that a page load no longer pays
+(objectui#7479).
 
 ```tsx
-import { en, zh, ja, ko, de, fr, es, pt, ru, ar } from '@object-ui/i18n';
+import {
+  en,                        // resident
+  BUILT_IN_LANGUAGE_CODES,   // all ten codes, no catalogue payload
+  isBuiltInLanguage,
+  loadBuiltInLocale,         // fetch one: Promise<catalogue | null>
+  getLoadedBuiltInLocales,   // synchronous snapshot of what is resident
+} from '@object-ui/i18n';
+
+BUILT_IN_LANGUAGE_CODES;            // ['en','zh','ja','ko','de','fr','es','pt','ru','ar']
+await loadBuiltInLocale('zh');      // the zh catalogue, fetched once and memoised
+await loadBuiltInLocale('zh-CN');   // the same zh catalogue — a region tag is served by its base
+await loadBuiltInLocale('tlh');     // null — not a code this package ships
+isBuiltInLanguage('zh-CN');         // true
+isBuiltInLanguage('xx-YY');         // false — no catalogue for the tag or its base
 ```
 
+A code is looked up **exact tag first, then its base language**: `zh-CN` is
+served by the `zh` catalogue, while a catalogue keyed by a full tag would win
+over its base. `isBuiltInLanguage` and `isBuiltInLocaleLoaded` answer by the same
+rule as `loadBuiltInLocale`, and a catalogue is memoised under its own code, so
+`zh` and `zh-CN` share one fetch.
+
+`I18nProvider` does this for you: it fetches the catalogue for whatever language
+it boots into, and `changeLanguage()` awaits the new catalogue before switching,
+so a switcher needs no extra wiring.
+
+#### Resolving before the first render
+
+Without a resolve, a provider booting into `zh` paints once through the `en`
+fallback — correct strings, never a raw key — and re-renders in Chinese when the
+catalogue lands. If your app already awaits something before mounting, spend
+that await here instead and the first paint is already right:
+
+```tsx
+import { I18nProvider, preloadBootstrapLocale, resolveBootstrapLanguage } from '@object-ui/i18n';
+import { createRoot } from 'react-dom/client';
+import type { FC } from 'react';
+
+declare const App: FC;
+declare const container: HTMLElement;
+declare const loadLanguage: (lang: string) => Promise<Record<string, unknown>>;
+
+// Pass the SAME options you will pass to <I18nProvider>, or the two will
+// disagree about which language this boot is in.
+await preloadBootstrapLocale({ hasLoader: true });
+createRoot(container).render(
+  <I18nProvider loadLanguage={loadLanguage}>
+    <App />
+  </I18nProvider>,
+);
+
+resolveBootstrapLanguage({ hasLoader: true }); // 'zh' — the same answer, no fetch
+```
+
+`preloadBootstrapLocale` never rejects: a catalogue that will not download must
+not take the boot down, and the provider retries on mount.
+`apps/console/src/main.tsx` is the worked example.
+
+#### When you really do want all ten
+
+The parity suites do, and so does an app that ships every language resident. The
+door is a separate specifier, so the cost is visible at the import site:
+
+```tsx
+import { builtInLocales, zh, ru } from '@object-ui/i18n/locales';
+```
+
+⚠️ That module statically imports every catalogue. Never reach for it on a
+page-load path — that is exactly the eager payload the split removed.
+
 ### RTL Helpers
 
 ```tsx
@@ -135,6 +288,32 @@ isRTL('ar'); // true
 isRTL('en'); // false
 ```
 
+### Localized value helpers — reading and editing an `I18nLabel`
+
+Server-driven metadata types a label as a plain string **or** an inline
+per-locale map (`{ en: 'Pricing', 'zh-CN': '定价' }`). An authoring surface that
+shows one locale in one text input has to answer three separate questions, so
+there are three functions and each answers exactly one:
+
+```tsx
+import { pickLocalized, setLocalized, clearLocalized } from '@object-ui/i18n';
+
+const stored = { en: 'Pricing', 'zh-CN': '定价' };
+
+pickLocalized(stored, 'en-US');          // 'Pricing'   — which entry to DISPLAY
+setLocalized(stored, 'en-US', 'Plans');  // { en: 'Plans', 'zh-CN': '定价' }
+clearLocalized(stored, 'en-US');         // { 'zh-CN': '定价' }
+```
+
+⛔ Never write the input's string back as the whole value — that replaces the
+map and every locale the author was not looking at is gone, silently, on the
+first keystroke. `setLocalized` replaces **one** entry (adding it when the
+active locale has none) and `clearLocalized` removes **one** entry (returning
+`undefined` once nothing localized is left). Both choose that entry with the
+same limbs, and deliberately stop short of `pickLocalized`'s display-only
+fallbacks, so an author editing in `fr` while shown the `en` string can neither
+overwrite nor delete English.
+
 ## Scope — the `engine.*` carve-out (metadata-admin / Studio)
 
 Not every user-facing string in this repository resolves through these packs.

package/dist/builtinAggregateLabels.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+/**
+ * objectui#7258 — the locale labels for the analytics service's BUILT-IN
+ * default measures, keyed by the wire discriminator a result field carries as
+ * `builtinAggregate` (producer half: objectstack#14492).
+ *
+ * `@object-ui/core`'s `buildChartSeries` cannot read the locale bundle (that
+ * package is React-free and i18n-free by design), so this is the seam: the
+ * renderer that holds the provider resolves the six strings ONCE through its
+ * `useSafeTranslate()` and hands the map to core as
+ * `ChartSeriesOptions.builtinAggregateLabels` — the same division of labour
+ * `chart.nullCategory` already makes for the null bucket's label.
+ *
+ * The keys are the `report.aggregate.*` family the matrix report and the
+ * dashboard's aggregate charts already read, not a second namespace: the
+ * vocabulary (Count / Sum / Average / …) is the same on every surface, so ten
+ * packs already carry it and a new key would only add drift surface. The only
+ * mapping done here is spelling — the wire enum says `count_distinct`, the
+ * bundle key says `countDistinct`.
+ *
+ * The English fallbacks are byte-equal to the `en` pack's values, so a
+ * provider-less host renders exactly what an `en` session renders (pinned in
+ * `__tests__/builtinAggregateLabels-locale-parity-7258.test.ts`).
+ */
+import type { BuiltinAggregate } from '@object-ui/core';
+/** The per-call translate shape `useSafeTranslate()` returns: first real translation, else the English fallback. */
+export type SafeTranslate = (key: string, fallback: string) => string;
+/**
+ * Resolve the display label of every built-in aggregate through the locale
+ * bundle. Typed as the FULL record on purpose: a member added to core's
+ * `BUILTIN_AGGREGATES` without a line here is a compile error, not a legend
+ * that silently falls back to the server's English.
+ */
+export declare function builtinAggregateLabels(tt: SafeTranslate): Record<BuiltinAggregate, string>;

package/dist/builtinAggregateLabels.js

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+/**
+ * Resolve the display label of every built-in aggregate through the locale
+ * bundle. Typed as the FULL record on purpose: a member added to core's
+ * `BUILTIN_AGGREGATES` without a line here is a compile error, not a legend
+ * that silently falls back to the server's English.
+ */
+export function builtinAggregateLabels(tt) {
+    return {
+        count: tt('report.aggregate.count', 'Count'),
+        count_distinct: tt('report.aggregate.countDistinct', 'Distinct Count'),
+        sum: tt('report.aggregate.sum', 'Sum'),
+        avg: tt('report.aggregate.avg', 'Average'),
+        min: tt('report.aggregate.min', 'Min'),
+        max: tt('report.aggregate.max', 'Max'),
+    };
+}

package/dist/currency.d.ts

@@ -7,12 +7,35 @@
  */
 /**
  * Resolve the display currency code for a currency-typed field, in precedence
- * order: the field's explicit `currency` -> its `currencyConfig.defaultCurrency`
- * (fixed mode) -> a legacy top-level `defaultCurrency` -> the tenant default
- * (`localization.currency`, ADR-0053, surfaced via {@link useLocalization}).
+ * order:
+ *
+ *  1. the field's explicit `currency` — a per-node display code. The spec
+ *     declares it on presentation surfaces (the metric widget's `currency`, a
+ *     dataset measure's `currency`) and looser grid/column configs carry it;
+ *     `FieldSchema` itself refuses it as a field key;
+ *  2. `currencyConfig.defaultCurrency`, ONLY when `currencyConfig.currencyMode`
+ *     is `'fixed'` — the spec's one fixed-currency declaration;
+ *  3. a legacy top-level `defaultCurrency` — a pre-spec spelling that
+ *     `FieldSchema` refuses as an unrecognized key, kept in place so configs
+ *     written against it still read their code;
+ *  4. the tenant default (`localization.currency`, ADR-0053, surfaced via
+ *     {@link useLocalization}).
+ *
  * Returns `undefined` when none is known, so the renderer shows a plain number
  * rather than guessing a symbol.
  *
+ * `currencyMode: 'dynamic'` — and a `currencyConfig` with no `currencyMode` at
+ * all, which `@objectstack/spec` defaults to `'dynamic'` — skips step 2
+ * (objectui#10422). The spec describes that mode as "user selectable", and its
+ * `FieldSchema` guidance says a field without a fixed currency "uses the tenant
+ * default at runtime". No value carries a user-selected code today (a currency
+ * value is a bare number), so a dynamic field reads the tenant default, never
+ * its `defaultCurrency`. That matters beyond authored dynamic configs: the
+ * spec parses an EMPTY `currencyConfig` to
+ * `{ currencyMode: 'dynamic', defaultCurrency: 'CNY' }`, which must not render
+ * as yuan. If a value ever carries its own selected code, that code is the one
+ * to win, ahead of the tenant default.
+ *
  * This is the single resolution every field / measure / cell renderer shares -
  * ending the per-renderer drift where some read only `currency`, others only
  * `defaultCurrency`, and others `currencyConfig`. It lives in `@object-ui/i18n`
@@ -23,6 +46,7 @@ export declare function resolveFieldCurrency(field: {
     currency?: string;
     defaultCurrency?: string;
     currencyConfig?: {
+        currencyMode?: 'dynamic' | 'fixed';
         defaultCurrency?: string;
     };
 } | null | undefined, tenantDefault?: string): string | undefined;

package/dist/currency.js

@@ -7,12 +7,35 @@
  */
 /**
  * Resolve the display currency code for a currency-typed field, in precedence
- * order: the field's explicit `currency` -> its `currencyConfig.defaultCurrency`
- * (fixed mode) -> a legacy top-level `defaultCurrency` -> the tenant default
- * (`localization.currency`, ADR-0053, surfaced via {@link useLocalization}).
+ * order:
+ *
+ *  1. the field's explicit `currency` — a per-node display code. The spec
+ *     declares it on presentation surfaces (the metric widget's `currency`, a
+ *     dataset measure's `currency`) and looser grid/column configs carry it;
+ *     `FieldSchema` itself refuses it as a field key;
+ *  2. `currencyConfig.defaultCurrency`, ONLY when `currencyConfig.currencyMode`
+ *     is `'fixed'` — the spec's one fixed-currency declaration;
+ *  3. a legacy top-level `defaultCurrency` — a pre-spec spelling that
+ *     `FieldSchema` refuses as an unrecognized key, kept in place so configs
+ *     written against it still read their code;
+ *  4. the tenant default (`localization.currency`, ADR-0053, surfaced via
+ *     {@link useLocalization}).
+ *
  * Returns `undefined` when none is known, so the renderer shows a plain number
  * rather than guessing a symbol.
  *
+ * `currencyMode: 'dynamic'` — and a `currencyConfig` with no `currencyMode` at
+ * all, which `@objectstack/spec` defaults to `'dynamic'` — skips step 2
+ * (objectui#10422). The spec describes that mode as "user selectable", and its
+ * `FieldSchema` guidance says a field without a fixed currency "uses the tenant
+ * default at runtime". No value carries a user-selected code today (a currency
+ * value is a bare number), so a dynamic field reads the tenant default, never
+ * its `defaultCurrency`. That matters beyond authored dynamic configs: the
+ * spec parses an EMPTY `currencyConfig` to
+ * `{ currencyMode: 'dynamic', defaultCurrency: 'CNY' }`, which must not render
+ * as yuan. If a value ever carries its own selected code, that code is the one
+ * to win, ahead of the tenant default.
+ *
  * This is the single resolution every field / measure / cell renderer shares -
  * ending the per-renderer drift where some read only `currency`, others only
  * `defaultCurrency`, and others `currencyConfig`. It lives in `@object-ui/i18n`
@@ -20,8 +43,9 @@
  * concern; `@object-ui/fields` re-exports it for backward compatibility.
  */
 export function resolveFieldCurrency(field, tenantDefault) {
+    const config = field?.currencyConfig;
     return (field?.currency ||
-        field?.currencyConfig?.defaultCurrency ||
+        (config?.currencyMode === 'fixed' ? config.defaultCurrency : undefined) ||
         field?.defaultCurrency ||
         tenantDefault ||
         undefined);

package/dist/fallbackInterpolation.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The ONE interpolator every provider-less translation path in this package
+ * runs — extracted so there is exactly one of it (objectui#6219).
+ *
+ * ## Why this module exists at all
+ *
+ * Three things can render a translation in this repo, and each has its own
+ * answer to "does a `{{hole}}` get filled?":
+ *
+ *   1. **i18next, with an `I18nProvider` mounted.** It interpolates. This is
+ *      the reference behaviour every other path has to agree with.
+ *   2. **`createSafeTranslation`'s `fallbackT`** (`useSafeTranslation.ts`).
+ *      It interpolates — with the exact literal needle below.
+ *   3. **react-i18next's not-ready `t`**, which is what a bare
+ *      `useObjectTranslation()` yields when no i18next instance is initialised.
+ *      Measured in `react-i18next@17.0.11/dist/es/useTranslation.js`:
+ *      `notReadyT` returns `options.defaultValue` VERBATIM and does not
+ *      interpolate at all.
+ *
+ * (3) was objectui#6219: 68 inline defaults across 24 files carried a
+ * `{{hole}}` that reached the user as literal braces on any host that embeds an
+ * ObjectUI component without `I18nProvider` — the configuration
+ * `createSafeTranslation` exists for (objectui#3865), so a supported one.
+ * `useObjectTranslation` now runs its not-ready result through this function,
+ * which makes (3) agree with (2), and (2) already agrees with (1) for the one
+ * spelling this repo is allowed to author.
+ *
+ * ## Why one shared function rather than a second copy
+ *
+ * The semantics below are pinned in three places at once —
+ * `useSafeTranslation.test.tsx` (behaviour), `fallback-placeholder-spelling-3512.test.ts`
+ * (the copy is held to what this can resolve) and
+ * `scripts/check-i18n-call-site-keys.mjs` class 7 (the same rule over inline
+ * defaults). A second interpolator with its own drift would have made all three
+ * of those true of one path and quietly false of the other. There is one
+ * function, so "the fallback resolves only `{{name}}`" is one fact.
+ *
+ * ## The exact spelling, and why only that one
+ *
+ * objectui#3512 measured that i18next additionally accepts `{{ name }}`,
+ * `{{count, number}}`, `{{- name}}` and `$t(key)`, and the ruling was
+ * deliberately NOT to teach the fallback three more dialects (a second
+ * interpolator to keep in step with i18next forever) but to hold the copy to
+ * the one spelling both paths agree on — enforced by the two gates named above.
+ * This module keeps that ruling: it widens WHICH BINDINGS interpolate, never
+ * WHICH SPELLINGS resolve.
+ */
+/**
+ * The i18next option that names the string to use when the lookup misses.
+ *
+ * It is a LOOKUP CONTROL, not interpolation data (objectui#3865): it chooses
+ * which string is rendered, so it must never also be spliced into a
+ * `{{defaultValue}}` hole in the string it chose — or in any other.
+ */
+export declare const DEFAULT_VALUE_OPTION = "defaultValue";
+/**
+ * Fill `{{name}}` holes in `value` from `options`, i18next-compatibly.
+ *
+ * Returns `value` untouched when there is nothing to fill from, so a caller can
+ * hand it every result unconditionally.
+ *
+ * @param value - The string that was chosen for rendering.
+ * @param options - The `t()` call's options object, or `undefined`.
+ */
+export declare function interpolateFallback(value: string, options?: Record<string, unknown>): string;
+/**
+ * The options object of a `t()` call, or `undefined` when the call passed none.
+ *
+ * i18next's `t` accepts both `t(key, options)` and `t(key, defaultValue,
+ * options)`, so the options object is the LAST argument when it is an object at
+ * all. A string second argument is a default value, not data — there is nothing
+ * to interpolate from, which is why `t(key, 'Hi {{name}}')` keeps its braces on
+ * both paths.
+ *
+ * Arrays are excluded deliberately: `t(key, [...])` is not an i18next options
+ * shape, and `Object.entries` over one would mint `{{0}}`-style needles that no
+ * copy in this repo spells.
+ */
+export declare function optionsOf(args: readonly unknown[]): Record<string, unknown> | undefined;

package/dist/fallbackInterpolation.js

@@ -0,0 +1,124 @@
+/**
+ * The ONE interpolator every provider-less translation path in this package
+ * runs — extracted so there is exactly one of it (objectui#6219).
+ *
+ * ## Why this module exists at all
+ *
+ * Three things can render a translation in this repo, and each has its own
+ * answer to "does a `{{hole}}` get filled?":
+ *
+ *   1. **i18next, with an `I18nProvider` mounted.** It interpolates. This is
+ *      the reference behaviour every other path has to agree with.
+ *   2. **`createSafeTranslation`'s `fallbackT`** (`useSafeTranslation.ts`).
+ *      It interpolates — with the exact literal needle below.
+ *   3. **react-i18next's not-ready `t`**, which is what a bare
+ *      `useObjectTranslation()` yields when no i18next instance is initialised.
+ *      Measured in `react-i18next@17.0.11/dist/es/useTranslation.js`:
+ *      `notReadyT` returns `options.defaultValue` VERBATIM and does not
+ *      interpolate at all.
+ *
+ * (3) was objectui#6219: 68 inline defaults across 24 files carried a
+ * `{{hole}}` that reached the user as literal braces on any host that embeds an
+ * ObjectUI component without `I18nProvider` — the configuration
+ * `createSafeTranslation` exists for (objectui#3865), so a supported one.
+ * `useObjectTranslation` now runs its not-ready result through this function,
+ * which makes (3) agree with (2), and (2) already agrees with (1) for the one
+ * spelling this repo is allowed to author.
+ *
+ * ## Why one shared function rather than a second copy
+ *
+ * The semantics below are pinned in three places at once —
+ * `useSafeTranslation.test.tsx` (behaviour), `fallback-placeholder-spelling-3512.test.ts`
+ * (the copy is held to what this can resolve) and
+ * `scripts/check-i18n-call-site-keys.mjs` class 7 (the same rule over inline
+ * defaults). A second interpolator with its own drift would have made all three
+ * of those true of one path and quietly false of the other. There is one
+ * function, so "the fallback resolves only `{{name}}`" is one fact.
+ *
+ * ## The exact spelling, and why only that one
+ *
+ * objectui#3512 measured that i18next additionally accepts `{{ name }}`,
+ * `{{count, number}}`, `{{- name}}` and `$t(key)`, and the ruling was
+ * deliberately NOT to teach the fallback three more dialects (a second
+ * interpolator to keep in step with i18next forever) but to hold the copy to
+ * the one spelling both paths agree on — enforced by the two gates named above.
+ * This module keeps that ruling: it widens WHICH BINDINGS interpolate, never
+ * WHICH SPELLINGS resolve.
+ */
+/**
+ * The i18next option that names the string to use when the lookup misses.
+ *
+ * It is a LOOKUP CONTROL, not interpolation data (objectui#3865): it chooses
+ * which string is rendered, so it must never also be spliced into a
+ * `{{defaultValue}}` hole in the string it chose — or in any other.
+ */
+export const DEFAULT_VALUE_OPTION = 'defaultValue';
+/**
+ * Fill `{{name}}` holes in `value` from `options`, i18next-compatibly.
+ *
+ * Returns `value` untouched when there is nothing to fill from, so a caller can
+ * hand it every result unconditionally.
+ *
+ * @param value - The string that was chosen for rendering.
+ * @param options - The `t()` call's options object, or `undefined`.
+ */
+export function interpolateFallback(value, options) {
+    if (!options)
+        return value;
+    let out = value;
+    for (const [k, v] of Object.entries(options)) {
+        // Reserved: see DEFAULT_VALUE_OPTION. Skipped whatever its type, so an
+        // ignored non-string default cannot re-enter through this loop.
+        //
+        // This is the one deliberate divergence from i18next on this path, and it
+        // is unreachable with today's strings: i18next passes the whole options
+        // object to its interpolator, so it WOULD render
+        // `'Fallback: {{defaultValue}}'` as `'Fallback: INLINE'` (measured on
+        // 26.3.6) — but no value in this repo spells that hole (zero hits for
+        // `{{defaultValue` across packages/apps/examples), and splicing a fallback
+        // string into a hole named after itself has no sensible reading. The
+        // alternative — letting a call site's fallback text leak into an unrelated
+        // table value — is the worse of the two.
+        if (k === DEFAULT_VALUE_OPTION)
+            continue;
+        // `split(needle).join(value)` — deliberately not `replace`, and not
+        // `replaceAll` either (objectui#3418). This path must agree with i18next,
+        // which serves the *provider* path; any divergence is a silent fork that
+        // only shows up on provider-less hosts, where we are least likely to see
+        // it:
+        //   1. `replace` with a string needle substitutes only the FIRST
+        //      occurrence. i18next substitutes every one, so a sentence that
+        //      repeats a placeholder ("Selected {{count}} of {{count}} items" —
+        //      natural in many locales, and often required by RTL / agglutinative
+        //      word order) leaked literal braces to users.
+        //   2. `replace` AND `replaceAll` both interpret `$&`, `` $` ``, `$'` and
+        //      `$$` in the *replacement* string. i18next does not. Values here are
+        //      runtime data — record labels, search terms — so this one is
+        //      reachable today, unlike (1).
+        // split/join is literal on both sides, which is exactly i18next's
+        // behaviour, and needs no regex escaping of the placeholder name.
+        out = out.split(`{{${k}}}`).join(String(v));
+    }
+    return out;
+}
+/**
+ * The options object of a `t()` call, or `undefined` when the call passed none.
+ *
+ * i18next's `t` accepts both `t(key, options)` and `t(key, defaultValue,
+ * options)`, so the options object is the LAST argument when it is an object at
+ * all. A string second argument is a default value, not data — there is nothing
+ * to interpolate from, which is why `t(key, 'Hi {{name}}')` keeps its braces on
+ * both paths.
+ *
+ * Arrays are excluded deliberately: `t(key, [...])` is not an i18next options
+ * shape, and `Object.entries` over one would mint `{{0}}`-style needles that no
+ * copy in this repo spells.
+ */
+export function optionsOf(args) {
+    if (args.length < 2)
+        return undefined;
+    const last = args[args.length - 1];
+    if (typeof last !== 'object' || last === null || Array.isArray(last))
+        return undefined;
+    return last;
+}