ai-l10n-core 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog - ai-l10n-core
+
+All notable changes to the core package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.0] - 2026-04-02
+
+### Added
+- **Initial Package Release** - Core library extracted from `ai-l10n` as independent package
+  - `L10nTranslationService` — low-level translation API client
+    - `TranslationRequest` now includes optional `format?: string` field for specifying localization file format (e.g., `"json"`, `"arb"`, `"po"`, `"yaml"`, `"xliff"`)
+  - `ILogger` interface — dependency injection for logging
+  - `ConsoleLogger` — default console-based logger implementation
+  - `languageUtils` — BCP 47 language code normalization and validation
+    - `validateLanguageCode(code)` and `normalizeLanguageCode(code)` are now the canonical location for these utilities (previously also exposed as wrapper methods on `I18nProjectManager` in `ai-l10n-sdk`)
+  - `constants` — `URLS` and `CONFIG` shared configuration
+  - Complete TypeScript type definitions

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Antonov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,27 @@
+ai-l10n-core
+Copyright (C) 2025 Antonov Anton Yurevich, Individual Entrepreneur. <https://l10n.dev/>
+
+This package is part of the ai-l10n project and provides the platform-independent
+core for AI-powered localization — translation API client, language utilities, and
+shared types.
+
+License:
+--------
+This software is licensed under the MIT License.
+See the LICENSE file for the complete license text.
+
+Usage of l10n.dev service:
+--------------------------
+This package communicates with the l10n.dev platform, which provides AI-powered
+translation for internationalization (i18n) files. The l10n.dev backend service is
+proprietary and not covered by the MIT License. A valid l10n.dev account and API key
+are required to use the translation features of this package.
+
+You may freely use, modify, and distribute this package under the terms of the MIT License.
+However, this does not grant any rights to the l10n.dev backend services, which remain
+the exclusive property of Antonov Anton Yurevich, Individual Entrepreneur.
+
+Trademark Notice:
+-----------------
+"l10n.dev" and associated branding are trademarks of Antonov Anton Yurevich,
+Individual Entrepreneur. Use of these names and branding is subject to applicable law.

package/README.md

