transduck 0.0.5 → 0.1.2

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "transduck",
-  "version": "0.0.5",
+  "version": "0.1.2",
   "description": "AI-native translation tool using source text as keys",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
   "bin": {
     "transduck": "./dist/cli.js"
   },
@@ -21,7 +31,21 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@testing-library/react": "^16.0.0",
+    "jsdom": "^25.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
   }
 }

package/src/cli.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 import { createHash } from 'crypto';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { resolve, join } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { resolve, join, dirname } from 'path';
 import { Command } from 'commander';
 import { stringify as yamlStringify } from 'yaml';
 import { loadConfig } from './config.js';
@@ -540,6 +540,25 @@ program.command('init')
       targetLangs: targetsRaw.split(',').map(s => s.trim()),
     });
     console.log(output);
+
+    const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask2 = (q: string): Promise<string> => new Promise(r => rl2.question(q, r));
+
+    const useReact = await ask2('Are you using React/Next.js? (y/n): ');
+    if (useReact.toLowerCase() === 'y') {
+      const routePath = await ask2('API route path (default: app/api/translations/route.ts): ');
+      const finalPath = join(dir, routePath.trim() || 'app/api/translations/route.ts');
+
+      // Create directory
+      const routeDir = dirname(finalPath);
+      mkdirSync(routeDir, { recursive: true });
+
+      // Write route file
+      writeFileSync(finalPath, `import { createTransDuckHandler } from 'transduck';\n\nexport const POST = createTransDuckHandler();\n`);
+      console.log(`Created ${finalPath}`);
+      console.log('Add TransDuckProvider to your layout — see docs: transduck/react');
+    }
+    rl2.close();
   });
 
 program.command('translate')

package/src/config.ts

@@ -14,6 +14,7 @@ export interface TransduckConfig {
   backendModel: string;
   backendTimeout: number;
   backendMaxRetries: number;
+  readOnly: boolean;
 }
 
 function findConfig(): string {
@@ -58,5 +59,6 @@ export function loadConfig(path?: string): TransduckConfig {
     backendModel: raw.backend.model,
     backendTimeout: raw.backend.timeout_seconds,
     backendMaxRetries: raw.backend.max_retries,
+    readOnly: raw.runtime?.read_only ?? false,
   };
 }

package/src/handler.ts

