@universal-i18n/core 1.0.0

package/dist/index.mjs

@@ -0,0 +1,752 @@
+// src/types.ts
+var TranslationError = class extends Error {
+  constructor(message, sourceText, targetLocale, cause) {
+    super(message);
+    this.sourceText = sourceText;
+    this.targetLocale = targetLocale;
+    this.cause = cause;
+    this.name = "TranslationError";
+  }
+};
+var CacheError = class extends Error {
+  constructor(message, backend, cause) {
+    super(message);
+    this.backend = backend;
+    this.cause = cause;
+    this.name = "CacheError";
+  }
+};
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+var RateLimitError = class extends Error {
+  constructor(message, retryAfterMs) {
+    super(message);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "RateLimitError";
+  }
+};
+
+// src/cache/memory-cache.ts
+var MemoryCache = class {
+  cache;
+  maxEntries;
+  hits = 0;
+  misses = 0;
+  constructor(maxEntries = 1e3) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.maxEntries = maxEntries;
+  }
+  async get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+    if (entry.ttl !== void 0 && Date.now() - entry.createdAt > entry.ttl * 1e3) {
+      this.cache.delete(key);
+      this.misses++;
+      return null;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    this.hits++;
+    return entry.value;
+  }
+  async set(key, value, ttl) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+    if (this.cache.size >= this.maxEntries) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== void 0) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(key, {
+      value,
+      createdAt: Date.now(),
+      ttl
+    });
+  }
+  async delete(key) {
+    this.cache.delete(key);
+  }
+  async clear(pattern) {
+    if (!pattern) {
+      this.cache.clear();
+      this.hits = 0;
+      this.misses = 0;
+      return;
+    }
+    const prefix = pattern.replace(/\*$/, "");
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+  async stats() {
+    const total = this.hits + this.misses;
+    const entries = Array.from(this.cache.values());
+    let oldestEntry;
+    let newestEntry;
+    if (entries.length > 0) {
+      const sorted = entries.sort((a, b) => a.createdAt - b.createdAt);
+      oldestEntry = new Date(sorted[0].createdAt).toISOString();
+      newestEntry = new Date(sorted[sorted.length - 1].createdAt).toISOString();
+    }
+    return {
+      totalEntries: this.cache.size,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+      missRate: total > 0 ? this.misses / total : 0,
+      oldestEntry,
+      newestEntry
+    };
+  }
+};
+
+// src/cache/fs-cache.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, statSync, unlinkSync } from "fs";
+import { join, dirname } from "path";
+var FileSystemCache = class {
+  dir;
+  hits = 0;
+  misses = 0;
+  defaultTtl;
+  constructor(dir = ".cache/universal-i18n", defaultTtl = 604800) {
+    this.dir = dir;
+    this.defaultTtl = defaultTtl;
+    this.ensureDir(this.dir);
+  }
+  ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+  }
+  getFilePath(key) {
+    const parts = key.split(":");
+    const namespace = parts[3] || "default";
+    const locale = parts[2] || "unknown";
+    const entryKey = parts[4] || key;
+    const localeDir = join(this.dir, locale);
+    this.ensureDir(localeDir);
+    return {
+      filePath: join(localeDir, `${namespace}.json`),
+      entryKey
+    };
+  }
+  readCacheFile(filePath) {
+    if (!existsSync(filePath)) {
+      return { version: "1.0", entries: {} };
+    }
+    try {
+      const raw = readFileSync(filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return { version: "1.0", entries: {} };
+    }
+  }
+  writeCacheFile(filePath, data) {
+    const tmpPath = `${filePath}.tmp`;
+    this.ensureDir(dirname(filePath));
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf-8");
+    renameSync(tmpPath, filePath);
+  }
+  async get(key) {
+    const { filePath, entryKey } = this.getFilePath(key);
+    const cacheFile = this.readCacheFile(filePath);
+    const entry = cacheFile.entries[entryKey];
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+    const ttl = entry.ttl ?? this.defaultTtl;
+    const age = (Date.now() - new Date(entry.translatedAt).getTime()) / 1e3;
+    if (age > ttl) {
+      delete cacheFile.entries[entryKey];
+      this.writeCacheFile(filePath, cacheFile);
+      this.misses++;
+      return null;
+    }
+    this.hits++;
+    return entry.value;
+  }
+  async set(key, value, ttl) {
+    const { filePath, entryKey } = this.getFilePath(key);
+    const cacheFile = this.readCacheFile(filePath);
+    cacheFile.entries[entryKey] = {
+      value,
+      translatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ttl: ttl ?? this.defaultTtl
+    };
+    this.writeCacheFile(filePath, cacheFile);
+  }
+  async delete(key) {
+    const { filePath, entryKey } = this.getFilePath(key);
+    const cacheFile = this.readCacheFile(filePath);
+    if (entryKey in cacheFile.entries) {
+      delete cacheFile.entries[entryKey];
+      this.writeCacheFile(filePath, cacheFile);
+    }
+  }
+  async clear(pattern) {
+    if (!pattern) {
+      this.clearDirectory(this.dir);
+      this.hits = 0;
+      this.misses = 0;
+      return;
+    }
+    const parts = pattern.split(":");
+    const locale = parts[2];
+    if (locale) {
+      const localeDir = join(this.dir, locale);
+      if (existsSync(localeDir)) {
+        this.clearDirectory(localeDir);
+      }
+    }
+  }
+  clearDirectory(dirPath) {
+    if (!existsSync(dirPath)) return;
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        this.clearDirectory(fullPath);
+      } else {
+        unlinkSync(fullPath);
+      }
+    }
+  }
+  async stats() {
+    const total = this.hits + this.misses;
+    let totalEntries = 0;
+    let sizeBytes = 0;
+    let oldest;
+    let newest;
+    this.scanDirectory(this.dir, (filePath) => {
+      try {
+        const stat = statSync(filePath);
+        sizeBytes += stat.size;
+        const cacheFile = this.readCacheFile(filePath);
+        for (const entry of Object.values(cacheFile.entries)) {
+          totalEntries++;
+          const date = new Date(entry.translatedAt);
+          if (!oldest || date < oldest) oldest = date;
+          if (!newest || date > newest) newest = date;
+        }
+      } catch {
+      }
+    });
+    return {
+      totalEntries,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+      missRate: total > 0 ? this.misses / total : 0,
+      sizeBytes,
+      oldestEntry: oldest?.toISOString(),
+      newestEntry: newest?.toISOString()
+    };
+  }
+  scanDirectory(dirPath, callback) {
+    if (!existsSync(dirPath)) return;
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        this.scanDirectory(fullPath, callback);
+      } else if (entry.name.endsWith(".json")) {
+        callback(fullPath);
+      }
+    }
+  }
+};
+
+// src/cache/redis-cache.ts
+var RedisCache = class {
+  client;
+  defaultTtl;
+  hits = 0;
+  misses = 0;
+  connected = false;
+  constructor(redisUrl, defaultTtl = 604800) {
+    this.defaultTtl = defaultTtl;
+    this.initClient(redisUrl);
+  }
+  async initClient(redisUrl) {
+    try {
+      const Redis = await this.loadRedis();
+      const url = redisUrl || process.env.REDIS_URL || "redis://localhost:6379";
+      this.client = new Redis(url, {
+        maxRetriesPerRequest: 3,
+        retryStrategy(times) {
+          if (times > 3) return null;
+          return Math.min(times * 200, 2e3);
+        },
+        lazyConnect: true
+      });
+      await this.client.connect();
+      this.connected = true;
+    } catch (error) {
+      console.warn("[ui18n:warn] Redis connection failed. Cache operations will be no-ops.", error);
+      this.connected = false;
+    }
+  }
+  async loadRedis() {
+    try {
+      const mod = await import("ioredis");
+      return mod.default || mod;
+    } catch {
+      throw new Error(
+        "ioredis is required for Redis cache backend. Install it with: npm install ioredis"
+      );
+    }
+  }
+  async get(key) {
+    if (!this.connected || !this.client) {
+      this.misses++;
+      return null;
+    }
+    try {
+      const value = await this.client.get(key);
+      if (value === null) {
+        this.misses++;
+        return null;
+      }
+      this.hits++;
+      return value;
+    } catch {
+      this.misses++;
+      return null;
+    }
+  }
+  async set(key, value, ttl) {
+    if (!this.connected || !this.client) return;
+    try {
+      const effectiveTtl = ttl ?? this.defaultTtl;
+      await this.client.set(key, value, "EX", effectiveTtl);
+    } catch {
+    }
+  }
+  async delete(key) {
+    if (!this.connected || !this.client) return;
+    try {
+      await this.client.del(key);
+    } catch {
+    }
+  }
+  async clear(pattern) {
+    if (!this.connected || !this.client) return;
+    try {
+      if (!pattern) {
+        const keys = await this.client.keys("ui18n:*");
+        if (keys.length > 0) {
+          await this.client.del(...keys);
+        }
+      } else {
+        const keys = await this.client.keys(pattern);
+        if (keys.length > 0) {
+          await this.client.del(...keys);
+        }
+      }
+      this.hits = 0;
+      this.misses = 0;
+    } catch {
+    }
+  }
+  async stats() {
+    const total = this.hits + this.misses;
+    let totalEntries = 0;
+    if (this.connected && this.client) {
+      try {
+        const keys = await this.client.keys("ui18n:*");
+        totalEntries = keys.length;
+      } catch {
+      }
+    }
+    return {
+      totalEntries,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+      missRate: total > 0 ? this.misses / total : 0
+    };
+  }
+  async disconnect() {
+    if (this.connected && this.client) {
+      await this.client.quit();
+      this.connected = false;
+    }
+  }
+};
+
+// src/cache/index.ts
+function createCache(config) {
+  const backend = config?.backend ?? "fs";
+  const ttl = config?.ttl ?? 604800;
+  switch (backend) {
+    case "memory":
+      return new MemoryCache(config?.memoryMaxEntries ?? 1e3);
+    case "redis":
+      return new RedisCache(config?.redisUrl, ttl);
+    case "fs":
+    default: {
+      const dir = config?.fsDir ?? process.env.UI18N_CACHE_DIR ?? ".cache/universal-i18n";
+      return new FileSystemCache(dir, ttl);
+    }
+  }
+}
+
+// src/utils.ts
+import { createHash } from "crypto";
+function generateCacheKey(sourceLocale, targetLocale, namespace, sourceText) {
+  const hash = createHash("sha256").update(sourceText).digest("hex").slice(0, 16);
+  return `ui18n:${sourceLocale}:${targetLocale}:${namespace}:${hash}`;
+}
+function sha256(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function exponentialBackoff(attempt) {
+  const baseDelay = 1e3;
+  const delay = baseDelay * Math.pow(2, attempt);
+  const jitter = delay * 0.25 * (Math.random() * 2 - 1);
+  return Math.round(delay + jitter);
+}
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+function createLogger(level) {
+  const envLevel = typeof process !== "undefined" && process.env?.UI18N_LOG_LEVEL;
+  const currentLevel = LOG_LEVELS[level ?? envLevel ?? "info"];
+  const shouldLog = (msgLevel) => LOG_LEVELS[msgLevel] >= currentLevel;
+  return {
+    debug(message, ...args) {
+      if (shouldLog("debug")) console.debug(`[ui18n:debug] ${message}`, ...args);
+    },
+    info(message, ...args) {
+      if (shouldLog("info")) console.info(`[ui18n:info] ${message}`, ...args);
+    },
+    warn(message, ...args) {
+      if (shouldLog("warn")) console.warn(`[ui18n:warn] ${message}`, ...args);
+    },
+    error(message, ...args) {
+      if (shouldLog("error")) console.error(`[ui18n:error] ${message}`, ...args);
+    }
+  };
+}
+function flattenObject(obj, prefix = "") {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      Object.assign(result, flattenObject(value, fullKey));
+    } else {
+      result[fullKey] = String(value);
+    }
+  }
+  return result;
+}
+function unflattenObject(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const parts = key.split(".");
+    let current = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (!(part in current) || typeof current[part] !== "object") {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+  }
+  return result;
+}
+
+// src/engine.ts
+var UniversalI18nEngine = class {
+  cache;
+  logger;
+  apiKey;
+  sourceLocale;
+  targetLocales;
+  batchDelayMs;
+  maxRetries;
+  fallbackOnError;
+  provider;
+  providerApiKey;
+  model;
+  // Batching state
+  pendingBatch = [];
+  batchTimer = null;
+  // SDK engine instance (lazy-loaded)
+  sdkEngine = null;
+  constructor(config) {
+    this.apiKey = config.apiKey || process.env.LINGODOTDEV_API_KEY || "";
+    this.sourceLocale = config.sourceLocale ?? "en";
+    this.targetLocales = config.targetLocales;
+    this.batchDelayMs = config.batchDelayMs ?? 50;
+    this.maxRetries = config.maxRetries ?? 3;
+    this.fallbackOnError = config.fallbackOnError ?? true;
+    this.provider = config.provider ?? "lingo.dev";
+    this.providerApiKey = config.providerApiKey;
+    this.model = config.model;
+    this.cache = createCache(config.cache);
+    this.logger = createLogger();
+  }
+  /**
+   * Initialize the lingo.dev SDK engine lazily.
+   */
+  async getSDKEngine() {
+    if (this.sdkEngine) return this.sdkEngine;
+    try {
+      const sdk = await import("lingo.dev/sdk");
+      const LingoDotDevEngine = sdk.LingoDotDevEngine || sdk.default?.LingoDotDevEngine;
+      if (!LingoDotDevEngine) {
+        throw new Error("LingoDotDevEngine not found in lingo.dev package");
+      }
+      this.sdkEngine = new LingoDotDevEngine({
+        apiKey: this.apiKey
+      });
+      return this.sdkEngine;
+    } catch (error) {
+      this.logger.error("Failed to initialize lingo.dev SDK", error);
+      throw new TranslationError(
+        "Failed to initialize translation engine. Ensure lingo.dev is installed.",
+        void 0,
+        void 0,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Translate a single string with cache-first strategy.
+   */
+  async translate(text, opts) {
+    const namespace = opts.namespace ?? "default";
+    const cacheKey = generateCacheKey(opts.sourceLocale, opts.targetLocale, namespace, text);
+    try {
+      const cached = await this.cache.get(cacheKey);
+      if (cached !== null) {
+        this.logger.debug(`Cache hit for key: ${cacheKey}`);
+        return cached;
+      }
+    } catch (error) {
+      this.logger.warn("Cache read failed, proceeding with API call", error);
+    }
+    const translated = await this.translateWithRetry(text, opts);
+    try {
+      await this.cache.set(cacheKey, translated);
+    } catch (error) {
+      this.logger.warn("Cache write failed", error);
+    }
+    return translated;
+  }
+  /**
+   * Translate a nested object (all string values) with cache.
+   */
+  async translateObject(obj, opts) {
+    const flat = flattenObject(obj);
+    const translatedFlat = {};
+    const entries = Object.entries(flat);
+    const translations = await Promise.all(
+      entries.map(([, value]) => this.translate(value, opts))
+    );
+    entries.forEach(([key], idx) => {
+      translatedFlat[key] = translations[idx];
+    });
+    return unflattenObject(translatedFlat);
+  }
+  /**
+   * Translate an HTML string.
+   */
+  async translateHTML(html, opts) {
+    const namespace = opts.namespace ?? "html";
+    const cacheKey = generateCacheKey(opts.sourceLocale, opts.targetLocale, namespace, html);
+    try {
+      const cached = await this.cache.get(cacheKey);
+      if (cached !== null) return cached;
+    } catch {
+    }
+    try {
+      const engine = await this.getSDKEngine();
+      const translated = await this.callWithRetry(async () => {
+        return await engine.translateHtml(html, {
+          sourceLocale: opts.sourceLocale,
+          targetLocale: opts.targetLocale
+        });
+      });
+      await this.cache.set(cacheKey, translated).catch(() => {
+      });
+      return translated;
+    } catch (error) {
+      if (this.fallbackOnError) {
+        this.logger.warn("HTML translation failed, returning original", error);
+        return html;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Translate multiple items, leveraging batching and caching.
+   */
+  async translateBatch(items, opts) {
+    const results = [];
+    for (const item of items) {
+      const namespace = opts.namespace ?? "default";
+      const cacheKey = generateCacheKey(opts.sourceLocale, opts.targetLocale, namespace, item.text);
+      let cached = false;
+      let translated = item.text;
+      try {
+        const cachedValue = await this.cache.get(cacheKey);
+        if (cachedValue !== null) {
+          translated = cachedValue;
+          cached = true;
+        }
+      } catch {
+      }
+      if (!cached) {
+        try {
+          translated = await this.translateWithRetry(item.text, opts);
+          await this.cache.set(cacheKey, translated).catch(() => {
+          });
+        } catch {
+          if (!this.fallbackOnError) {
+            throw new TranslationError(
+              `Batch translation failed for item: ${item.id ?? item.text.slice(0, 50)}`
+            );
+          }
+        }
+      }
+      results.push({
+        id: item.id,
+        original: item.text,
+        translated,
+        cached
+      });
+    }
+    return results;
+  }
+  /**
+   * Get current cache statistics.
+   */
+  getCacheStats() {
+    return this.cache.stats();
+  }
+  /**
+   * Clear the cache, optionally for a specific locale.
+   */
+  async clearCache(locale) {
+    if (locale) {
+      await this.cache.clear(`ui18n:*:${locale}:*`);
+    } else {
+      await this.cache.clear();
+    }
+    this.logger.info(`Cache cleared${locale ? ` for locale: ${locale}` : ""}`);
+  }
+  /**
+   * Pre-populate cache by translating all provided keys for specified locales.
+   */
+  async warmCache(keys, locales) {
+    this.logger.info(`Warming cache: ${keys.length} keys \xD7 ${locales.length} locales`);
+    for (const locale of locales) {
+      for (const key of keys) {
+        await this.translate(key, {
+          sourceLocale: this.sourceLocale,
+          targetLocale: locale,
+          namespace: "warm"
+        });
+      }
+    }
+    this.logger.info("Cache warming complete");
+  }
+  /**
+   * Translate with automatic retry and exponential backoff.
+   */
+  async translateWithRetry(text, opts) {
+    return this.callWithRetry(async () => {
+      const engine = await this.getSDKEngine();
+      const result = await engine.translateText(text, {
+        sourceLocale: opts.sourceLocale,
+        targetLocale: opts.targetLocale
+      });
+      return result;
+    }, text, opts.targetLocale);
+  }
+  /**
+   * Generic retry wrapper with exponential backoff.
+   */
+  async callWithRetry(fn, sourceText, targetLocale) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        this.logger.warn(
+          `Translation attempt ${attempt + 1}/${this.maxRetries + 1} failed`,
+          lastError.message
+        );
+        if (lastError.message.includes("429") || lastError.message.toLowerCase().includes("rate limit")) {
+          const retryDelay = exponentialBackoff(attempt + 1);
+          this.logger.info(`Rate limited. Waiting ${retryDelay}ms before retry...`);
+          await sleep(retryDelay);
+          continue;
+        }
+        if (attempt < this.maxRetries) {
+          const delay = exponentialBackoff(attempt);
+          await sleep(delay);
+        }
+      }
+    }
+    if (this.fallbackOnError) {
+      this.logger.error("All translation attempts failed, returning original text");
+      return sourceText ?? "";
+    }
+    throw new TranslationError(
+      `Translation failed after ${this.maxRetries + 1} attempts`,
+      sourceText,
+      targetLocale,
+      lastError
+    );
+  }
+};
+
+// src/index.ts
+function createEngine(config) {
+  return new UniversalI18nEngine(config);
+}
+function defineConfig(config) {
+  return config;
+}
+export {
+  CacheError,
+  ConfigError,
+  FileSystemCache,
+  MemoryCache,
+  RateLimitError,
+  RedisCache,
+  TranslationError,
+  UniversalI18nEngine,
+  createCache,
+  createEngine,
+  createLogger,
+  defineConfig,
+  flattenObject,
+  generateCacheKey,
+  sha256,
+  unflattenObject
+};
+//# sourceMappingURL=index.mjs.map