ai-l10n-core 1.4.0

package/dist/test/translationService.test.js

@@ -0,0 +1,454 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const assert = __importStar(require("assert"));
+const sinon = __importStar(require("sinon"));
+const constants_1 = require("../constants");
+const translationService_1 = require("../translationService");
+// Mock fetch globally
+const mockFetch = sinon.stub();
+global.fetch = mockFetch;
+// Mock URL constructor
+global.URL = function (url) {
+    this.searchParams = {
+        append: sinon.stub(),
+    };
+    this.toString = () => url;
+};
+suite("L10nTranslationService Test Suite", () => {
+    let service;
+    let mockLogger;
+    // Helper function to create a proper translation request
+    const createRequest = (overrides = {}) => ({
+        sourceStrings: JSON.stringify({}),
+        targetLanguageCode: "es",
+        useContractions: false,
+        useShortening: false,
+        returnTranslationsAsString: true,
+        client: "test",
+        schema: null,
+        ...overrides,
+    });
+    setup(() => {
+        // Reset all stubs
+        sinon.resetHistory();
+        // Reset fetch mock
+        mockFetch.reset();
+        // Create mock logger
+        mockLogger = {
+            logInfo: sinon.stub(),
+            logWarning: sinon.stub(),
+            logError: sinon.stub(),
+            showAndLogError: sinon.stub(),
+        };
+        // Create service instance with mocked logger only
+        service = new translationService_1.L10nTranslationService(mockLogger);
+    });
+    teardown(() => {
+        sinon.restore();
+    });
+    suite("Language Prediction", () => {
+        test("predictLanguages returns parsed results on success", async () => {
+            const mockResponse = {
+                languages: [
+                    { code: "es", name: "Spanish" },
+                    { code: "fr", name: "French" },
+                ],
+            };
+            const mockFetchResponse = {
+                ok: true,
+                json: sinon.stub().resolves(mockResponse),
+            };
+            mockFetch.resolves(mockFetchResponse);
+            const result = await service.predictLanguages("spanish", 5);
+            assert.strictEqual(result.length, 2);
+            assert.deepStrictEqual(result, mockResponse.languages);
+        });
+        test("predictLanguages throws error on failed API call", async () => {
+            const mockFetchResponse = {
+                ok: false,
+                statusText: "Bad Request",
+            };
+            mockFetch.resolves(mockFetchResponse);
+            await assert.rejects(async () => await service.predictLanguages("test"), /Failed to predict languages: Bad Request/);
+        });
+    });
+    suite("JSON Translation", () => {
+        test("translate returns null when no API Key is set", async () => {
+            const result = await service.translate(createRequest(), "");
+            assert.strictEqual(result, null);
+            // Verify error was logged
+            assert.ok(mockLogger.showAndLogError.called);
+        });
+        test("translate makes correct API call with valid API Key", async () => {
+            const apiKey = "valid-api-key";
+            const sourceStrings = { hello: "Hello", world: "World" };
+            const targetLanguage = "es";
+            const useContractions = false;
+            const useShortening = true;
+            const request = {
+                sourceStrings: JSON.stringify(sourceStrings),
+                targetLanguageCode: targetLanguage,
+                useContractions,
+                useShortening,
+                returnTranslationsAsString: true,
+                client: "test",
+                schema: null,
+            };
+            const mockTranslationResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "Hola", world: "Mundo" }),
+                usage: { charsUsed: 10 },
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockFetchResponse = {
+                ok: true,
+                json: sinon.stub().resolves(mockTranslationResult),
+            };
+            mockFetch.resolves(mockFetchResponse);
+            const result = await service.translate(request, apiKey);
+            assert.deepStrictEqual(result, mockTranslationResult);
+            // Verify fetch was called with correct parameters
+            assert.ok(mockFetch.called);
+            const fetchCall = mockFetch.getCall(0);
+            assert.strictEqual(fetchCall.args[0], `${constants_1.URLS.API_BASE}/v2/translate`);
+            const requestOptions = fetchCall.args[1];
+            assert.strictEqual(requestOptions.method, "POST");
+            assert.strictEqual(requestOptions.headers["Content-Type"], "application/json");
+            assert.strictEqual(requestOptions.headers["X-API-Key"], apiKey);
+            const requestBody = JSON.parse(requestOptions.body);
+            assert.strictEqual(requestBody.sourceStrings, JSON.stringify(sourceStrings));
+            assert.strictEqual(requestBody.targetLanguageCode, targetLanguage);
+            assert.strictEqual(requestBody.useContractions, false);
+            assert.strictEqual(requestBody.useShortening, true);
+            assert.strictEqual(requestBody.returnTranslationsAsString, true);
+            assert.strictEqual(requestBody.client, "test");
+            assert.strictEqual(requestBody.schema, null);
+        });
+        test("includes translateMetadata in API request when set to true", async () => {
+            const apiKey = "valid-api-key";
+            const request = {
+                sourceStrings: JSON.stringify({ hello: "Hello" }),
+                targetLanguageCode: "es",
+                useContractions: true,
+                useShortening: false,
+                translateMetadata: true,
+                returnTranslationsAsString: true,
+                client: "test",
+                schema: null,
+            };
+            const mockTranslationResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "Hola" }),
+                usage: { charsUsed: 10 },
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockFetchResponse = {
+                ok: true,
+                json: sinon.stub().resolves(mockTranslationResult),
+            };
+            mockFetch.resolves(mockFetchResponse);
+            await service.translate(request, apiKey);
+            const fetchCall = mockFetch.getCall(0);
+            const requestOptions = fetchCall.args[1];
+            const requestBody = JSON.parse(requestOptions.body);
+            assert.strictEqual(requestBody.translateMetadata, true);
+        });
+        test("includes translateMetadata in API request when set to false", async () => {
+            const apiKey = "valid-api-key";
+            const request = {
+                sourceStrings: JSON.stringify({ hello: "Hello" }),
+                targetLanguageCode: "es",
+                useContractions: true,
+                useShortening: false,
+                translateMetadata: false,
+                returnTranslationsAsString: true,
+                client: "test",
+                schema: null,
+            };
+            const mockTranslationResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "Hola" }),
+                usage: { charsUsed: 10 },
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockFetchResponse = {
+                ok: true,
+                json: sinon.stub().resolves(mockTranslationResult),
+            };
+            mockFetch.resolves(mockFetchResponse);
+            await service.translate(request, apiKey);
+            const fetchCall = mockFetch.getCall(0);
+            const requestOptions = fetchCall.args[1];
+            const requestBody = JSON.parse(requestOptions.body);
+            assert.strictEqual(requestBody.translateMetadata, false);
+        });
+        test("translate handles 400 Bad Request error", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 400,
+                json: sinon.stub().resolves({
+                    errors: ["Invalid source strings format"],
+                }),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /Invalid source strings format/);
+        });
+        test("translate handles 401 Unauthorized error", async () => {
+            const apiKey = "invalid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 401,
+                json: sinon.stub().resolves({}),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            // 401 errors now return null instead of throwing
+            assert.strictEqual(result, null);
+            // Verify error was logged
+            assert.ok(mockLogger.showAndLogError.called);
+        });
+        test("translate handles 402 Payment Required error with specific message", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 402,
+                json: sinon.stub().resolves({
+                    data: {
+                        requiredBalance: 1000,
+                        currentBalance: 500,
+                    },
+                }),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            // 402 errors now return null instead of throwing
+            assert.strictEqual(result, null);
+        });
+        test("translate handles 413 Request Too Large error", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 413,
+                json: sinon.stub().resolves({}),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /Request too large. Maximum request size is 5 MB./);
+        });
+        test("translate handles 500 Internal Server Error", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 500,
+                json: sinon.stub().resolves({
+                    errorCode: "INTERNAL_ERROR_123",
+                }),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /An internal server error occurred \(Error code: INTERNAL_ERROR_123\)/);
+        });
+    });
+    suite("Error Handling", () => {
+        test("handles complex validation error structure", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 400,
+                json: sinon.stub().resolves({
+                    errors: {
+                        sourceStrings: ["is required"],
+                        targetLanguageCode: ["is invalid", "must be BCP-47 format"],
+                    },
+                }),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /is required is invalid must be BCP-47 format/);
+        });
+        test("handles array validation error structure", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 400,
+                json: sinon.stub().resolves({
+                    errors: ["Field validation failed", "Invalid input format"],
+                }),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /Field validation failed Invalid input format/);
+        });
+        test("handles JSON parsing failure in error response", async () => {
+            const apiKey = "valid-api-key";
+            const mockErrorResponse = {
+                ok: false,
+                status: 500,
+                json: sinon.stub().rejects(new Error("JSON parse error")),
+            };
+            mockFetch.resolves(mockErrorResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /An internal server error occurred \(Error code: unknown\)/);
+        });
+    });
+    suite("Finish Reason Handling", () => {
+        test("handles insufficientBalance finish reason", async () => {
+            const apiKey = "valid-api-key";
+            const expectedResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "hola" }),
+                usage: { charsUsed: 5 },
+                finishReason: "insufficientBalance",
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockResponse = {
+                ok: true,
+                json: sinon.stub().resolves(expectedResult),
+            };
+            mockFetch.resolves(mockResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            // insufficientBalance finish reason now returns result with partial translations
+            assert.deepStrictEqual(result, expectedResult);
+            // Verify error was logged
+            assert.ok(mockLogger.showAndLogError.called);
+        });
+        test("throws error for error finish reason", async () => {
+            const apiKey = "valid-api-key";
+            const mockResponse = {
+                ok: true,
+                json: sinon.stub().resolves({
+                    targetLanguageCode: "es",
+                    translations: JSON.stringify({ hello: "hola" }),
+                    usage: { charsUsed: 5 },
+                    finishReason: "error",
+                    completedChunks: 1,
+                    totalChunks: 1,
+                }),
+            };
+            mockFetch.resolves(mockResponse);
+            await assert.rejects(async () => await service.translate(createRequest(), apiKey), /Translation failed due to an error\./);
+        });
+        test("does not throw error for length finish reason", async () => {
+            const apiKey = "valid-api-key";
+            const expectedResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "hola" }),
+                usage: { charsUsed: 5 },
+                finishReason: "length",
+                filteredStrings: '{"hello":"hola"}',
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockResponse = {
+                ok: true,
+                json: sinon.stub().resolves({
+                    targetLanguageCode: "es",
+                    translations: JSON.stringify({ hello: "hola" }),
+                    usage: { charsUsed: 5 },
+                    finishReason: "length",
+                    filteredStrings: '{"hello":"hola"}',
+                    completedChunks: 1,
+                    totalChunks: 1,
+                }),
+            };
+            mockFetch.resolves(mockResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            assert.deepStrictEqual(result, expectedResult);
+        });
+        test("does not throw error for contentFilter finish reason", async () => {
+            const apiKey = "valid-api-key";
+            const expectedResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "hola" }),
+                usage: { charsUsed: 5 },
+                finishReason: "contentFilter",
+                filteredStrings: '{"hello":"hola"}',
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockResponse = {
+                ok: true,
+                json: sinon.stub().resolves({
+                    targetLanguageCode: "es",
+                    translations: JSON.stringify({ hello: "hola" }),
+                    usage: { charsUsed: 5 },
+                    finishReason: "contentFilter",
+                    filteredStrings: '{"hello":"hola"}',
+                    completedChunks: 1,
+                    totalChunks: 1,
+                }),
+            };
+            mockFetch.resolves(mockResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            assert.deepStrictEqual(result, expectedResult);
+        });
+        test("does not throw error for stop finish reason", async () => {
+            const apiKey = "valid-api-key";
+            const expectedResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "hola" }),
+                usage: { charsUsed: 5 },
+                finishReason: "stop",
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockResponse = {
+                ok: true,
+                json: sinon.stub().resolves(expectedResult),
+            };
+            mockFetch.resolves(mockResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            assert.deepStrictEqual(result, expectedResult);
+        });
+        test("works normally when no finish reason is present", async () => {
+            const apiKey = "valid-api-key";
+            const expectedResult = {
+                targetLanguageCode: "es",
+                translations: JSON.stringify({ hello: "hola" }),
+                usage: { charsUsed: 5 },
+                completedChunks: 1,
+                totalChunks: 1,
+            };
+            const mockResponse = {
+                ok: true,
+                json: sinon.stub().resolves(expectedResult),
+            };
+            mockFetch.resolves(mockResponse);
+            const result = await service.translate(createRequest(), apiKey);
+            assert.deepStrictEqual(result, expectedResult);
+        });
+    });
+});

