@chipmobilesdk/rn-i18n 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @chipmobilesdk/rn-i18n
 
+## 0.3.0
+
+### Minor Changes
+
+- `registerRuntimeEntries` notifies subscribers, so copy a lazily loaded feature registers after its screen mounted appears instead of leaving the key on screen until something else re-rendered. Entries registered at runtime get the same validation as configured ones: a missing key or a non-string default throws `I18nConfigError` there rather than surfacing at render time. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  `init()` runs once however many times it is called — StrictMode mounts an effect twice — and loses to the user: a `setLocale` made while the persisted read was in flight is no longer overwritten by the stored value. Setting the locale that is already active changes nothing and re-renders nothing.
+
+  `i18n.useDeviceLocale()` forgets the stored choice and detects again, which is the "System language" option a settings screen offers; the storage adapter's `removeItem`, required by the contract and called by nothing, is what it uses.
+
+  Plural rules cover a compact CLDR subset instead of three languages: English and its neighbours, Korean, Chinese, Thai, Indonesian and Malay (no singular), French and Portuguese (0 is singular), Russian, Ukrainian, Polish, Czech and Slovak (`few`/`many`), and Arabic (every category). A language outside the table still falls back to "1 is singular", but now reports a `plural_rule_default` diagnostic once, rather than shipping wrong plurals in silence.
+
+  `formatDate` **merges** its options over the locale's default date format, as `formatNumber` always has: `{ month: 'long' }` keeps the year and the day. Pass `formatDate(value, options, { replaceDefaults: true })` for the old behaviour of replacing them. `formatCurrency` deliberately does not apply the locale's default number options, because a currency's own minor units must win.
+
+  The generated keys file escapes a key holding an apostrophe or a backslash, which used to produce a file that did not parse and failed `tsc` for the whole app.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -231,6 +231,14 @@ createI18n({
 
 ## Formatting
 
+Options **merge** over the active locale's defaults, for every formatter:
+`formatDate(value, { month: 'long' })` keeps the locale's year and day, exactly as
+`formatNumber(value, { maximumFractionDigits: 0 })` keeps the rest of the locale's number
+options. Pass `formatDate(value, options, { replaceDefaults: true })` to use only what you
+give it. `formatCurrency` deliberately does not take the locale's default number options:
+a currency carries its own minor units (yen has none), and generic number defaults would
+override them.
+
 `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
@@ -238,6 +246,18 @@ 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.
 
+## Switching, and following the device
+
+```ts
+await i18n.setLocale('vi-VN');   // the user chose a language
+await i18n.useDeviceLocale();    // "System language": forget the choice, detect again
+```
+
+`init()` resolves the locale once — persisted, then device, then the primary fallback —
+and is safe to call again (it returns the same promise). A `setLocale` during that read
+wins: the stored value never overwrites a choice the user has just made. Setting the
+locale already active changes nothing and re-renders nothing.
+
 ## Diagnostics
 
 Missing translations and variables, fallbacks, invalid formats, persistence

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-i18n",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

package/skills/sdk-rn-i18n/SKILL.md

@@ -46,9 +46,36 @@ Runtime:
 - `I18nConfigError` — thrown on invalid configuration at startup; an rn-core SDK error with an
   `I18nErrorCode`
 
+Formatting, on the instance (all locale-aware, all through Hermes's Intl):
+
+- `i18n.formatNumber(value, options?)`, `i18n.formatCurrency(value, currency?, options?)`,
+  `i18n.formatUnit(value, options?)` — options merge over the locale's defaults
+- `i18n.formatDate(value, options?, { replaceDefaults? })` — options merge too;
+  `replaceDefaults: true` uses only what is passed
+- `i18n.convertUnit(value, from, to)`, `SUPPORTED_UNITS`, `UnitConversionError`
+
+Locale, on the instance: `init()` (idempotent), `initSync()`, `setLocale(code)`,
+`useDeviceLocale()` (forget the stored choice and follow the device again),
+`getLocale()`, `getSupportedLocales()`, `registerRuntimeEntries(entries)`,
+`subscribe(listener)`, `getVersion()`
+
 Types: `I18n`, `UnitFormatOptions`, `I18nProviderProps`, `UseLocaleResult`,
 `UseTranslationResult`
 
+## Plural rules are declared, not inferred
+
+Hermes has no `Intl.PluralRules`, so this package carries a compact CLDR subset
+(en/de/es/it/nl/sv/da/nb/fi/el/he, ja/vi/ko/zh/th/id/ms, fr/pt, ru/uk/pl/cs/sk, ar). A
+language outside it falls back to "1 is singular" **and reports a
+`plural_rule_default` diagnostic** — declare `pluralRule` on the locale rather than
+shipping wrong plurals.
+
+## Entries registered at runtime re-render
+
+`registerRuntimeEntries` notifies subscribers, so a lazily loaded feature's copy appears
+without another render pass, and a malformed entry throws `I18nConfigError` there and then
+instead of rendering the key.
+
 `I18nConfigError` throws at startup by design — a misconfigured i18n setup should fail
 loudly, not silently render keys.
 

package/src/config/diagnostics.ts

@@ -12,6 +12,7 @@ export type I18nDiagnosticCode =
 	| 'invalid_value'
 	| 'invalid_format'
 	| 'locale_unsupported'
+	| 'plural_rule_default'
 	| 'locale_read_failed'
 	| 'locale_write_failed'
 	| 'listener_threw';
@@ -33,6 +34,7 @@ const SEVERITY: Record<I18nDiagnosticCode, DiagnosticSeverity> = {
 	invalid_value: 'warn',
 	invalid_format: 'warn',
 	locale_unsupported: 'warn',
+	plural_rule_default: 'warn',
 	locale_read_failed: 'warn',
 	locale_write_failed: 'warn',
 	listener_threw: 'error',

package/src/format/currency.ts

@@ -5,6 +5,11 @@ import { applyInvalidFormatPolicy } from './invalid';
 /**
  * Locale-aware currency formatting. The locale's configured default currency
  * applies unless the caller passes an explicit currency override (FR-021).
+ *
+ * `locale.defaultNumberFormat` is deliberately **not** applied here: a currency
+ * carries its own minor units (yen has none, dinar has three), and the locale's
+ * generic number options would override them — ¥1,234.56 instead of ¥1,235.
+ * Pass the options you want for a currency explicitly (I18N-09).
  */
 export function formatCurrencyValue(
 	value: number,

package/src/format/date.ts

@@ -4,9 +4,14 @@ import { applyInvalidFormatPolicy } from './invalid';
 
 /**
  * Locale-aware date formatting through the Hermes built-in
- * Intl.DateTimeFormat. The locale's configured default date format applies
- * unless the caller passes explicit overrides (FR-020). Options are limited
- * to component options supported by Hermes on both platforms.
+ * Intl.DateTimeFormat.
+ *
+ * Options are **merged** over the locale's configured default, the way
+ * `formatNumber` has always worked: `{ month: 'long' }` changes the month and
+ * keeps the year and day. Replacing the default wholesale, which this used to
+ * do, meant one option silently dropped every other component — and the two
+ * formatters disagreed about what an option meant (I18N-09). Pass
+ * `{ replaceDefaults: true }` for the old behaviour.
  */
 export function formatDateValue(
 	value: Date | number,
@@ -14,6 +19,7 @@ export function formatDateValue(
 	defaults: Intl.DateTimeFormatOptions,
 	override: Intl.DateTimeFormatOptions | undefined,
 	invalidFormat: InvalidFormatPolicy,
+	replaceDefaults = false,
 ): string {
 	const date = value instanceof Date ? value : new Date(value);
 	if (Number.isNaN(date.getTime())) {
@@ -22,7 +28,7 @@ export function formatDateValue(
 			`Cannot format invalid date value "${String(value)}" for locale "${localeCode}".`,
 		);
 	}
-	const options = override ?? defaults;
+	const options = replaceDefaults ? (override ?? defaults) : { ...defaults, ...override };
 	// rn-core's cached formatter (I18N-03); a bad option is a format problem (I18N-08).
 	try {
 		return getDateTimeFormat(localeCode, options).format(date);

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/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/tooling/generateKeys.ts

@@ -17,8 +17,11 @@ export function renderKeysModule(
 		.map(entry => entry.key)
 		.sort((a, b) => a.localeCompare(b, 'en'));
 
+	// Escaped, not interpolated: a key holding an apostrophe or a backslash wrote
+	// a file that did not parse, and `tsc` then failed for the whole app (I18N-20).
+	const literal = (key: string) => `'${key.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 	const renderList = (keys: readonly string[]) =>
-		keys.length === 0 ? '[]' : `[\n${keys.map(key => `\t'${key}',`).join('\n')}\n]`;
+		keys.length === 0 ? '[]' : `[\n${keys.map(key => `\t${literal(key)},`).join('\n')}\n]`;
 
 	return [
 		'// AUTO-GENERATED by @chipmobilesdk/rn-i18n tooling. Do not edit by hand.',

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);
 	}