@universal-i18n/core 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,347 @@
+declare class TranslationError extends Error {
+    readonly sourceText?: string | undefined;
+    readonly targetLocale?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, sourceText?: string | undefined, targetLocale?: string | undefined, cause?: Error | undefined);
+}
+declare class CacheError extends Error {
+    readonly backend?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, backend?: string | undefined, cause?: Error | undefined);
+}
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+declare class RateLimitError extends Error {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+interface CacheEntry {
+    value: string;
+    translatedAt: string;
+    ttl?: number;
+}
+interface CacheStats {
+    totalEntries: number;
+    hitRate: number;
+    missRate: number;
+    hits: number;
+    misses: number;
+    sizeBytes?: number;
+    oldestEntry?: string;
+    newestEntry?: string;
+}
+interface ICache {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    stats(): Promise<CacheStats>;
+}
+interface CacheConfig {
+    /** Cache backend type. Default: 'fs' */
+    backend: 'fs' | 'redis' | 'memory';
+    /** TTL in seconds. Default: 604800 (7 days) */
+    ttl?: number;
+    /** Filesystem cache directory. Default: '.cache/universal-i18n' */
+    fsDir?: string;
+    /** Redis connection URL */
+    redisUrl?: string;
+    /** Max entries for in-memory LRU cache. Default: 1000 */
+    memoryMaxEntries?: number;
+    /** Compress cached values with gzip. Default: false */
+    compression?: boolean;
+}
+type ProviderType = 'lingo.dev' | 'openai' | 'anthropic' | 'groq';
+interface EngineConfig {
+    /** API key. Falls back to LINGODOTDEV_API_KEY env var */
+    apiKey?: string;
+    /** Source locale. Default: 'en' */
+    sourceLocale?: string;
+    /** Target locales to support */
+    targetLocales: string[];
+    /** Cache config */
+    cache?: CacheConfig;
+    /** Batch delay in ms before sending batched requests. Default: 50 */
+    batchDelayMs?: number;
+    /** Max retries on failure. Default: 3 */
+    maxRetries?: number;
+    /** Return original text on translation failure. Default: true */
+    fallbackOnError?: boolean;
+    /** Translation provider. Default: 'lingo.dev' */
+    provider?: ProviderType;
+    /** API key for non-lingo.dev providers */
+    providerApiKey?: string;
+    /** Model identifier for the chosen provider */
+    model?: string;
+}
+interface TranslateOpts {
+    /** Source locale */
+    sourceLocale: string;
+    /** Target locale */
+    targetLocale: string;
+    /** Additional context hint for the LLM */
+    context?: string;
+    /** Namespace used as cache key prefix */
+    namespace?: string;
+}
+interface BatchItem {
+    text: string;
+    id?: string;
+}
+interface BatchResult {
+    id?: string;
+    original: string;
+    translated: string;
+    cached: boolean;
+}
+interface GlossaryEntry {
+    [locale: string]: string;
+}
+interface BucketConfig {
+    include: string[];
+}
+interface UniversalI18nConfig {
+    /** Source locale. Default: 'en' */
+    sourceLocale: string;
+    /** Target locales */
+    targetLocales: string[];
+    /** Directory for locale JSON files. Default: './locales' */
+    localesDir?: string;
+    /** Cache configuration */
+    cache?: CacheConfig;
+    /** Translation provider config */
+    provider?: {
+        id: ProviderType;
+        apiKey?: string;
+        model?: string;
+    };
+    /** Brand glossary: terms that should never or always be translated a specific way */
+    glossary?: Record<string, GlossaryEntry>;
+    /** Namespace buckets mapping to lingo.dev buckets config */
+    buckets?: Record<string, BucketConfig>;
+    /** Lifecycle hooks */
+    hooks?: {
+        beforeTranslate?: (text: string, locale: string) => Promise<string>;
+        afterTranslate?: (text: string, locale: string) => Promise<string>;
+    };
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+interface I18nMessages {
+    [locale: string]: Record<string, string | Record<string, unknown>>;
+}
+interface I18nContextValue {
+    locale: string;
+    setLocale: (locale: string) => void;
+    messages: I18nMessages;
+    t: (key: string, vars?: Record<string, string>) => string;
+    availableLocales: string[];
+    isLoading: boolean;
+    fallbackLocale?: string;
+    onMissingKey?: (key: string, locale: string) => void;
+}
+
+/**
+ * Core translation engine wrapping LingoDotDevEngine with:
+ * - Cache-first strategy
+ * - Request batching (configurable delay)
+ * - Automatic retry with exponential backoff
+ * - Graceful fallback on errors
+ */
+declare class UniversalI18nEngine {
+    private cache;
+    private logger;
+    private apiKey;
+    private sourceLocale;
+    private targetLocales;
+    private batchDelayMs;
+    private maxRetries;
+    private fallbackOnError;
+    private provider;
+    private providerApiKey?;
+    private model?;
+    private pendingBatch;
+    private batchTimer;
+    private sdkEngine;
+    constructor(config: EngineConfig);
+    /**
+     * Initialize the lingo.dev SDK engine lazily.
+     */
+    private getSDKEngine;
+    /**
+     * Translate a single string with cache-first strategy.
+     */
+    translate(text: string, opts: TranslateOpts): Promise<string>;
+    /**
+     * Translate a nested object (all string values) with cache.
+     */
+    translateObject<T extends Record<string, unknown>>(obj: T, opts: TranslateOpts): Promise<T>;
+    /**
+     * Translate an HTML string.
+     */
+    translateHTML(html: string, opts: TranslateOpts): Promise<string>;
+    /**
+     * Translate multiple items, leveraging batching and caching.
+     */
+    translateBatch(items: BatchItem[], opts: TranslateOpts): Promise<BatchResult[]>;
+    /**
+     * Get current cache statistics.
+     */
+    getCacheStats(): Promise<CacheStats>;
+    /**
+     * Clear the cache, optionally for a specific locale.
+     */
+    clearCache(locale?: string): Promise<void>;
+    /**
+     * Pre-populate cache by translating all provided keys for specified locales.
+     */
+    warmCache(keys: string[], locales: string[]): Promise<void>;
+    /**
+     * Translate with automatic retry and exponential backoff.
+     */
+    private translateWithRetry;
+    /**
+     * Generic retry wrapper with exponential backoff.
+     */
+    private callWithRetry;
+}
+
+/**
+ * In-memory LRU cache with optional TTL support.
+ * Ideal for edge/serverless environments where filesystem isn't persistent.
+ */
+declare class MemoryCache implements ICache {
+    private cache;
+    private maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    stats(): Promise<CacheStats>;
+}
+
+/**
+ * Filesystem-based cache that stores translations as JSON files.
+ * Uses atomic writes (write to .tmp then rename) for safety.
+ * Cache structure: {fsDir}/{namespace}.json
+ */
+declare class FileSystemCache implements ICache {
+    private dir;
+    private hits;
+    private misses;
+    private defaultTtl;
+    constructor(dir?: string, defaultTtl?: number);
+    private ensureDir;
+    private getFilePath;
+    private readCacheFile;
+    private writeCacheFile;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    private clearDirectory;
+    stats(): Promise<CacheStats>;
+    private scanDirectory;
+}
+
+/**
+ * Redis-based cache using ioredis.
+ * ioredis is a peer dependency — this module gracefully handles missing imports.
+ *
+ * Uses HSET/HGET with key pattern: ui18n:{srcLocale}:{tgtLocale}:{namespace}:{hash}
+ * TTL via EXPIRE on individual keys.
+ */
+declare class RedisCache implements ICache {
+    private client;
+    private defaultTtl;
+    private hits;
+    private misses;
+    private connected;
+    constructor(redisUrl?: string, defaultTtl?: number);
+    private initClient;
+    private loadRedis;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    stats(): Promise<CacheStats>;
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Factory function to create a cache instance based on configuration.
+ */
+declare function createCache(config?: CacheConfig): ICache;
+
+/**
+ * Generate a cache key from translation parameters.
+ * Format: ui18n:{sourceLocale}:{targetLocale}:{namespace}:{sha256(sourceText)}
+ */
+declare function generateCacheKey(sourceLocale: string, targetLocale: string, namespace: string, sourceText: string): string;
+/**
+ * Compute a SHA-256 hash of a string, returning a hex digest.
+ */
+declare function sha256(text: string): string;
+/**
+ * Create a pluggable logger respecting UI18N_LOG_LEVEL env var.
+ */
+declare function createLogger(level?: LogLevel): Logger;
+/**
+ * Flatten a nested object into dot-notation keys.
+ * { a: { b: 'c' } } => { 'a.b': 'c' }
+ */
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, string>;
+/**
+ * Unflatten dot-notation keys back into a nested object.
+ * { 'a.b': 'c' } => { a: { b: 'c' } }
+ */
+declare function unflattenObject(obj: Record<string, string>): Record<string, unknown>;
+
+/**
+ * Create a new translation engine instance.
+ *
+ * @example
+ * ```ts
+ * import { createEngine } from '@universal-i18n/core'
+ *
+ * const engine = createEngine({
+ *   apiKey: process.env.LINGODOTDEV_API_KEY,
+ *   sourceLocale: 'en',
+ *   targetLocales: ['es', 'fr'],
+ *   cache: { backend: 'fs' }
+ * })
+ *
+ * const translated = await engine.translate('Hello', {
+ *   sourceLocale: 'en',
+ *   targetLocale: 'es'
+ * })
+ * ```
+ */
+declare function createEngine(config: EngineConfig): UniversalI18nEngine;
+/**
+ * Define a universal-i18n configuration object with type safety.
+ *
+ * @example
+ * ```ts
+ * // i18n.config.ts
+ * import { defineConfig } from '@universal-i18n/core'
+ *
+ * export default defineConfig({
+ *   sourceLocale: 'en',
+ *   targetLocales: ['es', 'fr', 'de'],
+ *   cache: { backend: 'fs', ttl: 604800 }
+ * })
+ * ```
+ */
+declare function defineConfig(config: UniversalI18nConfig): UniversalI18nConfig;
+
+export { type BatchItem, type BatchResult, type BucketConfig, type CacheConfig, type CacheEntry, CacheError, type CacheStats, ConfigError, type EngineConfig, FileSystemCache, type GlossaryEntry, type I18nContextValue, type I18nMessages, type ICache, type LogLevel, type Logger, MemoryCache, type ProviderType, RateLimitError, RedisCache, type TranslateOpts, TranslationError, type UniversalI18nConfig, UniversalI18nEngine, createCache, createEngine, createLogger, defineConfig, flattenObject, generateCacheKey, sha256, unflattenObject };

package/dist/index.d.ts

@@ -0,0 +1,347 @@
+declare class TranslationError extends Error {
+    readonly sourceText?: string | undefined;
+    readonly targetLocale?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, sourceText?: string | undefined, targetLocale?: string | undefined, cause?: Error | undefined);
+}
+declare class CacheError extends Error {
+    readonly backend?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, backend?: string | undefined, cause?: Error | undefined);
+}
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+declare class RateLimitError extends Error {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+interface CacheEntry {
+    value: string;
+    translatedAt: string;
+    ttl?: number;
+}
+interface CacheStats {
+    totalEntries: number;
+    hitRate: number;
+    missRate: number;
+    hits: number;
+    misses: number;
+    sizeBytes?: number;
+    oldestEntry?: string;
+    newestEntry?: string;
+}
+interface ICache {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    stats(): Promise<CacheStats>;
+}
+interface CacheConfig {
+    /** Cache backend type. Default: 'fs' */
+    backend: 'fs' | 'redis' | 'memory';
+    /** TTL in seconds. Default: 604800 (7 days) */
+    ttl?: number;
+    /** Filesystem cache directory. Default: '.cache/universal-i18n' */
+    fsDir?: string;
+    /** Redis connection URL */
+    redisUrl?: string;
+    /** Max entries for in-memory LRU cache. Default: 1000 */
+    memoryMaxEntries?: number;
+    /** Compress cached values with gzip. Default: false */
+    compression?: boolean;
+}
+type ProviderType = 'lingo.dev' | 'openai' | 'anthropic' | 'groq';
+interface EngineConfig {
+    /** API key. Falls back to LINGODOTDEV_API_KEY env var */
+    apiKey?: string;
+    /** Source locale. Default: 'en' */
+    sourceLocale?: string;
+    /** Target locales to support */
+    targetLocales: string[];
+    /** Cache config */
+    cache?: CacheConfig;
+    /** Batch delay in ms before sending batched requests. Default: 50 */
+    batchDelayMs?: number;
+    /** Max retries on failure. Default: 3 */
+    maxRetries?: number;
+    /** Return original text on translation failure. Default: true */
+    fallbackOnError?: boolean;
+    /** Translation provider. Default: 'lingo.dev' */
+    provider?: ProviderType;
+    /** API key for non-lingo.dev providers */
+    providerApiKey?: string;
+    /** Model identifier for the chosen provider */
+    model?: string;
+}
+interface TranslateOpts {
+    /** Source locale */
+    sourceLocale: string;
+    /** Target locale */
+    targetLocale: string;
+    /** Additional context hint for the LLM */
+    context?: string;
+    /** Namespace used as cache key prefix */
+    namespace?: string;
+}
+interface BatchItem {
+    text: string;
+    id?: string;
+}
+interface BatchResult {
+    id?: string;
+    original: string;
+    translated: string;
+    cached: boolean;
+}
+interface GlossaryEntry {
+    [locale: string]: string;
+}
+interface BucketConfig {
+    include: string[];
+}
+interface UniversalI18nConfig {
+    /** Source locale. Default: 'en' */
+    sourceLocale: string;
+    /** Target locales */
+    targetLocales: string[];
+    /** Directory for locale JSON files. Default: './locales' */
+    localesDir?: string;
+    /** Cache configuration */
+    cache?: CacheConfig;
+    /** Translation provider config */
+    provider?: {
+        id: ProviderType;
+        apiKey?: string;
+        model?: string;
+    };
+    /** Brand glossary: terms that should never or always be translated a specific way */
+    glossary?: Record<string, GlossaryEntry>;
+    /** Namespace buckets mapping to lingo.dev buckets config */
+    buckets?: Record<string, BucketConfig>;
+    /** Lifecycle hooks */
+    hooks?: {
+        beforeTranslate?: (text: string, locale: string) => Promise<string>;
+        afterTranslate?: (text: string, locale: string) => Promise<string>;
+    };
+}
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+interface I18nMessages {
+    [locale: string]: Record<string, string | Record<string, unknown>>;
+}
+interface I18nContextValue {
+    locale: string;
+    setLocale: (locale: string) => void;
+    messages: I18nMessages;
+    t: (key: string, vars?: Record<string, string>) => string;
+    availableLocales: string[];
+    isLoading: boolean;
+    fallbackLocale?: string;
+    onMissingKey?: (key: string, locale: string) => void;
+}
+
+/**
+ * Core translation engine wrapping LingoDotDevEngine with:
+ * - Cache-first strategy
+ * - Request batching (configurable delay)
+ * - Automatic retry with exponential backoff
+ * - Graceful fallback on errors
+ */
+declare class UniversalI18nEngine {
+    private cache;
+    private logger;
+    private apiKey;
+    private sourceLocale;
+    private targetLocales;
+    private batchDelayMs;
+    private maxRetries;
+    private fallbackOnError;
+    private provider;
+    private providerApiKey?;
+    private model?;
+    private pendingBatch;
+    private batchTimer;
+    private sdkEngine;
+    constructor(config: EngineConfig);
+    /**
+     * Initialize the lingo.dev SDK engine lazily.
+     */
+    private getSDKEngine;
+    /**
+     * Translate a single string with cache-first strategy.
+     */
+    translate(text: string, opts: TranslateOpts): Promise<string>;
+    /**
+     * Translate a nested object (all string values) with cache.
+     */
+    translateObject<T extends Record<string, unknown>>(obj: T, opts: TranslateOpts): Promise<T>;
+    /**
+     * Translate an HTML string.
+     */
+    translateHTML(html: string, opts: TranslateOpts): Promise<string>;
+    /**
+     * Translate multiple items, leveraging batching and caching.
+     */
+    translateBatch(items: BatchItem[], opts: TranslateOpts): Promise<BatchResult[]>;
+    /**
+     * Get current cache statistics.
+     */
+    getCacheStats(): Promise<CacheStats>;
+    /**
+     * Clear the cache, optionally for a specific locale.
+     */
+    clearCache(locale?: string): Promise<void>;
+    /**
+     * Pre-populate cache by translating all provided keys for specified locales.
+     */
+    warmCache(keys: string[], locales: string[]): Promise<void>;
+    /**
+     * Translate with automatic retry and exponential backoff.
+     */
+    private translateWithRetry;
+    /**
+     * Generic retry wrapper with exponential backoff.
+     */
+    private callWithRetry;
+}
+
+/**
+ * In-memory LRU cache with optional TTL support.
+ * Ideal for edge/serverless environments where filesystem isn't persistent.
+ */
+declare class MemoryCache implements ICache {
+    private cache;
+    private maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    stats(): Promise<CacheStats>;
+}
+
+/**
+ * Filesystem-based cache that stores translations as JSON files.
+ * Uses atomic writes (write to .tmp then rename) for safety.
+ * Cache structure: {fsDir}/{namespace}.json
+ */
+declare class FileSystemCache implements ICache {
+    private dir;
+    private hits;
+    private misses;
+    private defaultTtl;
+    constructor(dir?: string, defaultTtl?: number);
+    private ensureDir;
+    private getFilePath;
+    private readCacheFile;
+    private writeCacheFile;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    private clearDirectory;
+    stats(): Promise<CacheStats>;
+    private scanDirectory;
+}
+
+/**
+ * Redis-based cache using ioredis.
+ * ioredis is a peer dependency — this module gracefully handles missing imports.
+ *
+ * Uses HSET/HGET with key pattern: ui18n:{srcLocale}:{tgtLocale}:{namespace}:{hash}
+ * TTL via EXPIRE on individual keys.
+ */
+declare class RedisCache implements ICache {
+    private client;
+    private defaultTtl;
+    private hits;
+    private misses;
+    private connected;
+    constructor(redisUrl?: string, defaultTtl?: number);
+    private initClient;
+    private loadRedis;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(pattern?: string): Promise<void>;
+    stats(): Promise<CacheStats>;
+    disconnect(): Promise<void>;
+}
+
+/**
+ * Factory function to create a cache instance based on configuration.
+ */
+declare function createCache(config?: CacheConfig): ICache;
+
+/**
+ * Generate a cache key from translation parameters.
+ * Format: ui18n:{sourceLocale}:{targetLocale}:{namespace}:{sha256(sourceText)}
+ */
+declare function generateCacheKey(sourceLocale: string, targetLocale: string, namespace: string, sourceText: string): string;
+/**
+ * Compute a SHA-256 hash of a string, returning a hex digest.
+ */
+declare function sha256(text: string): string;
+/**
+ * Create a pluggable logger respecting UI18N_LOG_LEVEL env var.
+ */
+declare function createLogger(level?: LogLevel): Logger;
+/**
+ * Flatten a nested object into dot-notation keys.
+ * { a: { b: 'c' } } => { 'a.b': 'c' }
+ */
+declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, string>;
+/**
+ * Unflatten dot-notation keys back into a nested object.
+ * { 'a.b': 'c' } => { a: { b: 'c' } }
+ */
+declare function unflattenObject(obj: Record<string, string>): Record<string, unknown>;
+
+/**
+ * Create a new translation engine instance.
+ *
+ * @example
+ * ```ts
+ * import { createEngine } from '@universal-i18n/core'
+ *
+ * const engine = createEngine({
+ *   apiKey: process.env.LINGODOTDEV_API_KEY,
+ *   sourceLocale: 'en',
+ *   targetLocales: ['es', 'fr'],
+ *   cache: { backend: 'fs' }
+ * })
+ *
+ * const translated = await engine.translate('Hello', {
+ *   sourceLocale: 'en',
+ *   targetLocale: 'es'
+ * })
+ * ```
+ */
+declare function createEngine(config: EngineConfig): UniversalI18nEngine;
+/**
+ * Define a universal-i18n configuration object with type safety.
+ *
+ * @example
+ * ```ts
+ * // i18n.config.ts
+ * import { defineConfig } from '@universal-i18n/core'
+ *
+ * export default defineConfig({
+ *   sourceLocale: 'en',
+ *   targetLocales: ['es', 'fr', 'de'],
+ *   cache: { backend: 'fs', ttl: 604800 }
+ * })
+ * ```
+ */
+declare function defineConfig(config: UniversalI18nConfig): UniversalI18nConfig;
+
+export { type BatchItem, type BatchResult, type BucketConfig, type CacheConfig, type CacheEntry, CacheError, type CacheStats, ConfigError, type EngineConfig, FileSystemCache, type GlossaryEntry, type I18nContextValue, type I18nMessages, type ICache, type LogLevel, type Logger, MemoryCache, type ProviderType, RateLimitError, RedisCache, type TranslateOpts, TranslationError, type UniversalI18nConfig, UniversalI18nEngine, createCache, createEngine, createLogger, defineConfig, flattenObject, generateCacheKey, sha256, unflattenObject };