locai 2.1.0

package/dist/utils/progress-tracker.js

@@ -0,0 +1,277 @@
+/**
+ * Progress tracking for translation operations
+ */
+class ProgressTracker {
+    logToConsole;
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    logFrequency;
+    _isUpdating;
+    _pendingUpdates;
+    _spinnerInterval;
+    _spinnerIndex;
+    _spinnerFrames;
+    total;
+    completed;
+    success;
+    failed;
+    startTime;
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    endTime;
+    lastUpdateTime;
+    recentOperationTimes;
+    language;
+    isCompleted;
+    statistics;
+    constructor(options = {}) {
+        this.logToConsole = options.logToConsole !== false;
+        this.logFrequency = options.logFrequency || 1;
+        this._isUpdating = false;
+        this._pendingUpdates = [];
+        this._spinnerInterval = null;
+        this._spinnerIndex = 0;
+        this._spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+        // Initialize fields to satisfy TypeScript before calling reset()
+        this.total = 0;
+        this.completed = 0;
+        this.success = 0;
+        this.failed = 0;
+        this.startTime = null;
+        this.endTime = null;
+        this.lastUpdateTime = null;
+        this.recentOperationTimes = [];
+        this.language = null;
+        this.isCompleted = false;
+        this.statistics = {
+            avgTimePerItem: 0,
+            totalTime: 0,
+            estimatedTimeRemaining: 0,
+            itemsPerSecond: 0,
+            percentComplete: 0,
+            successRate: 0,
+        };
+        this.reset();
+    }
+    reset() {
+        // Stop any existing spinner
+        this._stopSpinner();
+        this.total = 0;
+        this.completed = 0;
+        this.success = 0;
+        this.failed = 0;
+        this.startTime = null;
+        this.endTime = null;
+        this.lastUpdateTime = null;
+        this.recentOperationTimes = [];
+        this.language = null;
+        this.isCompleted = false;
+        this._isUpdating = false;
+        this._pendingUpdates = [];
+        this.statistics = {
+            avgTimePerItem: 0,
+            totalTime: 0,
+            estimatedTimeRemaining: 0,
+            itemsPerSecond: 0,
+            percentComplete: 0,
+            successRate: 0,
+        };
+    }
+    start(total, language = null) {
+        this.reset();
+        this.total = Math.max(0, total);
+        this.startTime = Date.now();
+        this.lastUpdateTime = Date.now();
+        this.language = language;
+        this.isCompleted = false;
+        if (this.logToConsole && this.total > 0) {
+            // Start spinner animation
+            this._startSpinner();
+            this._renderProgress();
+        }
+    }
+    increment(type = "success") {
+        if (!this.startTime) {
+            throw new Error("Progress tracker not started");
+        }
+        if (this.isCompleted) {
+            return;
+        }
+        if (this._isUpdating) {
+            this._pendingUpdates.push({ type, timestamp: Date.now() });
+            return;
+        }
+        this._processUpdate(type);
+    }
+    _processUpdate(type) {
+        this._isUpdating = true;
+        try {
+            if (this.isCompleted) {
+                return;
+            }
+            const previousCompleted = this.completed;
+            this.completed = Math.min(this.total, this.completed + 1);
+            if (this.completed > previousCompleted) {
+                if (type === "success") {
+                    this.success = Math.min(this.completed, this.success + 1);
+                }
+                else if (type === "failed") {
+                    this.failed = Math.min(this.completed, this.failed + 1);
+                }
+            }
+            this._ensureDataConsistency();
+            const now = Date.now();
+            const timeSinceLastUpdate = now - (this.lastUpdateTime || now);
+            this.lastUpdateTime = now;
+            const MAX_OPERATION_TIMES = 10;
+            this.recentOperationTimes.push(timeSinceLastUpdate);
+            if (this.recentOperationTimes.length > MAX_OPERATION_TIMES) {
+                this.recentOperationTimes.shift(); // Keep only last 10
+            }
+            this._updateStatistics();
+            if (this.logToConsole && this._shouldLog()) {
+                this._renderProgress();
+            }
+            if (this.completed >= this.total && !this.isCompleted) {
+                this.endTime = Date.now();
+                this.isCompleted = true;
+                this._stopSpinner();
+                this._renderProgress(true); // Final render
+                if (this.logToConsole) {
+                    this._finalReport();
+                }
+            }
+        }
+        finally {
+            this._isUpdating = false;
+            this._processPendingUpdates();
+        }
+    }
+    _ensureDataConsistency() {
+        this.completed = Math.min(this.total, Math.max(0, this.completed));
+        this.success = Math.min(this.completed, Math.max(0, this.success));
+        this.failed = Math.min(this.completed, Math.max(0, this.failed));
+        const totalCounted = this.success + this.failed;
+        if (totalCounted > this.completed) {
+            if (this.success > this.completed) {
+                this.success = this.completed;
+                this.failed = 0;
+            }
+            else {
+                this.failed = this.completed - this.success;
+            }
+        }
+    }
+    _processPendingUpdates() {
+        if (!this._pendingUpdates ||
+            !Array.isArray(this._pendingUpdates) ||
+            this._pendingUpdates.length === 0) {
+            return;
+        }
+        setImmediate(() => {
+            while (this._pendingUpdates && this._pendingUpdates.length > 0 && !this._isUpdating) {
+                const updateItem = this._pendingUpdates.shift();
+                if (updateItem && typeof updateItem === "object" && updateItem.type) {
+                    this._processUpdate(updateItem.type);
+                }
+            }
+        });
+    }
+    _shouldLog() {
+        if (!this.logToConsole || this.total === 0)
+            return false;
+        return true;
+    }
+    _startSpinner() {
+        if (this._spinnerInterval)
+            return;
+        this._spinnerInterval = setInterval(() => {
+            if (!this.isCompleted) {
+                this._spinnerIndex = (this._spinnerIndex + 1) % this._spinnerFrames.length;
+                this._renderProgress();
+            }
+        }, 80);
+    }
+    _stopSpinner() {
+        if (this._spinnerInterval) {
+            clearInterval(this._spinnerInterval);
+            this._spinnerInterval = null;
+        }
+    }
+    _renderProgress(final = false) {
+        const percent = this.total > 0 ? (this.completed / this.total) * 100 : 0;
+        const langInfo = this.language ? `[${this.language}] ` : "";
+        const barWidth = 20;
+        const filledWidth = Math.max(0, Math.min(barWidth, Math.round((this.completed / this.total) * barWidth)));
+        const emptyWidth = barWidth - filledWidth;
+        const bar = "[" + "█".repeat(filledWidth) + "═".repeat(emptyWidth) + "]";
+        let etaText = "";
+        if (this.completed > 0 && this.completed < this.total) {
+            const eta = this.statistics.estimatedTimeRemaining;
+            if (eta < 60) {
+                etaText = ` | ETA: ${Math.round(eta)}s`;
+            }
+            else if (eta < 3600) {
+                etaText = ` | ETA: ${Math.floor(eta / 60)}m ${Math.round(eta % 60)}s`;
+            }
+            else {
+                etaText = ` | ETA: ${Math.floor(eta / 3600)}h ${Math.floor((eta % 3600) / 60)}m`;
+            }
+        }
+        const spinner = final ? "[OK]" : this._spinnerFrames[this._spinnerIndex];
+        const text = `${spinner} ${langInfo}${bar} ${percent.toFixed(1)}% | ${this.completed}/${this.total} items | OK ${this.success} | ERR ${this.failed}${etaText}`;
+        process.stderr.write("\r\x1b[K" + text);
+        if (final) {
+            process.stderr.write("\n");
+        }
+    }
+    _updateStatistics() {
+        if (!this.startTime)
+            return;
+        const elapsed = Date.now() - this.startTime;
+        const averageTime = this.completed > 0 ? elapsed / this.completed : 0;
+        let recentAverage = 0;
+        if (this.recentOperationTimes.length >= 3) {
+            recentAverage =
+                this.recentOperationTimes.reduce((a, b) => a + b, 0) /
+                    this.recentOperationTimes.length;
+        }
+        else {
+            recentAverage = averageTime;
+        }
+        const remaining = Math.max(0, this.total - this.completed);
+        const estimatedTimeRemaining = remaining * Math.min(averageTime, recentAverage);
+        const percentComplete = Math.min(100, Math.max(0, (this.completed / this.total) * 100 || 0));
+        const successRate = this.completed > 0
+            ? Math.min(100, Math.max(0, (this.success / this.completed) * 100))
+            : 0;
+        this.statistics = {
+            avgTimePerItem: averageTime,
+            recentAvgTimePerItem: recentAverage,
+            totalTime: elapsed / 1000, // in seconds
+            estimatedTimeRemaining: estimatedTimeRemaining / 1000, // in seconds
+            itemsPerSecond: this.completed > 0 ? this.completed / (elapsed / 1000) : 0,
+            percentComplete: percentComplete,
+            successRate: successRate,
+            startTime: new Date(this.startTime).toISOString(),
+            estimatedEndTime: new Date(Date.now() + estimatedTimeRemaining).toISOString(),
+        };
+    }
+    _finalReport() {
+        // Progress bar already displays the summary visually
+        // Remove duplicate console output to keep it clean
+    }
+    getStatus() {
+        return {
+            total: this.total,
+            completed: this.completed,
+            success: this.success,
+            failed: this.failed,
+            language: this.language,
+            inProgress: !!(this.startTime && !this.isCompleted),
+            statistics: { ...this.statistics },
+        };
+    }
+    setLogToConsole(value) {
+        this.logToConsole = value;
+    }
+}
+export default ProgressTracker;

