inline-i18n-multi 0.9.0 → 0.11.0

package/README.md

@@ -76,6 +76,12 @@ See "Hello" in your app? Just search for "Hello" in your codebase. **Done.**
 - **Context System** - Contextual translation disambiguation (`t('greeting', { _context: 'formal' })` with `key#context` dictionary keys)
 - **Translation Extraction** - Extract inline translations to JSON files (`npx inline-i18n extract`)
 - **CLI Watch Mode** - `--watch` flag for `validate` and `typegen` commands
+- **Fallback Value** - Custom fallback text when translation is missing (`t('key', { _fallback: 'Default' })`)
+- **Diff Command** - Compare translations between two locales (`npx inline-i18n diff en ko`)
+- **Stats Command** - Translation statistics dashboard (`npx inline-i18n stats`)
+- **Locale Display Names** - Get human-readable locale names using `Intl.DisplayNames` (`getLocaleDisplayName('ko', 'en')` → `"Korean"`)
+- **Translation Key Listing** - `getTranslationKeys(locale?, namespace?)` returns all loaded translation keys
+- **Missing Translation Tracker** - Runtime collection of missing translation keys (`trackMissingKeys(true/false)`, `getMissingKeys()`, `clearMissingKeys()`)
 
 ---
 
@@ -779,6 +785,119 @@ Provides instant feedback during development by re-running validation or type ge
 
 ---
 
+## Fallback Value
+
+Provide custom fallback text when a translation key is missing, instead of returning the raw key:
+
+```typescript
+import { t, loadDictionaries, setLocale } from 'inline-i18n-multi'
+
+loadDictionaries({
+  en: { greeting: 'Hello' }
+})
+
+setLocale('en')
+
+// Without _fallback: returns the raw key when missing
+t('missing.key')  // → "missing.key"
+
+// With _fallback: returns custom fallback text
+t('missing.key', { _fallback: 'Default text' })  // → "Default text"
+
+// _fallback is stripped from interpolation output (not passed as a variable)
+t('greeting', { _fallback: 'Fallback' })  // → "Hello" (uses real translation, ignores _fallback)
+
+// Works with variables — _fallback is not treated as a variable
+t('welcome', { name: 'John', _fallback: 'Welcome!' })
+// If 'welcome' exists: uses translation with {name} interpolated
+// If 'welcome' is missing: → "Welcome!"
+```
+
+Useful for providing user-friendly defaults in UI components where raw keys would be confusing.
+
+---
+
+## Locale Display Names
+
+Get human-readable display names for locale codes using `Intl.DisplayNames`:
+
+```typescript
+import { getLocaleDisplayName, setLocale } from 'inline-i18n-multi'
+
+setLocale('en')
+
+// Get display name in a specific locale
+getLocaleDisplayName('ko', 'en')    // → "Korean"
+getLocaleDisplayName('ja', 'en')    // → "Japanese"
+getLocaleDisplayName('zh', 'en')    // → "Chinese"
+
+// Display name in the target's own locale
+getLocaleDisplayName('ko', 'ko')    // → "한국어"
+getLocaleDisplayName('en', 'ja')    // → "英語"
+
+// Omit displayLocale to use current locale
+setLocale('ko')
+getLocaleDisplayName('en')          // → "영어"
+```
+
+---
+
+## Translation Key Listing
+
+Get a list of all loaded translation keys:
+
+```typescript
+import { getTranslationKeys, loadDictionaries } from 'inline-i18n-multi'
+
+loadDictionaries({
+  en: { greeting: 'Hello', farewell: 'Goodbye' },
+  ko: { greeting: '안녕하세요' }
+}, 'common')
+
+// Get all keys for a specific locale and namespace
+getTranslationKeys('en', 'common')   // → ['greeting', 'farewell']
+getTranslationKeys('ko', 'common')   // → ['greeting']
+
+// Omit namespace to get keys from all namespaces
+getTranslationKeys('en')             // → ['common:greeting', 'common:farewell']
+
+// Omit all parameters to use current locale
+getTranslationKeys()                 // → all keys for current locale
+```
+
+---
+
+## Missing Translation Tracker
+
+Collect missing translation keys at runtime to identify what needs translating:
+
+```typescript
+import { trackMissingKeys, getMissingKeys, clearMissingKeys, t, loadDictionaries } from 'inline-i18n-multi'
+
+loadDictionaries({ en: { greeting: 'Hello' } })
+
+// Enable missing key tracking
+trackMissingKeys(true)
+
+// Use keys that don't exist
+t('missing.key')
+t('another.missing')
+
+// Get all missing keys
+getMissingKeys()  // → ['missing.key', 'another.missing']
+
+// Clear the tracked list
+clearMissingKeys()
+getMissingKeys()  // → []
+
+// Disable tracking
+trackMissingKeys(false)
+```
+
+Useful for discovering untranslated content during development and testing.
+
+---
+
 ## Configuration
 
 Configure global settings for fallback behavior and warnings:
