transduck 0.6.8 → 0.6.10

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.8');
+program.name('transduck').description('AI-native translation tool').version('0.6.10');
 program.command('init')
     .description('Initialize a new transduck project')
     .action(async () => {

package/dist/handler.d.ts

@@ -12,6 +12,7 @@ interface TranslationRequestPlural {
 }
 export interface TranslationRequest {
     language: string;
+    sourceLang?: string;
     strings: TranslationRequestString[];
     plurals: TranslationRequestPlural[];
 }

package/dist/handler.js

@@ -46,12 +46,13 @@ export async function handleTranslationRequest(body, configPath, opts) {
     const store = await getStore(configPath);
     const shared = await getSharedStore(configPath);
     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 ?? []) {
-        const sourceLang = item.sourceLang?.toUpperCase() ?? cfg.sourceLang;
+        const sourceLang = item.sourceLang?.toUpperCase() ?? bodySourceLang ?? cfg.sourceLang;
         const stringContextHash = hash(item.context ?? '');
         const key = `${item.text}||${item.context ?? ''}`;
         const lookupParams = {
@@ -109,7 +110,7 @@ export async function handleTranslationRequest(body, configPath, opts) {
     }
     // Translate plurals
     for (const item of body.plurals ?? []) {
-        const sourceLang = item.sourceLang?.toUpperCase() ?? cfg.sourceLang;
+        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 ?? ''}`;

package/dist/react/provider.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from 'react';
+import { TranslationResult } from '../result.js';
 interface ReactState {
     language: string;
     sourceLang: string;
@@ -29,11 +30,11 @@ 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>): string;
+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?: {
     context?: string;
     vars?: Record<string, string | number>;
-}): string;
+}): TranslationResult;
 export declare const ait: typeof t;
 export declare const aitPlural: typeof tPlural;
 interface TransDuckProviderProps {

package/dist/react/provider.js

@@ -1,6 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import React, { createContext, useContext, useEffect, useState, useCallback } from 'react';
+import { TranslationResult } from '../result.js';
 let _state = {
     language: '',
     sourceLang: 'EN',
@@ -82,18 +83,31 @@ export function t(sourceText, context, vars) {
     _state.knownKeys.add(key);
     // Same language — return source
     if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-        return interpolateVars(sourceText, vars);
+        return new TranslationResult(interpolateVars(sourceText, vars), {
+            pending: false,
+            sourceLang: _state.sourceLang,
+            lang: _state.language,
+        });
     }
     // Cache hit
     const cached = _state.cache.get(key);
     if (cached !== undefined) {
-        return interpolateVars(cached, vars);
+        return new TranslationResult(interpolateVars(cached, vars), {
+            pending: false,
+            sourceLang: _state.sourceLang,
+            lang: _state.language,
+            source: 'cache',
+        });
     }
     // Queue for fetch
     _state.pendingStrings.add(key);
     schedulePendingFlush();
-    // Return source text as fallback
-    return interpolateVars(sourceText, vars);
+    // Return source text as fallback, marked pending
+    return new TranslationResult(interpolateVars(sourceText, vars), {
+        pending: true,
+        sourceLang: _state.sourceLang,
+        lang: _state.language,
+    });
 }
 export function tPlural(one, other, count, opts) {
     const context = opts?.context;
@@ -114,7 +128,11 @@ export function tPlural(one, other, count, opts) {
     if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
         const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
         const form = rules.select(count) === 'one' ? one : other;
-        return interpolateVars(form, vars);
+        return new TranslationResult(interpolateVars(form, vars), {
+            pending: false,
+            sourceLang: _state.sourceLang,
+            lang: _state.language,
+        });
     }
     // Cache hit
     const cachedForms = _state.pluralCache.get(cacheKey);
@@ -122,15 +140,24 @@ export function tPlural(one, other, count, opts) {
         const rules = new Intl.PluralRules(_state.language.toLowerCase());
         const category = rules.select(count);
         const form = cachedForms[category] ?? cachedForms['other'] ?? other;
-        return interpolateVars(form, vars);
+        return new TranslationResult(interpolateVars(form, vars), {
+            pending: false,
+            sourceLang: _state.sourceLang,
+            lang: _state.language,
+            source: 'cache',
+        });
     }
     // Queue for fetch
     _state.pendingPlurals.add(cacheKey);
     schedulePendingFlush();
-    // Fallback to source form
+    // Fallback to source form, marked pending
     const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
     const form = rules.select(count) === 'one' ? one : other;
-    return interpolateVars(form, vars);
+    return new TranslationResult(interpolateVars(form, vars), {
+        pending: true,
+        sourceLang: _state.sourceLang,
+        lang: _state.language,
+    });
 }
 // Aliases
 export const ait = t;
@@ -255,6 +282,7 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify({
                     language: _state.language,
+                    sourceLang: _state.sourceLang,
                     strings,
                     plurals,
                 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transduck",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "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.8');
+program.name('transduck').description('AI-native translation tool').version('0.6.10');
 
 program.command('init')
   .description('Initialize a new transduck project')

package/src/handler.ts

@@ -25,6 +25,7 @@ interface TranslationRequestPlural {
 
 export interface TranslationRequest {
   language: string;
+  sourceLang?: string;
   strings: TranslationRequestString[];
   plurals: TranslationRequestPlural[];
 }
@@ -77,6 +78,7 @@ export async function handleTranslationRequest(
   const store = await getStore(configPath);
   const shared = await getSharedStore(configPath);
   const targetLang = body.language.toUpperCase();
+  const bodySourceLang = body.sourceLang?.toUpperCase();
 
   const projectContextHash = hash(cfg.projectContext);
 
@@ -85,7 +87,7 @@ export async function handleTranslationRequest(
 
   // Translate regular strings
   for (const item of body.strings ?? []) {
-    const sourceLang = item.sourceLang?.toUpperCase() ?? cfg.sourceLang;
+    const sourceLang = item.sourceLang?.toUpperCase() ?? bodySourceLang ?? cfg.sourceLang;
     const stringContextHash = hash(item.context ?? '');
     const key = `${item.text}||${item.context ?? ''}`;
     const lookupParams = {
@@ -148,7 +150,7 @@ export async function handleTranslationRequest(
 
   // Translate plurals
   for (const item of body.plurals ?? []) {
-    const sourceLang = item.sourceLang?.toUpperCase() ?? cfg.sourceLang;
+    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 ?? ''}`;

package/src/react/provider.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import React, { createContext, useContext, useEffect, useState, useCallback, type ReactNode } from 'react';
+import { TranslationResult } from '../result.js';
 
 // --- Module-level state (accessed by stable t()/ait() functions) ---
 
@@ -133,27 +134,40 @@ export function t(
   sourceText: string,
   context?: string,
   vars?: Record<string, string | number>,
-): string {
+): TranslationResult {
   const key = `${sourceText}||${context ?? ''}`;
   _state.knownKeys.add(key);
 
   // Same language — return source
   if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-    return interpolateVars(sourceText, vars);
+    return new TranslationResult(interpolateVars(sourceText, vars), {
+      pending: false,
+      sourceLang: _state.sourceLang,
+      lang: _state.language,
+    });
   }
 
   // Cache hit
   const cached = _state.cache.get(key);
   if (cached !== undefined) {
-    return interpolateVars(cached, vars);
+    return new TranslationResult(interpolateVars(cached, vars), {
+      pending: false,
+      sourceLang: _state.sourceLang,
+      lang: _state.language,
+      source: 'cache',
+    });
   }
 
   // Queue for fetch
   _state.pendingStrings.add(key);
   schedulePendingFlush();
 
-  // Return source text as fallback
-  return interpolateVars(sourceText, vars);
+  // Return source text as fallback, marked pending
+  return new TranslationResult(interpolateVars(sourceText, vars), {
+    pending: true,
+    sourceLang: _state.sourceLang,
+    lang: _state.language,
+  });
 }
 
 export function tPlural(
@@ -161,7 +175,7 @@ export function tPlural(
   other: string,
   count: number,
   opts?: { context?: string; vars?: Record<string, string | number> },
-): string {
+): TranslationResult {
   const context = opts?.context;
   let vars: Record<string, string | number>;
   if (!opts?.vars) {
@@ -180,7 +194,11 @@ export function tPlural(
   if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
     const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
     const form = rules.select(count) === 'one' ? one : other;
-    return interpolateVars(form, vars);
+    return new TranslationResult(interpolateVars(form, vars), {
+      pending: false,
+      sourceLang: _state.sourceLang,
+      lang: _state.language,
+    });
   }
 
   // Cache hit
@@ -189,17 +207,26 @@ export function tPlural(
     const rules = new Intl.PluralRules(_state.language.toLowerCase());
     const category = rules.select(count);
     const form = cachedForms[category] ?? cachedForms['other'] ?? other;
-    return interpolateVars(form, vars);
+    return new TranslationResult(interpolateVars(form, vars), {
+      pending: false,
+      sourceLang: _state.sourceLang,
+      lang: _state.language,
+      source: 'cache',
+    });
   }
 
   // Queue for fetch
   _state.pendingPlurals.add(cacheKey);
   schedulePendingFlush();
 
-  // Fallback to source form
+  // Fallback to source form, marked pending
   const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
   const form = rules.select(count) === 'one' ? one : other;
-  return interpolateVars(form, vars);
+  return new TranslationResult(interpolateVars(form, vars), {
+    pending: true,
+    sourceLang: _state.sourceLang,
+    lang: _state.language,
+  });
 }
 
 // Aliases
@@ -355,6 +382,7 @@ export function TransDuckProvider({
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           language: _state.language,
+          sourceLang: _state.sourceLang,
           strings,
           plurals,
         }),

package/tests/handler.test.ts

@@ -133,4 +133,54 @@ describe('handleTranslationRequest', () => {
     expect(result.plurals[pluralKey]).toBeDefined();
     expect(result.plurals[pluralKey].one).toBe('{count} Artikel');
   });
+
+  it('body-level sourceLang overrides config sourceLang', async () => {
+    const { TranslationStore } = await import('../src/storage.js');
+    const { createHash } = await import('crypto');
+    const hash = (t: string) => createHash('sha256').update(t).digest('hex');
+
+    // Cache entry stored under source FR (not config's EN)
+    const store = new TranslationStore(join(tmpDir, 'translations.db'));
+    await store.initialize();
+    await store.insert({
+      sourceText: 'Bonjour', sourceLang: 'FR', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      translatedText: 'Hallo', model: 'gpt-4.1-mini', status: 'translated', stringContext: '',
+    });
+    store.close();
+
+    // With body-level sourceLang: FR, the handler should find the cache entry
+    const result = await handleTranslationRequest({
+      language: 'DE',
+      sourceLang: 'FR',
+      strings: [{ text: 'Bonjour' }],
+      plurals: [],
+    }, configPath);
+
+    expect(result.translations['Bonjour||']).toBe('Hallo');
+  });
+
+  it('per-item sourceLang overrides body-level sourceLang', async () => {
+    const { TranslationStore } = await import('../src/storage.js');
+    const { createHash } = await import('crypto');
+    const hash = (t: string) => createHash('sha256').update(t).digest('hex');
+
+    const store = new TranslationStore(join(tmpDir, 'translations.db'));
+    await store.initialize();
+    await store.insert({
+      sourceText: 'Hola', sourceLang: 'ES', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      translatedText: 'Hallo', model: 'gpt-4.1-mini', status: 'translated', stringContext: '',
+    });
+    store.close();
+
+    const result = await handleTranslationRequest({
+      language: 'DE',
+      sourceLang: 'FR',
+      strings: [{ text: 'Hola', sourceLang: 'ES' }],
+      plurals: [],
+    }, configPath);
+
+    expect(result.translations['Hola||']).toBe('Hallo');
+  });
 });

package/tests/react-provider.test.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { render, screen, cleanup, waitFor, act } from '@testing-library/react';
 import { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState, _getReactState } from '../src/react/index.js';
 import type { UseTransDuckReturn } from '../src/react/index.js';
+import { TranslationResult } from '../src/result.js';
 
 // Mock fetch globally
 const mockFetch = vi.fn();
@@ -499,6 +500,162 @@ describe('TransDuckProvider + t()', () => {
     });
   });
 
+  it('t() returns a TranslationResult with pending=true on cache miss', () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    let captured: ReturnType<typeof t> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = t('Hello');
+      return <span>{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    expect(captured).toBeInstanceOf(TranslationResult);
+    expect(captured!.pending).toBe(true);
+    expect(captured!.sourceLang).toBe('EN');
+    expect(captured!.lang).toBe('DE');
+    expect(captured!.toString()).toBe('Hello');
+  });
+
+  it('t() returns a TranslationResult with pending=false on cache hit', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    let captured: ReturnType<typeof t> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = t('Hello');
+      return <span data-testid="text">{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('Hallo');
+    });
+
+    expect(captured).toBeInstanceOf(TranslationResult);
+    expect(captured!.pending).toBe(false);
+    expect(captured!.source).toBe('cache');
+    expect(captured!.toString()).toBe('Hallo');
+  });
+
+  it('t() returns a TranslationResult with pending=false when language matches source', () => {
+    let captured: ReturnType<typeof t> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = t('Hello');
+      return <span>{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="EN" sourceLang="EN">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    expect(captured).toBeInstanceOf(TranslationResult);
+    expect(captured!.pending).toBe(false);
+    expect(captured!.toString()).toBe('Hello');
+  });
+
+  it('tPlural() returns a TranslationResult with pending=true on cache miss', () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ translations: {}, plurals: {} }),
+    });
+
+    let captured: ReturnType<typeof tPlural> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = tPlural('{count} message', '{count} messages', 2);
+      return <span>{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    expect(captured).toBeInstanceOf(TranslationResult);
+    expect(captured!.pending).toBe(true);
+    expect(captured!.toString()).toBe('2 messages');
+  });
+
+  it('tPlural() returns a TranslationResult with pending=false on cache hit', async () => {
+    const pluralKey = '{count} message\x00{count} messages||';
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        translations: {},
+        plurals: { [pluralKey]: { one: '{count} Nachricht', other: '{count} Nachrichten' } },
+      }),
+    });
+
+    let captured: ReturnType<typeof tPlural> | null = null;
+    function TestComp() {
+      useTransDuck();
+      captured = tPlural('{count} message', '{count} messages', 3);
+      return <span data-testid="text">{captured}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('text').textContent).toBe('3 Nachrichten');
+    });
+
+    expect(captured).toBeInstanceOf(TranslationResult);
+    expect(captured!.pending).toBe(false);
+    expect(captured!.source).toBe('cache');
+  });
+
+  it('fetch body includes sourceLang from provider prop', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => ({ translations: { 'Hello||': 'Hallo' }, plurals: {} }),
+    });
+
+    function TestComp() {
+      useTransDuck();
+      return <span data-testid="text">{t('Hello')}</span>;
+    }
+
+    render(
+      <TransDuckProvider language="DE" sourceLang="FR">
+        <TestComp />
+      </TransDuckProvider>
+    );
+
+    await waitFor(() => {
+      expect(mockFetch).toHaveBeenCalled();
+    });
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.sourceLang).toBe('FR');
+    expect(body.language).toBe('DE');
+  });
+
   it('useTransDuck() still works without destructuring (backward compat)', async () => {
     mockFetch.mockResolvedValue({
       ok: true,