@chipmobilesdk/rn-i18n 0.1.1 → 0.1.3

package/src/config/types.ts

@@ -1,152 +1,144 @@
-/**
- * Public configuration and contract types for @chipmobilesdk/rn-i18n.
- *
- * The package has zero runtime dependencies: formatting uses the Intl APIs
- * built into Hermes (Intl.NumberFormat, Intl.DateTimeFormat), while plural
- * rules and unit conversion are package-owned because Intl.PluralRules and
- * Intl unit-style formatting are not reliably available in Hermes.
- */
-
-export type LocaleDirection = 'ltr' | 'rtl';
-
-export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
-
-export type PluralRule = (count: number) => PluralCategory;
-
-export type UnitDimension = 'length' | 'mass' | 'volume' | 'temperature';
-
-export type UnitId =
-	| 'millimeter'
-	| 'centimeter'
-	| 'meter'
-	| 'kilometer'
-	| 'inch'
-	| 'foot'
-	| 'mile'
-	| 'gram'
-	| 'kilogram'
-	| 'ounce'
-	| 'pound'
-	| 'milliliter'
-	| 'liter'
-	| 'gallon'
-	| 'celsius'
-	| 'fahrenheit'
-	| 'kelvin';
-
-export interface LocaleConfig {
-	/** BCP-47 language-region code, e.g. `vi-VN`, `en-US`, `ja-JP`. */
-	code: string;
-	displayName: string;
-	direction: LocaleDirection;
-	/**
-	 * Ordered locale codes consulted when a key is missing from this locale.
-	 * Every entry must be another supported locale; cycles, duplicates, and
-	 * self-references are rejected during setup validation.
-	 */
-	fallbackChain: string[];
-	/** ISO-4217 currency code used when no explicit currency is requested. */
-	defaultCurrency: string;
-	defaultUnit: UnitId;
-	/**
-	 * Default Intl.DateTimeFormat options for this locale. Restricted to the
-	 * component options supported by Hermes on both Android and iOS.
-	 */
-	defaultDateFormat: Intl.DateTimeFormatOptions;
-	/** Default Intl.NumberFormat options for this locale. */
-	defaultNumberFormat: Intl.NumberFormatOptions;
-	/** Optional plural rule override; defaults to the built-in language rule. */
-	pluralRule?: PluralRule;
-}
-
-export type TranslationNode = string | { [key: string]: TranslationNode };
-
-export type TranslationNamespace = { [key: string]: TranslationNode };
-
-/** App-owned translation resources keyed by locale code. */
-export type TranslationResources = { [localeCode: string]: TranslationNamespace };
-
-/**
- * A translation key intentionally resolved at runtime and therefore not
- * discoverable by static source scanning. Declared entries are protected
- * from removal during locale JSON synchronization.
- */
-export interface RuntimeTranslationEntry {
-	key: string;
-	/** Template text used when no locale resource provides a value. */
-	defaultText: string;
-	/**
-	 * Synchronization policy when the key is missing from a locale file:
-	 * `add` writes the default text, `report` only lists it. Default: `report`.
-	 */
-	policy?: 'add' | 'report';
-	/** Owning feature note surfaced in the extraction report. */
-	description?: string;
-}
-
-export type MissingTranslationPolicy =
-	| { mode: 'key' }
-	| { mode: 'placeholder'; text: string };
-
-export type InvalidFormatPolicy =
-	| { mode: 'placeholder'; text: string }
-	| { mode: 'error' };
-
-/** App-injected persistence contract. The package never bundles a backend. */
-export interface LocaleStorageAdapter {
-	getItem(key: string): Promise<string | null>;
-	setItem(key: string, value: string): Promise<void>;
-	removeItem(key: string): Promise<void>;
-}
-
-/** Returns the device locale, or undefined when detection is unavailable. */
-export type DeviceLocaleProvider = () => string | undefined;
-
-export interface I18nConfig {
-	locales: LocaleConfig[];
-	/** Recovery locale when persistence or device detection cannot decide. */
-	primaryLocale: string;
-	resources: TranslationResources;
-	runtimeEntries?: RuntimeTranslationEntry[];
-	/** Persist the selected locale across launches. Default: true. */
-	persistLocale?: boolean;
-	/** Required when `persistLocale` is not disabled. */
-	storage?: LocaleStorageAdapter;
-	deviceLocale?: DeviceLocaleProvider;
-	/** Default: `{ mode: 'key' }`. */
-	missingTranslation?: MissingTranslationPolicy;
-	/** Default: `{ mode: 'placeholder', text: '—' }`. */
-	invalidFormat?: InvalidFormatPolicy;
-}
-
-export type LocaleSelectionSource =
-	| 'persisted'
-	| 'device'
-	| 'languageMatch'
-	| 'primaryFallback'
-	| 'runtimeSwitch';
-
-export interface ActiveLocalePreference {
-	code: string;
-	source: LocaleSelectionSource;
-	/** True when an unsupported persisted locale was discarded. */
-	recovered: boolean;
-}
-
-export type TranslateVars = Record<string, string | number>;
-
-export interface TranslateOptions {
-	/** Selects the plural variant and is exposed as the `count` variable. */
-	count?: number;
-}
-
-/** Configuration error listing every detected violation. */
-export class I18nConfigError extends Error {
-	readonly issues: readonly string[];
-
-	constructor(issues: readonly string[]) {
-		super(`Invalid i18n configuration:\n- ${issues.join('\n- ')}`);
-		this.name = 'I18nConfigError';
-		this.issues = issues;
-	}
-}
+/**
+ * Public configuration and contract types for @chipmobilesdk/rn-i18n.
+ *
+ * The package has zero runtime dependencies: formatting uses the Intl APIs
+ * built into Hermes (Intl.NumberFormat, Intl.DateTimeFormat), while plural
+ * rules and unit conversion are package-owned because Intl.PluralRules and
+ * Intl unit-style formatting are not reliably available in Hermes.
+ */
+
+export type LocaleDirection = 'ltr' | 'rtl';
+
+export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+
+export type PluralRule = (count: number) => PluralCategory;
+
+export type UnitDimension = 'length' | 'mass' | 'volume' | 'temperature';
+
+export type UnitId =
+	| 'millimeter'
+	| 'centimeter'
+	| 'meter'
+	| 'kilometer'
+	| 'inch'
+	| 'foot'
+	| 'mile'
+	| 'gram'
+	| 'kilogram'
+	| 'ounce'
+	| 'pound'
+	| 'milliliter'
+	| 'liter'
+	| 'gallon'
+	| 'celsius'
+	| 'fahrenheit'
+	| 'kelvin';
+
+export interface LocaleConfig {
+	/** BCP-47 language-region code, e.g. `vi-VN`, `en-US`, `ja-JP`. */
+	code: string;
+	displayName: string;
+	direction: LocaleDirection;
+	/**
+	 * Ordered locale codes consulted when a key is missing from this locale.
+	 * Every entry must be another supported locale; cycles, duplicates, and
+	 * self-references are rejected during setup validation.
+	 */
+	fallbackChain: string[];
+	/** ISO-4217 currency code used when no explicit currency is requested. */
+	defaultCurrency: string;
+	defaultUnit: UnitId;
+	/**
+	 * Default Intl.DateTimeFormat options for this locale. Restricted to the
+	 * component options supported by Hermes on both Android and iOS.
+	 */
+	defaultDateFormat: Intl.DateTimeFormatOptions;
+	/** Default Intl.NumberFormat options for this locale. */
+	defaultNumberFormat: Intl.NumberFormatOptions;
+	/** Optional plural rule override; defaults to the built-in language rule. */
+	pluralRule?: PluralRule;
+}
+
+export type TranslationNode = string | { [key: string]: TranslationNode };
+
+export type TranslationNamespace = { [key: string]: TranslationNode };
+
+/** App-owned translation resources keyed by locale code. */
+export type TranslationResources = { [localeCode: string]: TranslationNamespace };
+
+/**
+ * A translation key intentionally resolved at runtime and therefore not
+ * discoverable by static source scanning. Declared entries are protected
+ * from removal during locale JSON synchronization.
+ */
+export interface RuntimeTranslationEntry {
+	key: string;
+	/** Template text used when no locale resource provides a value. */
+	defaultText: string;
+	/**
+	 * Synchronization policy when the key is missing from a locale file:
+	 * `add` writes the default text, `report` only lists it. Default: `report`.
+	 */
+	policy?: 'add' | 'report';
+	/** Owning feature note surfaced in the extraction report. */
+	description?: string;
+}
+
+export type MissingTranslationPolicy = { mode: 'key' } | { mode: 'placeholder'; text: string };
+
+export type InvalidFormatPolicy = { mode: 'placeholder'; text: string } | { mode: 'error' };
+
+/** App-injected persistence contract. The package never bundles a backend. */
+export interface LocaleStorageAdapter {
+	getItem(key: string): Promise<string | null>;
+	setItem(key: string, value: string): Promise<void>;
+	removeItem(key: string): Promise<void>;
+}
+
+/** Returns the device locale, or undefined when detection is unavailable. */
+export type DeviceLocaleProvider = () => string | undefined;
+
+export interface I18nConfig {
+	locales: LocaleConfig[];
+	/** Recovery locale when persistence or device detection cannot decide. */
+	primaryLocale: string;
+	resources: TranslationResources;
+	runtimeEntries?: RuntimeTranslationEntry[];
+	/** Persist the selected locale across launches. Default: true. */
+	persistLocale?: boolean;
+	/** Required when `persistLocale` is not disabled. */
+	storage?: LocaleStorageAdapter;
+	deviceLocale?: DeviceLocaleProvider;
+	/** Default: `{ mode: 'key' }`. */
+	missingTranslation?: MissingTranslationPolicy;
+	/** Default: `{ mode: 'placeholder', text: '—' }`. */
+	invalidFormat?: InvalidFormatPolicy;
+}
+
+export type LocaleSelectionSource =
+	'persisted' | 'device' | 'languageMatch' | 'primaryFallback' | 'runtimeSwitch';
+
+export interface ActiveLocalePreference {
+	code: string;
+	source: LocaleSelectionSource;
+	/** True when an unsupported persisted locale was discarded. */
+	recovered: boolean;
+}
+
+export type TranslateVars = Record<string, string | number>;
+
+export interface TranslateOptions {
+	/** Selects the plural variant and is exposed as the `count` variable. */
+	count?: number;
+}
+
+/** Configuration error listing every detected violation. */
+export class I18nConfigError extends Error {
+	readonly issues: readonly string[];
+
+	constructor(issues: readonly string[]) {
+		super(`Invalid i18n configuration:\n- ${issues.join('\n- ')}`);
+		this.name = 'I18nConfigError';
+		this.issues = issues;
+	}
+}

