transduck 0.0.4 → 0.0.5

package/dist/cli.d.ts

@@ -31,6 +31,14 @@ export interface WarmOptions {
     configPath?: string;
 }
 export declare function runWarm(opts: WarmOptions): Promise<string>;
+export interface ScanOptions {
+    dirs: string[];
+    warm?: boolean;
+    langs?: string[];
+    outputPath?: string;
+    configPath?: string;
+}
+export declare function runScan(opts: ScanOptions): Promise<string>;
 export interface StatsOptions {
     configPath?: string;
 }

package/dist/cli.js

@@ -9,6 +9,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 } from './scanner.js';
 function hash(text) {
     return createHash('sha256').update(text).digest('hex');
 }
@@ -285,6 +286,138 @@ export async function runWarm(opts) {
     store.close();
     return `Translated: ${translated} | Skipped: ${skipped} | Failed: ${failed}`;
 }
+export async function runScan(opts) {
+    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();
+    for (const e of entries) {
+        for (const f of (e.files ?? [])) {
+            allFiles.add(f);
+        }
+    }
+    const lines = [];
+    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 = {};
+            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,
+                                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 async function runStats(opts) {
     const cfg = loadConfig(opts.configPath);
     const store = new TranslationStore(cfg.storagePath);
@@ -375,6 +508,23 @@ program.command('stats')
     const output = await runStats({ configPath: opts.config ?? '' });
     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) => {
+    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)
 if (typeof process !== 'undefined' && process.argv[1]) {

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,154 @@
+/**
+ * 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;
+// 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 });
+    }
+    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,6 +1,6 @@
 {
   "name": "transduck",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "AI-native translation tool using source text as keys",
   "type": "module",
   "main": "./dist/index.js",

package/src/cli.ts

@@ -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;
 }
@@ -441,6 +597,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)

package/src/scanner.ts

@@ -0,0 +1,186 @@
+/**
+ * Source code scanner for TransDuck ait() and ait_plural()/aitPlural() calls.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+// --- Types ---
+
+export interface ScanEntry {
+  text?: string;
+  context?: string | null;
+  plural?: true;
+  one?: string;
+  other?: string;
+  line?: number;
+  files?: string[];
+}
+
+// --- 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;
+
+// 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: string): boolean {
+  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: string, filename: string): ScanEntry[] {
+  const results: ScanEntry[] = [];
+  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: Array<[number, number]> = [];
+
+  // 1. Find all plural calls
+  const pluralRegex = new RegExp(AIT_PLURAL.source, 'g');
+  let match: RegExpExecArray | null;
+  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 });
+  }
+
+  return results;
+}
+
+/**
+ * Walk directories and extract all translatable strings.
+ * Returns deduplicated list of entries with 'files' field listing all locations.
+ */
+export function scanDirectory(dirs: string[]): ScanEntry[] {
+  const rawMatches = new Map<string, ScanEntry>();
+
+  for (const scanDir of dirs) {
+    walkDir(scanDir, rawMatches);
+  }
+
+  return Array.from(rawMatches.values());
+}
+
+function walkDir(dir: string, rawMatches: Map<string, ScanEntry>): void {
+  let entries: string[];
+  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: string;
+      try {
+        content = readFileSync(fullPath, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      const entries = extractStrings(content, name);
+      for (const entry of entries) {
+        // Build dedup key
+        let key: string;
+        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: ScanEntry = { ...entry, files: [fileLoc] };
+          delete resultEntry.line;
+          rawMatches.set(key, resultEntry);
+        }
+      }
+    }
+  }
+}

package/tests/cli.test.ts

@@ -1,11 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { writeFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { mkdtempSync } from 'fs';
 import { tmpdir } from 'os';
 import { createHash } from 'crypto';
 
-import { runInit, runStats, runTranslate, runTranslatePlural, runWarm } from '../src/cli.js';
+import { runInit, runStats, runTranslate, runTranslatePlural, runWarm, runScan } from '../src/cli.js';
 import { TranslationStore } from '../src/storage.js';
 
 function hash(text: string): string {
@@ -159,4 +159,65 @@ describe('CLI functions', () => {
     // Since plural forms already exist, should be skipped
     expect(output).toContain('Skipped: 1');
   });
+
+  // --- scan ---
+
+  it('scan finds strings', async () => {
+    const configPath = writeConfig(tmpDir);
+    // Create source files to scan
+    const srcDir = join(tmpDir, 'src');
+    mkdirSync(srcDir);
+    writeFileSync(join(srcDir, 'app.py'), 'from transduck import ait\nait("Hello")\nait("World", context="greeting")\n');
+    const output = await runScan({
+      dirs: [srcDir],
+      configPath,
+    });
+    expect(output).toContain('Hello');
+    expect(output).toContain('World');
+    expect(output).toContain('2');
+  });
+
+  it('scan output JSON', async () => {
+    const configPath = writeConfig(tmpDir);
+    const srcDir = join(tmpDir, 'src');
+    mkdirSync(srcDir);
+    writeFileSync(join(srcDir, 'app.py'), 'ait("Hello")\n');
+    const outputFile = join(tmpDir, 'strings.json');
+    const output = await runScan({
+      dirs: [srcDir],
+      outputPath: outputFile,
+      configPath,
+    });
+    expect(output).toContain('Wrote');
+    expect(existsSync(outputFile)).toBe(true);
+    const data = JSON.parse(readFileSync(outputFile, 'utf-8'));
+    expect(data).toHaveLength(1);
+    expect(data[0].text).toBe('Hello');
+  });
+
+  it('scan with warm', async () => {
+    const configPath = writeConfig(tmpDir);
+    const srcDir = join(tmpDir, 'src');
+    mkdirSync(srcDir);
+    writeFileSync(join(srcDir, 'app.py'), 'ait("Hello")\n');
+
+    // Pre-populate the DB so warm skips
+    const dbPath = join(tmpDir, 'translations.duckdb');
+    const store = new TranslationStore(dbPath);
+    await store.initialize();
+    await store.insert({
+      sourceText: 'Hello', sourceLang: 'EN', targetLang: 'DE',
+      projectContextHash: hash('A test site'), stringContextHash: hash(''),
+      translatedText: 'Hallo', model: 'gpt-4.1-mini', status: 'translated',
+    });
+    store.close();
+
+    const output = await runScan({
+      dirs: [srcDir],
+      warm: true,
+      langs: ['DE'],
+      configPath,
+    });
+    expect(output).toContain('Skipped: 1');
+  });
 });

package/tests/scanner.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from 'vitest';
+import { writeFileSync, mkdirSync, mkdtempSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { extractStrings, scanDirectory } from '../src/scanner.js';
+
+function makeTmpDir(): string {
+  return mkdtempSync(join(tmpdir(), 'transduck-scanner-test-'));
+}
+
+describe('extractStrings', () => {
+  it('extracts ait with double quotes', () => {
+    const result = extractStrings('ait("Our Events")', 'test.py');
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Our Events');
+    expect(result[0].plural).toBeUndefined();
+  });
+
+  it('extracts ait with single quotes', () => {
+    const result = extractStrings("ait('Our Events')", 'test.py');
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Our Events');
+  });
+
+  it('extracts ait with keyword context', () => {
+    const result = extractStrings('ait("Book Now", context="Hotel booking")', 'test.py');
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Book Now');
+    expect(result[0].context).toBe('Hotel booking');
+  });
+
+  it('extracts ait with positional context (JS style)', () => {
+    const result = extractStrings('ait("Book Now", "Hotel booking")', 'test.js');
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Book Now');
+    expect(result[0].context).toBe('Hotel booking');
+  });
+
+  it('extracts ait with no context', () => {
+    const result = extractStrings('ait("Hello")', 'test.py');
+    expect(result[0].context).toBeNull();
+  });
+
+  it('extracts ait with vars but no context', () => {
+    const result = extractStrings('ait("Welcome {name}", vars={"name": user})', 'test.py');
+    expect(result[0].text).toBe('Welcome {name}');
+    expect(result[0].context).toBeNull();
+  });
+
+  it('extracts ait_plural (Python style)', () => {
+    const result = extractStrings('ait_plural("{count} message", "{count} messages", count=n)', 'test.py');
+    expect(result).toHaveLength(1);
+    expect(result[0].plural).toBe(true);
+    expect(result[0].one).toBe('{count} message');
+    expect(result[0].other).toBe('{count} messages');
+  });
+
+  it('extracts aitPlural (JS style)', () => {
+    const result = extractStrings("aitPlural('{count} night', '{count} nights', 5)", 'test.ts');
+    expect(result).toHaveLength(1);
+    expect(result[0].plural).toBe(true);
+    expect(result[0].one).toBe('{count} night');
+    expect(result[0].other).toBe('{count} nights');
+  });
+
+  it('extracts Django template tag', () => {
+    const result = extractStrings('{% ait "Our Events" %}', 'test.html');
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Our Events');
+  });
+
+  it('extracts Django template tag with context', () => {
+    const result = extractStrings('{% ait "Book Now" context="Hotel booking" %}', 'test.html');
+    expect(result[0].text).toBe('Book Now');
+    expect(result[0].context).toBe('Hotel booking');
+  });
+
+  it('extracts Jinja expression', () => {
+    const result = extractStrings('{{ ait("Our Events") }}', 'test.html');
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Our Events');
+  });
+
+  it('extracts multiple strings', () => {
+    const code = `
+ait("Hello")
+ait("World", context="greeting")
+ait_plural("{count} item", "{count} items", count=n)
+`;
+    const result = extractStrings(code, 'test.py');
+    expect(result).toHaveLength(3);
+  });
+
+  it('returns empty for no matches', () => {
+    const result = extractStrings('print("Hello")', 'test.py');
+    expect(result).toHaveLength(0);
+  });
+
+  it('includes line numbers', () => {
+    const result = extractStrings('line1\nait("Hello")\nline3', 'test.py');
+    expect(result[0].line).toBe(2);
+  });
+});
+
+describe('scanDirectory', () => {
+  it('scans directory and deduplicates', () => {
+    const tmp = makeTmpDir();
+    writeFileSync(join(tmp, 'app.py'), 'ait("Hello")\nait("World")');
+    writeFileSync(join(tmp, 'views.py'), 'ait("Hello")'); // duplicate
+    writeFileSync(join(tmp, 'template.html'), '{% ait "Events" %}');
+    const result = scanDirectory([tmp]);
+    const texts = result.filter(e => !e.plural).map(e => e.text);
+    expect(texts).toContain('Hello');
+    expect(texts).toContain('World');
+    expect(texts).toContain('Events');
+    expect(result).toHaveLength(3);
+  });
+
+  it('dedup tracks files', () => {
+    const tmp = makeTmpDir();
+    writeFileSync(join(tmp, 'a.py'), 'ait("Hello")');
+    writeFileSync(join(tmp, 'b.py'), 'ait("Hello")');
+    const result = scanDirectory([tmp]);
+    expect(result).toHaveLength(1);
+    expect(result[0].files).toHaveLength(2);
+  });
+
+  it('skips node_modules', () => {
+    const tmp = makeTmpDir();
+    const nm = join(tmp, 'node_modules');
+    mkdirSync(nm);
+    writeFileSync(join(nm, 'dep.js'), 'ait("Hidden")');
+    writeFileSync(join(tmp, 'app.py'), 'ait("Visible")');
+    const result = scanDirectory([tmp]);
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Visible');
+  });
+
+  it('skips .venv', () => {
+    const tmp = makeTmpDir();
+    const venv = join(tmp, '.venv');
+    mkdirSync(venv);
+    writeFileSync(join(venv, 'lib.py'), 'ait("Hidden")');
+    writeFileSync(join(tmp, 'app.py'), 'ait("Visible")');
+    const result = scanDirectory([tmp]);
+    expect(result).toHaveLength(1);
+  });
+
+  it('filters extensions', () => {
+    const tmp = makeTmpDir();
+    writeFileSync(join(tmp, 'readme.md'), 'ait("Not a code file")');
+    writeFileSync(join(tmp, 'app.py'), 'ait("Code file")');
+    const result = scanDirectory([tmp]);
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('Code file');
+  });
+
+  it('deduplicates plural entries', () => {
+    const tmp = makeTmpDir();
+    writeFileSync(join(tmp, 'a.py'), 'ait_plural("{count} msg", "{count} msgs", count=n)');
+    writeFileSync(join(tmp, 'b.py'), 'ait_plural("{count} msg", "{count} msgs", count=n)');
+    const result = scanDirectory([tmp]);
+    expect(result).toHaveLength(1);
+    expect(result[0].plural).toBe(true);
+    expect(result[0].files).toHaveLength(2);
+  });
+});