inline-i18n-multi 0.3.0 → 0.4.0

package/README.md

@@ -53,10 +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, select, date, number, and time formatting
+- **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
 
 ---
 
@@ -205,6 +207,75 @@ it({
 - `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
@@ -280,17 +351,19 @@ 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) |
+| `configure(options)` | Configure global settings (fallback, warnings, debug) |
 | `getConfig()` | Get current configuration |
 | `resetConfig()` | Reset configuration to defaults |
 
@@ -299,7 +372,7 @@ Available helpers:
 ```typescript
 type Locale = string
 type Translations = Record<Locale, string>
-type TranslationVars = Record<string, string | number | Date>
+type TranslationVars = Record<string, string | number | Date | string[]>
 
 interface Config {
   defaultLocale: Locale
@@ -308,6 +381,14 @@ interface Config {
   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 {

package/dist/index.d.mts

@@ -8,9 +8,10 @@ type Locale = string;
 type Translations = Record<Locale, string>;
 /**
  * Variables for interpolation
- * Supports string, number, and Date values for ICU formatting
+ * Supports string, number, Date values for ICU formatting
+ * Supports string[] for list formatting
  */
-type TranslationVars = Record<string, string | number | Date>;
+type TranslationVars = Record<string, string | number | Date | string[]>;
 /**
  * Warning information for missing translations
  */
@@ -29,6 +30,19 @@ interface TranslationWarning {
  * Warning handler function type
  */
 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
  */
@@ -45,6 +59,8 @@ interface Config {
     warnOnMissing?: boolean;
     /** Custom warning handler */
     onMissingTranslation?: WarningHandler;
+    /** Enable debug mode with visual indicators (default: false) */
+    debugMode?: boolean | DebugModeOptions;
 }
 
 /**
@@ -115,45 +131,65 @@ 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 getDictionary(locale: Locale): Dictionary | undefined;
+declare function getLoadedNamespaces(): string[];
 
 /**
  * Configure inline-i18n-multi settings
@@ -175,4 +211,4 @@ declare function getConfig(): Required<Config>;
  */
 declare function resetConfig(): void;
 
-export { type Config, 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, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, resetConfig, 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

@@ -8,9 +8,10 @@ type Locale = string;
 type Translations = Record<Locale, string>;
 /**
  * Variables for interpolation
- * Supports string, number, and Date values for ICU formatting
+ * Supports string, number, Date values for ICU formatting
+ * Supports string[] for list formatting
  */
-type TranslationVars = Record<string, string | number | Date>;
+type TranslationVars = Record<string, string | number | Date | string[]>;
 /**
  * Warning information for missing translations
  */
@@ -29,6 +30,19 @@ interface TranslationWarning {
  * Warning handler function type
  */
 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
  */
@@ -45,6 +59,8 @@ interface Config {
     warnOnMissing?: boolean;
     /** Custom warning handler */
     onMissingTranslation?: WarningHandler;
+    /** Enable debug mode with visual indicators (default: false) */
+    debugMode?: boolean | DebugModeOptions;
 }
 
 /**
@@ -115,45 +131,65 @@ 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 getDictionary(locale: Locale): Dictionary | undefined;
+declare function getLoadedNamespaces(): string[];
 
 /**
  * Configure inline-i18n-multi settings
@@ -175,4 +211,4 @@ declare function getConfig(): Required<Config>;
  */
 declare function resetConfig(): void;
 
-export { type Config, 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, getLocale, hasTranslation, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadDictionaries, loadDictionary, resetConfig, 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 };