transduck 0.0.4 → 0.1.1

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.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Source code scanner for TransDuck ait() and ait_plural()/aitPlural() calls.
+ */
+export interface ScanEntry {
+    text?: string;
+    context?: string | null;
+    plural?: true;
+    one?: string;
+    other?: string;
+    line?: number;
+    files?: string[];
+}
+/**
+ * Extract translatable strings from file content.
+ */
+export declare function extractStrings(content: string, filename: string): ScanEntry[];
+/**
+ * Walk directories and extract all translatable strings.
+ * Returns deduplicated list of entries with 'files' field listing all locations.
+ */
+export declare function scanDirectory(dirs: string[]): ScanEntry[];

package/dist/scanner.js

@@ -0,0 +1,180 @@
+/**
+ * Source code scanner for TransDuck ait() and ait_plural()/aitPlural() calls.
+ */
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join, extname } from 'path';
+// --- Regex patterns ---
+// ait("text") or ait("text", context="ctx") — Python/template keyword style
+const AIT_KEYWORD_CTX = /ait\s*\(\s*(['"])(.*?)\1(?:\s*,\s*context\s*=\s*(['"])(.*?)\3)?/g;
+// ait("text") or ait("text", "ctx") — JS positional style
+const AIT_POSITIONAL_CTX = /ait\s*\(\s*(['"])(.*?)\1(?:\s*,\s*(['"])(.*?)\3)?/g;
+// ait_plural("one", "other") or aitPlural("one", "other")
+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
+const TEMPLATE_EXTENSIONS = new Set(['.html', '.jinja', '.jinja2']);
+// Supported file extensions for scanning
+const SCAN_EXTENSIONS = new Set(['.py', '.js', '.ts', '.tsx', '.jsx', '.html', '.jinja', '.jinja2']);
+// Directories to skip
+const SKIP_DIRS = new Set(['node_modules', '.venv', 'venv', '__pycache__', '.git', 'dist', 'build', '.next']);
+function shouldSkipDir(dirname) {
+    if (SKIP_DIRS.has(dirname))
+        return true;
+    if (dirname.includes('egg-info'))
+        return true;
+    return false;
+}
+/**
+ * Extract translatable strings from file content.
+ */
+export function extractStrings(content, filename) {
+    const results = [];
+    const ext = extname(filename).toLowerCase();
+    const isJs = JS_EXTENSIONS.has(ext);
+    const isTemplate = TEMPLATE_EXTENSIONS.has(ext);
+    // Track positions of plural matches so we don't double-match them as ait()
+    const pluralSpans = [];
+    // 1. Find all plural calls
+    const pluralRegex = new RegExp(AIT_PLURAL.source, 'g');
+    let match;
+    while ((match = pluralRegex.exec(content)) !== null) {
+        const one = match[2];
+        const other = match[4];
+        const lineNum = content.slice(0, match.index).split('\n').length;
+        results.push({
+            plural: true,
+            one,
+            other,
+            context: null,
+            line: lineNum,
+        });
+        pluralSpans.push([match.index, match.index + match[0].length]);
+    }
+    // 2. Find Django template tags (only in template files)
+    if (isTemplate) {
+        const djangoRegex = new RegExp(DJANGO_TAG.source, 'g');
+        while ((match = djangoRegex.exec(content)) !== null) {
+            const text = match[2];
+            const context = match[4] || null;
+            const lineNum = content.slice(0, match.index).split('\n').length;
+            results.push({ text, context, line: lineNum });
+        }
+    }
+    // 3. Find ait() calls
+    const pattern = isJs ? AIT_POSITIONAL_CTX : AIT_KEYWORD_CTX;
+    const aitRegex = new RegExp(pattern.source, 'g');
+    while ((match = aitRegex.exec(content)) !== null) {
+        // Skip if this is part of a plural match
+        const pos = match.index;
+        if (pluralSpans.some(([start, end]) => pos >= start && pos < end)) {
+            continue;
+        }
+        // Check that this is specifically "ait(" not "ait_plural(" or "aitPlural("
+        const prefixStart = Math.max(0, pos - 10);
+        const prefix = content.slice(prefixStart, pos + 4);
+        if (prefix.toLowerCase().includes('plural') || prefix.includes('Plural')) {
+            continue;
+        }
+        const text = match[2];
+        const context = match[4] || null;
+        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;
+}
+/**
+ * Walk directories and extract all translatable strings.
+ * Returns deduplicated list of entries with 'files' field listing all locations.
+ */
+export function scanDirectory(dirs) {
+    const rawMatches = new Map();
+    for (const scanDir of dirs) {
+        walkDir(scanDir, rawMatches);
+    }
+    return Array.from(rawMatches.values());
+}
+function walkDir(dir, rawMatches) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        const fullPath = join(dir, name);
+        let stat;
+        try {
+            stat = statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            if (!shouldSkipDir(name)) {
+                walkDir(fullPath, rawMatches);
+            }
+        }
+        else if (stat.isFile()) {
+            const ext = extname(name).toLowerCase();
+            if (!SCAN_EXTENSIONS.has(ext))
+                continue;
+            let content;
+            try {
+                content = readFileSync(fullPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const entries = extractStrings(content, name);
+            for (const entry of entries) {
+                // Build dedup key
+                let key;
+                if (entry.plural) {
+                    key = `plural:${entry.one}\x00${entry.other}\x00${entry.context ?? ''}`;
+                }
+                else {
+                    key = `text:${entry.text}\x00${entry.context ?? ''}`;
+                }
+                const fileLoc = `${fullPath}:${entry.line}`;
+                if (rawMatches.has(key)) {
+                    rawMatches.get(key).files.push(fileLoc);
+                }
+                else {
+                    const resultEntry = { ...entry, files: [fileLoc] };
+                    delete resultEntry.line;
+                    rawMatches.set(key, resultEntry);
+                }
+            }
+        }
+    }
+}

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "transduck",
-  "version": "0.0.4",
+  "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';
@@ -10,6 +10,7 @@ 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';
+import { scanDirectory, type ScanEntry } from './scanner.js';
 
 function hash(text: string): string {
   return createHash('sha256').update(text).digest('hex');
@@ -336,6 +337,161 @@ export async function runWarm(opts: WarmOptions): Promise<string> {
   return `Translated: ${translated} | Skipped: ${skipped} | Failed: ${failed}`;
 }
 
+export interface ScanOptions {
+  dirs: string[];
+  warm?: boolean;
+  langs?: string[];
+  outputPath?: string;
+  configPath?: string;
+}
+
+export async function runScan(opts: ScanOptions): Promise<string> {
+  const cfg = loadConfig(opts.configPath);
+  const scanDirs = opts.dirs.length > 0 ? opts.dirs : [process.cwd()];
+  const entries = scanDirectory(scanDirs);
+
+  const regular = entries.filter(e => !e.plural);
+  const plurals = entries.filter(e => e.plural);
+
+  // Count scanned files
+  const allFiles = new Set<string>();
+  for (const e of entries) {
+    for (const f of (e.files ?? [])) {
+      allFiles.add(f);
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push(`Scanned files with matches: ${allFiles.size}`);
+  lines.push(`Found ${entries.length} strings (${regular.length} regular, ${plurals.length} plural)`);
+  lines.push('');
+
+  for (const e of entries) {
+    const locations = (e.files ?? []).join(', ');
+    if (e.plural) {
+      lines.push(`  ait_plural("${e.one}", "${e.other}")  ${locations}`);
+    } else {
+      const ctx = e.context ? `, context="${e.context}"` : '';
+      lines.push(`  ait("${e.text}"${ctx})  ${locations}`);
+    }
+  }
+
+  // Output to JSON
+  if (opts.outputPath) {
+    const outputEntries = entries.map(e => {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(e)) {
+        if (k !== 'files') out[k] = v;
+      }
+      return out;
+    });
+    writeFileSync(opts.outputPath, JSON.stringify(outputEntries, null, 2));
+    lines.push(`\nWrote ${entries.length} entries to ${opts.outputPath}`);
+  }
+
+  // Warm
+  if (opts.warm) {
+    const targetLangs = opts.langs && opts.langs.length > 0
+      ? opts.langs.map(l => l.toUpperCase())
+      : cfg.targetLangs;
+
+    const store = new TranslationStore(cfg.storagePath);
+    await store.initialize();
+    const apiKey = process.env[cfg.apiKeyEnv];
+    const projectContextHash = hash(cfg.projectContext);
+
+    let translated = 0;
+    let skipped = 0;
+    let failed = 0;
+
+    for (const entry of entries) {
+      if (entry.plural) {
+        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,
+            });
+
+            for (const [cat, translatedText] of Object.entries(forms)) {
+              await store.insertPlural({
+                sourceText: sourceKey, sourceLang: cfg.sourceLang, targetLang: lang,
+                projectContextHash, stringContextHash,
+                pluralCategory: cat, translatedText: translatedText as string,
+                model: cfg.backendModel, status: 'translated',
+              });
+            }
+            translated++;
+          } catch {
+            failed++;
+          }
+        }
+      } else {
+        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 {
+              failed++;
+            }
+          } catch {
+            failed++;
+          }
+        }
+      }
+    }
+
+    store.close();
+    lines.push(`\nTranslated: ${translated} | Skipped: ${skipped} | Failed: ${failed}`);
+  }
+
+  if (!opts.warm && !opts.outputPath) {
+    lines.push(`\nRun 'transduck scan --warm --langs DE,ES' to translate all strings.`);
+  }
+
+  return lines.join('\n');
+}
+
 export interface StatsOptions {
   configPath?: string;
 }
@@ -384,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')
@@ -441,6 +616,24 @@ program.command('stats')
     console.log(output);
   });
 
+program.command('scan')
+  .description('Scan source code for translatable strings')
+  .option('--dir <path...>', 'Directories to scan (repeatable)')
+  .option('--warm', 'Translate all found strings')
+  .option('--langs <langs>', 'Comma-separated target languages (for --warm)')
+  .option('--output <path>', 'Write found strings to JSON')
+  .option('--config <path>', 'Path to transduck.yaml')
+  .action(async (opts: { dir?: string[]; warm?: boolean; langs?: string; output?: string; config?: string }) => {
+    const output = await runScan({
+      dirs: opts.dir ?? [],
+      warm: opts.warm ?? false,
+      langs: opts.langs ? opts.langs.split(',').map(s => s.trim()) : undefined,
+      outputPath: opts.output,
+      configPath: opts.config,
+    });
+    console.log(output);
+  });
+
 export { program };
 
 // Run CLI when executed directly (not when imported by tests or other modules)