package/dist/translationService.d.ts

@@ -0,0 +1,94 @@
+import { ILogger } from "./logger";
+/**
+ * Supported file schema formats for translation requests.
+ * Used to enable schema-specific translation handling.
+ */
+export declare enum FileSchema {
+    /** OpenAPI specification format */
+    OpenAPI = "openApi",
+    /** Flutter ARB (Application Resource Bundle) format */
+    ARBFlutter = "arbFlutter"
+}
+export interface TranslationRequest {
+    sourceStrings: string;
+    targetLanguageCode: string;
+    useContractions?: boolean;
+    useShortening?: boolean;
+    generatePluralForms?: boolean;
+    translateMetadata?: boolean;
+    returnTranslationsAsString: boolean;
+    client: string;
+    translateOnlyNewStrings?: boolean;
+    targetStrings?: string;
+    schema: FileSchema | null;
+    /**
+     * Localization file format (e.g., "json", "arb", "po", "yaml", "xml").
+     * If not specified, auto-detected from sourceStrings content.
+     * See https://l10n.dev/ws/translate-i18n-files#supported-formats for supported formats.
+     */
+    format?: string;
+}
+export interface TranslationResult {
+    targetLanguageCode: string;
+    translations?: string;
+    usage: TranslationUsage;
+    finishReason?: FinishReason;
+    completedChunks: number;
+    totalChunks: number;
+    remainingBalance?: number;
+    /**
+     * Source strings that were filtered out due to content policy violations or length limits.
+     * Populated when the finish reason is 'contentFilter' or 'length'.
+     * Raw text in the same format as the input (JSON, YAML, PO, etc.).
+     */
+    filteredStrings?: string;
+}
+export interface TranslationUsage {
+    charsUsed?: number;
+}
+export declare enum FinishReason {
+    stop = "stop",
+    length = "length",
+    contentFilter = "contentFilter",
+    insufficientBalance = "insufficientBalance",
+    error = "error"
+}
+export interface Language {
+    code: string;
+    name: string;
+}
+export interface LanguagePredictionResponse {
+    languages: Language[];
+}
+export type LanguageProficiencyLevel = "strong" | "high" | "moderate" | "limited";
+export interface Region {
+    code: string | null;
+    name: string | null;
+    nativeName: string | null;
+}
+export interface Script {
+    code: string | null;
+    name: string | null;
+    nativeName: string | null;
+}
+export interface SupportedLanguage {
+    code: string | null;
+    name: string | null;
+    nativeName: string | null;
+    level?: LanguageProficiencyLevel;
+    regions?: Region[] | null;
+    scripts?: Script[] | null;
+}
+export interface SupportedLanguagesResponse {
+    languages: SupportedLanguage[];
+}
+export declare class L10nTranslationService {
+    private readonly logger;
+    constructor(logger?: ILogger);
+    getLanguages(options?: {
+        codes?: string[];
+        proficiencyLevels?: LanguageProficiencyLevel[];
+    }): Promise<SupportedLanguagesResponse>;
+    predictLanguages(input: string, limit?: number): Promise<Language[]>;
+    translate(request: TranslationRequest, apiKey: string): Promise<TranslationResult | null>;
+}