gptrans 2.0.2 → 2.0.6

package/README.md

@@ -15,16 +15,19 @@ 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
 
 ```bash
 npm install gptrans
 ```
+
 > **AI Skill**: You can also add GPTrans as a skill for AI agentic development:
 > ```bash
 > npx skills add https://github.com/clasen/GPTrans --skill gptrans
 > ```
+
 ### 🌐 Environment Setup
 
 GPTrans uses dotenv for environment configuration. Create a `.env` file in your project root and add your API keys:
@@ -76,6 +79,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 +124,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: {
@@ -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,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gptrans",
   "type": "module",
-  "version": "2.0.2",
+  "version": "2.0.6",
   "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.