locai 2.1.2 → 2.2.0

package/dist/utils/glossary-manager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Glossary Manager
+ * Manages brand terminology and ensures consistent translations
+ */
+export interface GlossaryEntry {
+    term: string;
+    translation: string;
+    caseSensitive?: boolean;
+    languages?: string[];
+}
+export interface ProtectedTerm {
+    original: string;
+    translation: string;
+    term: string;
+}
+export interface GlossaryConfig {
+    glossary?: Record<string, string | Partial<GlossaryEntry> | Record<string, string>>;
+    enabled?: boolean;
+    caseSensitive?: boolean;
+    preserveFormatting?: boolean;
+}
+declare class GlossaryManager {
+    private glossary;
+    enabled: boolean;
+    private caseSensitive;
+    private preserveFormatting;
+    constructor(config?: GlossaryConfig);
+    /**
+     * Apply glossary terms to source text before translation
+     * Replaces terms with protected tokens to preserve them
+     */
+    protectTerms(text: string, sourceLang: string, targetLang: string): {
+        protectedText: string;
+        termMap: Map<string, ProtectedTerm>;
+    };
+    /**
+     * Restore protected terms in translated text
+     */
+    restoreTerms(translatedText: string, termMap: Map<string, ProtectedTerm>): string;
+    /**
+     * Get applicable glossary entries for language pair
+     */
+    getApplicableEntries(sourceLang: string, targetLang: string): GlossaryEntry[];
+    /**
+     * Match formatting (capitalization) from original to translation
+     */
+    matchFormatting(original: string, translation: string): string;
+    /**
+     * Escape special regex characters
+     */
+    escapeRegex(string: string): string;
+    /**
+     * Validate glossary configuration
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Get statistics about glossary
+     */
+    getStats(): any;
+    /**
+     * Load glossary from file
+     */
+    static loadFromFile(filePath: string): Promise<GlossaryManager>;
+}
+export default GlossaryManager;

package/dist/utils/graceful-shutdown.d.ts

@@ -0,0 +1,22 @@
+export type ShutdownCallback = () => Promise<void> | void;
+export interface ShutdownOptions {
+    shutdownTimeout?: number;
+    waitForPending?: boolean;
+    logger?: Console | any;
+}
+declare class GracefulShutdown {
+    private options;
+    private isShuttingDown;
+    private shutdownCallbacks;
+    private logger;
+    constructor(options?: ShutdownOptions);
+    registerCallback(callback: ShutdownCallback): void;
+    unregisterCallback(callback: ShutdownCallback): void;
+    init(): void;
+    handleSignal(signal: string): Promise<void>;
+    shutdown(exitCode?: number): Promise<void>;
+    performShutdown(): Promise<void>;
+    waitForPendingOperations(): Promise<void>;
+}
+declare const gracefulShutdown: GracefulShutdown;
+export default gracefulShutdown;

