@chipmobilesdk/rn-i18n 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-i18n` are documented here. This project
+follows [Semantic Versioning](https://semver.org/).
+
+## 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

@@ -0,0 +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.0`
+- **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.

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@chipmobilesdk/rn-i18n",
+	"version": "0.1.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",
+		"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/"
+	}
+}

package/src/config/types.ts

@@ -0,0 +1,152 @@
+/**
+ * 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

@@ -0,0 +1,174 @@
+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;
+		}
+	}
+}

package/src/format/currency.ts

@@ -0,0 +1,27 @@
+import type { InvalidFormatPolicy } from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+
+/**
+ * Locale-aware currency formatting. The locale's configured default currency
+ * applies unless the caller passes an explicit currency override (FR-021).
+ */
+export function formatCurrencyValue(
+	value: number,
+	localeCode: string,
+	defaultCurrency: string,
+	currencyOverride: string | undefined,
+	options: Intl.NumberFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format invalid currency value "${String(value)}" for locale "${localeCode}".`,
+		);
+	}
+	return new Intl.NumberFormat(localeCode, {
+		...options,
+		style: 'currency',
+		currency: currencyOverride ?? defaultCurrency,
+	}).format(value);
+}

package/src/format/date.ts

@@ -0,0 +1,26 @@
+import type { InvalidFormatPolicy } from '../config/types';
+import { applyInvalidFormatPolicy } from './invalid';
+
+/**
+ * Locale-aware date formatting through the Hermes built-in
+ * Intl.DateTimeFormat. The locale's configured default date format applies
+ * unless the caller passes explicit overrides (FR-020). Options are limited
+ * to component options supported by Hermes on both platforms.
+ */
+export function formatDateValue(
+	value: Date | number,
+	localeCode: string,
+	defaults: Intl.DateTimeFormatOptions,
+	override: Intl.DateTimeFormatOptions | undefined,
+	invalidFormat: InvalidFormatPolicy,
+): string {
+	const date = value instanceof Date ? value : new Date(value);
+	if (Number.isNaN(date.getTime())) {
+		return applyInvalidFormatPolicy(
+			invalidFormat,
+			`Cannot format invalid date value "${String(value)}" for locale "${localeCode}".`,
+		);
+	}
+	const options = override ?? defaults;
+	return new Intl.DateTimeFormat(localeCode, options).format(date);
+}