locai 2.1.1 → 2.1.3

package/dist/utils/ai-context-analyzer.d.ts

@@ -0,0 +1,73 @@
+export interface AnalysisResult {
+    category: string;
+    confidence: number;
+    keywords: string[];
+    explanation: string;
+    prompt: string;
+    method?: string;
+}
+export interface ContextConfig {
+    enabled?: boolean;
+    useAI?: boolean;
+    minTextLength?: number;
+    cacheSize?: number;
+    cacheTTL?: number;
+    categories?: Record<string, any>;
+    detection?: {
+        threshold?: number;
+        minConfidence?: number;
+    };
+    allowNewCategories?: boolean;
+    fallback?: {
+        category?: string;
+        prompt?: string;
+    };
+    analysisOptions?: {
+        maxTokens?: number;
+        timeout?: number;
+        retries?: number;
+    };
+    [key: string]: any;
+}
+export interface Stats {
+    totalAnalyzed: number;
+    aiCalls: number;
+    cacheHits: number;
+    keywordMatches: number;
+    newCategories: number;
+    errors: number;
+}
+declare class AIContextAnalyzer {
+    private config;
+    private cache;
+    private categoryKeywords;
+    private stats;
+    constructor(config: ContextConfig);
+    analyzeBatch(texts: (string | null)[], apiProvider?: string): Promise<(AnalysisResult | null)[]>;
+    analyzeContext(text: string, apiProvider?: string): Promise<AnalysisResult | null>;
+    _batchAIAnalysis(texts: string[], apiProvider: string): Promise<(AnalysisResult | null)[]>;
+    _createBatchAnalysisPrompt(texts: string[]): string;
+    _createAnalysisPrompt(text: string): string;
+    _createSimplifiedAnalysisPrompt(text: string): string;
+    _parseBatchAnalysisResult(result: string, expectedCount: number): (AnalysisResult | null)[];
+    _parseAnalysisResult(result: string): AnalysisResult | null;
+    _fastKeywordMatch(text: string): AnalysisResult | null;
+    _getDefaultContext(): AnalysisResult;
+    _findClosestCategory(suggestedCategory: string, keywords: string[]): string;
+    _saveNewCategory(category: string, keywords: string[]): void;
+    /**
+     * Generate a collision-resistant cache key for text
+     */
+    _getCacheKey(text: string): string;
+    getStats(): Stats & {
+        cacheSize: number;
+        cacheCapacity: number;
+        hitRate: number;
+        aiUsageRate: number;
+        keywordMatchRate: number;
+        errorRate: number;
+    };
+    resetStats(): void;
+    clearCache(): void;
+}
+export default AIContextAnalyzer;

package/dist/utils/confidence-scorer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Quality Confidence Scoring System
+ * Calculates confidence scores for translations based on AI response and quality checks
+ */
+export interface ConfidenceIssue {
+    type: string;
+    severity: "critical" | "warning" | "error";
+    message: string;
+}
+export interface ConfidenceOptions {
+    aiConfidence?: number;
+    sourceText: string;
+    translation: string;
+    sourceLang: string;
+    targetLang: string;
+    provider: string;
+    category?: string;
+}
+export interface ConfidenceResult {
+    score: number;
+    level: "high" | "medium" | "low" | "very_low";
+    aiConfidence: number;
+    qualityScore: number;
+    details: {
+        categoryAdjustment: number;
+        languageFactor: number;
+        providerReliability: number;
+    };
+    issues: ConfidenceIssue[];
+    needsReview: boolean;
+    autoApprove: boolean;
+}
+declare class ConfidenceScorer {
+    /**
+     * Calculate final confidence score
+     * @param {ConfidenceOptions} options
+     * @returns {ConfidenceResult} { score, details, issues }
+     */
+    static calculateConfidence(options: ConfidenceOptions): ConfidenceResult;
+    /**
+     * Calculate quality score based on internal checks
+     */
+    private static _calculateQualityScore;
+    /**
+     * Get category-specific adjustment
+     */
+    private static _getCategoryAdjustment;
+    /**
+     * Get language pair complexity factor
+     */
+    private static _getLanguagePairFactor;
+    /**
+     * Get provider reliability for specific tasks
+     */
+    private static _getProviderReliability;
+    /**
+     * Determine confidence level from score
+     */
+    private static _getConfidenceLevel;
+    /**
+     * Detect specific issues with translation
+     */
+    private static _detectIssues;
+    /**
+     * Get confidence color for terminal display
+     */
+    static getConfidenceColor(score: number): string;
+    /**
+     * Format confidence for display
+     */
+    static formatConfidence(score: number): string;
+    /**
+     * Extract AI confidence from provider response
+     */
+    static extractAIConfidence(response: any, provider: string): number;
+}
+export default ConfidenceScorer;

