@chipmobilesdk/rn-i18n 0.1.2 → 0.2.0

package/src/i18n.ts

@@ -1,222 +1,231 @@
-import type {
-	ActiveLocalePreference,
-	I18nConfig,
-	InvalidFormatPolicy,
-	LocaleConfig,
-	MissingTranslationPolicy,
-	RuntimeTranslationEntry,
-	TranslateOptions,
-	TranslateVars,
-	UnitId,
-} from './config/types';
-import { validateConfig } from './config/validateConfig';
-import { createActiveLocaleStore } from './locale/activeLocale';
-import {
-	defaultDeviceLocaleProvider,
-	matchSupportedLocale,
-} from './locale/deviceLocale';
-import { readPersistedLocale, writePersistedLocale } from './locale/persistence';
-import { translate } from './translation/resolver';
-import type { ResolverContext } from './translation/resolver';
-import {
-	createRuntimeRegistry,
-	registerRuntimeEntries,
-} from './translation/runtimeKeys';
-import { formatCurrencyValue } from './format/currency';
-import { formatDateValue } from './format/date';
-import { formatNumberValue } from './format/number';
-import {
-	KNOWN_UNIT_IDS,
-	convertUnitValue,
-	formatUnitValue,
-} from './format/units';
-import type { UnitFormatOptions } from './format/units';
-
-export interface I18n<TKey extends string = string> {
-	/** Resolves the initial locale: persisted → device → primary fallback. */
-	init(): Promise<void>;
-	t(key: TKey, vars?: TranslateVars, options?: TranslateOptions): string;
-	getLocale(): ActiveLocalePreference;
-	/** Switches at runtime without restart and persists best-effort. */
-	setLocale(code: string): Promise<void>;
-	getSupportedLocales(): readonly LocaleConfig[];
-	formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
-	formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
-	formatCurrency(
-		value: number,
-		currency?: string,
-		options?: Intl.NumberFormatOptions,
-	): string;
-	formatUnit(value: number, options?: UnitFormatOptions): string;
-	convertUnit(value: number, from: UnitId, to: UnitId): number;
-	registerRuntimeEntries(entries: readonly RuntimeTranslationEntry[]): void;
-	subscribe(listener: () => void): () => void;
-	getVersion(): number;
-}
-
-const DEFAULT_MISSING: MissingTranslationPolicy = { mode: 'key' };
-const DEFAULT_INVALID: InvalidFormatPolicy = { mode: 'placeholder', text: '—' };
-
-/**
- * Creates an I18n instance from an app-owned configuration. Validation runs
- * eagerly and throws an I18nConfigError before any localized content can be
- * served (FR-003). Pass the app's generated key type for typed lookups:
- * `createI18n<AppI18nKey>(config)`.
- */
-export function createI18n<TKey extends string = string>(
-	config: I18nConfig,
-): I18n<TKey> {
-	validateConfig(config, KNOWN_UNIT_IDS);
-
-	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 persistenceEnabled = config.persistLocale !== false && !!config.storage;
-	const runtimeEntries = createRuntimeRegistry(config.runtimeEntries);
-
-	const store = createActiveLocaleStore({
-		code: config.primaryLocale,
-		source: 'primaryFallback',
-		recovered: false,
-	});
-
-	const resolverContext: ResolverContext = {
-		localesByCode,
-		resources: config.resources,
-		runtimeEntries,
-		missingTranslation,
-		warned: new Set(),
-	};
-
-	const activeLocale = (): LocaleConfig => {
-		const locale = localesByCode.get(store.get().code);
-		if (!locale) {
-			// Unreachable after validation; guards against external mutation.
-			throw new Error(
-				`[rn-i18n] Active locale "${store.get().code}" is not configured.`,
-			);
-		}
-		return locale;
-	};
-
-	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;
-				}
-			}
-			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,
-					  },
-			);
-		},
-
-		t(key, vars, options) {
-			return translate(resolverContext, store.get().code, key, vars, options);
-		},
-
-		getLocale() {
-			return store.get();
-		},
-
-		async setLocale(code) {
-			if (!localesByCode.has(code)) {
-				throw new Error(
-					`[rn-i18n] Cannot switch to unsupported locale "${code}".`,
-				);
-			}
-			store.set({ code, source: 'runtimeSwitch', recovered: false });
-			if (persistenceEnabled && config.storage) {
-				await writePersistedLocale(config.storage, code);
-			}
-		},
-
-		getSupportedLocales() {
-			return locales;
-		},
-
-		formatNumber(value, options) {
-			const locale = activeLocale();
-			return formatNumberValue(
-				value,
-				locale.code,
-				locale.defaultNumberFormat,
-				options,
-				invalidFormat,
-			);
-		},
-
-		formatDate(value, options) {
-			const locale = activeLocale();
-			return formatDateValue(
-				value,
-				locale.code,
-				locale.defaultDateFormat,
-				options,
-				invalidFormat,
-			);
-		},
-
-		formatCurrency(value, currency, options) {
-			const locale = activeLocale();
-			return formatCurrencyValue(
-				value,
-				locale.code,
-				locale.defaultCurrency,
-				currency,
-				options,
-				invalidFormat,
-			);
-		},
-
-		formatUnit(value, options) {
-			const locale = activeLocale();
-			return formatUnitValue(
-				value,
-				locale.code,
-				locale.defaultUnit,
-				locale.defaultNumberFormat,
-				options,
-				invalidFormat,
-			);
-		},
-
-		convertUnit(value, from, to) {
-			return convertUnitValue(value, from, to);
-		},
-
-		registerRuntimeEntries(entries) {
-			registerRuntimeEntries(runtimeEntries, entries);
-		},
-
-		subscribe(listener) {
-			return store.subscribe(listener);
-		},
-
-		getVersion() {
-			return store.getVersion();
-		},
-	};
-}
+import { createReporter } from './config/diagnostics';
+import type { ResolvedInvalidFormatPolicy } from './format/invalid';
+import type {
+	ActiveLocalePreference,
+	I18nConfig,
+	InvalidFormatPolicy,
+	LocaleConfig,
+	MissingTranslationPolicy,
+	RuntimeTranslationEntry,
+	TranslateOptions,
+	TranslateVars,
+	UnitId,
+} from './config/types';
+import { validateConfig } from './config/validateConfig';
+import { createActiveLocaleStore } from './locale/activeLocale';
+import { defaultDeviceLocaleProvider, matchSupportedLocale } from './locale/deviceLocale';
+import {
+	readPersistedLocale,
+	readPersistedLocaleSync,
+	writePersistedLocale,
+} from './locale/persistence';
+import { translate } from './translation/resolver';
+import type { ResolverContext } from './translation/resolver';
+import { createRuntimeRegistry, registerRuntimeEntries } from './translation/runtimeKeys';
+import { formatCurrencyValue } from './format/currency';
+import { formatDateValue } from './format/date';
+import { formatNumberValue } from './format/number';
+import { KNOWN_UNIT_IDS, convertUnitValue, formatUnitValue } from './format/units';
+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. */
+	setLocale(code: string): Promise<void>;
+	getSupportedLocales(): readonly LocaleConfig[];
+	formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+	formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+	formatCurrency(value: number, currency?: string, options?: Intl.NumberFormatOptions): string;
+	formatUnit(value: number, options?: UnitFormatOptions): string;
+	convertUnit(value: number, from: UnitId, to: UnitId): number;
+	registerRuntimeEntries(entries: readonly RuntimeTranslationEntry[]): void;
+	subscribe(listener: () => void): () => void;
+	getVersion(): number;
+}
+
+const DEFAULT_MISSING: MissingTranslationPolicy = { mode: 'key' };
+const DEFAULT_INVALID: InvalidFormatPolicy = { mode: 'placeholder', text: '—' };
+
+/**
+ * Creates an I18n instance from an app-owned configuration. Validation runs
+ * eagerly and throws an I18nConfigError before any localized content can be
+ * served (FR-003). Pass the app's generated key type for typed lookups:
+ * `createI18n<AppI18nKey>(config)`.
+ */
+export function createI18n<TKey extends string = string>(config: I18nConfig): I18n<TKey> {
+	validateConfig(config, KNOWN_UNIT_IDS);
+
+	const locales: readonly LocaleConfig[] = [...config.locales];
+	const localesByCode = new Map(locales.map(locale => [locale.code, locale]));
+	const missingTranslation = config.missingTranslation ?? DEFAULT_MISSING;
+	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 },
+		report,
+	);
+
+	const resolverContext: ResolverContext = {
+		localesByCode,
+		resources: config.resources,
+		runtimeEntries,
+		missingTranslation,
+		warned: new Set(),
+		report,
+	};
+
+	const activeLocale = (): LocaleConfig => {
+		const locale = localesByCode.get(store.get().code);
+		if (!locale) {
+			// Unreachable after validation; guards against external mutation.
+			throw new Error(`[rn-i18n] Active locale "${store.get().code}" is not configured.`);
+		}
+		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() {
+			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;
+			}
+			resolveInitialLocale(
+				readPersistedLocaleSync(
+					storage as typeof storage & { getItemSync(key: string): string | null },
+					report,
+				),
+			);
+			return true;
+		},
+
+		t(key, vars, options) {
+			return translate(resolverContext, store.get().code, key, vars, options);
+		},
+
+		getLocale() {
+			return store.get();
+		},
+
+		async setLocale(code) {
+			if (!localesByCode.has(code)) {
+				throw new Error(`[rn-i18n] Cannot switch to unsupported locale "${code}".`);
+			}
+			store.set({ code, source: 'runtimeSwitch', recovered: false });
+			if (persistenceEnabled && config.storage) {
+				await writePersistedLocale(config.storage, code, report);
+			}
+		},
+
+		getSupportedLocales() {
+			return locales;
+		},
+
+		formatNumber(value, options) {
+			const locale = activeLocale();
+			return formatNumberValue(
+				value,
+				locale.code,
+				locale.defaultNumberFormat,
+				options,
+				invalidFormat,
+			);
+		},
+
+		formatDate(value, options) {
+			const locale = activeLocale();
+			return formatDateValue(value, locale.code, locale.defaultDateFormat, options, invalidFormat);
+		},
+
+		formatCurrency(value, currency, options) {
+			const locale = activeLocale();
+			return formatCurrencyValue(
+				value,
+				locale.code,
+				locale.defaultCurrency,
+				currency,
+				options,
+				invalidFormat,
+			);
+		},
+
+		formatUnit(value, options) {
+			const locale = activeLocale();
+			return formatUnitValue(
+				value,
+				locale.code,
+				locale.defaultUnit,
+				locale.defaultNumberFormat,
+				options,
+				invalidFormat,
+			);
+		},
+
+		convertUnit(value, from, to) {
+			return convertUnitValue(value, from, to);
+		},
+
+		registerRuntimeEntries(entries) {
+			registerRuntimeEntries(runtimeEntries, entries);
+		},
+
+		subscribe(listener) {
+			return store.subscribe(listener);
+		},
+
+		getVersion() {
+			return store.getVersion();
+		},
+	};
+}

