transduck 0.7.0 → 0.9.0

package/src/handler.ts

@@ -10,6 +10,48 @@ function hash(text: string): string {
   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: number) {
+  let active = 0;
+  const queue: Array<() => void> = [];
+  return {
+    acquire(): Promise<void> {
+      return new Promise(resolve => {
+        if (active < limit) {
+          active++;
+          resolve();
+        } else {
+          queue.push(() => {
+            active++;
+            resolve();
+          });
+        }
+      });
+    },
+    release(): void {
+      active--;
+      const next = queue.shift();
+      if (next) next();
+    },
+  };
+}
+
+async function withSlot<T>(
+  sem: ReturnType<typeof createSemaphore>,
+  fn: () => Promise<T>,
+): Promise<T> {
+  await sem.acquire();
+  try {
+    return await fn();
+  } finally {
+    sem.release();
+  }
+}
+
 interface TranslationRequestString {
   text: string;
   context?: string;
@@ -82,137 +124,140 @@ export async function handleTranslationRequest(
 
   const projectContextHash = hash(cfg.projectContext);
 
-  const translations: Record<string, string> = {};
-  const plurals: Record<string, Record<string, string>> = {};
+  // Single semaphore shared across strings and plurals so total outbound
+  // concurrency to the backend is bounded across both categories.
+  const sem = createSemaphore(cfg.backendMaxConcurrency);
 
-  // Translate regular strings
-  for (const item of body.strings ?? []) {
-    const sourceLang = item.sourceLang?.toUpperCase() ?? bodySourceLang ?? cfg.sourceLang;
-    const stringContextHash = hash(item.context ?? '');
-    const key = `${item.text}||${item.context ?? ''}`;
-    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;
-    }
+  const stringWork = (body.strings ?? []).map(item =>
+    withSlot(sem, async (): Promise<[string, string]> => {
+      const sourceLang = item.sourceLang?.toUpperCase() ?? bodySourceLang ?? cfg.sourceLang;
+      const stringContextHash = hash(item.context ?? '');
+      const key = `${item.text}||${item.context ?? ''}||${sourceLang}`;
+      const lookupParams = {
+        sourceText: item.text, sourceLang, targetLang,
+        projectContextHash, stringContextHash,
+      };
 
-    // 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;
+      // Tier 1: local cache
+      const cached = await store.lookup(lookupParams);
+      if (cached !== null) return [key, cached];
+
+      // Tier 2: shared store
+      if (shared) {
+        const sharedCached = await shared.lookup(lookupParams);
+        if (sharedCached !== null) {
+          await store.insert({
+            ...lookupParams, stringContext: item.context ?? '',
+            translatedText: sharedCached, model: cfg.backendModel, status: 'translated',
+          });
+          return [key, sharedCached];
+        }
       }
-    }
 
-    // Backend call
-    try {
-      const translated = await backendTranslate(
-        item.text, sourceLang, targetLang,
-        cfg.projectContext, item.context ?? null, cfg,
-      );
-
-      if (validateTranslation(item.text, translated)) {
-        const insertParams = {
-          ...lookupParams, stringContext: item.context ?? '',
-          translatedText: translated, model: cfg.backendModel, status: 'translated',
-        };
-        await store.insert(insertParams);
-        if (shared) await shared.insert(insertParams);
-        if (opts?.onTranslate) {
-          const event: TranslationEvent = {
-            sourceText: item.text, translatedText: translated,
-            sourceLang, lang: targetLang, context: item.context ?? null,
-            projectContext: cfg.projectContext, source: 'translated',
-            plural: false,
+      // Backend call
+      try {
+        const translated = await backendTranslate(
+          item.text, sourceLang, targetLang,
+          cfg.projectContext, item.context ?? null, cfg,
+        );
+
+        if (validateTranslation(item.text, translated)) {
+          const insertParams = {
+            ...lookupParams, stringContext: item.context ?? '',
+            translatedText: translated, model: cfg.backendModel, status: 'translated',
           };
-          await fireHooks([], event, opts.onTranslate);
+          await store.insert(insertParams);
+          if (shared) await shared.insert(insertParams);
+          if (opts?.onTranslate) {
+            const event: TranslationEvent = {
+              sourceText: item.text, translatedText: translated,
+              sourceLang, lang: targetLang, context: item.context ?? null,
+              projectContext: cfg.projectContext, source: 'translated',
+              plural: false,
+            };
+            await fireHooks([], event, opts.onTranslate);
+          }
+          return [key, translated];
         }
-        translations[key] = translated;
-      } else {
-        translations[key] = item.text;
+        return [key, item.text];
+      } catch {
+        return [key, item.text];
       }
-    } catch {
-      translations[key] = item.text;
-    }
-  }
+    })
+  );
 
-  // Translate plurals
-  for (const item of body.plurals ?? []) {
-    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 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;
-    }
+  const pluralWork = (body.plurals ?? []).map(item =>
+    withSlot(sem, async (): Promise<[string, Record<string, string>]> => {
+      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 ?? ''}||${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) return [responseKey, cachedForms];
+
+      // Tier 2: shared store
+      if (shared) {
+        const sharedForms = await shared.lookupPlural(lookupParams);
+        if (Object.keys(sharedForms).length > 0) {
+          for (const [cat, text] of Object.entries(sharedForms)) {
+            await store.insertPlural({
+              ...lookupParams, stringContext: item.context ?? '',
+              pluralCategory: cat, translatedText: text,
+              model: cfg.backendModel, status: 'translated',
+            });
+          }
+          return [responseKey, sharedForms];
+        }
+      }
+
+      // Backend call
+      try {
+        const forms = await backendTranslatePlural(
+          item.one, item.other, sourceLang, targetLang,
+          cfg.projectContext, item.context ?? null, cfg,
+        );
 
-    // 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({
+        for (const [cat, translatedText] of Object.entries(forms)) {
+          const insertParams = {
             ...lookupParams, stringContext: item.context ?? '',
-            pluralCategory: cat, translatedText: text,
+            pluralCategory: cat, translatedText: translatedText as string,
             model: cfg.backendModel, status: 'translated',
-          });
+          };
+          await store.insertPlural(insertParams);
+          if (shared) await shared.insertPlural(insertParams);
         }
-        plurals[responseKey] = sharedForms;
-        continue;
+        if (opts?.onTranslate && 'other' in forms) {
+          const event: TranslationEvent = {
+            sourceText: sourceKey, translatedText: forms.other ?? '',
+            sourceLang, lang: targetLang, context: item.context ?? null,
+            projectContext: cfg.projectContext, source: 'translated',
+            plural: true, pluralForms: forms,
+          };
+          await fireHooks([], event, opts.onTranslate);
+        }
+        return [responseKey, forms];
+      } catch {
+        return [responseKey, { one: item.one, other: item.other }];
       }
-    }
+    })
+  );
 
