ai-l10n-core 1.4.0

package/dist/translationService.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.L10nTranslationService = exports.FinishReason = exports.FileSchema = void 0;
+const consoleLogger_1 = require("./consoleLogger");
+const constants_1 = require("./constants");
+/**
+ * Supported file schema formats for translation requests.
+ * Used to enable schema-specific translation handling.
+ */
+var FileSchema;
+(function (FileSchema) {
+    /** OpenAPI specification format */
+    FileSchema["OpenAPI"] = "openApi";
+    /** Flutter ARB (Application Resource Bundle) format */
+    FileSchema["ARBFlutter"] = "arbFlutter";
+})(FileSchema || (exports.FileSchema = FileSchema = {}));
+var FinishReason;
+(function (FinishReason) {
+    FinishReason["stop"] = "stop";
+    FinishReason["length"] = "length";
+    FinishReason["contentFilter"] = "contentFilter";
+    FinishReason["insufficientBalance"] = "insufficientBalance";
+    FinishReason["error"] = "error";
+})(FinishReason || (exports.FinishReason = FinishReason = {}));
+// ── Translation Service ─────────────────────────────────────────────────────
+class L10nTranslationService {
+    constructor(logger = new consoleLogger_1.ConsoleLogger()) {
+        this.logger = logger;
+    }
+    async getLanguages(options) {
+        const url = new URL(`${constants_1.URLS.API_BASE}/v2/languages`);
+        if (options?.codes) {
+            for (const c of options.codes) {
+                url.searchParams.append("c", c);
+            }
+        }
+        if (options?.proficiencyLevels) {
+            for (const p of options.proficiencyLevels) {
+                url.searchParams.append("p", p);
+            }
+        }
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            throw new Error(`Failed to get languages: ${response.status} ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    async predictLanguages(input, limit = 10) {
+        const url = new URL(`${constants_1.URLS.API_BASE}/v2/languages/predict`);
+        url.searchParams.append("input", input);
+        url.searchParams.append("limit", limit.toString());
+        this.logger.logInfo(`Predicting languages for input (${input.length} characters)`);
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            this.logger.logWarning(`Language prediction failed - ${response.status} ${response.statusText}`);
+            const error = new Error(`Failed to predict languages: ${response.statusText}`);
+            throw error;
+        }
+        const result = (await response.json());
+        this.logger.logInfo(`Successfully predicted ${result.languages.length} languages`);
+        return result.languages;
+    }
+    async translate(request, apiKey) {
+        if (!apiKey) {
+            this.logger.showAndLogError("API Key not set. Please configure your API Key first.", null, "", "Get API Key", constants_1.URLS.API_KEYS);
+            return null;
+        }
+        this.logger.logInfo(`Starting translation to ${request.targetLanguageCode}`);
+        const response = await fetch(`${constants_1.URLS.API_BASE}/v2/translate`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": apiKey,
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            let errorMessage;
+            let errorData = null;
+            // Try to parse error response body
+            try {
+                errorData = await response.json();
+            }
+            catch {
+                // Ignore JSON parsing errors
+            }
+            this.logger.logWarning(`Translation API error - ${response.status} ${response.statusText}`);
+            if (errorData) {
+                this.logger.logWarning(`API error details - ${JSON.stringify(errorData)}`);
+            }
+            switch (response.status) {
+                case 400: {
+                    // Try to extract validation errors from the error response
+                    let validationMessage = "Invalid request. Please check your input and try again.";
+                    if (errorData && errorData.errors) {
+                        const errorDetails = errorData.errors;
+                        if (Array.isArray(errorDetails)) {
+                            validationMessage = errorDetails.join(" ");
+                        }
+                        else if (typeof errorDetails === "object") {
+                            validationMessage = Object.values(errorDetails)
+                                .map((v) => (Array.isArray(v) ? v.join(" ") : v))
+                                .join(" ");
+                        }
+                    }
+                    errorMessage = validationMessage;
+                    break;
+                }
+                case 401:
+                    errorMessage = "Unauthorized. Please check your API Key.";
+                    this.logger.showAndLogError(errorMessage, errorData, "", "Get API Key", constants_1.URLS.API_KEYS);
+                    return null;
+                case 402: {
+                    // Try to extract required characters from the error response
+                    let message = "Not enough characters remaining for this translation. You can try translating a smaller portion of your file or purchase more characters.";
+                    const requiredBalance = errorData?.data?.requiredBalance;
+                    if (requiredBalance) {
+                        const currentBalance = errorData?.data?.currentBalance ?? 0;
+                        message = `This translation requires ${requiredBalance.toLocaleString()} characters, but you only have ${currentBalance.toLocaleString()} characters available. You can try translating a smaller portion of your file or purchase more characters.`;
+                    }
+                    this.logger.showAndLogError(message, errorData, "", "Visit l10n.dev", constants_1.URLS.PRICING);
+                    return null;
+                }
+                case 413:
+                    errorMessage = "Request too large. Maximum request size is 5 MB.";
+                    break;
+                case 500:
+                    errorMessage = `An internal server error occurred (Error code: ${errorData?.errorCode || "unknown"}). Please try again later.`;
+                    break;
+                default:
+                    errorMessage =
+                        "Failed to translate. Please check your connection and try again.";
+            }
+            throw new Error(errorMessage);
+        }
+        const result = (await response.json());
+        // Handle finish reasons
+        if (result.finishReason) {
+            if (result.finishReason !== FinishReason.stop) {
+                this.logger.logWarning(`Translation finished with reason: ${result.finishReason}`);
+            }
+            switch (result.finishReason) {
+                case FinishReason.insufficientBalance:
+                    const message = `Not enough characters remaining for this translation. You can try translating a smaller portion of your file or purchase more characters.`;
+                    this.logger.showAndLogError(message, undefined, "", "Visit l10n.dev", constants_1.URLS.PRICING);
+                    return result;
+                case FinishReason.error:
+                    throw new Error("Translation failed due to an error.");
+                // Note: FinishReason.contentFilter and FinishReason.length return partial results with filteredStrings
+            }
+        }
+        return result;
+    }
+}
+exports.L10nTranslationService = L10nTranslationService;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ai-l10n-core",
+  "version": "1.4.0",
+  "description": "Platform-independent core for AI-powered localization — translation API client, language utilities, and shared types",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "mocha",
+    "verify": "node scripts/verify.js"
+  },
+  "keywords": [
+    "localization",
+    "l10n",
+    "i18n",
+    "translation",
+    "ai",
+    "sdk",
+    "api",
+    "typescript",
+    "core"
+  ],
+  "author": "l10n.dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/l10n-dev/ai-l10n.git",
+    "directory": "core"
+  },
+  "homepage": "https://github.com/l10n-dev/ai-l10n#readme",
+  "bugs": {
+    "url": "https://github.com/l10n-dev/ai-l10n/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.17.10",
+    "@types/sinon": "^17.0.3",
+    "mocha": "^11.0.1",
+    "sinon": "^19.0.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.0"
+  }
+}