inline-i18n-multi 0.6.0 → 0.8.0

package/README.md

@@ -67,6 +67,12 @@ See "Hello" in your app? Just search for "Hello" in your codebase. **Done.**
 - **Interpolation Guards** - Handle missing variables gracefully (`missingVarHandler`)
 - **Locale Detection** - Auto-detect user locale from navigator, cookie, URL, or header (`detectLocale()`)
 - **Selectordinal** - Ordinal plural formatting (`{rank, selectordinal, one {#st} two {#nd} ...}`)
+- **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
 
 ---
 
@@ -551,6 +557,150 @@ Uses `Intl.PluralRules` with `{ type: 'ordinal' }` for locale-aware ordinal cate
 
 ---
 
+## ICU Message Cache
+
+Memoize parsed ICU ASTs to avoid re-parsing the same message patterns:
+
+```typescript
+import { configure, clearICUCache } from 'inline-i18n-multi'
+
+// Enable caching (default: 500 entries)
+configure({ icuCacheSize: 500 })
+
+// Disable caching
+configure({ icuCacheSize: 0 })
+
+// Manually clear the cache
+clearICUCache()
+```
+
+The cache uses FIFO (First-In, First-Out) eviction when the maximum size is reached. Repeated calls to `it()` or `t()` with the same ICU pattern will reuse the cached AST instead of re-parsing.
+
+---
+
+## Plural Shorthand
+
+Concise syntax for common plural patterns using `p` as a short type name:
+
+```typescript
+import { it, setLocale } from 'inline-i18n-multi'
+
+setLocale('en')
+
+// 2-part: singular|plural (value is prepended automatically)
+it({
+  en: '{count, p, item|items}',
+  ko: '{count, p, 개|개}'
+}, { count: 1 })   // → "1 item"
+
+it({
+  en: '{count, p, item|items}',
+  ko: '{count, p, 개|개}'
+}, { count: 5 })   // → "5 items"
+
+// 3-part: zero|singular|plural
+it({
+  en: '{count, p, no items|item|items}',
+  ko: '{count, p, 항목 없음|개|개}'
+}, { count: 0 })   // → "no items"
+
+it({
+  en: '{count, p, no items|item|items}',
+  ko: '{count, p, 항목 없음|개|개}'
+}, { count: 1 })   // → "1 item"
+
+it({
+  en: '{count, p, no items|item|items}',
+  ko: '{count, p, 항목 없음|개|개}'
+}, { count: 5 })   // → "5 items"
+```
+
+The shorthand is preprocessed into standard ICU `plural` syntax before parsing.
+
+---
+
+## Locale Persistence
+
+Auto-save and restore the user's locale to `cookie` or `localStorage`:
+
+```typescript
+import { configure, setLocale, restoreLocale } from 'inline-i18n-multi'
+
+// Configure persistence
+configure({
+  persistLocale: {
+    storage: 'cookie',         // 'cookie' | 'localStorage'
+    key: 'LOCALE',             // storage key (default: 'LOCALE')
+    expires: 365               // cookie expiry in days (default: 365)
+  }
+})
+
+// Restore locale from storage (returns the saved locale or undefined)
+const saved = restoreLocale()
+if (saved) {
+  // locale was restored from storage
+}
+
+// setLocale() automatically saves to the configured storage
+setLocale('ko')  // also saves 'ko' to cookie or localStorage
+```
+
+```typescript
+// localStorage example
+configure({
+  persistLocale: {
+    storage: 'localStorage',
+    key: 'APP_LOCALE'
+  }
+})
+
+restoreLocale()   // reads from localStorage
+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.
+
+---
+
 ## Configuration
 
 Configure global settings for fallback behavior and warnings:
@@ -636,12 +786,15 @@ Available helpers:
 
 | Function | Description |
 |----------|-------------|
-| `configure(options)` | Configure global settings (fallback, warnings, debug, missingVarHandler) |
+| `configure(options)` | Configure global settings (fallback, warnings, debug, missingVarHandler, icuCacheSize, persistLocale) |
 | `getConfig()` | Get current configuration |
 | `resetConfig()` | Reset configuration to defaults |
 | `loadAsync(locale, namespace?)` | Asynchronously load dictionary using configured loader |
 | `isLoaded(locale, namespace?)` | Check if dictionary has been loaded |
 | `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
 
