@chipmobilesdk/rn-i18n 0.1.2 → 0.2.0

package/README.md

@@ -1,218 +1,277 @@
-# @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
+```
+
+With a storage adapter that reads synchronously (see below), resolve the locale before
+the first render instead, so the first frame is already in the user's language:
+
+```ts
+if (!i18n.initSync()) await i18n.init(); // initSync is false only for an async-only store
+```
+
+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` (an `SdkError` from `@chipmobilesdk/rn-core`, `code: 'invalid_config'`; `UnitConversionError` has `code: 'unit_conversion'`) |
+| 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`, `i18n.initSync`, `defaultDeviceLocaleProvider` |
+| Formatting | `i18n.formatNumber/formatDate/formatCurrency/formatUnit` |
+| Unit conversion | `i18n.convertUnit`, `convertUnit`, `getUnitSymbol`, `SUPPORTED_UNITS`, `UnitConversionError` |
+| Runtime-only declarations | `i18n.registerRuntimeEntries` |
+| Persistence | `LOCALE_STORAGE_KEY`, `localeStorageFromKeyValue` |
+| 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 adapter may also have `getItemSync(key)`. With it, `i18n.initSync()` reads the
+saved locale synchronously and the app skips the frame it would otherwise render in
+the fallback language. MMKV through rn-core's `KeyValuePort` is one line:
+
+```ts
+import { openDurable } from '@chipmobilesdk/rn-core';
+import { localeStorageFromKeyValue } from '@chipmobilesdk/rn-i18n';
+import { createMMKV } from 'react-native-mmkv';
+
+const storage = localeStorageFromKeyValue(openDurable(() => createMMKV({ id: 'app' })));
+```
+
+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.
+
+### SDK copy
+
+Every `@chipmobilesdk` package with user-facing copy exports it as a catalog
+(`key -> English default`). `runtimeEntriesFromCatalog(catalog, { policy? })`
+turns one into runtime entries, converting `{name}` variables to `{{name}}`, so an
+app translates SDK copy like its own:
+
+```ts
+createI18n({
+  ...config,
+  runtimeEntries: [
+    ...runtimeEntriesFromCatalog(aiMessageSet.user),
+    ...runtimeEntriesFromCatalog(paymentMessages.user),
+  ],
+});
+```
+
+## Formatting
+
+`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
+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.
+
+## Diagnostics
+
+Missing translations and variables, fallbacks, invalid formats, persistence
+failures and a throwing locale listener are each reported once per lookup path as an
+`I18nDiagnostic` (`code`, `message`, and the `key` and `locale` involved):
+
+- to `onDiagnostic` in the config, when given;
+- otherwise to `console.warn`, in development builds only;
+- and always to the app's SDK sinks (`installSdkSink` from `@chipmobilesdk/rn-core`),
+  as `code` with `key` and `locale`.
+
+```ts
+const i18n = createI18n({ ...config, onDiagnostic: d => crashlytics.log(`${d.code} ${d.key ?? ''}`) });
+```
+
+## 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       # source, tests and the Node CLI
+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.

package/package.json

@@ -1,49 +1,49 @@
-{
-	"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.2.0",
+	"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 && tsc -p tsconfig.test.json && tsc -p tsconfig.tooling.json",
+		"pack:check": "npm pack --dry-run"
+	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}