@chipmobilesdk/rn-i18n 0.2.0 → 0.4.0

package/src/i18n.ts

@@ -15,10 +15,12 @@ import { validateConfig } from './config/validateConfig';
 import { createActiveLocaleStore } from './locale/activeLocale';
 import { defaultDeviceLocaleProvider, matchSupportedLocale } from './locale/deviceLocale';
 import {
+	clearPersistedLocale,
 	readPersistedLocale,
 	readPersistedLocaleSync,
 	writePersistedLocale,
 } from './locale/persistence';
+import { hasPluralRule } from './translation/plurals';
 import { translate } from './translation/resolver';
 import type { ResolverContext } from './translation/resolver';
 import { createRuntimeRegistry, registerRuntimeEntries } from './translation/runtimeKeys';
@@ -42,9 +44,23 @@ export interface I18n<TKey extends string = string> {
 	getLocale(): ActiveLocalePreference;
 	/** Switches at runtime without restart and persists best-effort. */
 	setLocale(code: string): Promise<void>;
+	/**
+	 * Forgets the stored choice and follows the device again — the "System
+	 * language" option a settings screen offers (I18N-17). Resolves to the
+	 * locale now active.
+	 */
+	useDeviceLocale(): Promise<ActiveLocalePreference>;
 	getSupportedLocales(): readonly LocaleConfig[];
 	formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
-	formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+	/**
+	 * Options are merged over the locale's default (`{ month: 'long' }` keeps the
+	 * year and day). `replaceDefaults` uses only what is passed.
+	 */
+	formatDate(
+		value: Date | number,
+		options?: Intl.DateTimeFormatOptions,
+		formatting?: { replaceDefaults?: boolean },
+	): string;
 	formatCurrency(value: number, currency?: string, options?: Intl.NumberFormatOptions): string;
 	formatUnit(value: number, options?: UnitFormatOptions): string;
 	convertUnit(value: number, from: UnitId, to: UnitId): number;
@@ -81,6 +97,21 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 		report,
 	);
 
+	// A language this package has no plural rule for falls back to
+	// `count === 1 ? one : other`, which is wrong for most of the world. Said
+	// once per locale, at creation, rather than never (I18N-12).
+	for (const locale of locales) {
+		if (!hasPluralRule(locale)) {
+			report({
+				code: 'plural_rule_default',
+				locale: locale.code,
+				message:
+					`No plural rule for "${locale.code}"; falling back to "count === 1 selects one". ` +
+					'Declare `pluralRule` on the locale if that is not how the language works.',
+			});
+		}
+	}
+
 	const resolverContext: ResolverContext = {
 		localesByCode,
 		resources: config.resources,
@@ -123,13 +154,33 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 		);
 	};
 
+	/**
+	 * `init()` runs once, and loses to the user.
+	 *
+	 * It used to be re-run by every caller (StrictMode mounts an effect twice),
+	 * and the persisted value it had awaited was written in unconditionally — so
+	 * a locale the user picked, or a deep link set, while the read was in flight
+	 * was overwritten by the old one (I18N-07).
+	 */
+	let initialized: Promise<void> | undefined;
+	let switched = false;
+
+	const runInit = async (): Promise<void> => {
+		const persisted =
+			persistenceEnabled && config.storage
+				? await readPersistedLocale(config.storage, report)
+				: null;
+		if (switched) {
+			// The user chose while the read was in flight; their choice stands.
+			return;
+		}
+		resolveInitialLocale(persisted);
+	};
+
 	return {
-		async init() {
-			resolveInitialLocale(
-				persistenceEnabled && config.storage
-					? await readPersistedLocale(config.storage, report)
-					: null,
-			);
+		init() {
+			initialized ??= runInit();
+			return initialized;
 		},
 
 		initSync() {
@@ -162,12 +213,34 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 			if (!localesByCode.has(code)) {
 				throw new Error(`[rn-i18n] Cannot switch to unsupported locale "${code}".`);
 			}
+			switched = true;
+			const current = store.get();
+			if (current.code === code && current.source === 'runtimeSwitch') {
+				// Already this locale, by this route: re-rendering the whole tree and
+				// rewriting storage would change nothing (I18N-07).
+				return;
+			}
 			store.set({ code, source: 'runtimeSwitch', recovered: false });
 			if (persistenceEnabled && config.storage) {
 				await writePersistedLocale(config.storage, code, report);
 			}
 		},
 
+		async useDeviceLocale() {
+			switched = true;
+			if (persistenceEnabled && config.storage) {
+				await clearPersistedLocale(config.storage, report);
+			}
+			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 store.get();
+		},
+
 		getSupportedLocales() {
 			return locales;
 		},
@@ -183,9 +256,16 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 			);
 		},
 
