transduck 0.6.8 → 0.6.9

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.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.8",
+  "version": "0.6.9",
   "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.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,