@concircle/i18n-ai-translator 0.1.2 → 0.1.3

package/README.md

@@ -3,33 +3,32 @@
 <table>
   <tr>
     <td width="200" valign="top">
-      <img src="https://bitbucket.org/concircle/i18n-ai-translator/raw/HEAD/assets/logo.png" alt="Concircle logo" />
+      <img src="https://raw.githubusercontent.com/concircle/i18n-ai-translator/main/assets/logo.png" alt="Concircle logo" />
     </td>
     <td valign="top">
-      AI-powered internationalization (i18n) translator for UI5 applications. Automatically translates <code>i18n.properties</code> files to multiple languages using OpenAI, with support for glossaries, placeholder preservation, and intelligent caching.
+      Translates UI5 <code>i18n.properties</code> files with OpenAI, preserves placeholders, supports glossary terms, and writes language-specific <code>.properties</code> files.
     </td>
   </tr>
 </table>
 
 ## Features
 
-- 🤖 **AI-Powered Translation**: Uses OpenAI GPT-4 for accurate, context-aware translations
-- 🔒 **Placeholder Preservation**: Protects UI5 placeholders like `{0}`, `{name}`, `%s`, `${variable}` from being translated
-- 📚 **Glossary Support**: Define domain-specific vocabulary (e.g., SAP terminology) for consistent translations
-- 🚀 **Batch Processing**: Parallel translation requests for efficiency
-- 💾 **Smart Caching**: Local file-based cache with TTL and glossary hash invalidation
-- 🔌 **Extensible Architecture**: Plugin-ready for future AI providers (Claude, Gemini, etc.)
-- 📦 **Dual Format**: CommonJS and ES Modules support
-- ✅ **Fully Tested**: Comprehensive test suite with focus on placeholder preservation
-- 📄 **TypeScript**: Full type safety and IntelliSense support
+- Preserves placeholders like `{0}`, `{name}`, `%s`, `${variable}`, and `%1$s`
+- Supports `missing` and `overwrite` translation modes
+- Applies shared and language-specific glossary terms
+- Writes UI5-style language files such as `i18n_de.properties`
+- Supports optional Unicode escaping with per-language overrides
+- Uses a local cache to avoid repeated translation requests
 
 ## Installation
 
 ```bash
-npm install @concircle/i18n-ai-translator
+npm install --save-dev @concircle/i18n-ai-translator
 ```
 
-Then add a script in the consuming app:
+## CLI
+
+Example `package.json` script:
 
 ```json
 {
@@ -39,7 +38,13 @@ Then add a script in the consuming app:
 }
 ```
 
-If your target system expects Java-style Unicode escapes in `.properties` files, enable them with:
+Show CLI help:
+
+```bash
+npx i18n-ai-translator --help
+```
+
+Enable Unicode escaping:
 
 ```json
 {
@@ -49,426 +54,233 @@ If your target system expects Java-style Unicode escapes in `.properties` files,
 }
 ```
 
-Or set it in your config file:
-
-```json
-{
-  "encodeUnicode": true
-}
-```
+## Configuration
 
