@chipmobilesdk/rn-i18n 0.1.0

package/src/format/invalid.ts

@@ -0,0 +1,16 @@
+import type { InvalidFormatPolicy } from '../config/types';
+
+/**
+ * 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}`);
+	if (policy.mode === 'error') {
+		throw new RangeError(`[rn-i18n] ${message}`);
+	}
+	return policy.text;
+}

package/src/format/number.ts

@@ -0,0 +1,25 @@
+import type { InvalidFormatPolicy } from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+
+/**
+ * Locale-aware number formatting through the Hermes built-in
+ * Intl.NumberFormat. The locale default options apply unless the caller
+ * passes explicit overrides (FR-019).
+ */
+export function formatNumberValue(
+	value: number,
+	localeCode: string,
+	defaults: Intl.NumberFormatOptions,
+	override: Intl.NumberFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format invalid number value "${String(value)}" for locale "${localeCode}".`,
+		);
+	}
+	return new Intl.NumberFormat(localeCode, { ...defaults, ...override }).format(
+		value,
+	);
+}

package/src/format/units.ts

@@ -0,0 +1,151 @@
+import type {
+	InvalidFormatPolicy,
+	UnitDimension,
+	UnitId,
+} from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+import { formatNumberValue } from './number';
+
+interface UnitDefinition {
+	dimension: UnitDimension;
+	/** Factor to the dimension's base unit; unused for temperature. */
+	factor: number;
+	symbol: string;
+}
+
+/**
+ * Package-owned unit registry and conversion tables. Intl.NumberFormat unit
+ * style is not consistently available under Hermes, so the numeric part is
+ * formatted through Intl and the unit symbol is appended from this registry
+ * (research R4). Base units: meter, kilogram, liter, celsius.
+ */
+const UNIT_REGISTRY: Record<UnitId, UnitDefinition> = {
+	millimeter: { dimension: 'length', factor: 0.001, symbol: 'mm' },
+	centimeter: { dimension: 'length', factor: 0.01, symbol: 'cm' },
+	meter: { dimension: 'length', factor: 1, symbol: 'm' },
+	kilometer: { dimension: 'length', factor: 1000, symbol: 'km' },
+	inch: { dimension: 'length', factor: 0.0254, symbol: 'in' },
+	foot: { dimension: 'length', factor: 0.3048, symbol: 'ft' },
+	mile: { dimension: 'length', factor: 1609.344, symbol: 'mi' },
+	gram: { dimension: 'mass', factor: 0.001, symbol: 'g' },
+	kilogram: { dimension: 'mass', factor: 1, symbol: 'kg' },
+	ounce: { dimension: 'mass', factor: 0.028349523125, symbol: 'oz' },
+	pound: { dimension: 'mass', factor: 0.45359237, symbol: 'lb' },
+	milliliter: { dimension: 'volume', factor: 0.001, symbol: 'ml' },
+	liter: { dimension: 'volume', factor: 1, symbol: 'l' },
+	gallon: { dimension: 'volume', factor: 3.785411784, symbol: 'gal' },
+	celsius: { dimension: 'temperature', factor: 1, symbol: '°C' },
+	fahrenheit: { dimension: 'temperature', factor: 1, symbol: '°F' },
+	kelvin: { dimension: 'temperature', factor: 1, symbol: 'K' },
+};
+
+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';
+	}
+}
+
+export function getUnitSymbol(unit: UnitId): string {
+	return UNIT_REGISTRY[unit].symbol;
+}
+
+function toCelsius(value: number, from: UnitId): number {
+	switch (from) {
+		case 'fahrenheit':
+			return ((value - 32) * 5) / 9;
+		case 'kelvin':
+			return value - 273.15;
+		default:
+			return value;
+	}
+}
+
+function fromCelsius(value: number, to: UnitId): number {
+	switch (to) {
+		case 'fahrenheit':
+			return (value * 9) / 5 + 32;
+		case 'kelvin':
+			return value + 273.15;
+		default:
+			return value;
+	}
+}
+
+/**
+ * Converts between compatible supported units. Unknown units or conversions
+ * across dimensions throw a UnitConversionError (FR-044/FR-045).
+ */
+export function convertUnitValue(
+	value: number,
+	from: UnitId,
+	to: UnitId,
+): number {
+	const fromDef = UNIT_REGISTRY[from];
+	const toDef = UNIT_REGISTRY[to];
+	if (!fromDef || !toDef) {
+		throw new UnitConversionError(
+			`Unknown unit in conversion "${from}" -> "${to}".`,
+		);
+	}
+	if (fromDef.dimension !== toDef.dimension) {
+		throw new UnitConversionError(
+			`Cannot convert between incompatible dimensions "${fromDef.dimension}" (${from}) and "${toDef.dimension}" (${to}).`,
+		);
+	}
+	if (!Number.isFinite(value)) {
+		throw new UnitConversionError(
+			`Cannot convert invalid value "${String(value)}" from "${from}" to "${to}".`,
+		);
+	}
+	if (from === to) {
+		return value;
+	}
+	if (fromDef.dimension === 'temperature') {
+		return fromCelsius(toCelsius(value, from), to);
+	}
+	return (value * fromDef.factor) / toDef.factor;
+}
+
+export interface UnitFormatOptions extends Intl.NumberFormatOptions {
+	/** Unit the value is expressed in. Default: the locale's default unit. */
+	from?: UnitId;
+	/** Unit to display. Default: `from` (no conversion). */
+	to?: UnitId;
+}
+
+/**
+ * Converts (when requested) and formats a measurement value: locale-aware
+ * numeric part via Intl.NumberFormat plus the package-owned unit symbol.
+ */
+export function formatUnitValue(
+	value: number,
+	localeCode: string,
+	localeDefaultUnit: UnitId,
+	numberDefaults: Intl.NumberFormatOptions,
+	options: UnitFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	const { from = localeDefaultUnit, to = from, ...numberOptions } = options ?? {};
+	let converted: number;
+	try {
+		converted = convertUnitValue(value, from, to);
+	} catch (error) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			error instanceof Error ? error.message : String(error),
+		);
+	}
+	const formatted = formatNumberValue(
+		converted,
+		localeCode,
+		numberDefaults,
+		numberOptions,
+		invalidFormat,
+	);
+	return `${formatted} ${getUnitSymbol(to)}`;
+}

package/src/i18n.ts

@@ -0,0 +1,222 @@
+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();
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * @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';

package/src/locale/activeLocale.ts

@@ -0,0 +1,35 @@
+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;
+			for (const listener of [...listeners]) {
+				listener();
+			}
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getVersion: () => version,
+	};
+}

package/src/locale/deviceLocale.ts

@@ -0,0 +1,54 @@
+import type {
+	DeviceLocaleProvider,
+	LocaleConfig,
+	LocaleSelectionSource,
+} from '../config/types';
+
+/**
+ * Default device locale detection. Hermes resolves the Intl default locale
+ * from the device locale on both Android and iOS, so no native module is
+ * required. Apps may inject their own provider (e.g. react-native-localize)
+ * through `I18nConfig.deviceLocale`.
+ */
+export const defaultDeviceLocaleProvider: DeviceLocaleProvider = () => {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().locale;
+	} catch {
+		return undefined;
+	}
+};
+
+export interface DeviceLocaleMatch {
+	code: string;
+	source: Extract<LocaleSelectionSource, 'device' | 'languageMatch'>;
+}
+
+/**
+ * Matches a detected device locale against the supported locales: an exact
+ * (case-insensitive) match wins; otherwise a device language that matches
+ * exactly one supported locale selects that locale (US4 scenario 3).
+ */
+export function matchSupportedLocale(
+	deviceLocale: string | undefined,
+	locales: readonly LocaleConfig[],
+): DeviceLocaleMatch | undefined {
+	if (!deviceLocale) {
+		return undefined;
+	}
+	const normalized = deviceLocale.toLowerCase();
+	const exact = locales.find(locale => locale.code.toLowerCase() === normalized);
+	if (exact) {
+		return { code: exact.code, source: 'device' };
+	}
+	const language = normalized.split('-')[0];
+	if (!language) {
+		return undefined;
+	}
+	const languageMatches = locales.filter(
+		locale => locale.code.toLowerCase().split('-')[0] === language,
+	);
+	if (languageMatches.length === 1) {
+		return { code: languageMatches[0].code, source: 'languageMatch' };
+	}
+	return undefined;
+}

package/src/locale/persistence.ts

@@ -0,0 +1,37 @@
+import type { LocaleStorageAdapter } from '../config/types';
+
+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> {
+	try {
+		return await storage.getItem(LOCALE_STORAGE_KEY);
+	} catch (error) {
+		console.warn(
+			`[rn-i18n] Failed to read the persisted locale preference: ${String(error)}`,
+		);
+		return null;
+	}
+}
+
+/**
+ * Persists the selected locale. Persistence is best-effort: a write failure
+ * is reported but the in-memory locale switch stays authoritative.
+ */
+export async function writePersistedLocale(
+	storage: LocaleStorageAdapter,
+	code: string,
+): Promise<void> {
+	try {
+		await storage.setItem(LOCALE_STORAGE_KEY, code);
+	} catch (error) {
+		console.warn(
+			`[rn-i18n] Failed to persist locale "${code}": ${String(error)}`,
+		);
+	}
+}

package/src/react/I18nProvider.tsx

@@ -0,0 +1,35 @@
+import React, { createContext, useContext } from 'react';
+import type { ReactNode } from 'react';
+import type { I18n } from '../i18n';
+
+// The context intentionally erases the app-specific key type; the typed
+// surface is restored by the hooks' generic parameters.
+export const I18nContext = createContext<I18n<string> | null>(null);
+
+export interface I18nProviderProps {
+	i18n: I18n<never>;
+	children: ReactNode;
+}
+
+/**
+ * Provides the I18n instance to the React tree. Locale changes re-render
+ * consumers through the hooks' useSyncExternalStore subscription, so a
+ * runtime switch updates UI within one interaction cycle (PERF-002).
+ */
+export function I18nProvider({ i18n, children }: I18nProviderProps) {
+	return (
+		<I18nContext.Provider value={i18n as unknown as I18n<string>}>
+			{children}
+		</I18nContext.Provider>
+	);
+}
+
+export function useI18nContext(): I18n<string> {
+	const i18n = useContext(I18nContext);
+	if (!i18n) {
+		throw new Error(
+			'[rn-i18n] No I18n instance found. Wrap your app in <I18nProvider>.',
+		);
+	}
+	return i18n;
+}

package/src/react/hooks.ts

@@ -0,0 +1,61 @@
+import { useSyncExternalStore } from 'react';
+import type {
+	ActiveLocalePreference,
+	LocaleConfig,
+	LocaleDirection,
+	TranslateOptions,
+	TranslateVars,
+} from '../config/types';
+import type { I18n } from '../i18n';
+import { useI18nContext } from './I18nProvider';
+
+function useLocaleVersion(i18n: I18n<string>): void {
+	useSyncExternalStore(i18n.subscribe, i18n.getVersion, i18n.getVersion);
+}
+
+export interface UseTranslationResult<TKey extends string> {
+	t: (key: TKey, vars?: TranslateVars, options?: TranslateOptions) => string;
+	locale: string;
+}
+
+/**
+ * Returns the translation function bound to the active locale. Pass the
+ * app's generated key type for compile-time key validation (FR-041):
+ * `const { t } = useTranslation<AppI18nKey>();`
+ */
+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,
+	};
+}
+
+export interface UseLocaleResult {
+	locale: string;
+	direction: LocaleDirection;
+	preference: ActiveLocalePreference;
+	supportedLocales: readonly LocaleConfig[];
+	setLocale: (code: string) => Promise<void>;
+}
+
+/** Returns active locale state, direction metadata, and the locale switcher. */
+export function useLocale(): UseLocaleResult {
+	const i18n = useI18nContext();
+	useLocaleVersion(i18n);
+	const preference = i18n.getLocale();
+	const supportedLocales = i18n.getSupportedLocales();
+	const active = supportedLocales.find(
+		locale => locale.code === preference.code,
+	);
+	return {
+		locale: preference.code,
+		direction: active?.direction ?? 'ltr',
+		preference,
+		supportedLocales,
+		setLocale: code => i18n.setLocale(code),
+	};
+}