ai-l10n-sdk 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to the SDK 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.6.0] - 2026-06-02
+
+### Added
+- **`I18nProjectManager.extractLanguageCodeFromPath(sourceFilePath)`** — New public method that returns the detected source language code from the file path (e.g., `"en"` for `locales/en.json`) or `null` if the structure is unrecognised. Used internally by `AiTranslator` to auto-populate `sourceLanguageCode` on translation requests.
+- **Extended `TranslationConfig`** with four new optional fields:
+  - `sourceLanguageCode?: string | null` — BCP-47 source language; auto-detected from the file path when not provided
+  - `generateGlossary?: boolean` — generates and saves a glossary for this language pair for future translations (default: `false`)
+  - `glossary?: GlossaryEntry[] | null` — override the active glossary: omit/`null` = use active, `[]` = disable, entries = replace for this request
+  - `terminology?: TerminologyEntry[]` — terms for consistent translation with disallowed synonyms
+- **`GlossaryEntry` and `TerminologyEntry`** re-exported from `ai-l10n-core` for convenience
+
+### Changed
+- Updated to use `ai-l10n-core@1.6.0`
+- `AiTranslator.translate()` now auto-detects the source language code from the project structure and passes it to the API as `sourceLanguageCode`
+
+## [1.5.1] - 2026-04-17
+
+### Changed
+- Updated to use `ai-l10n-core@1.5.1`
+- Set default client identifier on `translate()` requests.
+- Standardized the `reason` type used in API error responses to a fixed union of values.
+
+### Fixed
+- API documentation
+
 ## [1.5.0] - 2026-04-16
 
 ### Changed

package/README.md

@@ -155,7 +155,7 @@ const result = await translator.translate({
 });
 ```
 
-For the full list of supported formats see the [API documentation](https://l10n.dev/ws/translate-i18n-files#supported-formats).
+For the full list of supported formats see the [API documentation](https://api.l10n.dev/doc/#tag/ai-translation/post/v2/translate).
 
 ### Multiple Files
 
@@ -170,6 +170,64 @@ for (const file of files) {
 }
 ```
 