package/dist/utils/prompt-templates.js

@@ -0,0 +1,415 @@
+/**
+ * Prompt template utilities for translation and analysis
+ */
+const getLengthInstructions = (options) => {
+    // ... existing getLengthInstructions ...
+    if (!options || typeof options !== "object") {
+        console.warn("Invalid options provided to getLengthInstructions, using defaults");
+        options = {};
+    }
+    const { mode = "smart", lengthControl, targetLang, detectedContext } = options;
+    if (!targetLang || typeof targetLang !== "string") {
+        // Just return basic length instructions without failing
+        return "TRANSLATION LENGTH: Keep translation concise and natural.";
+    }
+    const context = detectedContext?.category || "general";
+    if (mode === "smart" && lengthControl?.rules?.smart) {
+        const langRules = lengthControl.rules.smart.byLanguage?.[targetLang] || {};
+        const contextRules = lengthControl.rules.smart.byContext?.[context] || {};
+        const langMax = typeof langRules.max === "number" ? langRules.max : 0.15;
+        const contextMax = typeof contextRules.max === "number" ? contextRules.max : 0.15;
+        return `TRANSLATION LENGTH REQUIREMENTS [${targetLang}]:
+1. Maximum allowed length: ${Math.round(langMax * 100)}% longer than source
+2. Context-specific [${context}] limit: ${Math.round(contextMax * 100)}% longer than source
+3. Shorter translations are preferred when possible
+4. Maintain semantic completeness while being concise`;
+    }
+    const templates = {
+        strict: () => {
+            const strictLimit = lengthControl?.rules?.strict;
+            const limit = typeof strictLimit === "number" ? strictLimit : 1.0;
+            return `CRITICAL: Translation must not exceed ${Math.round(limit * 100)}% of source length. Prefer shorter translations.`;
+        },
+        flexible: () => {
+            const flexibleLimit = lengthControl?.rules?.flexible;
+            const limit = typeof flexibleLimit === "number" ? flexibleLimit : 1.2;
+            return `IMPORTANT: Keep translation concise. Target length should not exceed source length by more than ${Math.round(limit * 100)}%.`;
+        },
+        exact: () => {
+            const exactLimit = lengthControl?.rules?.exact;
+            const limit = typeof exactLimit === "number" ? exactLimit : 1.05;
+            return `STRICT: Translation must closely match source length (max ${Math.round(limit * 100)}% deviation).`;
+        },
+        relaxed: () => {
+            const relaxedLimit = lengthControl?.rules?.relaxed;
+            const limit = typeof relaxedLimit === "number" ? relaxedLimit : 1.5;
+            return `GUIDELINE: Translation should be concise but can be up to ${Math.round(limit * 100)}% longer if needed.`;
+        },
+    };
+    const templateFn = templates[mode];
+    if (typeof templateFn === "function") {
+        try {
+            return templateFn();
+        }
+        catch (error) {
+            console.warn(`Error generating length template for mode ${mode}:`, error.message);
+        }
+    }
+    return "TRANSLATION LENGTH: Keep translation concise and natural.";
+};
+/**
+ * Base translation prompt template
+ */
+const baseTranslationPromptTemplate = (sourceLang, targetLang, text, options = {}) => {
+    if (!sourceLang || typeof sourceLang !== "string") {
+        console.warn("Invalid sourceLang provided to baseTranslationPromptTemplate");
+        sourceLang = "en";
+    }
+    if (!targetLang || typeof targetLang !== "string") {
+        console.warn("Invalid targetLang provided to baseTranslationPromptTemplate");
+        targetLang = "es";
+    }
+    if (typeof text !== "string") {
+        console.warn("Invalid text provided to baseTranslationPromptTemplate");
+        text = "";
+    }
+    if (!options || typeof options !== "object") {
+        console.warn("Invalid options provided to baseTranslationPromptTemplate, using defaults");
+        options = {};
+    }
+    const context = options.detectedContext && typeof options.detectedContext === "object"
+        ? options.detectedContext
+        : {
+            category: "general",
+            confidence: 1.0,
+            prompt: "Provide a natural translation",
+        };
+    const safeContext = {
+        category: context.category || "general",
+        confidence: typeof context.confidence === "number" ? context.confidence : 1.0,
+        prompt: context.prompt || "Provide a natural translation",
+        existingTranslation: context.existingTranslation,
+        similarTranslation: context.similarTranslation,
+    };
+    const lengthInstructions = getLengthInstructions({
+        ...options,
+        targetLang: targetLang, // Pass targetLang explicitly
+        detectedContext: safeContext, // Also pass context
+    });
+    let additionalInstructions = "";
+    if (safeContext.existingTranslation && typeof safeContext.existingTranslation === "string") {
+        const truncatedTranslation = safeContext.existingTranslation.length > 200
+            ? safeContext.existingTranslation.substring(0, 200) + "..."
+            : safeContext.existingTranslation;
+        additionalInstructions = `\nREVISION REQUEST: The existing translation "${truncatedTranslation}" has length issues. Please provide a corrected version that matches the source text length requirements.`;
+    }
+    else if (safeContext.similarTranslation) {
+        const { source, target, similarity } = safeContext.similarTranslation;
+        const simPercent = Math.round(similarity * 100);
+        additionalInstructions = `\nREFERENCE CONTEXT (${simPercent}% Match):
+Previously, a similar phrase: "${source}"
+Was translated as: "${target}"
+Please maintain consistency with this style and vocabulary where appropriate.`;
+    }
+    const formality = options.styleGuide?.formality || "neutral";
+    const toneOfVoice = options.styleGuide?.toneOfVoice || "professional";
+    return `
+Translation Task: ${sourceLang} → ${targetLang}
+${additionalInstructions}
+
+Category: ${safeContext.category}
+Context Instructions: ${safeContext.prompt}
+
+LENGTH CONTROL:
+${lengthInstructions}
+
+STRICT OUTPUT REQUIREMENTS:
+1. RETURN ONLY THE TRANSLATED TEXT
+2. NO EXPLANATIONS OR COMMENTARY
+3. NO <think> BLOCKS OR MARKDOWN
+4. NO QUOTES OR FORMATTING
+5. PRESERVE ALL PLACEHOLDERS EXACTLY AS THEY APPEAR
+
+CRITICAL PLACEHOLDER RULES:
+- Keep ALL placeholders like {message}, {name}, {value} EXACTLY as they appear in the source
+- DO NOT translate placeholder names: {message} must stay {message}, NOT {mesaj} or {mensaje}
+- DO NOT add content around placeholders: {message} must NOT become {mesaj}{message} or Bạn{message}
+- DO NOT modify the curly braces: { and } must remain unchanged
+- Placeholders are variables that will be replaced with dynamic content later
+- Only translate the text AROUND the placeholders, never the placeholders themselves
+
+Style: ${formality}, ${toneOfVoice}
+
+Text to Translate:
+${text}`;
+};
+/**
+ * Base analysis prompt template
+ */
+const baseAnalysisPromptTemplate = (text, options = {}) => {
+    if (typeof text !== "string") {
+        console.warn("Invalid text provided to baseAnalysisPromptTemplate");
+        text = "";
+    }
+    if (!options || typeof options !== "object") {
+        console.warn("Invalid options provided to baseAnalysisPromptTemplate, using defaults");
+        options = {};
+    }
+    let categories = "technical, marketing, legal, defi, ui, general";
+    if (options.categories && typeof options.categories === "object") {
+        try {
+            const categoryKeys = Object.keys(options.categories);
+            if (Array.isArray(categoryKeys) && categoryKeys.length > 0) {
+                categories = categoryKeys.join(", ");
+            }
+        }
+        catch (error) {
+            console.warn("Error processing categories:", error.message);
+        }
+    }
+    const maxTextLength = 1500;
+    const truncatedText = text.length > maxTextLength ? text.substring(0, maxTextLength) + "..." : text;
+    const allowNewCategories = options.allowNewCategories === true;
+    const categoryNote = allowNewCategories
+        ? ", or suggest a new category if none of these fit"
+        : "";
+    return `
+TASK: Analyze the following text and determine its context category.
+
+TEXT TO ANALYZE:
+"""
+${truncatedText}
+"""
+
+AVAILABLE CATEGORIES: ${categories}${categoryNote}
+
+INSTRUCTIONS:
+1. Identify the primary context category of the text
+2. Provide a confidence score (0.0-1.0)
+3. Suggest 3-5 keywords that are relevant to this text
+4. Provide a brief explanation of your categorization
+
+FORMAT YOUR RESPONSE AS JSON:
+{
+  "category": "category_name",
+  "confidence": 0.0-1.0,
+  "keywords": ["keyword1", "keyword2", "keyword3"],
+  "explanation": "Brief explanation of why this category was chosen"
+}
+`;
+};
+// Provider-specific templates for translation
+const translationPrompts = {
+    gemini: (sourceLang, targetLang, text, options) => ({
+        contents: [
+            {
+                parts: [
+                    {
+                        text: `${baseTranslationPromptTemplate(sourceLang, targetLang, text, options)}
+Original Text: "${text}"`,
+                    },
+                ],
+            },
+        ],
+    }),
+    openai: (sourceLang, targetLang, text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: baseTranslationPromptTemplate(sourceLang, targetLang, text, options),
+            },
+            {
+                role: "user",
+                content: text,
+            },
+        ],
+    }),
+    dashscope: (sourceLang, targetLang, text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: baseTranslationPromptTemplate(sourceLang, targetLang, text, options),
+            },
+            {
+                role: "user",
+                content: text,
+            },
+        ],
+    }),
+    deepseek: (sourceLang, targetLang, text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: baseTranslationPromptTemplate(sourceLang, targetLang, text, options),
+            },
+            {
+                role: "user",
+                content: text,
+            },
+        ],
+    }),
+    xai: (sourceLang, targetLang, text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: baseTranslationPromptTemplate(sourceLang, targetLang, text, options),
+            },
+            {
+                role: "user",
+                content: text,
+            },
+        ],
+    }),
+    default: (sourceLang, targetLang, text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: baseTranslationPromptTemplate(sourceLang, targetLang, text, options),
+            },
+            {
+                role: "user",
+                content: text,
+            },
+        ],
+    }),
+};
+// Provider-specific templates for analysis
+const analysisPrompts = {
+    gemini: (text, options) => ({
+        contents: [
+            {
+                parts: [
+                    {
+                        text: baseAnalysisPromptTemplate(text, options),
+                    },
+                ],
+            },
+        ],
+    }),
+    openai: (text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: "You are a context analysis assistant that helps identify the category and context of text.",
+            },
+            {
+                role: "user",
+                content: baseAnalysisPromptTemplate(text, options),
+            },
+        ],
+    }),
+    dashscope: (text, options) => ({
+        model: options.model || "qwen-plus",
+        input: {
+            messages: [
+                {
+                    role: "system",
+                    content: "You are a context analysis assistant that helps identify the category and context of text.",
+                },
+                {
+                    role: "user",
+                    content: baseAnalysisPromptTemplate(text, options),
+                },
+            ],
+        },
+        parameters: {
+            temperature: options.temperature || 0.2,
+            max_tokens: options.maxTokens || 1000,
+        },
+    }),
+    deepseek: (text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: "You are a context analysis assistant that helps identify the category and context of text.",
+            },
+            {
+                role: "user",
+                content: baseAnalysisPromptTemplate(text, options),
+            },
+        ],
+    }),
+    xai: (text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: "You are a context analysis assistant that helps identify the category and context of text.",
+            },
+            {
+                role: "user",
+                content: baseAnalysisPromptTemplate(text, options),
+            },
+        ],
+    }),
+    default: (text, options) => ({
+        messages: [
+            {
+                role: "system",
+                content: "You are a context analysis assistant that helps identify the category and context of text.",
+            },
+            {
+                role: "user",
+                content: baseAnalysisPromptTemplate(text, options),
+            },
+        ],
+    }),
+};
+/**
+ * Get translation prompt
+ */
+const getPrompt = (provider, sourceLang, targetLang, text, options = {}) => {
+    if (!provider || typeof provider !== "string") {
+        console.warn("Invalid provider provided to getPrompt, using default");
+        provider = "default";
+    }
+    if (!sourceLang || typeof sourceLang !== "string") {
+        console.warn("Invalid sourceLang provided to getPrompt, using en");
+        sourceLang = "en";
+    }
+    if (!targetLang || typeof targetLang !== "string") {
+        console.warn("Invalid targetLang provided to getPrompt, using es");
+        targetLang = "es";
+    }
+    if (typeof text !== "string") {
+        console.warn("Invalid text provided to getPrompt, using empty string");
+        text = "";
+    }
+    if (!options || typeof options !== "object") {
+        console.warn("Invalid options provided to getPrompt, using defaults");
+        options = {};
+    }
+    const promptGenerator = translationPrompts[provider] || translationPrompts.default;
+    try {
+        return promptGenerator(sourceLang, targetLang, text, options);
+    }
+    catch (error) {
+        console.error(`Error generating prompt for provider ${provider}:`, error.message);
+        return translationPrompts.default(sourceLang, targetLang, text, options);
+    }
+};
+/**
+ * Get analysis prompt
+ */
+const getAnalysisPrompt = (provider, text, options = {}) => {
+    if (!provider || typeof provider !== "string") {
+        console.warn("Invalid provider provided to getAnalysisPrompt, using default");
+        provider = "default";
+    }
+    if (typeof text !== "string") {
+        console.warn("Invalid text provided to getAnalysisPrompt, using empty string");
+        text = "";
+    }
+    if (!options || typeof options !== "object") {
+        console.warn("Invalid options provided to getAnalysisPrompt, using defaults");
+        options = {};
+    }
+    const promptGenerator = analysisPrompts[provider] || analysisPrompts.default;
+    try {
+        return promptGenerator(text, options);
+    }
+    catch (error) {
+        console.error(`Error generating analysis prompt for provider ${provider}:`, error.message);
+        return analysisPrompts.default(text, options);
+    }
+};
+export { getPrompt, getAnalysisPrompt };