-    // Backend call
-    try {
-      const forms = await backendTranslatePlural(
-        item.one, item.other, sourceLang, targetLang,
-        cfg.projectContext, item.context ?? null, cfg,
-      );
-
-      for (const [cat, translatedText] of Object.entries(forms)) {
-        const insertParams = {
-          ...lookupParams, stringContext: item.context ?? '',
-          pluralCategory: cat, translatedText: translatedText as string,
-          model: cfg.backendModel, status: 'translated',
-        };
-        await store.insertPlural(insertParams);
-        if (shared) await shared.insertPlural(insertParams);
-      }
-      if (opts?.onTranslate && 'other' in forms) {
-        const event: TranslationEvent = {
-          sourceText: sourceKey, translatedText: forms.other ?? '',
-          sourceLang, lang: targetLang, context: item.context ?? null,
-          projectContext: cfg.projectContext, source: 'translated',
-          plural: true, pluralForms: forms,
-        };
-        await fireHooks([], event, opts.onTranslate);
-      }
-      plurals[responseKey] = forms;
-    } catch {
-      plurals[responseKey] = { one: item.one, other: item.other };
-    }
-  }
+  const [stringResults, pluralResults] = await Promise.all([
+    Promise.all(stringWork),
+    Promise.all(pluralWork),
+  ]);
+
+  const translations: Record<string, string> = {};
+  for (const [key, value] of stringResults) translations[key] = value;
+
+  const plurals: Record<string, Record<string, string>> = {};
+  for (const [key, value] of pluralResults) plurals[key] = value;
 
   return { translations, plurals };
 }