package/src/index.ts

@@ -1,50 +1,58 @@
-/**
- * @chipmobilesdk/rn-i18n — reusable localization for ChipMobileSdk-family
- * React Native apps.
- *
- * This is the single React Native entrypoint. Node-only extraction and
- * synchronization tooling is exposed separately via
- * `@chipmobilesdk/rn-i18n/tooling` and must never be imported from here.
- */
-
-export { createI18n } from './i18n';
-export type { I18n } from './i18n';
-
-export { I18nConfigError } from './config/types';
-export type {
-	ActiveLocalePreference,
-	DeviceLocaleProvider,
-	I18nConfig,
-	InvalidFormatPolicy,
-	LocaleConfig,
-	LocaleDirection,
-	LocaleSelectionSource,
-	LocaleStorageAdapter,
-	MissingTranslationPolicy,
-	PluralCategory,
-	PluralRule,
-	RuntimeTranslationEntry,
-	TranslateOptions,
-	TranslateVars,
-	TranslationNamespace,
-	TranslationNode,
-	TranslationResources,
-	UnitDimension,
-	UnitId,
-} from './config/types';
-
-export { LOCALE_STORAGE_KEY } from './locale/persistence';
-export { defaultDeviceLocaleProvider } from './locale/deviceLocale';
-
-export {
-	SUPPORTED_UNITS,
-	UnitConversionError,
-	convertUnitValue as convertUnit,
-	getUnitSymbol,
-} from './format/units';
-export type { UnitFormatOptions } from './format/units';
-
-export { I18nProvider } from './react/I18nProvider';
-export type { I18nProviderProps } from './react/I18nProvider';
-export { useLocale, useTranslation } from './react/hooks';
-export type { UseLocaleResult, UseTranslationResult } from './react/hooks';
+/**
+ * @chipmobilesdk/rn-i18n — reusable localization for ChipMobileSdk-family
+ * React Native apps.
+ *
+ * This is the single React Native entrypoint. Node-only extraction and
+ * synchronization tooling is exposed separately via
+ * `@chipmobilesdk/rn-i18n/tooling` and must never be imported from here.
+ */
+
+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,
+	I18nConfig,
+	InvalidFormatPolicy,
+	LocaleConfig,
+	LocaleDirection,
+	LocaleSelectionSource,
+	LocaleStorageAdapter,
+	MissingTranslationPolicy,
+	PluralCategory,
+	PluralRule,
+	RuntimeTranslationEntry,
+	TranslateOptions,
+	TranslateVars,
+	TranslationNamespace,
+	TranslationNode,
+	TranslationResources,
+	UnitDimension,
+	UnitId,
+} from './config/types';
+
+export { LOCALE_STORAGE_KEY } from './locale/persistence';
+export { defaultDeviceLocaleProvider } from './locale/deviceLocale';
+
+export {
+	SUPPORTED_UNITS,
+	UnitConversionError,
+	convertUnitValue as convertUnit,
+	getUnitSymbol,
+} from './format/units';
+export type { UnitFormatOptions } from './format/units';
+
+export { I18nProvider } from './react/I18nProvider';
+export type { I18nProviderProps } from './react/I18nProvider';
+export { useLocale, useTranslation } from './react/hooks';
+export type { UseLocaleResult, UseTranslationResult } from './react/hooks';