@@ -0,0 +1,193 @@
+import { createHash } from 'crypto';
+import { loadConfig } from './config.js';
+import { TranslationStore } from './storage.js';
+import { translate as backendTranslate, translatePlural as backendTranslatePlural } from './backend.js';
+import { validateTranslation } from './validation.js';
+
+function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+interface TranslationRequestString {
+  text: string;
+  context?: string;
+}
+
+interface TranslationRequestPlural {
+  one: string;
+  other: string;
+  context?: string | null;
+}
+
+export interface TranslationRequest {
+  language: string;
+  strings: TranslationRequestString[];
+  plurals: TranslationRequestPlural[];
+}
+
+export interface TranslationResponse {
+  translations: Record<string, string>;
+  plurals: Record<string, Record<string, string>>;
+}
+
+let _store: TranslationStore | null = null;
+
+async function getStore(configPath?: string) {
+  if (!_store) {
+    const cfg = loadConfig(configPath);
+    _store = new TranslationStore(cfg.storagePath);
+    await _store.initialize();
+  }
+  return _store;
+}
+
+/** @internal Reset the singleton store — for testing only. */
+export function _resetHandlerStore(): void {
+  if (_store) {
+    _store.close();
+  }
+  _store = null;
+}
+
+export async function handleTranslationRequest(
+  body: TranslationRequest,
+  configPath?: string,
+): Promise<TranslationResponse> {
+  const cfg = loadConfig(configPath);
+  const store = await getStore(configPath);
+  const targetLang = body.language.toUpperCase();
+
+  const projectContextHash = hash(cfg.projectContext);
+  const apiKey = process.env[cfg.apiKeyEnv];
+
+  const translations: Record<string, string> = {};
+  const plurals: Record<string, Record<string, string>> = {};
+
+  // Translate regular strings
+  for (const item of body.strings) {
+    const stringContextHash = hash(item.context ?? '');
+    const key = `${item.text}||${item.context ?? ''}`;
+
+    // Cache lookup
+    const cached = await store.lookup({
+      sourceText: item.text,
+      sourceLang: cfg.sourceLang,
+      targetLang,
+      projectContextHash,
+      stringContextHash,
+    });
+
+    if (cached !== null) {
+      translations[key] = cached;
+      continue;
+    }
+
+    // Backend call
+    try {
+      const translated = await backendTranslate({
+        sourceText: item.text,
+        sourceLang: cfg.sourceLang,
+        targetLang,
+        projectContext: cfg.projectContext,
+        stringContext: item.context ?? null,
+        apiKey: apiKey!,
+        model: cfg.backendModel,
+        timeout: cfg.backendTimeout,
+        maxRetries: cfg.backendMaxRetries,
+      });
+
+      if (validateTranslation(item.text, translated)) {
+        await store.insert({
+          sourceText: item.text,
+          sourceLang: cfg.sourceLang,
+          targetLang,
+          projectContextHash,
+          stringContextHash,
+          translatedText: translated,
+          model: cfg.backendModel,
+          status: 'translated',
+        });
+        translations[key] = translated;
+      } else {
+        translations[key] = item.text;
+      }
+    } catch {
+      translations[key] = item.text;
+    }
+  }
+
+  // Translate plurals
+  for (const item of body.plurals) {
+    const stringContextHash = hash(item.context ?? '');
+    const sourceKey = item.one + '\x00' + item.other;
+    const responseKey = `${sourceKey}||${item.context ?? ''}`;
+
+    // Cache lookup
+    const cachedForms = await store.lookupPlural({
+      sourceText: sourceKey,
+      sourceLang: cfg.sourceLang,
+      targetLang,
+      projectContextHash,
+      stringContextHash,
+    });
+
+    if (Object.keys(cachedForms).length > 0) {
+      plurals[responseKey] = cachedForms;
+      continue;
+    }
+
+    // Backend call
+    try {
+      const forms = await backendTranslatePlural({
+        one: item.one,
+        other: item.other,
+        sourceLang: cfg.sourceLang,
+        targetLang,
+        projectContext: cfg.projectContext,
+        stringContext: item.context ?? null,
+        apiKey: apiKey!,
+        model: cfg.backendModel,
+        timeout: cfg.backendTimeout,
+        maxRetries: cfg.backendMaxRetries,
+      });
+
+      for (const [cat, translatedText] of Object.entries(forms)) {
+        await store.insertPlural({
+          sourceText: sourceKey,
+          sourceLang: cfg.sourceLang,
+          targetLang,
+          projectContextHash,
+          stringContextHash,
+          pluralCategory: cat,
+          translatedText: translatedText as string,
+          model: cfg.backendModel,
+          status: 'translated',
+        });
+      }
+      plurals[responseKey] = forms;
+    } catch {
+      plurals[responseKey] = { one: item.one, other: item.other };
+    }
+  }
+
+  return { translations, plurals };
+}
+
+export function createTransDuckHandler(configPath?: string) {
+  return async function POST(request: Request): Promise<Response> {
+    try {
+      const body = await request.json() as TranslationRequest;
+      const result = await handleTranslationRequest(body, configPath);
+      return new Response(JSON.stringify(result), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } catch (err) {
+      console.error('[transduck] Handler error:', err);
+      return new Response(JSON.stringify({ error: 'Translation failed' }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  };
+}

package/src/index.ts

@@ -71,6 +71,11 @@ export async function ait(
   });
   if (cached !== null) return interpolateVars(cached, vars);
 
+  // Read-only mode: skip backend, return source text
+  if (cfg.readOnly) {
+    return interpolateVars(sourceText, vars);
+  }
+
   // In-process dedup
   const lockKey = `${sourceText}|${cfg.sourceLang}|${state.targetLang}|${projectContextHash}|${stringContextHash}`;
 
@@ -125,6 +130,8 @@ export async function ait(
   return interpolateVars(result, vars);
 }
 
+export { createTransDuckHandler } from './handler.js';
+
 export async function aitPlural(
   one: string,
   other: string,
@@ -177,6 +184,13 @@ export async function aitPlural(
     return interpolateVars(cached[category], vars);
   }
 
+  // Read-only mode: skip backend, fall back to source forms
+  if (cfg.readOnly) {
+    const fallbackCategory = getPluralCategory(cfg.sourceLang, count);
+    const fallback = fallbackCategory === 'one' ? one : other;
+    return interpolateVars(fallback, vars);
+  }
+
   // Cache miss — call backend
   const apiKey = process.env[cfg.apiKeyEnv];
   try {

package/src/react/index.ts

@@ -0,0 +1 @@
+export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';

package/src/react/provider.tsx

@@ -0,0 +1,287 @@
+'use client';
+
+import React, { createContext, useContext, useEffect, useState, useCallback, type ReactNode } from 'react';
+
+// --- Module-level state (accessed by stable t()/ait() functions) ---
+
+interface ReactState {
+  language: string;
+  sourceLang: string;
+  endpoint: string;
+  cache: Map<string, string>;
+  pluralCache: Map<string, Record<string, string>>;
+  pendingStrings: Set<string>; // "text||context"
+  pendingPlurals: Set<string>; // "one\x00other||context"
+  triggerFetch: (() => void) | null;
+}
+
+let _state: ReactState = {
+  language: '',
+  sourceLang: 'EN',
+  endpoint: '/api/translations',
+  cache: new Map(),
+  pluralCache: new Map(),
+  pendingStrings: new Set(),
+  pendingPlurals: new Set(),
+  triggerFetch: null,
+};
+
+// --- Context for triggering child re-renders ---
+// The context value (a version counter) changes when translations are loaded.
+// Components that call useTransDuck() subscribe to this and re-render automatically.
+const TransDuckContext = createContext<number>(0);
+
+/**
+ * Hook that subscribes to translation updates. Call this in any component
+ * that uses t()/ait() to ensure it re-renders when translations are loaded.
+ */
+export function useTransDuck(): void {
+  useContext(TransDuckContext);
+}
+
+export function _resetReactState(): void {
+  _state = {
+    language: '',
+    sourceLang: 'EN',
+    endpoint: '/api/translations',
+    cache: new Map(),
+    pluralCache: new Map(),
+    pendingStrings: new Set(),
+    pendingPlurals: new Set(),
+    triggerFetch: null,
+  };
+}
+
+function interpolateVars(text: string, vars?: Record<string, string | number> | null): string {
+  if (!vars) return text;
+  let result = text;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{${key}}`, String(value));
+  }
+  return result;
+}
+
+// --- Stable exported functions ---
+
+export function t(
+  sourceText: string,
+  context?: string,
+  vars?: Record<string, string | number>,
+): string {
+  // Same language — return source
+  if (_state.language.toUpperCase() === _state.sourceLang.toUpperCase()) {
+    return interpolateVars(sourceText, vars);
+  }
+
+  const key = `${sourceText}||${context ?? ''}`;
+
+  // Cache hit
+  const cached = _state.cache.get(key);
+  if (cached !== undefined) {
+    return interpolateVars(cached, vars);
+  }
+
+  // Queue for fetch (useEffect in provider will flush after render)
+  _state.pendingStrings.add(key);
+
+  // Return source text as fallback
+  return interpolateVars(sourceText, vars);
+}
+
+export function tPlural(
+  one: string,
+  other: string,
+  count: number,
+  opts?: { context?: string; vars?: Record<string, string | number> },
+): string {
+  const context = opts?.context;
+  let vars: Record<string, string | number>;
+  if (!opts?.vars) {
+    vars = { count };
+  } else if (!('count' in opts.vars)) {
+    vars = { ...opts.vars, count };
+  } else {
+    vars = { ...opts.vars };
+  }
+
+  // Same language
+  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);
+  }
+
+  const sourceKey = `${one}\x00${other}`;
+  const cacheKey = `${sourceKey}||${context ?? ''}`;
+
+  // Cache hit
+  const cachedForms = _state.pluralCache.get(cacheKey);
+  if (cachedForms) {
+    const rules = new Intl.PluralRules(_state.language.toLowerCase());
+    const category = rules.select(count);
+    const form = cachedForms[category] ?? cachedForms['other'] ?? other;
+    return interpolateVars(form, vars);
+  }
+
+  // Queue for fetch (useEffect in provider will flush after render)
+  _state.pendingPlurals.add(cacheKey);
+
+  // Fallback to source form
+  const rules = new Intl.PluralRules(_state.sourceLang.toLowerCase());
+  const form = rules.select(count) === 'one' ? one : other;
+  return interpolateVars(form, vars);
+}
+
+// Aliases
+export const ait = t;
+export const aitPlural = tPlural;
+
+// --- LocalStorage helpers ---
+
+function loadFromLocalStorage(projectName: string, language: string): void {
+  try {
+    const storageKey = `transduck:${projectName}:${language}`;
+    const stored = localStorage.getItem(storageKey);
+    if (stored) {
+      const data = JSON.parse(stored);
+      if (data.translations) {
+        for (const [k, v] of Object.entries(data.translations)) {
+          _state.cache.set(k, v as string);
+        }
+      }
+      if (data.plurals) {
+        for (const [k, v] of Object.entries(data.plurals)) {
+          _state.pluralCache.set(k, v as Record<string, string>);
+        }
+      }
+    }
+  } catch {
+    // localStorage not available or corrupt — ignore
+  }
+}
+
+function saveToLocalStorage(projectName: string, language: string): void {
+  try {
+    const storageKey = `transduck:${projectName}:${language}`;
+    const data = {
+      translations: Object.fromEntries(_state.cache),
+      plurals: Object.fromEntries(_state.pluralCache),
+    };
+    localStorage.setItem(storageKey, JSON.stringify(data));
+  } catch {
+    // localStorage not available — ignore
+  }
+}
+
+// --- Provider ---
+
+interface TransDuckProviderProps {
+  language: string;
+  sourceLang?: string;
+  endpoint?: string;
+  projectName?: string;
+  children: ReactNode;
+}
+
+export function TransDuckProvider({
+  language,
+  sourceLang = 'EN',
+  endpoint = '/api/translations',
+  projectName = 'default',
+  children,
+}: TransDuckProviderProps) {
+  const [version, setVersion] = useState(0);
+
+  // Update module-level state synchronously so t() works during first render
+  _state.endpoint = endpoint;
+  _state.sourceLang = sourceLang;
+
+  const upperLang = language.toUpperCase();
+  if (_state.language !== upperLang) {
+    _state.language = upperLang;
+    _state.cache.clear();
+    _state.pluralCache.clear();
+    loadFromLocalStorage(projectName, upperLang);
+  }
+
+  // Set up trigger
+  const doFetch = useCallback(async () => {
+    const stringsToFetch = new Set(_state.pendingStrings);
+    const pluralsToFetch = new Set(_state.pendingPlurals);
+    _state.pendingStrings.clear();
+    _state.pendingPlurals.clear();
+
+    // Filter out already-cached
+    for (const key of stringsToFetch) {
+      if (_state.cache.has(key)) stringsToFetch.delete(key);
+    }
+    for (const key of pluralsToFetch) {
+      if (_state.pluralCache.has(key)) pluralsToFetch.delete(key);
+    }
+
+    if (stringsToFetch.size === 0 && pluralsToFetch.size === 0) return;
+
+    // Build request body
+    const strings = Array.from(stringsToFetch).map(key => {
+      const [text, context] = key.split('||');
+      return { text, context: context || undefined };
+    });
+    const plurals = Array.from(pluralsToFetch).map(key => {
+      const [sourceKey, context] = key.split('||');
+      const [one, other] = sourceKey.split('\x00');
+      return { one, other, context: context || undefined };
+    });
+
+    try {
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          language: _state.language,
+          strings,
+          plurals,
+        }),
+      });
+
+      if (!response.ok) {
+        console.warn(`[transduck] Translation fetch failed: ${response.status}`);
+        return;
+      }
+
+      const data = await response.json();
+
+      // Store translations
+      if (data.translations) {
+        for (const [key, value] of Object.entries(data.translations)) {
+          _state.cache.set(key, value as string);
+        }
+      }
+      if (data.plurals) {
+        for (const [key, value] of Object.entries(data.plurals)) {
+          _state.pluralCache.set(key, value as Record<string, string>);
+        }
+      }
+
+      saveToLocalStorage(projectName, _state.language);
+      setVersion(v => v + 1);
+    } catch (err) {
+      console.warn('[transduck] Translation fetch error:', err);
+    }
+  }, [endpoint, projectName]);
+
+  // Register trigger
+  _state.triggerFetch = doFetch;
+
+  // Flush pending after render
+  useEffect(() => {
+    if (_state.pendingStrings.size > 0 || _state.pendingPlurals.size > 0) {
+      doFetch();
+    }
+  });
+
+  return (
+    <TransDuckContext.Provider value={version}>
+      {children}
+    </TransDuckContext.Provider>
+  );
+}

package/src/scanner.ts

@@ -31,6 +31,14 @@ const AIT_PLURAL = /ait(?:_p|P)lural\s*\(\s*(['"])(.*?)\1\s*,\s*(['"])(.*?)\3/g;
 // {% ait "text" %} or {% ait "text" context="ctx" %}
 const DJANGO_TAG = /\{%\s*ait\s+(['"])(.*?)\1(?:\s+context=(['"])(.*?)\3)?\s*%\}/g;
 
+// t("text") or t("text", "ctx") — only matched in files with transduck/react import
+const T_POSITIONAL = /(?<![a-zA-Z_.$])t\s*\(\s*(['"])(.*?)\1(?:\s*,\s*(['"])(.*?)\3)?/g;
+
+// tPlural("one", "other") — only matched in files with transduck/react import
+const T_PLURAL = /(?<![a-zA-Z_.$])tPlural\s*\(\s*(['"])(.*?)\1\s*,\s*(['"])(.*?)\3/g;
+
+const HAS_TRANSDUCK_REACT = /from\s+['"]transduck\/react['"]/;
+
 // File extensions that use JS-style positional context
 const JS_EXTENSIONS = new Set(['.js', '.ts', '.tsx', '.jsx']);
 
@@ -112,6 +120,27 @@ export function extractStrings(content: string, filename: string): ScanEntry[] {
     results.push({ text, context, line: lineNum });
   }
 
+  // 4. t() and tPlural() — only in files that import from transduck/react
+  if (HAS_TRANSDUCK_REACT.test(content)) {
+    // t() calls
+    for (const m of content.matchAll(new RegExp(T_POSITIONAL.source, 'g'))) {
+      const pos = m.index!;
+      // Skip if overlaps with plural spans
+      if (pluralSpans.some(([start, end]) => pos >= start && pos < end)) continue;
+      const text = m[2];
+      const context = m[4] || null;
+      const lineNum = content.slice(0, pos).split('\n').length;
+      results.push({ text, context, line: lineNum });
+    }
+    // tPlural() calls
+    for (const m of content.matchAll(new RegExp(T_PLURAL.source, 'g'))) {
+      const one = m[2];
+      const other = m[4];
+      const lineNum = content.slice(0, m.index!).split('\n').length;
+      results.push({ plural: true, one, other, context: null, line: lineNum });
+    }
+  }
+
   return results;
 }