@chipmobilesdk/rn-i18n 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # @chipmobilesdk/rn-i18n
 
+## 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,47 @@ 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
+
+`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.
+
+## 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 +266,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.2.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,7 +40,11 @@ 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`
 
 Types: `I18n`, `UnitFormatOptions`, `I18nProviderProps`, `UseLocaleResult`,
 `UseTranslationResult`

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,68 @@
+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'
+	| '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',
+	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,3 +1,4 @@
+import { getNumberFormat } from '@chipmobilesdk/rn-core';
 import type { InvalidFormatPolicy } from '../config/types';
 import { applyInvalidFormatPolicy } from './invalid';
 
@@ -19,9 +20,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,3 +1,4 @@
+import { getDateTimeFormat } from '@chipmobilesdk/rn-core';
 import type { InvalidFormatPolicy } from '../config/types';
 import { applyInvalidFormatPolicy } from './invalid';
 
@@ -22,5 +23,10 @@ export function formatDateValue(
 		);
 	}
 	const options = override ?? defaults;
-	return new Intl.DateTimeFormat(localeCode, options).format(date);
+	// 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;

package/src/i18n.ts

@@ -1,3 +1,5 @@
+import { createReporter } from './config/diagnostics';
+import type { ResolvedInvalidFormatPolicy } from './format/invalid';
 import type {
 	ActiveLocalePreference,
 	I18nConfig,
@@ -12,7 +14,11 @@ import type {
 import { validateConfig } from './config/validateConfig';
 import { createActiveLocaleStore } from './locale/activeLocale';
 import { defaultDeviceLocaleProvider, matchSupportedLocale } from './locale/deviceLocale';
-import { readPersistedLocale, writePersistedLocale } from './locale/persistence';
+import {
+	readPersistedLocale,
+	readPersistedLocaleSync,
+	writePersistedLocale,
+} from './locale/persistence';
 import { translate } from './translation/resolver';
 import type { ResolverContext } from './translation/resolver';
 import { createRuntimeRegistry, registerRuntimeEntries } from './translation/runtimeKeys';
@@ -25,6 +31,13 @@ import type { UnitFormatOptions } from './format/units';
 export interface I18n<TKey extends string = string> {
 	/** Resolves the initial locale: persisted → device → primary fallback. */
 	init(): Promise<void>;
+	/**
+	 * `init()` without waiting, before the first render (PERF-08). Resolves the locale
+	 * and returns true when it can do so synchronously: persistence is off, or the
+	 * storage adapter has `getItemSync`. Returns false, changing nothing, when the
+	 * adapter can only read asynchronously; call `init()` then.
+	 */
+	initSync(): boolean;
 	t(key: TKey, vars?: TranslateVars, options?: TranslateOptions): string;
 	getLocale(): ActiveLocalePreference;
 	/** Switches at runtime without restart and persists best-effort. */
@@ -55,15 +68,18 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 	const locales: readonly LocaleConfig[] = [...config.locales];
 	const localesByCode = new Map(locales.map(locale => [locale.code, locale]));
 	const missingTranslation = config.missingTranslation ?? DEFAULT_MISSING;
-	const invalidFormat = config.invalidFormat ?? DEFAULT_INVALID;
+	const report = createReporter(config.onDiagnostic);
+	const invalidFormat: ResolvedInvalidFormatPolicy = {
+		...(config.invalidFormat ?? DEFAULT_INVALID),
+		report,
+	};
 	const persistenceEnabled = config.persistLocale !== false && !!config.storage;
 	const runtimeEntries = createRuntimeRegistry(config.runtimeEntries);
 
-	const store = createActiveLocaleStore({
-		code: config.primaryLocale,
-		source: 'primaryFallback',
-		recovered: false,
-	});
+	const store = createActiveLocaleStore(
+		{ code: config.primaryLocale, source: 'primaryFallback', recovered: false },
+		report,
+	);
 
 	const resolverContext: ResolverContext = {
 		localesByCode,
@@ -71,6 +87,7 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 		runtimeEntries,
 		missingTranslation,
 		warned: new Set(),
+		report,
 	};
 
 	const activeLocale = (): LocaleConfig => {
@@ -82,37 +99,55 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 		return locale;
 	};
 
+	/** persisted → device → primary fallback; shared by `init` and `initSync`. */
+	const resolveInitialLocale = (persisted: string | null): void => {
+		if (persisted) {
+			if (localesByCode.has(persisted)) {
+				store.set({ code: persisted, source: 'persisted', recovered: false });
+				return;
+			}
+			report({
+				code: 'locale_unsupported',
+				locale: persisted,
+				message: `Persisted locale "${persisted}" is no longer supported; recovering to "${config.primaryLocale}".`,
+			});
+			store.set({ code: config.primaryLocale, source: 'primaryFallback', recovered: true });
+			return;
+		}
+		const provider = config.deviceLocale ?? defaultDeviceLocaleProvider;
+		const match = matchSupportedLocale(provider(), locales);
+		store.set(
+			match
+				? { code: match.code, source: match.source, recovered: false }
+				: { code: config.primaryLocale, source: 'primaryFallback', recovered: false },
+		);
+	};
+
 	return {
 		async init() {
-			if (persistenceEnabled && config.storage) {
-				const persisted = await readPersistedLocale(config.storage);
-				if (persisted) {
-					if (localesByCode.has(persisted)) {
-						store.set({ code: persisted, source: 'persisted', recovered: false });
-						return;
-					}
-					console.warn(
-						`[rn-i18n] Persisted locale "${persisted}" is no longer supported; recovering to "${config.primaryLocale}".`,
-					);
-					store.set({
-						code: config.primaryLocale,
-						source: 'primaryFallback',
-						recovered: true,
-					});
-					return;
-				}
+			resolveInitialLocale(
+				persistenceEnabled && config.storage
+					? await readPersistedLocale(config.storage, report)
+					: null,
+			);
+		},
+
+		initSync() {
+			if (!persistenceEnabled || !config.storage) {
+				resolveInitialLocale(null);
+				return true;
+			}
+			const { storage } = config;
+			if (typeof storage.getItemSync !== 'function') {
+				return false;
 			}
-			const provider = config.deviceLocale ?? defaultDeviceLocaleProvider;
-			const match = matchSupportedLocale(provider(), locales);
-			store.set(
-				match
-					? { code: match.code, source: match.source, recovered: false }
-					: {
-							code: config.primaryLocale,
-							source: 'primaryFallback',
-							recovered: false,
-						},
+			resolveInitialLocale(
+				readPersistedLocaleSync(
+					storage as typeof storage & { getItemSync(key: string): string | null },
+					report,
+				),
 			);
+			return true;
 		},
 
 		t(key, vars, options) {
@@ -129,7 +164,7 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 			}
 			store.set({ code, source: 'runtimeSwitch', recovered: false });
 			if (persistenceEnabled && config.storage) {
-				await writePersistedLocale(config.storage, code);
+				await writePersistedLocale(config.storage, code, report);
 			}
 		},
 

package/src/index.ts

@@ -11,6 +11,14 @@ export { createI18n } from './i18n';
 export type { I18n } from './i18n';
 
 export { I18nConfigError } from './config/types';
+export { runtimeEntriesFromCatalog } from './config/catalog';
+export { localeStorageFromKeyValue } from './locale/keyValueStorage';
+export type { I18nErrorCode } from './config/errors';
+export type {
+	I18nDiagnostic,
+	I18nDiagnosticCode,
+	I18nDiagnosticHandler,
+} from './config/diagnostics';
 export type {
 	ActiveLocalePreference,
 	DeviceLocaleProvider,

package/src/locale/activeLocale.ts

@@ -1,3 +1,6 @@
+import { createListenerSet } from '@chipmobilesdk/rn-core';
+
+import { defaultReporter, describeError, type I18nDiagnosticHandler } from '../config/diagnostics';
 import type { ActiveLocalePreference } from '../config/types';
 
 export interface ActiveLocaleStore {
@@ -8,39 +11,32 @@ export interface ActiveLocaleStore {
 	getVersion(): number;
 }
 
-export function createActiveLocaleStore(initial: ActiveLocalePreference): ActiveLocaleStore {
+export function createActiveLocaleStore(
+	initial: ActiveLocalePreference,
+	report: I18nDiagnosticHandler = defaultReporter,
+): ActiveLocaleStore {
 	let preference = initial;
 	let version = 0;
-	const listeners = new Set<() => void>();
+	const listeners = createListenerSet<[]>({
+		onListenerError: error =>
+			report({
+				code: 'listener_threw',
+				message: `A locale listener threw; the locale change still applied: ${describeError(error)}`,
+			}),
+	});
 
 	return {
 		get: () => preference,
 		set(next) {
 			preference = next;
 			version += 1;
-			// Snapshot, and isolate each listener (CORE-03). One that threw used to
-			// skip every listener after it — useSyncExternalStore subscribers
-			// included — and made setLocale reject after the switch but before the
-			// choice was persisted, so the app showed one locale and stored another.
-			for (const listener of [...listeners]) {
-				// Unsubscribed by an earlier listener during this notification.
-				if (!listeners.has(listener)) continue;
-				try {
-					listener();
-				} catch (error) {
-					console.warn(
-						'[rn-i18n] A locale listener threw; the locale change still applied.',
-						error,
-					);
-				}
-			}
-		},
-		subscribe(listener) {
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
+			// Isolated (CORE-03). One that threw used to skip every listener after
+			// it — useSyncExternalStore subscribers included — and made setLocale
+			// reject after the switch but before the choice was persisted, so the
+			// app showed one locale and stored another.
+			listeners.notify();
 		},
+		subscribe: listener => listeners.add(listener),
 		getVersion: () => version,
 	};
 }

package/src/locale/keyValueStorage.ts

@@ -0,0 +1,27 @@
+/**
+ * A `LocaleStorageAdapter` over rn-core's synchronous `KeyValuePort` (PERF-08).
+ *
+ * The adapter carries `getItemSync`, so `i18n.initSync()` resolves the persisted
+ * locale before the first render. Open the port the way the app opens its other
+ * durable state, for example `openDurable(() => createMMKV({ id: 'app' }))`.
+ */
+import type { KeyValuePort } from '@chipmobilesdk/rn-core';
+
+import type { LocaleStorageAdapter } from '../config/types';
+
+export function localeStorageFromKeyValue(
+	port: KeyValuePort,
+): LocaleStorageAdapter & { getItemSync(key: string): string | null } {
+	return {
+		getItemSync: key => port.getString(key) ?? null,
+		async getItem(key) {
+			return port.getString(key) ?? null;
+		},
+		async setItem(key, value) {
+			port.set(key, value);
+		},
+		async removeItem(key) {
+			port.remove(key);
+		},
+	};
+}

package/src/locale/persistence.ts

@@ -1,3 +1,4 @@
+import { defaultReporter, describeError, type I18nDiagnosticHandler } from '../config/diagnostics';
 import type { LocaleStorageAdapter } from '../config/types';
 
 export const LOCALE_STORAGE_KEY = '@chipmobilesdk/rn-i18n:locale';
@@ -6,11 +7,33 @@ export const LOCALE_STORAGE_KEY = '@chipmobilesdk/rn-i18n:locale';
  * Reads the persisted locale preference. Adapter failures are reported and
  * treated as "no persisted value" so locale selection never crashes (FR-015).
  */
-export async function readPersistedLocale(storage: LocaleStorageAdapter): Promise<string | null> {
+export async function readPersistedLocale(
+	storage: LocaleStorageAdapter,
+	report: I18nDiagnosticHandler = defaultReporter,
+): Promise<string | null> {
 	try {
 		return await storage.getItem(LOCALE_STORAGE_KEY);
 	} catch (error) {
-		console.warn(`[rn-i18n] Failed to read the persisted locale preference: ${String(error)}`);
+		report({
+			code: 'locale_read_failed',
+			message: `Failed to read the persisted locale preference: ${describeError(error)}`,
+		});
+		return null;
+	}
+}
+
+/** `readPersistedLocale` for a store with a synchronous read; same failure handling. */
+export function readPersistedLocaleSync(
+	storage: LocaleStorageAdapter & { getItemSync(key: string): string | null },
+	report: I18nDiagnosticHandler = defaultReporter,
+): string | null {
+	try {
+		return storage.getItemSync(LOCALE_STORAGE_KEY);
+	} catch (error) {
+		report({
+			code: 'locale_read_failed',
+			message: `Failed to read the persisted locale preference: ${describeError(error)}`,
+		});
 		return null;
 	}
 }
@@ -22,10 +45,15 @@ export async function readPersistedLocale(storage: LocaleStorageAdapter): Promis
 export async function writePersistedLocale(
 	storage: LocaleStorageAdapter,
 	code: string,
+	report: I18nDiagnosticHandler = defaultReporter,
 ): Promise<void> {
 	try {
 		await storage.setItem(LOCALE_STORAGE_KEY, code);
 	} catch (error) {
-		console.warn(`[rn-i18n] Failed to persist locale "${code}": ${String(error)}`);
+		report({
+			code: 'locale_write_failed',
+			locale: code,
+			message: `Failed to persist locale "${code}": ${describeError(error)}`,
+		});
 	}
 }

package/src/react/hooks.ts

@@ -1,4 +1,4 @@
-import { useSyncExternalStore } from 'react';
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
 import type {
 	ActiveLocalePreference,
 	LocaleConfig,
@@ -9,8 +9,8 @@ import type {
 import type { I18n } from '../i18n';
 import { useI18nContext } from './I18nProvider';
 
-function useLocaleVersion(i18n: I18n<string>): void {
-	useSyncExternalStore(i18n.subscribe, i18n.getVersion, i18n.getVersion);
+function useLocaleVersion(i18n: I18n<string>): number {
+	return useSyncExternalStore(i18n.subscribe, i18n.getVersion, i18n.getVersion);
 }
 
 export interface UseTranslationResult<TKey extends string> {
@@ -25,11 +25,19 @@ export interface UseTranslationResult<TKey extends string> {
  */
 export function useTranslation<TKey extends string = string>(): UseTranslationResult<TKey> {
 	const i18n = useI18nContext();
-	useLocaleVersion(i18n);
-	return {
-		t: (key, vars, options) => i18n.t(key, vars, options),
-		locale: i18n.getLocale().code,
-	};
+	const version = useLocaleVersion(i18n);
+	// One `t` and one result per locale version (I18N-05): a memoized child that
+	// takes `t` re-renders when the locale changes, not on every parent render.
+	return useMemo(
+		() => ({
+			t: (key: TKey, vars?: TranslateVars, options?: TranslateOptions) =>
+				i18n.t(key, vars, options),
+			locale: i18n.getLocale().code,
+		}),
+		// `version` is the dependency that matters: it changes with the locale.
+		// eslint-disable-next-line react-hooks/exhaustive-deps -- `version` is read to invalidate, not used
+		[i18n, version],
+	);
 }
 
 export interface UseLocaleResult {
@@ -44,6 +52,7 @@ export interface UseLocaleResult {
 export function useLocale(): UseLocaleResult {
 	const i18n = useI18nContext();
 	useLocaleVersion(i18n);
+	const setLocale = useCallback((code: string) => i18n.setLocale(code), [i18n]);
 	const preference = i18n.getLocale();
 	const supportedLocales = i18n.getSupportedLocales();
 	const active = supportedLocales.find(locale => locale.code === preference.code);
@@ -52,6 +61,6 @@ export function useLocale(): UseLocaleResult {
 		direction: active?.direction ?? 'ltr',
 		preference,
 		supportedLocales,
-		setLocale: code => i18n.setLocale(code),
+		setLocale,
 	};
 }

package/src/translation/resolver.ts

@@ -1,3 +1,4 @@
+import type { I18nDiagnostic, I18nDiagnosticHandler } from '../config/diagnostics';
 import type {
 	LocaleConfig,
 	MissingTranslationPolicy,
@@ -18,14 +19,30 @@ export interface ResolverContext {
 	missingTranslation: MissingTranslationPolicy;
 	/** Dedupe set so each failed lookup path warns exactly once. */
 	warned: Set<string>;
+	report: I18nDiagnosticHandler;
 }
 
-export function warnOnce(warned: Set<string>, dedupeKey: string, message: string): void {
+/**
+ * How many lookup paths are remembered. An app that misses many distinct keys
+ * forgets the oldest first, so memory stays bounded (I18N-11).
+ */
+const WARNED_CAPACITY = 500;
+
+export function warnOnce(
+	context: Pick<ResolverContext, 'warned' | 'report'>,
+	dedupeKey: string,
+	diagnostic: I18nDiagnostic,
+): void {
+	const { warned } = context;
 	if (warned.has(dedupeKey)) {
 		return;
 	}
 	warned.add(dedupeKey);
-	console.warn(message);
+	if (warned.size > WARNED_CAPACITY) {
+		const oldest = warned.values().next().value;
+		if (oldest !== undefined) warned.delete(oldest);
+	}
+	context.report(diagnostic);
 }
 
 /** Walks a dot-path key through a nested translation namespace. */
@@ -54,7 +71,7 @@ function pickValue(
 	node: TranslationNode,
 	locale: LocaleConfig,
 	options: TranslateOptions | undefined,
-	warned: Set<string>,
+	warnings: Pick<ResolverContext, 'warned' | 'report'>,
 	key: string,
 ): string | undefined {
 	if (typeof node === 'string') {
@@ -67,11 +84,12 @@ function pickValue(
 		}
 		return selectPluralVariant(node, resolvePluralRule(locale)(count));
 	}
-	warnOnce(
-		warned,
-		`invalid-value|${locale.code}|${key}`,
-		`[rn-i18n] Translation value for "${key}" in locale "${locale.code}" is not text or a plural group; treating it as missing.`,
-	);
+	warnOnce(warnings, `invalid-value|${locale.code}|${key}`, {
+		code: 'invalid_value',
+		key,
+		locale: locale.code,
+		message: `Translation value for "${key}" in locale "${locale.code}" is not text or a plural group; treating it as missing.`,
+	});
 	return undefined;
 }
 
@@ -96,11 +114,12 @@ export function translate(
 
 	const interpolateWith = (text: string, sourceLocale: string) =>
 		interpolate(text, mergedVars, name =>
-			warnOnce(
-				context.warned,
-				`missing-var|${sourceLocale}|${key}|${name}`,
-				`[rn-i18n] Missing interpolation variable "${name}" for key "${key}" in locale "${sourceLocale}".`,
-			),
+			warnOnce(context, `missing-var|${sourceLocale}|${key}|${name}`, {
+				code: 'missing_variable',
+				key,
+				locale: sourceLocale,
+				message: `Missing interpolation variable "${name}" for key "${key}" in locale "${sourceLocale}".`,
+			}),
 		);
 
 	for (const code of chain) {
@@ -112,16 +131,17 @@ export function translate(
 		if (node === undefined) {
 			continue;
 		}
-		const value = pickValue(node, locale, options, context.warned, key);
+		const value = pickValue(node, locale, options, context, key);
 		if (value === undefined) {
 			continue;
 		}
 		if (code !== activeCode) {
-			warnOnce(
-				context.warned,
-				`fallback|${activeCode}|${key}`,
-				`[rn-i18n] Key "${key}" is missing in locale "${activeCode}"; served from fallback locale "${code}".`,
-			);
+			warnOnce(context, `fallback|${activeCode}|${key}`, {
+				code: 'fallback_used',
+				key,
+				locale: activeCode,
+				message: `Key "${key}" is missing in locale "${activeCode}"; served from fallback locale "${code}".`,
+			});
 		}
 		return interpolateWith(value, code);
 	}
@@ -131,10 +151,11 @@ export function translate(
 		return interpolateWith(runtimeEntry.defaultText, activeCode);
 	}
 
-	warnOnce(
-		context.warned,
-		`missing|${activeCode}|${key}`,
-		`[rn-i18n] Missing translation for key "${key}" in locale "${activeCode}" and its entire fallback chain.`,
-	);
+	warnOnce(context, `missing|${activeCode}|${key}`, {
+		code: 'missing_translation',
+		key,
+		locale: activeCode,
+		message: `Missing translation for key "${key}" in locale "${activeCode}" and its entire fallback chain.`,
+	});
 	return context.missingTranslation.mode === 'placeholder' ? context.missingTranslation.text : key;
 }