inline-i18n-multi 0.2.0 → 0.4.0

package/README.md

@@ -53,8 +53,12 @@ See "Hello" in your app? Just search for "Hello" in your codebase. **Done.**
 - **Type-safe** - Full TypeScript support with variable type checking
 - **Multiple languages** - Support for any number of locales
 - **i18n compatible** - Support for traditional key-based translations with JSON dictionaries
-- **ICU Message Format** - Plural and select syntax for complex translations
+- **ICU Message Format** - Plural, select, date, number, time, relative time, and list formatting
 - **Variable interpolation** - `{name}` syntax for dynamic values
+- **Locale Fallback Chain** - BCP 47 parent locale support (`zh-TW` → `zh` → `en`)
+- **Missing Translation Warning** - Development-time diagnostics with customizable handlers
+- **Namespace Support** - Organize translations for large apps (`t('common:greeting')`)
+- **Debug Mode** - Visual indicators for missing/fallback translations
 
 ---
 
@@ -184,6 +188,125 @@ it({
   ko: '{name}님이 {count, plural, =0 {메시지가 없습니다} other {# 개의 메시지가 있습니다}}',
   en: '{name} has {count, plural, =0 {no messages} one {# message} other {# messages}}'
 }, { name: 'John', count: 3 })  // → "John has 3 messages"
+
+// Date formatting
+it({
+  en: 'Created: {date, date, long}',
+  ko: '생성일: {date, date, long}'
+}, { date: new Date() })  // → "Created: January 15, 2024"
+
+// Number formatting
+it({
+  en: 'Price: {price, number}',
+  ko: '가격: {price, number}'
+}, { price: 1234.56 })  // → "Price: 1,234.56"
+```
+
+**Supported ICU styles:**
+- `number`: `decimal`, `percent`, `integer`, `currency`
+- `date`: `short`, `medium`, `long`, `full`
+- `time`: `short`, `medium`, `long`, `full`
+
+### Relative Time Formatting
+
+```typescript
+it({
+  en: 'Updated {time, relativeTime}',
+  ko: '{time, relativeTime} 업데이트됨'
+}, { time: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000) })
+// → "Updated 3 days ago"
+
+// Styles: long (default), short, narrow
+it({ en: '{time, relativeTime, short}' }, { time: pastDate })
+```
+
+### List Formatting
+
+```typescript
+it({
+  en: 'Invited: {names, list}',
+  ko: '초대됨: {names, list}'
+}, { names: ['Alice', 'Bob', 'Charlie'] })
+// → "Invited: Alice, Bob, and Charlie"
+
+// Types: conjunction (and), disjunction (or), unit
+it({ en: '{options, list, disjunction}' }, { options: ['A', 'B'] })
+// → "A or B"
+```
+
+---
+
+## Namespace Support
+
+Organize translations for large applications:
+
+```typescript
+import { loadDictionaries, t, getLoadedNamespaces, clearDictionaries } from 'inline-i18n-multi'
+
+// Load with namespace
+loadDictionaries({
+  en: { hello: 'Hello' },
+  ko: { hello: '안녕하세요' }
+}, 'common')
+
+// Use with namespace prefix
+t('common:hello')  // → "Hello"
+
+// Without namespace = 'default' (backward compatible)
+loadDictionaries({ en: { greeting: 'Hi' } })
+t('greeting')  // → "Hi"
+
+getLoadedNamespaces()  // → ['common', 'default']
+clearDictionaries('common')  // Clear specific namespace
+```
+
+---
+
+## Debug Mode
+
+Visual indicators for debugging:
+
+```typescript
+import { configure, setLocale, it, t } from 'inline-i18n-multi'
+
+configure({ debugMode: true })
+
+setLocale('fr')
+it({ en: 'Hello', ko: '안녕하세요' })  // → "[fr -> en] Hello"
+t('missing.key')  // → "[MISSING: fr] missing.key"
+```
+
+---
+
+## Configuration
+
+Configure global settings for fallback behavior and warnings:
+
+```typescript
+import { configure, getConfig, resetConfig } from 'inline-i18n-multi'
+
+configure({
+  fallbackLocale: 'en',           // Final fallback (default: 'en')
+  autoParentLocale: true,         // BCP 47 parent (zh-TW → zh)
+  fallbackChain: {                // Custom chains
+    'pt-BR': ['pt', 'es', 'en']
+  },
+  warnOnMissing: true,            // Enable warnings
+  onMissingTranslation: (w) => {  // Custom handler
+    console.warn(`Missing: ${w.requestedLocale}`)
+  }
+})
+```
+
+### Locale Fallback Chain
+
+Automatic locale fallback with BCP 47 support:
+
+```typescript
+setLocale('zh-TW')
+it({ en: 'Hello', zh: '你好' })  // → '你好' (falls back to zh)
+
+t('greeting')  // Also works with dictionaries
 ```
 
 ---
@@ -228,18 +351,55 @@ Available helpers:
 | Function | Description |
 |----------|-------------|
 | `t(key, vars?, locale?)` | Key-based translation with optional locale override |
-| `loadDictionaries(dicts)` | Load translation dictionaries for multiple locales |
-| `loadDictionary(locale, dict)` | Load dictionary for a single locale |
-| `hasTranslation(key, locale?)` | Check if translation key exists |
+| `loadDictionaries(dicts, namespace?)` | Load translation dictionaries with optional namespace |
+| `loadDictionary(locale, dict, namespace?)` | Load dictionary for a single locale with optional namespace |
+| `hasTranslation(key, locale?)` | Check if translation key exists (supports namespace:key) |
 | `getLoadedLocales()` | Get array of loaded locale codes |
-| `getDictionary(locale)` | Get dictionary for a specific locale |
+| `getLoadedNamespaces()` | Get array of loaded namespace names |
+| `getDictionary(locale, namespace?)` | Get dictionary for a specific locale and namespace |
+| `clearDictionaries(namespace?)` | Clear dictionaries (all or specific namespace) |
+
+### Configuration
+
+| Function | Description |
+|----------|-------------|
+| `configure(options)` | Configure global settings (fallback, warnings, debug) |
+| `getConfig()` | Get current configuration |
+| `resetConfig()` | Reset configuration to defaults |
 
 ### Types
 
 ```typescript
 type Locale = string
 type Translations = Record<Locale, string>
