@chipmobilesdk/rn-i18n 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # @chipmobilesdk/rn-i18n
 
+## 0.3.0
+
+### Minor Changes
+
+- `registerRuntimeEntries` notifies subscribers, so copy a lazily loaded feature registers after its screen mounted appears instead of leaving the key on screen until something else re-rendered. Entries registered at runtime get the same validation as configured ones: a missing key or a non-string default throws `I18nConfigError` there rather than surfacing at render time. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  `init()` runs once however many times it is called — StrictMode mounts an effect twice — and loses to the user: a `setLocale` made while the persisted read was in flight is no longer overwritten by the stored value. Setting the locale that is already active changes nothing and re-renders nothing.
+
+  `i18n.useDeviceLocale()` forgets the stored choice and detects again, which is the "System language" option a settings screen offers; the storage adapter's `removeItem`, required by the contract and called by nothing, is what it uses.
+
+  Plural rules cover a compact CLDR subset instead of three languages: English and its neighbours, Korean, Chinese, Thai, Indonesian and Malay (no singular), French and Portuguese (0 is singular), Russian, Ukrainian, Polish, Czech and Slovak (`few`/`many`), and Arabic (every category). A language outside the table still falls back to "1 is singular", but now reports a `plural_rule_default` diagnostic once, rather than shipping wrong plurals in silence.
+
+  `formatDate` **merges** its options over the locale's default date format, as `formatNumber` always has: `{ month: 'long' }` keeps the year and the day. Pass `formatDate(value, options, { replaceDefaults: true })` for the old behaviour of replacing them. `formatCurrency` deliberately does not apply the locale's default number options, because a currency's own minor units must win.
+
+  The generated keys file escapes a key holding an apostrophe or a backslash, which used to produce a file that did not parse and failed `tsc` for the whole app.
+
+## 0.2.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+- Formatters come from rn-core's cache instead of being built per call. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-notification: resolving a time zone builds one `Intl.DateTimeFormat` per zone
+    instead of one per occurrence; expanding 32 series of 32 occurrences went from
+    about 230 ms to under 30 ms on Node. Zone validity is memoized.
+  - rn-i18n: number, currency and date formatters are cached. A bad option (an unknown
+    currency such as `usd1`) goes through the invalid-format policy instead of
+    throwing out of a render, and a locale's `defaultCurrency` must be a three-letter
+    ISO 4217 code at startup.
+
+- One app-lifecycle source, and a startup that needs no extra frame. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `appLifecycle()`, a shared, reference-counted `AppState` subscription that
+    reports changes only (`active`, `inactive`, `background`), with `onForeground` for a
+    return from the background and `createManualLifecycle` in `./testing`.
+  - rn-camera, rn-ads and rn-notification hear the lifecycle through it instead of
+    subscribing to `AppState` each, so an app holds one native listener. The camera
+    controller's core layer no longer imports `react-native`.
+  - rn-payment: `syncOnForeground(engine)` and `<PaymentProvider syncOnForeground>` call
+    `handleForeground()` on each return from the background. Off by default; calling
+    `handleForeground()` yourself works as before.
+  - rn-i18n: `i18n.initSync()` resolves the locale before the first render when the
+    storage adapter has the new optional `getItemSync`, and returns false otherwise.
+    `localeStorageFromKeyValue(port)` builds such an adapter from rn-core's
+    `KeyValuePort` (MMKV).
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -75,6 +75,13 @@ export const i18n = createI18n<AppI18nKey>({
 await i18n.init(); // persisted -> device -> primary fallback
 ```
 
+With a storage adapter that reads synchronously (see below), resolve the locale before
+the first render instead, so the first frame is already in the user's language:
+
+```ts
+if (!i18n.initSync()) await i18n.init(); // initSync is false only for an async-only store
+```
+
 Wrap the app and use the hooks:
 
 ```tsx
@@ -95,15 +102,15 @@ t('cart.items', { count }, { count }); // plural variant by count
 
 | Capability | Member |
 |------------|--------|
-| Setup + validation | `createI18n(config)`, `I18nConfigError` |
+| Setup + validation | `createI18n(config)`, `I18nConfigError` (an `SdkError` from `@chipmobilesdk/rn-core`, `code: 'invalid_config'`; `UnitConversionError` has `code: 'unit_conversion'`) |
 | Translation lookup | `i18n.t`, `useTranslation` |
 | Locale state + switching | `i18n.getLocale`, `i18n.setLocale`, `useLocale` |
 | Locale metadata (RTL/LTR, defaults) | `i18n.getSupportedLocales` |
-| Device-locale init | `i18n.init`, `defaultDeviceLocaleProvider` |
+| Device-locale init | `i18n.init`, `i18n.initSync`, `defaultDeviceLocaleProvider` |
 | Formatting | `i18n.formatNumber/formatDate/formatCurrency/formatUnit` |
 | Unit conversion | `i18n.convertUnit`, `convertUnit`, `getUnitSymbol`, `SUPPORTED_UNITS`, `UnitConversionError` |
 | Runtime-only declarations | `i18n.registerRuntimeEntries` |
-| Persistence key | `LOCALE_STORAGE_KEY` |
+| Persistence | `LOCALE_STORAGE_KEY`, `localeStorageFromKeyValue` |
 | React | `I18nProvider` |
 
 Public contract types also include the configuration, locale, translation,
@@ -126,9 +133,20 @@ export const storageAdapter: LocaleStorageAdapter = {
 };
 ```
 
-An MMKV-backed adapter (wrapping its synchronous API in `Promise.resolve`)
-works equally well. If persistence is enabled without an adapter, `createI18n`
-throws before any localized content is served.
+An adapter may also have `getItemSync(key)`. With it, `i18n.initSync()` reads the
+saved locale synchronously and the app skips the frame it would otherwise render in
+the fallback language. MMKV through rn-core's `KeyValuePort` is one line:
+
+```ts
+import { openDurable } from '@chipmobilesdk/rn-core';
+import { localeStorageFromKeyValue } from '@chipmobilesdk/rn-i18n';
+import { createMMKV } from 'react-native-mmkv';
+
+const storage = localeStorageFromKeyValue(openDurable(() => createMMKV({ id: 'app' })));
+```
+
+If persistence is enabled without an adapter, `createI18n` throws before any localized
+content is served.
 
 ### Device-locale provider (optional)
 
@@ -194,6 +212,67 @@ lookup, fallback, interpolation, and missing-key behavior, and are never
 removed by synchronization. Policy `add` writes the default text to missing
 locales; `report` only lists them.
 
+### SDK copy
+
+Every `@chipmobilesdk` package with user-facing copy exports it as a catalog
+(`key -> English default`). `runtimeEntriesFromCatalog(catalog, { policy? })`
+turns one into runtime entries, converting `{name}` variables to `{{name}}`, so an
+app translates SDK copy like its own:
+
+```ts
+createI18n({
+  ...config,
+  runtimeEntries: [
+    ...runtimeEntriesFromCatalog(aiMessageSet.user),
+    ...runtimeEntriesFromCatalog(paymentMessages.user),
+  ],
+});
+```
+
+## Formatting
+
+Options **merge** over the active locale's defaults, for every formatter:
+`formatDate(value, { month: 'long' })` keeps the locale's year and day, exactly as
+`formatNumber(value, { maximumFractionDigits: 0 })` keeps the rest of the locale's number
+options. Pass `formatDate(value, options, { replaceDefaults: true })` to use only what you
+give it. `formatCurrency` deliberately does not take the locale's default number options:
+a currency carries its own minor units (yen has none), and generic number defaults would
+override them.
+
+`formatNumber`, `formatCurrency`, `formatDate` and `formatUnit` reuse one cached
+`Intl` formatter per locale and options. A value or option they cannot format (a
+`NaN`, an unknown currency code) is handled by the `invalidFormat` policy: the
+placeholder text, or a thrown error in `error` mode, and an `invalid_format`
+diagnostic either way. It never throws from inside `Intl` during a render. A
+locale's `defaultCurrency` must be a three-letter ISO 4217 code, checked at startup.
+
+## Switching, and following the device
+
+```ts
+await i18n.setLocale('vi-VN');   // the user chose a language
+await i18n.useDeviceLocale();    // "System language": forget the choice, detect again
+```
+
+`init()` resolves the locale once — persisted, then device, then the primary fallback —
+and is safe to call again (it returns the same promise). A `setLocale` during that read
+wins: the stored value never overwrites a choice the user has just made. Setting the
+locale already active changes nothing and re-renders nothing.
+
+## Diagnostics
+
+Missing translations and variables, fallbacks, invalid formats, persistence
+failures and a throwing locale listener are each reported once per lookup path as an
+`I18nDiagnostic` (`code`, `message`, and the `key` and `locale` involved):
+
+- to `onDiagnostic` in the config, when given;
+- otherwise to `console.warn`, in development builds only;
+- and always to the app's SDK sinks (`installSdkSink` from `@chipmobilesdk/rn-core`),
+  as `code` with `key` and `locale`.
+
+```ts
+const i18n = createI18n({ ...config, onDiagnostic: d => crashlytics.log(`${d.code} ${d.key ?? ''}`) });
+```
+
 ## Compatibility
 
 | Surface | Baseline |
@@ -207,7 +286,7 @@ locales; `report` only lists them.
 
 ```bash
 npm test                     # package + demo suites
-npm run typecheck --workspace @chipmobilesdk/rn-i18n       # tsc -p packages/rn-i18n/tsconfig.json --noEmit
+npm run typecheck --workspace @chipmobilesdk/rn-i18n       # source, tests and the Node CLI
 npm run pack:check --workspace @chipmobilesdk/rn-i18n            # npm pack --workspace @chipmobilesdk/rn-i18n --dry-run
 npm run i18n:sync            # extraction + synchronization
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-i18n",
-	"version": "0.1.3",
+	"version": "0.3.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -32,9 +32,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json && tsc -p tsconfig.tooling.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85"

package/skills/sdk-rn-i18n/SKILL.md

@@ -40,11 +40,42 @@ Runtime:
 - `useLocale()` → `UseLocaleResult`
 - `defaultDeviceLocaleProvider` — device locale detection
 - `LOCALE_STORAGE_KEY` — where the chosen locale persists
-- `I18nConfigError` — thrown on invalid configuration at startup
+- `i18n.initSync()` — resolve the locale before the first render when storage reads
+  synchronously; `localeStorageFromKeyValue(port)` makes such storage from an rn-core
+  key-value port (MMKV)
+- `I18nConfigError` — thrown on invalid configuration at startup; an rn-core SDK error with an
+  `I18nErrorCode`
+
+Formatting, on the instance (all locale-aware, all through Hermes's Intl):
+
+- `i18n.formatNumber(value, options?)`, `i18n.formatCurrency(value, currency?, options?)`,
+  `i18n.formatUnit(value, options?)` — options merge over the locale's defaults
+- `i18n.formatDate(value, options?, { replaceDefaults? })` — options merge too;
+  `replaceDefaults: true` uses only what is passed
+- `i18n.convertUnit(value, from, to)`, `SUPPORTED_UNITS`, `UnitConversionError`
+
+Locale, on the instance: `init()` (idempotent), `initSync()`, `setLocale(code)`,
+`useDeviceLocale()` (forget the stored choice and follow the device again),
+`getLocale()`, `getSupportedLocales()`, `registerRuntimeEntries(entries)`,
+`subscribe(listener)`, `getVersion()`
 
 Types: `I18n`, `UnitFormatOptions`, `I18nProviderProps`, `UseLocaleResult`,
 `UseTranslationResult`
 
+## Plural rules are declared, not inferred
+
+Hermes has no `Intl.PluralRules`, so this package carries a compact CLDR subset
+(en/de/es/it/nl/sv/da/nb/fi/el/he, ja/vi/ko/zh/th/id/ms, fr/pt, ru/uk/pl/cs/sk, ar). A
+language outside it falls back to "1 is singular" **and reports a
+`plural_rule_default` diagnostic** — declare `pluralRule` on the locale rather than
+shipping wrong plurals.
+
+## Entries registered at runtime re-render
+
+`registerRuntimeEntries` notifies subscribers, so a lazily loaded feature's copy appears
+without another render pass, and a malformed entry throws `I18nConfigError` there and then
+instead of rendering the key.
+
 `I18nConfigError` throws at startup by design — a misconfigured i18n setup should fail
 loudly, not silently render keys.
 

package/src/config/catalog.ts

@@ -0,0 +1,25 @@
+import type { RuntimeTranslationEntry } from './types';
+
+/**
+ * Runtime entries for a package's message catalog (I18N-13), so an app registers
+ * an SDK's copy in one line and translates it like its own:
+ *
+ * ```ts
+ * createI18n({ ...config, runtimeEntries: runtimeEntriesFromCatalog(paymentMessages.user) });
+ * ```
+ *
+ * Catalogs mark variables `{name}`; rn-i18n's are `{{name}}`, so they are
+ * converted. `policy: 'add'` lets the sync CLI write missing keys into each locale
+ * file with the default text.
+ */
+export function runtimeEntriesFromCatalog(
+	catalog: Readonly<Record<string, string>>,
+	options: { readonly policy?: 'add' | 'report'; readonly description?: string } = {},
+): RuntimeTranslationEntry[] {
+	return Object.entries(catalog).map(([key, text]) => ({
+		key,
+		defaultText: text.replace(/(?<!\{)\{(\w+)\}(?!\})/g, '{{$1}}'),
+		policy: options.policy ?? 'report',
+		...(options.description === undefined ? {} : { description: options.description }),
+	}));
+}

package/src/config/diagnostics.ts

@@ -0,0 +1,70 @@
+import {
+	createDiagnosticChannel,
+	redactPatterns,
+	type DiagnosticSeverity,
+} from '@chipmobilesdk/rn-core';
+
+/** What rn-i18n reports. Stable: an app may branch on these. */
+export type I18nDiagnosticCode =
+	| 'missing_translation'
+	| 'fallback_used'
+	| 'missing_variable'
+	| 'invalid_value'
+	| 'invalid_format'
+	| 'locale_unsupported'
+	| 'plural_rule_default'
+	| 'locale_read_failed'
+	| 'locale_write_failed'
+	| 'listener_threw';
+
+export interface I18nDiagnostic {
+	readonly code: I18nDiagnosticCode;
+	/** For people: names the key, locale or variable involved. */
+	readonly message: string;
+	readonly key?: string;
+	readonly locale?: string;
+}
+
+export type I18nDiagnosticHandler = (diagnostic: I18nDiagnostic) => void;
+
+const SEVERITY: Record<I18nDiagnosticCode, DiagnosticSeverity> = {
+	missing_translation: 'warn',
+	fallback_used: 'info',
+	missing_variable: 'warn',
+	invalid_value: 'warn',
+	invalid_format: 'warn',
+	locale_unsupported: 'warn',
+	plural_rule_default: 'warn',
+	locale_read_failed: 'warn',
+	locale_write_failed: 'warn',
+	listener_threw: 'error',
+};
+
+const channel = createDiagnosticChannel<I18nDiagnosticCode>('rn-i18n');
+
+/**
+ * One place every diagnostic goes through (I18N-11): the app's SDK sinks always
+ * (`installSdkSink` from rn-core), then `onDiagnostic` when the app gave one,
+ * otherwise `console.warn` in development builds and tests only.
+ */
+export function createReporter(onDiagnostic?: I18nDiagnosticHandler): I18nDiagnosticHandler {
+	return diagnostic => {
+		channel.emit(diagnostic.code, SEVERITY[diagnostic.code], {
+			...(diagnostic.key === undefined ? {} : { key: diagnostic.key }),
+			...(diagnostic.locale === undefined ? {} : { locale: diagnostic.locale }),
+		});
+		if (onDiagnostic) {
+			onDiagnostic(diagnostic);
+		} else if (typeof __DEV__ === 'undefined' || __DEV__) {
+			console.warn(`[rn-i18n] ${diagnostic.message}`);
+		}
+	};
+}
+
+/** For the few call sites that run before or outside an i18n instance. */
+export const defaultReporter = createReporter();
+
+/** Foreign error text, shaped before it reaches a message. */
+export function describeError(error: unknown): string {
+	return redactPatterns(error instanceof Error ? error.message : String(error));
+}

package/src/config/errors.ts

@@ -0,0 +1,28 @@
+import { SdkError } from '@chipmobilesdk/rn-core';
+
+/** The package's error codes. */
+export type I18nErrorCode = 'invalid_config' | 'unit_conversion';
+
+/**
+ * Configuration error listing every detected violation. An `SdkError`
+ * (`@chipmobilesdk/rn-core`) with `pkg: 'rn-i18n'`.
+ */
+export class I18nConfigError extends SdkError<I18nErrorCode> {
+	readonly issues: readonly string[];
+
+	constructor(issues: readonly string[]) {
+		super('rn-i18n', 'invalid_config', {
+			message: `Invalid i18n configuration:\n- ${issues.join('\n- ')}`,
+		});
+		this.name = 'I18nConfigError';
+		this.issues = issues;
+	}
+}
+
+/** A unit conversion the package cannot perform, such as across dimensions. */
+export class UnitConversionError extends SdkError<I18nErrorCode> {
+	constructor(message: string) {
+		super('rn-i18n', 'unit_conversion', { message });
+		this.name = 'UnitConversionError';
+	}
+}

package/src/config/types.ts

@@ -1,12 +1,14 @@
 /**
  * Public configuration and contract types for @chipmobilesdk/rn-i18n.
  *
- * The package has zero runtime dependencies: formatting uses the Intl APIs
+ * The package has one runtime dependency, rn-core; formatting uses the Intl APIs
  * built into Hermes (Intl.NumberFormat, Intl.DateTimeFormat), while plural
  * rules and unit conversion are package-owned because Intl.PluralRules and
  * Intl unit-style formatting are not reliably available in Hermes.
  */
 
+import type { I18nDiagnosticHandler } from './diagnostics';
+
 export type LocaleDirection = 'ltr' | 'rtl';
 
 export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
@@ -93,6 +95,12 @@ export interface LocaleStorageAdapter {
 	getItem(key: string): Promise<string | null>;
 	setItem(key: string, value: string): Promise<void>;
 	removeItem(key: string): Promise<void>;
+	/**
+	 * A synchronous read, for a store that has one (MMKV, rn-core's `KeyValuePort`).
+	 * With it, `initSync()` resolves the locale before the first render, so the app
+	 * never paints a frame in the wrong language (PERF-08).
+	 */
+	getItemSync?(key: string): string | null;
 }
 
 /** Returns the device locale, or undefined when detection is unavailable. */
@@ -108,6 +116,12 @@ export interface I18nConfig {
 	persistLocale?: boolean;
 	/** Required when `persistLocale` is not disabled. */
 	storage?: LocaleStorageAdapter;
+	/**
+	 * Receives every diagnostic: missing translations and variables, fallbacks,
+	 * invalid formats, persistence failures. Defaults to `console.warn` in
+	 * development builds only. Diagnostics also reach rn-core's SDK sinks.
+	 */
+	onDiagnostic?: I18nDiagnosticHandler;
 	deviceLocale?: DeviceLocaleProvider;
 	/** Default: `{ mode: 'key' }`. */
 	missingTranslation?: MissingTranslationPolicy;
@@ -132,13 +146,5 @@ export interface TranslateOptions {
 	count?: number;
 }
 
-/** Configuration error listing every detected violation. */
-export class I18nConfigError extends Error {
-	readonly issues: readonly string[];
-
-	constructor(issues: readonly string[]) {
-		super(`Invalid i18n configuration:\n- ${issues.join('\n- ')}`);
-		this.name = 'I18nConfigError';
-		this.issues = issues;
-	}
-}
+// Kept importable from here for compatibility; the errors live in config/errors.ts (I18N-14).
+export { I18nConfigError } from './errors';

package/src/config/validateConfig.ts

@@ -85,6 +85,11 @@ function validateLocale(
 	}
 	if (!locale.defaultCurrency) {
 		issues.push(`Locale "${code}" must declare a default currency.`);
+	} else if (!/^[A-Z]{3}$/.test(locale.defaultCurrency)) {
+		// An ISO 4217 code; anything else would fail every currency format (I18N-08).
+		issues.push(
+			`Locale "${code}" default currency "${locale.defaultCurrency}" is not a three-letter ISO 4217 code.`,
+		);
 	}
 	if (!knownUnits.has(locale.defaultUnit)) {
 		issues.push(`Locale "${code}" declares unknown default unit "${locale.defaultUnit}".`);

package/src/format/currency.ts

@@ -1,9 +1,15 @@
+import { getNumberFormat } from '@chipmobilesdk/rn-core';
 import type { InvalidFormatPolicy } from '../config/types';
 import { applyInvalidFormatPolicy } from './invalid';
 
 /**
  * Locale-aware currency formatting. The locale's configured default currency
  * applies unless the caller passes an explicit currency override (FR-021).
+ *
+ * `locale.defaultNumberFormat` is deliberately **not** applied here: a currency
+ * carries its own minor units (yen has none, dinar has three), and the locale's
+ * generic number options would override them — ¥1,234.56 instead of ¥1,235.
+ * Pass the options you want for a currency explicitly (I18N-09).
  */
 export function formatCurrencyValue(
 	value: number,
@@ -19,9 +25,15 @@ export function formatCurrencyValue(
 			`Cannot format invalid currency value "${String(value)}" for locale "${localeCode}".`,
 		);
 	}
-	return new Intl.NumberFormat(localeCode, {
-		...options,
-		style: 'currency',
-		currency: currencyOverride ?? defaultCurrency,
-	}).format(value);
+	const currency = currencyOverride ?? defaultCurrency;
+	// rn-core's cached formatter (I18N-03). An unknown currency code (`usd1`) used
+	// to throw out of render; it is a format problem now (I18N-08).
+	try {
+		return getNumberFormat(localeCode, { ...options, style: 'currency', currency }).format(value);
+	} catch (error) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format currency "${currency}" for locale "${localeCode}": ${String(error)}`,
+		);
+	}
 }

package/src/format/date.ts

@@ -1,11 +1,17 @@
+import { getDateTimeFormat } from '@chipmobilesdk/rn-core';
 import type { InvalidFormatPolicy } from '../config/types';
 import { applyInvalidFormatPolicy } from './invalid';
 
 /**
  * Locale-aware date formatting through the Hermes built-in
- * Intl.DateTimeFormat. The locale's configured default date format applies
- * unless the caller passes explicit overrides (FR-020). Options are limited
- * to component options supported by Hermes on both platforms.
+ * Intl.DateTimeFormat.
+ *
+ * Options are **merged** over the locale's configured default, the way
+ * `formatNumber` has always worked: `{ month: 'long' }` changes the month and
+ * keeps the year and day. Replacing the default wholesale, which this used to
+ * do, meant one option silently dropped every other component — and the two
+ * formatters disagreed about what an option meant (I18N-09). Pass
+ * `{ replaceDefaults: true }` for the old behaviour.
  */
 export function formatDateValue(
 	value: Date | number,
@@ -13,6 +19,7 @@ export function formatDateValue(
 	defaults: Intl.DateTimeFormatOptions,
 	override: Intl.DateTimeFormatOptions | undefined,
 	invalidFormat: InvalidFormatPolicy,
+	replaceDefaults = false,
 ): string {
 	const date = value instanceof Date ? value : new Date(value);
 	if (Number.isNaN(date.getTime())) {
@@ -21,6 +28,11 @@ export function formatDateValue(
 			`Cannot format invalid date value "${String(value)}" for locale "${localeCode}".`,
 		);
 	}
-	const options = override ?? defaults;
-	return new Intl.DateTimeFormat(localeCode, options).format(date);
+	const options = replaceDefaults ? (override ?? defaults) : { ...defaults, ...override };
+	// rn-core's cached formatter (I18N-03); a bad option is a format problem (I18N-08).
+	try {
+		return getDateTimeFormat(localeCode, options).format(date);
+	} catch (error) {
+		return applyInvalidFormatPolicy(invalidFormat, `Cannot format a date: ${String(error)}`);
+	}
 }

package/src/format/invalid.ts

@@ -1,11 +1,20 @@
+import { defaultReporter, type I18nDiagnosticHandler } from '../config/diagnostics';
 import type { InvalidFormatPolicy } from '../config/types';
 
+/** The policy as an i18n instance resolves it: with the instance's reporter. */
+export type ResolvedInvalidFormatPolicy = InvalidFormatPolicy & {
+	readonly report?: I18nDiagnosticHandler | undefined;
+};
+
 /**
  * Applies the configured invalid-format behavior: return the placeholder, or
  * throw a clear formatting error in `error` mode (FR-037, FR-045).
  */
-export function applyInvalidFormatPolicy(policy: InvalidFormatPolicy, message: string): string {
-	console.warn(`[rn-i18n] ${message}`);
+export function applyInvalidFormatPolicy(
+	policy: ResolvedInvalidFormatPolicy,
+	message: string,
+): string {
+	(policy.report ?? defaultReporter)({ code: 'invalid_format', message });
 	if (policy.mode === 'error') {
 		throw new RangeError(`[rn-i18n] ${message}`);
 	}

package/src/format/number.ts

@@ -1,3 +1,4 @@
+import { getNumberFormat } from '@chipmobilesdk/rn-core';
 import type { InvalidFormatPolicy } from '../config/types';
 import { applyInvalidFormatPolicy } from './invalid';
 
@@ -19,5 +20,11 @@ export function formatNumberValue(
 			`Cannot format invalid number value "${String(value)}" for locale "${localeCode}".`,
 		);
 	}
-	return new Intl.NumberFormat(localeCode, { ...defaults, ...override }).format(value);
+	// rn-core's cached formatter (I18N-03); a bad option is a format problem, not a
+	// crash in render (I18N-08).
+	try {
+		return getNumberFormat(localeCode, { ...defaults, ...override }).format(value);
+	} catch (error) {
+		return applyInvalidFormatPolicy(invalidFormat, `Cannot format a number: ${String(error)}`);
+	}
 }

package/src/format/units.ts

@@ -39,12 +39,10 @@ export const SUPPORTED_UNITS = Object.keys(UNIT_REGISTRY) as readonly UnitId[];
 
 export const KNOWN_UNIT_IDS: ReadonlySet<string> = new Set(SUPPORTED_UNITS);
 
-export class UnitConversionError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = 'UnitConversionError';
-	}
-}
+// Kept importable from here for compatibility; the errors live in config/errors.ts.
+import { UnitConversionError } from '../config/errors';
+
+export { UnitConversionError };
 
 export function getUnitSymbol(unit: UnitId): string {
 	return UNIT_REGISTRY[unit].symbol;