transduck 0.6.9 → 0.7.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.9');
+program.name('transduck').description('AI-native translation tool').version('0.7.0');
 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/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/dist/react/provider.js

@@ -282,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.9",
+  "version": "0.7.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.9');
+program.name('transduck').description('AI-native translation tool').version('0.7.0');
 
 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/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/src/react/provider.tsx

@@ -382,6 +382,7 @@ export function TransDuckProvider({
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
           language: _state.language,
+          sourceLang: _state.sourceLang,
           strings,
           plurals,
         }),

package/tests/backend.test.ts

@@ -34,12 +34,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 +66,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 +124,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 +146,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 +155,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/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/providers.test.ts

@@ -48,12 +48,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 +63,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');
     });
   });
 

package/tests/react-provider.test.tsx

@@ -630,6 +630,32 @@ describe('TransDuckProvider + t()', () => {
     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,