transduck 0.0.1

package/dist/backend.d.ts

@@ -0,0 +1,40 @@
+interface BuildMessagesParams {
+    sourceText: string;
+    sourceLang: string;
+    targetLang: string;
+    projectContext: string;
+    stringContext: string | null;
+}
+interface TranslateParams extends BuildMessagesParams {
+    apiKey: string;
+    model: string;
+    timeout: number;
+    maxRetries: number;
+    _clientOverride?: any;
+}
+interface BuildPluralMessagesParams {
+    one: string;
+    other: string;
+    sourceLang: string;
+    targetLang: string;
+    projectContext: string;
+    stringContext: string | null;
+}
+interface TranslatePluralParams extends BuildPluralMessagesParams {
+    apiKey: string;
+    model: string;
+    timeout: number;
+    maxRetries: number;
+    _clientOverride?: any;
+}
+export declare function buildMessages(params: BuildMessagesParams): Array<{
+    role: string;
+    content: string;
+}>;
+export declare function translate(params: TranslateParams): Promise<string>;
+export declare function buildPluralMessages(params: BuildPluralMessagesParams): Array<{
+    role: string;
+    content: string;
+}>;
+export declare function translatePlural(params: TranslatePluralParams): Promise<Record<string, string>>;
+export {};

package/dist/backend.js

@@ -0,0 +1,85 @@
+import OpenAI from 'openai';
+/* eslint-disable no-template-curly-in-string */
+const SYSTEM_TEMPLATE = 'You are a professional translator. Translate the given text from {source_lang} ' +
+    'to {target_lang}. Return ONLY the translated text, nothing else. Preserve any ' +
+    'placeholders like {name}, {{count}}, %s, ${value} exactly as they appear. ' +
+    'Preserve brand names. Match the tone and formality of the original.\n\n' +
+    'Project context: {project_context}';
+const USER_TEMPLATE = `Translate: "{source_text}"\nString context: {string_context}`;
+const PLURAL_SYSTEM_TEMPLATE = 'You are a professional translator. You will be given two plural forms ' +
+    '(one and other) in {source_lang}. Generate ALL plural forms needed in ' +
+    '{target_lang} according to CLDR plural rules. Return ONLY a JSON object ' +
+    'mapping plural categories to translated strings. Do not include explanation.\n\n' +
+    'Preserve any placeholders like {name}, {count}, %s, ${value} exactly as ' +
+    'they appear. Preserve brand names. Match the tone and formality of the original.\n\n' +
+    'CLDR plural categories are: zero, one, two, few, many, other.\n' +
+    'Only include categories that {target_lang} actually uses.\n\n' +
+    'Project context: {project_context}';
+const PLURAL_USER_TEMPLATE = 'Source one form: "{one}"\n' +
+    'Source other form: "{other}"\n' +
+    'String context: {string_context}';
+function safeRender(template, vars) {
+    let result = template;
+    for (const [key, value] of Object.entries(vars)) {
+        result = result.replaceAll(`{${key}}`, value);
+    }
+    return result;
+}
+export function buildMessages(params) {
+    const systemMsg = SYSTEM_TEMPLATE
+        .replace('{source_lang}', params.sourceLang)
+        .replace('{target_lang}', params.targetLang)
+        .replace('{project_context}', params.projectContext);
+    const userMsg = USER_TEMPLATE
+        .replace('{source_text}', params.sourceText)
+        .replace('{string_context}', params.stringContext || 'none');
+    return [
+        { role: 'system', content: systemMsg },
+        { role: 'user', content: userMsg },
+    ];
+}
+export async function translate(params) {
+    const client = params._clientOverride ?? new OpenAI({
+        apiKey: params.apiKey,
+        timeout: params.timeout * 1000,
+        maxRetries: params.maxRetries,
+    });
+    const messages = buildMessages(params);
+    const response = await client.chat.completions.create({
+        model: params.model,
+        messages,
+        temperature: 0.3,
+    });
+    return response.choices[0].message.content.trim();
+}
+export function buildPluralMessages(params) {
+    const systemMsg = safeRender(PLURAL_SYSTEM_TEMPLATE, {
+        source_lang: params.sourceLang,
+        target_lang: params.targetLang,
+        project_context: params.projectContext,
+    });
+    const userMsg = safeRender(PLURAL_USER_TEMPLATE, {
+        one: params.one,
+        other: params.other,
+        string_context: params.stringContext || 'none',
+    });
+    return [
+        { role: 'system', content: systemMsg },
+        { role: 'user', content: userMsg },
+    ];
+}
+export async function translatePlural(params) {
+    const client = params._clientOverride ?? new OpenAI({
+        apiKey: params.apiKey,
+        timeout: params.timeout * 1000,
+        maxRetries: params.maxRetries,
+    });
+    const messages = buildPluralMessages(params);
+    const response = await client.chat.completions.create({
+        model: params.model,
+        messages,
+        temperature: 0.3,
+    });
+    const raw = response.choices[0].message.content.trim();
+    return JSON.parse(raw);
+}

