i18ntk 4.0.0 → 4.2.0

package/runtime/enhanced.d.ts

@@ -72,19 +72,19 @@ export interface LanguageConfig {
 }
 
 // Enhanced TypeScript-compatible translation functions
-export function translate<T = string>(key: string, params?: TranslationParams, options?: TranslationOptions): T;
-export function translate<T = string>(key: TranslationKey<T>, params?: TranslationParams, options?: TranslationOptions): T;
+export function translate<T = string>(key: string, params?: TranslationParams, options?: TranslationOptions): Promise<T>;
+export function translate<T = string>(key: TranslationKey<T>, params?: TranslationParams, options?: TranslationOptions): Promise<T>;
 
 export const t: typeof translate;
 
 // Type-safe translation with strict typing
-export function tTyped<T = string>(key: string, params?: TranslationParams, options?: TranslationOptions): T;
+export function tTyped<T = string>(key: string, params?: TranslationParams, options?: TranslationOptions): Promise<T>;
 
 // Translation with encryption support
 export function translateEncrypted<T = string>(key: string, params?: TranslationParams, options?: TranslationOptions): Promise<T>;
 
 // Batch translation operations
-export function translateBatch<T = string>(keys: string[], params?: TranslationParams[], options?: TranslationOptions): T[];
+export function translateBatch<T = string>(keys: string[], params?: TranslationParams[], options?: TranslationOptions): Promise<T[]>;
 export function translateBatchEncrypted<T = string>(keys: string[], params?: TranslationParams[], options?: TranslationOptions): Promise<T[]>;
 
 // Configuration and initialization
@@ -219,4 +219,4 @@ export interface MigrationResult {
 }
 
 // Export compatibility with existing runtime
-export * from './i18ntk.d.ts';
+export * from './i18ntk.d.ts';

package/runtime/enhanced.js

@@ -884,26 +884,46 @@ async function initI18nRuntime(options = {}) {
 }
 
 // Backward compatibility
