@chipmobilesdk/rn-i18n 0.1.2 → 0.2.0

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

@@ -1,62 +1,65 @@
----
-name: sdk-rn-i18n
-description: "Localization via @chipmobilesdk/rn-i18n: createI18n, useTranslation, useLocale, locale persistence, unit formatting, and the extraction/sync CLI. Use when adding translated strings, switching locale, formatting units, or syncing translation keys."
-metadata:
-  package: "@chipmobilesdk/rn-i18n"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-i18n
-
-Localization with device-locale detection, persisted locale choice, typed translation
-access, unit/number formatting, and a CLI that extracts and synchronizes keys.
-
-## Use this when
-
-- Adding or changing any user-facing string
-- Reading or switching the active locale
-- Formatting numbers, dates or units for a locale
-- Translation keys are missing, stale, or out of sync across locale files
-
-## Never hardcode a user-facing string
-
-Every string rendered to a user goes through `useTranslation`. A literal in a component
-is a defect — it cannot be translated and will not appear in extraction output.
-
-## Keys are generated, not hand-maintained
-
-Do not hand-edit locale JSON to add a key. Run the extraction/sync CLI so every locale
-file stays aligned. The monorepo exposes it as `npm run i18n:sync`. See
-`## Extraction & synchronization CLI`.
-
-## Public API (v0.1.2)
-
-Runtime:
-
-- `createI18n(...)` → `I18n`
-- `I18nProvider` (+ `I18nProviderProps`)
-- `useTranslation()` → `UseTranslationResult`
-- `useLocale()` → `UseLocaleResult`
-- `defaultDeviceLocaleProvider` — device locale detection
-- `LOCALE_STORAGE_KEY` — where the chosen locale persists
-- `I18nConfigError` — thrown on invalid configuration at startup
-
-Types: `I18n`, `UnitFormatOptions`, `I18nProviderProps`, `UseLocaleResult`,
-`UseTranslationResult`
-
-`I18nConfigError` throws at startup by design — a misconfigured i18n setup should fail
-loudly, not silently render keys.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-i18n/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Installation`, `## Quick start` |
-| Full export list | `## Public API` |
-| Locale file layout, plurals | `## Translations` |
-| Adding/syncing keys | `## Extraction & synchronization CLI` |
-| Version/peer constraints | `## Compatibility` |
+---
+name: sdk-rn-i18n
+description: "Localization via @chipmobilesdk/rn-i18n: createI18n, useTranslation, useLocale, locale persistence, unit formatting, and the extraction/sync CLI. Use when adding translated strings, switching locale, formatting units, or syncing translation keys."
+metadata:
+  package: "@chipmobilesdk/rn-i18n"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-i18n
+
+Localization with device-locale detection, persisted locale choice, typed translation
+access, unit/number formatting, and a CLI that extracts and synchronizes keys.
+
+## Use this when
+
+- Adding or changing any user-facing string
+- Reading or switching the active locale
+- Formatting numbers, dates or units for a locale
+- Translation keys are missing, stale, or out of sync across locale files
+
+## Never hardcode a user-facing string
+
+Every string rendered to a user goes through `useTranslation`. A literal in a component
+is a defect — it cannot be translated and will not appear in extraction output.
+
+## Keys are generated, not hand-maintained
+
+Do not hand-edit locale JSON to add a key. Run the extraction/sync CLI so every locale
+file stays aligned. The monorepo exposes it as `npm run i18n:sync`. See
+`## Extraction & synchronization CLI`.
+
+## Public API
+
+Runtime:
+
+- `createI18n(...)` → `I18n`
+- `I18nProvider` (+ `I18nProviderProps`)
+- `useTranslation()` → `UseTranslationResult`
+- `useLocale()` → `UseLocaleResult`
+- `defaultDeviceLocaleProvider` — device locale detection
+- `LOCALE_STORAGE_KEY` — where the chosen locale persists
+- `i18n.initSync()` — resolve the locale before the first render when storage reads
+  synchronously; `localeStorageFromKeyValue(port)` makes such storage from an rn-core
+  key-value port (MMKV)
+- `I18nConfigError` — thrown on invalid configuration at startup; an rn-core SDK error with an
+  `I18nErrorCode`
+
+Types: `I18n`, `UnitFormatOptions`, `I18nProviderProps`, `UseLocaleResult`,
+`UseTranslationResult`
+
+`I18nConfigError` throws at startup by design — a misconfigured i18n setup should fail
+loudly, not silently render keys.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-i18n/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Installation`, `## Quick start` |
+| Full export list | `## Public API` |
+| Locale file layout, plurals | `## Translations` |
+| Adding/syncing keys | `## Extraction & synchronization CLI` |
+| Version/peer constraints | `## Compatibility` |

package/src/config/catalog.ts

@@ -0,0 +1,25 @@
+import type { RuntimeTranslationEntry } from './types';
+
+/**
+ * Runtime entries for a package's message catalog (I18N-13), so an app registers
+ * an SDK's copy in one line and translates it like its own:
+ *
+ * ```ts
+ * createI18n({ ...config, runtimeEntries: runtimeEntriesFromCatalog(paymentMessages.user) });
+ * ```
+ *
+ * Catalogs mark variables `{name}`; rn-i18n's are `{{name}}`, so they are
+ * converted. `policy: 'add'` lets the sync CLI write missing keys into each locale
+ * file with the default text.
+ */
+export function runtimeEntriesFromCatalog(
+	catalog: Readonly<Record<string, string>>,
+	options: { readonly policy?: 'add' | 'report'; readonly description?: string } = {},
+): RuntimeTranslationEntry[] {
+	return Object.entries(catalog).map(([key, text]) => ({
+		key,
+		defaultText: text.replace(/(?<!\{)\{(\w+)\}(?!\})/g, '{{$1}}'),
+		policy: options.policy ?? 'report',
+		...(options.description === undefined ? {} : { description: options.description }),
+	}));
+}

