@coherent.js/i18n 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/i18n",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Internationalization support for Coherent.js applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
   "author": "Coherent.js Team",
   "license": "MIT",
   "peerDependencies": {
-    "@coherent.js/core": "1.0.0"
+    "@coherent.js/core": "1.0.1"
   },
   "repository": {
     "type": "git",
@@ -51,6 +51,7 @@
     "build": "node build.mjs",
     "clean": "rm -rf dist",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
   }
 }

package/types/index.d.ts

@@ -3,354 +3,236 @@
  * @module @coherent.js/i18n
  */
 
-import type { CoherentNode } from '@coherent.js/core';
-
 // ============================================================================
-// Translation Key Types
+// Translation Messages
 // ============================================================================
 
-/**
- * Translation key type (can be extended for type-safe translations)
- */
+/** Translation key, dot-separated for nested lookups (`'home.title'`). */
 export type TranslationKey = string;
 
 /**
- * Nested translation messages object
+ * A translation tree. Leaves are strings, or plural objects keyed by CLDR
+ * category (`one`, `other`, ...) selected via a `count` parameter.
  */
 export type TranslationMessages = {
-  [key: string]: string | TranslationMessages;
+  [key: string]: string | PluralForms | TranslationMessages;
 };
 
-/**
- * Helper type to flatten nested keys with dot notation
- * @example FlattenKeys<{ home: { title: 'Title' } }> = 'home.title'
- */
-export type FlattenKeys<T, Prefix extends string = ''> = T extends string
-  ? Prefix
-  : {
-      [K in keyof T]: FlattenKeys<
-        T[K],
-        `${Prefix}${Prefix extends '' ? '' : '.'}${K & string}`
-      >;
-    }[keyof T];
-
-// ============================================================================
-// Translation Function Types
-// ============================================================================
-
-/**
- * Translation function with overloads for different use cases
- */
-export interface TranslationFunction {
-  /**
-   * Translate a key
-   */
-  (key: TranslationKey): string;
-
-  /**
-   * Translate a key with interpolation parameters
-   */
-  (key: TranslationKey, params: Record<string, string | number>): string;
+/** Plural variants for one key, selected by `Intl.PluralRules`. */
+export interface PluralForms {
+  zero?: string;
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other?: string;
+}
 
-  /**
-   * Translate a key with interpolation and pluralization
-   */
-  (key: TranslationKey, params: Record<string, string | number>, count: number): string;
+/** Interpolation parameters; `count` also drives plural selection. */
+export interface TranslationParams {
+  count?: number;
+  [param: string]: unknown;
 }
 
 // ============================================================================
-// I18n Configuration
+// Translator
 // ============================================================================
 
-/**
- * I18n configuration options
- */
-export interface I18nConfig {
-  /** Default locale code (e.g., 'en', 'en-US') */
-  defaultLocale: string;
-  /** List of supported locale codes */
-  supportedLocales: string[];
-  /** Fallback locale when translation is missing */
+export interface TranslatorOptions {
+  /** Locale used until `setLocale()` is called; defaults to `'en'` */
+  defaultLocale?: string;
+  /** Locale consulted when a key is missing; defaults to `'en'` */
   fallbackLocale?: string;
-  /** Async function to load messages for a locale */
-  loadMessages?: (locale: string) => Promise<TranslationMessages>;
-  /** Pre-loaded messages by locale */
-  messages?: Record<string, TranslationMessages>;
-  /** Handler for missing translation keys */
-  missingKeyHandler?: (key: string, locale: string) => string;
-  /** Interpolation settings */
+  /** Called instead of returning the key when a translation is missing */
+  missingKeyHandler?: ((key: string, locale: string) => string) | null;
   interpolation?: {
-    /** Interpolation prefix (default: '{{') */
+    /** Defaults to `'{{'` */
     prefix?: string;
-    /** Interpolation suffix (default: '}}') */
+    /** Defaults to `'}}'` */
     suffix?: string;
-    /** Escape HTML in interpolated values */
-    escapeHtml?: boolean;
   };
-  /** Enable pluralization support */
-  pluralization?: boolean;
-  /** Context separator for contextual translations */
-  contextSeparator?: string;
+  [option: string]: unknown;
 }
 
-// ============================================================================
-// I18n Instance
-// ============================================================================
-
 /**
- * I18n instance interface
+ * Holds translations per locale and resolves keys with interpolation,
+ * pluralization and fallback.
+ *
+ * ```ts
+ * const t = new Translator({ defaultLocale: 'fr' });
+ * t.addTranslations('fr', { greeting: 'Bonjour {{name}}' });
+ * t.t('greeting', { name: 'Ada' }); // 'Bonjour Ada'
+ * ```
  */
-export interface I18nInstance {
-  /** Current locale code */
-  readonly locale: string;
+export class Translator {
+  constructor(options?: TranslatorOptions);
 
-  /** Translation function */
-  t: TranslationFunction;
+  options: TranslatorOptions;
+  translations: Map<string, TranslationMessages>;
+  currentLocale: string;
+  loadedLocales: Set<string>;
 
-  /**
-   * Change the current locale
-   */
-  setLocale(locale: string): Promise<void>;
+  /** Deep-merge messages into a locale */
+  addTranslations(locale: string, translations: TranslationMessages): void;
 
-  /**
-   * Get the current locale code
-   */
+  /** Recursively merge `source` into `target` */
+  deepMerge(target: TranslationMessages, source: TranslationMessages): TranslationMessages;
+
+  /** Switch the active locale */
+  setLocale(locale: string): void;
+
+  /** The active locale */
   getLocale(): string;
 
   /**
-   * Get list of supported locales
+   * Resolve a key. Falls back to the fallback locale, then to
+   * `missingKeyHandler`, then to the key itself.
    */
-  getSupportedLocales(): string[];
+  t(key: TranslationKey, params?: TranslationParams, locale?: string | null): string;
 
-  /**
-   * Check if a translation key exists
-   */
-  hasTranslation(key: TranslationKey): boolean;
+  /** Look a key up in one locale without fallback; `null` if absent */
+  getTranslation(
+    key: TranslationKey,
+    locale: string
+  ): string | PluralForms | TranslationMessages | null;
 
-  /**
-   * Format a number according to locale
-   */
-  formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+  /** Pick the plural form matching `count` */
+  selectPlural(pluralObject: PluralForms, count: number, locale: string): string;
 
-  /**
-   * Format a date according to locale
-   */
-  formatDate(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+  /** Substitute `{{param}}` placeholders */
+  interpolate(str: string, params: TranslationParams): string;
 
-  /**
-   * Format a currency value
-   */
-  formatCurrency(
-    value: number,
-    currency: string,
-    options?: Intl.NumberFormatOptions
-  ): string;
+  /** Whether a key resolves in the given (or current) locale */
+  has(key: TranslationKey, locale?: string | null): boolean;
 
-  /**
-   * Format a relative time (e.g., "3 days ago")
-   */
-  formatRelativeTime(
-    value: number,
-    unit: Intl.RelativeTimeFormatUnit,
-    options?: Intl.RelativeTimeFormatOptions
-  ): string;
+  /** All messages for a locale, or `{}` */
+  getTranslations(locale?: string | null): TranslationMessages;
 
-  /**
-   * Format a list (e.g., "A, B, and C")
-   */
-  formatList(values: string[], options?: Intl.ListFormatOptions): string;
+  /** Locales that have been marked loaded */
+  getLoadedLocales(): string[];
 
-  /**
-   * Add messages for a locale
-   */
-  addMessages(messages: TranslationMessages, locale?: string): void;
+  /** Drop a locale's messages, resetting the current locale if it was active */
+  removeLocale(locale: string): void;
 
-  /**
-   * Get all messages for current locale
-   */
-  getMessages(): TranslationMessages;
+  /** Drop every locale and reset to the default */
+  clear(): void;
 }
 
+/** Create a {@link Translator}. */
+export function createTranslator(options?: TranslatorOptions): Translator;
+
+/**
+ * Wrap a translator so every key is prefixed with `namespace`.
+ */
+export function createScopedTranslator(
+  translator: Translator,
+  namespace: string
+): {
+  t(key: TranslationKey, params?: TranslationParams, locale?: string | null): string;
+  has(key: TranslationKey, locale?: string | null): boolean;
+  getLocale(): string;
+  setLocale(locale: string): void;
+};
 
 // ============================================================================
-// Translator Class
+// Formatters
 // ============================================================================
 
-/**
- * Translator options
- */
-export interface TranslatorOptions {
-  /** Current locale code */
+/** Locale-aware date and time formatting. */
+export class DateFormatter {
+  constructor(locale?: string);
+
   locale: string;
-  /** Translation messages for current locale */
-  messages: TranslationMessages;
-  /** Fallback locale code */
-  fallbackLocale?: string;
-  /** Fallback messages */
-  fallbackMessages?: TranslationMessages;
-  /** Interpolation settings */
-  interpolation?: {
-    prefix?: string;
-    suffix?: string;
-  };
-  /** Enable pluralization */
-  pluralization?: boolean;
-  /** Context separator */
-  contextSeparator?: string;
-}
 
-/**
- * Translator class
- */
-export class Translator {
-  constructor(options: TranslatorOptions);
+  /** Format with explicit `Intl.DateTimeFormat` options */
+  format(date: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
 
-  /**
-   * Translate a key
-   */
-  t(key: string, params?: Record<string, unknown>): string;
+  /** Short date (e.g. `1/15/25`) */
+  short(date: Date | number | string): string;
 
-  /**
-   * Alias for t()
-   */
-  translate(key: string, params?: Record<string, unknown>): string;
+  /** Medium date (e.g. `Jan 15, 2025`) */
+  medium(date: Date | number | string): string;
 
-  /**
-   * Check if a translation exists
-   */
-  has(key: string): boolean;
+  /** Long date (e.g. `January 15, 2025`) */
+  long(date: Date | number | string): string;
 
-  /**
-   * Set the current locale
-   */
-  setLocale(locale: string): void;
+  /** Full date, including weekday */
+  full(date: Date | number | string): string;
 
-  /**
-   * Get the current locale
-   */
-  getLocale(): string;
+  /** Time only */
+  time(date: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
 
-  /**
-   * Add translation messages
-   */
-  addMessages(messages: TranslationMessages, locale?: string): void;
+  /** Date and time together */
+  dateTime(date: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
 
-  /**
-   * Remove translation messages
-   */
-  removeMessages(keys: string[], locale?: string): void;
+  /** Relative to now (e.g. `2 hours ago`) */
+  relative(date: Date | number | string): string;
 }
 
-/**
- * Create a translator instance
- */
-export function createTranslator(options: TranslatorOptions): Translator;
-
-/**
- * Create a scoped translator (prefixes all keys)
- */
-export function createScopedTranslator(translator: Translator, scope: string): Translator;
+/** Locale-aware number formatting. */
+export class NumberFormatter {
+  constructor(locale?: string);
 
-// ============================================================================
-// Formatters
-// ============================================================================
+  locale: string;
 
-/**
- * Date formatter options
- */
-export interface DateFormatterOptions {
-  locale?: string;
-  timeZone?: string;
-  dateStyle?: 'full' | 'long' | 'medium' | 'short';
-  timeStyle?: 'full' | 'long' | 'medium' | 'short';
-  format?: string;
-}
+  /** Format with explicit `Intl.NumberFormat` options */
+  format(value: number, options?: Intl.NumberFormatOptions): string;
 
-/**
- * Date formatter class
- */
-export class DateFormatter {
-  constructor(locale?: string, options?: DateFormatterOptions);
+  /** Fixed number of fraction digits; defaults to 2 */
+  decimal(value: number, decimals?: number): string;
 
-  /** Format a date */
-  format(date: Date | number | string): string;
+  /** Percentage; `value` is a ratio, so `0.42` renders as `42%` */
+  percent(value: number, decimals?: number): string;
 
-  /** Format as relative time (e.g., "2 hours ago") */
-  formatRelative(date: Date | number | string): string;
+  /** Compact notation (e.g. `1.2K`) */
+  compact(value: number): string;
 
-  /** Format distance between dates */
-  formatDistance(date: Date | number | string, baseDate?: Date | number): string;
+  /** Value with a unit (e.g. `5 km`) */
+  unit(value: number, unit: string, options?: Intl.NumberFormatOptions): string;
 }
 
-/**
- * Number formatter options
- */
-export interface NumberFormatterOptions {
-  locale?: string;
-  style?: 'decimal' | 'currency' | 'percent' | 'unit';
-  currency?: string;
-  minimumFractionDigits?: number;
-  maximumFractionDigits?: number;
-  useGrouping?: boolean;
-}
+/** Locale-aware currency formatting. */
+export class CurrencyFormatter {
+  constructor(locale?: string, defaultCurrency?: string);
 
-/**
- * Number formatter class
- */
-export class NumberFormatter {
-  constructor(locale?: string, options?: NumberFormatterOptions);
+  locale: string;
 
-  /** Format a number */
-  format(value: number): string;
+  /** Format using the given currency, or the configured default */
+  format(value: number, currency?: string | null, options?: Intl.NumberFormatOptions): string;
 
-  /** Format as compact notation */
-  formatCompact(value: number): string;
+  /** No fraction digits */
+  whole(value: number, currency?: string | null): string;
 
-  /** Format as percentage */
-  formatPercent(value: number): string;
-}
+  /** Symbol notation (`$1.00`) */
+  symbol(value: number, currency?: string | null): string;
 
-/**
- * Currency formatter options
- */
-export interface CurrencyFormatterOptions {
-  locale?: string;
-  currency: string;
-  display?: 'symbol' | 'code' | 'name';
+  /** Narrow symbol notation */
+  narrowSymbol(value: number, currency?: string | null): string;
+
+  /** Code notation (`USD 1.00`) */
+  code(value: number, currency?: string | null): string;
 }
 
-/**
- * Currency formatter class
- */
-export class CurrencyFormatter {
-  constructor(locale?: string, options?: CurrencyFormatterOptions);
+/** Locale-aware list formatting. */
+export class ListFormatter {
+  constructor(locale?: string);
 
-  /** Format a currency value */
-  format(value: number): string;
-}
+  locale: string;
 
-/**
- * List formatter options
- */
-export interface ListFormatterOptions {
-  locale?: string;
-  type?: 'conjunction' | 'disjunction' | 'unit';
-  style?: 'long' | 'short' | 'narrow';
-}
+  /** Format with explicit `Intl.ListFormat` options */
+  format(items: string[], options?: Intl.ListFormatOptions): string;
 
-/**
- * List formatter class
- */
-export class ListFormatter {
-  constructor(locale?: string, options?: ListFormatterOptions);
+  /** Conjunction (`A, B, and C`) */
+  and(items: string[]): string;
 
-  /** Format a list of items */
-  format(list: string[]): string;
+  /** Disjunction (`A, B, or C`) */
+  or(items: string[]): string;
+
+  /** Unit list (`A, B, C`) */
+  unit(items: string[]): string;
 }
 
-/**
- * All formatters for a locale
- */
+/** Every formatter for one locale. */
 export interface Formatters {
   date: DateFormatter;
   number: NumberFormatter;
@@ -358,91 +240,114 @@ export interface Formatters {
   list: ListFormatter;
 }
 
-/**
- * Create all formatters for a locale
- */
-export function createFormatters(locale: string): Formatters;
+/** Create all four formatters for a locale. */
+export function createFormatters(
+  locale?: string,
+  options?: { defaultCurrency?: string }
+): Formatters;
 
 // ============================================================================
-// Locale Management
+// Locale Utilities
 // ============================================================================
 
-/**
- * Locale configuration
- */
-export interface LocaleConfig {
-  /** Locale code (e.g., 'en-US') */
-  code: string;
-  /** English name */
-  name: string;
-  /** Native name */
-  nativeName: string;
-  /** Text direction */
-  direction?: 'ltr' | 'rtl';
-  /** Date format pattern */
-  dateFormat?: string;
-  /** Time format pattern */
-  timeFormat?: string;
-  /** First day of week (0 = Sunday, 1 = Monday, etc.) */
-  firstDayOfWeek?: number;
+/** Text direction. */
+export type LocaleDirection = 'ltr' | 'rtl';
+
+/** A locale code split into its parts. */
+export interface ParsedLocale {
+  language: string;
+  region: string | null;
+  script: string | null;
+  full: string;
 }
 
+/** The environment's preferred locale, or `'en'` outside a browser. */
+export function detectLocale(): string;
+
 /**
- * Locale manager class
+ * Lowercase a locale code and normalize the separator. The region is dropped
+ * unless `keepRegion` is set, so `'en_US'` gives `'en'`, or `'en-us'` when
+ * kept. Empty input gives `'en'`.
  */
-export class LocaleManager {
-  constructor(locales: LocaleConfig[]);
+export function normalizeLocale(locale: string | null | undefined, keepRegion?: boolean): string;
 
-  /** Add a locale configuration */
-  addLocale(locale: LocaleConfig): void;
+/** Split a locale code into language, region and script. */
+export function parseLocale(locale: string): ParsedLocale;
 
-  /** Remove a locale */
-  removeLocale(code: string): void;
+/** Text direction for a locale. */
+export function getLocaleDirection(locale: string): LocaleDirection;
 
-  /** Get locale configuration */
-  getLocale(code: string): LocaleConfig | undefined;
+/** Whether a locale is right-to-left. */
+export function isRTL(locale: string): boolean;
 
-  /** Get all locale configurations */
-  getAllLocales(): LocaleConfig[];
+/** Human-readable name of a locale, rendered in `displayLocale`. */
+export function getLocaleDisplayName(locale: string, displayLocale?: string): string;
+
+/**
+ * Pick the closest available locale, falling back to the language subtag and
+ * finally to `defaultLocale`.
+ */
+export function matchLocale(
+  requestedLocale: string,
+  availableLocales: string[],
+  defaultLocale?: string
+): string;
 
-  /** Set current locale */
-  setCurrentLocale(code: string): void;
+/** The environment's preferred locales, most preferred first. */
+export function getSupportedLocales(): string[];
 
-  /** Get current locale configuration */
-  getCurrentLocale(): LocaleConfig;
+export interface LocaleManagerOptions {
+  /** Locale used when detection and storage yield nothing; defaults to `'en'` */
+  defaultLocale?: string;
+  /** Locales this app ships; defaults to `['en']` */
+  availableLocales?: string[];
+  /** localStorage key; defaults to `'coherent-locale'` */
+  storageKey?: string;
+  /** Detect from the environment on construction; defaults to `true` */
+  autoDetect?: boolean;
+  [option: string]: unknown;
 }
 
-/**
- * Create a locale manager
- */
-export function createLocaleManager(locales: LocaleConfig[]): LocaleManager;
+/** Called after the locale changes. */
+export type LocaleChangeListener = (newLocale: string, oldLocale: string) => void;
 
 /**
- * Detect user's preferred locale
+ * Tracks the active locale, persisting it to localStorage where available.
  */
-export function detectLocale(): string;
+export class LocaleManager {
+  constructor(options?: LocaleManagerOptions);
 
-/**
- * Normalize a locale code (e.g., 'en_US' -> 'en-US')
- */
-export function getLocaleDirection(locale: string): 'ltr' | 'rtl';
+  options: LocaleManagerOptions;
+  currentLocale: string;
+  listeners: LocaleChangeListener[];
 
-export function getLocaleDisplayName(locale: string, displayLocale?: string): string;
+  /** Detect the environment locale and match it against the available ones */
+  detectAndMatch(): string;
 
-export function getSupportedLocales(): string[];
+  /** The active locale */
+  getLocale(): string;
 
-export function matchLocale(requestedLocale: string, availableLocales: string[], defaultLocale?: string): string;
+  /** Match, store and broadcast a new locale; a no-op if unchanged */
+  setLocale(locale: string): void;
 
-export function parseLocale(locale: string): { language: string; region: string | null; script: string | null; full: string };
+  /** Subscribe to locale changes; returns an unsubscribe function */
+  onChange(listener: LocaleChangeListener): () => void;
 
-export function normalizeLocale(locale: string): string;
+  /** Invoke every listener, swallowing listener errors */
+  notifyListeners(oldLocale: string, newLocale: string): void;
 
-/**
- * Check if a locale uses RTL text direction
- */
-export function isRTL(locale: string): boolean;
+  /** Persist the active locale, ignoring storage failures */
+  saveToStorage(): void;
 
-// ============================================================================
-// Component Helpers
-// ============================================================================
+  /** Restore a persisted locale, ignoring storage failures */
+  loadFromStorage(): void;
+
+  /** Copy of the configured available locales */
+  getAvailableLocales(): string[];
+
+  /** Whether a locale is in the available list */
+  isAvailable(locale: string): boolean;
+}
 
+/** Create a {@link LocaleManager}. */
+export function createLocaleManager(options?: LocaleManagerOptions): LocaleManager;