gptrans 2.0.0 → 2.0.4

package/README.md

@@ -15,6 +15,7 @@ Whether you're building a multilingual website, a mobile app, or a localization
 - **Caching with JSON:** Quickly retrieves cached translations to boost performance
 - **Parameter Substitution:** Dynamically replace placeholders in your translations
 - **Smart Context Handling:** Add contextual information to improve translation accuracy. Perfect for gender-aware translations, domain-specific content, or any scenario where additional context helps produce better results. The context is automatically cleared after each translation to prevent unintended effects.
+- **Translation Instructions:** Pass additional instructions (e.g., "Use natural tone") to guide the AI translator's style.
 
 ## 📦 Installation
 
@@ -76,6 +77,7 @@ When creating a new instance of GPTrans, you can customize:
 | `model` | Translation model key or array of models for fallback | `sonnet45` `gpt41` |
 | `batchThreshold` | Maximum number of characters to accumulate before triggering batch processing | `1500` |
 | `debounceTimeout` | Time in milliseconds to wait before processing translations | `500` |
+| `instruction` | Additional instruction for the translator (e.g., tone, style). Does not affect the cache key | `''` |
 | `freeze` | Freeze mode to prevent translations from being queued | `false` |
 
 ### BCP 47 Language Tags
@@ -120,6 +122,31 @@ GPTrans stands out by combining advanced AI capabilities with efficient batching
 
 If you're looking to streamline your translation workflow and bring your applications to a global audience effortlessly, GPTrans is the perfect choice!
 
+## 📝 Translation Instructions
+
+The `instruction` option lets you guide the AI translator's style, tone, or behavior without creating a separate cache entry. Unlike `context` (which produces separate translations for each unique context), `instruction` does not affect the cache key — so the same text with the same context always maps to the same cache entry regardless of the instruction used.
+
+### Usage
+
+```javascript
+const gptrans = new GPTrans({
+  from: 'en',
+  target: 'es-AR',
+  instruction: 'Use natural and colloquial tone'
+});
+
+console.log(gptrans.t('Welcome to our platform'));
+console.log(gptrans.t('Please verify your identity'));
+```
+
+### Instruction vs Context
+
+| | `context` | `instruction` |
+|---|---|---|
+| **Purpose** | Semantic information (gender, domain) | Style guidance (tone, formality) |
+| **Affects cache key** | Yes — different contexts create separate translations | No — same key regardless of instruction |
+| **Example** | `'Use natural tone'` |
+
 ## 🔄 Preloading Translations
 
 The `preload()` method allows you to pre-translate all texts in your database. It now supports advanced options for improved translation accuracy through reference translations and alternate base languages.

package/index.js

@@ -64,7 +64,7 @@ class GPTrans {
         return isLanguageAvailable(langCode);
     }
 
