gptrans 2.1.10 → 2.2.4

package/skills/gptrans/SKILL.md

@@ -81,11 +81,13 @@ You can manually edit translation files to override specific entries.
 
 ```javascript
 import GPTrans from 'gptrans';
+import path from 'node:path';
 
+const dbPath = path.join(import.meta.dirname, 'db');
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en-US',
-  target: 'es-AR',
-  model: 'sonnet45'
+  target: 'es-AR'
 });
 
 // Translate text — returns original on first call, cached translation after
@@ -104,7 +106,7 @@ console.log(gptrans.setContext().t('Welcome back'));
 | --- | --- | --- | --- |
 | `from` | `string` | `'en-US'` | Source language (BCP 47) |
 | `target` | `string` | `'es'` | Target language (BCP 47) |
-| `model` | `string \| string[]` | `'sonnet45'` | Model key or array for fallback chain |
+| `model` | `string \| string[]` | `['sonnet5@50', 'gpt56luna@100']` | ModelMix shortcut or ordered fallback chain; supports `@<effort>` from `0` to `100` |
 | `batchThreshold` | `number` | `1500` | Max characters before triggering batch |
 | `debounceTimeout` | `number` | `500` | Milliseconds to wait before processing |
 | `freeze` | `boolean` | `false` | Prevent new translations from being queued |
@@ -119,7 +121,7 @@ console.log(gptrans.setContext().t('Welcome back'));
 ### Translate text with parameter substitution
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 console.log(gptrans.t('Hello, {name}!', { name: 'Martin' }));
 // First call: "Hello, Martin!" (original)
 // After caching: "Hola, Martin!" (translated)
@@ -129,16 +131,19 @@ console.log(gptrans.t('Hello, {name}!', { name: 'Martin' }));
 
 ```javascript
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en',
   target: 'fr',
-  model: ['sonnet45', 'gpt41']  // falls back to gpt41 if sonnet45 fails
+  model: ['sonnet5@50', 'gpt56luna@100']
 });
 ```
 
+Use `model@<effort>` with an integer from `0` to `100` to override the unified effort for one model. The default chain uses `sonnet5` at effort `50`, then falls back to `gpt56luna` at effort `100`.
+
 ### Pre-translate all pending texts
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es' });
 
 // Register texts
 gptrans.t('Welcome');
@@ -157,7 +162,7 @@ console.log(gptrans.t('Welcome'));  // "Bienvenido"
 Use existing translations in other languages as context for better accuracy:
 
 ```javascript
-const gptrans = new GPTrans({ from: 'es', target: 'fr' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'fr' });
 await gptrans.preload({
   references: ['en', 'pt']  // AI sees English and Portuguese as reference
 });
@@ -168,7 +173,7 @@ await gptrans.preload({
 Translate from an intermediate language instead of the original (useful for gender-neutral intermediaries):
 
 ```javascript
-const gptrans = new GPTrans({ from: 'es', target: 'pt' });
+const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
 await gptrans.preload({
   baseLanguage: 'en',       // translate FROM English instead of Spanish
   references: ['es']        // show original Spanish for context
@@ -178,7 +183,7 @@ await gptrans.preload({
 ### Set context for gender-aware translations
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 
 // Context applies to next translation(s) in the batch
 console.log(gptrans.setContext('The user is female').t('You are welcome'));
@@ -191,6 +196,7 @@ console.log(gptrans.setContext().t('Thank you'));
 
 ```javascript
 const gptrans = new GPTrans({
+  path: dbPath,
   from: 'en', target: 'es-AR',
   instruction: 'Use a formal and professional tone'
 });
@@ -203,7 +209,7 @@ console.log(gptrans.t('Welcome to our platform'));
 Improve cached translations with specific instructions:
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es-AR' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
 
 // Single instruction
 await gptrans.refine('Use a more colloquial tone');
@@ -224,7 +230,7 @@ await gptrans.refine('More formal', { promptFile: './my-refine-prompt.md' });
 Requires `GEMINI_API_KEY`. Auto-detects language folders for output path:
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es' });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es' });
 
 // en/banner.jpg → es/banner.jpg (auto sibling folder)
 const translatedPath = await gptrans.img('en/banner.jpg');