package/src/locale/activeLocale.ts

@@ -1,45 +1,42 @@
-import type { ActiveLocalePreference } from '../config/types';
-
-export interface ActiveLocaleStore {
-	get(): ActiveLocalePreference;
-	set(preference: ActiveLocalePreference): void;
-	subscribe(listener: () => void): () => void;
-	/** Monotonic change counter consumed by useSyncExternalStore. */
-	getVersion(): number;
-}
-
-export function createActiveLocaleStore(
-	initial: ActiveLocalePreference,
-): ActiveLocaleStore {
-	let preference = initial;
-	let version = 0;
-	const listeners = new Set<() => void>();
-
-	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);
-			};
-		},
-		getVersion: () => version,
-	};
-}
+import { createListenerSet } from '@chipmobilesdk/rn-core';
+
+import { defaultReporter, describeError, type I18nDiagnosticHandler } from '../config/diagnostics';
+import type { ActiveLocalePreference } from '../config/types';
+
+export interface ActiveLocaleStore {
+	get(): ActiveLocalePreference;
+	set(preference: ActiveLocalePreference): void;
+	subscribe(listener: () => void): () => void;
+	/** Monotonic change counter consumed by useSyncExternalStore. */
+	getVersion(): number;
+}
+
+export function createActiveLocaleStore(
+	initial: ActiveLocalePreference,
+	report: I18nDiagnosticHandler = defaultReporter,
+): ActiveLocaleStore {
+	let preference = initial;
+	let version = 0;
+	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;
+			// 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,
+	};
+}