-type TranslationVars = Record<string, string | number>
+type TranslationVars = Record<string, string | number | Date | string[]>
+
+interface Config {
+  defaultLocale: Locale
+  fallbackLocale?: Locale
+  autoParentLocale?: boolean
+  fallbackChain?: Record<Locale, Locale[]>
+  warnOnMissing?: boolean
+  onMissingTranslation?: WarningHandler
+  debugMode?: boolean | DebugModeOptions
+}
+
+interface DebugModeOptions {
+  showMissingPrefix?: boolean
+  showFallbackPrefix?: boolean
+  missingPrefixFormat?: (locale: string, key?: string) => string
+  fallbackPrefixFormat?: (requestedLocale: string, usedLocale: string, key?: string) => string
+}
+
+interface TranslationWarning {
+  type: 'missing_translation'
+  key?: string
+  requestedLocale: string
+  availableLocales: string[]
+  fallbackUsed?: string
+}
+
+type WarningHandler = (warning: TranslationWarning) => void
 ```
 
 ---

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 /**
- * Locale code type (e.g., 'ko', 'en', 'ja')
+ * Locale code type (e.g., 'ko', 'en', 'ja', 'zh-TW')
  */
 type Locale = string;
 /**
@@ -8,14 +8,59 @@ type Locale = string;
 type Translations = Record<Locale, string>;
 /**
  * Variables for interpolation
+ * Supports string, number, Date values for ICU formatting
+ * Supports string[] for list formatting
+ */
+type TranslationVars = Record<string, string | number | Date | string[]>;
+/**
+ * Warning information for missing translations
+ */
+interface TranslationWarning {
+    type: 'missing_translation';
+    /** Dictionary key (for t() function) */
+    key?: string;
+    /** The locale that was requested */
+    requestedLocale: string;
+    /** Available locales that have translations */
+    availableLocales: string[];
+    /** The locale that was used as fallback */
+    fallbackUsed?: string;
+}
+/**
+ * Warning handler function type
  */
-type TranslationVars = Record<string, string | number>;
+type WarningHandler = (warning: TranslationWarning) => void;
+/**
+ * Debug mode options for visual indicators
+ */
+interface DebugModeOptions {
+    /** Show visual prefix for missing translations (default: true) */
+    showMissingPrefix?: boolean;
+    /** Show visual prefix for fallback translations (default: true) */
+    showFallbackPrefix?: boolean;
+    /** Custom prefix format for missing translations */
+    missingPrefixFormat?: (locale: string, key?: string) => string;
+    /** Custom prefix format for fallback translations */
+    fallbackPrefixFormat?: (requestedLocale: string, usedLocale: string, key?: string) => string;
+}
 /**
  * Configuration options
  */
 interface Config {
+    /** Default locale to use when none is set */
     defaultLocale: Locale;
+    /** Fallback locale when translation is missing (default: 'en') */
     fallbackLocale?: Locale;
+    /** Enable automatic BCP 47 parent locale derivation (default: true) */
+    autoParentLocale?: boolean;
+    /** Custom fallback chain for specific locales */
+    fallbackChain?: Record<Locale, Locale[]>;
+    /** Enable warnings when translation is missing (default: true in dev mode) */
+    warnOnMissing?: boolean;
+    /** Custom warning handler */
+    onMissingTranslation?: WarningHandler;
+    /** Enable debug mode with visual indicators (default: false) */
+    debugMode?: boolean | DebugModeOptions;
 }
 
 /**
@@ -86,44 +131,84 @@ interface PluralRules {
 /**
  * Load translations from dictionary objects
  * @param dicts - Dictionary objects keyed by locale
+ * @param namespace - Optional namespace (defaults to 'default')
  * @example
+ * // Without namespace (backward compatible)
  * loadDictionaries({
  *   en: { greeting: { hello: "Hello" } },
  *   ko: { greeting: { hello: "안녕하세요" } }
  * })
+ *
+ * // With namespace
+ * loadDictionaries({
+ *   en: { hello: "Hello" },
+ *   ko: { hello: "안녕하세요" }
+ * }, 'common')
  */
-declare function loadDictionaries(dicts: Dictionaries): void;
+declare function loadDictionaries(dicts: Dictionaries, namespace?: string): void;
 /**
  * Load a single locale's dictionary
  * @param locale - Locale code
  * @param dict - Dictionary object
+ * @param namespace - Optional namespace (defaults to 'default')
  */
-declare function loadDictionary(locale: Locale, dict: Dictionary): void;
+declare function loadDictionary(locale: Locale, dict: Dictionary, namespace?: string): void;
 /**
- * Clear all loaded dictionaries
+ * Clear loaded dictionaries
+ * @param namespace - Optional namespace to clear (clears all if not specified)
  */
-declare function clearDictionaries(): void;
+declare function clearDictionaries(namespace?: string): void;
 /**
  * Translate using key-based lookup (i18n compatible)
- * @param key - Dot-separated translation key
+ * @param key - Dot-separated translation key, optionally prefixed with namespace
  * @param vars - Variables for interpolation (including 'count' for plurals)
  * @param locale - Override locale (optional)
  * @example
- * t('greeting.hello') // "Hello"
+ * t('greeting.hello')           // Uses default namespace
+ * t('common:greeting.hello')    // Uses 'common' namespace
  * t('items.count', { count: 5 }) // "5 items"
  */
 declare function t(key: string, vars?: TranslationVars, locale?: Locale): string;
 /**
  * Check if a translation key exists
+ * @param key - Translation key (may include namespace prefix)
+ * @param locale - Optional locale to check
  */
 declare function hasTranslation(key: string, locale?: Locale): boolean;
 /**
  * Get all loaded locales
+ * @param namespace - Optional namespace (returns from all if not specified)
  */
-declare function getLoadedLocales(): Locale[];
+declare function getLoadedLocales(namespace?: string): Locale[];
 /**
  * Get dictionary for a specific locale
+ * @param locale - Locale code
+ * @param namespace - Optional namespace (defaults to 'default')
+ */
+declare function getDictionary(locale: Locale, namespace?: string): Dictionary | undefined;
+/**
+ * Get all loaded namespaces
+ */
+declare function getLoadedNamespaces(): string[];
+
+/**
+ * Configure inline-i18n-multi settings
+ *
+ * @example
+ * configure({
+ *   fallbackLocale: 'en',
+ *   fallbackChain: { 'pt-BR': ['pt', 'es', 'en'] },
+ *   warnOnMissing: true,
+ * })
+ */
+declare function configure(options: Partial<Config>): void;
+/**
+ * Get current configuration
+ */
+declare function getConfig(): Required<Config>;
+/**
+ * Reset configuration to defaults
  */
-declare function getDictionary(locale: Locale): Dictionary | undefined;
+declare function resetConfig(): void;
 
-export { type Config, type Dictionaries, type Dictionary, type Locale, type PluralRules, type TranslationVars, type Translations, __i18n_lookup, clearDictionaries, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, setLocale, t, zh_es };
+export { type Config, type DebugModeOptions, type Dictionaries, type Dictionary, type Locale, type PluralRules, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, configure, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, resetConfig, setLocale, t, zh_es };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Locale code type (e.g., 'ko', 'en', 'ja')
+ * Locale code type (e.g., 'ko', 'en', 'ja', 'zh-TW')
  */
 type Locale = string;
 /**
@@ -8,14 +8,59 @@ type Locale = string;
 type Translations = Record<Locale, string>;
 /**
  * Variables for interpolation
+ * Supports string, number, Date values for ICU formatting
+ * Supports string[] for list formatting
+ */
+type TranslationVars = Record<string, string | number | Date | string[]>;
+/**
+ * Warning information for missing translations
+ */
+interface TranslationWarning {
+    type: 'missing_translation';
+    /** Dictionary key (for t() function) */
+    key?: string;
+    /** The locale that was requested */
+    requestedLocale: string;
+    /** Available locales that have translations */
+    availableLocales: string[];
+    /** The locale that was used as fallback */
+    fallbackUsed?: string;
+}
+/**
+ * Warning handler function type
  */
-type TranslationVars = Record<string, string | number>;
+type WarningHandler = (warning: TranslationWarning) => void;
+/**
+ * Debug mode options for visual indicators
+ */
+interface DebugModeOptions {
+    /** Show visual prefix for missing translations (default: true) */
+    showMissingPrefix?: boolean;
+    /** Show visual prefix for fallback translations (default: true) */
+    showFallbackPrefix?: boolean;
+    /** Custom prefix format for missing translations */
+    missingPrefixFormat?: (locale: string, key?: string) => string;
+    /** Custom prefix format for fallback translations */
+    fallbackPrefixFormat?: (requestedLocale: string, usedLocale: string, key?: string) => string;
+}
 /**
  * Configuration options
  */
 interface Config {
+    /** Default locale to use when none is set */
     defaultLocale: Locale;
+    /** Fallback locale when translation is missing (default: 'en') */
     fallbackLocale?: Locale;
+    /** Enable automatic BCP 47 parent locale derivation (default: true) */
+    autoParentLocale?: boolean;
+    /** Custom fallback chain for specific locales */
+    fallbackChain?: Record<Locale, Locale[]>;
+    /** Enable warnings when translation is missing (default: true in dev mode) */
+    warnOnMissing?: boolean;
+    /** Custom warning handler */
+    onMissingTranslation?: WarningHandler;
+    /** Enable debug mode with visual indicators (default: false) */
+    debugMode?: boolean | DebugModeOptions;
 }
 
 /**
@@ -86,44 +131,84 @@ interface PluralRules {
 /**
  * Load translations from dictionary objects
  * @param dicts - Dictionary objects keyed by locale
+ * @param namespace - Optional namespace (defaults to 'default')
  * @example
+ * // Without namespace (backward compatible)
  * loadDictionaries({
  *   en: { greeting: { hello: "Hello" } },
  *   ko: { greeting: { hello: "안녕하세요" } }
  * })
+ *
+ * // With namespace
+ * loadDictionaries({
+ *   en: { hello: "Hello" },
+ *   ko: { hello: "안녕하세요" }
+ * }, 'common')
  */
-declare function loadDictionaries(dicts: Dictionaries): void;
+declare function loadDictionaries(dicts: Dictionaries, namespace?: string): void;
 /**
  * Load a single locale's dictionary
  * @param locale - Locale code
  * @param dict - Dictionary object
+ * @param namespace - Optional namespace (defaults to 'default')
  */
-declare function loadDictionary(locale: Locale, dict: Dictionary): void;
+declare function loadDictionary(locale: Locale, dict: Dictionary, namespace?: string): void;
 /**
- * Clear all loaded dictionaries
+ * Clear loaded dictionaries
+ * @param namespace - Optional namespace to clear (clears all if not specified)
  */
-declare function clearDictionaries(): void;
+declare function clearDictionaries(namespace?: string): void;
 /**
  * Translate using key-based lookup (i18n compatible)
- * @param key - Dot-separated translation key
+ * @param key - Dot-separated translation key, optionally prefixed with namespace
  * @param vars - Variables for interpolation (including 'count' for plurals)
  * @param locale - Override locale (optional)
  * @example
- * t('greeting.hello') // "Hello"
+ * t('greeting.hello')           // Uses default namespace
+ * t('common:greeting.hello')    // Uses 'common' namespace
  * t('items.count', { count: 5 }) // "5 items"
  */
 declare function t(key: string, vars?: TranslationVars, locale?: Locale): string;
 /**
  * Check if a translation key exists
+ * @param key - Translation key (may include namespace prefix)
+ * @param locale - Optional locale to check
  */
 declare function hasTranslation(key: string, locale?: Locale): boolean;
 /**
  * Get all loaded locales
+ * @param namespace - Optional namespace (returns from all if not specified)
  */
-declare function getLoadedLocales(): Locale[];
+declare function getLoadedLocales(namespace?: string): Locale[];
 /**
  * Get dictionary for a specific locale
+ * @param locale - Locale code
+ * @param namespace - Optional namespace (defaults to 'default')
+ */
+declare function getDictionary(locale: Locale, namespace?: string): Dictionary | undefined;
+/**
+ * Get all loaded namespaces
+ */
+declare function getLoadedNamespaces(): string[];
+
+/**
+ * Configure inline-i18n-multi settings
+ *
+ * @example
+ * configure({
+ *   fallbackLocale: 'en',
+ *   fallbackChain: { 'pt-BR': ['pt', 'es', 'en'] },
+ *   warnOnMissing: true,
+ * })
+ */
+declare function configure(options: Partial<Config>): void;
+/**
+ * Get current configuration
+ */
+declare function getConfig(): Required<Config>;
+/**
+ * Reset configuration to defaults
  */
-declare function getDictionary(locale: Locale): Dictionary | undefined;
+declare function resetConfig(): void;
 
-export { type Config, type Dictionaries, type Dictionary, type Locale, type PluralRules, type TranslationVars, type Translations, __i18n_lookup, clearDictionaries, en_de, en_es, en_fr, en_ja, en_zh, getDictionary, getLoadedLocales, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, setLocale, t, zh_es };
+export { type Config, type DebugModeOptions, type Dictionaries, type Dictionary, type Locale, type PluralRules, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, configure, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, resetConfig, setLocale, t, zh_es };