package/dist/utils/input-validator.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Input validation utility for security and data integrity.
+ * Defines regex patterns, limits, and validation methods.
+ */
+export interface ApiProviderConfig {
+    temperature?: number;
+    maxTokens?: number;
+    [key: string]: any;
+}
+export interface RateLimiterProviderLimit {
+    rpm?: number;
+    concurrency?: number;
+}
+export interface RateLimiterConfig {
+    queueStrategy?: "fifo" | "priority";
+    queueTimeout?: number;
+    providerLimits?: Record<string, RateLimiterProviderLimit>;
+}
+export interface RetryOptions {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+}
+export interface ContextConfig {
+    aiProvider?: string;
+    minTextLength?: number;
+    detection?: {
+        threshold?: number;
+        minConfidence?: number;
+    };
+    categories?: Record<string, any>;
+}
+export interface QualityChecksConfig {
+    rules?: Record<string, any>;
+    enabled?: boolean;
+    autoFix?: boolean;
+}
+export interface LengthControlConfig {
+    mode?: "strict" | "flexible" | "exact" | "relaxed" | "smart";
+    rules?: Record<string, any>;
+}
+export interface AdvancedConfig {
+    timeoutMs?: number;
+    maxKeyLength?: number;
+    maxBatchSize?: number;
+}
+export interface AppConfig {
+    source: string;
+    targets: string[];
+    localesDir: string;
+    apiProvider?: string;
+    fallbackOrder?: string[];
+    concurrencyLimit?: number;
+    cacheSize?: number;
+    cacheTTL?: number;
+    apiConfig?: Record<string, ApiProviderConfig>;
+    rateLimiter?: RateLimiterConfig;
+    retryOptions?: RetryOptions;
+    context?: ContextConfig;
+    qualityChecks?: QualityChecksConfig;
+    lengthControl?: LengthControlConfig;
+    advanced?: AdvancedConfig;
+    fileOperations?: Record<string, any>;
+    debug?: boolean;
+    verbose?: boolean;
+    [key: string]: any;
+}
+declare class InputValidator {
+    static LANGUAGE_CODE_PATTERN: RegExp;
+    static VALID_PROVIDERS: string[];
+    static MAX_TEXT_LENGTH: number;
+    static MAX_KEY_LENGTH: number;
+    static MAX_PATH_LENGTH: number;
+    static MAX_CONFIG_DEPTH: number;
+    static DANGEROUS_PATTERNS: RegExp[];
+    private static _requestCounts?;
+    /**
+     * Validate and sanitize language code.
+     * @param {string} langCode - Language code to validate.
+     * @param {string} [paramName="language"] - Parameter name for error messages.
+     * @returns {string} - Sanitized language code.
+     * @throws {Error} If validation fails.
+     */
+    static validateLanguageCode(langCode: string, paramName?: string): string;
+    /**
+     * Validate array of language codes.
+     * @param {string[]} langCodes - Array of language codes.
+     * @param {string} [paramName="languages"] - Parameter name for errors.
+     * @returns {string[]} - Sanitized array of language codes.
+     * @throws {Error} If array is empty or contains invalid codes.
+     */
+    static validateLanguageCodes(langCodes: string[], paramName?: string): string[];
+    /**
+     * Validate and sanitize directory path.
+     * @param {string} dirPath - Directory path.
+     * @param {string} [paramName="directory"] - Parameter name for errors.
+     * @returns {string} - Resolved and validated absolute path.
+     * @throws {Error} If path is invalid or outside working directory.
+     */
+    static validateDirectoryPath(dirPath: string, paramName?: string): string;
+    /**
+     * Validate translation text.
+     * @param {string} text - Text to validate.
+     * @param {string} [paramName="text"] - Parameter name for errors.
+     * @returns {string} - Validated text.
+     * @throws {Error} If text is invalid or too long.
+     */
+    static validateText(text: string, paramName?: string): string;
+    /**
+     * Validate translation key.
+     * @param {string} key - Key to validate.
+     * @param {string} [paramName="key"] - Parameter name.
+     * @returns {string} - Validated key.
+     * @throws {Error} If key is invalid, too long, or contains traversal.
+     */
+    static validateKey(key: string, paramName?: string): string;
+    /**
+     * Validate API provider name.
+     * @param {string} provider - Provider name.
+     * @param {string} [fieldName="API provider"] - Parameter name.
+     * @returns {string} - Normalized provider name.
+     * @throws {Error} If provider is unknown.
+     */
+    static validateProvider(provider: string, fieldName?: string): string;
+    /**
+     * Sanitize filename to prevent path traversal.
+     * @param {string} filename - Filename to sanitize.
+     * @param {string|null} [extension=null] - Optional extension to enforce.
+     * @returns {string} - Sanitized filename.
+     * @throws {Error} If filename is invalid.
+     */
+    static sanitizeFilename(filename: string, extension?: string | null): string;
+    /**
+     * Create safe file path within a directory.
+     * @param {string} baseDir - Base directory.
+     * @param {string} filename - Filename.
+     * @returns {string} - Safe full path.
+     * @throws {Error} If path escapes base directory.
+     */
+    static createSafeFilePath(baseDir: string, filename: string): string;
+    /**
+     * Validate configuration object.
+     * @param {any} config - Configuration object to validate.
+     * @returns {AppConfig} - Validated configuration.
+     * @throws {Error} If configuration is invalid.
+     */
+    static validateConfig(config: any): AppConfig;
+    /**
+     * Validate API config for each provider.
+     * @param {Record<string, ApiProviderConfig>} apiConfig - API configuration object.
+     * @param {string[]} errors - Array to push errors to.
+     * @param {string[]} warnings - Array to push warnings to.
+     */
+    static validateApiConfig(apiConfig: Record<string, ApiProviderConfig>, errors: string[], warnings: string[]): void;
+    /**
+     * Validate rate limiter configuration.
+     * @param {RateLimiterConfig} rateLimiter - Rate limiter configuration.
+     * @param {string[]} errors - Array to push errors to.
+     * @param {string[]} warnings - Array to push warnings to.
+     */
+    static validateRateLimiterConfig(rateLimiter: RateLimiterConfig, errors: string[], _warnings: string[]): void;
+    /**
+     * Validate retry options.
+     * @param {RetryOptions} retryOptions - Retry options.
+     * @param {string[]} errors - Array to push errors to.
+     * @param {string[]} warnings - Array to push warnings to.
+     */
+    static validateRetryOptions(retryOptions: RetryOptions, errors: string[], _warnings: string[]): void;
+    /**
+     * Validate context configuration.
+     * @param {ContextConfig} context - Context configuration.
+     * @param {string[]} errors - Array to push errors to.
+     * @param {string[]} warnings - Array to push warnings to.
+     */
+    static validateContextConfig(context: ContextConfig, errors: string[], warnings: string[]): void;
+    /**
+     * Validate quality checks configuration.
+     * @param {QualityChecksConfig} qualityChecks - Quality checks configuration.
+     * @param {string[]} errors - Array to push errors to.
+     * @param {string[]} warnings - Array to push warnings to.
+     */
+    static validateQualityChecks(qualityChecks: QualityChecksConfig, errors: string[], warnings: string[]): void;
+    /**
+     * Validate length control configuration.
+     * @param {LengthControlConfig} lengthControl - Length control configuration.
+     * @param {string[]} errors - Array to push errors to.
+     */
+    static validateLengthControl(lengthControl: LengthControlConfig, errors: string[]): void;
+    /**
+     * Validate advanced configuration.
+     * @param {AdvancedConfig} advanced - Advanced configuration.
+     * @param {string[]} errors - Array to push errors to.
+     */
+    static validateAdvancedConfig(advanced: AdvancedConfig, errors: string[]): void;
+    /**
+     * Sanitize translation text for security.
+     * @param {string | null} text - Text to sanitize.
+     * @returns {string | null} - Sanitized text.
+     */
+    static sanitizeTranslationText(text: string | null): string | null;
+    /**
+     * Validate API key format.
+     * @param {string} apiKey - API key to validate.
+     * @param {string} providerName - Provider name.
+     * @returns {boolean} - True if valid.
+     * @throws {Error} If key is invalid.
+     */
+    static validateApiKeyFormat(apiKey: string, providerName: string): boolean;
+    /**
+     * Validate object depth to prevent circular references and deep nesting.
+     * @param {any} obj - Object to validate.
+     * @param {number} [maxDepth=10] - Maximum depth.
+     * @param {number} [currentDepth=0] - Current depth.
+     * @returns {boolean} - True if valid.
+     * @throws {Error} If depth exceeded.
+     */
+    static validateObjectDepth(obj: any, maxDepth?: number, currentDepth?: number): boolean;
+    /**
+     * Validate request rate for an identifier.
+     * @param {string} identifier - Identifier (e.g., user ID or IP).
+     * @param {number} [maxRequestsPerMinute=60] - Max requests per minute.
+     * @returns {boolean} - True if allowed.
+     * @throws {Error} If rate limit exceeded.
+     */
+    static validateRequestRate(identifier: string, maxRequestsPerMinute?: number): boolean;
+}
+export default InputValidator;