package/dist/utils/error-helper.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Centralized Error Handling System
+ * Provides detailed, actionable error messages with context and solutions
+ */
+export interface HelperError extends Error {
+    code?: string;
+    type?: string;
+    details?: Record<string, any>;
+    solutions?: string[];
+    context?: string[];
+}
+export interface ErrorDetails {
+    [key: string]: any;
+}
+declare class ErrorHelper {
+    static ErrorCodes: {
+        API_RATE_LIMIT: string;
+        API_AUTH_FAILED: string;
+        API_SERVER_ERROR: string;
+        API_NETWORK: string;
+        API_TIMEOUT: string;
+        API_INVALID_KEY: string;
+        API_QUOTA_EXCEEDED: string;
+        API_RESPONSE_ERROR: string;
+        CONFIG_NOT_FOUND: string;
+        CONFIG_INVALID: string;
+        CONFIG_VALIDATION: string;
+        CONFIG_MISSING_FIELD: string;
+        FILE_NOT_FOUND: string;
+        FILE_READ_ERROR: string;
+        FILE_WRITE_ERROR: string;
+        FILE_PERMISSION: string;
+        VALIDATION_LANGUAGE: string;
+        VALIDATION_TEXT: string;
+        VALIDATION_PROVIDER: string;
+        VALIDATION_CONCURRENCY: string;
+        TRANSLATION_FAILED: string;
+        TRANSLATION_QUALITY: string;
+        TRANSLATION_TIMEOUT: string;
+    };
+    /**
+     * Create a detailed error with context and solutions
+     */
+    static createError(type: string, details?: ErrorDetails): HelperError;
+    /**
+     * Format error for display
+     */
+    static formatError(error: HelperError, options?: {
+        showDebug?: boolean;
+        showSolutions?: boolean;
+        showContext?: boolean;
+    }): string;
+    /**
+     * Get error information based on type
+     */
+    private static _getErrorInfo;
+    /**
+     * Build rate limit message with details
+     */
+    private static _buildRateLimitMessage;
+    /**
+     * Get environment variable name for provider
+     */
+    private static _getEnvKeyName;
+    /**
+     * Get provider console URL
+     */
+    private static _getProviderConsoleUrl;
+    /**
+     * Suggest fallback provider
+     */
+    private static _suggestFallbackProvider;
+    /**
+     * Quick error creators for common cases
+     */
+    static rateLimitError(provider: string, details?: ErrorDetails): HelperError;
+    static authError(provider: string, statusCode?: number | string, apiMessage?: string): HelperError;
+    static serverError(provider: string, statusCode?: number | string, apiMessage?: string): HelperError;
+    static networkError(provider: string): HelperError;
+    static timeoutError(provider: string, timeout?: number): HelperError;
+    static configNotFoundError(): HelperError;
+    static configValidationError(validationErrors: string[]): HelperError;
+    static fileNotFoundError(filePath: string, expectedSource?: string): HelperError;
+    static translationError(key: string, language: string, reason?: string): HelperError;
+    static languageValidationError(langCode: string, field?: string): HelperError;
+}
+export default ErrorHelper;

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

