transduck 0.5.3 → 0.6.0

package/dist/index.js

@@ -1,14 +1,18 @@
 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 { SharedStore } from './shared-store.js';
+import { TranslationResult } from './result.js';
+import { translate as backendTranslate, translatePlural as backendTranslatePlural, detectLanguage as backendDetectLanguage } from './backend.js';
 import { validateTranslation, extractPlaceholders } from './validation.js';
 import { getPluralCategory, getPluralCategories, interpolateVars } from './plural.js';
 let state = {
     config: null,
     store: null,
+    sharedStore: null,
     targetLang: null,
     pendingTranslations: new Map(),
+    backgroundKeys: new Set(),
 };
 function hash(text) {
     return createHash('sha256').update(text).digest('hex');
@@ -19,85 +23,156 @@ export async function initialize(config) {
     await store.initialize();
     state.config = cfg;
     state.store = store;
+    if (cfg.sharedUrl) {
+        try {
+            const shared = new SharedStore(cfg.sharedUrl);
+            await shared.initialize();
+            state.sharedStore = shared;
+        }
+        catch (err) {
+            console.warn(`[transduck] Could not connect to shared store: ${err.message}`);
+            state.sharedStore = null;
+        }
+    }
 }
 export function setLanguage(lang) {
     state.targetLang = lang.toUpperCase();
 }
 export function _resetState() {
-    state = { config: null, store: null, targetLang: null, pendingTranslations: new Map() };
+    state = {
+        config: null, store: null, sharedStore: null, targetLang: null,
+        pendingTranslations: new Map(), backgroundKeys: new Set(),
+    };
 }
 export function _getStore() {
     return state.store;
 }
-export async function ait(sourceText, context, vars) {
+export function _getSharedStore() {
+    return state.sharedStore;
+}
+export function _setSharedStore(shared) {
+    state.sharedStore = shared;
+}
+export async function ait(sourceText, contextOrOpts, vars) {
     if (!state.config || !state.store) {
         throw new Error('transduck not initialized. Call initialize() first.');
     }
     if (!state.targetLang) {
         throw new Error('Target language not set. Call setLanguage() first.');
     }
+    // Parse overloaded args: ait(text, context?, vars?) OR ait(text, opts)
+    let context;
+    let resolvedVars;
+    let sourceLang;
+    let background = false;
+    if (typeof contextOrOpts === 'string') {
+        context = contextOrOpts;
+        resolvedVars = vars;
+    }
+    else if (contextOrOpts != null) {
+        context = contextOrOpts.context;
+        resolvedVars = contextOrOpts.vars;
+        sourceLang = contextOrOpts.sourceLang;
+        background = contextOrOpts.background ?? false;
+    }
+    else {
+        resolvedVars = vars;
+    }
     const cfg = state.config;
-    if (state.targetLang === cfg.sourceLang) {
-        return interpolateVars(sourceText, vars);
+    const effectiveSourceLang = sourceLang?.toUpperCase() ?? cfg.sourceLang;
+    const targetLang = state.targetLang;
+    if (targetLang === effectiveSourceLang) {
+        return new TranslationResult(interpolateVars(sourceText, resolvedVars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
     }
     const projectContextHash = hash(cfg.projectContext);
     const stringContextHash = hash(context ?? '');
-    // Cache lookup
-    const cached = await state.store.lookup({
-        sourceText, sourceLang: cfg.sourceLang, targetLang: state.targetLang,
+    const lookupParams = {
+        sourceText, sourceLang: effectiveSourceLang, targetLang,
         projectContextHash, stringContextHash,
-    });
-    if (cached !== null)
-        return interpolateVars(cached, vars);
+    };
+    // Tier 1: local SQLite lookup
+    const cached = await state.store.lookup(lookupParams);
+    if (cached !== null) {
+        return new TranslationResult(interpolateVars(cached, resolvedVars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+    }
+    // Tier 2: shared Postgres lookup
+    if (state.sharedStore) {
+        const sharedCached = await state.sharedStore.lookup(lookupParams);
+        if (sharedCached !== null) {
+            // Propagate to local store
+            await state.store.insert({
+                ...lookupParams, stringContext: context ?? '',
+                translatedText: sharedCached, model: cfg.backendModel, status: 'translated',
+            });
+            return new TranslationResult(interpolateVars(sharedCached, resolvedVars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+        }
+    }
     // Read-only mode: skip backend, return source text
     if (cfg.readOnly) {
-        return interpolateVars(sourceText, vars);
+        return new TranslationResult(interpolateVars(sourceText, resolvedVars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+    }
+    // Background mode: return immediately with pending=true
+    if (background) {
+        const bgKey = `${sourceText}|${effectiveSourceLang}|${targetLang}|${projectContextHash}|${stringContextHash}`;
+        if (!state.backgroundKeys.has(bgKey)) {
+            state.backgroundKeys.add(bgKey);
+            _doTranslate(sourceText, effectiveSourceLang, targetLang, projectContextHash, stringContextHash, context ?? '', cfg)
+                .finally(() => state.backgroundKeys.delete(bgKey));
+        }
+        return new TranslationResult(interpolateVars(sourceText, resolvedVars), { pending: true, sourceLang: effectiveSourceLang, lang: targetLang });
     }
     // In-process dedup
-    const lockKey = `${sourceText}|${cfg.sourceLang}|${state.targetLang}|${projectContextHash}|${stringContextHash}`;
+    const lockKey = `${sourceText}|${effectiveSourceLang}|${targetLang}|${projectContextHash}|${stringContextHash}`;
     if (state.pendingTranslations.has(lockKey)) {
         const pending = await state.pendingTranslations.get(lockKey);
-        return interpolateVars(pending, vars);
+        return new TranslationResult(interpolateVars(pending, resolvedVars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
     }
-    const translationPromise = (async () => {
-        // Double-check after getting in
-        const rechecked = await state.store.lookup({
-            sourceText, sourceLang: cfg.sourceLang, targetLang: state.targetLang,
-            projectContextHash, stringContextHash,
-        });
-        if (rechecked !== null)
-            return rechecked;
-        try {
-            const translated = await backendTranslate(sourceText, cfg.sourceLang, state.targetLang, cfg.projectContext, context ?? null, cfg);
-            if (!validateTranslation(sourceText, translated)) {
-                console.warn(`[transduck] Validation failed for: ${sourceText} -> ${translated}`);
-                await state.store.insert({
-                    sourceText, sourceLang: cfg.sourceLang, targetLang: state.targetLang,
-                    projectContextHash, stringContextHash, stringContext: context ?? '',
-                    translatedText: translated, model: cfg.backendModel, status: 'failed',
-                });
-                return sourceText;
-            }
-            await state.store.insert({
-                sourceText, sourceLang: cfg.sourceLang, targetLang: state.targetLang,
-                projectContextHash, stringContextHash, stringContext: context ?? '',
-                translatedText: translated, model: cfg.backendModel, status: 'translated',
-            });
-            return translated;
-        }
-        catch (err) {
-            console.warn(`[transduck] Backend failed for: ${sourceText}`, err);
-            return sourceText;
-        }
-        finally {
-            state.pendingTranslations.delete(lockKey);
-        }
-    })();
+    const translationPromise = _doTranslate(sourceText, effectiveSourceLang, targetLang, projectContextHash, stringContextHash, context ?? '', cfg);
     state.pendingTranslations.set(lockKey, translationPromise);
     const result = await translationPromise;
-    return interpolateVars(result, vars);
+    state.pendingTranslations.delete(lockKey);
+    return new TranslationResult(interpolateVars(result, resolvedVars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+}
+async function _doTranslate(sourceText, sourceLang, targetLang, projectContextHash, stringContextHash, stringContext, cfg) {
+    // Double-check local cache
+    const rechecked = await state.store.lookup({
+        sourceText, sourceLang, targetLang, projectContextHash, stringContextHash,
+    });
+    if (rechecked !== null)
+        return rechecked;
+    try {
+        const translated = await backendTranslate(sourceText, sourceLang, targetLang, cfg.projectContext, stringContext || null, cfg);
+        const insertParams = {
+            sourceText, sourceLang, targetLang,
+            projectContextHash, stringContextHash, stringContext,
+            translatedText: translated, model: cfg.backendModel,
+        };
+        if (!validateTranslation(sourceText, translated)) {
+            console.warn(`[transduck] Validation failed for: ${sourceText} -> ${translated}`);
+            await state.store.insert({ ...insertParams, status: 'failed' });
+            if (state.sharedStore)
+                await state.sharedStore.insert({ ...insertParams, status: 'failed' });
+            return sourceText;
+        }
+        await state.store.insert({ ...insertParams, status: 'translated' });
+        if (state.sharedStore)
+            await state.sharedStore.insert({ ...insertParams, status: 'translated' });
+        return translated;
+    }
+    catch (err) {
+        console.warn(`[transduck] Backend failed for: ${sourceText}`, err);
+        return sourceText;
+    }
 }
 export { createTransDuckHandler } from './handler.js';
+export { TranslationResult } from './result.js';
+export { SharedStore } from './shared-store.js';
+export async function detectLanguage(text) {
+    if (!state.config) {
+        throw new Error('transduck not initialized. Call initialize() first.');
+    }
+    return backendDetectLanguage(text, state.config);
+}
 export async function aitPlural(one, other, count, opts) {
     if (!state.config || !state.store) {
         throw new Error('transduck not initialized. Call initialize() first.');
@@ -107,6 +182,8 @@ export async function aitPlural(one, other, count, opts) {
     }
     const cfg = state.config;
     const context = opts?.context;
+    const effectiveSourceLang = opts?.sourceLang?.toUpperCase() ?? cfg.sourceLang;
+    const background = opts?.background ?? false;
     // Build vars with count
     let vars;
     if (!opts?.vars) {
@@ -118,37 +195,76 @@ export async function aitPlural(one, other, count, opts) {
     else {
         vars = { ...opts.vars };
     }
+    const targetLang = state.targetLang;
     // Same language, 2-form language: select directly from provided forms
-    if (state.targetLang === cfg.sourceLang) {
-        const categories = getPluralCategories(cfg.sourceLang);
+    if (targetLang === effectiveSourceLang) {
+        const categories = getPluralCategories(effectiveSourceLang);
         if (categories.size <= 2) {
-            const category = getPluralCategory(cfg.sourceLang, count);
+            const category = getPluralCategory(effectiveSourceLang, count);
             const form = category === 'one' ? one : other;
-            return interpolateVars(form, vars);
+            return new TranslationResult(interpolateVars(form, vars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
         }
     }
     // Build cache key
     const sourceKey = one + '\x00' + other;
     const projectContextHash = hash(cfg.projectContext);
     const stringContextHash = hash(context ?? '');
-    // Cache lookup
-    const cached = await state.store.lookupPlural({
-        sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: state.targetLang,
+    const lookupParams = {
+        sourceText: sourceKey, sourceLang: effectiveSourceLang, targetLang,
         projectContextHash, stringContextHash,
-    });
-    const category = getPluralCategory(state.targetLang, count);
+    };
+    const category = getPluralCategory(targetLang, count);
+    // Tier 1: local cache lookup
+    const cached = await state.store.lookupPlural(lookupParams);
     if (category in cached) {
-        return interpolateVars(cached[category], vars);
+        return new TranslationResult(interpolateVars(cached[category], vars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+    }
+    // Tier 2: shared store lookup
+    if (state.sharedStore) {
+        const sharedCached = await state.sharedStore.lookupPlural(lookupParams);
+        if (category in sharedCached) {
+            // Propagate all forms to local store
+            for (const [cat, text] of Object.entries(sharedCached)) {
+                await state.store.insertPlural({
+                    ...lookupParams, stringContext: context ?? '',
+                    pluralCategory: cat, translatedText: text,
+                    model: cfg.backendModel, status: 'translated',
+                });
+            }
+            return new TranslationResult(interpolateVars(sharedCached[category], vars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+        }
     }
     // Read-only mode: skip backend, fall back to source forms
     if (cfg.readOnly) {
-        const fallbackCategory = getPluralCategory(cfg.sourceLang, count);
+        const fallbackCategory = getPluralCategory(effectiveSourceLang, count);
         const fallback = fallbackCategory === 'one' ? one : other;
-        return interpolateVars(fallback, vars);
+        return new TranslationResult(interpolateVars(fallback, vars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+    }
+    // Background mode
+    if (background) {
+        const bgKey = `plural|${sourceKey}|${effectiveSourceLang}|${targetLang}|${projectContextHash}|${stringContextHash}`;
+        if (!state.backgroundKeys.has(bgKey)) {
+            state.backgroundKeys.add(bgKey);
+            _doPluralTranslate(one, other, sourceKey, effectiveSourceLang, targetLang, projectContextHash, stringContextHash, context ?? '', cfg)
+                .finally(() => state.backgroundKeys.delete(bgKey));
+        }
+        const fallbackCategory = getPluralCategory(effectiveSourceLang, count);
+        const fallback = fallbackCategory === 'one' ? one : other;
+        return new TranslationResult(interpolateVars(fallback, vars), { pending: true, sourceLang: effectiveSourceLang, lang: targetLang });
     }
     // Cache miss — call backend
+    const translatedText = await _doPluralTranslate(one, other, sourceKey, effectiveSourceLang, targetLang, projectContextHash, stringContextHash, context ?? '', cfg);
+    if (translatedText !== null && category in translatedText) {
+        return new TranslationResult(interpolateVars(translatedText[category], vars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+    }
+    // Fallback
+    const fallbackCategory = getPluralCategory(effectiveSourceLang, count);
+    const fallback = fallbackCategory === 'one' ? one : other;
+    return new TranslationResult(interpolateVars(fallback, vars), { pending: false, sourceLang: effectiveSourceLang, lang: targetLang });
+}
+async function _doPluralTranslate(one, other, sourceKey, sourceLang, targetLang, projectContextHash, stringContextHash, stringContext, cfg) {
     try {
-        const forms = await backendTranslatePlural(one, other, cfg.sourceLang, state.targetLang, cfg.projectContext, context ?? null, cfg);
+        const forms = await backendTranslatePlural(one, other, sourceLang, targetLang, cfg.projectContext, stringContext || null, cfg);
         // Validate and store each form
         const validCategories = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
         const sourcePlaceholders = new Set([
@@ -157,14 +273,15 @@ export async function aitPlural(one, other, count, opts) {
         ]);
         if (typeof forms !== 'object' || forms === null || !('other' in forms)) {
             console.warn(`[transduck] Invalid plural response for: ${one} / ${other}`);
-            const fallbackCategory = getPluralCategory(cfg.sourceLang, count);
-            const fallback = fallbackCategory === 'one' ? one : other;
-            return interpolateVars(fallback, vars);
+            return null;
         }
+        const lookupParams = {
+            sourceText: sourceKey, sourceLang, targetLang,
+            projectContextHash, stringContextHash,
+        };
         for (const [cat, text] of Object.entries(forms)) {
             if (!validCategories.has(cat) || !text)
                 continue;
-            // Validate placeholders
             const translatedPlaceholders = extractPlaceholders(text);
             let allPresent = true;
             for (const p of sourcePlaceholders) {
@@ -174,37 +291,19 @@ export async function aitPlural(one, other, count, opts) {
                 }
             }
             const status = allPresent ? 'translated' : 'failed';
-            await state.store.insertPlural({
-                sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: state.targetLang,
-                projectContextHash, stringContextHash, stringContext: context ?? '',
+            const insertParams = {
+                ...lookupParams, stringContext,
                 pluralCategory: cat, translatedText: text,
                 model: cfg.backendModel, status,
-            });
+            };
+            await state.store.insertPlural(insertParams);
+            if (state.sharedStore)
+                await state.sharedStore.insertPlural(insertParams);
         }
-        // Select the right form
-        if (category in forms) {
-            const text = forms[category];
-            const tp = extractPlaceholders(text);
-            let allPresent = true;
-            for (const p of sourcePlaceholders) {
-                if (!tp.has(p)) {
-                    allPresent = false;
-                    break;
-                }
-            }
-            if (allPresent) {
-                return interpolateVars(text, vars);
-            }
-        }
-        // Fallback
-        const fallbackCategory = getPluralCategory(cfg.sourceLang, count);
-        const fallback = fallbackCategory === 'one' ? one : other;
-        return interpolateVars(fallback, vars);
+        return forms;
     }
     catch (err) {
         console.warn(`[transduck] Backend failed for plural: ${one} / ${other}`, err);
-        const fallbackCategory = getPluralCategory(cfg.sourceLang, count);
-        const fallback = fallbackCategory === 'one' ? one : other;
-        return interpolateVars(fallback, vars);
+        return null;
     }
 }

package/dist/providers/claude-api.d.ts

@@ -4,4 +4,5 @@
  */
 import type { TransduckConfig } from '../config.js';
 export declare function translate(sourceText: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig): Promise<string>;
+export declare function detectLanguage(text: string, config: TransduckConfig): Promise<string>;
 export declare function translatePlural(one: string, other: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig): Promise<Record<string, string>>;

package/dist/providers/claude-api.js

@@ -33,6 +33,17 @@ export async function translate(sourceText, sourceLang, targetLang, projectConte
     });
     return response.content[0].text.trim();
 }
+export async function detectLanguage(text, config) {
+    const client = await getClient(config);
+    const response = await client.messages.create({
+        model: config.backendModel,
+        max_tokens: 16,
+        temperature: 0.0,
+        system: 'What language is this text written in? Return only the uppercase ISO 639-1 code.',
+        messages: [{ role: 'user', content: text }],
+    });
+    return response.content[0].text.trim().toUpperCase();
+}
 export async function translatePlural(one, other, sourceLang, targetLang, projectContext, stringContext, config) {
     const client = await getClient(config);
     const messages = buildPluralMessages({

package/dist/providers/claude-code.d.ts

@@ -5,4 +5,5 @@
  */
 import type { TransduckConfig } from '../config.js';
 export declare function translate(sourceText: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig): Promise<string>;
+export declare function detectLanguage(text: string, config: TransduckConfig): Promise<string>;
 export declare function translatePlural(one: string, other: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig): Promise<Record<string, string>>;

package/dist/providers/claude-code.js

@@ -37,6 +37,12 @@ export async function translate(sourceText, sourceLang, targetLang, projectConte
     });
     return translateWithSdk(prompt);
 }
+export async function detectLanguage(text, config) {
+    ensureToken(config);
+    const prompt = 'What language is this text written in? Return only the uppercase ISO 639-1 code.\n\n' + text;
+    const raw = await translateWithSdk(prompt);
+    return raw.trim().toUpperCase();
+}
 export async function translatePlural(one, other, sourceLang, targetLang, projectContext, stringContext, config) {
     ensureToken(config);
     const prompt = buildPluralSinglePrompt({

package/dist/providers/index.d.ts

@@ -5,6 +5,7 @@ import type { TransduckConfig } from '../config.js';
 export interface TranslationProvider {
     translate(sourceText: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig, _clientOverride?: any): Promise<string>;
     translatePlural(one: string, other: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig, _clientOverride?: any): Promise<Record<string, string>>;
+    detectLanguage(text: string, config: TransduckConfig, _clientOverride?: any): Promise<string>;
 }
 /**
  * Return the provider module for the configured provider.

package/dist/providers/openai-provider.d.ts

@@ -3,4 +3,5 @@
  */
 import type { TransduckConfig } from '../config.js';
 export declare function translate(sourceText: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig, _clientOverride?: any): Promise<string>;
+export declare function detectLanguage(text: string, config: TransduckConfig, _clientOverride?: any): Promise<string>;
 export declare function translatePlural(one: string, other: string, sourceLang: string, targetLang: string, projectContext: string, stringContext: string | null, config: TransduckConfig, _clientOverride?: any): Promise<Record<string, string>>;

package/dist/providers/openai-provider.js

@@ -20,6 +20,23 @@ export async function translate(sourceText, sourceLang, targetLang, projectConte
     });
     return response.choices[0].message.content.trim();
 }
+export async function detectLanguage(text, config, _clientOverride) {
+    const apiKey = process.env[config.apiKeyEnv];
+    const client = _clientOverride ?? new OpenAI({
+        apiKey,
+        timeout: config.backendTimeout * 1000,
+        maxRetries: config.backendMaxRetries,
+    });
+    const response = await client.chat.completions.create({
+        model: config.backendModel,
+        messages: [
+            { role: 'system', content: 'What language is this text written in? Return only the uppercase ISO 639-1 code.' },
+            { role: 'user', content: text },
+        ],
+        temperature: 0.0,
+    });
+    return response.choices[0].message.content.trim().toUpperCase();
+}
 export async function translatePlural(one, other, sourceLang, targetLang, projectContext, stringContext, config, _clientOverride) {
     const apiKey = process.env[config.apiKeyEnv];
     const client = _clientOverride ?? new OpenAI({

package/dist/result.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A string wrapper that carries translation metadata.
+ *
+ * Works in template literals, concatenation, and equality checks via
+ * toString() and valueOf() overrides, plus Symbol.toPrimitive.
+ */
+export declare class TranslationResult extends String {
+    readonly pending: boolean;
+    readonly sourceLang: string;
+    readonly lang: string;
+    constructor(text: string, opts: {
+        pending: boolean;
+        sourceLang: string;
+        lang: string;
+    });
+    toString(): string;
+    valueOf(): string;
+    [Symbol.toPrimitive](_hint: string): string;
+}

package/dist/result.js

@@ -0,0 +1,26 @@
+/**
+ * A string wrapper that carries translation metadata.
+ *
+ * Works in template literals, concatenation, and equality checks via
+ * toString() and valueOf() overrides, plus Symbol.toPrimitive.
+ */
+export class TranslationResult extends String {
+    pending;
+    sourceLang;
+    lang;
+    constructor(text, opts) {
+        super(text);
+        this.pending = opts.pending;
+        this.sourceLang = opts.sourceLang;
+        this.lang = opts.lang;
+    }
+    toString() {
+        return super.toString();
+    }
+    valueOf() {
+        return super.valueOf();
+    }
+    [Symbol.toPrimitive](_hint) {
+        return super.valueOf();
+    }
+}

package/dist/shared-store.d.ts

@@ -0,0 +1,18 @@
+import type { LookupParams, InsertParams, InsertPluralParams } from './storage.js';
+export declare class SharedStore {
+    private pool;
+    private url;
+    constructor(url: string);
+    initialize(): Promise<void>;
+    private getPool;
+    lookup(params: LookupParams): Promise<string | null>;
+    insert(params: InsertParams): Promise<void>;
+    lookupPlural(params: LookupParams): Promise<Record<string, string>>;
+    insertPlural(params: InsertPluralParams): Promise<void>;
+    stats(): Promise<{
+        totalTranslations: number;
+        totalFailed: number;
+        byLanguage: Record<string, number>;
+    }>;
+    close(): Promise<void>;
+}