-    constructor({ from = 'en-US', target = 'es', model = 'sonnet45', batchThreshold = 1500, debounceTimeout = 500, promptFile = null, name = '', context = '', freeze = false, debug = false } = {}) {
+    constructor({ from = 'en-US', target = 'es', model = 'sonnet45', batchThreshold = 1500, debounceTimeout = 500, promptFile = null, name = '', context = '', instruction = '', freeze = false, debug = false } = {}) {
 
         target = this.normalizeBCP47(target);
         from = this.normalizeBCP47(from);
@@ -99,6 +99,7 @@ class GPTrans {
         this.modelKey = model;
         this.promptFile = promptFile ?? new URL('./prompt/translate.md', import.meta.url).pathname;
         this.context = context;
+        this.instruction = instruction;
         this.freeze = freeze;
         this.modelConfig = {
             options: {
@@ -215,15 +216,15 @@ class GPTrans {
         const textsToTranslate = batch.map(([_, text]) => text).join(`\n${this.divider}\n`);
         try {
             const translations = await this._translate(textsToTranslate, batch, batchReferences, this.preloadBaseLanguage);
-            
+
             // Try different split strategies to be more robust
             let translatedTexts = translations.split(`\n${this.divider}\n`);
-            
+
             // If split doesn't match batch size, try alternative separators
             if (translatedTexts.length !== batch.length) {
                 // Try without newlines around divider
                 translatedTexts = translations.split(this.divider);
-                
+
                 // If still doesn't match, try with just newline
                 if (translatedTexts.length !== batch.length) {
                     translatedTexts = translations.split(/\n{2,}/); // Split by multiple newlines
@@ -231,7 +232,7 @@ class GPTrans {
             }
 
             const contextHash = this._hash(context);
-            
+
             // Validate we have the right number of translations
             if (translatedTexts.length !== batch.length) {
                 console.error(`❌ Translation count mismatch:`);
@@ -239,7 +240,7 @@ class GPTrans {
                 console.error(`   Received: ${translatedTexts.length} translations`);
                 console.error(`   Batch keys: ${batch.map(([key]) => key).join(', ')}`);
                 console.error(`\n📝 Full response from model:\n${translations}\n`);
-                
+
                 // Try to save what we can
                 const minLength = Math.min(translatedTexts.length, batch.length);
                 for (let i = 0; i < minLength; i++) {
@@ -322,6 +323,7 @@ class GPTrans {
             model.replace({
                 '{INPUT}': text,
                 '{CONTEXT}': this.context,
+                '{INSTRUCTION}': this.instruction,
                 '{REFERENCES}': referencesText,
                 '{TARGET_ISO}': this.replaceTarget.TARGET_ISO,
                 '{TARGET_LANG}': this.replaceTarget.TARGET_LANG,
@@ -333,7 +335,7 @@ class GPTrans {
                 '{FROM_DENONYM}': fromReplace.FROM_DENONYM,
             });
 
-            return model.block();
+            return await model.block({ addSystemExtra: false });
 
         } finally {
             // Always release the lock
@@ -407,14 +409,14 @@ class GPTrans {
 
         // Track which keys need translation
         const keysNeedingTranslation = [];
-        
+
         for (const [context, pairs] of this.dbFrom.entries()) {
             // Skip the _context metadata
             if (context === '_context') continue;
-            
+
             this.setContext(context);
             const contextHash = this._hash(context);
-            
+
             for (const [key, text] of Object.entries(pairs)) {
                 // Check if translation already exists
                 if (!this.dbTarget.get(contextHash, key)) {
@@ -438,7 +440,7 @@ class GPTrans {
             const checkInterval = setInterval(() => {
                 // Check if there are still pending translations or batch being processed
                 const hasPending = this.pendingTranslations.size > 0 || this.isProcessingBatch;
-                
+
                 // Check if all needed translations are now complete
                 let allTranslated = true;
                 for (const { contextHash, key } of keysNeedingTranslation) {
@@ -447,7 +449,7 @@ class GPTrans {
                         break;
                     }
                 }
-                
+
                 if (allTranslated && !hasPending) {
                     clearInterval(checkInterval);
                     resolve();
@@ -610,7 +612,7 @@ class GPTrans {
                 '{FROM_DENONYM}': this.replaceFrom.FROM_DENONYM,
             });
 
-            return await model.block();
+            return await model.block({ addSystemExtra: false });
 
         } finally {
             releaseLock();
@@ -696,7 +698,7 @@ class GPTrans {
             // Save translated image - preserve original file format
             const filename = path.basename(targetPath, path.extname(targetPath));
             const formatOptions = generator.getReferenceMetadata();
-            
+
             // Apply default quality settings for JPEG images
             if (formatOptions && (formatOptions.format === 'jpeg' || formatOptions.format === 'jpg')) {
                 // Apply custom quality if specified, otherwise use defaults
@@ -705,7 +707,7 @@ class GPTrans {
                 formatOptions.chromaSubsampling = '4:4:4';  // Better color quality
                 formatOptions.optimiseCoding = true;  // Lossless size reduction
             }
-            
+
             await generator.save({ directory: targetDir, filename, formatOptions });
         } else {
             throw new Error('No translated image was generated');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gptrans",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "🚆 GPTrans - The smarter AI-powered way to translate.",
   "keywords": [
     "translate",

package/prompt/translate.md

@@ -1,5 +1,6 @@
 # Goal
 Translation from {FROM_ISO} to {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) with cultural adaptations.
+{INSTRUCTION}
 
 ## Text to translate
 ```
@@ -22,4 +23,4 @@ Translation from {FROM_ISO} to {TARGET_ISO} ({TARGET_DENONYM} {TARGET_LANG}) wit
 
 
 # Context
-{CONTEXT}
+{CONTEXT}

package/skills/gptrans/SKILL.md

@@ -110,6 +110,7 @@ console.log(gptrans.setContext().t('Welcome back'));
 | `freeze` | `boolean` | `false` | Prevent new translations from being queued |
 | `name` | `string` | `''` | Instance name (isolates cache files) |
 | `context` | `string` | `''` | Default context for translations |
+| `instruction` | `string` | `''` | Additional instruction for the translator (tone, style). Does not affect cache key |
 | `promptFile` | `string` | `null` | Custom prompt file path (overrides built-in) |
 | `debug` | `boolean` | `false` | Enable debug output |
 
@@ -186,6 +187,17 @@ console.log(gptrans.setContext('The user is female').t('You are welcome'));
 console.log(gptrans.setContext().t('Thank you'));
 ```
 
+### Set instruction for translation style
+
+```javascript
+const gptrans = new GPTrans({
+  from: 'en', target: 'es-AR',
+  instruction: 'Use a formal and professional tone'
+});
+
+console.log(gptrans.t('Welcome to our platform'));
+```
+
 ### Refine existing translations
 
 Improve cached translations with specific instructions:
@@ -276,6 +288,7 @@ if (GPTrans.isLanguageAvailable('pt-BR')) {
 - The `t()` method is synchronous and non-blocking. It returns the original text on first call and the cached translation on subsequent calls. Do NOT `await` it.
 - To ensure translations are complete before using them, call `await gptrans.preload()` after registering texts with `t()`.
 - Use `setContext()` for gender-aware or domain-specific translations. Context is captured per-batch and auto-resets when changed.
+- Use the `instruction` constructor option for style/tone guidance (e.g., "Use a more natural tone"). Unlike `context`, `instruction` does NOT affect the cache key — different instructions for the same text overwrite the same translation entry.
 - Prefer passing an array of instructions to `refine()` over multiple calls — it processes everything in a single API pass.
 - Use model arrays (`model: ['sonnet45', 'gpt41']`) for production resilience with automatic fallback.
 - Translation caches live in `db/gptrans_<locale>.json`. These files can be manually edited to override specific translations.