transduck 0.7.0 → 0.9.0

package/dist/cli.js

@@ -637,7 +637,7 @@ export async function runStats(opts) {
 }
 // CLI entry point
 const program = new Command();
-program.name('transduck').description('AI-native translation tool').version('0.7.0');
+program.name('transduck').description('AI-native translation tool').version('0.9.0');
 program.command('init')
     .description('Initialize a new transduck project')
     .action(async () => {

package/dist/config.d.ts

@@ -11,6 +11,7 @@ export interface TransduckConfig {
     backendModel: string;
     backendTimeout: number;
     backendMaxRetries: number;
+    backendMaxConcurrency: number;
     sharedUrl: string | null;
     readOnly: boolean;
 }

package/dist/config.js

@@ -37,6 +37,10 @@ export function loadConfig(path) {
     const backendModel = backend.model ?? 'gpt-4.1-mini';
     const backendTimeout = backend.timeout_seconds ?? 10;
     const backendMaxRetries = backend.max_retries ?? 2;
+    const backendMaxConcurrency = backend.max_concurrency ?? 10;
+    if (!Number.isInteger(backendMaxConcurrency) || backendMaxConcurrency < 1) {
+        throw new Error(`backend.max_concurrency must be a positive integer (got ${backend.max_concurrency})`);
+    }
     const sharedUrl = process.env.TRANSDUCK_SHARED_URL || raw.storage?.shared_url || null;
     let readOnly = raw.runtime?.read_only ?? false;
     if (provider === 'claude_code') {
@@ -55,6 +59,7 @@ export function loadConfig(path) {
         backendModel,
         backendTimeout,
         backendMaxRetries,
+        backendMaxConcurrency,
         readOnly,
     };
 }

package/dist/handler.d.ts

@@ -1,4 +1,13 @@
 import { type TranslationHook } from './hooks.js';
+/**
+ * Bounded-concurrency semaphore. Workers call `acquire()` to get a slot,
+ * then `release()` when done. When the active count is at the limit,
+ * further `acquire()` calls queue until a slot frees up.
+ */
+export declare function createSemaphore(limit: number): {
+    acquire(): Promise<void>;
+    release(): void;
+};
 interface TranslationRequestString {
     text: string;
     context?: string;

package/dist/handler.js

@@ -8,6 +8,46 @@ import { fireHooks } from './hooks.js';
 function hash(text) {
     return createHash('sha256').update(text).digest('hex');
 }
+/**
+ * Bounded-concurrency semaphore. Workers call `acquire()` to get a slot,
+ * then `release()` when done. When the active count is at the limit,
+ * further `acquire()` calls queue until a slot frees up.
+ */
+export function createSemaphore(limit) {
+    let active = 0;
+    const queue = [];
+    return {
+        acquire() {
+            return new Promise(resolve => {
+                if (active < limit) {
+                    active++;
+                    resolve();
+                }
+                else {
+                    queue.push(() => {
+                        active++;
+                        resolve();
+                    });
+                }
+            });
+        },
+        release() {
+            active--;
+            const next = queue.shift();
+            if (next)
+                next();
+        },
+    };
+}
+async function withSlot(sem, fn) {
+    await sem.acquire();
+    try {
+        return await fn();
+    }
+    finally {
+        sem.release();
+    }
+}
 let _store = null;
 let _sharedStore = null;
 async function getStore(configPath) {
@@ -48,34 +88,30 @@ export async function handleTranslationRequest(body, configPath, opts) {
     const targetLang = body.language.toUpperCase();
     const bodySourceLang = body.sourceLang?.toUpperCase();
     const projectContextHash = hash(cfg.projectContext);
-    const translations = {};
-    const plurals = {};
-    // Translate regular strings
-    for (const item of body.strings ?? []) {
+    // Single semaphore shared across strings and plurals so total outbound
+    // concurrency to the backend is bounded across both categories.
+    const sem = createSemaphore(cfg.backendMaxConcurrency);
+    const stringWork = (body.strings ?? []).map(item => withSlot(sem, async () => {
         const sourceLang = item.sourceLang?.toUpperCase() ?? bodySourceLang ?? cfg.sourceLang;
         const stringContextHash = hash(item.context ?? '');
-        const key = `${item.text}||${item.context ?? ''}`;
+        const key = `${item.text}||${item.context ?? ''}||${sourceLang}`;
         const lookupParams = {
             sourceText: item.text, sourceLang, targetLang,
             projectContextHash, stringContextHash,
         };
         // Tier 1: local cache
         const cached = await store.lookup(lookupParams);
-        if (cached !== null) {
-            translations[key] = cached;
-            continue;
-        }
+        if (cached !== null)
+            return [key, cached];
         // Tier 2: shared store
         if (shared) {
             const sharedCached = await shared.lookup(lookupParams);
             if (sharedCached !== null) {
-                // Propagate to local
                 await store.insert({
                     ...lookupParams, stringContext: item.context ?? '',
                     translatedText: sharedCached, model: cfg.backendModel, status: 'translated',
                 });
-                translations[key] = sharedCached;
-                continue;
+                return [key, sharedCached];
             }
         }
         // Backend call
@@ -98,37 +134,31 @@ export async function handleTranslationRequest(body, configPath, opts) {
                     };
                     await fireHooks([], event, opts.onTranslate);
                 }
-                translations[key] = translated;
-            }
-            else {
-                translations[key] = item.text;
+                return [key, translated];
             }
+            return [key, item.text];
         }
         catch {
-            translations[key] = item.text;
+            return [key, item.text];
         }
-    }
-    // Translate plurals
-    for (const item of body.plurals ?? []) {
+    }));
+    const pluralWork = (body.plurals ?? []).map(item => withSlot(sem, async () => {
         const sourceLang = item.sourceLang?.toUpperCase() ?? bodySourceLang ?? cfg.sourceLang;
         const stringContextHash = hash(item.context ?? '');
         const sourceKey = item.one + '\x00' + item.other;
-        const responseKey = `${sourceKey}||${item.context ?? ''}`;
+        const responseKey = `${sourceKey}||${item.context ?? ''}||${sourceLang}`;
         const lookupParams = {
             sourceText: sourceKey, sourceLang, targetLang,
             projectContextHash, stringContextHash,
         };
         // Tier 1: local cache
         const cachedForms = await store.lookupPlural(lookupParams);
-        if (Object.keys(cachedForms).length > 0) {
-            plurals[responseKey] = cachedForms;
-            continue;
-        }
+        if (Object.keys(cachedForms).length > 0)
+            return [responseKey, cachedForms];
         // Tier 2: shared store
         if (shared) {
             const sharedForms = await shared.lookupPlural(lookupParams);
             if (Object.keys(sharedForms).length > 0) {
-                // Propagate to local
                 for (const [cat, text] of Object.entries(sharedForms)) {
                     await store.insertPlural({
                         ...lookupParams, stringContext: item.context ?? '',
@@ -136,8 +166,7 @@ export async function handleTranslationRequest(body, configPath, opts) {
                         model: cfg.backendModel, status: 'translated',
                     });
                 }
-                plurals[responseKey] = sharedForms;
-                continue;
+                return [responseKey, sharedForms];
             }
         }
         // Backend call
@@ -162,12 +191,22 @@ export async function handleTranslationRequest(body, configPath, opts) {
                 };
                 await fireHooks([], event, opts.onTranslate);
             }
-            plurals[responseKey] = forms;
+            return [responseKey, forms];
         }
         catch {
-            plurals[responseKey] = { one: item.one, other: item.other };
+            return [responseKey, { one: item.one, other: item.other }];
         }
-    }
+    }));
+    const [stringResults, pluralResults] = await Promise.all([
+        Promise.all(stringWork),
+        Promise.all(pluralWork),
+    ]);
+    const translations = {};
+    for (const [key, value] of stringResults)
+        translations[key] = value;
+    const plurals = {};
+    for (const [key, value] of pluralResults)
+        plurals[key] = value;
     return { translations, plurals };
 }
 export function createTransDuckHandler(configPath, opts) {

package/dist/react/provider.d.ts

@@ -30,11 +30,16 @@ export interface UseTransDuckReturn {
 export declare function useTransDuck(): UseTransDuckReturn;
 export declare function _resetReactState(): void;
 export declare function _getReactState(): ReactState;
-export declare function t(sourceText: string, context?: string, vars?: Record<string, string | number>): TranslationResult;
-export declare function tPlural(one: string, other: string, count: number, opts?: {
+export interface TOptions {
     context?: string;
     vars?: Record<string, string | number>;
-}): TranslationResult;
+    /** Override the provider's source language for this call. */
+    sourceLang?: string;
+}
+export interface TPluralOptions extends TOptions {
+}
+export declare function t(sourceText: string, contextOrOpts?: string | TOptions, vars?: Record<string, string | number>): TranslationResult;
+export declare function tPlural(one: string, other: string, count: number, opts?: TPluralOptions): TranslationResult;
 export declare const ait: typeof t;
 export declare const aitPlural: typeof tPlural;
 interface TransDuckProviderProps {

package/dist/react/provider.js

@@ -77,24 +77,43 @@ function schedulePendingFlush() {
         _state.triggerFetch?.();
     });
 }
-// --- Stable exported functions ---
-export function t(sourceText, context, vars) {
-    const key = `${sourceText}||${context ?? ''}`;
+/**
+ * Build the client-side cache / pending-set key.
+ * Format: text || context || sourceLang (last two always present)
+ */
+function buildKey(text, context, sourceLang) {
+    return `${text}||${context ?? ''}||${sourceLang}`;
+}
+export function t(sourceText, contextOrOpts, vars) {
+    let context;
+    let resolvedVars;
+    let sourceLangOverride;
+    if (typeof contextOrOpts === 'string' || contextOrOpts === undefined) {
+        context = contextOrOpts;
+        resolvedVars = vars;
+    }
+    else {
+        context = contextOrOpts.context;
+        resolvedVars = contextOrOpts.vars;
+        sourceLangOverride = contextOrOpts.sourceLang;
+    }
+    const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
+    const key = buildKey(sourceText, context, effectiveSourceLang);
     _state.knownKeys.add(key);
     // Same language — return source
-    if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-        return new TranslationResult(interpolateVars(sourceText, vars), {
+    if (_state.language.toUpperCase() === effectiveSourceLang) {
+        return new TranslationResult(interpolateVars(sourceText, resolvedVars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
         });
     }
     // Cache hit
     const cached = _state.cache.get(key);
     if (cached !== undefined) {
-        return new TranslationResult(interpolateVars(cached, vars), {
+        return new TranslationResult(interpolateVars(cached, resolvedVars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
             source: 'cache',
         });
@@ -103,14 +122,16 @@ export function t(sourceText, context, vars) {
     _state.pendingStrings.add(key);
     schedulePendingFlush();
     // Return source text as fallback, marked pending
-    return new TranslationResult(interpolateVars(sourceText, vars), {
+    return new TranslationResult(interpolateVars(sourceText, resolvedVars), {
         pending: true,
-        sourceLang: _state.sourceLang,
+        sourceLang: effectiveSourceLang,
         lang: _state.language,
     });
 }
 export function tPlural(one, other, count, opts) {
     const context = opts?.context;
+    const sourceLangOverride = opts?.sourceLang;
+    const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
     let vars;
     if (!opts?.vars) {
         vars = { count };
@@ -122,15 +143,15 @@ export function tPlural(one, other, count, opts) {
         vars = { ...opts.vars };
     }
     const sourceKey = `${one}\x00${other}`;
-    const cacheKey = `${sourceKey}||${context ?? ''}`;
+    const cacheKey = buildKey(sourceKey, context, effectiveSourceLang);
     _state.knownPlurals.add(cacheKey);
     // Same language
-    if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-        const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+    if (_state.language.toUpperCase() === effectiveSourceLang) {
+        const rules = new Intl.PluralRules(effectiveSourceLang.toLowerCase());
         const form = rules.select(count) === 'one' ? one : other;
         return new TranslationResult(interpolateVars(form, vars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
         });
     }
@@ -142,7 +163,7 @@ export function tPlural(one, other, count, opts) {
         const form = cachedForms[category] ?? cachedForms['other'] ?? other;
         return new TranslationResult(interpolateVars(form, vars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
             source: 'cache',
         });
@@ -151,11 +172,11 @@ export function tPlural(one, other, count, opts) {
     _state.pendingPlurals.add(cacheKey);
     schedulePendingFlush();
     // Fallback to source form, marked pending
-    const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+    const rules = new Intl.PluralRules(effectiveSourceLang.toLowerCase());
     const form = rules.select(count) === 'one' ? one : other;
     return new TranslationResult(interpolateVars(form, vars), {
         pending: true,
-        sourceLang: _state.sourceLang,
+        sourceLang: effectiveSourceLang,
         lang: _state.language,
     });
 }
@@ -266,15 +287,23 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
             }
             return;
         }
-        // Build request body
+        // Build request body.
+        // Key format: text || context || sourceLang. Pop the tail segments so text
+        // can contain "||" safely.
         const strings = Array.from(stringsToFetch).map(key => {
-            const [text, context] = key.split('||');
-            return { text, context: context || undefined };
+            const parts = key.split('||');
+            const sourceLang = parts.pop();
+            const context = parts.pop();
+            const text = parts.join('||');
+            return { text, context: context || undefined, sourceLang };
         });
         const plurals = Array.from(pluralsToFetch).map(key => {
-            const [sourceKey, context] = key.split('||');
+            const parts = key.split('||');
+            const sourceLang = parts.pop();
+            const context = parts.pop();
+            const sourceKey = parts.join('||');
             const [one, other] = sourceKey.split('\x00');
-            return { one, other, context: context || undefined };
+            return { one, other, context: context || undefined, sourceLang };
         });
         try {
             const response = await fetch(endpoint, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transduck",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "AI-native translation tool using source text as keys",
   "type": "module",
   "main": "./dist/index.js",

package/src/cli.ts

@@ -743,7 +743,7 @@ export async function runStats(opts: StatsOptions): Promise<string> {
 // CLI entry point
 const program = new Command();
 
-program.name('transduck').description('AI-native translation tool').version('0.7.0');
+program.name('transduck').description('AI-native translation tool').version('0.9.0');
 
 program.command('init')
   .description('Initialize a new transduck project')

package/src/config.ts

@@ -17,6 +17,7 @@ export interface TransduckConfig {
   backendModel: string;
   backendTimeout: number;
   backendMaxRetries: number;
+  backendMaxConcurrency: number;
   sharedUrl: string | null;
   readOnly: boolean;
 }
@@ -61,6 +62,13 @@ export function loadConfig(path?: string): TransduckConfig {
   const backendTimeout = backend.timeout_seconds ?? 10;
   const backendMaxRetries = backend.max_retries ?? 2;
 
+  const backendMaxConcurrency = backend.max_concurrency ?? 10;
+  if (!Number.isInteger(backendMaxConcurrency) || backendMaxConcurrency < 1) {
+    throw new Error(
+      `backend.max_concurrency must be a positive integer (got ${backend.max_concurrency})`
+    );
+  }
+
   const sharedUrl = process.env.TRANSDUCK_SHARED_URL || raw.storage?.shared_url || null;
 
   let readOnly = raw.runtime?.read_only ?? false;
@@ -81,6 +89,7 @@ export function loadConfig(path?: string): TransduckConfig {
     backendModel,
     backendTimeout,
     backendMaxRetries,
+    backendMaxConcurrency,
     readOnly,
   };
 }