transduck 0.7.0 → 0.9.0

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-'));
@@ -63,7 +63,7 @@ describe('handleTranslationRequest', () => {
       plurals: [],
     }, configPath);
 
-    expect(result.translations['Hello||']).toBe('Hallo');
+    expect(result.translations['Hello||||EN']).toBe('Hallo');
   });
 
   it('returns empty translations for uncached strings without API key', async () => {
@@ -75,7 +75,7 @@ describe('handleTranslationRequest', () => {
     }, configPath);
 
     // Without API key, backend will fail, should return source text
-    expect(result.translations['Unknown||']).toBe('Unknown');
+    expect(result.translations['Unknown||||EN']).toBe('Unknown');
   });
 
   it('handles context in cache key', async () => {
@@ -98,7 +98,7 @@ describe('handleTranslationRequest', () => {
       plurals: [],
     }, configPath);
 
-    expect(result.translations['Book||Hotel booking']).toBe('Buchen');
+    expect(result.translations['Book||Hotel booking||EN']).toBe('Buchen');
   });
 
   it('returns plural forms from cache', async () => {
@@ -129,7 +129,7 @@ describe('handleTranslationRequest', () => {
       plurals: [{ one: '{count} item', other: '{count} items' }],
     }, configPath);
 
-    const pluralKey = '{count} item\x00{count} items||';
+    const pluralKey = '{count} item\x00{count} items||||EN';
     expect(result.plurals[pluralKey]).toBeDefined();
     expect(result.plurals[pluralKey].one).toBe('{count} Artikel');
   });
@@ -157,7 +157,7 @@ describe('handleTranslationRequest', () => {
       plurals: [],
     }, configPath);
 