@@ -240,7 +246,7 @@ const result = await gptrans.img('en/hero.jpg', {
 ### Freeze mode (prevent new translations)
 
 ```javascript
-const gptrans = new GPTrans({ from: 'en', target: 'es', freeze: true });
+const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es', freeze: true });
 
 // Returns original text, logs "[key] text" — nothing queued
 console.log(gptrans.t('New text'));
@@ -262,9 +268,9 @@ await gptrans.purge();
 ```javascript
 // Spain Spanish → Argentina Spanish
 const es2ar = new GPTrans({
+  path: dbPath,
   from: 'es-ES',
-  target: 'es-AR',
-  model: 'sonnet45'
+  target: 'es-AR'
 });
 
 console.log(es2ar.t('Eres muy bueno'));
@@ -290,7 +296,7 @@ if (GPTrans.isLanguageAvailable('pt-BR')) {
 - 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.
+- Use model arrays (`model: ['sonnet5@50', 'gpt56luna@100']`) for production resilience with automatic fallback. The optional `@<effort>` suffix accepts integers from `0` to `100` and applies only to that model.
 - Translation caches live in `db/gptrans_<locale>.json`. These files can be manually edited to override specific translations.
 - The `name` constructor option isolates cache files (`db/gptrans_<name>_<locale>.json`), useful for multiple independent translation contexts in the same project.
 - When translating images, ensure `GEMINI_API_KEY` is set. The `img()` method auto-creates sibling language folders.
@@ -301,7 +307,7 @@ if (GPTrans.isLanguageAvailable('pt-BR')) {
 
 | Method | Returns | Description |
 | --- | --- | --- |
-| `new GPTrans(options)` | `GPTrans` | Create instance with `from`, `target`, `model`, etc. |
+| `new GPTrans(options)` | `GPTrans` | Create an instance. `options.path` must be an absolute directory path. |
 | `.t(text, params?)` | `string` | Translate text (sync). Returns cached or original. |
 | `.get(key, text)` | `string \| undefined` | Get translation by key, queue if missing. |
 | `.setContext(context?)` | `this` | Set context for next batch (gender, tone, etc.). |

package/test/gptrans.batch.test.js

@@ -1,11 +1,22 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
 import GPTrans from '../index.js';
 
 function createMemoryDb() {
     const store = new Map();
     return {
-        get(context, key) {
+        getSync(...keys) {
+            if (keys.length === 0) {
+                return Object.fromEntries(Array.from(store.entries()).map(([context, pairs]) => [
+                    context,
+                    Object.fromEntries(pairs.entries())
+                ]));
+            }
+            const [context, key] = keys;
+            if (keys.length === 1) {
+                return Object.fromEntries(store.get(context)?.entries() ?? []);
+            }
             return store.get(context)?.get(key);
         },
         set(context, key, value) {
@@ -35,6 +46,7 @@ function createTestInstance() {
         target: 'en-US',
         debounceTimeout: 10_000,
         batchThreshold: 50_000,
+        path: tmpdir(),
         name: `unit_${Date.now()}_${Math.random().toString(36).slice(2)}`
     });
 
@@ -63,9 +75,9 @@ test('_processBatch splits correctly with \\n------\\n separators', async (t) =>
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Goodbye');
-    assert.equal(gp.dbTarget.get(h, 'k3'), 'Thank you');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), 'Thank you');
 
     GPTrans.mmix = originalMmix;
 });
@@ -86,9 +98,9 @@ test('_processBatch falls back to split by divider without newlines', async (t)
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Goodbye');
-    assert.equal(gp.dbTarget.get(h, 'k3'), 'Thank you');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), 'Thank you');
 
     GPTrans.mmix = originalMmix;
 });
@@ -149,10 +161,10 @@ test('_processBatch discards batch when all translations are identical (3+)', as
 
     const h = gp._hash('');
     // Nothing should be saved
-    assert.equal(gp.dbTarget.get(h, 'k1'), undefined);
-    assert.equal(gp.dbTarget.get(h, 'k2'), undefined);
-    assert.equal(gp.dbTarget.get(h, 'k3'), undefined);
-    assert.equal(gp.dbTarget.get(h, 'k4'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), undefined);
+    assert.equal(gp.dbTarget.getSync(h, 'k4'), undefined);
 
     assert.ok(errors.some(e => e.includes('translations are identical')));
 
@@ -174,8 +186,8 @@ test('_processBatch allows batch of 2 with identical translations (edge case)',
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Yes');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Yes');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Yes');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Yes');
 
     GPTrans.mmix = originalMmix;
 });
@@ -196,9 +208,9 @@ test('_processBatch saves partial duplicates normally', async (t) => {
     await gp._processBatch('');
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k3'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), 'Goodbye');
 
     GPTrans.mmix = originalMmix;
 });
