locai 2.3.0 → 2.5.0

package/dist/config/index.js

@@ -50,3 +50,29 @@ export async function loadConfig(cwd = process.cwd()) {
         layers,
     };
 }
+export const validateEnvironment = (config) => {
+    const providerMap = {
+        openai: "OPENAI_API_KEY",
+        anthropic: "ANTHROPIC_API_KEY",
+        gemini: "GEMINI_API_KEY",
+        deepseek: "DEEPSEEK_API_KEY",
+        xai: "XAI_API_KEY",
+        dashscope: "DASHSCOPE_API_KEY",
+    };
+    // If a specific provider is configured, check its key
+    if (config?.apiProvider && config.apiProvider !== "auto") {
+        const requiredKey = providerMap[config.apiProvider];
+        if (requiredKey && !process.env[requiredKey]) {
+            console.warn(`\n\u26a0\ufe0f  Warning: ${requiredKey} is missing for provider '${config.apiProvider}'`);
+            console.warn(`   Please add it to your .env file or environment variables.\n`);
+        }
+        return;
+    }
+    // If auto or no provider, check if ANY valid key exists
+    const hasAnyKey = Object.values(providerMap).some((key) => process.env[key]);
+    if (!hasAnyKey) {
+        console.warn("\n\u26a0\ufe0f  Warning: No supported API keys found in environment.");
+        console.warn("   Supported keys: " + Object.values(providerMap).join(", "));
+        console.warn("   Please add at least one to your .env file.\n");
+    }
+};

package/dist/config/setup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Load environment variables from .env files.
+ * Prioritizes .env.local over .env.
+ */
+export declare const loadEnvironmentVariables: () => Promise<void>;
+/**
+ * Configure global components (logger, rate limiter, etc.).
+ * @param {any} config - Configuration object.
+ */
+export declare const configureComponents: (config: any) => void;

package/dist/config/setup.js

@@ -0,0 +1,79 @@
+import dotenv from "dotenv";
+import { promises as fs } from "fs";
+import path from "path";
+import { FileManager } from "../utils/file-manager.js";
+import { getLogger } from "../utils/logger.js";
+import rateLimiter from "../utils/rate-limiter.js";
+/**
+ * Load environment variables from .env files.
+ * Prioritizes .env.local over .env.
+ */
+export const loadEnvironmentVariables = async () => {
+    // Load environment files in priority order
+    // First load .env (base defaults), then .env.local (local overrides)
+    // This ensures .env.local values take precedence over .env values
+    const envFiles = [
+        { file: ".env", override: false },
+        { file: ".env.local", override: true },
+    ];
+    let loadedCount = 0;
+    for (const { file: envFile, override } of envFiles) {
+        const envPath = path.resolve(process.cwd(), envFile);
+        try {
+            await fs.access(envPath);
+            const result = dotenv.config({ path: envPath, override });
+            if (!result.error) {
+                loadedCount++;
+                // Only log in verbose/debug mode to reduce noise
+                if (process.env.VERBOSE || process.env.DEBUG) {
+                    console.log(`Loaded environment variables from ${envFile}`);
+                }
+            }
+        }
+        catch (error) {
+            // ENOENT is expected when files don't exist - silently skip
+            if (error.code !== "ENOENT") {
+                console.warn(`Warning: Could not load ${envFile}: ${error.message}`);
+            }
+        }
+    }
+    // Informative message only if verbose/debug and at least one file was loaded
+    if ((process.env.VERBOSE || process.env.DEBUG) && loadedCount > 0) {
+        console.log(`Environment: ${loadedCount} file(s) loaded`);
+    }
+};
+/**
+ * Configure global components (logger, rate limiter, etc.).
+ * @param {any} config - Configuration object.
+ */
+export const configureComponents = (config) => {
+    // Configure FileManager with config settings
+    if (config.fileOperations) {
+        FileManager.configure(config.fileOperations);
+    }
+    // Initialize logger with config
+    if (config.logging) {
+        const logger = getLogger(config.logging);
+        if (config.logging.verbose || config.debug) {
+            logger.info("Logger initialized", {
+                saveErrorLogs: config.logging.saveErrorLogs,
+                logDirectory: config.logging.logDirectory,
+                rotationEnabled: config.logging.logRotation?.enabled,
+            });
+        }
+    }
+    if (config.rateLimiter) {
+        rateLimiter.updateConfig({
+            queueStrategy: config.rateLimiter.queueStrategy || "priority",
+            queueTimeout: config.rateLimiter.queueTimeout || 30000,
+            adaptiveThrottling: config.rateLimiter.adaptiveThrottling !== false,
+            providerLimits: config.rateLimiter.providerLimits,
+        });
+    }
+    if (config.advanced?.debug) {
+        process.env.DEBUG = "true";
+    }
+    if (config.logging?.verbose) {
+        process.env.VERBOSE = "true";
+    }
+};

