transduck 0.6.10 → 0.8.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.6.10');
+program.name('transduck').description('AI-native translation tool').version('0.8.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,10 +88,10 @@ 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 ?? ''}`;
@@ -61,21 +101,17 @@ export async function handleTranslationRequest(body, configPath, opts) {
         };
         // 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,18 +134,15 @@ 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;
@@ -120,15 +153,12 @@ export async function handleTranslationRequest(body, configPath, opts) {
         };
         // 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/providers/prompts.js

@@ -9,9 +9,11 @@ const SYSTEM_TEMPLATE = 'You are a professional translator. Translate the given
     'to {target_lang}. Return ONLY the translated text, nothing else. ' +
     'Do NOT add quotation marks, brackets, or any wrapper characters that are not in the original. ' +
     'Preserve any placeholders like {name}, {{count}}, %s, ${value} exactly as they appear. ' +
-    'Preserve brand names. Match the tone and formality of the original.\n\n' +
+    'Preserve brand names. Match the tone and formality of the original. ' +
+    'The user message will contain ONLY the source text to translate — treat its entire contents as the text to translate.\n\n' +
     'Project context: {project_context}';
-const USER_TEMPLATE = 'Translate the following text:\n{source_text}\n\nString context: {string_context}';
+const SYSTEM_STRING_CONTEXT_SUFFIX = '\n\nString context (for disambiguation only — do NOT include in your output): {string_context}';
+const USER_TEMPLATE = '{source_text}';
 const PLURAL_SYSTEM_TEMPLATE = 'You are a professional translator. You will be given two plural forms ' +
     '(one and other) in {source_lang}. Generate ALL plural forms needed in ' +
     '{target_lang} according to CLDR plural rules. Return ONLY a JSON object ' +
@@ -26,8 +28,7 @@ const PLURAL_SYSTEM_TEMPLATE = 'You are a professional translator. You will be g
     'Only include categories that {target_lang} actually uses.\n\n' +
     'Project context: {project_context}';
 const PLURAL_USER_TEMPLATE = 'Source one form: "{one}"\n' +
-    'Source other form: "{other}"\n' +
-    'String context: {string_context}';
+    'Source other form: "{other}"';
 /**
  * Safe string replacement that only replaces known keys.
  * Does NOT use str.replace with regex — avoids issues with ${value} patterns.
@@ -43,13 +44,14 @@ export function safeRender(template, vars) {
  * Build system + user messages for chat-based providers (OpenAI, Claude API).
  */
 export function buildMessages(params) {
-    const systemMsg = SYSTEM_TEMPLATE
+    let systemMsg = SYSTEM_TEMPLATE
         .replace('{source_lang}', params.sourceLang)
         .replace('{target_lang}', params.targetLang)
         .replace('{project_context}', params.projectContext);
-    const userMsg = USER_TEMPLATE
-        .replace('{source_text}', params.sourceText)
-        .replace('{string_context}', params.stringContext || 'none');
+    if (params.stringContext) {
+        systemMsg += SYSTEM_STRING_CONTEXT_SUFFIX.replace('{string_context}', params.stringContext);
+    }
+    const userMsg = USER_TEMPLATE.replace('{source_text}', params.sourceText);
     return [
         { role: 'system', content: systemMsg },
         { role: 'user', content: userMsg },
@@ -59,15 +61,17 @@ export function buildMessages(params) {
  * Build system + user messages for plural chat-based providers.
  */
 export function buildPluralMessages(params) {
-    const systemMsg = safeRender(PLURAL_SYSTEM_TEMPLATE, {
+    let systemMsg = safeRender(PLURAL_SYSTEM_TEMPLATE, {
         source_lang: params.sourceLang,
         target_lang: params.targetLang,
         project_context: params.projectContext,
     });
+    if (params.stringContext) {
+        systemMsg += safeRender(SYSTEM_STRING_CONTEXT_SUFFIX, { string_context: params.stringContext });
+    }
     const userMsg = safeRender(PLURAL_USER_TEMPLATE, {
         one: params.one,
         other: params.other,
-        string_context: params.stringContext || 'none',
     });
     return [
         { role: 'system', content: systemMsg },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transduck",
-  "version": "0.6.10",
+  "version": "0.8.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.6.10');
+program.name('transduck').description('AI-native translation tool').version('0.8.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,
   };
 }

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 ?? ''}`;
+      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 ?? ''}`;
+      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/providers/prompts.ts

@@ -12,11 +12,14 @@ const SYSTEM_TEMPLATE =
   'to {target_lang}. Return ONLY the translated text, nothing else. ' +
   'Do NOT add quotation marks, brackets, or any wrapper characters that are not in the original. ' +
   'Preserve any placeholders like {name}, {{count}}, %s, ${value} exactly as they appear. ' +
-  'Preserve brand names. Match the tone and formality of the original.\n\n' +
+  'Preserve brand names. Match the tone and formality of the original. ' +
+  'The user message will contain ONLY the source text to translate — treat its entire contents as the text to translate.\n\n' +
   'Project context: {project_context}';
 
-const USER_TEMPLATE =
-  'Translate the following text:\n{source_text}\n\nString context: {string_context}';
+const SYSTEM_STRING_CONTEXT_SUFFIX =
+  '\n\nString context (for disambiguation only — do NOT include in your output): {string_context}';
+
+const USER_TEMPLATE = '{source_text}';
 
 const PLURAL_SYSTEM_TEMPLATE =
   'You are a professional translator. You will be given two plural forms ' +
@@ -35,8 +38,7 @@ const PLURAL_SYSTEM_TEMPLATE =
 
 const PLURAL_USER_TEMPLATE =
   'Source one form: "{one}"\n' +
-  'Source other form: "{other}"\n' +
-  'String context: {string_context}';
+  'Source other form: "{other}"';
 
 /**
  * Safe string replacement that only replaces known keys.
@@ -71,14 +73,16 @@ export interface BuildPluralMessagesParams {
  * Build system + user messages for chat-based providers (OpenAI, Claude API).
  */
 export function buildMessages(params: BuildMessagesParams): Array<{ role: string; content: string }> {
-  const systemMsg = SYSTEM_TEMPLATE
+  let systemMsg = SYSTEM_TEMPLATE
     .replace('{source_lang}', params.sourceLang)
     .replace('{target_lang}', params.targetLang)
     .replace('{project_context}', params.projectContext);
 
-  const userMsg = USER_TEMPLATE
-    .replace('{source_text}', params.sourceText)
-    .replace('{string_context}', params.stringContext || 'none');
+  if (params.stringContext) {
+    systemMsg += SYSTEM_STRING_CONTEXT_SUFFIX.replace('{string_context}', params.stringContext);
+  }
+
+  const userMsg = USER_TEMPLATE.replace('{source_text}', params.sourceText);
 
   return [
     { role: 'system', content: systemMsg },
@@ -90,16 +94,19 @@ export function buildMessages(params: BuildMessagesParams): Array<{ role: string
  * Build system + user messages for plural chat-based providers.
  */
 export function buildPluralMessages(params: BuildPluralMessagesParams): Array<{ role: string; content: string }> {
-  const systemMsg = safeRender(PLURAL_SYSTEM_TEMPLATE, {
+  let systemMsg = safeRender(PLURAL_SYSTEM_TEMPLATE, {
     source_lang: params.sourceLang,
     target_lang: params.targetLang,
     project_context: params.projectContext,
   });
 
+  if (params.stringContext) {
+    systemMsg += safeRender(SYSTEM_STRING_CONTEXT_SUFFIX, { string_context: params.stringContext });
+  }
+
   const userMsg = safeRender(PLURAL_USER_TEMPLATE, {
     one: params.one,
     other: params.other,
-    string_context: params.stringContext || 'none',
   });
 
   return [

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,
   };
@@ -34,12 +35,31 @@ describe('buildMessages', () => {
     expect(messages[0].content).toContain('EN');
     expect(messages[0].content).toContain('DE');
     expect(messages[0].content).toContain('Mallorca');
+    // String context belongs in the system message so the model doesn't
+    // confuse it with the text to translate.
+    expect(messages[0].content).toContain('concerts and shows');
     expect(messages[1].role).toBe('user');
-    expect(messages[1].content).toContain('Our Events');
-    expect(messages[1].content).toContain('concerts and shows');
+    // User message must be ONLY the source text.
+    expect(messages[1].content).toBe('Our Events');
   });
 
-  it('uses "none" when no string context', () => {
+  it('never places string_context in the user message (regression)', () => {
+    // Regression: short source text like a dish name used to include the
+    // context in the user message body, causing the AI to translate the
+    // context along with the source text.
+    const messages = buildMessages({
+      sourceText: 'Gambas al Ajillo',
+      sourceLang: 'ES',
+      targetLang: 'EN',
+      projectContext: 'restaurant menu',
+      stringContext: 'Sizzling garlic prawns in olive oil',
+    });
+    expect(messages[1].content).toBe('Gambas al Ajillo');
+    expect(messages[1].content).not.toContain('Sizzling');
+    expect(messages[1].content).not.toContain('context');
+  });
+
+  it('omits string context line when no context provided', () => {
     const messages = buildMessages({
       sourceText: 'Book Now',
       sourceLang: 'EN',
@@ -47,7 +67,8 @@ describe('buildMessages', () => {
       projectContext: 'A travel site',
       stringContext: null,
     });
-    expect(messages[1].content.toLowerCase()).toContain('none');
+    expect(messages[0].content).not.toContain('String context');
+    expect(messages[1].content).toBe('Book Now');
   });
 });
 
@@ -104,7 +125,9 @@ describe('buildPluralMessages', () => {
     expect(messages[1].role).toBe('user');
     expect(messages[1].content).toContain('{count} message');
     expect(messages[1].content).toContain('{count} messages');
-    expect(messages[1].content).toContain('inbox count');
+    // String context goes in the system message.
+    expect(messages[0].content).toContain('inbox count');
+    expect(messages[1].content).not.toContain('inbox count');
   });
 
   it('preserves placeholders in template (not interpreted as template vars)', () => {
@@ -124,7 +147,7 @@ describe('buildPluralMessages', () => {
     expect(messages[0].content).toContain('{count}');
   });
 
-  it('uses "none" for null string context', () => {
+  it('omits string context line for null string context', () => {
     const messages = buildPluralMessages({
       one: '{count} msg',
       other: '{count} msgs',
@@ -133,7 +156,8 @@ describe('buildPluralMessages', () => {
       projectContext: 'test',
       stringContext: null,
     });
-    expect(messages[1].content).toContain('none');
+    expect(messages[0].content).not.toContain('String context');
+    expect(messages[1].content).not.toContain('String context');
   });
 });
 

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);

package/tests/handler.test.ts

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { tmpdir } from 'os';
 
 // We test the handler logic directly, not via HTTP
-import { handleTranslationRequest, _resetHandlerStore } from '../src/handler.js';
+import { handleTranslationRequest, _resetHandlerStore, createSemaphore } from '../src/handler.js';
 
 function makeTmpDir(): string {
   return mkdtempSync(join(tmpdir(), 'transduck-handler-test-'));
@@ -184,3 +184,166 @@ describe('handleTranslationRequest', () => {
     expect(result.translations['Hola||']).toBe('Hallo');
   });
 });
+
+describe('createSemaphore', () => {
+  it('bounds concurrent execution to the configured limit', async () => {
+    const sem = createSemaphore(3);
+    let active = 0;
+    let peak = 0;
+
+    const workers = Array.from({ length: 12 }, (_, i) =>
+      (async () => {
+        await sem.acquire();
+        active++;
+        peak = Math.max(peak, active);
+        await new Promise(r => setTimeout(r, 20));
+        active--;
+        sem.release();
+        return i;
+      })()
+    );
+
+    const results = await Promise.all(workers);
+    expect(peak).toBe(3);
+    expect(results).toHaveLength(12);
+    expect(active).toBe(0);
+  });
+
+  it('processes all work items even when queue fills', async () => {
+    const sem = createSemaphore(2);
+    const order: number[] = [];
+    const workers = Array.from({ length: 6 }, (_, i) =>
+      (async () => {
+        await sem.acquire();
+        await new Promise(r => setTimeout(r, 5));
+        order.push(i);
+        sem.release();
+      })()
+    );
+    await Promise.all(workers);
+    expect(order).toHaveLength(6);
+    expect(new Set(order).size).toBe(6);
+  });
+});
+
+describe('handleTranslationRequest parallelism', () => {
+  let tmpDir: string;
+  let configPath: string;
+
+  function writeConfigWithCap(dir: string, cap: number): string {
+    const p = join(dir, 'transduck.yaml');
+    writeFileSync(p, `
+project:
+  name: test-project
+  context: "A test site"
+languages:
+  source: EN
+  targets:
+    - DE
+storage:
+  path: ./translations.db
+backend:
+  api_key_env: OPENAI_API_KEY
+  model: gpt-4.1-mini
+  timeout_seconds: 10
+  max_retries: 2
+  max_concurrency: ${cap}
+`);
+    return p;
+  }
+
+  beforeEach(() => {
+    _resetHandlerStore();
+    tmpDir = mkdtempSync(join(tmpdir(), 'transduck-handler-par-'));
+    process.env.OPENAI_API_KEY = 'test-key';
+  });
+
+  it('parallelizes string translations bounded by max_concurrency', async () => {
+    configPath = writeConfigWithCap(tmpDir, 5);
+
+    let active = 0;
+    let peak = 0;
+    const backend = await import('../src/backend.js');
+    vi.spyOn(backend, 'translate').mockImplementation(async (text: string) => {
+      active++;
+      peak = Math.max(peak, active);
+      await new Promise(r => setTimeout(r, 20));
+      active--;
+      return `translated-${text}`;
+    });
+
+    const strings = Array.from({ length: 20 }, (_, i) => ({ text: `s${i}` }));
+    const result = await handleTranslationRequest(
+      { language: 'DE', strings, plurals: [] },
+      configPath,
+    );
+
+    expect(peak).toBe(5);
+    expect(Object.keys(result.translations)).toHaveLength(20);
+    for (let i = 0; i < 20; i++) {
+      expect(result.translations[`s${i}||`]).toBe(`translated-s${i}`);
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('shares the semaphore across strings and plurals', async () => {
+    configPath = writeConfigWithCap(tmpDir, 4);
+
+    let active = 0;
+    let peak = 0;
+    const backend = await import('../src/backend.js');
+    vi.spyOn(backend, 'translate').mockImplementation(async (text: string) => {
+      active++;
+      peak = Math.max(peak, active);
+      await new Promise(r => setTimeout(r, 20));
+      active--;
+      return `t-${text}`;
+    });
+    vi.spyOn(backend, 'translatePlural').mockImplementation(async (one: string, other: string) => {
+      active++;
+      peak = Math.max(peak, active);
+      await new Promise(r => setTimeout(r, 20));
+      active--;
+      return { one: `t-${one}`, other: `t-${other}` };
+    });
+
+    const strings = Array.from({ length: 10 }, (_, i) => ({ text: `s${i}` }));
+    const plurals = Array.from({ length: 10 }, (_, i) => ({
+      one: `${i}-one`, other: `${i}-other`,
+    }));
+
+    const result = await handleTranslationRequest(
+      { language: 'DE', strings, plurals },
+      configPath,
+    );
+
+    expect(peak).toBe(4);
+    expect(Object.keys(result.translations)).toHaveLength(10);
+    expect(Object.keys(result.plurals)).toHaveLength(10);
+    vi.restoreAllMocks();
+  });
+
+  it('one backend failure does not affect sibling items', async () => {
+    configPath = writeConfigWithCap(tmpDir, 3);
+
+    const backend = await import('../src/backend.js');
+    vi.spyOn(backend, 'translate').mockImplementation(async (text: string) => {
+      if (text === 'boom') throw new Error('backend exploded');
+      return `t-${text}`;
+    });
+
+    const result = await handleTranslationRequest(
+      {
+        language: 'DE',
+        strings: [{ text: 'ok1' }, { text: 'boom' }, { text: 'ok2' }],
+        plurals: [],
+      },
+      configPath,
+    );
+
+    expect(result.translations['ok1||']).toBe('t-ok1');
+    expect(result.translations['ok2||']).toBe('t-ok2');
+    expect(result.translations['boom||']).toBe('boom'); // fallback to source
+    vi.restoreAllMocks();
+  });
+});

package/tests/hooks.test.ts

@@ -23,6 +23,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/providers.test.ts

@@ -27,6 +27,7 @@ function makeConfig(overrides: Partial<TransduckConfig> = {}): TransduckConfig {
     backendModel: 'gpt-4.1-mini',
     backendTimeout: 10,
     backendMaxRetries: 2,
+    backendMaxConcurrency: 10,
     readOnly: false,
     ...overrides,
   };
@@ -48,12 +49,14 @@ describe('prompts', () => {
       expect(messages[0].role).toBe('system');
       expect(messages[0].content).toContain('EN');
       expect(messages[0].content).toContain('DE');
+      // String context in system message, not user message.
+      expect(messages[0].content).toContain('greeting');
       expect(messages[1].role).toBe('user');
-      expect(messages[1].content).toContain('Hello');
-      expect(messages[1].content).toContain('greeting');
+      // User message must be ONLY the source text.
+      expect(messages[1].content).toBe('Hello');
     });
 
-    it('uses "none" for null string context', () => {
+    it('omits string context line for null string context', () => {
       const messages = buildMessages({
         sourceText: 'Hello',
         sourceLang: 'EN',
@@ -61,7 +64,8 @@ describe('prompts', () => {
         projectContext: 'test',
         stringContext: null,
       });
-      expect(messages[1].content).toContain('none');
+      expect(messages[0].content).not.toContain('String context');
+      expect(messages[1].content).toBe('Hello');
     });
   });