-		formatDate(value, options) {
+		formatDate(value, options, formatting) {
 			const locale = activeLocale();
-			return formatDateValue(value, locale.code, locale.defaultDateFormat, options, invalidFormat);
+			return formatDateValue(
+				value,
+				locale.code,
+				locale.defaultDateFormat,
+				options,
+				invalidFormat,
+				formatting?.replaceDefaults === true,
+			);
 		},
 
 		formatCurrency(value, currency, options) {
@@ -218,6 +298,10 @@ export function createI18n<TKey extends string = string>(config: I18nConfig): I1
 
 		registerRuntimeEntries(entries) {
 			registerRuntimeEntries(runtimeEntries, entries);
+			// What `t()` answers has changed, so every subscriber has to read again:
+			// a feature that registered its entries after mounting used to leave the
+			// screen showing the key (I18N-06).
+			store.bump();
 		},
 
 		subscribe(listener) {

package/src/index.ts

@@ -2,9 +2,11 @@
  * @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.
+ * This is the single entrypoint, and the package is React Native code only. The
+ * Node-only extraction and synchronization tooling is a package of its own,
+ * `@chipmobilesdk/rn-i18n-tooling` (the `chip-i18n` CLI): it used to ship inside
+ * this tarball as TypeScript source under `./tooling`, which no consumer could
+ * execute.
  */
 
 export { createI18n } from './i18n';

package/src/locale/activeLocale.ts

@@ -7,6 +7,12 @@ export interface ActiveLocaleStore {
 	get(): ActiveLocalePreference;
 	set(preference: ActiveLocalePreference): void;
 	subscribe(listener: () => void): () => void;
+	/**
+	 * Notifies subscribers without changing the locale: what reaches the screen
+	 * changed, not which language it is in (a runtime entry registered by a
+	 * lazily loaded feature, say).
+	 */
+	bump(): void;
 	/** Monotonic change counter consumed by useSyncExternalStore. */
 	getVersion(): number;
 }
@@ -36,6 +42,10 @@ export function createActiveLocaleStore(
 			// app showed one locale and stored another.
 			listeners.notify();
 		},
+		bump() {
+			version += 1;
+			listeners.notify();
+		},
 		subscribe: listener => listeners.add(listener),
 		getVersion: () => version,
 	};

package/src/locale/persistence.ts

@@ -57,3 +57,22 @@ export async function writePersistedLocale(
 		});
 	}
 }
+
+/**
+ * Forgets the stored choice, so the next launch follows the device again. The
+ * adapter's `removeItem` was required by the contract and called by nothing
+ * until `useDeviceLocale()` (I18N-17). Best-effort, like the write.
+ */
+export async function clearPersistedLocale(
+	storage: LocaleStorageAdapter,
+	report: I18nDiagnosticHandler = defaultReporter,
+): Promise<void> {
+	try {
+		await storage.removeItem(LOCALE_STORAGE_KEY);
+	} catch (error) {
+		report({
+			code: 'locale_write_failed',
+			message: `Failed to forget the persisted locale preference: ${describeError(error)}`,
+		});
+	}
+}

package/src/translation/plurals.ts

@@ -11,22 +11,91 @@ export const PLURAL_CATEGORIES: readonly PluralCategory[] = [
 
 const oneOtherRule: PluralRule = count => (count === 1 ? 'one' : 'other');
 const otherOnlyRule: PluralRule = () => 'other';
+/** French and Brazilian Portuguese: 0 and 1 are both singular. */
+const zeroOneRule: PluralRule = count => (count === 0 || count === 1 ? 'one' : 'other');
+
+/** Russian, Ukrainian, Polish, Czech and their neighbours (CLDR). */
+const slavicRule: PluralRule = count => {
+	if (!Number.isInteger(count)) {
+		return 'many';
+	}
+	const mod10 = Math.abs(count) % 10;
+	const mod100 = Math.abs(count) % 100;
+	if (mod10 === 1 && mod100 !== 11) {
+		return 'one';
+	}
+	if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) {
+		return 'few';
+	}
+	return 'many';
+};
+
+/** Arabic (CLDR), which uses every category. */
+const arabicRule: PluralRule = count => {
+	if (count === 0) return 'zero';
+	if (count === 1) return 'one';
+	if (count === 2) return 'two';
+	const mod100 = Math.abs(count) % 100;
+	if (mod100 >= 3 && mod100 <= 10) return 'few';
+	if (mod100 >= 11 && mod100 <= 99) return 'many';
+	return 'other';
+};
 
 /**
- * Package-owned plural rules. Intl.PluralRules is not implemented by Hermes,
- * so rules are resolved from configuration to keep behavior identical across
- * devices and test environments. Languages without a built-in rule use the
- * documented default (`count === 1` selects `one`, everything else `other`)
- * unless the locale configuration supplies a custom rule.
+ * Package-owned plural rules, a compact subset of CLDR. Intl.PluralRules is not
+ * implemented by Hermes, so rules are resolved from configuration to keep
+ * behavior identical across devices and test environments.
+ *
+ * A language that is not here falls back to `count === 1 ? one : other`, which
+ * is wrong for most of the world — Korean and Thai have no singular, French
+ * calls 0 singular, Russian has `few` and `many` — so the fallback now reports
+ * a diagnostic once per locale rather than being silently applied (I18N-12).
  */
 const BUILT_IN_RULES: Record<string, PluralRule> = {
+	// one/other
 	en: oneOtherRule,
+	de: oneOtherRule,
+	es: oneOtherRule,
+	it: oneOtherRule,
+	nl: oneOtherRule,
+	sv: oneOtherRule,
+	da: oneOtherRule,
+	nb: oneOtherRule,
+	fi: oneOtherRule,
+	el: oneOtherRule,
+	he: oneOtherRule,
+	// other only
 	ja: otherOnlyRule,
 	vi: otherOnlyRule,
+	ko: otherOnlyRule,
+	zh: otherOnlyRule,
+	th: otherOnlyRule,
+	id: otherOnlyRule,
+	ms: otherOnlyRule,
+	// 0 and 1 are singular
+	fr: zeroOneRule,
+	pt: zeroOneRule,
+	// Slavic
+	ru: slavicRule,
+	uk: slavicRule,
+	pl: slavicRule,
+	cs: slavicRule,
+	sk: slavicRule,
+	// Every category
+	ar: arabicRule,
 };
 
 export const DEFAULT_PLURAL_RULE: PluralRule = oneOtherRule;
 