-If you only want escapes for specific target languages, use per-language overrides:
+Example `i18n-ai.config.json`:
 
 ```json
 {
+  "sourceLanguage": "en",
+  "targetLanguages": ["de", "uk"],
+  "translationMode": "missing",
   "encodeUnicode": false,
   "languageOptions": {
     "de": { "encodeUnicode": true },
     "uk": { "encodeUnicode": false }
-  }
-}
-```
-
-This keeps languages like Ukrainian readable in UTF-8:
-
-```properties
-ai.button_tooltip = ШІ планувальник
-```
-
-Run it with:
-
-```bash
-npm run i18n:translate
-```
-
-## Quick Start
-
-### Basic Usage (ES Modules)
-
-```javascript
-import { Translator } from '@concircle/i18n-ai-translator';
-
-const translator = new Translator({
-  provider: 'openai',
-  openai: {
-    apiKey: process.env.OPENAI_API_KEY,
   },
-  targetLanguages: ['de', 'fr'],
-});
-
-const result = await translator.translate({
-  inputPath: './src/i18n/i18n.properties',
-  outputFormat: 'new-files',
-});
-
-console.log('Translation complete!', result);
-```
-
-### With Glossary (Domain Vocabulary)
-
-```javascript
-const translator = new Translator({
-  provider: 'openai',
-  openai: { apiKey: process.env.OPENAI_API_KEY },
-  targetLanguages: ['de'],
-  glossary: {
-    'SAP': { doNotTranslate: true },
-    'HANA': { translation: 'SAP HANA', context: 'database' },
-    'Fiori': { doNotTranslate: true },
+  "provider": "openai",
+  "providerOptions": {
+    "apiKey": "sk-...",
+    "model": "gpt-4.1-mini",
+    "temperature": 0,
+    "maxOutputTokens": 4000
   },
-});
-
-// Ensures SAP terms are correctly handled during translation
-```
-
-### Load Config from File
-
-```javascript
-import { loadConfig, Translator } from '@concircle/i18n-ai-translator';
-
-const config = loadConfig('./config.json');
-const translator = new Translator(config);
+  "files": {
+    "input": "./webapp/i18n/i18n.properties"
+  },
+  "cache": {
+    "enabled": true,
+    "ttlMs": 604800000
+  },
+  "batchSize": 20,
+  "verbose": false
+}
 ```
 
-## Configuration
-
-### TranslatorConfig Interface
+Supported top-level config fields:
 
