locai 2.6.1 → 2.7.0

package/dist/core/adapters/po-adapter.js

@@ -4,7 +4,6 @@ import gettextParser from "gettext-parser";
  */
 export class PoAdapter {
     extensions = [".po", ".pot"];
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async parse(content) {
         try {
             const po = gettextParser.po.parse(content);
@@ -22,11 +21,10 @@ export class PoAdapter {
             return result;
         }
         catch (error) {
-            throw new Error(`PO parse error: ${error.message}`);
+            throw new Error(`PO parse error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async serialize(data, options = {}) {
+    async serialize(data) {
         const translations = {
             "": {},
         };
@@ -34,7 +32,8 @@ export class PoAdapter {
         for (const [key, value] of Object.entries(data)) {
             translations[""][key] = {
                 msgid: key,
-                msgstr: [value],
+                // gettext-parser writes falsy msgstr values as "" and stringifies the rest
+                msgstr: [value ? String(value) : ""],
             };
         }
         return gettextParser.po

package/dist/core/adapters/properties-adapter.d.ts

@@ -1,9 +1,10 @@
+import type { TranslationObject } from "../../utils/object-transformer.js";
 import { FileFormatAdapter } from "./base-adapter.js";
 /**
  * Adapter for Java .properties files
  */
 export declare class PropertiesAdapter implements FileFormatAdapter {
     extensions: string[];
-    parse(content: string): Promise<Record<string, any>>;
-    serialize(data: Record<string, any>, options?: any): Promise<string>;
+    parse(content: string): Promise<TranslationObject>;
+    serialize(data: TranslationObject): Promise<string>;
 }

package/dist/core/adapters/properties-adapter.js

@@ -4,17 +4,15 @@ import dotProperties from "dot-properties";
  */
 export class PropertiesAdapter {
     extensions = [".properties"];
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async parse(content) {
         try {
             return dotProperties.parse(content);
         }
         catch (error) {
-            throw new Error(`Properties parse error: ${error.message}`);
+            throw new Error(`Properties parse error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async serialize(data, options = {}) {
+    async serialize(data) {
         // dot-properties doesn't have a standardized stringify, simple implementation
         // or used a different library, but let's do a simple one for now or use the lib if it supports it.
         // Checking docs: dot-properties is mostly a parser. 'properties' npm package is better for writing but we installed dot-properties.

package/dist/core/adapters/yaml-adapter.d.ts

@@ -1,9 +1,10 @@
-import { FileFormatAdapter } from "./base-adapter.js";
+import type { TranslationObject } from "../../utils/object-transformer.js";
+import { FileFormatAdapter, SerializeOptions } from "./base-adapter.js";
 /**
  * Adapter for YAML files
  */
 export declare class YamlAdapter implements FileFormatAdapter {
     extensions: string[];
-    parse(content: string): Promise<Record<string, any>>;
-    serialize(data: Record<string, any>, options?: any): Promise<string>;
+    parse(content: string): Promise<TranslationObject>;
+    serialize(data: TranslationObject, options?: SerializeOptions): Promise<string>;
 }

package/dist/core/adapters/yaml-adapter.js

@@ -4,16 +4,14 @@ import yaml from "js-yaml";
  */
 export class YamlAdapter {
     extensions = [".yaml", ".yml"];
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async parse(content) {
         try {
             return yaml.load(content) || {};
         }
         catch (error) {
-            throw new Error(`YAML parse error: ${error.message}`);
+            throw new Error(`YAML parse error: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async serialize(data, options = {}) {
         return yaml.dump(data, {
             indent: options.indent || 2,

package/dist/core/context-processor.d.ts

@@ -1,16 +1,30 @@
-interface CategoryConfig {
+/** A content category and the keywords that identify it. */
+export interface CategoryConfig {
     keywords: string[];
+    /** Multiplier applied to this category's keyword matches (default 1.0). */
     weight?: number;
+    /** Instruction added to the translation prompt for texts in this category. */
     prompt?: string;
 }
+/** Settings of the AI-based analysis; the whole object is also read by AIContextAnalyzer. */
+export interface ContextAnalysisOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeout?: number;
+    retries?: number;
+    /** Cache analysis results (default true). */
+    cacheAnalysis?: boolean;
+}
+/** The `context` configuration section: category detection for translation texts. */
 export interface ContextConfig {
     enabled?: boolean;
     useAI?: boolean;
     aiProvider?: string;
     minTextLength?: number;
-    analysisOptions?: {
-        cacheAnalysis?: boolean;
-    };
+    allowNewCategories?: boolean;
+    debug?: boolean;
+    analysisOptions?: ContextAnalysisOptions;
     categories: Record<string, CategoryConfig>;
     detection: {
         threshold: number;
@@ -21,7 +35,8 @@ export interface ContextConfig {
         prompt: string;
     };
 }
-interface AnalysisResult {
+/** Detected category of a text. */
+export interface AnalysisResult {
     category: string;
     confidence: number;
     prompt?: string;
@@ -42,7 +57,7 @@ declare class ContextProcessor {
      * Create a new ContextProcessor instance.
      * @param config - Configuration object.
      */
-    constructor(config: any);
+    constructor(config: ContextConfig);
     /**
      * Initialize keyword matching patterns from configuration.
      */

package/dist/core/context-processor.js

@@ -10,13 +10,11 @@ class ContextProcessor {
     config;
     keywordCache;
     aiAnalyzer;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     resultCache;
     /**
      * Create a new ContextProcessor instance.
      * @param config - Configuration object.
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(config) {
         this.config = config;
         this.keywordCache = new Map();
@@ -56,7 +54,6 @@ class ContextProcessor {
         if (!texts || !Array.isArray(texts) || !this.config.enabled) {
             return texts.map(() => this.getFallback());
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const results = [];
         const aiTexts = [];
         const aiIndices = [];
@@ -120,7 +117,8 @@ class ContextProcessor {
                 }
             }
             catch (error) {
-                console.error("Batch AI context analysis failed:", error.message);
+                const message = error instanceof Error ? error.message : String(error);
+                console.error("Batch AI context analysis failed:", message);
             }
         }
         return results;
@@ -141,7 +139,6 @@ class ContextProcessor {
      */
     _performKeywordAnalysis(text) {
         const lowerText = text.toLowerCase();
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const results = new Map();
         let totalScore = 0;
         const isShortText = text.length < 500;
@@ -183,7 +180,6 @@ class ContextProcessor {
     /**
      * Determine the best category match from analysis results.
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     getBestMatch(results, totalScore) {
         if (totalScore === 0)
             return this.getFallback();
@@ -212,7 +208,6 @@ class ContextProcessor {
     /**
      * Generate a collision-resistant cache key for text and context.
      */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     getCacheKey(text, context) {
         let keyContent;
         if (text.length <= 200) {

package/dist/core/detection/framework-detector.js

@@ -34,7 +34,7 @@ export class FrameworkDetector {
                     return { framework: "react", localesDir: "public/locales", fileFormat: "json" };
                 }
             }
-            catch (e) {
+            catch {
                 // No package.json or invalid
             }
             // Check for pubspec.yaml (Flutter)

package/dist/core/detection/structure-detector.js

@@ -23,7 +23,7 @@ export class StructureDetector {
             }
             return LocaleStructure.UNKNOWN;
         }
-        catch (error) {
+        catch {
             return LocaleStructure.UNKNOWN;
         }
     }

package/dist/core/fallback-provider.d.ts

@@ -1,9 +1,8 @@
-import { TranslateOptions, ProviderConfig } from "../providers/base-provider.js";
+import { TranslateOptions, ProviderConfig, ChatMessage } from "../providers/base-provider.js";
 export interface ProviderModule {
     translate(text: string, sourceLang: string, targetLang: string, options?: TranslateOptions): Promise<string>;
     analyze?(prompt: string, options?: ProviderConfig): Promise<string>;
-    chat?(messages: any[], options?: ProviderConfig): Promise<string>;
-    [key: string]: any;
+    chat?(messages: ChatMessage[], options?: ProviderConfig): Promise<string>;
 }
 export interface ProviderWrapper {
     name: string;
@@ -41,7 +40,7 @@ declare class FallbackProvider {
     _calculatePriority(text: string): number;
     translate(text: string, sourceLang: string, targetLang: string, options?: TranslateOptions): Promise<string>;
     analyze(prompt: string, options?: ProviderConfig): Promise<string>;
-    chat(messages: any[], options?: ProviderConfig): Promise<string>;
+    chat(messages: ChatMessage[], options?: ProviderConfig): Promise<string>;
     getStats(): Record<string, ProviderStats>;
     reset(): void;
     resetStats(): void;

package/dist/core/fallback-provider.js

@@ -43,7 +43,6 @@ class FallbackProvider {
         return 1;
     }
     async translate(text, sourceLang, targetLang, options = {}) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const errors = [];
         const startTime = Date.now();
         const startIndex = this.currentIndex;
@@ -89,7 +88,6 @@ class FallbackProvider {
                     },
                 }), this._calculatePriority(text));
                 const responseTime = Date.now() - providerStartTime;
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 const stats = this.providerStats.get(providerName);
                 stats.success++;
                 stats.consecutiveFailures = 0;
@@ -102,14 +100,14 @@ class FallbackProvider {
                 return result;
             }
             catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
                 if (this.providerStats.has(providerName)) {
-                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     const stats = this.providerStats.get(providerName);
                     stats.failure++;
                     stats.consecutiveFailures++;
                     stats.lastError = {
                         time: new Date(),
-                        message: error.message,
+                        message,
                     };
                     if (stats.consecutiveFailures >= 5) {
                         this._disableProvider(providerData, 2 * 60 * 1000);
@@ -119,13 +117,13 @@ class FallbackProvider {
                 this.lastErrorTime = Date.now();
                 errors.push({
                     provider: providerName,
-                    error: error.message,
+                    error: message,
                     attempt: currentAttempt + 1,
                 });
                 const safeProviderName = `Provider_${(currentProviderIndex % totalProviders) + 1}`;
-                const safeErrorMessage = error.message.includes("API") || error.message.includes("key")
+                const safeErrorMessage = message.includes("API") || message.includes("key")
                     ? "Authentication or API error"
-                    : error.message.substring(0, 100);
+                    : message.substring(0, 100);
                 console.warn(`${safeProviderName} failed (attempt ${currentAttempt + 1}/${maxAttempts}): ${safeErrorMessage}`);
                 currentAttempt++;
                 this.currentIndex++;
@@ -135,7 +133,6 @@ class FallbackProvider {
         throw new Error(`All providers failed after ${maxAttempts} attempts (${Date.now() - startTime}ms):\n${JSON.stringify(errors, null, 2)}`);
     }
     async analyze(prompt, options = {}) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const errors = [];
         const startTime = Date.now();
         const savedIndex = this.currentIndex;
@@ -185,7 +182,6 @@ class FallbackProvider {
                     },
                 }), this._calculatePriority(prompt));
                 const responseTime = Date.now() - providerStartTime;
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 const stats = this.providerStats.get(providerName);
                 stats.success++;
                 stats.consecutiveFailures = 0;
@@ -199,14 +195,14 @@ class FallbackProvider {
                 return result;
             }
             catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
                 if (this.providerStats.has(providerName)) {
-                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     const stats = this.providerStats.get(providerName);
                     stats.failure++;
                     stats.consecutiveFailures++;
                     stats.lastError = {
                         time: new Date(),
-                        message: error.message,
+                        message,
                     };
                     if (stats.consecutiveFailures >= 5) {
                         this._disableProvider(providerData, 2 * 60 * 1000);
@@ -216,13 +212,13 @@ class FallbackProvider {
                 this.lastErrorTime = Date.now();
                 errors.push({
                     provider: providerName,
-                    error: error.message,
+                    error: message,
                     attempt: currentAttempt + 1,
                 });
                 const safeProviderName = `Provider_${(currentProviderIndex % totalProviders) + 1}`;
-                const safeErrorMessage = error.message.includes("API") || error.message.includes("key")
+                const safeErrorMessage = message.includes("API") || message.includes("key")
                     ? "Authentication or API error"
-                    : error.message.substring(0, 100);
+                    : message.substring(0, 100);
                 console.warn(`${safeProviderName} failed (attempt ${currentAttempt + 1}/${maxAttempts}): ${safeErrorMessage}`);
                 currentAttempt++;
                 this.currentIndex++;
@@ -232,7 +228,6 @@ class FallbackProvider {
         throw new Error(`All providers failed for analysis after ${maxAttempts} attempts (${Date.now() - startTime}ms):\n${JSON.stringify(errors, null, 2)}`);
     }
     async chat(messages, options = {}) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const errors = [];
         const startTime = Date.now();
         const savedIndex = this.currentIndex;
@@ -283,7 +278,6 @@ class FallbackProvider {
                 }), 1 // Priority 1 (normal)
                 );
                 const responseTime = Date.now() - providerStartTime;
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                 const stats = this.providerStats.get(providerName);
                 stats.success++;
                 stats.consecutiveFailures = 0;
@@ -297,14 +291,14 @@ class FallbackProvider {
                 return result;
             }
             catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
                 if (this.providerStats.has(providerName)) {
-                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
                     const stats = this.providerStats.get(providerName);
                     stats.failure++;
                     stats.consecutiveFailures++;
                     stats.lastError = {
                         time: new Date(),
-                        message: error.message,
+                        message,
                     };
                     if (stats.consecutiveFailures >= 5) {
                         this._disableProvider(providerData, 2 * 60 * 1000);
@@ -314,13 +308,13 @@ class FallbackProvider {
                 this.lastErrorTime = Date.now();
                 errors.push({
                     provider: providerName,
-                    error: error.message,
+                    error: message,
                     attempt: currentAttempt + 1,
                 });
                 const safeProviderName = `Provider_${(currentProviderIndex % totalProviders) + 1}`;
-                const safeErrorMessage = error.message.includes("API") || error.message.includes("key")
+                const safeErrorMessage = message.includes("API") || message.includes("key")
                     ? "Authentication or API error"
-                    : error.message.substring(0, 100);
+                    : message.substring(0, 100);
                 console.warn(`${safeProviderName} failed (attempt ${currentAttempt + 1}/${maxAttempts}): ${safeErrorMessage}`);
                 currentAttempt++;
                 this.currentIndex++;

package/dist/core/orchestrator.d.ts

@@ -1,21 +1,52 @@
-import ProgressTracker from "../utils/progress-tracker.js";
+import { ProviderStatus, RateLimiterConfig } from "../utils/rate-limiter.js";
+import ProgressTracker, { ProgressOptions } from "../utils/progress-tracker.js";
 import QualityChecker from "../utils/quality/index.js";
+import type { QualityRules } from "../utils/quality/base-checker.js";
+import type { LengthControlOptions } from "../utils/quality/length-checker.js";
+import type { StyleGuideConfig } from "../utils/quality/style-guide-checker.js";
 import { ContextConfig } from "./context-processor.js";
 import { LRUCache } from "lru-cache";
-import GlossaryManager from "../utils/glossary-manager.js";
-import { TranslationResult } from "./pipeline/context.js";
+import GlossaryManager, { GlossaryConfig } from "../utils/glossary-manager.js";
+import type { FlatTranslationValue } from "../utils/object-transformer.js";
+import type { RetryConfig } from "../utils/retry-helper.js";
+import type { ProviderConfig } from "../providers/base-provider.js";
+import { TranslationMeta, TranslationResult } from "./pipeline/context.js";
 import { CacheStats } from "./pipeline/steps/CacheReadStep.js";
 import { ConfidenceSettings } from "./pipeline/steps/TranslationStep.js";
 import { SourceCodeAnalyzer } from "../services/source-analyzer.js";
+/** The `rateLimiter` configuration section. */
+export interface RateLimiterOptions extends RateLimiterConfig {
+    enabled?: boolean;
+}
+/** The `retryOptions` configuration section; providers read `maxRetries` and `initialDelay`. */
+export interface ProviderRetryOptions {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    jitter?: boolean;
+    retryableErrors?: string[];
+    perProviderRetry?: Record<string, Partial<RetryConfig>>;
+}
+/** The `vectorMemory` configuration section. */
+export interface VectorMemoryOptions extends VectorStoreConfig {
+    embeddingProvider?: string;
+    embeddingModel?: string;
+}
+/**
+ * Settings read by the orchestrator and its pipeline steps. The whole object is also
+ * forwarded to the provider's `translate()` (see TranslationStep).
+ */
 export interface OrchestratorOptions {
     context: ContextConfig;
+    /** Scan the project's source code for where each key is used (default true). */
     deepContext?: boolean;
-    progressOptions?: any;
-    styleGuide?: any;
-    lengthControl?: any;
+    progressOptions?: ProgressOptions;
+    styleGuide?: StyleGuideConfig;
+    lengthControl?: LengthControlOptions;
     qualityChecks?: {
         enabled?: boolean;
-        rules?: any;
+        rules?: QualityRules;
+        autoFix?: boolean;
     };
     advanced?: {
         timeoutMs?: number;
@@ -24,34 +55,49 @@ export interface OrchestratorOptions {
         autoOptimize?: boolean;
         debug?: boolean;
     };
-    glossary?: any;
-    rateLimiter?: {
-        queueStrategy?: string;
-        queueTimeout?: number;
-        adaptiveThrottling?: boolean;
-        providerLimits?: any;
-    };
+    glossary?: GlossaryConfig;
+    rateLimiter?: RateLimiterOptions;
     cacheSize?: number;
     cacheTTL?: number;
     updateAgeOnGet?: boolean;
+    /** @deprecated Has no effect: expired cache entries are always translated again. */
     allowStaleCache?: boolean;
+    /** @deprecated Has no effect: the cache never refreshes entries in the background. */
     staleWhileRevalidate?: boolean;
+    /** Turns confidence scoring on; translations scoring below it need review (`--min-confidence`). */
     minConfidence?: number;
+    /** Turns confidence scoring on and saves the flagged translations for `locai review`. */
     saveReviewQueue?: boolean;
     confidenceScoring?: {
+        /** Score every new translation (default false). */
         enabled?: boolean;
+        /** Translations scoring below it need review (default 0.7); the top-level minConfidence wins. */
         minConfidence?: number;
+        /** Save the flagged translations to .localize-cache/review-queue.json for `locai review`. */
         saveReviewQueue?: boolean;
+        /** Translations scoring at or above it are marked auto-approved (default 0.9). */
         autoApproveThreshold?: number;
+        /** Older name of minConfidence; when both are set, the higher one applies. */
         reviewThreshold?: number;
+        /** Translations scoring below it are rejected and not written (default 0.5). */
         rejectThreshold?: number;
     };
     concurrencyLimit?: number;
     cacheEnabled?: boolean;
+    /** Language of the source texts. */
     source: string;
-    [key: string]: any;
+    vectorMemory?: VectorMemoryOptions;
+    /** Analyzer shared between orchestrators; a new one is created when omitted. */
+    sourceCodeAnalyzer?: SourceCodeAnalyzer;
+    /** Translation provider; the available providers are tried in order when unset. */
+    apiProvider?: string;
+    useFallback?: boolean;
+    fallbackOrder?: string[];
+    /** Model settings per provider, keyed by provider name. */
+    apiConfig?: Record<string, ProviderConfig>;
+    retryOptions?: ProviderRetryOptions;
 }
-import { VectorStore } from "../services/vector-store.js";
+import { VectorStore, VectorStoreConfig } from "../services/vector-store.js";
 import { EmbeddingProvider } from "../services/embedding-provider.js";
 import { VectorMemoryStats } from "./pipeline/steps/VectorCacheReadStep.js";
 interface AdvancedSettings {
@@ -61,21 +107,44 @@ interface AdvancedSettings {
     autoOptimize: boolean;
     debug: boolean;
 }
+/** One key to translate, as passed to {@link Orchestrator.processTranslations}. */
 interface TranslationItem {
     key: string;
     text: string;
     targetLang: string;
-    existingTranslation?: any;
-    [key: string]: any;
+    existingTranslation?: FlatTranslationValue;
+}
+/** Cache counters plus the cache's current size, capacity and hit rate. */
+export interface CacheStatus extends CacheStats {
+    size: number;
+    capacity: number;
+    hitRate: number;
+}
+/** Snapshot returned by {@link Orchestrator.getStatus}. */
+export interface OrchestratorStatus {
+    /** Empty when the cache is disabled. */
+    cache: CacheStatus | Record<string, never>;
+    rateLimiter: Record<string, ProviderStatus>;
+    concurrency: number;
+    advanced: AdvancedSettings;
+    confidence: {
+        minThreshold?: number;
+        autoApproveThreshold: number;
+        reviewThreshold: number;
+        rejectThreshold: number;
+        reviewQueueSize: number;
+        autoApprovedCount: number;
+        rejectedCount: number;
+    } | null;
 }
 declare class Orchestrator {
     private options;
     private contextProcessor;
     progress: ProgressTracker;
-    qualityChecker: QualityChecker | any;
+    qualityChecker: QualityChecker | null;
     advanced: AdvancedSettings;
     glossaryManager: GlossaryManager;
-    translationCache: LRUCache<string, any> | null;
+    translationCache: LRUCache<string, TranslationResult> | null;
     cacheStats: CacheStats;
     vectorStore: VectorStore;
     embeddingProvider: EmbeddingProvider;
@@ -87,18 +156,21 @@ declare class Orchestrator {
     private _shutdownCallback;
     constructor(options: OrchestratorOptions);
     private _buildPipeline;
-    processTranslation(key: string, text: string, targetLang: string, contextData: any, existingTranslation: any): Promise<TranslationResult>;
+    processTranslation(key: string, text: string, targetLang: string, contextData: TranslationMeta, existingTranslation?: FlatTranslationValue): Promise<TranslationResult>;
+    /** Count a scored translation and queue it when it needs review or was rejected. */
+    private _recordConfidence;
     processTranslations(items: TranslationItem[]): Promise<TranslationResult[]>;
     private _chunkArray;
     private _applyAutoOptimizations;
     clearCache(): void;
     resetCacheStats(): void;
-    getCacheStats(): any;
-    _refreshCacheEntry(key: string, context: any): Promise<void>;
-    getStatus(): any;
+    getCacheStats(): CacheStatus | Record<string, never>;
+    getStatus(): OrchestratorStatus;
+    /**
+     * Add the translations this orchestrator flagged to `.localize-cache/review-queue.json`,
+     * when saving the review queue is enabled.
+     */
     saveReviewQueue(): void;
-    private _groupByLanguage;
-    private _groupByConfidenceLevel;
     destroy(): void;
 }
 export default Orchestrator;