locai 2.1.0

package/dist/providers/base-provider.js

@@ -0,0 +1,230 @@
+/**
+ * Base class for translation providers
+ */
+import ErrorHelper from "../utils/error-helper.js";
+import ConfidenceScorer from "../utils/confidence-scorer.js";
+class BaseProvider {
+    name;
+    config;
+    defaultModel;
+    defaultTemperature;
+    defaultMaxTokens;
+    commonHeaders;
+    constructor(name, config = {}) {
+        this.name = name;
+        this.config = config;
+        this.defaultModel = config.model;
+        this.defaultTemperature = config.temperature || 0.3;
+        this.defaultMaxTokens = config.maxTokens || 2000;
+        this.commonHeaders = {
+            "Content-Type": "application/json",
+            "User-Agent": "locai/1.0",
+        };
+    }
+    async translate(text, sourceLang, targetLang, _options = {}) {
+        throw new Error(`translate method must be implemented by ${this.name} provider`);
+    }
+    async analyze(prompt, options = {}) {
+        throw new Error(`analyze method must be implemented by ${this.name} provider if supported`);
+    }
+    async chat(messages, options = {}) {
+        throw new Error(`chat method must be implemented by ${this.name} provider if supported`);
+    }
+    getApiKey() {
+        throw new Error(`getApiKey method must be implemented by ${this.name} provider`);
+    }
+    getEndpoint() {
+        throw new Error(`getEndpoint method must be implemented by ${this.name} provider`);
+    }
+    validateRequest(text, sourceLang, targetLang) {
+        if (!text || typeof text !== "string") {
+            throw new Error("Text must be a non-empty string");
+        }
+        if (!sourceLang || !targetLang) {
+            throw new Error("Source and target languages are required");
+        }
+        if (text.length > 10000) {
+            throw new Error("Text too long for translation (max 10000 characters)");
+        }
+    }
+    validateResponse(response, providerName) {
+        if (!response) {
+            throw new Error(`No response from ${providerName} API`);
+        }
+        if (!response.data) {
+            throw new Error(`Invalid response format from ${providerName}`);
+        }
+        return true;
+    }
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+    handleApiError(error, providerName) {
+        if (error.response) {
+            const status = error.response.status;
+            const apiMessage = error.response.data?.error?.message || error.response.data?.message || null;
+            // Rate limit error
+            if (status === 429) {
+                const retryAfter = error.response.headers?.["retry-after"] || 60;
+                const limit = error.response.headers?.["x-ratelimit-limit"];
+                const remaining = error.response.headers?.["x-ratelimit-remaining"];
+                throw ErrorHelper.rateLimitError(providerName, {
+                    limit,
+                    current: limit ? limit - remaining : null,
+                    retryAfter,
+                    statusCode: status,
+                });
+            }
+            // Server error (5xx)
+            if (status >= 500) {
+                throw ErrorHelper.serverError(providerName, status, apiMessage);
+            }
+            // Authentication error (401, 403)
+            if (status === 401 || status === 403) {
+                throw ErrorHelper.authError(providerName, status, apiMessage);
+            }
+            // Other API errors
+            const apiError = ErrorHelper.createError("API_RESPONSE_ERROR", {
+                provider: providerName,
+                statusCode: status,
+                apiMessage,
+            });
+            apiError.message = `${providerName} API error (${status})${apiMessage ? `: ${apiMessage}` : ""}`;
+            throw apiError;
+        }
+        // Network errors
+        if (error.code === "ECONNREFUSED" || error.code === "ENOTFOUND") {
+            throw ErrorHelper.networkError(providerName);
+        }
+        // Timeout errors
+        if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+            throw ErrorHelper.timeoutError(providerName, error.config?.timeout);
+        }
+        // Unknown errors - preserve original for debugging
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const unknownError = new Error(`${providerName}: ${error.message}`);
+        unknownError.code = "ERR_UNKNOWN";
+        unknownError.originalError = error;
+        throw unknownError;
+    }
+    generatePrompt(text, sourceLang, targetLang, options = {}) {
+        const context = options.detectedContext;
+        let prompt = `Translate the following text from ${sourceLang} to ${targetLang}`;
+        if (context?.category && context.category !== "general") {
+            const categoryPrompts = {
+                technical: ". Preserve technical terms and variable names exactly as they appear.",
+                defi: ". Keep DeFi and cryptocurrency terms in English.",
+                marketing: ". Use persuasive and engaging language appropriate for marketing.",
+                legal: ". Maintain formal tone and precise legal terminology.",
+                ui: ". Keep UI terms consistent and clear for user interface elements.",
+            };
+            prompt += categoryPrompts[context.category] || "";
+        }
+        if (options.lengthControl?.mode === "strict") {
+            prompt += " Keep the translation length similar to the original.";
+        }
+        const placeholderRegex = /\{[^}]+\}/g;
+        const hasPlaceholders = placeholderRegex.test(text);
+        if (hasPlaceholders) {
+            prompt +=
+                "\n\nCRITICAL: This text contains placeholders like {variable}. You MUST preserve them EXACTLY as they appear. Do NOT translate the placeholder names, do NOT modify the curly braces, and do NOT add any text around them.";
+        }
+        prompt += `\n\nText to translate: "${text}"`;
+        prompt += "\n\nProvide only the translation without explanations or quotes.";
+        return prompt;
+    }
+    getConfig(options = {}) {
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            throw new Error(`API key not configured for ${this.name} provider`);
+        }
+        return {
+            model: options.model || this.defaultModel,
+            temperature: options.temperature ?? this.defaultTemperature,
+            maxTokens: options.maxTokens || this.defaultMaxTokens,
+            max_tokens: options.maxTokens || this.defaultMaxTokens, // Backward compatibility
+            apiKey: apiKey,
+            endpoint: this.getEndpoint(),
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+    extractTranslation(response, providerName) {
+        // Check for error response first
+        if (response.error) {
+            const errorMsg = response.error.message || response.error.error || JSON.stringify(response.error);
+            throw new Error(`api: ${providerName} - ${errorMsg}`);
+        }
+        let translation = null;
+        if (response.choices && response.choices[0]?.message?.content) {
+            translation = response.choices[0].message.content.trim();
+        }
+        else if (response.choices && response.choices[0]?.text) {
+            translation = response.choices[0].text.trim();
+        }
+        else if (response.choices && response.choices[0]?.delta?.content) {
+            translation = response.choices[0].delta.content.trim();
+        }
+        else if (response.candidates && response.candidates[0]?.content?.parts?.[0]?.text) {
+            translation = response.candidates[0].content.parts[0].text.trim();
+        }
+        else if (response.output && response.output.text) {
+            translation = response.output.text.trim();
+        }
+        else if (response.text) {
+            translation = response.text.trim();
+        }
+        else if (response.content) {
+            translation = response.content.trim();
+        }
+        else if (response.data &&
+            response.data.choices &&
+            response.data.choices[0]?.message?.content) {
+            translation = response.data.choices[0].message.content.trim();
+        }
+        if (!translation) {
+            console.error(`Unable to extract translation from ${providerName} response. Response structure:`, {
+                keys: Object.keys(response),
+                choices: response.choices ? `Array(${response.choices.length})` : "undefined",
+                choicesStructure: response.choices && response.choices[0]
+                    ? Object.keys(response.choices[0])
+                    : "undefined",
+            });
+            throw new Error(`Unable to extract translation from ${providerName} response`);
+        }
+        return translation;
+    }
+    /**
+     * Extract translation with confidence score
+     */
+    extractTranslationWithConfidence(
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+    response, providerName, sourceText, sourceLang, targetLang, category = "general") {
+        const translation = this.extractTranslation(response, providerName);
+        // Extract AI confidence from response
+        const aiConfidence = ConfidenceScorer.extractAIConfidence(response, providerName);
+        // Calculate comprehensive confidence score
+        const confidenceResult = ConfidenceScorer.calculateConfidence({
+            aiConfidence,
+            sourceText,
+            translation,
+            sourceLang,
+            targetLang,
+            provider: providerName,
+            category,
+        });
+        return {
+            translation,
+            confidence: confidenceResult,
+            rawResponse: response,
+        };
+    }
+    sanitizeTranslation(translation) {
+        if (!translation || typeof translation !== "string") {
+            throw new Error("Invalid translation format");
+        }
+        return translation
+            .replace(/^["']|["']$/g, "")
+            .replace(/^\s*Translation:\s*/i, "")
+            .replace(/^\s*Result:\s*/i, "")
+            .trim();
+    }
+}
+export default BaseProvider;

package/dist/providers/dashscope.js

@@ -0,0 +1,128 @@
+import axios from "axios";
+import BaseProvider from "./base-provider.js";
+import { getPrompt, getAnalysisPrompt } from "../utils/prompt-templates.js";
+import RetryHelper from "../utils/retry-helper.js";
+/**
+ * Provider implementation for Alibaba DashScope (Qwen) models.
+ */
+class DashScopeProvider extends BaseProvider {
+    client;
+    generationClient;
+    /**
+     * Create a new DashScopeProvider instance.
+     * @param {ProviderConfig} config - Provider configuration.
+     */
+    constructor(config = {}) {
+        super("dashscope", config);
+        this.client = axios.create({
+            baseURL: "https://dashscope-intl.aliyuncs.com",
+            headers: {
+                ...this.commonHeaders,
+                Authorization: `Bearer ${this.getApiKey()}`,
+            },
+            timeout: 30000,
+            maxRedirects: 0,
+            validateStatus: (status) => status < 500,
+        });
+        // Generation client for analysis
+        this.generationClient = axios.create({
+            baseURL: "https://dashscope.aliyuncs.com/api/v1/services/aigc",
+            headers: {
+                ...this.commonHeaders,
+                Authorization: `Bearer ${this.getApiKey()}`,
+            },
+            timeout: 30000,
+            maxRedirects: 0,
+            validateStatus: (status) => status < 500,
+        });
+    }
+    getApiKey() {
+        return process.env.DASHSCOPE_API_KEY;
+    }
+    getEndpoint() {
+        return "/compatible-mode/v1/chat/completions";
+    }
+    getGenerationEndpoint() {
+        return "/text-generation/generation";
+    }
+    /**
+     * Translate text using DashScope.
+     */
+    async translate(text, sourceLang, targetLang, options = {}) {
+        this.validateRequest(text, sourceLang, targetLang);
+        const config = this.getConfig(options.apiConfig?.dashscope);
+        const promptData = getPrompt("dashscope", sourceLang, targetLang, text, options);
+        return RetryHelper.withRetry(async () => {
+            try {
+                const response = await this.client.post(this.getEndpoint(), {
+                    model: config.model || "qwen-plus",
+                    ...promptData,
+                    temperature: config.temperature || 0.3,
+                    max_tokens: config.maxTokens || 2000,
+                });
+                this.validateResponse(response, this.name);
+                const translation = this.extractTranslation(response.data, this.name);
+                return this.sanitizeTranslation(translation);
+            }
+            catch (error) {
+                this.handleApiError(error, this.name);
+                throw error;
+            }
+        }, {
+            maxRetries: options.retryOptions?.maxRetries || 2,
+            initialDelay: options.retryOptions?.initialDelay || 1000,
+            context: "DashScope Provider",
+            logContext: {
+                source: sourceLang,
+                target: targetLang,
+            },
+        });
+    }
+    async analyze(prompt, options = {}) {
+        const config = this.getConfig({
+            model: options.model || "qwen-plus",
+            temperature: options.temperature || 0.2,
+            maxTokens: options.maxTokens || 1000,
+        });
+        const promptData = getAnalysisPrompt("dashscope", prompt, {
+            ...options,
+            ...config,
+        });
+        return RetryHelper.withRetry(async () => {
+            try {
+                const response = await this.generationClient.post(this.getGenerationEndpoint(), {
+                    ...promptData,
+                });
+                if (!response.data?.output?.text) {
+                    throw new Error("Invalid response format from DashScope API");
+                }
+                const result = response.data.output.text.trim();
+                return this.sanitizeTranslation(result);
+            }
+            catch (error) {
+                this.handleApiError(error, this.name);
+                throw error;
+            }
+        }, {
+            maxRetries: options.maxRetries || 2,
+            initialDelay: options.initialDelay || 1000,
+            context: "DashScope Provider Analysis",
+        });
+    }
+}
+// Lazy singleton - created on first use
+let dashscopeProvider = null;
+function getProvider() {
+    if (!dashscopeProvider) {
+        dashscopeProvider = new DashScopeProvider();
+    }
+    return dashscopeProvider;
+}
+// Export both class and legacy functions
+async function translate(text, sourceLang, targetLang, options = {}) {
+    return getProvider().translate(text, sourceLang, targetLang, options);
+}
+async function analyze(prompt, options = {}) {
+    return getProvider().analyze(prompt, options);
+}
+export { translate, analyze, DashScopeProvider };

package/dist/providers/deepseek.js

@@ -0,0 +1,111 @@
+import axios from "axios";
+import BaseProvider from "./base-provider.js";
+import { getPrompt, getAnalysisPrompt } from "../utils/prompt-templates.js";
+import RetryHelper from "../utils/retry-helper.js";
+/**
+ * Provider implementation for DeepSeek API.
+ */
+class DeepSeekProvider extends BaseProvider {
+    client;
+    /**
+     * Create a new DeepSeekProvider instance.
+     * @param {ProviderConfig} config - Provider configuration.
+     */
+    constructor(config = {}) {
+        super("deepseek", config);
+        this.client = axios.create({
+            baseURL: "https://api.deepseek.com/v1",
+            headers: {
+                ...this.commonHeaders,
+                Authorization: `Bearer ${this.getApiKey()}`,
+            },
+            timeout: 45000,
+            maxRedirects: 0,
+            validateStatus: (status) => status < 500,
+        });
+    }
+    getApiKey() {
+        return process.env.DEEPSEEK_API_KEY;
+    }
+    getEndpoint() {
+        return "/chat/completions";
+    }
+    /**
+     * Translate text using DeepSeek.
+     */
+    async translate(text, sourceLang, targetLang, options = {}) {
+        this.validateRequest(text, sourceLang, targetLang);
+        const config = this.getConfig(options.apiConfig?.deepseek);
+        const promptData = getPrompt("deepseek", sourceLang, targetLang, text, options);
+        return RetryHelper.withRetry(async () => {
+            try {
+                const response = await this.client.post(this.getEndpoint(), {
+                    model: config.model || "deepseek-chat",
+                    ...promptData,
+                    temperature: config.temperature || 0.3,
+                    max_tokens: config.maxTokens || 2000,
+                });
+                this.validateResponse(response, this.name);
+                const translation = this.extractTranslation(response.data, this.name);
+                return this.sanitizeTranslation(translation);
+            }
+            catch (error) {
+                this.handleApiError(error, this.name);
+                throw error;
+            }
+        }, {
+            maxRetries: options.retryOptions?.maxRetries || 3,
+            initialDelay: options.retryOptions?.initialDelay || 2000,
+            context: "DeepSeek Provider",
+            logContext: {
+                source: sourceLang,
+                target: targetLang,
+            },
+        });
+    }
+    async analyze(prompt, options = {}) {
+        const config = this.getConfig({
+            model: options.model || "deepseek-chat",
+            temperature: options.temperature || 0.2,
+            maxTokens: options.maxTokens || 1000,
+        });
+        const promptData = getAnalysisPrompt("deepseek", prompt, options);
+        return RetryHelper.withRetry(async () => {
+            try {
+                const response = await this.client.post(this.getEndpoint(), {
+                    model: config.model,
+                    ...promptData,
+                    temperature: config.temperature,
+                    max_tokens: config.maxTokens,
+                });
+                this.validateResponse(response, this.name);
+                const result = this.extractTranslation(response.data, this.name);
+                return this.sanitizeTranslation(result);
+            }
+            catch (error) {
+                this.handleApiError(error, this.name);
+                throw error;
+            }
+        }, {
+            maxRetries: options.maxRetries || 2,
+            initialDelay: options.initialDelay || 1000,
+            context: "DeepSeek Provider Analysis",
+        });
+    }
+}
+// Lazy singleton - created on first use
+let deepseekProvider = null;
+function getProvider() {
+    if (!deepseekProvider) {
+        deepseekProvider = new DeepSeekProvider();
+    }
+    return deepseekProvider;
+}
+// Export both class and legacy functions
+async function translate(text, sourceLang, targetLang, options = {}) {
+    return getProvider().translate(text, sourceLang, targetLang, options);
+}
+async function analyze(prompt, options = {}) {
+    return getProvider().analyze(prompt, options);
+}
+export { translate, analyze, DeepSeekProvider };

package/dist/providers/gemini.js

@@ -0,0 +1,135 @@
+import axios from "axios";
+import BaseProvider from "./base-provider.js";
+import { getPrompt, getAnalysisPrompt } from "../utils/prompt-templates.js";
+import RetryHelper from "../utils/retry-helper.js";
+/**
+ * Provider implementation for Google Gemini models.
+ */
+class GeminiProvider extends BaseProvider {
+    client;
+    /**
+     * Create a new GeminiProvider instance.
+     * @param {ProviderConfig} config - Provider configuration.
+     */
+    constructor(config = {}) {
+        super("gemini", config);
+        this.client = axios.create({
+            baseURL: "https://generativelanguage.googleapis.com/v1beta",
+            headers: {
+                ...this.commonHeaders,
+            },
+            timeout: 30000,
+            maxRedirects: 0,
+            validateStatus: (status) => status < 500,
+        });
+    }
+    getApiKey() {
+        return process.env.GEMINI_API_KEY;
+    }
+    getEndpoint(model) {
+        return `/models/${model || "gemini-2.0-flash-exp"}:generateContent`;
+    }
+    /**
+     * Translate text using Gemini.
+     */
+    async translate(text, sourceLang, targetLang, options = {}) {
+        this.validateRequest(text, sourceLang, targetLang);
+        const config = this.getConfig(options.apiConfig?.gemini);
+        const model = config.model || "gemini-2.0-flash-exp";
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            throw new Error("GEMINI_API_KEY environment variable not found");
+        }
+        const promptData = getPrompt("gemini", sourceLang, targetLang, text, options);
+        return RetryHelper.withRetry(async () => {
+            try {
+                const response = await this.client.post(this.getEndpoint(model), {
+                    ...promptData,
+                    generationConfig: {
+                        temperature: config.temperature || 0.3,
+                        maxOutputTokens: config.maxTokens || 2048,
+                    },
+                }, {
+                    params: { key: apiKey },
+                });
+                if (!response.data?.candidates || response.data.candidates.length === 0) {
+                    throw new Error("Failed to get translation candidate from Gemini API");
+                }
+                if (!response.data.candidates[0]?.content?.parts?.[0]?.text) {
+                    throw new Error("Invalid response format from Gemini API");
+                }
+                const translation = response.data.candidates[0].content.parts[0].text.trim();
+                return this.sanitizeTranslation(translation);
+            }
+            catch (error) {
+                this.handleApiError(error, this.name);
+                throw error;
+            }
+        }, {
+            maxRetries: options.retryOptions?.maxRetries || 2,
+            initialDelay: options.retryOptions?.initialDelay || 1000,
+            context: "Gemini Provider",
+            logContext: {
+                source: sourceLang,
+                target: targetLang,
+            },
+        });
+    }
+    async analyze(prompt, options = {}) {
+        const config = this.getConfig({
+            model: options.model || "gemini-2.0-flash-exp",
+            temperature: options.temperature || 0.2,
+            maxTokens: options.maxTokens || 1000,
+        });
+        const apiKey = this.getApiKey();
+        if (!apiKey) {
+            throw new Error("GEMINI_API_KEY environment variable not found");
+        }
+        const promptData = getAnalysisPrompt("gemini", prompt, options);
+        return RetryHelper.withRetry(async () => {
+            try {
+                const response = await this.client.post(this.getEndpoint(config.model), {
+                    ...promptData,
+                    generationConfig: {
+                        temperature: config.temperature,
+                        maxOutputTokens: config.maxTokens,
+                    },
+                }, {
+                    params: { key: apiKey },
+                });
+                if (!response.data?.candidates || response.data.candidates.length === 0) {
+                    throw new Error("Failed to get analysis result from Gemini API");
+                }
+                if (!response.data.candidates[0]?.content?.parts?.[0]?.text) {
+                    throw new Error("Invalid response format from Gemini API");
+                }
+                const result = response.data.candidates[0].content.parts[0].text.trim();
+                return this.sanitizeTranslation(result);
+            }
+            catch (error) {
+                this.handleApiError(error, this.name);
+                throw error;
+            }
+        }, {
+            maxRetries: options.maxRetries || 2,
+            initialDelay: options.initialDelay || 1000,
+            context: "Gemini Provider Analysis",
+        });
+    }
+}
+// Lazy singleton - created on first use
+let geminiProvider = null;
+function getProvider() {
+    if (!geminiProvider) {
+        geminiProvider = new GeminiProvider();
+    }
+    return geminiProvider;
+}
+// Export both class and legacy functions
+async function translate(text, sourceLang, targetLang, options = {}) {
+    return getProvider().translate(text, sourceLang, targetLang, options);
+}
+async function analyze(prompt, options = {}) {
+    return getProvider().analyze(prompt, options);
+}
+export { translate, analyze, GeminiProvider };