@@ -681,6 +834,17 @@ interface Config {
   debugMode?: boolean | DebugModeOptions
   loader?: (locale: Locale, namespace: string) => Promise<Record<string, unknown>>
   missingVarHandler?: (varName: string, locale: string) => string
+  icuCacheSize?: number
+  persistLocale?: PersistLocaleOptions
+}
+
+interface PersistLocaleOptions {
+  /** Storage backend */
+  storage: 'cookie' | 'localStorage'
+  /** Storage key (default: 'LOCALE') */
+  key?: string
+  /** Cookie expiry in days (default: 365, cookie only) */
+  expires?: number
 }
 
 interface DebugModeOptions {

package/dist/index.d.mts

@@ -65,6 +65,17 @@ interface Config {
     loader?: (locale: Locale, namespace: string) => Promise<Record<string, unknown>>;
     /** Custom handler for missing interpolation variables (v0.6.0) */
     missingVarHandler?: (varName: string, locale: string) => string;
+    /** Maximum number of parsed ICU ASTs to cache (default: 500, 0 to disable) (v0.7.0) */
+    icuCacheSize?: number;
+    /** Locale persistence configuration (v0.7.0) */
+    persistLocale?: {
+        /** Storage mechanism */
+        storage: 'cookie' | 'localStorage';
+        /** Storage key name (default: 'LOCALE') */
+        key?: string;
+        /** Cookie expiry in days (default: 365). Only applies to cookie storage. */
+        expires?: number;
+    };
 }
 
 /**
@@ -83,6 +94,11 @@ declare function it(translations: Translations, vars?: TranslationVars): string;
 
 declare function setLocale(locale: Locale): void;
 declare function getLocale(): Locale;
+/**
+ * Restore locale from configured persistent storage.
+ * Returns the restored locale, or undefined if nothing was found.
+ */
+declare function restoreLocale(): Locale | undefined;
 
 /**
  * Runtime lookup function for build-tool-transformed code.
@@ -212,7 +228,7 @@ declare function getDictionary(locale: Locale, namespace?: string): Dictionary |
  */
 declare function getLoadedNamespaces(): string[];
 
-type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler'>> & Pick<Config, 'loader' | 'missingVarHandler'>;
+type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>> & Pick<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>;
 /**
  * Configure inline-i18n-multi settings
  *
@@ -233,6 +249,10 @@ declare function getConfig(): FullConfig;
  */
 declare function resetConfig(): void;
 
+/**
+ * Clear the ICU message AST cache
+ */
+declare function clearICUCache(): void;
 type CustomFormatter = (value: unknown, locale: string, style?: string) => string;
 /**
  * Register a custom formatter
@@ -275,6 +295,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
  */
@@ -303,4 +338,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, 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, 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

@@ -65,6 +65,17 @@ interface Config {
     loader?: (locale: Locale, namespace: string) => Promise<Record<string, unknown>>;
     /** Custom handler for missing interpolation variables (v0.6.0) */
     missingVarHandler?: (varName: string, locale: string) => string;
+    /** Maximum number of parsed ICU ASTs to cache (default: 500, 0 to disable) (v0.7.0) */
+    icuCacheSize?: number;
+    /** Locale persistence configuration (v0.7.0) */
+    persistLocale?: {
+        /** Storage mechanism */
+        storage: 'cookie' | 'localStorage';
+        /** Storage key name (default: 'LOCALE') */
+        key?: string;
+        /** Cookie expiry in days (default: 365). Only applies to cookie storage. */
+        expires?: number;
+    };
 }
 
 /**
@@ -83,6 +94,11 @@ declare function it(translations: Translations, vars?: TranslationVars): string;
 
 declare function setLocale(locale: Locale): void;
 declare function getLocale(): Locale;
+/**
+ * Restore locale from configured persistent storage.
+ * Returns the restored locale, or undefined if nothing was found.
+ */
+declare function restoreLocale(): Locale | undefined;
 
 /**
  * Runtime lookup function for build-tool-transformed code.
@@ -212,7 +228,7 @@ declare function getDictionary(locale: Locale, namespace?: string): Dictionary |
  */
 declare function getLoadedNamespaces(): string[];
 
-type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler'>> & Pick<Config, 'loader' | 'missingVarHandler'>;
+type FullConfig = Required<Omit<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>> & Pick<Config, 'loader' | 'missingVarHandler' | 'persistLocale'>;
 /**
  * Configure inline-i18n-multi settings
  *
@@ -233,6 +249,10 @@ declare function getConfig(): FullConfig;
  */
 declare function resetConfig(): void;
 
+/**
+ * Clear the ICU message AST cache
+ */
+declare function clearICUCache(): void;
 type CustomFormatter = (value: unknown, locale: string, style?: string) => string;
 /**
  * Register a custom formatter
@@ -275,6 +295,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
  */
@@ -303,4 +338,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, 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, 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

@@ -2,15 +2,6 @@
 
 var icuMessageformatParser = require('@formatjs/icu-messageformat-parser');
 
-// src/context.ts
-var currentLocale = "en";
-function setLocale(locale) {
-  currentLocale = locale;
-}
-function getLocale() {
-  return currentLocale;
-}
-
 // src/config.ts
 function defaultWarningHandler(warning) {
   const parts = [`[inline-i18n] Missing translation for locale "${warning.requestedLocale}"`];
@@ -42,7 +33,8 @@ var defaultConfig = {
   warnOnMissing: isDevMode(),
   onMissingTranslation: defaultWarningHandler,
   debugMode: false,
-  loader: void 0
+  loader: void 0,
+  icuCacheSize: 500
 };
 var config = { ...defaultConfig };
 function configure(options) {
@@ -110,6 +102,82 @@ function applyDebugFormat(output, debugInfo) {
   }
   return output;
 }
+
+// src/context.ts
+var currentLocale = "en";
+function setCookie(name, value, days) {
+  if (typeof document === "undefined") return;
+  const expires = new Date(Date.now() + days * 864e5).toUTCString();
+  document.cookie = `${name}=${value}; expires=${expires}; path=/; SameSite=Lax`;
+}
+function getCookie(name) {
+  if (typeof document === "undefined") return void 0;
+  const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+  return match?.[1];
+}
+function persistLocaleToStorage(locale) {
+  const cfg = getConfig();
+  if (!cfg.persistLocale) return;
+  const { storage, key = "LOCALE", expires = 365 } = cfg.persistLocale;
+  if (storage === "cookie") {
+    setCookie(key, locale, expires);
+  } else if (storage === "localStorage") {
+    if (typeof localStorage !== "undefined") {
+      try {
+        localStorage.setItem(key, locale);
+      } catch {
+      }
+    }
+  }
+}
+function setLocale(locale) {
+  currentLocale = locale;
+  persistLocaleToStorage(locale);
+}
+function getLocale() {
+  return currentLocale;
+}
+function restoreLocale() {
+  const cfg = getConfig();
+  if (!cfg.persistLocale) return void 0;
+  const { storage, key = "LOCALE" } = cfg.persistLocale;
+  let stored;
+  if (storage === "cookie") {
+    stored = getCookie(key);
+  } else if (storage === "localStorage") {
+    if (typeof localStorage !== "undefined") {
+      try {
+        stored = localStorage.getItem(key) ?? void 0;
+      } catch {
+      }
+    }
+  }
+  if (stored) {
+    currentLocale = stored;
+    return stored;
+  }
+  return void 0;
+}
+var icuCache = /* @__PURE__ */ new Map();
+function clearICUCache() {
+  icuCache.clear();
+}
+function cachedParse(template) {
+  const cached = icuCache.get(template);
+  if (cached) return cached;
+  const ast = icuMessageformatParser.parse(template);
+  const cfg = getConfig();
+  if (cfg.icuCacheSize > 0) {
+    if (icuCache.size >= cfg.icuCacheSize) {
+      const firstKey = icuCache.keys().next().value;
+      if (firstKey !== void 0) {
+        icuCache.delete(firstKey);
+      }
+    }
+    icuCache.set(template, ast);
+  }
+  return ast;
+}
 function handleMissingVar(varName, locale) {
   const cfg = getConfig();
   if (cfg.missingVarHandler) {
@@ -404,13 +472,34 @@ function formatListValue(variableName, type, style, vars, locale) {
     return value.join(", ");
   }
 }
+var PLURAL_SHORTHAND_PATTERN = /\{(\w+),\s*p,\s*([^}]+)\}/g;
+function hasPluralShorthand(template) {
+  PLURAL_SHORTHAND_PATTERN.lastIndex = 0;
+  return PLURAL_SHORTHAND_PATTERN.test(template);
+}
+function preprocessPluralShorthand(template) {
+  PLURAL_SHORTHAND_PATTERN.lastIndex = 0;
+  return template.replace(PLURAL_SHORTHAND_PATTERN, (_, variable, args) => {
+    const parts = args.split("|").map((s) => s.trim());
+    if (parts.length === 2) {
+      const [singular, plural] = parts;
+      return `{${variable}, plural, one {# ${singular}} other {# ${plural}}}`;
+    }
+    if (parts.length === 3) {
+      const [zero, singular, plural] = parts;
+      return `{${variable}, plural, =0 {${zero}} one {# ${singular}} other {# ${plural}}}`;
+    }
+    return `{${variable}, p, ${args}}`;
+  });
+}
 function interpolateICU(template, vars, locale) {
-  const { processed: afterCustom, replacements: customReplacements } = preprocessCustomFormatters(template);
+  const afterPluralShorthand = preprocessPluralShorthand(template);
+  const { processed: afterCustom, replacements: customReplacements } = preprocessCustomFormatters(afterPluralShorthand);
   const { processed: afterCurrency, replacements: currencyReplacements } = preprocessCurrency(afterCustom);
   const { processed: afterCompact, replacements: compactReplacements } = preprocessCompactNumber(afterCurrency);
   const { processed: afterRelTime, replacements: relTimeReplacements } = preprocessRelativeTime(afterCompact);
   const { processed: afterList, replacements: listReplacements } = preprocessList(afterRelTime);
-  const ast = icuMessageformatParser.parse(afterList);
+  const ast = cachedParse(afterList);
   let result = formatElements(ast, vars, locale, null);
   for (const [placeholder, { variable, formatterName, style }] of customReplacements) {
     const value = vars[variable];
@@ -507,7 +596,7 @@ function formatSelect(el, vars, locale) {
   }
   return handleMissingVar(el.value, locale);
 }
-var ICU_PATTERN = /\{[^}]+,\s*(plural|select|selectordinal|number|date|time|relativeTime|list|currency)\s*[,}]/;
+var ICU_PATTERN = /\{[^}]+,\s*(plural|select|selectordinal|number|date|time|relativeTime|list|currency|p)\s*[,}]/;
 function hasICUPattern(template) {
   return ICU_PATTERN.test(template);
 }
@@ -516,7 +605,7 @@ function hasICUPattern(template) {
 var VARIABLE_PATTERN = /\{(\w+)\}/g;
 function interpolate(template, vars, locale) {
   const resolvedLocale = locale || "en";
-  if (hasICUPattern(template) || hasCustomFormatter(template)) {
+  if (hasICUPattern(template) || hasCustomFormatter(template) || hasPluralShorthand(template)) {
     if (!vars) {
       const cfg = getConfig();
       if (cfg.missingVarHandler) {
@@ -961,6 +1050,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, "\\$&");
@@ -1000,7 +1096,9 @@ function parseRichText(template, componentNames) {
 exports.__i18n_lookup = __i18n_lookup;
 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;
@@ -1028,6 +1126,7 @@ exports.loadDictionary = loadDictionary;
 exports.parseRichText = parseRichText;
 exports.registerFormatter = registerFormatter;
 exports.resetConfig = resetConfig;
+exports.restoreLocale = restoreLocale;
 exports.setLocale = setLocale;
 exports.t = t;
 exports.zh_es = zh_es;