locai 2.3.0 → 2.4.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/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/translation-service.d.ts

@@ -1,60 +1,12 @@
 import Orchestrator from "../core/orchestrator.js";
-import { OrchestratorOptions } from "../core/orchestrator.js";
 import StateManager from "../utils/state-manager.js";
-export interface TranslationOptions extends OrchestratorOptions {
-    source: string;
-    targets?: string[];
-    localesDir?: string;
-    debug?: boolean;
-    forceUpdate?: boolean;
-    syncOptions?: {
-        enabled?: boolean;
-        removeDeletedKeys?: boolean;
-    };
-    concurrencyLimit?: number;
-    saveReviewQueue?: boolean;
-    minConfidence?: number;
-    fileExtensions?: string[];
-}
-export interface GlobalStats {
-    total: number;
-    success: number;
-    failed: number;
-    skipped: number;
-    languages: Record<string, any>;
-    byCategory: Record<string, number>;
-    details: Record<string, {
-        totalConfidence: number;
-        samples: number;
-    }>;
-    error?: {
-        message: string;
-        time: string;
-        stack?: string;
-    };
-    orchestrators: any[];
-    endTime?: string;
-    totalDuration?: number;
-    totalTime: number;
-    startTime: string;
-}
-interface LanguageProcessResult {
-    status: any;
-    savedMessage?: string;
-    error?: string;
-}
+import { TranslationOptions, GlobalStats, LanguageProcessResult } from "../types/index.js";
 /**
  * Service for handling file translation operations.
  * Orchestrates the translation process including state management,
  * verification, and statistics collection.
  */
 declare class TranslationService {
-    /**
-     * Check if text only contains placeholders and whitespace.
-     * @param {string} text - Text to check.
-     * @returns {boolean} - True if text only contains placeholders.
-     */
-    isPlaceholderOnlyText(text: string): boolean;
     /**
      * Main translator function to process source file and create translations.
      * @param {string} file - Path to source file.