+### Glossary & Terminology
+
+#### Generate and Save a Glossary
+
+When `generateGlossary` is enabled, a glossary is built from the source and translated target content and saved as the active glossary for this source/target language pair. It is then used automatically on future translations.
+
+> **Balance note:** Balance is debited for the full source content upfront — even when `translateOnlyNewStrings` is `true`. When disabled (default), a temporary internal glossary is generated at no extra cost only for content that exceeds the AI chunk size.
+
+```typescript
+const result = await translator.translate({
+  sourceFile: './locales/en.json',
+  targetLanguages: ['de', 'fr'],
+  generateGlossary: true,
+});
+```
+
+Manage your saved glossaries at [l10n.dev/ws/translation-glossary](https://l10n.dev/ws/translation-glossary).
+
+#### Override the Glossary for a Single Request
+
+Supply your own term mappings via `glossary`. Each `GlossaryEntry` maps a source term to the preferred target translation with an optional context note.
+
+```typescript
+import { AiTranslator, GlossaryEntry } from 'ai-l10n-sdk';
+
+const glossary: GlossaryEntry[] = [
+  { sourceTerm: 'Settings', targetTerm: 'Einstellungen' },
+  { sourceTerm: 'bank', targetTerm: 'Bank', context: 'financial institution' },
+];
+
+const result = await translator.translate({
+  sourceFile: './locales/en.json',
+  targetLanguages: ['de'],
+  glossary,
+});
+```
+
+Pass an empty array (`glossary: []`) to disable the active glossary entirely for this request.
+
+#### Terminology
+
+Use `terminology` to enforce consistent term usage. Synonyms listed for each entry are replaced with the preferred `term`.
+
+```typescript
+import { AiTranslator, TerminologyEntry } from 'ai-l10n-sdk';
+
+const terminology: TerminologyEntry[] = [
+  { term: 'Settings', synonyms: ['Preferences', 'Options', 'Configuration'] },
+  { term: 'Dashboard' },
+];
+
+const result = await translator.translate({
+  sourceFile: './locales/en.json',
+  targetLanguages: ['de', 'fr'],
+  terminology,
+});
+```
+
 ## Core API
 
 `ILogger`, `ConsoleLogger`, `L10nTranslationService`, and all related types are part of the core library. See [ai-l10n-core](https://www.npmjs.com/package/ai-l10n-core) for full documentation. These are also re-exported from `ai-l10n-sdk` for convenience.
@@ -284,6 +342,32 @@ interface TranslationConfig {
    * Enable verbose logging (default: false)
    */
   verbose?: boolean;
+
+  /**
+   * BCP-47 code of the source language (e.g., "en", "en-US", "zh-Hans-CN").
+   * If not specified, auto-detected from the source file path.
+   */
+  sourceLanguageCode?: string | null;
+
+  /**
+   * When true, generates a glossary from source and translated target content and saves it as the
+   * active glossary for this language pair for future translations.
+   * Balance is debited for the full source content upfront — even when translateOnlyNewStrings is true.
+   * When false (default), an internal glossary is generated only for large content at no extra cost.
+   */
+  generateGlossary?: boolean;
+
+  /**
+   * Glossary entries to apply during translation.
+   * null/omitted = use active glossary, [] = disable glossary, entries = replace active for this request.
+   * Manage saved glossaries at https://l10n.dev/ws/translation-glossary
+   */
+  glossary?: GlossaryEntry[] | null;
+
+  /**
+   * A list of terms for consistent translations. Synonyms are replaced by the preferred term.
+   */
+  terminology?: TerminologyEntry[];
 }
 ```
 
@@ -330,6 +414,37 @@ interface TranslationOutput {
 }
 ```
 
+#### GlossaryEntry
+
+Maps a source term to a preferred target translation for use in `TranslationConfig.glossary`.
+
+```typescript
+interface GlossaryEntry {
+  /** The term in the source language to be translated. Max length: 255. */
+  sourceTerm: string;
+  /** The preferred translation of the term in the target language. Max length: 255. */
+  targetTerm: string;
+  /**
+   * Optional context to clarify the meaning when the term is ambiguous. Max length: 500.
+   * Example: 'bank' could mean 'financial institution' or 'river bank'.
+   */
+  context?: string | null;
+}
+```
+
+#### TerminologyEntry
+
+Specifies a preferred term and disallowed synonyms for use in `TranslationConfig.terminology`.
+
+```typescript
+interface TerminologyEntry {
+  /** The preferred term to use in translations. */
+  term: string;
+  /** Synonyms that should be replaced by `term`. */
+  synonyms?: string[];
+}
+```
+
 ### I18nProjectManager
 
 Utility class for managing i18n project structure detection, language code validation, and file path generation.
@@ -354,6 +469,25 @@ Creates an instance of I18nProjectManager.
 
 #### Methods
 
+##### `extractLanguageCodeFromPath(sourceFilePath: string): string | null`
+
+Extracts the source language code from the file path using project structure detection.
+
+**Parameters:**
+- `sourceFilePath: string` - Path to the source file
+
+**Returns:** `string | null` — The detected language code (e.g., `"en"`, `"en-US"`) or `null` if the structure is unrecognised
+
+**Example:**
+```typescript
+const manager = new I18nProjectManager();
+
+manager.extractLanguageCodeFromPath('./locales/en.json');   // Returns: 'en'
+manager.extractLanguageCodeFromPath('./locales/en/common.json'); // Returns: 'en'
+manager.extractLanguageCodeFromPath('./lib/l10n/app_en_US.arb'); // Returns: 'en_US'
+manager.extractLanguageCodeFromPath('./strings.json');     // Returns: null
+```
+
 ##### `detectLanguagesFromProject(sourceFilePath: string): string[]`
 
 Detects target language codes from the project structure by scanning directories and files.
@@ -441,6 +575,10 @@ manager.getUniqueFilePath('./output.json');
 // Returns: './output (2).json'
 ```
 
+### I18nProjectManager.extractLanguageCodeFromPath usage in AiTranslator
+
+`AiTranslator` calls `extractLanguageCodeFromPath()` automatically on each translation to populate `sourceLanguageCode` in the API request. You can override this by setting `sourceLanguageCode` explicitly in `TranslationConfig`.
+
 ## License
 
 MIT

package/dist/i18nProjectManager.d.ts

@@ -4,6 +4,11 @@ export declare class I18nProjectManager {
     constructor(logger?: ILogger);
     detectLanguagesFromProject(sourceFilePath: string): string[];
     generateTargetFilePath(sourceFilePath: string, targetLanguage: string): string;
+    /**
+     * Extracts the source language code from the file path using project structure detection.
+     * Returns the language code (e.g., `"en"`, `"en-US"`) or `null` if it cannot be determined.
+     */
+    extractLanguageCodeFromPath(sourceFilePath: string): string | null;
     getUniqueFilePath(filePath: string): string;
     private detectProjectStructure;
 }

package/dist/i18nProjectManager.js

@@ -164,6 +164,14 @@ class I18nProjectManager {
             }
         }
     }
+    /**
+     * Extracts the source language code from the file path using project structure detection.
+     * Returns the language code (e.g., `"en"`, `"en-US"`) or `null` if it cannot be determined.
+     */
+    extractLanguageCodeFromPath(sourceFilePath) {
+        const structureInfo = this.detectProjectStructure(sourceFilePath);
+        return structureInfo.sourceLanguage ?? null;
+    }
     getUniqueFilePath(filePath) {
         if (!fs.existsSync(filePath)) {
             return filePath;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ILogger } from "ai-l10n-core";
+import { ILogger, GlossaryEntry, TerminologyEntry } from "ai-l10n-core";
 /**
  * Configuration options for translation
  */
@@ -53,6 +53,32 @@ export interface TranslationConfig {
      * Enable verbose logging (default: false)
      */
     verbose?: boolean;
+    /**
+     * BCP-47 code of the source language (e.g., "en", "en-US", "zh-Hans-CN").
+     * If not specified, auto-detected from the source file path.
+     */
+    sourceLanguageCode?: string | null;
+    /**
+     * When true, generates a glossary from source and translated target content and saves it as the
+     * active glossary for this language pair for future translations.
+     * Balance is debited for the full source content upfront — even when `translateOnlyNewStrings` is true.
+     * When false (default), an internal glossary is generated only for large content that exceeds the AI
+     * chunk size, at no extra cost. (default: false)
+     */
+    generateGlossary?: boolean;
+    /**
+     * Glossary entries to apply during translation.
+     * - `null` or omitted: use the active glossary for this language pair.
+     * - Empty array `[]`: disable glossary translation entirely.
+     * - One or more entries: replace the active glossary for this request.
+     * Manage saved glossaries at https://l10n.dev/ws/translation-glossary
+     */
+    glossary?: GlossaryEntry[] | null;
+    /**
+     * A list of terms to use for consistent translations.
+     * Synonyms listed per entry will be replaced by the preferred term.
+     */
+    terminology?: TerminologyEntry[];
 }
 /**
  * Result of a single translation operation

package/dist/index.js

@@ -74,6 +74,7 @@ class AiTranslator {
             // Ensure API key is available
             const apiKey = await this.apiKeyManager.ensureApiKey(config.apiKey);
             // Determine target languages
+            let sourceLanguageCode = config.sourceLanguageCode;
             let targetLanguages = config.targetLanguages;
             if (!targetLanguages || targetLanguages.length === 0) {
                 // Auto-detect from project structure
@@ -82,6 +83,12 @@ class AiTranslator {
                 if (targetLanguages.length === 0) {
                     throw new Error("No target languages found. Please specify targetLanguages in config or ensure your project has the proper structure (e.g., folders named with language codes or files named with language codes).");
                 }
+                // Auto-detect source language code from file path if not provided
+                // If we can detect target languages from the project structure, we can also attempt to detect the source language code from the file path.
+                if (!sourceLanguageCode) {
+                    sourceLanguageCode =
+                        this.i18nProjectManager.extractLanguageCodeFromPath(sourceFilePath);
+                }
                 this.logger.logInfo(`✨ Auto-detected target languages from project structure: ${targetLanguages.join(", ")}`);
             }
             // Validate language codes
@@ -100,6 +107,9 @@ class AiTranslator {
             const translateMetadata = config.translateMetadata ?? false;
             const saveFilteredStrings = config.saveFilteredStrings ?? true;
             const translateOnlyNewStrings = config.translateOnlyNewStrings ?? false;
+            const generateGlossary = config.generateGlossary ?? false;
+            const glossary = config.glossary;
+            const terminology = config.terminology;
             if (verbose) {
                 this.logger.logInfo(`Configuration:
   - Use contractions: ${useContractions}
@@ -107,7 +117,11 @@ class AiTranslator {
   - Generate plural forms: ${generatePluralForms}
   - Translate metadata: ${translateMetadata}
   - Save filtered strings: ${saveFilteredStrings}
-  - Translate only new strings: ${translateOnlyNewStrings}`);
+  - Translate only new strings: ${translateOnlyNewStrings}
+  - Source language: ${sourceLanguageCode ?? "auto-detect"}
+  - Generate glossary: ${generateGlossary}
+  - Glossary entries: ${glossary === undefined ? "use active" : glossary === null ? "use active" : glossary.length === 0 ? "disabled" : `${glossary.length} entries`}
+  - Terminology entries: ${terminology?.length ?? 0}`);
             }
             // Perform translations in parallel
             const totalLanguages = targetLanguages.length;
@@ -115,7 +129,7 @@ class AiTranslator {
                 const targetFilePath = this.i18nProjectManager.generateTargetFilePath(sourceFilePath, targetLanguage);
                 try {
                     this.logger.logInfo(`\n🌐 Translating (${i + 1}/${totalLanguages}) to ${targetLanguage}...`);
-                    const result = await this.performTranslation(apiKey, sourceFilePath, targetLanguage, targetFilePath, translateOnlyNewStrings, useContractions, useShortening, generatePluralForms, translateMetadata, saveFilteredStrings, format, verbose);
+                    const result = await this.performTranslation(apiKey, sourceFilePath, targetLanguage, targetFilePath, translateOnlyNewStrings, useContractions, useShortening, generatePluralForms, translateMetadata, saveFilteredStrings, format, verbose, sourceLanguageCode, generateGlossary, glossary, terminology);
                     return result;
                 }
                 catch (error) {
@@ -172,7 +186,7 @@ class AiTranslator {
             };
         }
     }
-    async performTranslation(apiKey, sourceFilePath, targetLanguage, targetFilePath, translateOnlyNewStrings, useContractions, useShortening, generatePluralForms, translateMetadata, saveFilteredStrings, format, verbose) {
+    async performTranslation(apiKey, sourceFilePath, targetLanguage, targetFilePath, translateOnlyNewStrings, useContractions, useShortening, generatePluralForms, translateMetadata, saveFilteredStrings, format, verbose, sourceLanguageCode, generateGlossary, glossary, terminology) {
         // Read source file
         const sourceContent = fs.readFileSync(sourceFilePath, "utf8");
         // Check if target file exists and read it if updating
@@ -189,6 +203,7 @@ class AiTranslator {
         const request = {
             sourceStrings: sourceContent,
             targetLanguageCode: normalizedLanguage,
+            sourceLanguageCode: sourceLanguageCode ?? null,
             useContractions,
             useShortening,
             generatePluralForms,
@@ -198,6 +213,9 @@ class AiTranslator {
             targetStrings,
             schema: format === "arb" ? ai_l10n_core_1.FileSchema.ARBFlutter : null,
             format,
+            generateGlossary,
+            glossary,
+            terminology,
         };
         // Call translation service
         const response = await this.translationService.translate(request, apiKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-l10n-sdk",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Lightweight SDK for AI-powered localization automation - programmatic API (no CLI)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
     "node": ">=14.0.0"
   },
   "dependencies": {
-    "ai-l10n-core": "^1.5.0"
+    "ai-l10n-core": "^1.6.0"
   },
   "devDependencies": {
     "@types/mocha": "^10.0.10",