transduck 0.0.5 → 0.1.2

package/README.md

@@ -0,0 +1,88 @@
+# TransDuck
+
+AI-powered translation for apps and websites. Fast. Cheap. No keys to manage.
+
+TransDuck translates your app's strings using AI, then caches them locally in DuckDB so you never pay for the same translation twice. No translation files. No key naming. No sync headaches.
+
+```typescript
+import { initialize, setLanguage, ait, aitPlural } from 'transduck';
+
+await initialize();
+setLanguage('DE');
+
+await ait('Welcome to Mallorca');              // → "Willkommen auf Mallorca"
+await ait('Hello {name}', undefined, { name: 'Tim' });  // → "Hallo Tim"
+await aitPlural('{count} night', '{count} nights', 7);   // → "7 Nächte"
+```
+
+## Why TransDuck?
+
+- **No keys to manage** — your source text is the key
+- **No translation files** — translations live in a single in-memory database file
+- **Translate once, pay once** — cached lookups take ~1.5ms, zero API costs after first call
+- **AI that understands context** — project and per-string context for accurate translations
+- **Pluralization that works everywhere** — handles Russian (4 forms), Arabic (6 forms) automatically
+- **Built for vibe coding** — AI coding tools read the docs and wrap strings with `ait()` across your project
+- **Dirt cheap** — 1,000 strings x 5 languages costs about $0.10 with gpt-4.1-mini
+
+## Quick Start
+
+```bash
+npm install transduck
+transduck init
+```
+
+## React / Next.js
+
+TransDuck includes a first-party React integration with synchronous `t()` for client components:
+
+```tsx
+// app/api/translations/route.ts (one-time setup)
+import { createTransDuckHandler } from 'transduck';
+export const POST = createTransDuckHandler();
+```
+
+```tsx
+// layout.tsx
+import { TransDuckProvider } from 'transduck/react';
+
+<TransDuckProvider language="DE">
+  <App />
+</TransDuckProvider>
+```
+
+```tsx
+// Any client component
+'use client';
+import { t, tPlural, useTransDuck } from 'transduck/react';
+
+function Dashboard() {
+  useTransDuck();
+  return (
+    <h1>{t("Dashboard")}</h1>
+    <p>{tPlural("{count} property", "{count} properties", 5)}</p>
+  );
+}
+```
+
+## CLI
+
+```bash
+transduck scan --warm --langs DE,ES,IT   # scan codebase and translate everything
+transduck translate "Hello" --to DE       # translate a single string
+transduck stats                           # check your translation database
+```
+
+## Also available for Python
+
+```bash
+pip install transduck
+```
+
+Works with Django, Flask, FastAPI, and Jinja. Same DuckDB database format — share translations between Python and JS.
+
+## Links
+
+- [GitHub](https://github.com/timnilson/transduck)
+- [Full Documentation](https://github.com/timnilson/transduck/blob/main/DOCUMENTATION.md)
+- [PyPI Package](https://pypi.org/project/transduck/)

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;
 }
 /**