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

package/dist/handler.js

@@ -94,7 +94,7 @@ export async function handleTranslationRequest(body, configPath, opts) {
     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 ?? ''}`;
+        const key = `${item.text}||${item.context ?? ''}||${sourceLang}`;
         const lookupParams = {
             sourceText: item.text, sourceLang, targetLang,
             projectContextHash, stringContextHash,
@@ -146,7 +146,7 @@ export async function handleTranslationRequest(body, configPath, opts) {
         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 responseKey = `${sourceKey}||${item.context ?? ''}||${sourceLang}`;
         const lookupParams = {
             sourceText: sourceKey, sourceLang, targetLang,
             projectContextHash, stringContextHash,

package/dist/react/provider.d.ts

@@ -30,11 +30,16 @@ 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>): TranslationResult;
-export declare function tPlural(one: string, other: string, count: number, opts?: {
+export interface TOptions {
     context?: string;
     vars?: Record<string, string | number>;
-}): TranslationResult;
+    /** Override the provider's source language for this call. */
+    sourceLang?: string;
+}
+export interface TPluralOptions extends TOptions {
+}
+export declare function t(sourceText: string, contextOrOpts?: string | TOptions, vars?: Record<string, string | number>): TranslationResult;
+export declare function tPlural(one: string, other: string, count: number, opts?: TPluralOptions): TranslationResult;
 export declare const ait: typeof t;
 export declare const aitPlural: typeof tPlural;
 interface TransDuckProviderProps {

package/dist/react/provider.js

@@ -77,24 +77,43 @@ function schedulePendingFlush() {
         _state.triggerFetch?.();
     });
 }
-// --- Stable exported functions ---
-export function t(sourceText, context, vars) {
-    const key = `${sourceText}||${context ?? ''}`;
+/**
+ * Build the client-side cache / pending-set key.
+ * Format: text || context || sourceLang (last two always present)
+ */
+function buildKey(text, context, sourceLang) {
+    return `${text}||${context ?? ''}||${sourceLang}`;
+}
+export function t(sourceText, contextOrOpts, vars) {
+    let context;
+    let resolvedVars;
+    let sourceLangOverride;
+    if (typeof contextOrOpts === 'string' || contextOrOpts === undefined) {
+        context = contextOrOpts;
+        resolvedVars = vars;
+    }
+    else {
+        context = contextOrOpts.context;
+        resolvedVars = contextOrOpts.vars;
+        sourceLangOverride = contextOrOpts.sourceLang;
+    }
+    const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
+    const key = buildKey(sourceText, context, effectiveSourceLang);
     _state.knownKeys.add(key);
     // Same language — return source
-    if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-        return new TranslationResult(interpolateVars(sourceText, vars), {
+    if (_state.language.toUpperCase() === effectiveSourceLang) {
+        return new TranslationResult(interpolateVars(sourceText, resolvedVars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
         });
     }
     // Cache hit
     const cached = _state.cache.get(key);
     if (cached !== undefined) {
-        return new TranslationResult(interpolateVars(cached, vars), {
+        return new TranslationResult(interpolateVars(cached, resolvedVars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
             source: 'cache',
         });
@@ -103,14 +122,16 @@ export function t(sourceText, context, vars) {
     _state.pendingStrings.add(key);
     schedulePendingFlush();
     // Return source text as fallback, marked pending
-    return new TranslationResult(interpolateVars(sourceText, vars), {
+    return new TranslationResult(interpolateVars(sourceText, resolvedVars), {
         pending: true,
-        sourceLang: _state.sourceLang,
+        sourceLang: effectiveSourceLang,
         lang: _state.language,
     });
 }
 export function tPlural(one, other, count, opts) {
     const context = opts?.context;
+    const sourceLangOverride = opts?.sourceLang;
+    const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
     let vars;
     if (!opts?.vars) {
         vars = { count };
@@ -122,15 +143,15 @@ export function tPlural(one, other, count, opts) {
         vars = { ...opts.vars };
     }
     const sourceKey = `${one}\x00${other}`;
-    const cacheKey = `${sourceKey}||${context ?? ''}`;
+    const cacheKey = buildKey(sourceKey, context, effectiveSourceLang);
     _state.knownPlurals.add(cacheKey);
     // Same language
-    if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-        const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+    if (_state.language.toUpperCase() === effectiveSourceLang) {
+        const rules = new Intl.PluralRules(effectiveSourceLang.toLowerCase());
         const form = rules.select(count) === 'one' ? one : other;
         return new TranslationResult(interpolateVars(form, vars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
         });
     }
@@ -142,7 +163,7 @@ export function tPlural(one, other, count, opts) {
         const form = cachedForms[category] ?? cachedForms['other'] ?? other;
         return new TranslationResult(interpolateVars(form, vars), {
             pending: false,
-            sourceLang: _state.sourceLang,
+            sourceLang: effectiveSourceLang,
             lang: _state.language,
             source: 'cache',
         });
@@ -151,11 +172,11 @@ export function tPlural(one, other, count, opts) {
     _state.pendingPlurals.add(cacheKey);
     schedulePendingFlush();
     // Fallback to source form, marked pending
-    const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+    const rules = new Intl.PluralRules(effectiveSourceLang.toLowerCase());
     const form = rules.select(count) === 'one' ? one : other;
     return new TranslationResult(interpolateVars(form, vars), {
         pending: true,
-        sourceLang: _state.sourceLang,
+        sourceLang: effectiveSourceLang,
         lang: _state.language,
     });
 }
@@ -266,15 +287,23 @@ export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/ap
             }
             return;
         }
-        // Build request body
+        // Build request body.
+        // Key format: text || context || sourceLang. Pop the tail segments so text
+        // can contain "||" safely.
         const strings = Array.from(stringsToFetch).map(key => {
-            const [text, context] = key.split('||');
-            return { text, context: context || undefined };
+            const parts = key.split('||');
+            const sourceLang = parts.pop();
+            const context = parts.pop();
+            const text = parts.join('||');
+            return { text, context: context || undefined, sourceLang };
         });
         const plurals = Array.from(pluralsToFetch).map(key => {
-            const [sourceKey, context] = key.split('||');
+            const parts = key.split('||');
+            const sourceLang = parts.pop();
+            const context = parts.pop();
+            const sourceKey = parts.join('||');
             const [one, other] = sourceKey.split('\x00');
-            return { one, other, context: context || undefined };
+            return { one, other, context: context || undefined, sourceLang };
         });
         try {
             const response = await fetch(endpoint, {

package/package.json

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

package/src/handler.ts

@@ -132,7 +132,7 @@ export async function handleTranslationRequest(
     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 key = `${item.text}||${item.context ?? ''}||${sourceLang}`;
       const lookupParams = {
         sourceText: item.text, sourceLang, targetLang,
         projectContextHash, stringContextHash,
@@ -191,7 +191,7 @@ export async function handleTranslationRequest(
       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 responseKey = `${sourceKey}||${item.context ?? ''}||${sourceLang}`;
       const lookupParams = {
         sourceText: sourceKey, sourceLang, targetLang,
         projectContextHash, stringContextHash,

package/src/react/provider.tsx

@@ -130,19 +130,50 @@ function schedulePendingFlush() {
 
 // --- Stable exported functions ---
 
+export interface TOptions {
+  context?: string;
+  vars?: Record<string, string | number>;
+  /** Override the provider's source language for this call. */
+  sourceLang?: string;
+}
+
+export interface TPluralOptions extends TOptions {}
+
+/**
+ * Build the client-side cache / pending-set key.
+ * Format: text || context || sourceLang (last two always present)
+ */
+function buildKey(text: string, context: string | undefined, sourceLang: string): string {
+  return `${text}||${context ?? ''}||${sourceLang}`;
+}
+
 export function t(
   sourceText: string,
-  context?: string,
+  contextOrOpts?: string | TOptions,
   vars?: Record<string, string | number>,
 ): TranslationResult {
-  const key = `${sourceText}||${context ?? ''}`;
+  let context: string | undefined;
+  let resolvedVars: Record<string, string | number> | undefined;
+  let sourceLangOverride: string | undefined;
+
+  if (typeof contextOrOpts === 'string' || contextOrOpts === undefined) {
+    context = contextOrOpts;
+    resolvedVars = vars;
+  } else {
+    context = contextOrOpts.context;
+    resolvedVars = contextOrOpts.vars;
+    sourceLangOverride = contextOrOpts.sourceLang;
+  }
+
+  const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
+  const key = buildKey(sourceText, context, effectiveSourceLang);
   _state.knownKeys.add(key);
 
   // Same language — return source
-  if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-    return new TranslationResult(interpolateVars(sourceText, vars), {
+  if (_state.language.toUpperCase() === effectiveSourceLang) {
+    return new TranslationResult(interpolateVars(sourceText, resolvedVars), {
       pending: false,
-      sourceLang: _state.sourceLang,
+      sourceLang: effectiveSourceLang,
       lang: _state.language,
     });
   }
@@ -150,9 +181,9 @@ export function t(
   // Cache hit
   const cached = _state.cache.get(key);
   if (cached !== undefined) {
-    return new TranslationResult(interpolateVars(cached, vars), {
+    return new TranslationResult(interpolateVars(cached, resolvedVars), {
       pending: false,
-      sourceLang: _state.sourceLang,
+      sourceLang: effectiveSourceLang,
       lang: _state.language,
       source: 'cache',
     });
@@ -163,9 +194,9 @@ export function t(
   schedulePendingFlush();
 
   // Return source text as fallback, marked pending
-  return new TranslationResult(interpolateVars(sourceText, vars), {
+  return new TranslationResult(interpolateVars(sourceText, resolvedVars), {
     pending: true,
-    sourceLang: _state.sourceLang,
+    sourceLang: effectiveSourceLang,
     lang: _state.language,
   });
 }
@@ -174,9 +205,12 @@ export function tPlural(
   one: string,
   other: string,
   count: number,
-  opts?: { context?: string; vars?: Record<string, string | number> },
+  opts?: TPluralOptions,
 ): TranslationResult {
   const context = opts?.context;
+  const sourceLangOverride = opts?.sourceLang;
+  const effectiveSourceLang = (sourceLangOverride ?? _state.sourceLang).toUpperCase();
+
   let vars: Record<string, string | number>;
   if (!opts?.vars) {
     vars = { count };
@@ -187,16 +221,16 @@ export function tPlural(
   }
 
   const sourceKey = `${one}\x00${other}`;
-  const cacheKey = `${sourceKey}||${context ?? ''}`;
+  const cacheKey = buildKey(sourceKey, context, effectiveSourceLang);
   _state.knownPlurals.add(cacheKey);
 
   // Same language
-  if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
-    const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+  if (_state.language.toUpperCase() === effectiveSourceLang) {
+    const rules = new Intl.PluralRules(effectiveSourceLang.toLowerCase());
     const form = rules.select(count) === 'one' ? one : other;
     return new TranslationResult(interpolateVars(form, vars), {
       pending: false,
-      sourceLang: _state.sourceLang,
+      sourceLang: effectiveSourceLang,
       lang: _state.language,
     });
   }
@@ -209,7 +243,7 @@ export function tPlural(
     const form = cachedForms[category] ?? cachedForms['other'] ?? other;
     return new TranslationResult(interpolateVars(form, vars), {
       pending: false,
-      sourceLang: _state.sourceLang,
+      sourceLang: effectiveSourceLang,
       lang: _state.language,
       source: 'cache',
     });
@@ -220,11 +254,11 @@ export function tPlural(
   schedulePendingFlush();
 
   // Fallback to source form, marked pending
-  const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+  const rules = new Intl.PluralRules(effectiveSourceLang.toLowerCase());
   const form = rules.select(count) === 'one' ? one : other;
   return new TranslationResult(interpolateVars(form, vars), {
     pending: true,
-    sourceLang: _state.sourceLang,
+    sourceLang: effectiveSourceLang,
     lang: _state.language,
   });
 }
@@ -365,15 +399,23 @@ export function TransDuckProvider({
       return;
     }
 
-    // Build request body
+    // Build request body.
+    // Key format: text || context || sourceLang. Pop the tail segments so text
+    // can contain "||" safely.
     const strings = Array.from(stringsToFetch).map(key => {
-      const [text, context] = key.split('||');
-      return { text, context: context || undefined };
+      const parts = key.split('||');
+      const sourceLang = parts.pop()!;
+      const context = parts.pop();
+      const text = parts.join('||');
+      return { text, context: context || undefined, sourceLang };
     });
     const plurals = Array.from(pluralsToFetch).map(key => {
-      const [sourceKey, context] = key.split('||');
+      const parts = key.split('||');
+      const sourceLang = parts.pop()!;
+      const context = parts.pop();
+      const sourceKey = parts.join('||');
       const [one, other] = sourceKey.split('\x00');
-      return { one, other, context: context || undefined };
+      return { one, other, context: context || undefined, sourceLang };
     });
 
     try {

package/tests/handler.test.ts

@@ -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,7 +181,7 @@ describe('handleTranslationRequest', () => {
       plurals: [],
     }, configPath);
 
-    expect(result.translations['Hola||']).toBe('Hallo');
+    expect(result.translations['Hola||||ES']).toBe('Hallo');
   });
 });
 
@@ -281,7 +281,7 @@ backend:
     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}`);
+      expect(result.translations[`s${i}||||EN`]).toBe(`translated-s${i}`);
     }
     vi.restoreAllMocks();
   });
@@ -341,9 +341,9 @@ backend:
       configPath,
     );
 
-    expect(result.translations['ok1||']).toBe('t-ok1');
-    expect(result.translations['ok2||']).toBe('t-ok2');
-    expect(result.translations['boom||']).toBe('boom'); // fallback to source
+    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/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() {