inline-i18n-multi 0.7.0 → 0.9.0

package/README.md

@@ -70,6 +70,12 @@ See "Hello" in your app? Just search for "Hello" in your codebase. **Done.**
 - **ICU Message Cache** - Memoize parsed ICU ASTs for performance (`icuCacheSize`, `clearICUCache()`)
 - **Plural Shorthand** - Concise plural syntax (`{count, p, item|items}`)
 - **Locale Persistence** - Auto-save/restore locale to cookie or localStorage (`persistLocale`, `restoreLocale()`)
+- **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
 
 ---
 
@@ -657,6 +663,122 @@ setLocale('ja')   // saves 'ja' to localStorage
 
 ---
 
+## Translation Scope
+
+Create a scoped translation function bound to a specific namespace with `createScope`:
+
+```typescript
+import { createScope, loadDictionaries } from 'inline-i18n-multi'
+
+loadDictionaries({ en: { greeting: 'Hello' }, ko: { greeting: '안녕하세요' } }, 'common')
+
+const tc = createScope('common')
+tc('greeting') // → "Hello"
+```
+
+Eliminates the need to write namespace prefixes (`t('common:greeting')`) every time, keeping your code cleaner.
+
+---
+
+## Unused Key Detection
+
+Use the `--unused` flag to detect translation keys defined in dictionaries but not used in your code:
+
+```bash
+npx inline-i18n validate --unused
+```
+
+Helps identify and clean up translations that are no longer needed.
+
+---
+
+## TypeScript Type Generation
+
+Auto-generate TypeScript type definition files for your translation keys with the `typegen` command:
+
+```bash
+npx inline-i18n typegen --output src/i18n.d.ts
+```
+
+The generated types enable autocomplete and type checking for `t()` function key arguments.
+
+---
+
+## 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.
+
+---
+
 ## Configuration
 
 Configure global settings for fallback behavior and warnings:
@@ -750,6 +872,7 @@ Available helpers:
 | `parseRichText(template, names)` | Parse rich text template into segments |
 | `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 |
 
 ### Custom Formatters
 
@@ -899,7 +1022,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`. Supports `--watch` mode for `validate` and `typegen`.
 
 ```bash
 npm install -D @inline-i18n-multi/cli

package/dist/index.d.mts

@@ -10,8 +10,11 @@ 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)
  */
-type TranslationVars = Record<string, string | number | Date | string[]>;
+type TranslationVars = Record<string, string | number | Date | string[]> & {
+    _context?: string;
+};
 /**
  * Warning information for missing translations
  */
@@ -210,8 +213,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)
@@ -295,6 +299,21 @@ interface DetectLocaleOptions {
  */
 declare function detectLocale(options: DetectLocaleOptions): Locale;
 
+/**
+ * Create a scoped translation function for a given namespace.
+ * Returns a `t()` wrapper that auto-prepends the namespace prefix.
+ *
+ * @param namespace - Namespace to scope to
+ * @returns Scoped translation function
+ *
+ * @example
+ * const tc = createScope('common')
+ * tc('greeting')      // equivalent to t('common:greeting')
+ * tc('nav.home')      // equivalent to t('common:nav.home')
+ * tc('welcome', { name: 'John' })
+ */
+declare function createScope(namespace: string): (key: string, vars?: TranslationVars, locale?: Locale) => string;
+
 /**
  * Rich Text segment types
  */
@@ -323,4 +342,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, 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, 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 };

package/dist/index.d.ts

@@ -10,8 +10,11 @@ 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)
  */
-type TranslationVars = Record<string, string | number | Date | string[]>;
+type TranslationVars = Record<string, string | number | Date | string[]> & {
+    _context?: string;
+};
 /**
  * Warning information for missing translations
  */
@@ -210,8 +213,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)
@@ -295,6 +299,21 @@ interface DetectLocaleOptions {
  */
 declare function detectLocale(options: DetectLocaleOptions): Locale;
 
+/**
+ * Create a scoped translation function for a given namespace.
+ * Returns a `t()` wrapper that auto-prepends the namespace prefix.
+ *
+ * @param namespace - Namespace to scope to
+ * @returns Scoped translation function
+ *
+ * @example
+ * const tc = createScope('common')
+ * tc('greeting')      // equivalent to t('common:greeting')
+ * tc('nav.home')      // equivalent to t('common:nav.home')
+ * tc('welcome', { name: 'John' })
+ */
+declare function createScope(namespace: string): (key: string, vars?: TranslationVars, locale?: Locale) => string;
+
 /**
  * Rich Text segment types
  */
@@ -323,4 +342,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, 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, 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 };

package/dist/index.js

@@ -603,19 +603,25 @@ function hasICUPattern(template) {
 
 // src/interpolation.ts
 var VARIABLE_PATTERN = /\{(\w+)\}/g;
+function stripContext(vars) {
+  if (!("_context" in vars)) return vars;
+  const { _context: _, ...rest } = vars;
+  return rest;
+}
 function interpolate(template, vars, locale) {
   const resolvedLocale = locale || "en";
+  const cleanVars = vars ? stripContext(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)}`;
@@ -936,12 +953,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) {
@@ -1050,6 +1072,13 @@ function detectLocale(options) {
   return defaultLocale;
 }
 
+// src/scope.ts
+function createScope(namespace) {
+  return (key, vars, locale) => {
+    return t(`${namespace}:${key}`, vars, locale);
+  };
+}
+
 // src/richtext.ts
 function escapeRegExp(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1091,6 +1120,7 @@ exports.clearDictionaries = clearDictionaries;
 exports.clearFormatters = clearFormatters;
 exports.clearICUCache = clearICUCache;
 exports.configure = configure;
+exports.createScope = createScope;
 exports.detectLocale = detectLocale;
 exports.en_de = en_de;
 exports.en_es = en_es;