package/dist/cli.d.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export interface InitOptions {
+    dir: string;
+    name: string;
+    context: string;
+    sourceLang: string;
+    targetLangs: string[];
+}
+export declare function runInit(opts: InitOptions): Promise<string>;
+export interface TranslateOptions {
+    text: string;
+    targetLang: string;
+    stringContext?: string;
+    configPath?: string;
+    vars?: Record<string, string | number>;
+}
+export declare function runTranslate(opts: TranslateOptions): Promise<string>;
+export interface TranslatePluralOptions {
+    one: string;
+    other: string;
+    count: number;
+    targetLang: string;
+    stringContext?: string;
+    configPath?: string;
+}
+export declare function runTranslatePlural(opts: TranslatePluralOptions): Promise<string>;
+export interface WarmOptions {
+    filePath: string;
+    langs: string[];
+    configPath?: string;
+}
+export declare function runWarm(opts: WarmOptions): Promise<string>;
+export interface StatsOptions {
+    configPath?: string;
+}
+export declare function runStats(opts: StatsOptions): Promise<string>;
+declare const program: Command;
+export { program };

package/dist/cli.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { Command } from 'commander';
+import { stringify as yamlStringify } from 'yaml';
+import { loadConfig } from './config.js';
+import { TranslationStore } from './storage.js';
+import { translate as backendTranslate, translatePlural as backendTranslatePlural } from './backend.js';
+import { validateTranslation, extractPlaceholders } from './validation.js';
+import { getPluralCategory, interpolateVars } from './plural.js';
+function hash(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+export async function runInit(opts) {
+    const config = {
+        project: { name: opts.name, context: opts.context },
+        languages: { source: opts.sourceLang.toUpperCase(), targets: opts.targetLangs.map(l => l.toUpperCase()) },
+        storage: { path: './translations.duckdb' },
+        backend: { api_key_env: 'OPENAI_API_KEY', model: 'gpt-4.1-mini', timeout_seconds: 10, max_retries: 2 },
+    };
+    const configPath = join(opts.dir, 'transduck.yaml');
+    writeFileSync(configPath, yamlStringify(config));
+    const dbPath = join(opts.dir, 'translations.duckdb');
+    const store = new TranslationStore(dbPath);
+    await store.initialize();
+    store.close();
+    return `Created ${configPath}\nCreated ${dbPath}`;
+}
+export async function runTranslate(opts) {
+    const cfg = loadConfig(opts.configPath);
+    const targetLang = opts.targetLang.toUpperCase();
+    const store = new TranslationStore(cfg.storagePath);
+    await store.initialize();
+    const projectContextHash = hash(cfg.projectContext);
+    const stringContextHash = hash(opts.stringContext ?? '');
+    const cached = await store.lookup({
+        sourceText: opts.text, sourceLang: cfg.sourceLang, targetLang,
+        projectContextHash, stringContextHash,
+    });
+    if (cached !== null) {
+        store.close();
+        return `[cached] ${interpolateVars(cached, opts.vars)}`;
+    }
+    const apiKey = process.env[cfg.apiKeyEnv];
+    const translated = await backendTranslate({
+        sourceText: opts.text, sourceLang: cfg.sourceLang, targetLang,
+        projectContext: cfg.projectContext, stringContext: opts.stringContext ?? null,
+        apiKey: apiKey, model: cfg.backendModel,
+        timeout: cfg.backendTimeout, maxRetries: cfg.backendMaxRetries,
+    });
+    if (!validateTranslation(opts.text, translated)) {
+        await store.insert({
+            sourceText: opts.text, sourceLang: cfg.sourceLang, targetLang,
+            projectContextHash, stringContextHash,
+            translatedText: translated, model: cfg.backendModel, status: 'failed',
+        });
+        store.close();
+        return `[failed] Validation failed: ${translated}`;
+    }
+    await store.insert({
+        sourceText: opts.text, sourceLang: cfg.sourceLang, targetLang,
+        projectContextHash, stringContextHash,
+        translatedText: translated, model: cfg.backendModel, status: 'translated',
+    });
+    store.close();
+    return `[new] ${interpolateVars(translated, opts.vars)}`;
+}
+export async function runTranslatePlural(opts) {
+    const cfg = loadConfig(opts.configPath);
+    const targetLang = opts.targetLang.toUpperCase();
+    const store = new TranslationStore(cfg.storagePath);
+    await store.initialize();
+    const projectContextHash = hash(cfg.projectContext);
+    const stringContextHash = hash(opts.stringContext ?? '');
+    // Auto-include {count} in vars
+    const countVal = Number.isInteger(opts.count) ? opts.count : opts.count;
+    const varsDict = { count: countVal };
+    // Build cache key
+    const sourceKey = opts.one + '\x00' + opts.other;
+    // Determine needed plural category for target language
+    const neededCategory = getPluralCategory(targetLang, opts.count);
+    // Check cache
+    const cachedForms = await store.lookupPlural({
+        sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang,
+        projectContextHash, stringContextHash,
+    });
+    if (neededCategory in cachedForms) {
+        const result = interpolateVars(cachedForms[neededCategory], varsDict);
+        store.close();
+        return `[cached] ${result}`;
+    }
+    // Cache miss — call backend
+    try {
+        const apiKey = process.env[cfg.apiKeyEnv];
+        const forms = await backendTranslatePlural({
+            one: opts.one, other: opts.other,
+            sourceLang: cfg.sourceLang, targetLang,
+            projectContext: cfg.projectContext, stringContext: opts.stringContext ?? null,
+            apiKey: apiKey, model: cfg.backendModel,
+            timeout: cfg.backendTimeout, maxRetries: cfg.backendMaxRetries,
+        });
+        // Validate each form
+        const sourcePlaceholders = new Set([
+            ...extractPlaceholders(opts.one),
+            ...extractPlaceholders(opts.other),
+        ]);
+        const validCategories = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+        let allValid = true;
+        for (const [cat, translatedText] of Object.entries(forms)) {
+            if (!validCategories.has(cat)) {
+                allValid = false;
+                break;
+            }
+            if (!translatedText || !translatedText.trim()) {
+                allValid = false;
+                break;
+            }
+            if (sourcePlaceholders.size > 0) {
+                const translatedPhs = extractPlaceholders(translatedText);
+                for (const p of sourcePlaceholders) {
+                    if (!translatedPhs.has(p)) {
+                        allValid = false;
+                        break;
+                    }
+                }
+                if (!allValid)
+                    break;
+            }
+        }
+        if (!allValid || !('other' in forms)) {
+            // Store as failed, fall back to source
+            for (const [cat, translatedText] of Object.entries(forms)) {
+                await store.insertPlural({
+                    sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang,
+                    projectContextHash, stringContextHash,
+                    pluralCategory: cat, translatedText,
+                    model: cfg.backendModel, status: 'failed',
+                });
+            }
+            const sourceCategory = getPluralCategory(cfg.sourceLang, opts.count);
+            const fallback = sourceCategory === 'other' ? opts.other : opts.one;
+            const result = interpolateVars(fallback, varsDict);
+            store.close();
+            return `[failed] ${result}`;
+        }
+        // Store all forms
+        for (const [cat, translatedText] of Object.entries(forms)) {
+            await store.insertPlural({
+                sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang,
+                projectContextHash, stringContextHash,
+                pluralCategory: cat, translatedText,
+                model: cfg.backendModel, status: 'translated',
+            });
+        }
+        // Select the right form
+        const selected = forms[neededCategory] ?? forms['other'];
+        const result = interpolateVars(selected, varsDict);
+        store.close();
+        return `[new] ${result}`;
+    }
+    catch {
+        const sourceCategory = getPluralCategory(cfg.sourceLang, opts.count);
+        const fallback = sourceCategory === 'other' ? opts.other : opts.one;
+        const result = interpolateVars(fallback, varsDict);
+        store.close();
+        return `[failed] ${result}`;
+    }
+}
+export async function runWarm(opts) {
+    const cfg = loadConfig(opts.configPath);
+    const targetLangs = opts.langs.map(l => l.toUpperCase());
+    const store = new TranslationStore(cfg.storagePath);
+    await store.initialize();
+    const content = readFileSync(opts.filePath, 'utf-8');
+    let entries;
+    if (opts.filePath.endsWith('.json')) {
+        entries = JSON.parse(content);
+    }
+    else {
+        entries = content.split('\n').filter(l => l.trim()).map(text => ({ text: text.trim() }));
+    }
+    const apiKey = process.env[cfg.apiKeyEnv];
+    const projectContextHash = hash(cfg.projectContext);
+    let translated = 0, skipped = 0, failed = 0;
+    for (const entry of entries) {
+        if (entry.plural) {
+            // Plural entry
+            const sourceKey = entry.one + '\x00' + entry.other;
+            const stringContextHash = hash(entry.context ?? '');
+            for (const lang of targetLangs) {
+                const cachedForms = await store.lookupPlural({
+                    sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
+                    projectContextHash, stringContextHash,
+                });
+                if (Object.keys(cachedForms).length > 0) {
+                    skipped++;
+                    continue;
+                }
+                try {
+                    const forms = await backendTranslatePlural({
+                        one: entry.one, other: entry.other,
+                        sourceLang: cfg.sourceLang, targetLang: lang,
+                        projectContext: cfg.projectContext, stringContext: entry.context ?? null,
+                        apiKey: apiKey, model: cfg.backendModel,
+                        timeout: cfg.backendTimeout, maxRetries: cfg.backendMaxRetries,
+                    });
+                    const sourcePlaceholders = new Set([
+                        ...extractPlaceholders(entry.one),
+                        ...extractPlaceholders(entry.other),
+                    ]);
+                    const validCategories = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+                    let anyStored = false;
+                    for (const [cat, translatedText] of Object.entries(forms)) {
+                        if (!validCategories.has(cat) || !translatedText)
+                            continue;
+                        const translatedPhs = extractPlaceholders(translatedText);
+                        let allPresent = true;
+                        for (const p of sourcePlaceholders) {
+                            if (!translatedPhs.has(p)) {
+                                allPresent = false;
+                                break;
+                            }
+                        }
+                        await store.insertPlural({
+                            sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
+                            projectContextHash, stringContextHash,
+                            pluralCategory: cat, translatedText: translatedText,
+                            model: cfg.backendModel, status: allPresent ? 'translated' : 'failed',
+                        });
+                        anyStored = true;
+                    }
+                    if (anyStored)
+                        translated++;
+                    else
+                        failed++;
+                }
+                catch {
+                    failed++;
+                }
+            }
+        }
+        else {
+            // Regular entry
+            const stringContextHash = hash(entry.context ?? '');
+            for (const lang of targetLangs) {
+                const cached = await store.lookup({
+                    sourceText: entry.text, sourceLang: cfg.sourceLang, targetLang: lang,
+                    projectContextHash, stringContextHash,
+                });
+                if (cached !== null) {
+                    skipped++;
+                    continue;
+                }
+                try {
+                    const result = await backendTranslate({
+                        sourceText: entry.text, sourceLang: cfg.sourceLang, targetLang: lang,
+                        projectContext: cfg.projectContext, stringContext: entry.context ?? null,
+                        apiKey: apiKey, model: cfg.backendModel,
+                        timeout: cfg.backendTimeout, maxRetries: cfg.backendMaxRetries,
+                    });
+                    if (validateTranslation(entry.text, result)) {
+                        await store.insert({
+                            sourceText: entry.text, sourceLang: cfg.sourceLang, targetLang: lang,
+                            projectContextHash, stringContextHash,
+                            translatedText: result, model: cfg.backendModel, status: 'translated',
+                        });
+                        translated++;
+                    }
+                    else {
+                        await store.insert({
+                            sourceText: entry.text, sourceLang: cfg.sourceLang, targetLang: lang,
+                            projectContextHash, stringContextHash,
+                            translatedText: result, model: cfg.backendModel, status: 'failed',
+                        });
+                        failed++;
+                    }
+                }
+                catch {
+                    failed++;
+                }
+            }
+        }
+    }
+    store.close();
+    return `Translated: ${translated} | Skipped: ${skipped} | Failed: ${failed}`;
+}
+export async function runStats(opts) {
+    const cfg = loadConfig(opts.configPath);
+    const store = new TranslationStore(cfg.storagePath);
+    await store.initialize();
+    const st = await store.stats();
+    const lines = [
+        `Total translations: ${st.totalTranslations}`,
+        `Failed translations: ${st.totalFailed}`,
+    ];
+    if (Object.keys(st.byLanguage).length > 0) {
+        lines.push('By language:');
+        for (const [lang, count] of Object.entries(st.byLanguage).sort()) {
+            lines.push(`  ${lang}: ${count}`);
+        }
+    }
+    store.close();
+    return lines.join('\n');
+}
+// CLI entry point
+const program = new Command();
+program.name('transduck').description('AI-native translation tool').version('0.1.0');
+program.command('init')
+    .description('Initialize a new transduck project')
+    .action(async () => {
+    const readline = await import('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+    const dir = await ask('Project directory: ');
+    const name = await ask('Project name: ');
+    const context = await ask('Project context: ');
+    const sourceLang = await ask('Source language (e.g. EN): ');
+    const targetsRaw = await ask('Target languages (comma-separated): ');
+    rl.close();
+    const output = await runInit({
+        dir, name, context, sourceLang,
+        targetLangs: targetsRaw.split(',').map(s => s.trim()),
+    });
+    console.log(output);
+});
+program.command('translate')
+    .description('Translate a single string')
+    .argument('<text>', 'Source text to translate')
+    .requiredOption('--to <lang>', 'Target language code')
+    .option('--context <context>', 'String context')
+    .option('--config <path>', 'Path to transduck.yaml')
+    .option('--vars <json>', 'JSON vars for interpolation')
+    .action(async (text, opts) => {
+    const varsDict = opts.vars ? JSON.parse(opts.vars) : undefined;
+    const output = await runTranslate({
+        text, targetLang: opts.to, stringContext: opts.context,
+        configPath: opts.config, vars: varsDict,
+    });
+    console.log(output);
+});
+program.command('translate-plural')
+    .description('Translate a plural string')
+    .requiredOption('--one <text>', 'Singular form')
+    .requiredOption('--other <text>', 'Plural form')
+    .requiredOption('--count <number>', 'Count value', parseFloat)
+    .requiredOption('--to <lang>', 'Target language code')
+    .option('--context <context>', 'String context')
+    .option('--config <path>', 'Path to transduck.yaml')
+    .action(async (opts) => {
+    const output = await runTranslatePlural({
+        one: opts.one, other: opts.other, count: opts.count,
+        targetLang: opts.to, stringContext: opts.context,
+        configPath: opts.config,
+    });
+    console.log(output);
+});
+program.command('warm')
+    .description('Pre-generate translations from a file')
+    .requiredOption('--file <path>', 'JSON or text file with strings')
+    .requiredOption('--langs <langs>', 'Comma-separated target languages')
+    .option('--config <path>', 'Path to transduck.yaml')
+    .action(async (opts) => {
+    const output = await runWarm({
+        filePath: opts.file,
+        langs: opts.langs.split(',').map(s => s.trim()),
+        configPath: opts.config,
+    });
+    console.log(output);
+});
+program.command('stats')
+    .description('Show translation database statistics')
+    .option('--config <path>', 'Path to transduck.yaml')
+    .action(async (opts) => {
+    const output = await runStats({ configPath: opts.config ?? '' });
+    console.log(output);
+});
+export { program };
+// Only run if this is the entry point
+const isMain = process.argv[1]?.endsWith('cli.js') || process.argv[1]?.endsWith('cli.ts');
+if (isMain) {
+    program.parse();
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export interface TransduckConfig {
+    projectName: string;
+    projectContext: string;
+    sourceLang: string;
+    targetLangs: string[];
+    storagePath: string;
+    apiKeyEnv: string;
+    backendModel: string;
+    backendTimeout: number;
+    backendMaxRetries: number;
+}
+export declare function loadConfig(path?: string): TransduckConfig;

package/dist/config.js

@@ -0,0 +1,43 @@
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { parse as parseYaml } from 'yaml';
+const CONFIG_FILENAME = 'transduck.yaml';
+function findConfig() {
+    const envPath = process.env.TRANSDUCK_CONFIG;
+    if (envPath) {
+        if (existsSync(envPath))
+            return resolve(envPath);
+        throw new Error(`TRANSDUCK_CONFIG points to ${envPath} which does not exist`);
+    }
+    let current = process.cwd();
+    while (true) {
+        const candidate = join(current, CONFIG_FILENAME);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new Error(`Could not find ${CONFIG_FILENAME}. Run 'transduck init' or set TRANSDUCK_CONFIG.`);
+}
+export function loadConfig(path) {
+    const configPath = path ? resolve(path) : findConfig();
+    if (!existsSync(configPath)) {
+        throw new Error(`Config file not found: ${configPath}`);
+    }
+    const raw = parseYaml(readFileSync(configPath, 'utf-8'));
+    const configDir = dirname(configPath);
+    const storagePath = resolve(configDir, raw.storage.path);
+    return {
+        projectName: raw.project.name,
+        projectContext: raw.project.context,
+        sourceLang: String(raw.languages.source).toUpperCase(),
+        targetLangs: raw.languages.targets.map((l) => String(l).toUpperCase()),
+        storagePath,
+        apiKeyEnv: raw.backend.api_key_env,
+        backendModel: raw.backend.model,
+        backendTimeout: raw.backend.timeout_seconds,
+        backendMaxRetries: raw.backend.max_retries,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { type TransduckConfig } from './config.js';
+import { TranslationStore } from './storage.js';
+export declare function initialize(config?: TransduckConfig): Promise<void>;
+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 declare function aitPlural(one: string, other: string, count: number, opts?: {
+    context?: string;
+    vars?: Record<string, string | number>;
+}): Promise<string>;