+/** True when this package has a rule for the language, or the locale brought one. */
+export function hasPluralRule(locale: LocaleConfig): boolean {
+	if (locale.pluralRule) {
+		return true;
+	}
+	const language = locale.code.split('-')[0]?.toLowerCase() ?? '';
+	return language in BUILT_IN_RULES;
+}
+
 export function resolvePluralRule(locale: LocaleConfig): PluralRule {
 	if (locale.pluralRule) {
 		return locale.pluralRule;

package/src/translation/runtimeKeys.ts

@@ -1,4 +1,4 @@
-import type { RuntimeTranslationEntry } from '../config/types';
+import { I18nConfigError, type RuntimeTranslationEntry } from '../config/types';
 
 /**
  * Registry of declared runtime-only translation entries. Entries participate
@@ -17,10 +17,37 @@ export function createRuntimeRegistry(
 	return registry;
 }
 
+/**
+ * The same checks the configured entries get (I18N-06): an entry registered at
+ * runtime by a lazily loaded feature used to be written in unvalidated, so a
+ * missing key or a non-string default surfaced only when a screen rendered it.
+ */
+export function validateRuntimeEntries(entries: readonly RuntimeTranslationEntry[]): void {
+	const issues: string[] = [];
+	const seen = new Set<string>();
+	for (const entry of entries) {
+		if (!entry?.key) {
+			issues.push('Runtime-only entries must declare a non-empty key.');
+			continue;
+		}
+		if (seen.has(entry.key)) {
+			issues.push(`Duplicate runtime-only entry "${entry.key}".`);
+		}
+		seen.add(entry.key);
+		if (typeof entry.defaultText !== 'string') {
+			issues.push(`Runtime-only entry "${entry.key}" must declare default text.`);
+		}
+	}
+	if (issues.length > 0) {
+		throw new I18nConfigError(issues);
+	}
+}
+
 export function registerRuntimeEntries(
 	registry: RuntimeEntryRegistry,
 	entries: readonly RuntimeTranslationEntry[],
 ): void {
+	validateRuntimeEntries(entries);
 	for (const entry of entries) {
 		registry.set(entry.key, entry);
 	}

package/src/tooling/cli.ts

@@ -1,76 +0,0 @@
-/**
- * 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,62 +0,0 @@
-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 };
-}

package/src/tooling/index.ts

@@ -1,27 +0,0 @@
-/**
- * Programmatic surface of the Node-only extraction and synchronization
- * tooling, exposed as `@chipmobilesdk/rn-i18n/tooling`. This entrypoint must
- * never be imported from React Native code; the runtime API lives at the
- * package root (LIB-003).
- */
-
-export { globToRegExp, listSourceFiles, scanSource } from './scan.ts';
-export { flattenTranslations, nestTranslations, syncLocaleFiles } from './sync.ts';
-export { buildReport, renderReport } from './report.ts';
-export { generateKeysFile, renderKeysModule } from './generateKeys.ts';
-export type { GenerateKeysResult } from './generateKeys.ts';
-export { SyncConfigError, loadRuntimeEntries, runSync, validateSyncConfig } from './runner.ts';
-export type { SyncRunResult } from './runner.ts';
-export type {
-	AmbiguousUsage,
-	ExtractionReport,
-	KeyConflict,
-	LocaleSyncResult,
-	PatternConfig,
-	ReportOutcome,
-	RuntimeEntryConfig,
-	SourceLocation,
-	SyncConfig,
-	TemplateKey,
-	TranslationTemplate,
-} from './types.ts';

package/src/tooling/report.ts

@@ -1,109 +0,0 @@
-import type {
-	ExtractionReport,
-	LocaleSyncResult,
-	ReportOutcome,
-	RuntimeEntryConfig,
-	TranslationTemplate,
-} from './types.ts';
-
-function perLocale(
-	results: readonly LocaleSyncResult[],
-	select: (result: LocaleSyncResult) => string[],
-): Record<string, string[]> {
-	const record: Record<string, string[]> = {};
-	for (const result of results) {
-		record[result.locale] = select(result);
-	}
-	return record;
-}
-
-/**
- * Assembles the extraction/synchronization report distinguishing scanned
- * template keys, runtime-only keys, stale removals, ambiguous usages, and
- * conflicts (FR-026, FR-036).
- */
-export function buildReport(
-	template: TranslationTemplate,
-	syncResults: readonly LocaleSyncResult[],
-	runtimeEntries: readonly RuntimeEntryConfig[],
-): ExtractionReport {
-	const errors = syncResults.filter(result => result.error).map(result => result.error!);
-
-	let outcome: ReportOutcome = 'success';
-	if (
-		template.ambiguous.length > 0 ||
-		syncResults.some(result => result.addedKeys.length > 0 || result.runtimeReported.length > 0)
-	) {
-		outcome = 'completedWithWarnings';
-	}
-	if (errors.length > 0 || template.conflicts.length > 0) {
-		outcome = 'failed';
-	}
-
-	return {
-		outcome,
-		discovered: template.keys.map(key => ({
-			key: key.key,
-			defaultText: key.defaultText,
-			locations: key.locations.map(location => `${location.file}:${location.line}`),
-		})),
-		createdLocaleFiles: syncResults
-			.filter(result => result.created && !result.error)
-			.map(result => ({ locale: result.locale, filePath: result.filePath })),
-		addedKeys: perLocale(syncResults, result => result.addedKeys),
-		preservedKeys: perLocale(syncResults, result => result.preservedKeys),
-		removedStaleKeys: perLocale(syncResults, result => result.removedKeys),
-		missingPerLocale: perLocale(syncResults, result =>
-			[...result.addedKeys, ...result.runtimeAdded, ...result.runtimeReported].sort((a, b) =>
-				a.localeCompare(b, 'en'),
-			),
-		),
-		runtimeOnly: {
-			declared: runtimeEntries.map(entry => entry.key),
-			preserved: perLocale(syncResults, result => result.runtimePreserved),
-			added: perLocale(syncResults, result => result.runtimeAdded),
-			reported: perLocale(syncResults, result => result.runtimeReported),
-		},
-		ambiguous: template.ambiguous,
-		conflicts: template.conflicts,
-		errors,
-	};
-}
-
-/** Renders the report as readable text for CLI output. */
-export function renderReport(report: ExtractionReport): string {
-	const lines: string[] = [];
-	lines.push(`i18n sync outcome: ${report.outcome}`);
-	lines.push(`Discovered keys: ${report.discovered.length}`);
-	for (const created of report.createdLocaleFiles) {
-		lines.push(`Created locale file: ${created.locale} -> ${created.filePath}`);
-	}
-	for (const [locale, keys] of Object.entries(report.addedKeys)) {
-		if (keys.length > 0) {
-			lines.push(`Added [${locale}]: ${keys.join(', ')}`);
-		}
-	}
-	for (const [locale, keys] of Object.entries(report.removedStaleKeys)) {
-		if (keys.length > 0) {
-			lines.push(`Removed stale [${locale}]: ${keys.join(', ')}`);
-		}
-	}
-	for (const [locale, keys] of Object.entries(report.runtimeOnly.reported)) {
-		if (keys.length > 0) {
-			lines.push(`Runtime-only missing [${locale}]: ${keys.join(', ')}`);
-		}
-	}
-	for (const usage of report.ambiguous) {
-		lines.push(`Ambiguous usage at ${usage.file}:${usage.line}: ${usage.snippet}`);
-	}
-	for (const conflict of report.conflicts) {
-		const sources = conflict.values
-			.map(value => `"${value.text}" (${value.location.file}:${value.location.line})`)
-			.join(' vs ');
-		lines.push(`Conflict for key "${conflict.key}": ${sources}`);
-	}
-	for (const error of report.errors) {
-		lines.push(`Error: ${error}`);
-	}
-	return lines.join('\n');
-}