gptrans 2.0.4 → 2.0.8

package/README.md

@@ -22,10 +22,12 @@ Whether you're building a multilingual website, a mobile app, or a localization
 ```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:

package/index.js

@@ -131,17 +131,45 @@ class GPTrans {
     t(text, params = {}) {
         const key = this._textToKey(text);
         const translation = this.get(key, text) || text;
+        return this._applyParams(translation, params);
+    }
 
-        return Object.entries(params).reduce(
-            (text, [key, value]) => text.replace(`{${key}}`, value),
-            translation
-        );
+    async tAsync(text, params = {}) {
+        const key = this._textToKey(text);
+        const { contextHash, translation, needsTranslation } = this._resolveTranslationState(key, text);
+
+        if (!needsTranslation) {
+            return this._applyParams(translation || text, params);
+        }
+
+        // If this key was enqueued via t(), avoid duplicate work in a later batch.
+        this._dequeuePendingTranslation(key);
+
+        const translatedText = await this._translate(text, [[key, text]], {}, this.preloadBaseLanguage);
+        const immediateTranslation = translatedText.trim();
+        this.dbTarget.set(contextHash, key, immediateTranslation);
+
+        return this._applyParams(immediateTranslation, params);
     }
 
     get(key, text) {
+        const { translation, needsTranslation } = this._resolveTranslationState(key, text);
+        if (needsTranslation) {
+            this._enqueuePendingTranslation(key, text);
+        }
+        return translation;
+    }
 
+    _applyParams(text, params = {}) {
+        return Object.entries(params).reduce(
+            (translated, [paramKey, value]) => translated.replace(`{${paramKey}}`, value),
+            text
+        );
+    }
+
+    _resolveTranslationState(key, text) {
         if (!text || !text.trim()) {
-            return text;
+            return { contextHash: this._hash(this.context), translation: text, needsTranslation: false };
         }
 
         const contextHash = this._hash(this.context);
@@ -152,41 +180,56 @@ class GPTrans {
             this.dbFrom.set('_context', contextHash, this.context);
         }
 
-        if (!translation) {
+        if (translation) {
+            return { contextHash, translation, needsTranslation: false };
+        }
 
-            // Skip translation if context is empty and languages are the same
-            if (!this.context && this.replaceFrom.FROM_ISO === this.replaceTarget.TARGET_ISO) {
-                return text;
-            }
+        if (!this.context && this.replaceFrom.FROM_ISO === this.replaceTarget.TARGET_ISO) {
+            return { contextHash, translation: text, needsTranslation: false };
+        }
 
-            if (this.freeze) {
-                console.log(`Freeze mode: [${key}] ${text}`);
-                return text;
-            }
+        if (this.freeze) {
+            console.log(`Freeze mode: [${key}] ${text}`);
+            return { contextHash, translation: text, needsTranslation: false };
+        }
 
-            this.pendingTranslations.set(key, text);
-            this.pendingCharCount += text.length; // Update character count
+        return { contextHash, translation: null, needsTranslation: true };
+    }
 
-            // Clear existing timer
-            if (this.debounceTimer) {
-                clearTimeout(this.debounceTimer);
-            }
+    _enqueuePendingTranslation(key, text) {
+        const existingText = this.pendingTranslations.get(key);
+        if (existingText) {
+            this.pendingCharCount -= existingText.length;
+        }
 
-            // Set new timer - capture context at scheduling time
-            const capturedContext = this.context;
-            this.debounceTimer = setTimeout(() => {
-                if (this.pendingTranslations.size > 0) {
-                    this._processBatch(capturedContext);
-                }
-            }, this.debounceTimeout);
+        this.pendingTranslations.set(key, text);
+        this.pendingCharCount += text.length;
+
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
 
-            // Process if we hit the character count threshold
-            if (this.pendingCharCount >= this.batchThreshold) {
-                clearTimeout(this.debounceTimer);
-                this._processBatch(this.context);
+        const capturedContext = this.context;
+        this.debounceTimer = setTimeout(() => {
+            if (this.pendingTranslations.size > 0) {
+                this._processBatch(capturedContext);
             }
+        }, this.debounceTimeout);
+
+        if (this.pendingCharCount >= this.batchThreshold) {
+            clearTimeout(this.debounceTimer);
+            this._processBatch(this.context);
         }
-        return translation;
+    }
+
+    _dequeuePendingTranslation(key) {
+        const queuedText = this.pendingTranslations.get(key);
+        if (!queuedText) {
+            return;
+        }
+
+        this.pendingTranslations.delete(key);
+        this.pendingCharCount = Math.max(0, this.pendingCharCount - queuedText.length);
     }
 
     async _processBatch(context) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gptrans",
   "type": "module",
-  "version": "2.0.4",
+  "version": "2.0.8",
   "description": "🚆 GPTrans - The smarter AI-powered way to translate.",
   "keywords": [
     "translate",
@@ -26,7 +26,7 @@
   },
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/**/*.test.js"
   },
   "author": "Martin Clasen",
   "license": "MIT",

package/test/gptrans.tAsync.test.js

@@ -0,0 +1,143 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import GPTrans from '../index.js';
+
+function createMemoryDb() {
+    const store = new Map();
+    return {
+        get(context, key) {
+            return store.get(context)?.get(key);
+        },
+        set(context, key, value) {
+            if (!store.has(context)) {
+                store.set(context, new Map());
+            }
+            store.get(context).set(key, value);
+        },
+        entries() {
+            return Array.from(store.entries()).map(([context, pairs]) => [
+                context,
+                Object.fromEntries(pairs.entries())
+            ]);
+        },
+        async del(context, key) {
+            const pairs = store.get(context);
+            if (!pairs) {
+                return;
+            }
+            pairs.delete(key);
+            if (pairs.size === 0) {
+                store.delete(context);
+            }
+        }
+    };
+}
+
+function createTestInstance() {
+    const gp = new GPTrans({
+        from: 'en-US',
+        target: 'es',
+        debounceTimeout: 10_000,
+        batchThreshold: 5000,
+        name: `unit_${Date.now()}_${Math.random().toString(36).slice(2)}`
+    });
+
+    gp.dbFrom = createMemoryDb();
+    gp.dbTarget = createMemoryDb();
+
+    return gp;
+}
+
+test('tAsync translates immediately and caches result', async () => {
+    const gp = createTestInstance();
+    let translateCalls = 0;
+
+    gp._translate = async (text) => {
+        translateCalls += 1;
+        assert.equal(text, 'Hello {name}');
+        return 'Hola {name}';
+    };
+
+    const first = await gp.tAsync('Hello {name}', { name: 'Martin' });
+    const second = await gp.tAsync('Hello {name}', { name: 'Martin' });
+
+    assert.equal(first, 'Hola Martin');
+    assert.equal(second, 'Hola Martin');
+    assert.equal(translateCalls, 1);
+
+    if (gp.debounceTimer) {
+        clearTimeout(gp.debounceTimer);
+    }
+});
+
+test('tAsync removes queued batch item to avoid duplicate work', async () => {
+    const gp = createTestInstance();
+    let translateCalls = 0;
+
+    gp._translate = async () => {
+        translateCalls += 1;
+        return 'Comprar';
+    };
+
+    const key = gp._textToKey('Buy');
+
+    // Enqueue via sync API (batch/background path).
+    const syncValue = gp.t('Buy');
+    assert.equal(syncValue, 'Buy');
+    assert.equal(gp.pendingTranslations.get(key), 'Buy');
+    assert.equal(gp.pendingCharCount, 'Buy'.length);
+
+    // Force immediate translation for same key.
+    const asyncValue = await gp.tAsync('Buy');
+    assert.equal(asyncValue, 'Comprar');
+
+    assert.equal(translateCalls, 1);
+    assert.equal(gp.pendingTranslations.has(key), false);
+    assert.equal(gp.pendingCharCount, 0);
+
+    if (gp.debounceTimer) {
+        clearTimeout(gp.debounceTimer);
+    }
+});
+
+test('preload translates missing keys from dbFrom into dbTarget', async () => {
+    const gp = createTestInstance();
+    gp.debounceTimeout = 1;
+    let translateCalls = 0;
+
+    const context = 'checkout';
+    const sourceText = 'Buy now';
+    const key = gp._textToKey(sourceText);
+    const contextHash = gp._hash(context);
+
+    gp.dbFrom.set(context, key, sourceText);
+    gp.dbFrom.set('_context', contextHash, context);
+
+    gp._translate = async (text) => {
+        translateCalls += 1;
+        assert.equal(text, sourceText);
+        return 'Comprar ahora';
+    };
+
+    const originalMmix = GPTrans.mmix;
+    GPTrans.mmix = () => ({
+        limiter: {
+            updateSettings() {
+            }
+        }
+    });
+
+    try {
+        await gp.preload();
+
+        assert.equal(translateCalls, 1);
+        assert.equal(gp.dbTarget.get(contextHash, key), 'Comprar ahora');
+        assert.deepEqual(gp.preloadReferences, []);
+        assert.equal(gp.preloadBaseLanguage, null);
+    } finally {
+        GPTrans.mmix = originalMmix;
+        if (gp.debounceTimer) {
+            clearTimeout(gp.debounceTimer);
+        }
+    }
+});