transduck 0.6.7 → 0.6.9

package/dist/cli.js

@@ -376,6 +376,19 @@ export async function runScan(opts) {
             const store = new TranslationStore(cfg.storagePath);
             await store.initialize();
             const projectContextHash = hash(cfg.projectContext);
+            // Initialize shared Postgres store if configured
+            let shared = null;
+            if (cfg.sharedUrl) {
+                try {
+                    shared = new SharedStore(cfg.sharedUrl);
+                    await shared.initialize();
+                    console.log('  Connected to shared Postgres store');
+                }
+                catch (err) {
+                    console.warn(`  Warning: could not connect to shared store: ${err.message}`);
+                    shared = null;
+                }
+            }
             let translated = 0;
             let skipped = 0;
             let failed = 0;
@@ -386,26 +399,68 @@ export async function runScan(opts) {
                     const sourceKey = entry.one + '\x00' + entry.other;
                     const stringContextHash = hash(entry.context ?? '');
                     const label = (entry.one ?? '').slice(0, 40);
+                    const lookupParams = {
+                        sourceText: sourceKey, sourceLang: cfg.sourceLang,
+                        projectContextHash, stringContextHash,
+                    };
                     for (const lang of targetLangs) {
                         done++;
-                        const cachedForms = await store.lookupPlural({
-                            sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
-                            projectContextHash, stringContextHash,
-                        });
+                        const langLookup = { ...lookupParams, targetLang: lang };
+                        const cachedForms = await store.lookupPlural(langLookup);
                         if (Object.keys(cachedForms).length > 0) {
+                            // Ensure shared store has it too
+                            if (shared) {
+                                try {
+                                    const sharedForms = await shared.lookupPlural(langLookup);
+                                    if (Object.keys(sharedForms).length === 0) {
+                                        for (const [cat, text] of Object.entries(cachedForms)) {
+                                            await shared.insertPlural({
+                                                ...langLookup, stringContext: entry.context ?? '',
+                                                pluralCategory: cat, translatedText: text,
+                                                model: cfg.backendModel, status: 'translated',
+                                            });
+                                        }
+                                    }
+                                }
+                                catch { /* ignore shared store errors */ }
+                            }
                             skipped++;
                             console.log(`  [${done}/${total}] ${lang} skipped (cached): ${label}`);
                             continue;
                         }
+                        // Check shared store before calling backend
+                        if (shared) {
+                            try {
+                                const sharedForms = await shared.lookupPlural(langLookup);
+                                if (Object.keys(sharedForms).length > 0) {
+                                    for (const [cat, text] of Object.entries(sharedForms)) {
+                                        await store.insertPlural({
+                                            ...langLookup, stringContext: entry.context ?? '',
+                                            pluralCategory: cat, translatedText: text,
+                                            model: cfg.backendModel, status: 'translated',
+                                        });
+                                    }
+                                    skipped++;
+                                    console.log(`  [${done}/${total}] ${lang} skipped (shared cache): ${label}`);
+                                    continue;
+                                }
+                            }
+                            catch { /* ignore */ }
+                        }
                         try {
                             const forms = await backendTranslatePlural(entry.one, entry.other, cfg.sourceLang, lang, cfg.projectContext, entry.context ?? null, cfg);
                             for (const [cat, translatedText] of Object.entries(forms)) {
-                                await store.insertPlural({
-                                    sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
-                                    projectContextHash, stringContextHash, stringContext: entry.context ?? '',
+                                const insertParams = {
+                                    ...langLookup, stringContext: entry.context ?? '',
                                     pluralCategory: cat, translatedText: translatedText,
                                     model: cfg.backendModel, status: 'translated',
-                                });
+                                };
+                                await store.insertPlural(insertParams);
+                                if (shared)
+                                    try {
+                                        await shared.insertPlural(insertParams);
+                                    }
+                                    catch { /* ignore */ }
                             }
                             translated++;
                             console.log(`  [${done}/${total}] ${lang} translated: ${label}`);
@@ -419,25 +474,61 @@ export async function runScan(opts) {
                 else {
                     const stringContextHash = hash(entry.context ?? '');
                     const label = (entry.text ?? '').slice(0, 40);
+                    const lookupParams = {
+                        sourceText: entry.text, sourceLang: cfg.sourceLang,
+                        projectContextHash, stringContextHash,
+                    };
                     for (const lang of targetLangs) {
                         done++;
-                        const cached = await store.lookup({
-                            sourceText: entry.text, sourceLang: cfg.sourceLang, targetLang: lang,
-                            projectContextHash, stringContextHash,
-                        });
+                        const langLookup = { ...lookupParams, targetLang: lang };
+                        const cached = await store.lookup(langLookup);
                         if (cached !== null) {
+                            // Ensure shared store has it too
+                            if (shared) {
+                                try {
+                                    const sharedCached = await shared.lookup(langLookup);
+                                    if (sharedCached === null) {
+                                        await shared.insert({
+                                            ...langLookup, stringContext: entry.context ?? '',
+                                            translatedText: cached, model: cfg.backendModel, status: 'translated',
+                                        });
+                                    }
+                                }
+                                catch { /* ignore */ }
+                            }
                             skipped++;
                             console.log(`  [${done}/${total}] ${lang} skipped (cached): ${label}`);
                             continue;
                         }
+                        // Check shared store before calling backend
+                        if (shared) {
+                            try {
+                                const sharedCached = await shared.lookup(langLookup);
+                                if (sharedCached !== null) {
+                                    await store.insert({
+                                        ...langLookup, stringContext: entry.context ?? '',
+                                        translatedText: sharedCached, model: cfg.backendModel, status: 'translated',
+                                    });
+                                    skipped++;
+                                    console.log(`  [${done}/${total}] ${lang} skipped (shared cache): ${label}`);
+                                    continue;
+                                }
+                            }
+                            catch { /* ignore */ }
+                        }
                         try {
                             const result = await backendTranslate(entry.text, cfg.sourceLang, lang, cfg.projectContext, entry.context ?? null, cfg);
                             if (validateTranslation(entry.text, result)) {
-                                await store.insert({
-                                    sourceText: entry.text, sourceLang: cfg.sourceLang, targetLang: lang,
-                                    projectContextHash, stringContextHash, stringContext: entry.context ?? '',
+                                const insertParams = {
+                                    ...langLookup, stringContext: entry.context ?? '',
                                     translatedText: result, model: cfg.backendModel, status: 'translated',
-                                });
+                                };
+                                await store.insert(insertParams);
+                                if (shared)
+                                    try {
+                                        await shared.insert(insertParams);
+                                    }
+                                    catch { /* ignore */ }
                                 translated++;
                                 console.log(`  [${done}/${total}] ${lang} translated: ${label}`);
                             }
@@ -454,6 +545,8 @@ export async function runScan(opts) {
                 }
             }
             store.close();
+            if (shared)
+                await shared.close();
             lines.push(`\nTranslated: ${translated} | Skipped: ${skipped} | Failed: ${failed}`);
         } // end if entries.length > 0
     }
@@ -544,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.7');
+program.name('transduck').description('AI-native translation tool').version('0.6.9');
 program.command('init')
     .description('Initialize a new transduck project')
     .action(async () => {

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transduck",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "AI-native translation tool using source text as keys",
   "type": "module",
   "main": "./dist/index.js",

package/src/cli.ts

@@ -459,6 +459,19 @@ export async function runScan(opts: ScanOptions): Promise<string> {
     await store.initialize();
     const projectContextHash = hash(cfg.projectContext);
 
+    // Initialize shared Postgres store if configured
+    let shared: SharedStore | null = null;
+    if (cfg.sharedUrl) {
+      try {
+        shared = new SharedStore(cfg.sharedUrl);
+        await shared.initialize();
+        console.log('  Connected to shared Postgres store');
+      } catch (err) {
+        console.warn(`  Warning: could not connect to shared store: ${(err as Error).message}`);
+        shared = null;
+      }
+    }
+
     let translated = 0;
     let skipped = 0;
     let failed = 0;
@@ -470,20 +483,56 @@ export async function runScan(opts: ScanOptions): Promise<string> {
         const sourceKey = entry.one + '\x00' + entry.other;
         const stringContextHash = hash(entry.context ?? '');
         const label = (entry.one ?? '').slice(0, 40);
+        const lookupParams = {
+          sourceText: sourceKey, sourceLang: cfg.sourceLang,
+          projectContextHash, stringContextHash,
+        };
 
         for (const lang of targetLangs) {
           done++;
-          const cachedForms = await store.lookupPlural({
-            sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
-            projectContextHash, stringContextHash,
-          });
+          const langLookup = { ...lookupParams, targetLang: lang };
+          const cachedForms = await store.lookupPlural(langLookup);
 
           if (Object.keys(cachedForms).length > 0) {
+            // Ensure shared store has it too
+            if (shared) {
+              try {
+                const sharedForms = await shared.lookupPlural(langLookup);
+                if (Object.keys(sharedForms).length === 0) {
+                  for (const [cat, text] of Object.entries(cachedForms)) {
+                    await shared.insertPlural({
+                      ...langLookup, stringContext: entry.context ?? '',
+                      pluralCategory: cat, translatedText: text,
+                      model: cfg.backendModel, status: 'translated',
+                    });
+                  }
+                }
+              } catch { /* ignore shared store errors */ }
+            }
             skipped++;
             console.log(`  [${done}/${total}] ${lang} skipped (cached): ${label}`);
             continue;
           }
 
+          // Check shared store before calling backend
+          if (shared) {
+            try {
+              const sharedForms = await shared.lookupPlural(langLookup);
+              if (Object.keys(sharedForms).length > 0) {
+                for (const [cat, text] of Object.entries(sharedForms)) {
+                  await store.insertPlural({
+                    ...langLookup, stringContext: entry.context ?? '',
+                    pluralCategory: cat, translatedText: text,
+                    model: cfg.backendModel, status: 'translated',
+                  });
+                }
+                skipped++;
+                console.log(`  [${done}/${total}] ${lang} skipped (shared cache): ${label}`);
+                continue;
+              }
+            } catch { /* ignore */ }
+          }
+
           try {
             const forms = await backendTranslatePlural(
               entry.one!, entry.other!,
@@ -492,12 +541,13 @@ export async function runScan(opts: ScanOptions): Promise<string> {
             );
 
             for (const [cat, translatedText] of Object.entries(forms)) {
-              await store.insertPlural({
-                sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
-                projectContextHash, stringContextHash, stringContext: entry.context ?? '',
+              const insertParams = {
+                ...langLookup, stringContext: entry.context ?? '',
                 pluralCategory: cat, translatedText: translatedText as string,
                 model: cfg.backendModel, status: 'translated',
-              });
+              };
+              await store.insertPlural(insertParams);
+              if (shared) try { await shared.insertPlural(insertParams); } catch { /* ignore */ }
             }
             translated++;
             console.log(`  [${done}/${total}] ${lang} translated: ${label}`);
@@ -509,20 +559,50 @@ export async function runScan(opts: ScanOptions): Promise<string> {
       } else {
         const stringContextHash = hash(entry.context ?? '');
         const label = (entry.text ?? '').slice(0, 40);
+        const lookupParams = {
+          sourceText: entry.text!, sourceLang: cfg.sourceLang,
+          projectContextHash, stringContextHash,
+        };
 
         for (const lang of targetLangs) {
           done++;
-          const cached = await store.lookup({
-            sourceText: entry.text!, sourceLang: cfg.sourceLang, targetLang: lang,
-            projectContextHash, stringContextHash,
-          });
+          const langLookup = { ...lookupParams, targetLang: lang };
+          const cached = await store.lookup(langLookup);
 
           if (cached !== null) {
+            // Ensure shared store has it too
+            if (shared) {
+              try {
+                const sharedCached = await shared.lookup(langLookup);
+                if (sharedCached === null) {
+                  await shared.insert({
+                    ...langLookup, stringContext: entry.context ?? '',
+                    translatedText: cached, model: cfg.backendModel, status: 'translated',
+                  });
+                }
+              } catch { /* ignore */ }
+            }
             skipped++;
             console.log(`  [${done}/${total}] ${lang} skipped (cached): ${label}`);
             continue;
           }
 
+          // Check shared store before calling backend
+          if (shared) {
+            try {
+              const sharedCached = await shared.lookup(langLookup);
+              if (sharedCached !== null) {
+                await store.insert({
+                  ...langLookup, stringContext: entry.context ?? '',
+                  translatedText: sharedCached, model: cfg.backendModel, status: 'translated',
+                });
+                skipped++;
+                console.log(`  [${done}/${total}] ${lang} skipped (shared cache): ${label}`);
+                continue;
+              }
+            } catch { /* ignore */ }
+          }
+
           try {
             const result = await backendTranslate(
               entry.text!, cfg.sourceLang, lang,
@@ -530,11 +610,12 @@ export async function runScan(opts: ScanOptions): Promise<string> {
             );
 
             if (validateTranslation(entry.text!, result)) {
-              await store.insert({
-                sourceText: entry.text!, sourceLang: cfg.sourceLang, targetLang: lang,
-                projectContextHash, stringContextHash, stringContext: entry.context ?? '',
+              const insertParams = {
+                ...langLookup, stringContext: entry.context ?? '',
                 translatedText: result, model: cfg.backendModel, status: 'translated',
-              });
+              };
+              await store.insert(insertParams);
+              if (shared) try { await shared.insert(insertParams); } catch { /* ignore */ }
               translated++;
               console.log(`  [${done}/${total}] ${lang} translated: ${label}`);
             } else {
@@ -550,6 +631,7 @@ export async function runScan(opts: ScanOptions): Promise<string> {
     }
 
     store.close();
+    if (shared) await shared.close();
     lines.push(`\nTranslated: ${translated} | Skipped: ${skipped} | Failed: ${failed}`);
     } // end if entries.length > 0
   }
@@ -661,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.7');
+program.name('transduck').description('AI-native translation tool').version('0.6.9');
 
 program.command('init')
   .description('Initialize a new transduck project')

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

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,136 @@ 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('useTransDuck() still works without destructuring (backward compat)', async () => {
     mockFetch.mockResolvedValue({
       ok: true,