package/src/react/provider.tsx

@@ -130,19 +130,50 @@ function schedulePendingFlush() {
 
 // --- Stable exported functions ---
 
+export interface TOptions {
+  context?: string;
+  vars?: Record<string, string | number>;
+  /** Override the provider's source language for this call. */
+  sourceLang?: string;
+}
+
+export interface TPluralOptions extends TOptions {}
+
+/**
+ * Build the client-side cache / pending-set key.
+ * Format: text || context || sourceLang (last two always present)
+ */
+function buildKey(text: string, context: string | undefined, sourceLang: string): string {
+  return `${text}||${context ?? ''}||${sourceLang}`;
+}
+
 export function t(
   sourceText: string,
-  context?: string,
+  contextOrOpts?: string | TOptions,
   vars?: Record<string, string | number>,
 ): TranslationResult {
-  const key = `${sourceText}||${context ?? ''}`;
+  let context: string | undefined;
+  let resolvedVars: Record<string, string | number> | undefined;
+  let sourceLangOverride: string | undefined;
+
+  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,
     });
   }
@@ -150,9 +181,9 @@ export function t(
   // 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',
     });
@@ -163,9 +194,9 @@ export function t(
   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,
   });
 }
@@ -174,9 +205,12 @@ export function tPlural(
   one: string,
   other: string,
   count: number,
-  opts?: { context?: string; vars?: Record<string, string | number> },
+  opts?: TPluralOptions,
 ): TranslationResult {
   const context = opts?.context;
+  const sourceLangOverride = opts?.sourceLang;
+  const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
+
   let vars: Record<string, string | number>;
   if (!opts?.vars) {
     vars = { count };
@@ -187,16 +221,16 @@ export function tPlural(
   }
 
   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,
     });
   }
@@ -209,7 +243,7 @@ export function tPlural(
     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',
     });
@@ -220,11 +254,11 @@ export function tPlural(
   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,
   });
 }
@@ -365,15 +399,23 @@ export function TransDuckProvider({
       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 {

package/tests/ait.test.ts

@@ -22,6 +22,7 @@ function makeConfig(tmpDir: string, overrides?: Partial<TransduckConfig>): Trans
     backendModel: 'gpt-4.1-mini',
     backendTimeout: 10,
     backendMaxRetries: 2,
+    backendMaxConcurrency: 10,
     sharedUrl: null,
     readOnly: false,
     ...overrides,

package/tests/backend.test.ts

@@ -15,6 +15,7 @@ function makeConfig(): TransduckConfig {
     backendModel: 'gpt-4.1-mini',
     backendTimeout: 10,
     backendMaxRetries: 2,
+    backendMaxConcurrency: 10,
     sharedUrl: null,
     readOnly: false,
   };

package/tests/config.test.ts

@@ -72,6 +72,32 @@ describe('loadConfig', () => {
     delete process.env.TRANSDUCK_CONFIG;
   });
 
+  it('defaults backendMaxConcurrency to 10 when absent', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML);
+    const cfg = loadConfig(configPath);
+    expect(cfg.backendMaxConcurrency).toBe(10);
+  });
+
+  it('reads backendMaxConcurrency from backend.max_concurrency', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML + '  max_concurrency: 25\n');
+    const cfg = loadConfig(configPath);
+    expect(cfg.backendMaxConcurrency).toBe(25);
+  });
+
+  it('rejects zero or negative backend.max_concurrency', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML + '  max_concurrency: 0\n');
+    expect(() => loadConfig(configPath)).toThrow(/max_concurrency/);
+  });
+
+  it('rejects non-integer backend.max_concurrency', () => {
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, VALID_YAML + '  max_concurrency: 2.5\n');
+    expect(() => loadConfig(configPath)).toThrow(/max_concurrency/);
+  });
+
   it('defaults shared_url to null', () => {
     const configPath = join(tmpDir, 'transduck.yaml');
     writeFileSync(configPath, VALID_YAML);