package/dist/utils/input-validator.js

@@ -5,7 +5,14 @@
 import path from "path";
 class InputValidator {
     static LANGUAGE_CODE_PATTERN = /^[a-z]{2}(-[a-z]{2})?$/;
-    static VALID_PROVIDERS = ["dashscope", "xai", "openai", "deepseek", "gemini"];
+    static VALID_PROVIDERS = [
+        "dashscope",
+        "xai",
+        "openai",
+        "deepseek",
+        "gemini",
+        "anthropic",
+    ];
     static MAX_TEXT_LENGTH = 10000;
     static MAX_KEY_LENGTH = 500;
     static MAX_PATH_LENGTH = 1000;

package/dist/utils/logger.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Advanced Logging System.
+ * Implements saveErrorLogs, logDirectory, logRotation, and other logging features.
+ */
+export interface LogRotationConfig {
+    enabled: boolean;
+    maxFiles: number;
+    maxSize: number;
+}
+export interface LoggerConfig {
+    verbose?: boolean;
+    diagnosticsLevel?: "minimal" | "normal" | "detailed";
+    outputFormat?: "pretty" | "json" | "simple";
+    saveErrorLogs?: boolean;
+    logDirectory?: string;
+    includeTimestamps?: boolean;
+    logRotation?: Partial<LogRotationConfig>;
+}
+interface InternalLoggerConfig extends Required<Omit<LoggerConfig, "logRotation">> {
+    logRotation: LogRotationConfig;
+}
+interface LogStats {
+    size: number;
+    sizeFormatted: string;
+    modified: Date | null;
+}
+declare class Logger {
+    config: InternalLoggerConfig;
+    logFiles: Record<string, string>;
+    currentLogSizes: Record<string, number>;
+    private initialized;
+    /**
+     * Create a new Logger instance.
+     * @param config - Logger configuration.
+     */
+    constructor(config?: LoggerConfig);
+    /**
+     * Initialize logger (create directories, check rotation).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Parse size string (e.g., "10MB") to bytes.
+     * @param sizeStr - Size string to parse.
+     */
+    parseSize(sizeStr: any): number;
+    /**
+     * Check and rotate logs if needed.
+     */
+    checkAndRotateLogs(): Promise<void>;
+    /**
+     * Rotate a log file.
+     * @param logPath - Path to the log file.
+     */
+    rotateLog(logPath: string): Promise<void>;
+    /**
+     * Clean up old log files.
+     * @param dir - Directory containing log files.
+     * @param basename - Basename of the log file.
+     */
+    cleanupOldLogs(dir: string, basename: string): Promise<void>;
+    /**
+     * Format log message.
+     * @param level - Log level.
+     * @param message - Log message.
+     * @param data - Additional data to log.
+     */
+    formatMessage(level: string, message: string, data?: any): string;
+    /**
+     * Write to log file.
+     * @param level - Log level.
+     * @param message - Log message.
+     * @param data - Additional data to log.
+     */
+    writeToFile(level: string, message: string, data?: any): Promise<void>;
+    /**
+     * Simple console log with debug awareness.
+     * @param message - Message to log
+     * @param debugOnly - Only log if debug mode is enabled
+     */
+    log(message: string, debugOnly?: boolean): Promise<void>;
+    /**
+     * Log error.
+     * @param message - Error message.
+     * @param data - Additional data.
+     */
+    error(message: string, data?: any): Promise<void>;
+    /**
+     * Log warning.
+     * @param message - Warning message.
+     * @param data - Additional data.
+     */
+    warn(message: string, data?: any): Promise<void>;
+    /**
+     * Log info.
+     * @param message - Info message.
+     * @param data - Additional data.
+     */
+    info(message: string, data?: any): Promise<void>;
+    /**
+     * Log debug.
+     * @param message - Debug message.
+     * @param data - Additional data.
+     */
+    debug(message: string, data?: any): Promise<void>;
+    /**
+     * Log based on diagnostics level.
+     * @param level - Log level.
+     * @param message - Log message.
+     * @param data - Additional data.
+     */
+    diagnostics(level: string, message: string, data?: any): Promise<void>;
+    /**
+     * Get log statistics.
+     * @returns Object containing log stats.
+     */
+    getLogStats(): Promise<Record<string, LogStats>>;
+    /**
+     * Format size to human-readable.
+     * @param bytes - Size in bytes.
+     */
+    formatSize(bytes: number): string;
+    /**
+     * Clear all logs.
+     */
+    clearLogs(): Promise<void>;
+}
+export declare function getLogger(config?: LoggerConfig | null): Logger;
+/**
+ * Quick debug-aware logging helper.
+ * @param message - Message to log.
+ * @param debugOnly - Only log in debug/verbose mode.
+ */
+export declare function log(message: string, debugOnly?: boolean): void;
+export default Logger;

package/dist/utils/object-transformer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Utility class for object manipulation.
+ */
+export interface TransformedObject {
+    [key: string]: any;
+}
+declare class ObjectTransformer {
+    /**
+     * Flatten a nested object into a single-level object with dot notation keys.
+     * @param obj - The object to flatten.
+     * @param prefix - Prefix for keys (used internally).
+     * @param maxDepth - Maximum recursion depth.
+     * @returns Flattened object.
+     */
+    static flatten(obj: TransformedObject, prefix?: string, maxDepth?: number): Record<string, string | number | boolean | null>;
+    /**
+     * Unflatten an object with dot notation keys into a nested object.
+     * @param obj - The flattened object.
+     * @returns Nested object.
+     */
+    static unflatten(obj: Record<string, any>): TransformedObject;
+    /**
+     * Create a deep copy of an object.
+     * @param obj - The object to clone.
+     * @param seen - Internal set to track circular references.
+     * @returns Deep copy of the object.
+     */
+    static deepClone<T>(obj: T, seen?: WeakSet<object>): T;
+    /**
+     * deeply merge two objects.
+     * @param target - The target object.
+     * @param source - The source object.
+     * @param overwriteArrays - Whether to overwrite arrays or merge them.
+     * @returns Merged object.
+     */
+    static mergeObjects(target: TransformedObject, source: TransformedObject, overwriteArrays?: boolean): TransformedObject;
+}
+export default ObjectTransformer;

package/dist/utils/progress-tracker.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Progress tracking for translation operations
+ */
+export interface ProgressOptions {
+    logToConsole?: boolean;
+    logFrequency?: number;
+}
+export interface ProgressStatistics {
+    avgTimePerItem: number;
+    recentAvgTimePerItem?: number;
+    totalTime: number;
+    estimatedTimeRemaining: number;
+    itemsPerSecond: number;
+    percentComplete: number;
+    successRate: number;
+    startTime?: string;
+    estimatedEndTime?: string;
+}
+export interface ProgressStatus {
+    total: number;
+    completed: number;
+    success: number;
+    failed: number;
+    language: string | null;
+    inProgress: boolean;
+    statistics: ProgressStatistics;
+}
+declare class ProgressTracker {
+    private logToConsole;
+    private logFrequency;
+    private _isUpdating;
+    private _pendingUpdates;
+    private _spinnerInterval;
+    private _spinnerIndex;
+    private _spinnerFrames;
+    private total;
+    private completed;
+    private success;
+    private failed;
+    private startTime;
+    private endTime;
+    private lastUpdateTime;
+    private recentOperationTimes;
+    private language;
+    private isCompleted;
+    private statistics;
+    constructor(options?: ProgressOptions);
+    reset(): void;
+    start(total: number, language?: string | null): void;
+    increment(type?: string): void;
+    private _processUpdate;
+    private _ensureDataConsistency;
+    private _processPendingUpdates;
+    private _shouldLog;
+    private _startSpinner;
+    private _stopSpinner;
+    private _renderProgress;
+    private _updateStatistics;
+    private _finalReport;
+    getStatus(): ProgressStatus;
+    setLogToConsole(value: boolean): void;
+}
+export default ProgressTracker;

package/dist/utils/prompt-templates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Prompt template utilities for translation and analysis
+ */
+export interface PromptOptions {
+    mode?: "smart" | "strict" | "flexible" | "exact" | "relaxed";
+    lengthControl?: any;
+    targetLang?: string;
+    detectedContext?: {
+        category?: string;
+        confidence?: number;
+        prompt?: string;
+        existingTranslation?: string;
+        similarTranslation?: {
+            source: string;
+            target: string;
+            similarity: number;
+        };
+    };
+    styleGuide?: {
+        formality?: string;
+        toneOfVoice?: string;
+    };
+    categories?: Record<string, any>;
+    allowNewCategories?: boolean;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Get translation prompt
+ */
+declare const getPrompt: (provider: string, sourceLang: string, targetLang: string, text: string, options?: PromptOptions) => any;
+/**
+ * Get analysis prompt
+ */
+declare const getAnalysisPrompt: (provider: string, text: string, options?: PromptOptions) => any;
+export { getPrompt, getAnalysisPrompt };

package/dist/utils/prompt-templates.js

@@ -236,6 +236,15 @@ Original Text: "${text}"`,
             },
         ],
     }),
+    anthropic: (sourceLang, targetLang, text, options) => ({
+        system: baseTranslationPromptTemplate(sourceLang, targetLang, text, options),
+        messages: [
+            {
+                role: "user",
+                content: text,
+            },
+        ],
+    }),
     deepseek: (sourceLang, targetLang, text, options) => ({
         messages: [
             {
@@ -317,6 +326,15 @@ const analysisPrompts = {
             max_tokens: options.maxTokens || 1000,
         },
     }),
+    anthropic: (text, options) => ({
+        system: "You are a context analysis assistant that helps identify the category and context of text.",
+        messages: [
+            {
+                role: "user",
+                content: baseAnalysisPromptTemplate(text, options),
+            },
+        ],
+    }),
     deepseek: (text, options) => ({
         messages: [
             {

package/dist/utils/quality/__tests__/tone-verifier.test.d.ts

@@ -0,0 +1 @@
+export {};