@chipmobilesdk/rn-i18n 0.1.2 → 0.1.3

package/package.json

@@ -1,49 +1,46 @@
-{
-	"name": "@chipmobilesdk/rn-i18n",
-	"version": "0.1.2",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		},
-		"./tooling": {
-			"types": "./src/tooling/index.ts",
-			"node": "./src/tooling/index.ts",
-			"default": "./src/tooling/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/i18n.ts",
-		"src/config",
-		"src/translation",
-		"src/locale",
-		"src/format",
-		"src/react",
-		"src/tooling",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85"
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-i18n",
+	"version": "0.1.3",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./tooling": {
+			"types": "./src/tooling/index.ts",
+			"node": "./src/tooling/index.ts",
+			"default": "./src/tooling/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/i18n.ts",
+		"src/config",
+		"src/translation",
+		"src/locale",
+		"src/format",
+		"src/react",
+		"src/tooling",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:check": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

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

@@ -1,62 +1,61 @@
----
-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
+- `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` |

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