@@ -0,0 +1,487 @@
+# ai-l10n-core
+
+[![npm version](https://img.shields.io/npm/v/ai-l10n-core.svg)](https://www.npmjs.com/package/ai-l10n-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Platform-independent core for AI-powered localization — translation API client, language utilities, and shared types.
+
+This is the foundational library for the [ai-l10n](https://www.npmjs.com/package/ai-l10n) ecosystem. It provides the low-level translation API client, logger interface, and language utilities used by the SDK and CLI.
+
+Powered by [l10n.dev](https://l10n.dev).
+
+## Installation
+
+```bash
+npm install ai-l10n-core
+```
+
+## Related Packages
+
+- [ai-l10n-sdk](https://www.npmjs.com/package/ai-l10n-sdk) — High-level SDK with `AiTranslator`, file management, and project structure detection
+- [ai-l10n](https://www.npmjs.com/package/ai-l10n) — CLI tool built on the SDK
+
+## Custom Logger Integration
+
+By default, `L10nTranslationService` uses the built-in `ConsoleLogger` which outputs to the console. For integration in other environments (VS Code extensions, web applications, custom UIs), implement a custom logger.
+
+### Logger Interface
+
+Implement the `ILogger` interface to create your own logger:
+
+```typescript
+import { ILogger } from 'ai-l10n-core';
+
+class MyLogger implements ILogger {
+  logInfo(message: string): void {
+    myLoggingSystem.info(message);
+  }
+  logWarning(message: string, error?: unknown): void {
+    myLoggingSystem.warn(message, error);
+  }
+  logError(message: string, error?: unknown): void {
+    myLoggingSystem.error(message, error);
+  }
+  showAndLogError(
+    message: string,
+    error?: unknown,
+    context?: string,
+    linkBtnText?: string,
+    url?: string
+  ): void {
+    myLoggingSystem.error(message, { error, context, linkBtnText, url });
+  }
+}
+```
+
+### Default ConsoleLogger
+
+The built-in `ConsoleLogger` implementation:
+
+```typescript
+import { ConsoleLogger } from 'ai-l10n-core';
+
+const logger = new ConsoleLogger();
+
+// Outputs with emojis and formatting
+logger.logInfo('Translation started');           // Plain console.log
+logger.logWarning('File not found', error);      // ⚠️ with error details
+logger.logError('Translation failed', error);    // ❌ with error details
+logger.showAndLogError(
+  'API request failed',
+  error,
+  'Authentication',
+  'Get API Key',
+  'https://l10n.dev/ws/keys'
+);
+```
+
+## API Reference
+
+### ConsoleLogger
+
+Default console-based implementation of `ILogger`.
+
+#### Constructor
+
+```typescript
+import { ConsoleLogger } from 'ai-l10n-core';
+
+const logger = new ConsoleLogger();
+```
+
+#### Methods
+
+- `logInfo(message: string): void` — Outputs plain `console.log`
+- `logWarning(message: string, error?: unknown): void` — Outputs `⚠️  message` via `console.warn`
+- `logError(message: string, error?: unknown): void` — Outputs `❌ message` via `console.error`
+- `showAndLogError(message, error?, context?, linkBtnText?, url?): void` — Outputs full error details including stack trace, context, and optional link
+
+---
+
+### L10nTranslationService
+
+Low-level client for interacting with the l10n.dev translation API.
+
+#### Constructor
+
+```typescript
+import { L10nTranslationService, ConsoleLogger, ILogger } from 'ai-l10n-core';
+
+// Default: uses ConsoleLogger
+const service = new L10nTranslationService();
+
+// With a custom logger
+const customLogger: ILogger = new ConsoleLogger();
+const service = new L10nTranslationService(customLogger);
+```
+
+#### Methods
+
+##### `translate(request: TranslationRequest, apiKey: string): Promise<TranslationResult | null>`
+
+Translates localization content using the l10n.dev API.
+
+**Parameters:**
+- `request: TranslationRequest` — Translation request configuration
+- `apiKey: string` — API key for authentication
+
+**Returns:** `Promise<TranslationResult | null>` — Translation result, or `null` for 401/402 responses
+
+**Throws:** Error for 400, 413, 500, and other failure conditions
+
+##### `predictLanguages(input: string, limit?: number): Promise<Language[]>`
+
+Predicts possible language codes from a text input (language name in English or native language, region, or script).
+
+**Parameters:**
+- `input: string` — Text to analyze
+- `limit?: number` — Maximum number of predictions (default: 10)
+
+**Returns:** `Promise<Language[]>` — Array of predicted languages with codes and names
+
+##### `getLanguages(options?: { codes?: string[]; proficiencyLevels?: LanguageProficiencyLevel[] }): Promise<SupportedLanguagesResponse>`
+
+Retrieves a list of supported languages, optionally filtered by language codes or proficiency levels.
+
+**Parameters:**
+- `options?` — Optional filter object
+  - `codes?: string[]` — Filter by specific language codes (e.g., `["en", "es", "fr"]`)
+  - `proficiencyLevels?: LanguageProficiencyLevel[]` — Filter by proficiency level: `"strong"`, `"high"`, `"moderate"`, or `"limited"`
+
+**Returns:** `Promise<SupportedLanguagesResponse>` — Object containing a `languages` array of `SupportedLanguage` entries
+
+**Throws:** Error if the API request fails (non-2xx response)
+
+**Example:**
+```typescript
+// Get all supported languages
+const { languages } = await service.getLanguages();
+
+// Filter by proficiency level
+const { languages } = await service.getLanguages({
+  proficiencyLevels: ['strong', 'high'],
+});
+
+// Filter by specific codes
+const { languages } = await service.getLanguages({
+  codes: ['en', 'es', 'fr'],
+});
+```
+
+#### Types
+
+##### TranslationRequest
+
+```typescript
+interface TranslationRequest {
+  /** Source strings as JSON string */
+  sourceStrings: string;
+
+  /** Target language code (e.g., "es", "fr-FR") */
+  targetLanguageCode: string;
+
+  /** Use contractions (e.g., "don't" vs "do not") */
+  useContractions?: boolean;
+
+  /** Use shortened forms when translation is longer than source text */
+  useShortening?: boolean;
+
+  /** Generate plural forms for i18next */
+  generatePluralForms?: boolean;
+
+  /** Translate metadata along with UI strings (e.g., ARB `@key` descriptions) */
+  translateMetadata?: boolean;
+
+  /** Return translations as JSON string */
+  returnTranslationsAsString: boolean;
+
+  /** Client identifier */
+  client: string;
+
+  /** Only translate new strings */
+  translateOnlyNewStrings?: boolean;
+
+  /** Existing target strings (for incremental updates) */
+  targetStrings?: string;
+
+  /** File schema format */
+  schema: FileSchema | null;
+
+  /**
+   * Localization file format (e.g., "json", "arb", "po", "yaml", "xml").
+   * If not specified, auto-detected from sourceStrings content.
+   * See the [supported formats table](https://l10n.dev/ws/translate-i18n-files#supported-formats).
+   */
+  format?: string;
+}
+```
+
+##### TranslationResult
+
+```typescript
+interface TranslationResult {
+  /** Target language code */
+  targetLanguageCode: string;
+
+  /** Translated content as JSON string */
+  translations?: string;
+
+  /** Usage statistics */
+  usage: TranslationUsage;
+
+  /** Reason translation finished */
+  finishReason?: FinishReason;
+
+  /** Number of chunks completed */
+  completedChunks: number;
+
+  /** Total number of chunks */
+  totalChunks: number;
+
+  /** Remaining character balance */
+  remainingBalance?: number;
+
+  /** Strings filtered due to content policy, in the same format as the input */
+  filteredStrings?: string;
+}
+```
+
+##### TranslationUsage
+
+```typescript
+interface TranslationUsage {
+  /** Number of characters used */
+  charsUsed?: number;
+}
+```
+
+##### FileSchema
+
+Supported file schema formats for translation requests.
+
+```typescript
+enum FileSchema {
+  /** OpenAPI specification format */
+  OpenAPI = "openApi",
+
+  /** Flutter ARB (Application Resource Bundle) format */
+  ARBFlutter = "arbFlutter"
+}
+```
+
+##### FinishReason
+
+Reasons why a translation finished.
+
+```typescript
+enum FinishReason {
+  /** Translation completed successfully */
+  stop = "stop",
+
+  /** Translation stopped due to length/context limits */
+  length = "length",
+
+  /** Some content was filtered due to content policy */
+  contentFilter = "contentFilter",
+
+  /** Insufficient character balance */
+  insufficientBalance = "insufficientBalance",
+
+  /** Translation failed with error */
+  error = "error"
+}
+```
+
+##### Language
+
+```typescript
+interface Language {
+  /** Language code (e.g., "es", "fr-FR") */
+  code: string;
+
+  /** Human-readable language name */
+  name: string;
+}
+
+```
+##### SupportedLanguage
+
+```typescript
+interface SupportedLanguage {
+  code: string | null;
+  name: string | null;
+  nativeName: string | null;
+  level?: "strong" | "high" | "moderate" | "limited";
+  regions?: Region[] | null;
+  scripts?: Script[] | null;
+}
+```
+
+#### Error Handling
+
+The service throws errors for:
+
+- **400 Bad Request** — Validation error with details
+- **413 Request Too Large** — `"Request too large. Maximum request size is 5 MB."`
+- **500 Server Error** — `"An internal server error occurred (Error code: ...)"`
+
+Returns `null` with error logged for:
+
+- **Missing API Key** — `"API Key not set. Please configure your API Key first."`
+- **401 Unauthorized** — `"Unauthorized. Please check your API Key."`
+- **402 Payment Required** — `"Not enough characters remaining for this translation..."`
+
+---
+
+### ILogger Interface
+
+```typescript
+interface ILogger {
+  logInfo(message: string): void;
+  logWarning(message: string, error?: unknown): void;
+  logError(message: string, error?: unknown): void;
+  showAndLogError(
+    message: string,
+    error?: unknown,
+    context?: string,
+    linkBtnText?: string,
+    url?: string
+  ): void;
+}
+```
+
+---
+
+### Constants
+
+```typescript
+import { URLS, CONFIG } from 'ai-l10n-core';
+
+// API endpoints
+URLS.API_BASE    // Base URL for l10n.dev API
+
+// Configuration keys
+CONFIG.API_KEY   // Key name for stored API key
+```
+
+---
+
+### Language Utilities
+
+Pure utility functions for working with BCP 47 language codes.
+
+```typescript
+import { validateLanguageCode, normalizeLanguageCode, extractLanguageCode } from 'ai-l10n-core';
+```
+
+##### `validateLanguageCode(code: string): boolean`
+
+Validates whether a string is a valid BCP 47 language code.
+
+**Parameters:**
+- `code: string` — Language code to validate
+
+**Returns:** `boolean` — `true` if valid, `false` otherwise
+
+**Validation Rules:**
+- **Case-insensitive validation**: Accepts language codes in any case (e.g., `"EN"`, `"en"`, `"EN-US"`)
+- Language: 2-3 letters (e.g., `en`, `eng`, `EN`)
+- Script (optional): 4 letters (e.g., `Hans`, `Latn`, `hans`)
+- Region (optional): 2-3 letters or 3 digits (e.g., `US`, `us`, `419`)
+- Separators: hyphens `-` or underscores `_`
+
+**Important:** This function only validates the format. For proper BCP 47 compliance, use `normalizeLanguageCode()` to convert validated codes to the correct case format (language lowercase, Script title case, REGION uppercase).
+
+**Example:**
+```typescript
+// All valid (case-insensitive)
+validateLanguageCode('en');           // true
+validateLanguageCode('EN');           // true
+validateLanguageCode('en-US');        // true
+validateLanguageCode('en-us');        // true
+validateLanguageCode('zh-Hans-CN');   // true
+validateLanguageCode('ZH-HANS-CN');   // true
+
+// Invalid
+validateLanguageCode('invalid');      // false
+validateLanguageCode('');             // false
+
+// Normalize after validation for proper BCP 47 format
+const code = 'EN-US';
+if (validateLanguageCode(code)) {
+  const normalized = normalizeLanguageCode(code);
+  console.log(normalized); // 'en-US'
+}
+```
+
+---
+
+##### `normalizeLanguageCode(code: string): string`
+
+Normalizes language codes to a consistent BCP 47 format.
+
+**Parameters:**
+- `code: string` — Language code to normalize (accepts hyphens or underscores)
+
+**Returns:** `string` — Normalized language code in format: `language[-Script][-REGION]`
+
+**Normalization Rules:**
+- Language: lowercase (e.g., `"EN"` → `"en"`)
+- Script: Title case (e.g., `"hans"` → `"Hans"`)
+- Region: uppercase (e.g., `"us"` → `"US"`)
+- Separator: always hyphen `-` (underscores converted to hyphens)
+
+**Example:**
+```typescript
+normalizeLanguageCode('en');          // 'en'
+normalizeLanguageCode('en-us');       // 'en-US'
+normalizeLanguageCode('en_US');       // 'en-US'
+normalizeLanguageCode('zh_hans');     // 'zh-Hans'
+normalizeLanguageCode('zh-Hans-CN');  // 'zh-Hans-CN'
+normalizeLanguageCode('ZH_HANS_CN'); // 'zh-Hans-CN'
+```
+
+---
+
+##### `extractLanguageCode(fileName: string): string | null`
+
+Extracts a language code from a file name, handling various localization file patterns.
+
+**Parameters:**
+- `fileName: string` — File name (with or without extension)
+
+**Returns:** `string | null` — Extracted language code, or `null` if none found
+
+**Supported Patterns:**
+- **JSON/JSONC**: `en.json`, `es-ES.json`, `en.jsonc`
+- **ARB**: `app_en.arb`, `app_en_US.arb`, `my_app_fr.arb`
+- **Shopify**: `en.default.schema.json`, `es-ES.schema.json`
+
+**Example:**
+```typescript
+// JSON files
+extractLanguageCode('en.json');                    // 'en'
+extractLanguageCode('es-ES.json');                 // 'es-ES'
+extractLanguageCode('fr.jsonc');                   // 'fr'
+
+// ARB files
+extractLanguageCode('app_en.arb');                 // 'en'
+extractLanguageCode('app_en_US.arb');              // 'en_US'
+extractLanguageCode('my_app_fr.arb');              // 'fr'
+
+// Shopify theme
+extractLanguageCode('en.default.schema.json');     // 'en'
+extractLanguageCode('es-ES.schema.json');          // 'es-ES'
+
+// Invalid files
+extractLanguageCode('readme.md');                  // null
+extractLanguageCode('invalid.json');               // null
+```
+
+## License
+
+MIT
+
+## Credits
+
+Powered by [l10n.dev](https://l10n.dev) — AI-powered localization service

package/dist/consoleLogger.d.ts

@@ -0,0 +1,26 @@
+import { ILogger } from "./logger";
+/**
+ * Console-based logger implementation
+ */
+export declare class ConsoleLogger implements ILogger {
+    /**
+     * Show and log error message
+     */
+    showAndLogError(message: string, error?: unknown, context?: string, linkBtnText?: string, url?: string): void;
+    /**
+     * Log informational message
+     */
+    logInfo(message: string): void;
+    /**
+     * Log warning message
+     */
+    logWarning(message: string, error?: unknown): void;
+    /**
+     * Log error message
+     */
+    logError(message: string, error?: unknown): void;
+    /**
+     * Log error details to console
+     */
+    private logErrorDetails;
+}

package/dist/consoleLogger.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleLogger = void 0;
+/**
+ * Console-based logger implementation
+ */
+class ConsoleLogger {
+    /**
+     * Show and log error message
+     */
+    showAndLogError(message, error, context, linkBtnText, url) {
+        console.error(`❌ ${message}`);
+        if (context) {
+            console.error(`Context: ${context}`);
+        }
+        if (error) {
+            this.logErrorDetails(error, console.error);
+        }
+        if (linkBtnText && url) {
+            console.error(`${linkBtnText}: ${url}`);
+        }
+    }
+    /**
+     * Log informational message
+     */
+    logInfo(message) {
+        console.log(message);
+    }
+    /**
+     * Log warning message
+     */
+    logWarning(message, error) {
+        console.warn(`⚠️  ${message}`);
+        if (error) {
+            this.logErrorDetails(error, console.warn);
+        }
+    }
+    /**
+     * Log error message
+     */
+    logError(message, error) {
+        console.error(`❌ ${message}`);
+        if (error) {
+            this.logErrorDetails(error, console.error);
+        }
+    }
+    /**
+     * Log error details to console
+     */
+    logErrorDetails(error, logFn) {
+        if (error instanceof Error) {
+            logFn(`Error: ${error.message}`);
+            if (error.stack) {
+                logFn(error.stack);
+            }
+        }
+        else {
+            logFn(`Error: ${String(error)}`);
+        }
+    }
+}
+exports.ConsoleLogger = ConsoleLogger;

package/dist/constants.d.ts

@@ -0,0 +1,17 @@
+export declare const CONFIG: {
+    readonly CLIENT: "ai-l10n-npmjs";
+    readonly KEYS: {
+        readonly API_KEY: "apiKey";
+        readonly USE_CONTRACTIONS: "useContractions";
+        readonly USE_SHORTENING: "useShortening";
+        readonly GENERATE_PLURAL_FORMS: "generatePluralForms";
+        readonly SAVE_FILTERED_STRINGS: "saveFilteredStrings";
+    };
+};
+export declare const URLS: {
+    readonly BASE: "https://l10n.dev";
+    readonly API_BASE: "https://api.l10n.dev";
+    readonly API_KEYS: "https://l10n.dev/ws/keys";
+    readonly PRICING: "https://l10n.dev/#pricing";
+    readonly CONTENT_POLICY: "https://l10n.dev/terms-of-service#content-policy";
+};

package/dist/constants.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.URLS = exports.CONFIG = void 0;
+// Configuration constants shared across the package
+exports.CONFIG = {
+    CLIENT: "ai-l10n-npmjs",
+    KEYS: {
+        API_KEY: "apiKey",
+        USE_CONTRACTIONS: "useContractions",
+        USE_SHORTENING: "useShortening",
+        GENERATE_PLURAL_FORMS: "generatePluralForms",
+        SAVE_FILTERED_STRINGS: "saveFilteredStrings",
+    },
+};
+// URL constants for l10n.dev service
+exports.URLS = {
+    BASE: "https://l10n.dev",
+    API_BASE: "https://api.l10n.dev",
+    API_KEYS: "https://l10n.dev/ws/keys",
+    PRICING: "https://l10n.dev/#pricing",
+    CONTENT_POLICY: "https://l10n.dev/terms-of-service#content-policy",
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./logger";
+export * from "./consoleLogger";
+export * from "./constants";
+export * from "./translationService";
+export * from "./languageUtils";