@chipmobilesdk/rn-i18n 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,57 +1,70 @@
-# Changelog
-
-All notable changes to `@chipmobilesdk/rn-i18n` are documented here. This project
-follows [Semantic Versioning](https://semver.org/).
-
-## 0.1.2 — 2026-11-01
-
-### Fixed
-
-- **A throwing locale listener no longer breaks a locale switch.** Listeners
-  were notified without isolation, so one that threw skipped every listener
-  after it (React subscribers included) and made `setLocale` reject after the
-  switch but before the choice was persisted: the app showed one locale and
-  stored another. Each listener is now isolated and reported with
-  `console.warn`, and a listener unsubscribed by an earlier one during the
-  same change is no longer called. No code change is required.
-
-## 0.1.0 — 2026-06-13
-
-Initial release of the reusable mobile i18n and locale library.
-
-### Added
-
-- `createI18n(config)` with eager configuration validation: duplicate locales,
-  unknown/duplicate/cyclic fallback chains, missing fallback resources, and
-  missing storage adapter are rejected before any localized content is served.
-- Translation lookup with namespaced nested keys, ordered fallback-chain
-  resolution, `{{name}}` interpolation, package-owned pluralization, and a
-  deterministic missing-key policy (one console warning per failed lookup path).
-- Runtime locale switching without restart, persisted through an app-injected
-  `LocaleStorageAdapter`, with recovery from unsupported persisted values.
-- Device-locale initialization via an injectable provider (default backed by
-  Hermes `Intl`), with exact-match and single-language-match selection.
-- Locale-aware formatting: `formatNumber`, `formatDate`, `formatCurrency` (via
-  Hermes `Intl`), and package-owned `formatUnit`/`convertUnit` across length,
-  mass, volume, and temperature dimensions.
-- Declared runtime-only translation entries that resolve through the same
-  pipeline and are protected during synchronization.
-- React bindings: `I18nProvider`, `useTranslation`, `useLocale`.
-- Node-only extraction/synchronization CLI (`@chipmobilesdk/rn-i18n/tooling`):
-  regex-pattern source scanning, locale JSON create/add/preserve/remove,
-  ambiguous-usage and conflict reporting, malformed-file isolation, typed key
-  contract generation, and deterministic output.
-
-### Adoption notes
-
-- App-owned translations live in the consuming app (commonly
-  `src/i18n/locales/<locale>.json`), never inside this package.
-- Host frameworks (`react`, `react-native`) are peer dependencies; this package
-  has zero runtime dependencies.
-- No native modules, permissions, network calls, analytics, or tracking are
-  introduced; the locale preference stays on-device via the injected adapter.
-
-### Compatibility
-
-React `19.x`, React Native `0.85+` (Hermes), TypeScript `5.8+`, Node `>=22.11.0`
-for tooling. Android and iOS, with no native code.
+# @chipmobilesdk/rn-i18n
+
+## 0.1.3
+
+### Patch Changes
+
+- Packaging only; no code change. The package no longer declares `engines.node`: a
+  React Native package does not run on Node, so the field only produced install
+  warnings in apps on another Node version. rn-i18n's command-line tooling does run
+  on Node; its README's compatibility table states the version it needs. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
+
+## 0.1.2 — 2026-11-01
+
+### Fixed
+
+- **A throwing locale listener no longer breaks a locale switch.** Listeners
+  were notified without isolation, so one that threw skipped every listener
+  after it (React subscribers included) and made `setLocale` reject after the
+  switch but before the choice was persisted: the app showed one locale and
+  stored another. Each listener is now isolated and reported with
+  `console.warn`, and a listener unsubscribed by an earlier one during the
+  same change is no longer called. No code change is required.
+
+## 0.1.1 — 2026-08-01
+
+### Changed
+
+- The package now ships its agent skill (`skills/`), which consuming apps
+  copy in with `scripts/sync-sdk-skills.mjs`. No code change.
+
+## 0.1.0 — 2026-06-13
+
+Initial release of the reusable mobile i18n and locale library.
+
+### Added
+
+- `createI18n(config)` with eager configuration validation: duplicate locales,
+  unknown/duplicate/cyclic fallback chains, missing fallback resources, and
+  missing storage adapter are rejected before any localized content is served.
+- Translation lookup with namespaced nested keys, ordered fallback-chain
+  resolution, `{{name}}` interpolation, package-owned pluralization, and a
+  deterministic missing-key policy (one console warning per failed lookup path).
+- Runtime locale switching without restart, persisted through an app-injected
+  `LocaleStorageAdapter`, with recovery from unsupported persisted values.
+- Device-locale initialization via an injectable provider (default backed by
+  Hermes `Intl`), with exact-match and single-language-match selection.
+- Locale-aware formatting: `formatNumber`, `formatDate`, `formatCurrency` (via
+  Hermes `Intl`), and package-owned `formatUnit`/`convertUnit` across length,
+  mass, volume, and temperature dimensions.
+- Declared runtime-only translation entries that resolve through the same
+  pipeline and are protected during synchronization.
+- React bindings: `I18nProvider`, `useTranslation`, `useLocale`.
+- Node-only extraction/synchronization CLI (`@chipmobilesdk/rn-i18n/tooling`):
+  regex-pattern source scanning, locale JSON create/add/preserve/remove,
+  ambiguous-usage and conflict reporting, malformed-file isolation, typed key
+  contract generation, and deterministic output.
+
+### Adoption notes
+
+- App-owned translations live in the consuming app (commonly
+  `src/i18n/locales/<locale>.json`), never inside this package.
+- Host frameworks (`react`, `react-native`) are peer dependencies; this package
+  has zero runtime dependencies.
+- No native modules, permissions, network calls, analytics, or tracking are
+  introduced; the locale preference stays on-device via the injected adapter.
+
+### Compatibility
+
+React `19.x`, React Native `0.85+` (Hermes), TypeScript `5.8+`, Node `>=22.11.0`
+for tooling. Android and iOS, with no native code.

package/README.md

@@ -1,218 +1,218 @@
-# @chipmobilesdk/rn-i18n
-
-Reusable localization for ChipMobileSdk-family React Native apps: per-locale
-configuration, app-owned namespaced translations, typed keys, interpolation,
-pluralization, fallback chains, runtime locale switching with app-injected
-persistence, device-locale detection, locale-aware number/date/currency/unit
-formatting, and a Node CLI that extracts and synchronizes translation keys.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Zero runtime dependencies.** Formatting uses the `Intl` APIs built into
-  Hermes; plural rules and unit conversion are package-owned.
-- **No native code.** Storage and (optionally) device-locale detection are
-  injected by the consuming app.
-- **Public package.** Published under the `@chipmobilesdk` npm organization.
-- **Version**: `0.1.2`
-- **Entrypoints**: `@chipmobilesdk/rn-i18n` and the Node-only
-  `@chipmobilesdk/rn-i18n/tooling`
-
-## Installation
-
-This package ships TypeScript sources and is consumed through the workspace or
-the public npm registry:
-
-```bash
-npm install @chipmobilesdk/rn-i18n
-```
-
-Host frameworks are peer dependencies:
-
-```jsonc
-// peerDependencies
-"react": ">=19",
-"react-native": ">=0.85"
-```
-
-## Quick start
-
-```ts
-import { createI18n } from '@chipmobilesdk/rn-i18n';
-import enUS from './locales/en-US.json';
-import viVN from './locales/vi-VN.json';
-import { storageAdapter } from './storage';
-import type { AppI18nKey } from './keys.generated';
-
-export const i18n = createI18n<AppI18nKey>({
-  primaryLocale: 'en-US',
-  locales: [
-    {
-      code: 'en-US',
-      displayName: 'English (US)',
-      direction: 'ltr',
-      fallbackChain: [],
-      defaultCurrency: 'USD',
-      defaultUnit: 'mile',
-      defaultDateFormat: { year: 'numeric', month: 'short', day: 'numeric' },
-      defaultNumberFormat: { maximumFractionDigits: 2 },
-    },
-    {
-      code: 'vi-VN',
-      displayName: 'Tiếng Việt',
-      direction: 'ltr',
-      fallbackChain: ['en-US'],
-      defaultCurrency: 'VND',
-      defaultUnit: 'kilometer',
-      defaultDateFormat: { day: '2-digit', month: '2-digit', year: 'numeric' },
-      defaultNumberFormat: { maximumFractionDigits: 2 },
-    },
-  ],
-  resources: { 'en-US': enUS, 'vi-VN': viVN },
-  storage: storageAdapter,
-});
-
-await i18n.init(); // persisted -> device -> primary fallback
-```
-
-Wrap the app and use the hooks:
-
-```tsx
-import { I18nProvider, useTranslation, useLocale } from '@chipmobilesdk/rn-i18n';
-
-<I18nProvider i18n={i18n}>
-  <App />
-</I18nProvider>;
-
-const { t } = useTranslation<AppI18nKey>();
-const { locale, direction, supportedLocales, setLocale } = useLocale();
-
-t('welcome.message', { name: 'Dung' });
-t('cart.items', { count }, { count }); // plural variant by count
-```
-
-## Public API
-
-| Capability | Member |
-|------------|--------|
-| Setup + validation | `createI18n(config)`, `I18nConfigError` |
-| Translation lookup | `i18n.t`, `useTranslation` |
-| Locale state + switching | `i18n.getLocale`, `i18n.setLocale`, `useLocale` |
-| Locale metadata (RTL/LTR, defaults) | `i18n.getSupportedLocales` |
-| Device-locale init | `i18n.init`, `defaultDeviceLocaleProvider` |
-| Formatting | `i18n.formatNumber/formatDate/formatCurrency/formatUnit` |
-| Unit conversion | `i18n.convertUnit`, `convertUnit`, `getUnitSymbol`, `SUPPORTED_UNITS`, `UnitConversionError` |
-| Runtime-only declarations | `i18n.registerRuntimeEntries` |
-| Persistence key | `LOCALE_STORAGE_KEY` |
-| React | `I18nProvider` |
-
-Public contract types also include the configuration, locale, translation,
-formatting, unit, provider/adapter, and hook result types exported by
-`src/index.ts`. Do not deep-import package internals. Node-only extraction and
-synchronization APIs must be imported from `@chipmobilesdk/rn-i18n/tooling`.
-
-### Storage adapter (required for persistence)
-
-The package never bundles a storage backend (FR-046/FR-047). Inject one:
-
-```ts
-import type { LocaleStorageAdapter } from '@chipmobilesdk/rn-i18n';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-export const storageAdapter: LocaleStorageAdapter = {
-  getItem: key => AsyncStorage.getItem(key),
-  setItem: (key, value) => AsyncStorage.setItem(key, value),
-  removeItem: key => AsyncStorage.removeItem(key),
-};
-```
-
-An MMKV-backed adapter (wrapping its synchronous API in `Promise.resolve`)
-works equally well. If persistence is enabled without an adapter, `createI18n`
-throws before any localized content is served.
-
-### Device-locale provider (optional)
-
-The default reads `Intl.DateTimeFormat().resolvedOptions().locale`. Apps that
-need richer detection can inject `deviceLocale` (e.g. backed by
-`react-native-localize`); that dependency stays in the app, never the package.
-
-## Translations
-
-App-owned JSON, organized by locale and namespace; nested dot-path keys,
-`{{name}}` interpolation, and plural groups:
-
-```jsonc
-{
-  "welcome": { "message": "Welcome, {{name}}!" },
-  "cart": { "items": { "one": "{{count}} item", "other": "{{count}} items" } }
-}
-```
-
-Plural categories deliberately come from package-owned rules rather than
-depending on `Intl.PluralRules`, which keeps behavior consistent across the
-supported Hermes environments. Built-ins cover `en` (one/other), `vi`/`ja`
-(other-only), and a default `count === 1 -> one` rule; supply
-`LocaleConfig.pluralRule` for richer languages.
-
-## Extraction & synchronization CLI
-
-Node-only, exposed via `@chipmobilesdk/rn-i18n/tooling` and a CLI. Add an app
-config (`i18n-sync.config.json`) and a script:
-
-```jsonc
-{
-  "sourceGlobs": ["src/**/*.ts", "src/**/*.tsx"],
-  "patterns": [{ "regex": "[^\\w.]t\\(\\s*'(?<key>[A-Za-z0-9_.-]+)'" }],
-  "localesDir": "src/i18n/locales",
-  "locales": ["en-US", "vi-VN", "ja-JP"],
-  "runtimeEntriesFile": "src/i18n/runtime-keys.ts",
-  "generateKeysFile": "src/i18n/keys.generated.ts",
-  "keysTypeName": "AppI18nKey"
-}
-```
-
-```jsonc
-// package.json
-"scripts": {
-  "i18n:sync": "node --experimental-strip-types node_modules/@chipmobilesdk/rn-i18n/src/tooling/cli.ts --config i18n-sync.config.json"
-}
-```
-
-Running it scans the source tree, then per locale: creates missing files, adds
-missing keys (with the placeholder policy), preserves existing translations,
-removes stale keys, protects declared runtime-only keys, regenerates the typed
-key contract, and prints a report. Exit codes: `0` success/warnings, `1`
-blocking findings (conflicts, malformed locale files), `2` invalid config.
-
-Bind `t()` to the generated `AppI18nKey` so `tsc --noEmit` reports invalid or
-stale key usage before release.
-
-### Runtime-only keys
-
-Keys resolved only at runtime (declared in `runtimeEntriesFile`) use the same
-lookup, fallback, interpolation, and missing-key behavior, and are never
-removed by synchronization. Policy `add` writes the default text to missing
-locales; `report` only lists them.
-
-## Compatibility
-
-| Surface | Baseline |
-|---------|----------|
-| React / React Native | `19.x` / `0.85+` (Hermes) |
-| TypeScript | `5.8+` |
-| Node (tooling) | `>=22.11.0` |
-| Platforms | Android, iOS (no native code) |
-
-## Validation
-
-```bash
-npm test                     # package + demo suites
-npm run typecheck:i18n       # tsc -p packages/rn-i18n/tsconfig.json --noEmit
-npm run pack:i18n            # npm pack --workspace @chipmobilesdk/rn-i18n --dry-run
-npm run i18n:sync            # extraction + synchronization
-```
-
-The demo integration lives in `src/screens/I18nDemoScreen.tsx` and uses
-`src/i18n/` for setup, translations, persistence, and generated keys.
-
-See [CHANGELOG.md](CHANGELOG.md) for release notes and adoption guidance.
+# @chipmobilesdk/rn-i18n
+
+Reusable localization for ChipMobileSdk-family React Native apps: per-locale
+configuration, app-owned namespaced translations, typed keys, interpolation,
+pluralization, fallback chains, runtime locale switching with app-injected
+persistence, device-locale detection, locale-aware number/date/currency/unit
+formatting, and a Node CLI that extracts and synchronizes translation keys.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Zero runtime dependencies.** Formatting uses the `Intl` APIs built into
+  Hermes; plural rules and unit conversion are package-owned.
+- **No native code.** Storage and (optionally) device-locale detection are
+  injected by the consuming app.
+- **Public package.** Published under the `@chipmobilesdk` npm organization.
+- **Version**: see [CHANGELOG](CHANGELOG.md)
+- **Entrypoints**: `@chipmobilesdk/rn-i18n` and the Node-only
+  `@chipmobilesdk/rn-i18n/tooling`
+
+## Installation
+
+This package ships TypeScript sources and is consumed through the workspace or
+the public npm registry:
+
+```bash
+npm install @chipmobilesdk/rn-i18n
+```
+
+Host frameworks are peer dependencies:
+
+```jsonc
+// peerDependencies
+"react": ">=19",
+"react-native": ">=0.85"
+```
+
+## Quick start
+
+```ts
+import { createI18n } from '@chipmobilesdk/rn-i18n';
+import enUS from './locales/en-US.json';
+import viVN from './locales/vi-VN.json';
+import { storageAdapter } from './storage';
+import type { AppI18nKey } from './keys.generated';
+
+export const i18n = createI18n<AppI18nKey>({
+  primaryLocale: 'en-US',
+  locales: [
+    {
+      code: 'en-US',
+      displayName: 'English (US)',
+      direction: 'ltr',
+      fallbackChain: [],
+      defaultCurrency: 'USD',
+      defaultUnit: 'mile',
+      defaultDateFormat: { year: 'numeric', month: 'short', day: 'numeric' },
+      defaultNumberFormat: { maximumFractionDigits: 2 },
+    },
+    {
+      code: 'vi-VN',
+      displayName: 'Tiếng Việt',
+      direction: 'ltr',
+      fallbackChain: ['en-US'],
+      defaultCurrency: 'VND',
+      defaultUnit: 'kilometer',
+      defaultDateFormat: { day: '2-digit', month: '2-digit', year: 'numeric' },
+      defaultNumberFormat: { maximumFractionDigits: 2 },
+    },
+  ],
+  resources: { 'en-US': enUS, 'vi-VN': viVN },
+  storage: storageAdapter,
+});
+
+await i18n.init(); // persisted -> device -> primary fallback
+```
+
+Wrap the app and use the hooks:
+
+```tsx
+import { I18nProvider, useTranslation, useLocale } from '@chipmobilesdk/rn-i18n';
+
+<I18nProvider i18n={i18n}>
+  <App />
+</I18nProvider>;
+
+const { t } = useTranslation<AppI18nKey>();
+const { locale, direction, supportedLocales, setLocale } = useLocale();
+
+t('welcome.message', { name: 'Dung' });
+t('cart.items', { count }, { count }); // plural variant by count
+```
+
+## Public API
+
+| Capability | Member |
+|------------|--------|
+| Setup + validation | `createI18n(config)`, `I18nConfigError` |
+| Translation lookup | `i18n.t`, `useTranslation` |
+| Locale state + switching | `i18n.getLocale`, `i18n.setLocale`, `useLocale` |
+| Locale metadata (RTL/LTR, defaults) | `i18n.getSupportedLocales` |
+| Device-locale init | `i18n.init`, `defaultDeviceLocaleProvider` |
+| Formatting | `i18n.formatNumber/formatDate/formatCurrency/formatUnit` |
+| Unit conversion | `i18n.convertUnit`, `convertUnit`, `getUnitSymbol`, `SUPPORTED_UNITS`, `UnitConversionError` |
+| Runtime-only declarations | `i18n.registerRuntimeEntries` |
+| Persistence key | `LOCALE_STORAGE_KEY` |
+| React | `I18nProvider` |
+
+Public contract types also include the configuration, locale, translation,
+formatting, unit, provider/adapter, and hook result types exported by
+`src/index.ts`. Do not deep-import package internals. Node-only extraction and
+synchronization APIs must be imported from `@chipmobilesdk/rn-i18n/tooling`.
+
+### Storage adapter (required for persistence)
+
+The package never bundles a storage backend (FR-046/FR-047). Inject one:
+
+```ts
+import type { LocaleStorageAdapter } from '@chipmobilesdk/rn-i18n';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+export const storageAdapter: LocaleStorageAdapter = {
+  getItem: key => AsyncStorage.getItem(key),
+  setItem: (key, value) => AsyncStorage.setItem(key, value),
+  removeItem: key => AsyncStorage.removeItem(key),
+};
+```
+
+An MMKV-backed adapter (wrapping its synchronous API in `Promise.resolve`)
+works equally well. If persistence is enabled without an adapter, `createI18n`
+throws before any localized content is served.
+
+### Device-locale provider (optional)
+
+The default reads `Intl.DateTimeFormat().resolvedOptions().locale`. Apps that
+need richer detection can inject `deviceLocale` (e.g. backed by
+`react-native-localize`); that dependency stays in the app, never the package.
+
+## Translations
+
+App-owned JSON, organized by locale and namespace; nested dot-path keys,
+`{{name}}` interpolation, and plural groups:
+
+```jsonc
+{
+  "welcome": { "message": "Welcome, {{name}}!" },
+  "cart": { "items": { "one": "{{count}} item", "other": "{{count}} items" } }
+}
+```
+
+Plural categories deliberately come from package-owned rules rather than
+depending on `Intl.PluralRules`, which keeps behavior consistent across the
+supported Hermes environments. Built-ins cover `en` (one/other), `vi`/`ja`
+(other-only), and a default `count === 1 -> one` rule; supply
+`LocaleConfig.pluralRule` for richer languages.
+
+## Extraction & synchronization CLI
+
+Node-only, exposed via `@chipmobilesdk/rn-i18n/tooling` and a CLI. Add an app
+config (`i18n-sync.config.json`) and a script:
+
+```jsonc
+{
+  "sourceGlobs": ["src/**/*.ts", "src/**/*.tsx"],
+  "patterns": [{ "regex": "[^\\w.]t\\(\\s*'(?<key>[A-Za-z0-9_.-]+)'" }],
+  "localesDir": "src/i18n/locales",
+  "locales": ["en-US", "vi-VN", "ja-JP"],
+  "runtimeEntriesFile": "src/i18n/runtime-keys.ts",
+  "generateKeysFile": "src/i18n/keys.generated.ts",
+  "keysTypeName": "AppI18nKey"
+}
+```
+
+```jsonc
+// package.json
+"scripts": {
+  "i18n:sync": "node --experimental-strip-types node_modules/@chipmobilesdk/rn-i18n/src/tooling/cli.ts --config i18n-sync.config.json"
+}
+```
+
+Running it scans the source tree, then per locale: creates missing files, adds
+missing keys (with the placeholder policy), preserves existing translations,
+removes stale keys, protects declared runtime-only keys, regenerates the typed
+key contract, and prints a report. Exit codes: `0` success/warnings, `1`
+blocking findings (conflicts, malformed locale files), `2` invalid config.
+
+Bind `t()` to the generated `AppI18nKey` so `tsc --noEmit` reports invalid or
+stale key usage before release.
+
+### Runtime-only keys
+
+Keys resolved only at runtime (declared in `runtimeEntriesFile`) use the same
+lookup, fallback, interpolation, and missing-key behavior, and are never
+removed by synchronization. Policy `add` writes the default text to missing
+locales; `report` only lists them.
+
+## Compatibility
+
+| Surface | Baseline |
+|---------|----------|
+| React / React Native | `19.x` / `0.85+` (Hermes) |
+| TypeScript | `5.8+` |
+| Node (tooling) | `>=22.11.0` |
+| Platforms | Android, iOS (no native code) |
+
+## Validation
+
+```bash
+npm test                     # package + demo suites
+npm run typecheck --workspace @chipmobilesdk/rn-i18n       # tsc -p packages/rn-i18n/tsconfig.json --noEmit
+npm run pack:check --workspace @chipmobilesdk/rn-i18n            # npm pack --workspace @chipmobilesdk/rn-i18n --dry-run
+npm run i18n:sync            # extraction + synchronization
+```
+
+The demo integration lives in `src/screens/I18nDemoScreen.tsx` and uses
+`src/i18n/` for setup, translations, persistence, and generated keys.
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and adoption guidance.