@@ -0,0 +1,129 @@
+export interface FileOptions {
+    atomic?: boolean;
+    createMissingDirs?: boolean;
+    backupFiles?: boolean;
+    backupDir?: string;
+    encoding?: BufferEncoding;
+    jsonIndent?: number;
+    compact?: boolean;
+    indent?: number;
+    format?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    filePath?: string;
+    error?: string;
+    position?: {
+        position: number | null;
+        line: number | null;
+    } | null;
+    key?: string;
+    value?: any;
+}
+/**
+ * FileManager - Modern asynchronous file operations
+ * Handles multiple file formats via Adapter pattern.
+ */
+declare class FileManager {
+    /**
+     * Default options for file operations
+     */
+    static defaultOptions: Required<Omit<FileOptions, "compact" | "indent" | "format">>;
+    private static options;
+    /**
+     * Configure global options for file operations
+     * @param options - File operation options
+     */
+    static configure(options: FileOptions): void;
+    /**
+     * Get current configuration
+     * @returns Current configuration
+     */
+    static getConfig(): FileOptions;
+    /**
+     * Find locale files in the specified directory
+     * @param localesDir - Directory containing locale files
+     * @param sourceLang - Source language code
+     * @returns Array of file paths
+     */
+    static findLocaleFiles(localesDir: string, sourceLang: string): Promise<string[]>;
+    /**
+     * Read structured data file asynchronously (JSON, YAML, etc.)
+     * @param filePath - Path to the file
+     * @param options - Options for reading
+     * @returns Parsed data
+     */
+    static readFile(filePath: string, options?: FileOptions): Promise<any>;
+    /**
+     * Write data to file asynchronously
+     * @param filePath - Path to write the file
+     * @param data - Data to write
+     * @param options - Options for writing
+     * @returns Success status
+     */
+    static writeFile(filePath: string, data: any, options?: FileOptions): Promise<boolean>;
+    static readJSON(filePath: string, options?: FileOptions): Promise<any>;
+    static writeJSON(filePath: string, data: any, options?: FileOptions): Promise<boolean>;
+    /**
+     * Generate a unique temporary file path
+     */
+    static _generateTempFilePath(filePath: string): string;
+    /**
+     * Ensure directory exists
+     */
+    static ensureDir(dir: string): Promise<void>;
+    /**
+     * Scan for locale files
+     */
+    static scanLocaleFiles(localesDir: string, pattern?: RegExp): Promise<string[]>;
+    /**
+     * Get file modification time
+     */
+    static getModifiedTime(filePath: string): Promise<Date>;
+    /**
+     * Check if file exists
+     */
+    static exists(filePath: string): Promise<boolean>;
+    /**
+     * Delete file
+     * @param filePath - Path to the file
+     * @param options - Options for deletion
+     * @returns Success status
+     */
+    static deleteFile(filePath: string, options?: FileOptions): Promise<boolean>;
+    /**
+     * Validate JSON file structure
+     * @param filePath - Path to the JSON file
+     * @returns Validation result
+     */
+    static validateJSONFile(filePath: string): Promise<ValidationResult>;
+    /**
+     * Extract error position from JSON parse error
+     * @param error - JSON parse error
+     * @returns Error position details
+     */
+    static _extractErrorPosition(error: any): {
+        position: number | null;
+        line: number | null;
+    } | null;
+    /**
+     * Validate translation value can be safely added to JSON
+     * @param key - Translation key
+     * @param value - Translation value
+     * @returns Validation result
+     */
+    static validateTranslationValue(key: string, value: any): ValidationResult;
+    /**
+     * List files in a directory
+     * @param dirPath - Directory path
+     * @returns Array of file paths
+     */
+    static listFiles(dirPath: string): Promise<string[]>;
+    /**
+     * Ensure directory exists, create if it doesn't
+     * @param dirPath - Directory path
+     * @returns True if directory exists or was created
+     */
+    static ensureDirectoryExists(dirPath: string): Promise<boolean>;
+}
+export { FileManager };

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;