-function translate(key, params, options) {
-  if (!runtimeInstance) {
-    runtimeInstance = new I18nEnhancedRuntime();
-  }
-  return runtimeInstance.translate(key, params, options);
-}
-
-const t = translate;
-
-// Export for both CommonJS and ES modules
-module.exports = {
-  initI18nRuntime,
-  translate,
-  t,
-  translateEncrypted: async (key, params, options) => {
-    if (!runtimeInstance) {
-      runtimeInstance = new I18nEnhancedRuntime();
-    }
-    return runtimeInstance.translateEncrypted(key, params, options);
-  },
+function translate(key, params, options) {
+  if (!runtimeInstance) {
+    runtimeInstance = new I18nEnhancedRuntime();
+  }
+  return runtimeInstance.translate(key, params, options);
+}
+
+const t = translate;
+const tTyped = translate;
+
+async function translateBatch(keys, paramsArray, options) {
+  if (!runtimeInstance) {
+    runtimeInstance = new I18nEnhancedRuntime();
+  }
+  return runtimeInstance.translateBatch(keys, paramsArray, options);
+}
+
+async function translateBatchEncrypted(keys, paramsArray, options) {
+  if (!runtimeInstance) {
+    runtimeInstance = new I18nEnhancedRuntime();
+  }
+  return runtimeInstance.translateBatchEncrypted(keys, paramsArray, options);
+}
+
+async function translateEncrypted(key, params, options) {
+  if (!runtimeInstance) {
+    runtimeInstance = new I18nEnhancedRuntime();
+  }
+  return runtimeInstance.translateEncrypted(key, params, options);
+}
+
+// Export for both CommonJS and ES modules
+module.exports = {
+  initI18nRuntime,
+  translate,
+  t,
+  tTyped,
+  translateEncrypted,
+  translateBatch,
+  translateBatchEncrypted,
   
   // TypeScript compatibility exports
   I18nEnhancedRuntime,
@@ -922,8 +942,12 @@ module.exports = {
 };
 
 // ES module support
-module.exports.default = {
-  initI18nRuntime,
-  translate,
-  t,
-};
+module.exports.default = {
+  initI18nRuntime,
+  translate,
+  t,
+  tTyped,
+  translateEncrypted,
+  translateBatch,
+  translateBatchEncrypted,
+};

package/runtime/i18ntk.d.ts

@@ -1,6 +1,6 @@
 // runtime/i18ntk.d.ts
-// Complete TypeScript definitions for i18ntk internationalization framework
-// Version 3.2.0 - Full TypeScript support with AES-256-GCM encryption
+// Complete TypeScript definitions for i18ntk internationalization framework
+// Version 4.2.0 - Enhanced API types plus lightweight runtime compatibility
 
 /**
  * Core translation parameters interface
@@ -445,16 +445,21 @@ export interface I18nRuntime {
 /**
  * Basic runtime interface (for backward compatibility)
  */
-export interface BasicI18nRuntime {
+export interface BasicI18nRuntime {
   /**
    * Translate a key with parameters (synchronous)
    */
-  translate(key: string, params?: TranslationParams): string;
+  translate(key: string, params?: TranslationParams, options?: Pick<TranslationOptions, 'language' | 'fallbackLanguage'>): string | number | boolean | null | object | unknown[];
   
   /**
    * Alias for translate function (synchronous)
    */
-  t(key: string, params?: TranslationParams): string;
+  t(key: string, params?: TranslationParams, options?: Pick<TranslationOptions, 'language' | 'fallbackLanguage'>): string | number | boolean | null | object | unknown[];
+
+  /**
+   * Translate multiple keys synchronously.
+   */
+  translateBatch(keys: string[], params?: TranslationParams | TranslationParams[], options?: Pick<TranslationOptions, 'language' | 'fallbackLanguage'>): Array<string | number | boolean | null | object | unknown[]>;
   
   /**
    * Set language
@@ -469,7 +474,25 @@ export interface BasicI18nRuntime {
   /**
    * Get available languages (synchronous)
    */
-  getAvailableLanguages(): string[];
+  getAvailableLanguages(): string[];
+
+  /**
+   * Clear all cached runtime data, or one language when provided.
+   */
+  clearCache(language?: string): void;
+
+  /**
+   * Return lightweight cache diagnostics for production observability.
+   */
+  getCacheInfo(): {
+    language: string;
+    fallbackLanguage: string;
+    lazy: boolean;
+    cachedLanguages: string[];
+    manifestLanguages: string[];
+    loadedFileCount: number;
+    eagerLoadedLanguages: string[];
+  };
   
   /**
    * Refresh translations
@@ -487,7 +510,7 @@ export declare function initI18nRuntime(config: I18nConfig): Promise<I18nRuntime
  * This is the default export from 'i18ntk/runtime'
  */
 export declare function initRuntime(options: {
-  baseDir: string;
+  baseDir?: string;
   language?: string;
   fallbackLanguage?: string;
   keySeparator?: string;

package/runtime/index.d.ts

@@ -1,31 +1,60 @@
 // runtime/index.d.ts
 // Public runtime API types for i18ntk
 
-export interface InitOptions {
-  baseDir?: string;
-  language?: string;
+export interface InitOptions {
+  /** Locale base directory. Defaults to config/env resolution when omitted. */
+  baseDir?: string;
+  language?: string;
   fallbackLanguage?: string;
   keySeparator?: string;
+  /** Eagerly cache the active and fallback languages during initialization. */
   preload?: boolean;
+  /** Build a key manifest and load matching JSON files on first key access. */
   lazy?: boolean;
 }
-
-export type TranslateParams = Record<string, unknown>;
-
-export function translate(key: string, params?: TranslateParams): string;
-export const t: typeof translate;
-
-export function initRuntime(options?: InitOptions): {
-  t: typeof translate;
-  translate: typeof translate;
-  setLanguage: typeof setLanguage;
-  getLanguage: typeof getLanguage;
-  getAvailableLanguages: typeof getAvailableLanguages;
-  refresh: typeof refresh;
-};
-
-export function setLanguage(lang: string): void;
+
+export type TranslateParams = Record<string, unknown>;
+export interface TranslationOptions {
+  /** Translate this call with a different language without mutating runtime state. */
+  language?: string;
+  /** Fallback language for this call. */
+  fallbackLanguage?: string;
+}
+export type TranslationValue = string | number | boolean | null | object | unknown[];
+export type TranslateBatchParams = TranslateParams | TranslateParams[];
+
+export interface RuntimeCacheInfo {
+  language: string;
+  fallbackLanguage: string;
+  lazy: boolean;
+  cachedLanguages: string[];
+  manifestLanguages: string[];
+  loadedFileCount: number;
+  eagerLoadedLanguages: string[];
+}
+
+export interface RuntimeInstance {
+  t(key: string, params?: TranslateParams, options?: TranslationOptions): TranslationValue;
+  translate(key: string, params?: TranslateParams, options?: TranslationOptions): TranslationValue;
+  translateBatch(keys: string[], params?: TranslateBatchParams, options?: TranslationOptions): TranslationValue[];
+  setLanguage(lang: string): void;
+  getLanguage(): string;
+  getAvailableLanguages(): string[];
+  clearCache(lang?: string): void;
+  getCacheInfo(): RuntimeCacheInfo;
+  refresh(lang?: string): void;
+}
+
+export function translate(key: string, params?: TranslateParams, options?: TranslationOptions): TranslationValue;
+export const t: typeof translate;
+export function translateBatch(keys: string[], params?: TranslateBatchParams, options?: TranslationOptions): TranslationValue[];
+
+export function initRuntime(options?: InitOptions): RuntimeInstance;
+
+export function setLanguage(lang: string): void;
 export function getLanguage(): string;
 export function getAvailableLanguages(): string[];
+export function clearCache(lang?: string): void;
+export function getCacheInfo(): RuntimeCacheInfo;
 export function refresh(lang?: string): void;
 export function loadKeyManifest(baseDir?: string): Map<string, string>;

package/runtime/index.js

@@ -8,14 +8,22 @@ const path = require('path');
 const SecurityUtils = require('../utils/security');
 const { envManager } = require('../utils/env-manager');
 
-let configManager = null;
-try { configManager = require('../utils/config-manager'); } catch (_) { /* optional */ }
-
-function createState(options = {}) {
-  return {
-    baseDir: resolveBaseDir(options.baseDir),
-    language: options.language || 'en',
-    fallbackLanguage: options.fallbackLanguage || 'en',
+let configManager = null;
+try { configManager = require('../utils/config-manager'); } catch (_) { /* optional */ }
+
+const SAFE_LANGUAGE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,35}$/;
+
+function normalizeLanguageCode(value, fallback = 'en') {
+  if (typeof value !== 'string') return fallback;
+  const trimmed = value.trim();
+  return SAFE_LANGUAGE_PATTERN.test(trimmed) ? trimmed : fallback;
+}
+
+function createState(options = {}) {
+  return {
+    baseDir: resolveBaseDir(options.baseDir),
+    language: normalizeLanguageCode(options.language, 'en'),
+    fallbackLanguage: normalizeLanguageCode(options.fallbackLanguage, 'en'),
     keySeparator: options.keySeparator || '.',
     cache: new Map(),
     lazy: options.lazy === true,
@@ -47,21 +55,29 @@ function stripBOMAndComments(s) {
   return s;
 }
 
-function readJsonSafe(file) {
-  const raw = SecurityUtils.safeReadFileSync(file, path.dirname(file), 'utf8');
-  if (raw === null || raw === undefined) {
-    throw new Error(`Unable to read JSON file: ${file}`);
-  }
-  const cleaned = stripBOMAndComments(raw);
-  if (!cleaned) {
-    throw new Error(`Empty JSON file: ${file}`);
-  }
-  try {
-    return JSON.parse(cleaned);
-  } catch (parseError) {
-    throw new Error(`Invalid JSON in file ${file}: ${parseError.message}`);
-  }
-}
+function readJsonSafe(file) {
+  const raw = SecurityUtils.safeReadFileSync(file, path.dirname(file), 'utf8');
+  if (raw === null || raw === undefined) {
+    throw new Error(`Unable to read JSON file: ${file}`);
+  }
+  const withoutBOM = raw.charCodeAt && raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw;
+  if (!withoutBOM) {
+    throw new Error(`Empty JSON file: ${file}`);
+  }
+  try {
+    return JSON.parse(withoutBOM);
+  } catch (parseError) {
+    const cleaned = stripBOMAndComments(raw);
+    if (!cleaned) {
+      throw new Error(`Empty JSON file: ${file}`);
+    }
+    try {
+      return JSON.parse(cleaned);
+    } catch (_) {
+      throw new Error(`Invalid JSON in file ${file}: ${parseError.message}`);
+    }
+  }
+}
 
 function deepMerge(target, source) {
   if (!target || typeof target !== 'object') target = {};
@@ -139,7 +155,8 @@ function listJsonFilesRecursively(dir, baseDir = dir) {
   return results;
 }
 
-function loadKeyManifestFromDir(baseDir) {
+function loadKeyManifestFromDir(baseDir) {
+  if (!baseDir || typeof baseDir !== 'string') return new Map();
   const validatedBase = SecurityUtils.validatePath(baseDir, path.dirname(baseDir));
   const baseStat = SecurityUtils.safeStatSync(validatedBase, path.dirname(validatedBase));
   const baseRoot = baseStat && baseStat.isFile() ? path.dirname(validatedBase) : validatedBase;
@@ -176,11 +193,13 @@ function loadKeyManifestFromDir(baseDir) {
 }
 
 function getLanguagePath(baseDir, lang) {
+  lang = normalizeLanguageCode(lang, '');
+  if (!lang) return null;
   const langDir = path.join(baseDir, lang);
   const langFile = path.join(baseDir, `${lang}.json`);
-  const langDirStat = SecurityUtils.safeStatSync(langDir, path.dirname(langDir));
+  const langDirStat = SecurityUtils.safeStatSync(langDir, baseDir);
   if (langDirStat && langDirStat.isDirectory()) return langDir;
-  const langFileStat = SecurityUtils.safeStatSync(langFile, path.dirname(langFile));
+  const langFileStat = SecurityUtils.safeStatSync(langFile, baseDir);
   if (langFileStat && langFileStat.isFile()) return langFile;
   return null;
 }
@@ -219,13 +238,15 @@ function loadFileLazy(runtimeState, filePath, lang) {
   return data;
 }
 
-function readLanguageFromBase(baseDir, lang) {
-  const merged = {};
-  const langFile = path.join(baseDir, `${lang}.json`);
-  const langDir = path.join(baseDir, lang);
-
-  // Prefer folder if exists, otherwise single file
-  const langDirStat = SecurityUtils.safeStatSync(langDir, path.dirname(langDir));
+function readLanguageFromBase(baseDir, lang) {
+  lang = normalizeLanguageCode(lang, '');
+  if (!lang) return {};
+  const merged = {};
+  const langFile = path.join(baseDir, `${lang}.json`);
+  const langDir = path.join(baseDir, lang);
+
+  // Prefer folder if exists, otherwise single file
+  const langDirStat = SecurityUtils.safeStatSync(langDir, baseDir);
   if (langDirStat && langDirStat.isDirectory()) {
     const files = listJsonFilesRecursively(langDir, langDir);
     for (const file of files) {
@@ -236,8 +257,8 @@ function readLanguageFromBase(baseDir, lang) {
         // Skip unreadable/invalid files
       }
     }
-  } else {
-    const langFileStat = SecurityUtils.safeStatSync(langFile, path.dirname(langFile));
+  } else {
+    const langFileStat = SecurityUtils.safeStatSync(langFile, baseDir);
     if (langFileStat && langFileStat.isFile()) {
       try {
         const data = readJsonSafe(langFile);
@@ -249,9 +270,10 @@ function readLanguageFromBase(baseDir, lang) {
   return merged;
 }
 
-function getTranslationsForState(runtimeState, lang) {
-  if (!runtimeState.baseDir) runtimeState.baseDir = resolveBaseDir();
-
+function getTranslationsForState(runtimeState, lang) {
+  if (!runtimeState.baseDir) runtimeState.baseDir = resolveBaseDir();
+  lang = normalizeLanguageCode(lang, runtimeState.fallbackLanguage || 'en');
+
   if (runtimeState.lazy) {
     if (runtimeState.cache.has(lang)) return runtimeState.cache.get(lang);
     runtimeState.cache.set(lang, {});
@@ -265,12 +287,13 @@ function getTranslationsForState(runtimeState, lang) {
   return data;
 }
 
-function interpolate(template, params) {
-  if (typeof template !== 'string') return template;
-  return template
-    .replace(/\{\{(\w+)\}\}/g, (m, p1) => (p1 in params ? String(params[p1]) : m))
-    .replace(/\{(\w+)\}/g, (m, p1) => (p1 in params ? String(params[p1]) : m));
-}
+function interpolate(template, params) {
+  if (typeof template !== 'string') return template;
+  params = params && typeof params === 'object' ? params : {};
+  return template
+    .replace(/\{\{(\w+)\}\}/g, (m, p1) => (p1 in params ? String(params[p1]) : m))
+    .replace(/\{(\w+)\}/g, (m, p1) => (p1 in params ? String(params[p1]) : m));
+}
 
 // Resolve a dotted key path from an object
 function resolveKey(obj, key, sep = '.', runtimeState = null, lang = null) {
@@ -288,11 +311,15 @@ function resolveKey(obj, key, sep = '.', runtimeState = null, lang = null) {
           const prefix = parts.slice(0, i).join(sep);
           const filePath = manifest.get(prefix);
           const loadedFileKey = `${lang}\0${filePath}`;
-          if (filePath && !runtimeState.loadedFiles.has(loadedFileKey)) {
-            loadFileLazy(runtimeState, filePath, lang);
-            runtimeState.loadedFiles.add(loadedFileKey);
-            const langData = runtimeState.cache.get(lang);
-            return resolveKey(langData, key, sep, runtimeState, lang);
+          if (filePath && !runtimeState.loadedFiles.has(loadedFileKey)) {
+            runtimeState.loadedFiles.add(loadedFileKey);
+            try {
+              loadFileLazy(runtimeState, filePath, lang);
+            } catch (_) {
+              // stale manifest entry — already marked as loaded to prevent retry
+            }
+            const langData = runtimeState.cache.get(lang);
+            return resolveKey(langData, key, sep, runtimeState, lang);
           }
         }
         if (!runtimeState.eagerLoadedLanguages.has(lang)) {
@@ -355,43 +382,67 @@ function preload(runtimeState, shouldPreload) {
   }
 }
 
-function createRuntime(runtimeState) {
-  const runtimeTranslate = (key, params) => translateWithState(runtimeState, key, params);
-  return {
-    t: runtimeTranslate,
-    translate: runtimeTranslate,
-    setLanguage: (lang) => setLanguageForState(runtimeState, lang),
-    getLanguage: () => getLanguageForState(runtimeState),
-    getAvailableLanguages: () => getAvailableLanguagesForState(runtimeState),
-    refresh: (lang) => refreshForState(runtimeState, lang),
-  };
-}
-
-function translate(key, params = {}) {
-  return translateWithState(singletonState, key, params);
-}
-
-function translateWithState(runtimeState, key, params = {}) {
-  const langData = getTranslationsForState(runtimeState, runtimeState.language);
-  let value = resolveKey(langData, key, runtimeState.keySeparator, runtimeState, runtimeState.language);
+function createRuntime(runtimeState) {
+  const runtimeTranslate = (key, params, options) => translateWithState(runtimeState, key, params, options);
+  return {
+    t: runtimeTranslate,
+    translate: runtimeTranslate,
+    translateBatch: (keys, params, options) => translateBatchWithState(runtimeState, keys, params, options),
+    setLanguage: (lang) => setLanguageForState(runtimeState, lang),
+    getLanguage: () => getLanguageForState(runtimeState),
+    getAvailableLanguages: () => getAvailableLanguagesForState(runtimeState),
+    clearCache: (lang) => clearCacheForState(runtimeState, lang),
+    getCacheInfo: () => getCacheInfoForState(runtimeState),
+    refresh: (lang) => refreshForState(runtimeState, lang),
+  };
+}
 
-  if (typeof value === 'undefined' && runtimeState.fallbackLanguage) {
-    const fbData = getTranslationsForState(runtimeState, runtimeState.fallbackLanguage);
-    value = resolveKey(fbData, key, runtimeState.keySeparator, runtimeState, runtimeState.fallbackLanguage);
+function translate(key, params = {}, options = {}) {
+  return translateWithState(singletonState, key, params, options);
+}
+
+function translateWithState(runtimeState, key, params = {}, options = {}) {
+  params = params && typeof params === 'object' ? params : {};
+  options = options && typeof options === 'object' ? options : {};
+
+  const activeLanguage = normalizeLanguageCode(options.language, runtimeState.language);
+  const fallbackLanguage = typeof options.fallbackLanguage === 'string'
+    ? normalizeLanguageCode(options.fallbackLanguage, '')
+    : runtimeState.fallbackLanguage;
+
+  const langData = getTranslationsForState(runtimeState, activeLanguage);
+  let value = resolveKey(langData, key, runtimeState.keySeparator, runtimeState, activeLanguage);
+
+  if (typeof value === 'undefined' && fallbackLanguage && fallbackLanguage !== activeLanguage) {
+    const fbData = getTranslationsForState(runtimeState, fallbackLanguage);
+    value = resolveKey(fbData, key, runtimeState.keySeparator, runtimeState, fallbackLanguage);
   }
-
-  if (typeof value === 'string') return interpolate(value, params);
-  return typeof value === 'undefined' ? key : value;
-}
+
+  if (typeof value === 'string') return interpolate(value, params);
+  return typeof value === 'undefined' ? key : value;
+}
+
+function translateBatch(keys, params = {}, options = {}) {
+  return translateBatchWithState(singletonState, keys, params, options);
+}
+
+function translateBatchWithState(runtimeState, keys, params = {}, options = {}) {
+  if (!Array.isArray(keys)) return [];
+  return keys.map((key, index) => {
+    const perKeyParams = Array.isArray(params) ? (params[index] || {}) : params;
+    return translateWithState(runtimeState, key, perKeyParams, options);
+  });
+}
 
 function setLanguage(lang) {
   setLanguageForState(singletonState, lang);
 }
 
-function setLanguageForState(runtimeState, lang) {
-  if (!lang || typeof lang !== 'string') return;
-  runtimeState.language = lang;
-}
+function setLanguageForState(runtimeState, lang) {
+  const safeLang = normalizeLanguageCode(lang, '');
+  if (!safeLang) return;
+  runtimeState.language = safeLang;
+}
 
 function getLanguage() {
   return getLanguageForState(singletonState);
@@ -405,35 +456,72 @@ function getAvailableLanguages() {
   return getAvailableLanguagesForState(singletonState);
 }
 
-function getAvailableLanguagesForState(runtimeState) {
+function getAvailableLanguagesForState(runtimeState) {
   const langs = new Set();
   if (!runtimeState.baseDir) runtimeState.baseDir = resolveBaseDir();
   if (!SecurityUtils.safeExistsSync(runtimeState.baseDir, path.dirname(runtimeState.baseDir))) return ['en'];
   try {
     for (const entry of fs.readdirSync(runtimeState.baseDir, { withFileTypes: true })) {
-      if (entry.isFile() && entry.name.toLowerCase().endsWith('.json')) {
-        langs.add(entry.name.replace(/\.json$/i, ''));
-      } else if (entry.isDirectory()) {
-        const lang = entry.name;
-        const idx = path.join(runtimeState.baseDir, lang, `${lang}.json`);
-        if (SecurityUtils.safeExistsSync(idx, path.dirname(idx))) langs.add(lang);
-        else langs.add(lang); // be permissive
-      }
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.json')) {
+        const lang = normalizeLanguageCode(entry.name.replace(/\.json$/i, ''), '');
+        if (lang) langs.add(lang);
+      } else if (entry.isDirectory()) {
+        const lang = normalizeLanguageCode(entry.name, '');
+        if (!lang) continue;
+        const idx = path.join(runtimeState.baseDir, lang, `${lang}.json`);
+        if (SecurityUtils.safeExistsSync(idx, runtimeState.baseDir)) langs.add(lang);
+        else langs.add(lang); // be permissive
+      }
     }
   } catch (_) {
     // Unreadable directory
     return ['en'];
   }
-  return Array.from(langs.size ? langs : new Set(['en']));
-}
+  return Array.from(langs.size ? langs : new Set(['en']));
+}
+
+function clearCache(lang) {
+  clearCacheForState(singletonState, lang);
+}
+
+function clearCacheForState(runtimeState, lang) {
+  if (typeof lang === 'string') {
+    refreshForState(runtimeState, lang);
+    return;
+  }
+
+  runtimeState.cache.clear();
+  if (runtimeState.keyManifest) runtimeState.keyManifest.clear();
+  if (runtimeState.loadedFiles) runtimeState.loadedFiles.clear();
+  if (runtimeState.eagerLoadedLanguages) runtimeState.eagerLoadedLanguages.clear();
+}
+
+function getCacheInfo() {
+  return getCacheInfoForState(singletonState);
+}
+
+function getCacheInfoForState(runtimeState) {
+  return {
+    language: runtimeState.language,
+    fallbackLanguage: runtimeState.fallbackLanguage,
+    lazy: runtimeState.lazy === true,
+    cachedLanguages: Array.from(runtimeState.cache.keys()).sort(),
+    manifestLanguages: runtimeState.keyManifest ? Array.from(runtimeState.keyManifest.keys()).sort() : [],
+    loadedFileCount: runtimeState.loadedFiles ? runtimeState.loadedFiles.size : 0,
+    eagerLoadedLanguages: runtimeState.eagerLoadedLanguages ? Array.from(runtimeState.eagerLoadedLanguages).sort() : [],
+  };
+}
 
 function refresh(lang) {
   refreshForState(singletonState, lang);
 }
 
 function refreshForState(runtimeState, lang = runtimeState.language) {
+  lang = normalizeLanguageCode(lang, '');
+  if (!lang) return;
   if (runtimeState.cache.has(lang)) runtimeState.cache.delete(lang);
-  if (runtimeState.eagerLoadedLanguages) runtimeState.eagerLoadedLanguages.delete(lang);
+  if (runtimeState.eagerLoadedLanguages) runtimeState.eagerLoadedLanguages.delete(lang);
+  if (runtimeState.keyManifest) runtimeState.keyManifest.delete(lang);
   if (runtimeState.loadedFiles) {
     for (const fileKey of Array.from(runtimeState.loadedFiles)) {
       if (fileKey.startsWith(`${lang}\0`)) runtimeState.loadedFiles.delete(fileKey);
@@ -445,12 +533,15 @@ function refreshForState(runtimeState, lang = runtimeState.language) {
 }
 
 module.exports = {
-  initRuntime,
-  translate,
-  t: translate,
-  setLanguage,
-  getLanguage,
-  getAvailableLanguages,
+  initRuntime,
+  translate,
+  t: translate,
+  translateBatch,
+  setLanguage,
+  getLanguage,
+  getAvailableLanguages,
+  clearCache,
+  getCacheInfo,
   refresh,
   loadKeyManifest: (baseDir) => loadKeyManifestFromDir(baseDir || singletonState.baseDir),
 };