package/src/config/diagnostics.ts

@@ -0,0 +1,68 @@
+import {
+	createDiagnosticChannel,
+	redactPatterns,
+	type DiagnosticSeverity,
+} from '@chipmobilesdk/rn-core';
+
+/** What rn-i18n reports. Stable: an app may branch on these. */
+export type I18nDiagnosticCode =
+	| 'missing_translation'
+	| 'fallback_used'
+	| 'missing_variable'
+	| 'invalid_value'
+	| 'invalid_format'
+	| 'locale_unsupported'
+	| 'locale_read_failed'
+	| 'locale_write_failed'
+	| 'listener_threw';
+
+export interface I18nDiagnostic {
+	readonly code: I18nDiagnosticCode;
+	/** For people: names the key, locale or variable involved. */
+	readonly message: string;
+	readonly key?: string;
+	readonly locale?: string;
+}
+
+export type I18nDiagnosticHandler = (diagnostic: I18nDiagnostic) => void;
+
+const SEVERITY: Record<I18nDiagnosticCode, DiagnosticSeverity> = {
+	missing_translation: 'warn',
+	fallback_used: 'info',
+	missing_variable: 'warn',
+	invalid_value: 'warn',
+	invalid_format: 'warn',
+	locale_unsupported: 'warn',
+	locale_read_failed: 'warn',
+	locale_write_failed: 'warn',
+	listener_threw: 'error',
+};
+
+const channel = createDiagnosticChannel<I18nDiagnosticCode>('rn-i18n');
+
+/**
+ * One place every diagnostic goes through (I18N-11): the app's SDK sinks always
+ * (`installSdkSink` from rn-core), then `onDiagnostic` when the app gave one,
+ * otherwise `console.warn` in development builds and tests only.
+ */
+export function createReporter(onDiagnostic?: I18nDiagnosticHandler): I18nDiagnosticHandler {
+	return diagnostic => {
+		channel.emit(diagnostic.code, SEVERITY[diagnostic.code], {
+			...(diagnostic.key === undefined ? {} : { key: diagnostic.key }),
+			...(diagnostic.locale === undefined ? {} : { locale: diagnostic.locale }),
+		});
+		if (onDiagnostic) {
+			onDiagnostic(diagnostic);
+		} else if (typeof __DEV__ === 'undefined' || __DEV__) {
+			console.warn(`[rn-i18n] ${diagnostic.message}`);
+		}
+	};
+}
+
+/** For the few call sites that run before or outside an i18n instance. */
+export const defaultReporter = createReporter();
+
+/** Foreign error text, shaped before it reaches a message. */
+export function describeError(error: unknown): string {
+	return redactPatterns(error instanceof Error ? error.message : String(error));
+}

package/src/config/errors.ts

@@ -0,0 +1,28 @@
+import { SdkError } from '@chipmobilesdk/rn-core';
+
+/** The package's error codes. */
+export type I18nErrorCode = 'invalid_config' | 'unit_conversion';
+
+/**
+ * Configuration error listing every detected violation. An `SdkError`
+ * (`@chipmobilesdk/rn-core`) with `pkg: 'rn-i18n'`.
+ */
+export class I18nConfigError extends SdkError<I18nErrorCode> {
+	readonly issues: readonly string[];
+
+	constructor(issues: readonly string[]) {
+		super('rn-i18n', 'invalid_config', {
+			message: `Invalid i18n configuration:\n- ${issues.join('\n- ')}`,
+		});
+		this.name = 'I18nConfigError';
+		this.issues = issues;
+	}
+}
+
+/** A unit conversion the package cannot perform, such as across dimensions. */
+export class UnitConversionError extends SdkError<I18nErrorCode> {
+	constructor(message: string) {
+		super('rn-i18n', 'unit_conversion', { message });
+		this.name = 'UnitConversionError';
+	}
+}

package/src/config/types.ts

@@ -1,152 +1,150 @@
-/**
- * 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 one runtime dependency, rn-core; 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.
+ */
+
+import type { I18nDiagnosticHandler } from './diagnostics';
+
+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>;
+	/**
+	 * A synchronous read, for a store that has one (MMKV, rn-core's `KeyValuePort`).
+	 * With it, `initSync()` resolves the locale before the first render, so the app
+	 * never paints a frame in the wrong language (PERF-08).
+	 */
+	getItemSync?(key: string): string | null;
+}
+
+/** 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;
+	/**
+	 * Receives every diagnostic: missing translations and variables, fallbacks,
+	 * invalid formats, persistence failures. Defaults to `console.warn` in
+	 * development builds only. Diagnostics also reach rn-core's SDK sinks.
+	 */
+	onDiagnostic?: I18nDiagnosticHandler;
+	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;
+}
+
+// Kept importable from here for compatibility; the errors live in config/errors.ts (I18N-14).
+export { I18nConfigError } from './errors';