package/dist/core/orchestrator.d.ts

@@ -6,8 +6,10 @@ import GlossaryManager from "../utils/glossary-manager.js";
 import { 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";
 export interface OrchestratorOptions {
     context: ContextConfig;
+    deepContext?: boolean;
     progressOptions?: any;
     styleGuide?: any;
     lengthControl?: any;
@@ -78,6 +80,7 @@ declare class Orchestrator {
     vectorStore: VectorStore;
     embeddingProvider: EmbeddingProvider;
     vectorStats: VectorMemoryStats;
+    sourceAnalyzer: SourceCodeAnalyzer;
     confidenceSettings: ConfidenceSettings;
     private concurrencyLimit;
     private pipeline;

package/dist/core/orchestrator.js

@@ -22,6 +22,8 @@ import QualityCheckStep from "./pipeline/steps/QualityCheckStep.js";
 import ToneCheckStep from "./pipeline/steps/ToneCheckStep.js";
 import ConfidenceCheckStep from "./pipeline/steps/ConfidenceCheckStep.js";
 import CacheWriteStep from "./pipeline/steps/CacheWriteStep.js";
+import ContextEnrichmentStep from "./pipeline/steps/ContextEnrichmentStep.js";
+import { SourceCodeAnalyzer } from "../services/source-analyzer.js";
 // Vector Memory Imports
 import { VectorStore } from "../services/vector-store.js";
 import { EmbeddingProvider } from "../services/embedding-provider.js";
@@ -41,6 +43,8 @@ class Orchestrator {
     vectorStore;
     embeddingProvider;
     vectorStats;
+    // Source Code Analysis
+    sourceAnalyzer;
     confidenceSettings;
     concurrencyLimit;
     pipeline;
@@ -150,6 +154,26 @@ class Orchestrator {
                 }
             });
         }
+        // Initialize Source Analyzer
+        if (options.sourceCodeAnalyzer) {
+            this.sourceAnalyzer = options.sourceCodeAnalyzer;
+            // Assumed initialized or self-initializing
+        }
+        else {
+            this.sourceAnalyzer = new SourceCodeAnalyzer();
+            // Fire and forget initialization (or await if strict)
+            // We'll trust it catches up or is fast enough for the first few items,
+            // or we can await it if we want to block startup.
+            // For CLI responsiveness, we might want to await it only if deep context is enabled.
+            const deepContextEnabled = options.deepContext !== false; // Enabled by default
+            if (deepContextEnabled) {
+                this.sourceAnalyzer.initialize().catch((err) => {
+                    if (this.advanced.debug) {
+                        console.warn("Source analyzer init failed:", err.message);
+                    }
+                });
+            }
+        }
         // Initialize Pipeline
         this.pipeline = new Pipeline();
         this._buildPipeline();
@@ -182,6 +206,9 @@ class Orchestrator {
         // 3. Glossary Pre-processing
         this.pipeline.use(new GlossaryPreStep(this.glossaryManager));
         // 4. Translation
+        // 3.5 Context Enrichment (Deep Context)
+        const deepContextEnabled = this.options.deepContext !== false;
+        this.pipeline.use(new ContextEnrichmentStep(this.sourceAnalyzer, deepContextEnabled));
         this.pipeline.use(new TranslationStep(this.options, this.confidenceSettings));
         // 4.5 Vector Cache Write (save new translations)
         if (this.options.vectorMemory?.enabled) {

package/dist/core/pipeline/steps/ContextEnrichmentStep.d.ts

@@ -0,0 +1,9 @@
+import PipelineStep from "../PipelineStep.js";
+import { TranslationContext } from "../context.js";
+import { SourceCodeAnalyzer } from "../../../services/source-analyzer.js";
+export default class ContextEnrichmentStep extends PipelineStep {
+    private analyzer;
+    private enabled;
+    constructor(analyzer: SourceCodeAnalyzer, enabled?: boolean);
+    execute(context: TranslationContext, next: () => Promise<void>): Promise<void>;
+}

package/dist/core/pipeline/steps/ContextEnrichmentStep.js

@@ -0,0 +1,43 @@
+import PipelineStep from "../PipelineStep.js";
+export default class ContextEnrichmentStep extends PipelineStep {
+    analyzer;
+    enabled;
+    constructor(analyzer, enabled = true) {
+        super();
+        this.analyzer = analyzer;
+        this.enabled = enabled;
+    }
+    async execute(context, next) {
+        if (this.enabled) {
+            try {
+                // Ensure analysis is complete before checking for context
+                await this.analyzer.ensureInitialized();
+                const codeContext = this.analyzer.getContext(context.key);
+                if (codeContext) {
+                    // Enrich the context meta
+                    context.meta = {
+                        ...context.meta,
+                        code: codeContext,
+                    };
+                    // Also append to the AI prompt context if it exists
+                    // (Assuming existing translation prompt uses contextData)
+                    context.contextData = {
+                        ...(context.contextData || {}),
+                        visualContext: {
+                            component: codeContext.component,
+                            file: codeContext.filePath,
+                            comments: codeContext.comments,
+                            props: codeContext.props,
+                            snippet: codeContext.usageSnippet,
+                        },
+                    };
+                }
+            }
+            catch (error) {
+                // Non-blocking error
+                // console.warn(`Context enrichment failed for ${context.key}`, error);
+            }
+        }
+        await next();
+    }
+}

package/dist/services/language-processor.d.ts

@@ -0,0 +1,22 @@
+import Orchestrator from "../core/orchestrator.js";
+import { TranslationOptions, GlobalStats, LanguageProcessResult } from "../types/index.js";
+export declare class LanguageProcessor {
+    /**
+     * Process a single language translation.
+     * @param {string} targetLang - Target language code.
+     * @param {string} sourceFile - Path to source file.
+     * @param {Record<string, any>} flattenedSource - Flattened source content.
+     * @param {Orchestrator} orchestrator - Orchestrator instance.
+     * @param {TranslationOptions} options - Translation options.
+     * @param {GlobalStats} globalStats - Global statistics object.
+     * @param {any} comparison - State comparison result.
+     * @returns {Promise<LanguageProcessResult>} - Status and messages for this language.
+     */
+    static processLanguage(targetLang: string, sourceFile: string, flattenedSource: Record<string, any>, orchestrator: Orchestrator, options: TranslationOptions, globalStats: GlobalStats, comparison: any): Promise<LanguageProcessResult>;
+    /**
+     * Check if text only contains placeholders and whitespace.
+     * @param {string} text - Text to check.
+     * @returns {boolean} - True if text only contains placeholders.
+     */
+    static isPlaceholderOnlyText(text: string): boolean;
+}

package/dist/services/language-processor.js

@@ -0,0 +1,239 @@
+import path from "path";
+import { FileManager } from "../utils/file-manager.js";
+import ObjectTransformer from "../utils/object-transformer.js";
+import InputValidator from "../utils/input-validator.js";
+import uiManager from "../utils/ui-manager.js";
+import statisticsManager from "../utils/statistics-manager.js";
+export class LanguageProcessor {
+    /**
+     * Process a single language translation.
+     * @param {string} targetLang - Target language code.
+     * @param {string} sourceFile - Path to source file.
+     * @param {Record<string, any>} flattenedSource - Flattened source content.
+     * @param {Orchestrator} orchestrator - Orchestrator instance.
+     * @param {TranslationOptions} options - Translation options.
+     * @param {GlobalStats} globalStats - Global statistics object.
+     * @param {any} comparison - State comparison result.
+     * @returns {Promise<LanguageProcessResult>} - Status and messages for this language.
+     */
+    static async processLanguage(targetLang, sourceFile, flattenedSource, orchestrator, options, globalStats, comparison) {
+        if (!targetLang) {
+            throw new Error("Invalid target language provided");
+        }
+        const langStartTime = Date.now();
+        try {
+            if (!targetLang || typeof targetLang !== "string") {
+                throw new Error("Invalid target language provided");
+            }
+            if (!sourceFile || typeof sourceFile !== "string") {
+                throw new Error("Invalid source file path provided");
+            }
+            if (!flattenedSource || typeof flattenedSource !== "object") {
+                throw new Error("Invalid flattened source data provided");
+            }
+            if (!orchestrator || typeof orchestrator.processTranslations !== "function") {
+                throw new Error("Invalid orchestrator instance provided");
+            }
+            if (!globalStats || typeof globalStats !== "object") {
+                throw new Error("Invalid global stats object provided");
+            }
+            const safeTargetLang = InputValidator.validateLanguageCode(targetLang, "target language");
+            await uiManager.log(`Starting translations for ${safeTargetLang}`);
+            let finalStatus = null;
+            let savedMessage = undefined;
+            statisticsManager.initLanguageStats(safeTargetLang);
+            const sourceDir = path.dirname(sourceFile);
+            const safeTargetFilename = `${safeTargetLang}.json`;
+            const targetPath = InputValidator.createSafeFilePath(sourceDir, safeTargetFilename);
+            let targetContent = {};
+            try {
+                targetContent = await FileManager.readJSON(targetPath);
+                if (!targetContent || typeof targetContent !== "object") {
+                    console.warn(`Invalid content in ${targetPath}, using empty object`);
+                    targetContent = {};
+                }
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    await uiManager.log(`\ud83c\udd95 Creating new translation file for ${safeTargetLang}`);
+                }
+                else {
+                    if (options.debug) {
+                        console.warn(`Error reading ${targetPath}: ${err.message}, using empty object`);
+                    }
+                }
+                targetContent = {};
+            }
+            let flattenedTarget = {};
+            try {
+                flattenedTarget = ObjectTransformer.flatten(targetContent);
+                if (!flattenedTarget || typeof flattenedTarget !== "object") {
+                    flattenedTarget = {};
+                }
+            }
+            catch (err) {
+                console.warn(`Error flattening target content: ${err.message}, using empty object`);
+                flattenedTarget = {};
+            }
+            const missingKeys = [];
+            let hasPlaceholderOnlyChanges = false;
+            for (const [key, sourceText] of Object.entries(flattenedSource)) {
+                try {
+                    InputValidator.validateKey(key, "translation key");
+                    InputValidator.validateText(sourceText, "source text");
+                }
+                catch (keyError) {
+                    await uiManager.log(`\u26a0\ufe0f Skipping invalid key/text: ${keyError.message}`);
+                    globalStats.languages[safeTargetLang].failed++;
+                    globalStats.failed++;
+                    continue;
+                }
+                globalStats.languages[safeTargetLang].processed++;
+                if (this.isPlaceholderOnlyText(sourceText)) {
+                    const existingValue = flattenedTarget[key];
+                    if (existingValue !== sourceText) {
+                        flattenedTarget[key] = sourceText;
+                        hasPlaceholderOnlyChanges = true;
+                        if (options.debug) {
+                            await uiManager.log(`   Copying placeholder-only text: "${sourceText}"`);
+                        }
+                    }
+                    globalStats.languages[safeTargetLang].skipped++;
+                    globalStats.skipped++;
+                    continue;
+                }
+                const isNewKey = comparison.newKeys.includes(key);
+                const isModifiedKey = comparison.modifiedKeys.includes(key);
+                const keyExistsInTarget = key in flattenedTarget;
+                if (keyExistsInTarget && !options.forceUpdate && !isModifiedKey) {
+                    globalStats.languages[safeTargetLang].skipped++;
+                    globalStats.skipped++;
+                    continue;
+                }
+                missingKeys.push({
+                    key,
+                    text: sourceText,
+                    targetLang: safeTargetLang,
+                    existingTranslation: flattenedTarget[key],
+                    isModified: isModifiedKey,
+                    isNew: isNewKey,
+                });
+            }
+            if (missingKeys.length === 0 && !hasPlaceholderOnlyChanges) {
+                await uiManager.log(`All translations exist for ${safeTargetLang}`);
+                globalStats.languages[safeTargetLang].timeMs = Date.now() - langStartTime;
+                return { status: { completed: 0, total: 0, language: safeTargetLang } };
+            }
+            if (missingKeys.length > 0) {
+                await uiManager.log(`Found ${missingKeys.length} missing translations for ${safeTargetLang}`);
+            }
+            let results = [];
+            if (missingKeys.length > 0) {
+                try {
+                    results = await orchestrator.processTranslations(missingKeys);
+                    if (!Array.isArray(results)) {
+                        console.warn("Invalid results from orchestrator, using empty array");
+                        results = [];
+                    }
+                }
+                catch (err) {
+                    console.error(`Error processing translations for ${safeTargetLang}: ${err.message}`);
+                    results = [];
+                    if (globalStats.languages[safeTargetLang]) {
+                        globalStats.languages[safeTargetLang].failed += missingKeys.length;
+                        globalStats.failed += missingKeys.length;
+                    }
+                }
+            }
+            else {
+                if (hasPlaceholderOnlyChanges) {
+                    await uiManager.log(`Found placeholder-only changes for ${safeTargetLang}`);
+                }
+            }
+            try {
+                if (orchestrator?.progress &&
+                    typeof orchestrator.progress.getStatus === "function") {
+                    finalStatus = orchestrator.progress.getStatus();
+                }
+            }
+            catch (err) {
+                console.warn(`Error getting orchestrator status: ${err.message}`);
+            }
+            let validResults = [];
+            try {
+                validResults = results.filter((result) => result && result.success === true);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                validResults = validResults.filter((result) => result.key &&
+                    typeof result.key === "string" &&
+                    result.translated &&
+                    typeof result.translated === "string");
+            }
+            catch (err) {
+                console.warn(`Error filtering results: ${err.message}`);
+                validResults = [];
+            }
+            if (validResults.length > 0) {
+                validResults.forEach(({ key, translated }) => {
+                    if (translated) {
+                        flattenedTarget[key] = translated;
+                    }
+                });
+            }
+            const hasChangesToSave = validResults.length > 0 || hasPlaceholderOnlyChanges;
+            if (hasChangesToSave) {
+                const unflattened = ObjectTransformer.unflatten(flattenedTarget);
+                await FileManager.writeJSON(targetPath, unflattened);
+                globalStats.total += validResults.length;
+                globalStats.success += validResults.length;
+                globalStats.failed += results.length - validResults.length;
+                globalStats.languages[safeTargetLang].added += validResults.length;
+                globalStats.languages[safeTargetLang].failed +=
+                    results.length - validResults.length;
+                validResults.forEach((result) => {
+                    if (result.context) {
+                        const category = result.context.category || "general";
+                        globalStats.byCategory[category] =
+                            (globalStats.byCategory[category] || 0) + 1;
+                        if (!globalStats.details[category]) {
+                            globalStats.details[category] = {
+                                totalConfidence: 0,
+                                samples: 0,
+                            };
+                        }
+                        globalStats.details[category].totalConfidence +=
+                            result.context.confidence || 0;
+                        globalStats.details[category].samples++;
+                    }
+                });
+                savedMessage = `Translations saved: ${safeTargetLang}.json`;
+            }
+            globalStats.languages[safeTargetLang].timeMs = Date.now() - langStartTime;
+            return { status: finalStatus, savedMessage };
+        }
+        catch (error) {
+            const safeError = error.message.includes("outside working directory")
+                ? "Invalid file path detected"
+                : error.message;
+            await uiManager.log(`\n\u274c Error processing ${targetLang}: ${safeError}`);
+            if (globalStats.languages[targetLang]) {
+                globalStats.languages[targetLang].error = safeError;
+                globalStats.languages[targetLang].timeMs = Date.now() - langStartTime;
+            }
+            return { status: null, error: safeError };
+        }
+    }
+    /**
+     * Check if text only contains placeholders and whitespace.
+     * @param {string} text - Text to check.
+     * @returns {boolean} - True if text only contains placeholders.
+     */
+    static isPlaceholderOnlyText(text) {
+        if (!text || typeof text !== "string") {
+            return false;
+        }
+        // Remove all placeholders from the text
+        const placeholderRegex = /\{[^}]+\}|\$\{[^}]+\}|%[sd]/g;
+        const textWithoutPlaceholders = text.replace(placeholderRegex, "").trim();
+        return textWithoutPlaceholders.length === 0;
+    }
+}

package/dist/services/source-analyzer.d.ts

@@ -0,0 +1,14 @@
+import { CodeContext } from "../types/context.js";
+export declare class SourceCodeAnalyzer {
+    private project;
+    private keyUsageMap;
+    private rootDir;
+    private initPromise;
+    constructor(rootDir?: string);
+    initialize(globPatterns?: string[]): Promise<void>;
+    ensureInitialized(): Promise<void>;
+    private processFile;
+    private processCallExpression;
+    private extractContext;
+    getContext(key: string): CodeContext | undefined;
+}