package/src/config/validateConfig.ts

@@ -1,174 +1,156 @@
-import type { I18nConfig, LocaleConfig } from './types';
-import { I18nConfigError } from './types';
-
-/**
- * Validates an I18nConfig before any localized content is served (FR-003,
- * FR-046). Collects every violation and throws a single I18nConfigError so
- * apps see the complete picture instead of fixing issues one at a time.
- */
-export function validateConfig(
-	config: I18nConfig,
-	knownUnits: ReadonlySet<string>,
-): void {
-	const issues: string[] = [];
-	const locales = Array.isArray(config.locales) ? config.locales : [];
-
-	if (locales.length === 0) {
-		issues.push('At least one supported locale must be declared.');
-	}
-
-	const codes = new Set<string>();
-	for (const locale of locales) {
-		if (codes.has(locale.code)) {
-			issues.push(`Duplicate locale code "${locale.code}".`);
-		}
-		codes.add(locale.code);
-	}
-
-	for (const locale of locales) {
-		validateLocale(locale, codes, knownUnits, issues);
-	}
-
-	detectFallbackCycles(locales, codes, issues);
-
-	if (locales.length > 0 && !codes.has(config.primaryLocale)) {
-		issues.push(
-			`Primary locale "${config.primaryLocale}" is not a supported locale.`,
-		);
-	}
-
-	for (const code of codes) {
-		const resource = config.resources?.[code];
-		if (resource === undefined || resource === null) {
-			issues.push(`Locale "${code}" has no translation resource.`);
-		}
-	}
-
-	if (config.persistLocale !== false && !config.storage) {
-		issues.push(
-			'Locale persistence is enabled but no storage adapter was injected. ' +
-				'Provide `storage` or set `persistLocale: false`.',
-		);
-	}
-
-	const runtimeKeys = new Set<string>();
-	for (const entry of config.runtimeEntries ?? []) {
-		if (!entry.key) {
-			issues.push('Runtime-only entries must declare a non-empty key.');
-			continue;
-		}
-		if (runtimeKeys.has(entry.key)) {
-			issues.push(`Duplicate runtime-only entry "${entry.key}".`);
-		}
-		runtimeKeys.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);
-	}
-}
-
-function validateLocale(
-	locale: LocaleConfig,
-	codes: ReadonlySet<string>,
-	knownUnits: ReadonlySet<string>,
-	issues: string[],
-): void {
-	const code = locale.code;
-	if (!code) {
-		issues.push('Every locale must declare a non-empty code.');
-		return;
-	}
-	if (!locale.displayName) {
-		issues.push(`Locale "${code}" must declare a display name.`);
-	}
-	if (locale.direction !== 'ltr' && locale.direction !== 'rtl') {
-		issues.push(`Locale "${code}" must declare direction "ltr" or "rtl".`);
-	}
-	if (!locale.defaultCurrency) {
-		issues.push(`Locale "${code}" must declare a default currency.`);
-	}
-	if (!knownUnits.has(locale.defaultUnit)) {
-		issues.push(
-			`Locale "${code}" declares unknown default unit "${locale.defaultUnit}".`,
-		);
-	}
-	if (typeof locale.defaultDateFormat !== 'object' || !locale.defaultDateFormat) {
-		issues.push(`Locale "${code}" must declare a default date format.`);
-	}
-	if (
-		typeof locale.defaultNumberFormat !== 'object' ||
-		!locale.defaultNumberFormat
-	) {
-		issues.push(`Locale "${code}" must declare a default number format.`);
-	}
-	if (!Array.isArray(locale.fallbackChain)) {
-		issues.push(`Locale "${code}" must declare a fallback chain array.`);
-		return;
-	}
-	const seen = new Set<string>();
-	for (const entry of locale.fallbackChain) {
-		if (entry === code) {
-			issues.push(`Locale "${code}" must not include itself in its fallback chain.`);
-		}
-		if (seen.has(entry)) {
-			issues.push(
-				`Locale "${code}" lists duplicate fallback-chain entry "${entry}".`,
-			);
-		}
-		seen.add(entry);
-		if (!codes.has(entry)) {
-			issues.push(
-				`Locale "${code}" references unsupported fallback locale "${entry}".`,
-			);
-		}
-	}
-}
-
-function detectFallbackCycles(
-	locales: readonly LocaleConfig[],
-	codes: ReadonlySet<string>,
-	issues: string[],
-): void {
-	const chains = new Map(
-		locales.map(locale => [
-			locale.code,
-			(locale.fallbackChain ?? []).filter(entry => codes.has(entry)),
-		]),
-	);
-	const states = new Map<string, 'visiting' | 'done'>();
-
-	const visit = (code: string, path: string[]): boolean => {
-		const state = states.get(code);
-		if (state === 'done') {
-			return false;
-		}
-		if (state === 'visiting') {
-			issues.push(
-				`Fallback cycle detected: ${[...path, code].join(' -> ')}.`,
-			);
-			return true;
-		}
-		states.set(code, 'visiting');
-		for (const next of chains.get(code) ?? []) {
-			if (visit(next, [...path, code])) {
-				states.set(code, 'done');
-				return true;
-			}
-		}
-		states.set(code, 'done');
-		return false;
-	};
-
-	for (const locale of locales) {
-		if (visit(locale.code, [])) {
-			// Report the first cycle only; one clear cycle message is actionable.
-			return;
-		}
-	}
-}
+import type { I18nConfig, LocaleConfig } from './types';
+import { I18nConfigError } from './types';
+
+/**
+ * Validates an I18nConfig before any localized content is served (FR-003,
+ * FR-046). Collects every violation and throws a single I18nConfigError so
+ * apps see the complete picture instead of fixing issues one at a time.
+ */
+export function validateConfig(config: I18nConfig, knownUnits: ReadonlySet<string>): void {
+	const issues: string[] = [];
+	const locales = Array.isArray(config.locales) ? config.locales : [];
+
+	if (locales.length === 0) {
+		issues.push('At least one supported locale must be declared.');
+	}
+
+	const codes = new Set<string>();
+	for (const locale of locales) {
+		if (codes.has(locale.code)) {
+			issues.push(`Duplicate locale code "${locale.code}".`);
+		}
+		codes.add(locale.code);
+	}
+
+	for (const locale of locales) {
+		validateLocale(locale, codes, knownUnits, issues);
+	}
+
+	detectFallbackCycles(locales, codes, issues);
+
+	if (locales.length > 0 && !codes.has(config.primaryLocale)) {
+		issues.push(`Primary locale "${config.primaryLocale}" is not a supported locale.`);
+	}
+
+	for (const code of codes) {
+		const resource = config.resources?.[code];
+		if (resource === undefined || resource === null) {
+			issues.push(`Locale "${code}" has no translation resource.`);
+		}
+	}
+
+	if (config.persistLocale !== false && !config.storage) {
+		issues.push(
+			'Locale persistence is enabled but no storage adapter was injected. ' +
+				'Provide `storage` or set `persistLocale: false`.',
+		);
+	}
+
+	const runtimeKeys = new Set<string>();
+	for (const entry of config.runtimeEntries ?? []) {
+		if (!entry.key) {
+			issues.push('Runtime-only entries must declare a non-empty key.');
+			continue;
+		}
+		if (runtimeKeys.has(entry.key)) {
+			issues.push(`Duplicate runtime-only entry "${entry.key}".`);
+		}
+		runtimeKeys.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);
+	}
+}
+
+function validateLocale(
+	locale: LocaleConfig,
+	codes: ReadonlySet<string>,
+	knownUnits: ReadonlySet<string>,
+	issues: string[],
+): void {
+	const code = locale.code;
+	if (!code) {
+		issues.push('Every locale must declare a non-empty code.');
+		return;
+	}
+	if (!locale.displayName) {
+		issues.push(`Locale "${code}" must declare a display name.`);
+	}
+	if (locale.direction !== 'ltr' && locale.direction !== 'rtl') {
+		issues.push(`Locale "${code}" must declare direction "ltr" or "rtl".`);
+	}
+	if (!locale.defaultCurrency) {
+		issues.push(`Locale "${code}" must declare a default currency.`);
+	}
+	if (!knownUnits.has(locale.defaultUnit)) {
+		issues.push(`Locale "${code}" declares unknown default unit "${locale.defaultUnit}".`);
+	}
+	if (typeof locale.defaultDateFormat !== 'object' || !locale.defaultDateFormat) {
+		issues.push(`Locale "${code}" must declare a default date format.`);
+	}
+	if (typeof locale.defaultNumberFormat !== 'object' || !locale.defaultNumberFormat) {
+		issues.push(`Locale "${code}" must declare a default number format.`);
+	}
+	if (!Array.isArray(locale.fallbackChain)) {
+		issues.push(`Locale "${code}" must declare a fallback chain array.`);
+		return;
+	}
+	const seen = new Set<string>();
+	for (const entry of locale.fallbackChain) {
+		if (entry === code) {
+			issues.push(`Locale "${code}" must not include itself in its fallback chain.`);
+		}
+		if (seen.has(entry)) {
+			issues.push(`Locale "${code}" lists duplicate fallback-chain entry "${entry}".`);
+		}
+		seen.add(entry);
+		if (!codes.has(entry)) {
+			issues.push(`Locale "${code}" references unsupported fallback locale "${entry}".`);
+		}
+	}
+}
+
+function detectFallbackCycles(
+	locales: readonly LocaleConfig[],
+	codes: ReadonlySet<string>,
+	issues: string[],
+): void {
+	const chains = new Map(
+		locales.map(locale => [
+			locale.code,
+			(locale.fallbackChain ?? []).filter(entry => codes.has(entry)),
+		]),
+	);
+	const states = new Map<string, 'visiting' | 'done'>();
+
+	const visit = (code: string, path: string[]): boolean => {
+		const state = states.get(code);
+		if (state === 'done') {
+			return false;
+		}
+		if (state === 'visiting') {
+			issues.push(`Fallback cycle detected: ${[...path, code].join(' -> ')}.`);
+			return true;
+		}
+		states.set(code, 'visiting');
+		for (const next of chains.get(code) ?? []) {
+			if (visit(next, [...path, code])) {
+				states.set(code, 'done');
+				return true;
+			}
+		}
+		states.set(code, 'done');
+		return false;
+	};
+
+	for (const locale of locales) {
+		if (visit(locale.code, [])) {
+			// Report the first cycle only; one clear cycle message is actionable.
+			return;
+		}
+	}
+}