-    expect(result.translations['Bonjour||']).toBe('Hallo');
+    expect(result.translations['Bonjour||||FR']).toBe('Hallo');
   });
 
   it('per-item sourceLang overrides body-level sourceLang', async () => {
@@ -181,6 +181,169 @@ describe('handleTranslationRequest', () => {
       plurals: [],
     }, configPath);
 
-    expect(result.translations['Hola||']).toBe('Hallo');
+    expect(result.translations['Hola||||ES']).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}||||EN`]).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||||EN']).toBe('t-ok1');
+    expect(result.translations['ok2||||EN']).toBe('t-ok2');
+    expect(result.translations['boom||||EN']).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,
   };

package/tests/react-provider.test.tsx

@@ -33,7 +33,7 @@ describe('TransDuckProvider + t()', () => {
   it('t() returns source text before translation loads', () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     function TestComp() {
@@ -94,7 +94,7 @@ describe('TransDuckProvider + t()', () => {
     mockFetch.mockResolvedValue({
       ok: true,
       json: async () => ({
-        translations: { 'Hello||': 'Hallo', 'World||': 'Welt' },
+        translations: { 'Hello||||EN': 'Hallo', 'World||||EN': 'Welt' },
         plurals: {},
       }),
     });
@@ -129,7 +129,7 @@ describe('TransDuckProvider + t()', () => {
     mockFetch.mockResolvedValue({
       ok: true,
       json: async () => ({
-        translations: { 'Hello||': 'Hallo' },
+        translations: { 'Hello||||EN': 'Hallo' },
         plurals: {},
       }),
     });
@@ -165,7 +165,7 @@ describe('TransDuckProvider + t()', () => {
   it('t() tracks called keys in _state.knownKeys', async () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     function TestComp() {
@@ -180,7 +180,7 @@ describe('TransDuckProvider + t()', () => {
     );
 
     const state = _getReactState();
-    expect(state.knownKeys.has('Hello||')).toBe(true);
+    expect(state.knownKeys.has('Hello||||EN')).toBe(true);
   });
 
   it('useTransDuck() returns t, tPlural, ait, aitPlural, language, setLanguage, isLoading', () => {
@@ -211,12 +211,12 @@ describe('TransDuckProvider + t()', () => {
     // First render in DE
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
     // After switch to ES
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hola' }, plurals: {} }),
     });
 
     let hookRef: UseTransDuckReturn | null = null;
@@ -254,7 +254,7 @@ describe('TransDuckProvider + t()', () => {
   it('setLanguage() with current language is a no-op', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     let hookRef: UseTransDuckReturn | null = null;
@@ -288,7 +288,7 @@ describe('TransDuckProvider + t()', () => {
   it('setLanguage() to source language skips fetch', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     let hookRef: UseTransDuckReturn | null = null;
@@ -324,7 +324,7 @@ describe('TransDuckProvider + t()', () => {
   it('isLoading is true during language switch fetch', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     let resolveSecondFetch: ((value: unknown) => void) | null = null;
@@ -359,7 +359,7 @@ describe('TransDuckProvider + t()', () => {
     await act(async () => {
       resolveSecondFetch!({
         ok: true,
-        json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+        json: async () => ({ translations: { 'Hello||||EN': 'Hola' }, plurals: {} }),
       });
     });
 
@@ -372,7 +372,7 @@ describe('TransDuckProvider + t()', () => {
   it('isLoading clears on fetch error during language switch', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
     mockFetch.mockRejectedValueOnce(new Error('Network error'));
 
@@ -406,7 +406,7 @@ describe('TransDuckProvider + t()', () => {
   it('discards stale fetch response when language changes during fetch', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     let resolveFRFetch: ((value: unknown) => void) | null = null;
@@ -416,7 +416,7 @@ describe('TransDuckProvider + t()', () => {
 
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hola' }, plurals: {} }),
     });
 
     let hookRef: UseTransDuckReturn | null = null;
@@ -452,7 +452,7 @@ describe('TransDuckProvider + t()', () => {
     await act(async () => {
       resolveFRFetch!({
         ok: true,
-        json: async () => ({ translations: { 'Hello||': 'Bonjour' }, plurals: {} }),
+        json: async () => ({ translations: { 'Hello||||EN': 'Bonjour' }, plurals: {} }),
       });
     });
 
@@ -463,11 +463,11 @@ describe('TransDuckProvider + t()', () => {
   it('changing language prop triggers switchLanguage with isLoading', async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
     mockFetch.mockResolvedValueOnce({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hola' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hola' }, plurals: {} }),
     });
 
     let hookRef: UseTransDuckReturn | null = null;
@@ -503,7 +503,7 @@ describe('TransDuckProvider + t()', () => {
   it('t() returns a TranslationResult with pending=true on cache miss', () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     let captured: ReturnType<typeof t> | null = null;
@@ -529,7 +529,7 @@ describe('TransDuckProvider + t()', () => {
   it('t() returns a TranslationResult with pending=false on cache hit', async () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     let captured: ReturnType<typeof t> | null = null;
@@ -599,7 +599,7 @@ describe('TransDuckProvider + t()', () => {
   });
 
   it('tPlural() returns a TranslationResult with pending=false on cache hit', async () => {
-    const pluralKey = '{count} message\x00{count} messages||';
+    const pluralKey = '{count} message\x00{count} messages||||EN';
     mockFetch.mockResolvedValue({
       ok: true,
       json: async () => ({
@@ -633,7 +633,7 @@ describe('TransDuckProvider + t()', () => {
   it('fetch body includes sourceLang from provider prop', async () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     function TestComp() {
@@ -656,10 +656,192 @@ describe('TransDuckProvider + t()', () => {
     expect(body.language).toBe('DE');
   });
 
+  it('t() with per-call sourceLang option uses it instead of provider sourceLang', async () => {
+    // POS case: menu items in ES, allergens in EN, user target DE.
+    // Both t() calls run in the same <TransDuckProvider sourceLang="ES">.
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        translations: {
+          'Gambas||||ES': 'Garnelen',
+          'Contains nuts||||EN': 'Enthält Nüsse',
+        },
+        plurals: {},
+      }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return (
+        <div>
+          <span data-testid="dish">{t('Gambas')}</span>
+          <span data-testid="allergen">{t('Contains nuts', { sourceLang: 'EN' })}</span>
+        </div>
+      );
+    }
+
+    render(
+      <TransDuckProvider language="DE" sourceLang="ES">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('dish').textContent).toBe('Garnelen');
+      expect(screen.getByTestId('allergen').textContent).toBe('Enthält Nüsse');
+    });
+
+    // Fetch body contains per-item sourceLang for the allergen.
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    const dish = body.strings.find((s: any) => s.text === 'Gambas');
+    const allergen = body.strings.find((s: any) => s.text === 'Contains nuts');
+    expect(dish.sourceLang).toBe('ES');
+    expect(allergen.sourceLang).toBe('EN');
+  });
+
+  it('t() same text under different sourceLang does not collide in cache', async () => {
+    // Two menu entries with identical source text but different source langs
+    // must resolve to distinct cache entries and independent translations.
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        translations: {
+          'Salat||||DE': 'Salad',       // German menu item → English
+          'Salat||||NL': 'Lettuce',     // Dutch menu item → English
+        },
+        plurals: {},
+      }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return (
+        <div>
+          <span data-testid="de">{t('Salat', { sourceLang: 'DE' })}</span>
+          <span data-testid="nl">{t('Salat', { sourceLang: 'NL' })}</span>
+        </div>
+      );
+    }
+
+    render(
+      <TransDuckProvider language="EN" sourceLang="EN">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('de').textContent).toBe('Salad');
+      expect(screen.getByTestId('nl').textContent).toBe('Lettuce');
+    });
+  });
+
+  it('t() same-language short-circuit respects per-call sourceLang', () => {
+    // Provider is ES→DE, but this call marks its text as EN source.
+    // Target language is DE, so this translation IS needed even though
+    // provider.sourceLang === 'ES'. No same-language short-circuit.
+    let captured: ReturnType<typeof t> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = t('Contains nuts', { sourceLang: 'EN' });
+      return <span>{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE" sourceLang="ES">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    expect(captured!.pending).toBe(true);
+    expect(captured!.sourceLang).toBe('EN');
+  });
+
+  it('t() short-circuits when per-call sourceLang equals target language', () => {
+    // Provider ES→EN. Allergen is EN source, target is EN: no translation.
+    let captured: ReturnType<typeof t> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = t('Contains nuts', { sourceLang: 'EN' });
+      return <span>{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="EN" sourceLang="ES">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    expect(captured!.pending).toBe(false);
+    expect(captured!.toString()).toBe('Contains nuts');
+  });
+
+  it('t() options form supports context and vars', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        translations: { 'Book||hotel booking||EN': 'Buchen {name}' },
+        plurals: {},
+      }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return (
+        <span data-testid="t">
+          {t('Book', { context: 'hotel booking', vars: { name: 'Tim' }, sourceLang: 'EN' })}
+        </span>
+      );
+    }
+
+    render(
+      <TransDuckProvider language="DE" sourceLang="EN">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('t').textContent).toBe('Buchen Tim');
+    });
+  });
+
+  it('tPlural() accepts per-call sourceLang', async () => {
+    const pluralKey = '{count} item\x00{count} items||||EN';
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        translations: {},
+        plurals: { [pluralKey]: { one: '{count} Artikel', other: '{count} Artikel' } },
+      }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return (
+        <span data-testid="p">
+          {tPlural('{count} item', '{count} items', 5, { sourceLang: 'EN' })}
+        </span>
+      );
+    }
+
+    // Provider source is ES, but this plural is EN source.
+    render(
+      <TransDuckProvider language="DE" sourceLang="ES">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('p').textContent).toBe('5 Artikel');
+    });
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.plurals[0].sourceLang).toBe('EN');
+  });
+
   it('useTransDuck() still works without destructuring (backward compat)', async () => {
     mockFetch.mockResolvedValue({
       ok: true,
-      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+      json: async () => ({ translations: { 'Hello||||EN': 'Hallo' }, plurals: {} }),
     });
 
     function TestComp() {