inline-i18n-multi 0.8.0 → 0.10.0

package/README.md

@@ -73,6 +73,12 @@ See "Hello" in your app? Just search for "Hello" in your codebase. **Done.**
 - **Translation Scope** - Namespace scoping with `createScope` (`createScope('common')` returns a scoped `t()`)
 - **Unused Key Detection** - CLI `--unused` flag to detect unused translation keys
 - **TypeScript Type Generation** - `typegen` command for auto-generating translation key type definitions
+- **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`)
 
 ---
 
@@ -701,6 +707,113 @@ The generated types enable autocomplete and type checking for `t()` function key
 
 ---
 
+## Context System
+
+Use the `_context` parameter to disambiguate translations for the same key based on context. Dictionary keys use the `key#context` format:
+
+```typescript
+import { t, loadDictionaries } from 'inline-i18n-multi'
+
+loadDictionaries({
+  en: {
+    greeting: 'Hi',
+    'greeting#formal': 'Good day',
+    'greeting#casual': 'Hey',
+  },
+  ko: {
+    greeting: '안녕하세요',
+    'greeting#formal': '안녕하십니까',
+    'greeting#casual': '야',
+  }
+})
+
+// No context (default)
+t('greeting')  // → "Hi"
+
+// Formal context
+t('greeting', { _context: 'formal' })  // → "Good day"
+
+// Casual context
+t('greeting', { _context: 'casual' })  // → "Hey"
+
+// Falls back to the uncontexted key when a contexted key is not found
+t('greeting', { _context: 'unknown' })  // → "Hi"
+```
+
+Useful when the same translation key has different meanings depending on context (e.g., "open" used as both a verb and an adjective).
+
+---
+
+## Translation Extraction
+
+Extract inline translations from source code into JSON files using the `extract` command:
+
+```bash
+# Default (outputs to ./locales directory)
+npx inline-i18n extract
+
+# Specify output directory
+npx inline-i18n extract --output ./src/locales
+
+# Specify locales
+npx inline-i18n extract --locales en,ko,ja
+```
+
+Scans `it()` calls in your source code and generates per-locale JSON files. Existing JSON files are preserved, with only new keys being added.
+
+---
+
+## CLI Watch Mode
+
+Add the `--watch` flag to `validate` and `typegen` commands to automatically re-run on file changes:
+
+```bash
+# Watch mode for validation
+npx inline-i18n validate --watch
+
+# Watch mode for type generation
+npx inline-i18n typegen --output src/i18n.d.ts --watch
+
+# Combine with strict mode
+npx inline-i18n validate --strict --watch
+```
+
+Provides instant feedback during development by re-running validation or type generation each time a file is saved.
+
+---
+
+## 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.
+
+---
+
 ## Configuration
 
 Configure global settings for fallback behavior and warnings:
@@ -944,7 +1057,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`, and generate coverage reports with `inline-i18n coverage`.
+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

@@ -10,8 +10,13 @@ type Translations = Record<Locale, string>;
  * Variables for interpolation
  * 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[]>;
+type TranslationVars = Record<string, string | number | Date | string[]> & {
+    _context?: string;
+    _fallback?: string;
+};
 /**
  * Warning information for missing translations
  */
@@ -210,8 +215,9 @@ 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
+ * @param context - Optional context for contextual translations (v0.9.0)
  */
-declare function hasTranslation(key: string, locale?: Locale): boolean;
+declare function hasTranslation(key: string, locale?: Locale, context?: string): boolean;
 /**
  * Get all loaded locales
  * @param namespace - Optional namespace (returns from all if not specified)

package/dist/index.d.ts

@@ -10,8 +10,13 @@ type Translations = Record<Locale, string>;
  * Variables for interpolation
  * 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[]>;
+type TranslationVars = Record<string, string | number | Date | string[]> & {
+    _context?: string;
+    _fallback?: string;
+};
 /**
  * Warning information for missing translations
  */
@@ -210,8 +215,9 @@ 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
+ * @param context - Optional context for contextual translations (v0.9.0)
  */
-declare function hasTranslation(key: string, locale?: Locale): boolean;
+declare function hasTranslation(key: string, locale?: Locale, context?: string): boolean;
 /**
  * Get all loaded locales
  * @param namespace - Optional namespace (returns from all if not specified)

package/dist/index.js

@@ -603,19 +603,25 @@ function hasICUPattern(template) {
 
 // src/interpolation.ts
 var VARIABLE_PATTERN = /\{(\w+)\}/g;
+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 ? stripSpecialVars(vars) : vars;
   if (hasICUPattern(template) || hasCustomFormatter(template) || hasPluralShorthand(template)) {
-    if (!vars) {
+    if (!cleanVars) {
       const cfg = getConfig();
       if (cfg.missingVarHandler) {
         return interpolateICU(template, {}, resolvedLocale);
       }
       return template;
     }
-    return interpolateICU(template, vars, resolvedLocale);
+    return interpolateICU(template, cleanVars, resolvedLocale);
   }
-  if (!vars) {
+  if (!cleanVars) {
     const cfg = getConfig();
     if (cfg.missingVarHandler) {
       return template.replace(VARIABLE_PATTERN, (_, key) => {
@@ -625,7 +631,7 @@ function interpolate(template, vars, locale) {
     return template;
   }
   return template.replace(VARIABLE_PATTERN, (_, key) => {
-    const value = vars[key];
+    const value = cleanVars[key];
     if (value !== void 0) return String(value);
     const cfg = getConfig();
     if (cfg.missingVarHandler) {
@@ -872,7 +878,18 @@ function getPluralCategory(count, locale) {
   const rules = new Intl.PluralRules(locale);
   return rules.select(count);
 }
+var CONTEXT_SEPARATOR = "#";
 function findInDictionary(dict, key, vars, locale) {
+  if (vars?._context) {
+    const contextKey = `${key}${CONTEXT_SEPARATOR}${vars._context}`;
+    if (typeof vars.count === "number") {
+      const pluralKey = `${contextKey}_${getPluralCategory(vars.count, locale)}`;
+      const pluralTemplate = getNestedValue(dict, pluralKey);
+      if (pluralTemplate) return pluralTemplate;
+    }
+    const contextTemplate = getNestedValue(dict, contextKey);
+    if (contextTemplate !== void 0) return contextTemplate;
+  }
   let template = getNestedValue(dict, key);
   if (vars && typeof vars.count === "number") {
     const pluralKey = `${key}_${getPluralCategory(vars.count, locale)}`;
@@ -914,6 +931,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;
@@ -936,12 +956,17 @@ function t(key, vars, locale) {
   };
   return applyDebugFormat(result, debugInfo);
 }
-function hasTranslation(key, locale) {
+function hasTranslation(key, locale, context) {
   const { namespace, key: actualKey } = parseKey(key);
   const currentLocale2 = locale ?? getLocale();
   const nsDictionaries = namespacedDictionaries[namespace] || {};
   const dict = nsDictionaries[currentLocale2];
-  return dict ? getNestedValue(dict, actualKey) !== void 0 : false;
+  if (!dict) return false;
+  if (context) {
+    const contextKey = `${actualKey}${CONTEXT_SEPARATOR}${context}`;
+    return getNestedValue(dict, contextKey) !== void 0;
+  }
+  return getNestedValue(dict, actualKey) !== void 0;
 }
 function getLoadedLocales(namespace) {
   if (namespace) {