@chipmobilesdk/rn-i18n 0.1.1 → 0.1.3

package/src/locale/deviceLocale.ts

@@ -1,54 +1,50 @@
-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;
-}
+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

@@ -1,37 +1,31 @@
-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)}`,
-		);
-	}
-}
+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

@@ -1,35 +1,31 @@
-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;
-}
+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

@@ -1,61 +1,57 @@
-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),
-	};
-}
+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),
+	};
+}

package/src/tooling/cli.ts

@@ -1,78 +1,76 @@
-/**
- * Extraction/synchronization CLI. Node-only; run through the root npm
- * script under Node >= 22.11 with TypeScript type stripping:
- *
- *   npm run i18n:sync
- *   node --experimental-strip-types packages/rn-i18n/src/tooling/cli.ts --config i18n-sync.config.json
- *
- * Exit codes: 0 success or warnings, 1 blocking findings (conflicts or
- * malformed locale files), 2 invalid configuration or internal error.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { renderReport } from './report.ts';
-import { SyncConfigError, runSync } from './runner.ts';
-import type { SyncConfig } from './types.ts';
-
-function parseArgs(argv: readonly string[]): { configPath: string } {
-	let configPath = 'i18n-sync.config.json';
-	for (let index = 0; index < argv.length; index += 1) {
-		if (argv[index] === '--config' && argv[index + 1]) {
-			configPath = argv[index + 1];
-			index += 1;
-		}
-	}
-	return { configPath };
-}
-
-async function main(): Promise<number> {
-	const rootDir = process.cwd();
-	const { configPath } = parseArgs(process.argv.slice(2));
-	const absoluteConfigPath = path.resolve(rootDir, configPath);
-
-	if (!fs.existsSync(absoluteConfigPath)) {
-		console.error(`[rn-i18n] Sync configuration not found: ${configPath}`);
-		return 2;
-	}
-
-	let config: SyncConfig;
-	try {
-		config = JSON.parse(fs.readFileSync(absoluteConfigPath, 'utf8')) as SyncConfig;
-	} catch (error) {
-		console.error(
-			`[rn-i18n] Sync configuration is not valid JSON: ${String(error)}`,
-		);
-		return 2;
-	}
-
-	try {
-		const { report, generatedKeysChanged } = await runSync(rootDir, config);
-		console.log(renderReport(report));
-		if (config.generateKeysFile) {
-			console.log(
-				generatedKeysChanged
-					? `Typed keys regenerated: ${config.generateKeysFile}`
-					: `Typed keys unchanged: ${config.generateKeysFile}`,
-			);
-		}
-		return report.outcome === 'failed' ? 1 : 0;
-	} catch (error) {
-		if (error instanceof SyncConfigError) {
-			console.error(`[rn-i18n] ${error.message}`);
-		} else {
-			console.error(`[rn-i18n] Sync failed: ${String(error)}`);
-		}
-		return 2;
-	}
-}
-
-main().then(
-	code => {
-		process.exitCode = code;
-	},
-	error => {
-		console.error(`[rn-i18n] Unexpected failure: ${String(error)}`);
-		process.exitCode = 2;
-	},
-);
+/**
+ * Extraction/synchronization CLI. Node-only; run through the root npm
+ * script under Node >= 22.11 with TypeScript type stripping:
+ *
+ *   npm run i18n:sync
+ *   node --experimental-strip-types packages/rn-i18n/src/tooling/cli.ts --config i18n-sync.config.json
+ *
+ * Exit codes: 0 success or warnings, 1 blocking findings (conflicts or
+ * malformed locale files), 2 invalid configuration or internal error.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { renderReport } from './report.ts';
+import { SyncConfigError, runSync } from './runner.ts';
+import type { SyncConfig } from './types.ts';
+
+function parseArgs(argv: readonly string[]): { configPath: string } {
+	let configPath = 'i18n-sync.config.json';
+	for (let index = 0; index < argv.length; index += 1) {
+		if (argv[index] === '--config' && argv[index + 1]) {
+			configPath = argv[index + 1];
+			index += 1;
+		}
+	}
+	return { configPath };
+}
+
+async function main(): Promise<number> {
+	const rootDir = process.cwd();
+	const { configPath } = parseArgs(process.argv.slice(2));
+	const absoluteConfigPath = path.resolve(rootDir, configPath);
+
+	if (!fs.existsSync(absoluteConfigPath)) {
+		console.error(`[rn-i18n] Sync configuration not found: ${configPath}`);
+		return 2;
+	}
+
+	let config: SyncConfig;
+	try {
+		config = JSON.parse(fs.readFileSync(absoluteConfigPath, 'utf8')) as SyncConfig;
+	} catch (error) {
+		console.error(`[rn-i18n] Sync configuration is not valid JSON: ${String(error)}`);
+		return 2;
+	}
+
+	try {
+		const { report, generatedKeysChanged } = await runSync(rootDir, config);
+		console.log(renderReport(report));
+		if (config.generateKeysFile) {
+			console.log(
+				generatedKeysChanged
+					? `Typed keys regenerated: ${config.generateKeysFile}`
+					: `Typed keys unchanged: ${config.generateKeysFile}`,
+			);
+		}
+		return report.outcome === 'failed' ? 1 : 0;
+	} catch (error) {
+		if (error instanceof SyncConfigError) {
+			console.error(`[rn-i18n] ${error.message}`);
+		} else {
+			console.error(`[rn-i18n] Sync failed: ${String(error)}`);
+		}
+		return 2;
+	}
+}
+
+main().then(
+	code => {
+		process.exitCode = code;
+	},
+	error => {
+		console.error(`[rn-i18n] Unexpected failure: ${String(error)}`);
+		process.exitCode = 2;
+	},
+);

package/src/tooling/generateKeys.ts

@@ -1,68 +1,62 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import type { RuntimeEntryConfig, TranslationTemplate } from './types.ts';
-
-/**
- * Renders the typed key contract: the union of scanned template keys and
- * declared runtime-only keys (FR-041). Apps bind lookups to the generated
- * type so `tsc --noEmit` reports invalid or stale key usage before release.
- */
-export function renderKeysModule(
-	template: TranslationTemplate,
-	runtimeEntries: readonly RuntimeEntryConfig[],
-	typeName = 'AppI18nKey',
-): string {
-	const templateKeys = template.keys
-		.map(key => key.key)
-		.sort((a, b) => a.localeCompare(b, 'en'));
-	const runtimeKeys = runtimeEntries
-		.map(entry => entry.key)
-		.sort((a, b) => a.localeCompare(b, 'en'));
-
-	const renderList = (keys: readonly string[]) =>
-		keys.length === 0
-			? '[]'
-			: `[\n${keys.map(key => `\t'${key}',`).join('\n')}\n]`;
-
-	return [
-		'// AUTO-GENERATED by @chipmobilesdk/rn-i18n tooling. Do not edit by hand.',
-		'// Regenerate with: npm run i18n:sync',
-		'',
-		`export const I18N_TEMPLATE_KEYS = ${renderList(templateKeys)} as const;`,
-		'',
-		`export const I18N_RUNTIME_ONLY_KEYS = ${renderList(runtimeKeys)} as const;`,
-		'',
-		'export const I18N_KEYS = [',
-		'\t...I18N_TEMPLATE_KEYS,',
-		'\t...I18N_RUNTIME_ONLY_KEYS,',
-		'] as const;',
-		'',
-		`export type ${typeName} = (typeof I18N_KEYS)[number];`,
-		'',
-	].join('\n');
-}
-
-export interface GenerateKeysResult {
-	filePath: string;
-	changed: boolean;
-}
-
-/** Writes the typed key artifact and reports whether it changed (staleness). */
-export function generateKeysFile(
-	rootDir: string,
-	relativePath: string,
-	template: TranslationTemplate,
-	runtimeEntries: readonly RuntimeEntryConfig[],
-	typeName?: string,
-): GenerateKeysResult {
-	const filePath = path.join(rootDir, relativePath);
-	const content = renderKeysModule(template, runtimeEntries, typeName);
-	const previous = fs.existsSync(filePath)
-		? fs.readFileSync(filePath, 'utf8')
-		: undefined;
-	if (previous !== content) {
-		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		fs.writeFileSync(filePath, content, 'utf8');
-	}
-	return { filePath, changed: previous !== content };
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RuntimeEntryConfig, TranslationTemplate } from './types.ts';
+
+/**
+ * Renders the typed key contract: the union of scanned template keys and
+ * declared runtime-only keys (FR-041). Apps bind lookups to the generated
+ * type so `tsc --noEmit` reports invalid or stale key usage before release.
+ */
+export function renderKeysModule(
+	template: TranslationTemplate,
+	runtimeEntries: readonly RuntimeEntryConfig[],
+	typeName = 'AppI18nKey',
+): string {
+	const templateKeys = template.keys.map(key => key.key).sort((a, b) => a.localeCompare(b, 'en'));
+	const runtimeKeys = runtimeEntries
+		.map(entry => entry.key)
+		.sort((a, b) => a.localeCompare(b, 'en'));
+
+	const renderList = (keys: readonly string[]) =>
+		keys.length === 0 ? '[]' : `[\n${keys.map(key => `\t'${key}',`).join('\n')}\n]`;
+
+	return [
+		'// AUTO-GENERATED by @chipmobilesdk/rn-i18n tooling. Do not edit by hand.',
+		'// Regenerate with: npm run i18n:sync',
+		'',
+		`export const I18N_TEMPLATE_KEYS = ${renderList(templateKeys)} as const;`,
+		'',
+		`export const I18N_RUNTIME_ONLY_KEYS = ${renderList(runtimeKeys)} as const;`,
+		'',
+		'export const I18N_KEYS = [',
+		'\t...I18N_TEMPLATE_KEYS,',
+		'\t...I18N_RUNTIME_ONLY_KEYS,',
+		'] as const;',
+		'',
+		`export type ${typeName} = (typeof I18N_KEYS)[number];`,
+		'',
+	].join('\n');
+}
+
+export interface GenerateKeysResult {
+	filePath: string;
+	changed: boolean;
+}
+
+/** Writes the typed key artifact and reports whether it changed (staleness). */
+export function generateKeysFile(
+	rootDir: string,
+	relativePath: string,
+	template: TranslationTemplate,
+	runtimeEntries: readonly RuntimeEntryConfig[],
+	typeName?: string,
+): GenerateKeysResult {
+	const filePath = path.join(rootDir, relativePath);
+	const content = renderKeysModule(template, runtimeEntries, typeName);
+	const previous = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : undefined;
+	if (previous !== content) {
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.writeFileSync(filePath, content, 'utf8');
+	}
+	return { filePath, changed: previous !== content };
+}