@@ -873,6 +992,11 @@ Available helpers:
 | `clearICUCache()` | Clear the ICU message AST cache |
 | `restoreLocale()` | Restore locale from configured persistent storage (cookie or localStorage) |
 | `createScope(namespace)` | Return a translation function scoped to the given namespace |
+| `getLocaleDisplayName(locale, displayLocale?)` | Get human-readable display name for a locale using `Intl.DisplayNames` |
+| `getTranslationKeys(locale?, namespace?)` | Get all loaded translation keys |
+| `trackMissingKeys(enabled)` | Enable or disable missing translation key tracking |
+| `getMissingKeys()` | Get all tracked missing translation keys |
+| `clearMissingKeys()` | Clear the tracked missing keys list |
 
 ### Custom Formatters
 
@@ -1022,7 +1146,7 @@ npm install inline-i18n-multi-next
 
 ### CLI
 
-Command-line tools for translation management. Find translations with `inline-i18n find "text"`, validate consistency with `inline-i18n validate`, extract inline translations with `inline-i18n extract`, and generate coverage reports with `inline-i18n coverage`. Supports `--watch` mode for `validate` and `typegen`.
+Command-line tools for translation management. Find translations with `inline-i18n find "text"`, validate consistency with `inline-i18n validate`, extract inline translations with `inline-i18n extract`, and generate coverage reports with `inline-i18n coverage`. Compare locales with `inline-i18n diff en ko` and view statistics with `inline-i18n stats`. Supports `--watch` mode for `validate` and `typegen`.
 
 ```bash
 npm install -D @inline-i18n-multi/cli

package/dist/index.d.mts

@@ -11,9 +11,11 @@ type Translations = Record<Locale, string>;
  * Supports string, number, Date values for ICU formatting
  * Supports string[] for list formatting
  * Use _context for contextual translation disambiguation (v0.9.0)
+ * Use _fallback for custom fallback text when key is missing (v0.10.0)
  */
 type TranslationVars = Record<string, string | number | Date | string[]> & {
     _context?: string;
+    _fallback?: string;
 };
 /**
  * Warning information for missing translations
@@ -231,6 +233,49 @@ declare function getDictionary(locale: Locale, namespace?: string): Dictionary |
  * Get all loaded namespaces
  */
 declare function getLoadedNamespaces(): string[];
+/**
+ * Get the display name of a locale using Intl.DisplayNames (v0.11.0)
+ * @param locale - Locale code to get display name for (e.g., 'ko', 'ja', 'en-US')
+ * @param displayLocale - Locale in which to display the name (defaults to current locale)
+ * @returns Display name string (e.g., "Korean", "日本語")
+ *
+ * @example
+ * getLocaleDisplayName('ko', 'en')  // → "Korean"
+ * getLocaleDisplayName('ko', 'ko')  // → "한국어"
+ * getLocaleDisplayName('en', 'ja')  // → "英語"
+ */
+declare function getLocaleDisplayName(locale: Locale, displayLocale?: Locale): string;
+/**
+ * Get all translation keys for a locale (v0.11.0)
+ * @param locale - Locale to get keys for (defaults to current locale)
+ * @param namespace - Optional namespace (returns from all if not specified)
+ * @returns Array of translation keys (dot-notation paths)
+ *
+ * @example
+ * getTranslationKeys('en')             // → ['greeting.hello', 'greeting.goodbye', 'welcome']
+ * getTranslationKeys('en', 'common')   // → ['hello', 'goodbye']
+ */
+declare function getTranslationKeys(locale?: Locale, namespace?: string): string[];
+/**
+ * Enable or disable missing translation tracking (v0.11.0)
+ * When enabled, all missing translation keys encountered via t() are recorded.
+ * @param enabled - Whether to enable tracking
+ *
+ * @example
+ * trackMissingKeys(true)
+ * t('nonexistent.key')
+ * getMissingKeys()  // → ['nonexistent.key']
+ */
+declare function trackMissingKeys(enabled: boolean): void;
+/**
+ * Get all missing translation keys encountered since tracking was enabled (v0.11.0)
+ * @returns Array of missing keys
+ */
+declare function getMissingKeys(): string[];
+/**
+ * Clear the list of tracked missing keys (v0.11.0)
+ */
+declare function clearMissingKeys(): void;
 
 type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>> & Pick<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>;
 /**
@@ -342,4 +387,4 @@ interface RichTextSegment {
  */
 declare function parseRichText(template: string, componentNames: string[]): RichTextSegment[];
 
-export { type Config, type CustomFormatter, type DebugModeOptions, type DetectLocaleOptions, type DetectSource, type Dictionaries, type Dictionary, type Locale, type PluralRules, type RichTextSegment, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, clearFormatters, clearICUCache, configure, createScope, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, resetConfig, restoreLocale, setLocale, t, zh_es };
+export { type Config, type CustomFormatter, type DebugModeOptions, type DetectLocaleOptions, type DetectSource, type Dictionaries, type Dictionary, type Locale, type PluralRules, type RichTextSegment, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, clearFormatters, clearICUCache, clearMissingKeys, configure, createScope, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, getLocaleDisplayName, getMissingKeys, getTranslationKeys, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, resetConfig, restoreLocale, setLocale, t, trackMissingKeys, zh_es };

package/dist/index.d.ts

@@ -11,9 +11,11 @@ type Translations = Record<Locale, string>;
  * Supports string, number, Date values for ICU formatting
  * Supports string[] for list formatting
  * Use _context for contextual translation disambiguation (v0.9.0)
+ * Use _fallback for custom fallback text when key is missing (v0.10.0)
  */
 type TranslationVars = Record<string, string | number | Date | string[]> & {
     _context?: string;
+    _fallback?: string;
 };
 /**
  * Warning information for missing translations
@@ -231,6 +233,49 @@ declare function getDictionary(locale: Locale, namespace?: string): Dictionary |
  * Get all loaded namespaces
  */
 declare function getLoadedNamespaces(): string[];
+/**
+ * Get the display name of a locale using Intl.DisplayNames (v0.11.0)
+ * @param locale - Locale code to get display name for (e.g., 'ko', 'ja', 'en-US')
+ * @param displayLocale - Locale in which to display the name (defaults to current locale)
+ * @returns Display name string (e.g., "Korean", "日本語")
+ *
+ * @example
+ * getLocaleDisplayName('ko', 'en')  // → "Korean"
+ * getLocaleDisplayName('ko', 'ko')  // → "한국어"
+ * getLocaleDisplayName('en', 'ja')  // → "英語"
+ */
+declare function getLocaleDisplayName(locale: Locale, displayLocale?: Locale): string;
+/**
+ * Get all translation keys for a locale (v0.11.0)
+ * @param locale - Locale to get keys for (defaults to current locale)
+ * @param namespace - Optional namespace (returns from all if not specified)
+ * @returns Array of translation keys (dot-notation paths)
+ *
+ * @example
+ * getTranslationKeys('en')             // → ['greeting.hello', 'greeting.goodbye', 'welcome']
+ * getTranslationKeys('en', 'common')   // → ['hello', 'goodbye']
+ */
+declare function getTranslationKeys(locale?: Locale, namespace?: string): string[];
+/**
+ * Enable or disable missing translation tracking (v0.11.0)
+ * When enabled, all missing translation keys encountered via t() are recorded.
+ * @param enabled - Whether to enable tracking
+ *
+ * @example
+ * trackMissingKeys(true)
+ * t('nonexistent.key')
+ * getMissingKeys()  // → ['nonexistent.key']
+ */
+declare function trackMissingKeys(enabled: boolean): void;
+/**
+ * Get all missing translation keys encountered since tracking was enabled (v0.11.0)
+ * @returns Array of missing keys
+ */
+declare function getMissingKeys(): string[];
+/**
+ * Clear the list of tracked missing keys (v0.11.0)
+ */
+declare function clearMissingKeys(): void;
 
 type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>> & Pick<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>;
 /**
@@ -342,4 +387,4 @@ interface RichTextSegment {
  */
 declare function parseRichText(template: string, componentNames: string[]): RichTextSegment[];
 
-export { type Config, type CustomFormatter, type DebugModeOptions, type DetectLocaleOptions, type DetectSource, type Dictionaries, type Dictionary, type Locale, type PluralRules, type RichTextSegment, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, clearFormatters, clearICUCache, configure, createScope, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, resetConfig, restoreLocale, setLocale, t, zh_es };
+export { type Config, type CustomFormatter, type DebugModeOptions, type DetectLocaleOptions, type DetectSource, type Dictionaries, type Dictionary, type Locale, type PluralRules, type RichTextSegment, type TranslationVars, type TranslationWarning, type Translations, type WarningHandler, __i18n_lookup, clearDictionaries, clearFormatters, clearICUCache, clearMissingKeys, configure, createScope, detectLocale, en_de, en_es, en_fr, en_ja, en_zh, getConfig, getDictionary, getLoadedLocales, getLoadedNamespaces, getLocale, getLocaleDisplayName, getMissingKeys, getTranslationKeys, hasTranslation, isLoaded, it, it_de, it_es, it_fr, it_ja, it_zh, ja_es, ja_zh, loadAsync, loadDictionaries, loadDictionary, parseRichText, registerFormatter, resetConfig, restoreLocale, setLocale, t, trackMissingKeys, zh_es };

package/dist/index.js

@@ -603,14 +603,14 @@ function hasICUPattern(template) {
 
 // src/interpolation.ts
 var VARIABLE_PATTERN = /\{(\w+)\}/g;
-function stripContext(vars) {
-  if (!("_context" in vars)) return vars;
-  const { _context: _, ...rest } = vars;
+function stripSpecialVars(vars) {
+  if (!("_context" in vars) && !("_fallback" in vars)) return vars;
+  const { _context: _c, _fallback: _f, ...rest } = vars;
   return rest;
 }
 function interpolate(template, vars, locale) {
   const resolvedLocale = locale || "en";
-  const cleanVars = vars ? stripContext(vars) : vars;
+  const cleanVars = vars ? stripSpecialVars(vars) : vars;
   if (hasICUPattern(template) || hasCustomFormatter(template) || hasPluralShorthand(template)) {
     if (!cleanVars) {
       const cfg = getConfig();
@@ -919,6 +919,7 @@ function t(key, vars, locale) {
     }
   }
   if (!template) {
+    recordMissingKey(key);
     emitWarning({
       type: "missing_translation",
       key,
@@ -931,6 +932,9 @@ function t(key, vars, locale) {
       requestedLocale: currentLocale2,
       key
     };
+    if (vars?._fallback !== void 0) {
+      return applyDebugFormat(vars._fallback, debugInfo2);
+    }
     return applyDebugFormat(key, debugInfo2);
   }
   const isFallback = usedLocale !== currentLocale2;
@@ -984,6 +988,61 @@ function getDictionary(locale, namespace) {
 function getLoadedNamespaces() {
   return Object.keys(namespacedDictionaries);
 }
+function getLocaleDisplayName(locale, displayLocale) {
+  const dl = displayLocale ?? getLocale();
+  try {
+    const displayNames = new Intl.DisplayNames([dl], { type: "language" });
+    return displayNames.of(locale) ?? locale;
+  } catch {
+    return locale;
+  }
+}
+function getTranslationKeys(locale, namespace) {
+  const loc = locale ?? getLocale();
+  const keys = [];
+  function collectKeys(dict, prefix) {
+    for (const [k, v] of Object.entries(dict)) {
+      const fullKey = prefix ? `${prefix}.${k}` : k;
+      if (typeof v === "string") {
+        keys.push(fullKey);
+      } else {
+        collectKeys(v, fullKey);
+      }
+    }
+  }
+  if (namespace) {
+    const dict = namespacedDictionaries[namespace]?.[loc];
+    if (dict) collectKeys(dict, "");
+  } else {
+    for (const [ns, dicts] of Object.entries(namespacedDictionaries)) {
+      const dict = dicts[loc];
+      if (dict) {
+        const prefix = ns === DEFAULT_NAMESPACE ? "" : "";
+        collectKeys(dict, prefix);
+      }
+    }
+  }
+  return keys;
+}
+var missingKeys = /* @__PURE__ */ new Set();
+var trackMissing = false;
+function trackMissingKeys(enabled) {
+  trackMissing = enabled;
+  if (!enabled) {
+    missingKeys = /* @__PURE__ */ new Set();
+  }
+}
+function getMissingKeys() {
+  return Array.from(missingKeys);
+}
+function clearMissingKeys() {
+  missingKeys = /* @__PURE__ */ new Set();
+}
+function recordMissingKey(key) {
+  if (trackMissing) {
+    missingKeys.add(key);
+  }
+}
 
 // src/detect.ts
 function matchLocale(candidate, supportedLocales) {
@@ -1119,6 +1178,7 @@ exports.__i18n_lookup = __i18n_lookup;
 exports.clearDictionaries = clearDictionaries;
 exports.clearFormatters = clearFormatters;
 exports.clearICUCache = clearICUCache;
+exports.clearMissingKeys = clearMissingKeys;
 exports.configure = configure;
 exports.createScope = createScope;
 exports.detectLocale = detectLocale;
@@ -1132,6 +1192,9 @@ exports.getDictionary = getDictionary;
 exports.getLoadedLocales = getLoadedLocales;
 exports.getLoadedNamespaces = getLoadedNamespaces;
 exports.getLocale = getLocale;
+exports.getLocaleDisplayName = getLocaleDisplayName;
+exports.getMissingKeys = getMissingKeys;
+exports.getTranslationKeys = getTranslationKeys;
 exports.hasTranslation = hasTranslation;
 exports.isLoaded = isLoaded;
 exports.it = it;
@@ -1151,6 +1214,7 @@ exports.resetConfig = resetConfig;
 exports.restoreLocale = restoreLocale;
 exports.setLocale = setLocale;
 exports.t = t;
+exports.trackMissingKeys = trackMissingKeys;
 exports.zh_es = zh_es;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map