-```typescript
+```ts
 interface TranslatorConfig {
-  provider: 'openai'; // Future: 'claude', 'gemini'
-  openai: {
-    apiKey: string;         // Required: OpenAI API key
-    model?: string;         // Default: 'gpt-4'
-    temperature?: number;   // Default: 0.3
-    maxTokens?: number;     // Default: 2000
+  sourceLanguage?: string;
+  targetLanguages: string[];
+  translationMode?: 'missing' | 'overwrite';
+  encodeUnicode?: boolean;
+  languageOptions?: Record<string, { encodeUnicode?: boolean }>;
+  provider?: 'openai';
+  providerOptions?: {
+    apiKey?: string;
+    model?: string;
+    baseURL?: string;
+    organization?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+  };
+  files?: {
+    input?: string;
+    outputDir?: string;
+    languageFilePattern?: string;
   };
-  targetLanguages: string[]; // Required: e.g., ['de', 'fr', 'es']
-  encodeUnicode?: boolean; // Default: false, escape non-ASCII as \uXXXX
-  languageOptions?: Record<string, {
-    encodeUnicode?: boolean; // Per-language override
-  }>;
-  glossary?: Glossary;       // Optional: Domain-specific vocabulary
+  glossary?: GlossaryConfig | string;
   cache?: {
-    enabled?: boolean;      // Default: true
-    ttl?: number;          // Default: 7 days (ms)
-    dir?: string;          // Default: ~/.i18n-ai-translator-cache
+    enabled?: boolean;
+    ttlMs?: number;
+    dir?: string;
   };
-  batchSize?: number;       // Default: 10 (parallel requests)
-  debug?: boolean;          // Default: false
+  rules?: string[];
+  batchSize?: number;
+  verbose?: boolean;
 }
 ```
 
-### Example Configuration File (config.json)
-
-```json
-{
-  "provider": "openai",
-  "openai": {
-    "apiKey": "sk-...",
-    "model": "gpt-4",
-    "temperature": 0.3,
-    "maxTokens": 2000
-  },
-  "targetLanguages": ["de", "fr", "es"],
-  "encodeUnicode": false,
-  "languageOptions": {
-    "de": { "encodeUnicode": true },
-    "uk": { "encodeUnicode": false }
-  },
-  "glossary": "./glossary.json",
-  "cache": {
-    "enabled": true,
-    "ttl": 604800000
-  },
-  "batchSize": 10,
-  "debug": false
-}
-```
+## Glossary
 
-### Example Glossary File (glossary.json)
+Example glossary file:
 
 ```json
 {
-  "SAP": {
-    "term": "SAP",
-    "translation": "SAP",
-    "doNotTranslate": true,
-    "context": "Enterprise Resource Planning System"
-  },
-  "HANA": {
-    "term": "HANA",
-    "translation": "SAP HANA",
-    "doNotTranslate": true,
-    "context": "In-memory database"
-  },
-  "module": {
-    "term": "module",
-    "translation": "Modul",
-    "context": "German translation"
+  "shared": [
+    {
+      "source": "Order",
+      "target": "Auftrag",
+      "context": "SAP sales document"
+    }
+  ],
+  "languages": {
+    "de": [
+      {
+        "source": "Plant",
+        "target": "Werk"
+      }
+    ],
+    "uk": [
+      {
+        "source": "AI",
+        "target": "ШI"
+      }
+    ]
   }
 }
 ```
 
-## API Reference
+## Programmatic Usage
 
-### Translator Class
+Translate a file directly:
 
-#### Constructor
-
-```typescript
-new Translator(config: TranslatorConfig): Translator
-```
-
-#### Methods
+```js
+import { Translator } from '@concircle/i18n-ai-translator';
 
-##### `translate(job: TranslationJob): Promise<TranslationResult>`
+const translator = new Translator({
+  sourceLanguage: 'en',
+  targetLanguages: ['de'],
+  translationMode: 'missing',
+  provider: 'openai',
+  providerOptions: {
+    apiKey: process.env.OPENAI_API_KEY
+  },
+  files: {
+    input: './webapp/i18n/i18n.properties'
+  }
+});
 
-Translate a properties file to configured target languages.
+const result = await translator.translateFile();
+console.log(result);
+```
 
-**Parameters:**
-- `job.inputPath`: Path to source `i18n.properties` file
-- `job.outputFormat`: `'new-files'` | `'update-existing'` (default: `'new-files'`)
-- `job.outputDir`: Output directory for new files
-- `job.languages`: Override config languages for this job
+Load config from file:
 
-**Returns:** Object with translation results per language
+```js
+import { Translator } from '@concircle/i18n-ai-translator';
 
-```javascript
-const result = await translator.translate({
-  inputPath: './src/i18n/i18n.properties',
-  outputFormat: 'new-files',
-  outputDir: './src/i18n',
-  languages: ['de'], // Optional: override
+const translator = await Translator.fromConfig({
+  configPath: './i18n-ai.config.json'
 });
 
-// Result example:
-// {
-//   sourceFile: './src/i18n/i18n.properties',
-//   translations: {
-//     de: {
-//       outputFile: './src/i18n/i18n_de.properties',
-//       success: true,
-//       translatedKeysCount: 42
-//     },
-//     fr: {
-//       outputFile: './src/i18n/i18n_fr.properties',
-//       success: true,
-//       translatedKeysCount: 42
-//     }
-//   }
-// }
+const result = await translator.translateProject();
+console.log(result);
 ```
 
-##### `clearCache(): void`
-
-Clear the translation cache (useful for testing or after glossary changes)
-
-```javascript
-translator.clearCache();
-```
+Use the top-level helper:
 
-##### `getCacheStats(): object`
+```js
+import { translateProject } from '@concircle/i18n-ai-translator';
 
-Get cache statistics
+const result = await translateProject({
+  inputPath: './webapp/i18n/i18n.properties',
+  languages: ['de'],
+  dryRun: true
+});
 
-```javascript
-const stats = translator.getCacheStats();
-// { enabled: true, cacheDir: '...', ttl: ..., entriesCount: 5 }
+console.log(result);
 ```
 
-##### `getGlossary(): Glossary`
-
-Get current glossary
-
-```javascript
-const glossary = translator.getGlossary();
-```
+## Translation Modes
 
-##### `getGlossaryTerms(): string[]`
+- `missing`: only translates keys that are missing or empty in the target file
+- `overwrite`: retranslates all keys from the source file
 
-Get all glossary terms
+## Placeholder Handling
 
-```javascript
-const terms = translator.getGlossaryTerms();
-```
+The translator masks placeholders before sending text to the model and validates that they are still present afterwards.
 
-## UI5 Properties File Format
+Supported placeholder styles:
 
-### Input Example (i18n.properties)
+- `{0}`, `{1}`
+- `{name}`, `{email}`
+- `%s`, `%d`
+- `%1$s`, `%2$d`
+- `${variable}`
 
-```properties
-# Application messages
-app.title=My Application
-app.version=1.0.0
+## Output Files
 
-# Messages with placeholders (will be preserved)
-msg.save=Save {0} items
-msg.delete=Delete {0} from {1}
+By default, UI5-style language files are generated next to the source file:
 
-# Named placeholders
-form.email=Please enter {email}
+- `i18n.properties`
+- `i18n_de.properties`
+- `i18n_fr.properties`
 
-# Format specifiers (preserved)
-msg.count=Found %d results
-msg.user=User %s not found
-```
+You can override the output directory or file naming pattern in `files.outputDir` and `files.languageFilePattern`.
 
-### Output Example (i18n_de.properties)
+## Cache
 
-```properties
-# Application messages
-app.title=Meine Anwendung
-app.version=1.0.0
+Caching is enabled by default. Cache keys include:
 
-# Messages with placeholders (PRESERVED unchanged)
-msg.save=Speichern Sie {0} Elemente
-msg.delete=Löschen Sie {0} von {1}
+- provider
+- model
+- source language
+- target language
+- source value
+- glossary terms
+- translation rules
 
-# Named placeholders
-form.email=Bitte geben Sie {email} ein
+Default cache location:
 
-# Format specifiers (PRESERVED)
-msg.count=Es wurden %d Ergebnisse gefunden
-msg.user=Benutzer %s nicht gefunden
+```text
+~/.i18n-ai-translator-cache/
 ```
 
-## Placeholder Protection
-
-All placeholder types are automatically detected and preserved during translation:
-
-- `{0}`, `{1}`, etc. - Numeric placeholders
-- `{name}`, `{email}`, etc. - Named placeholders
-- `%s`, `%d`, etc. - Printf-style format specifiers
-- `${variable}` - Template variable syntax
-- `%1$s`, `%2$d`, etc. - Positional format specifiers
-
 ## Environment Variables
 
-Configuration can also be provided via environment variables:
+Supported environment variables:
 
 ```bash
 export OPENAI_API_KEY=sk-...
-export OPENAI_MODEL=gpt-4
-export TARGET_LANGUAGES=de,fr,es
-export GLOSSARY_FILE=./glossary.json
+export OPENAI_MODEL=gpt-4.1-mini
 ```
 
 ## Examples
 
-See `examples/` directory for complete working examples:
-
-- `basic.mjs` - Minimal setup with environment variables
-- `with-glossary.mjs` - Using domain-specific vocabulary
-- `advanced.mjs` - Full configuration with caching and debugging
-
-Run examples:
+See [`examples/`](./examples/) for small runnable examples:
 
-```bash
-export OPENAI_API_KEY=sk-...
-node examples/basic.mjs
-```
-
-## Caching
-
-The translator uses smart, local file-based caching to:
-
-- **Reduce API costs**: Skip repeated translations
-- **Improve performance**: Instant retrieval from cache
-- **Invalidate on glossary changes**: Cache is invalidated when glossary is updated
-- **Support TTL**: Default 7-day cache expiration
-
-Cache location: `~/.i18n-ai-translator-cache/`
-
-### Cache Configuration
-
-```javascript
-cache: {
-  enabled: true,           // Enable/disable caching
-  ttl: 7 * 24 * 60 * 60 * 1000,  // 7 days in milliseconds
-  dir: '/custom/cache/dir' // Custom cache directory
-}
-```
-
-## Performance & Batching
-
-Translations are processed in parallel batches for efficiency:
-
-```javascript
-batchSize: 10  // Process up to 10 translations in parallel
-```
-
-This balances between:
-- **Throughput**: Parallel processing speeds up translation
-- **API Limits**: Stays within OpenAI rate limits (default 10 concurrent)
-- **Cost**: Fewer API calls due to combining texts
-
-## Future Provider Support
+- [`basic.mjs`](./examples/basic.mjs)
+- [`with-glossary.mjs`](./examples/with-glossary.mjs)
+- [`advanced.mjs`](./examples/advanced.mjs)
 
-The architecture supports adding new AI providers. Implement the `AIProvider` interface:
-
-```typescript
-interface AIProvider {
-  translateTexts(texts: string[], targetLanguage: string, context?: string): Promise<string[]>;
-  getName(): string;
-}
-```
-
-Future providers planned:
-- Claude (Anthropic)
-- Gemini (Google)
-- Offline/Local models
-
-## Error Handling
-
-The translator provides detailed error information:
-
-```javascript
-try {
-  const result = await translator.translate({...});
-  
-  for (const [lang, langResult] of Object.entries(result.translations)) {
-    if (!langResult.success) {
-      console.error(`Translation failed for ${lang}: ${langResult.error}`);
-    }
-  }
-} catch (error) {
-  console.error('Translation job failed:', error.message);
-}
-```
-
-## Testing
-
-Run the comprehensive test suite:
+## Development
 
 ```bash
-npm test              # Run tests
-npm run test:watch   # Watch mode
-npm run test:coverage # Coverage report
+npm run build
+npm run lint
+npm test
 ```
 
-Tests include:
-- ✅ Placeholder extraction and restoration (critical)
-- ✅ Properties file parsing and writing
-- ✅ Glossary management and injection
-- ✅ Cache behavior and TTL
-- ✅ Configuration validation
-
 ## License
 
 MIT © 2026 Herbert Kaintz - Concircle
 
 ## Contributing
 
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 ## Security
 
-Please report security vulnerabilities to security contacts via email rather than public issues. See [SECURITY.md](./SECURITY.md) for details.
-
-## Support
-
-- 📖 [API Documentation](./docs/)
-- 📚 [Examples](./examples/)
-- 🤝 [Contributing Guide](./CONTRIBUTING.md)
-- 🔒 [Security Policy](./SECURITY.md)
+See [`SECURITY.md`](./SECURITY.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@concircle/i18n-ai-translator",
-  "version": "0.1.2",
-  "description": "AI-powered i18n translator for UI5 apps. Translates i18n.properties files using OpenAI (extensible for other AI providers).",
+  "version": "0.1.3",
+  "description": "Translates UI5 i18n.properties files with OpenAI, preserving placeholders and glossary terms.",
   "type": "module",
   "bin": {
     "i18n-ai-translator": "./bin/i18n-ai-translator.mjs"
@@ -64,12 +64,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://bitbucket.org/concircle/i18n-ai-translator.git"
+    "url": "https://github.com/concircle/i18n-ai-translator.git"
   },
   "bugs": {
-    "url": "https://bitbucket.org/concircle/i18n-ai-translator/issues"
+    "url": "https://github.com/concircle/i18n-ai-translator/issues"
   },
-  "homepage": "https://bitbucket.org/concircle/i18n-ai-translator",
+  "homepage": "https://www.concircle.com/en/",
   "engines": {
     "node": ">=20.0.0"
   }