transduck 0.0.5 → 0.1.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createHash } from 'crypto';
-import { readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
 import { Command } from 'commander';
 import { stringify as yamlStringify } from 'yaml';
 import { loadConfig } from './config.js';
@@ -456,6 +456,21 @@ 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) => 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')
     .description('Translate a single string')

package/dist/config.d.ts

@@ -8,5 +8,6 @@ export interface TransduckConfig {
     backendModel: string;
     backendTimeout: number;
     backendMaxRetries: number;
+    readOnly: boolean;
 }
 export declare function loadConfig(path?: string): TransduckConfig;

package/dist/config.js

@@ -39,5 +39,6 @@ export function loadConfig(path) {
         backendModel: raw.backend.model,
         backendTimeout: raw.backend.timeout_seconds,
         backendMaxRetries: raw.backend.max_retries,
+        readOnly: raw.runtime?.read_only ?? false,
     };
 }

package/dist/handler.d.ts

@@ -0,0 +1,23 @@
+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>>;
+}
+/** @internal Reset the singleton store — for testing only. */
+export declare function _resetHandlerStore(): void;
+export declare function handleTranslationRequest(body: TranslationRequest, configPath?: string): Promise<TranslationResponse>;
+export declare function createTransDuckHandler(configPath?: string): (request: Request) => Promise<Response>;
+export {};

package/dist/handler.js

@@ -0,0 +1,153 @@
+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) {
+    return createHash('sha256').update(text).digest('hex');
+}
+let _store = null;
+async function getStore(configPath) {
+    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() {
+    if (_store) {
+        _store.close();
+    }
+    _store = null;
+}
+export async function handleTranslationRequest(body, configPath) {
+    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 = {};
+    const plurals = {};
+    // 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,
+                    model: cfg.backendModel,
+                    status: 'translated',
+                });
+            }
+            plurals[responseKey] = forms;
+        }
+        catch {
+            plurals[responseKey] = { one: item.one, other: item.other };
+        }
+    }
+    return { translations, plurals };
+}
+export function createTransDuckHandler(configPath) {
+    return async function POST(request) {
+        try {
+            const body = await request.json();
+            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/dist/index.d.ts

@@ -5,6 +5,7 @@ export declare function setLanguage(lang: string): void;
 export declare function _resetState(): void;
 export declare function _getStore(): TranslationStore | null;
 export declare function ait(sourceText: string, context?: string, vars?: Record<string, string | number>): Promise<string>;
+export { createTransDuckHandler } from './handler.js';
 export declare function aitPlural(one: string, other: string, count: number, opts?: {
     context?: string;
     vars?: Record<string, string | number>;

package/dist/index.js

@@ -49,6 +49,10 @@ export async function ait(sourceText, context, vars) {
     });
     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}`;
     if (state.pendingTranslations.has(lockKey)) {
@@ -99,6 +103,7 @@ export async function ait(sourceText, context, vars) {
     const result = await translationPromise;
     return interpolateVars(result, vars);
 }
+export { createTransDuckHandler } from './handler.js';
 export async function aitPlural(one, other, count, opts) {
     if (!state.config || !state.store) {
         throw new Error('transduck not initialized. Call initialize() first.');
@@ -141,6 +146,12 @@ export async function aitPlural(one, other, count, opts) {
     if (category in cached) {
         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/dist/react/index.d.ts

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

package/dist/react/index.js

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

package/dist/react/provider.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+/**
+ * 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 declare function useTransDuck(): void;
+export declare function _resetReactState(): void;
+export declare function t(sourceText: string, context?: string, vars?: Record<string, string | number>): string;
+export declare function tPlural(one: string, other: string, count: number, opts?: {
+    context?: string;
+    vars?: Record<string, string | number>;
+}): string;
+export declare const ait: typeof t;
+export declare const aitPlural: typeof tPlural;
+interface TransDuckProviderProps {
+    language: string;
+    sourceLang?: string;
+    endpoint?: string;
+    projectName?: string;
+    children: ReactNode;
+}
+export declare function TransDuckProvider({ language, sourceLang, endpoint, projectName, children, }: TransDuckProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/react/provider.js

@@ -0,0 +1,218 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState, useCallback } from 'react';
+let _state = {
+    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(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() {
+    useContext(TransDuckContext);
+}
+export function _resetReactState() {
+    _state = {
+        language: '',
+        sourceLang: 'EN',
+        endpoint: '/api/translations',
+        cache: new Map(),
+        pluralCache: new Map(),
+        pendingStrings: new Set(),
+        pendingPlurals: new Set(),
+        triggerFetch: null,
+    };
+}
+function interpolateVars(text, vars) {
+    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, context, vars) {
+    // 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, other, count, opts) {
+    const context = opts?.context;
+    let vars;
+    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, language) {
+    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);
+                }
+            }
+            if (data.plurals) {
+                for (const [k, v] of Object.entries(data.plurals)) {
+                    _state.pluralCache.set(k, v);
+                }
+            }
+        }
+    }
+    catch {
+        // localStorage not available or corrupt — ignore
+    }
+}
+function saveToLocalStorage(projectName, language) {
+    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
+    }
+}
+export function TransDuckProvider({ language, sourceLang = 'EN', endpoint = '/api/translations', projectName = 'default', children, }) {
+    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);
+                }
+            }
+            if (data.plurals) {
+                for (const [key, value] of Object.entries(data.plurals)) {
+                    _state.pluralCache.set(key, value);
+                }
+            }
+            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 (_jsx(TransDuckContext.Provider, { value: version, children: children }));
+}

package/dist/scanner.js

@@ -12,6 +12,11 @@ const AIT_POSITIONAL_CTX = /ait\s*\(\s*(['"])(.*?)\1(?:\s*,\s*(['"])(.*?)\3)?/g;
 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']);
 // File extensions that may contain Django template tags
@@ -83,6 +88,27 @@ export function extractStrings(content, filename) {
         const lineNum = content.slice(0, pos).split('\n').length;
         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;
 }
 /**

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "transduck",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "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,
   };
 }