@@ -227,9 +239,9 @@ test('_processBatch saves partial results on count mismatch', async (t) => {
     console.error = origError;
 
     const h = gp._hash('');
-    assert.equal(gp.dbTarget.get(h, 'k1'), 'Hello');
-    assert.equal(gp.dbTarget.get(h, 'k2'), 'Goodbye');
-    assert.equal(gp.dbTarget.get(h, 'k3'), undefined); // Not saved
+    assert.equal(gp.dbTarget.getSync(h, 'k1'), 'Hello');
+    assert.equal(gp.dbTarget.getSync(h, 'k2'), 'Goodbye');
+    assert.equal(gp.dbTarget.getSync(h, 'k3'), undefined); // Not saved
 
     assert.ok(errors.some(e => e.includes('Translation count mismatch')));
 

package/test/gptrans.tAsync.test.js

@@ -1,11 +1,24 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { access, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import GPTrans from '../index.js';
 
 function createMemoryDb() {
     const store = new Map();
     return {
-        get(context, key) {
+        getSync(...keys) {
+            if (keys.length === 0) {
+                return Object.fromEntries(Array.from(store.entries()).map(([context, pairs]) => [
+                    context,
+                    Object.fromEntries(pairs.entries())
+                ]));
+            }
+            const [context, key] = keys;
+            if (keys.length === 1) {
+                return Object.fromEntries(store.get(context)?.entries() ?? []);
+            }
             return store.get(context)?.get(key);
         },
         set(context, key, value) {
@@ -39,6 +52,7 @@ function createTestInstance() {
         target: 'es',
         debounceTimeout: 10_000,
         batchThreshold: 5000,
+        path: tmpdir(),
         name: `unit_${Date.now()}_${Math.random().toString(36).slice(2)}`
     });
 
@@ -131,7 +145,7 @@ test('preload translates missing keys from dbFrom into dbTarget', async () => {
         await gp.preload();
 
         assert.equal(translateCalls, 1);
-        assert.equal(gp.dbTarget.get(contextHash, key), 'Comprar ahora');
+        assert.equal(gp.dbTarget.getSync(contextHash, key), 'Comprar ahora');
         assert.deepEqual(gp.preloadReferences, []);
         assert.equal(gp.preloadBaseLanguage, null);
     } finally {
@@ -141,3 +155,143 @@ test('preload translates missing keys from dbFrom into dbTarget', async () => {
         }
     }
 });
+
+test('constructor requires an absolute database path', () => {
+    assert.throws(() => new GPTrans(), /requires an absolute "path" option/);
+    assert.throws(() => new GPTrans({ path: './db' }), /requires an absolute "path" option/);
+});
+
+test('the default model chain uses the configured efforts and renders the EJS prompt', async () => {
+    const previousAnthropicKey = process.env.ANTHROPIC_API_KEY;
+    const previousOpenAiKey = process.env.OPENAI_API_KEY;
+    process.env.ANTHROPIC_API_KEY = 'test-anthropic-key';
+    process.env.OPENAI_API_KEY = 'test-openai-key';
+
+    try {
+        const model = GPTrans.mmix();
+        assert.deepEqual(
+            model.models.map(({ key }) => key),
+            ['claude-sonnet-5', 'gpt-5.6-luna']
+        );
+        assert.equal(model.models[0].provider.config.effort, 50);
+        assert.equal(model.models[1].provider.config.effort, 100);
+
+        const gp = new GPTrans({ path: tmpdir(), freeze: true, name: 'modelmix-render' });
+        assert.deepEqual(gp.modelKey, ['sonnet5@50', 'gpt56luna@100']);
+        model.addTextFromFile(gp.promptFile);
+        model.assign({
+            INPUT: 'Hello',
+            CONTEXT: 'Greeting',
+            INSTRUCTION: 'Be friendly',
+            REFERENCES: '',
+            TARGET_ISO: 'es',
+            TARGET_LANG: 'Spanish',
+            TARGET_COUNTRY: 'Spain',
+            TARGET_DENONYM: 'Spanish',
+            FROM_ISO: 'en-US',
+            FROM_LANG: 'English',
+            FROM_COUNTRY: 'United States',
+            FROM_DENONYM: 'American'
+        });
+        const messages = await model.prepareMessages();
+        const renderedPrompt = messages[0].content[0].text;
+        assert.match(renderedPrompt, /Translation from en-US to es/);
+        assert.match(renderedPrompt, /```\nHello\n```/);
+        assert.doesNotMatch(renderedPrompt, /<%-\s*[A-Z_]+\s*%>/);
+    } finally {
+        if (previousAnthropicKey === undefined) delete process.env.ANTHROPIC_API_KEY;
+        else process.env.ANTHROPIC_API_KEY = previousAnthropicKey;
+        if (previousOpenAiKey === undefined) delete process.env.OPENAI_API_KEY;
+        else process.env.OPENAI_API_KEY = previousOpenAiKey;
+    }
+});
+
+test('_translate uses assign() with the absolute built-in prompt path', async () => {
+    const gp = createTestInstance();
+    const originalMmix = GPTrans.mmix;
+    const calls = {};
+    const model = {
+        setSystem(value) {
+            calls.system = value;
+        },
+        addTextFromFile(value) {
+            calls.promptFile = value;
+        },
+        assign(value) {
+            calls.templateData = value;
+        },
+        async block(options) {
+            calls.blockOptions = options;
+            return 'Hola';
+        }
+    };
+    GPTrans.mmix = () => model;
+
+    try {
+        assert.equal(await gp._translate('Hello'), 'Hola');
+        assert.equal(path.isAbsolute(calls.promptFile), true);
+        assert.equal(path.basename(calls.promptFile), 'translate.md');
+        await access(calls.promptFile);
+        assert.equal(calls.templateData.INPUT, 'Hello');
+        assert.equal(calls.templateData.FROM_ISO, 'en-US');
+        assert.equal(calls.templateData.TARGET_ISO, 'es');
+        assert.match(calls.system, /<%- FROM_LANG %>/);
+        assert.deepEqual(calls.blockOptions, { addSystemExtra: false });
+    } finally {
+        GPTrans.mmix = originalMmix;
+    }
+});
+
+test('DeepBase 3.9 cache is available to synchronous translations', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'gptrans-deepbase-'));
+    const originalMmix = GPTrans.mmix;
+    const gp = new GPTrans({
+        from: 'en',
+        target: 'es',
+        freeze: true,
+        debounceTimeout: 1,
+        path: directory,
+        name: 'sync-cache'
+    });
+
+    try {
+        const text = 'Hello';
+        const key = gp._textToKey(text);
+        const contextHash = gp._hash('');
+        await gp.dbTarget.set(contextHash, key, 'Hola');
+
+        assert.equal(gp.t(text), 'Hola');
+        assert.equal(gp.dbTarget.getSync(contextHash, key), 'Hola');
+
+        gp.setFreeze(false);
+        const sourceText = 'New source text';
+        const sourceKey = gp._textToKey(sourceText);
+        gp._translate = async () => 'Nuevo texto fuente';
+        GPTrans.mmix = () => ({ limiter: { updateSettings() {} } });
+
+        gp.t(sourceText);
+        await gp.preload();
+
+        assert.equal(gp.dbFrom.getSync('', sourceKey), sourceText);
+        assert.equal(gp.dbTarget.getSync(contextHash, sourceKey), 'Nuevo texto fuente');
+
+        let refinePromptFile;
+        gp._processRefineBatch = async (entries, instruction, promptFile) => {
+            assert.equal(entries.length, 2);
+            assert.equal(instruction, 'Use a formal tone');
+            refinePromptFile = promptFile;
+        };
+        await gp.refine('Use a formal tone');
+        assert.equal(path.isAbsolute(refinePromptFile), true);
+        assert.equal(path.basename(refinePromptFile), 'refine.md');
+        await access(refinePromptFile);
+    } finally {
+        GPTrans.mmix = originalMmix;
+        if (gp.debounceTimer) {
+            clearTimeout(gp.debounceTimer);
+        }
+        await gp.dbTarget.dispose({ clearMemory: true, releaseInstance: true });
+        await gp.dbFrom.dispose({ clearMemory: true, releaseInstance: true });
+        await rm(directory, { recursive: true });
+    }
+});

package/test-image-translation.js

@@ -1,10 +1,6 @@
 import GPTrans from './index.js';
 import path from 'path';
 import fs from 'fs';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
 
 async function testImageTranslation() {
     try {
@@ -12,13 +8,14 @@ async function testImageTranslation() {
 
         // Initialize GPTrans with Portuguese as target language
         const gptrans = new GPTrans({
+            path: path.join(import.meta.dirname, 'db'),
             from: 'en-US',
             target: 'pt-BR',
             model: 'sonnet45'
         });
 
         // Test image path (you'll need to provide an actual image)
-        const testImagePath = path.join(__dirname, 'test-image.jpg');
+        const testImagePath = path.join(import.meta.dirname, 'test-image.jpg');
 
         // Check if test image exists
         if (!fs.existsSync(testImagePath)) {
@@ -67,4 +64,3 @@ async function testImageTranslation() {
 
 // Run the test
 testImageTranslation();
-