ai-localize-scanner 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # ai-localize-scanner
 
+## 2.0.1
+
+### Patch Changes
+
+- Fix config schema validation (aws optional/nullable, framework type), ignore className CSS values in AST scanner, add includePatterns config support for selective file scanning, add --extract-cdns flag to scan command to dump CDN URLs to a JSON file
+- Updated dependencies
+  - ai-localize-config@2.0.1
+  - ai-localize-shared@2.0.1
+
 ## 2.0.0
 
 ### Major Changes

package/dist/index.d.mts

@@ -1,9 +1,32 @@
-import { DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
+import { CodemodConfig, DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
 
 interface AstScanOptions {
     filePath: string;
     content: string;
     sourceRoot?: string;
+    /**
+     * Optional codemod config from ai-localize.config.json.
+     *
+     * The scanner uses this to recognise already-translated strings even when
+     * the project uses a custom i18n library or a locally-defined hook:
+     *
+     *   importPackage — matched against import source strings. Supports:
+     *     - npm package names:    "react-i18next", "my-i18n-lib"
+     *     - path aliases:    "@/hooks/useTranslation", "@/i18n"
+     *     - relative paths:       "../../hooks/useTranslation"
+     *     Matching is done by checking whether the import source equals the value
+     *     OR ends with the last path segment(s) of the value (normalised).
+     *
+     *   hookName — the hook identifier (e.g. "useTranslation", "useI18n").
+     *   Added directly to the translation-function names set regardless of
+     *     how the hook is imported.  This means even default imports, re-exports
+     *     or barrel aliases are handled correctly:
+     *       import useT from '../../hooks/useT'  (default import, hookName="useT")
+     *
+     *   translationFunction — the accessor returned by the hook (e.g. "t").
+     *     Added directly to the translation-function names set.
+     */
+    codemodConfig?: CodemodConfig;
 }
 /**
  * Scans a JS/TS/JSX/TSX file using Babel AST to find hardcoded text.
@@ -11,10 +34,23 @@ interface AstScanOptions {
 declare class AstScanner {
     private options;
     private detectedTexts;
+    /** Identifiers whose call/bracket expressions contain already-translated strings. */
     private translationFunctionNames;
+    /**
+       * Import source matchers.
+       * Each entry is either an exact string (npm package) or a path-suffix matcher
+       * function built from a relative/alias path.
+       */
+    private importSourceMatchers;
     constructor(options: AstScanOptions);
     scan(): DetectedText[];
+    /**
+     * Walk import declarations; when the source matches a known translation
+     * import, collect all named/default imports as translation function names.
+     */
     private collectTranslationImports;
+    /** Returns true if the import source string should be treated as a translation library. */
+    private isTranslationImportSource;
     private isInsideTranslationCall;
     private addDetected;
     private mapAttrToContext;

package/dist/index.d.ts

@@ -1,9 +1,32 @@
-import { DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
+import { CodemodConfig, DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
 
 interface AstScanOptions {
     filePath: string;
     content: string;
     sourceRoot?: string;
+    /**
+     * Optional codemod config from ai-localize.config.json.
+     *
+     * The scanner uses this to recognise already-translated strings even when
+     * the project uses a custom i18n library or a locally-defined hook:
+     *
+     *   importPackage — matched against import source strings. Supports:
+     *     - npm package names:    "react-i18next", "my-i18n-lib"
+     *     - path aliases:    "@/hooks/useTranslation", "@/i18n"
+     *     - relative paths:       "../../hooks/useTranslation"
+     *     Matching is done by checking whether the import source equals the value
+     *     OR ends with the last path segment(s) of the value (normalised).
+     *
+     *   hookName — the hook identifier (e.g. "useTranslation", "useI18n").
+     *   Added directly to the translation-function names set regardless of
+     *     how the hook is imported.  This means even default imports, re-exports
+     *     or barrel aliases are handled correctly:
+     *       import useT from '../../hooks/useT'  (default import, hookName="useT")
+     *
+     *   translationFunction — the accessor returned by the hook (e.g. "t").
+     *     Added directly to the translation-function names set.
+     */
+    codemodConfig?: CodemodConfig;
 }
 /**
  * Scans a JS/TS/JSX/TSX file using Babel AST to find hardcoded text.
@@ -11,10 +34,23 @@ interface AstScanOptions {
 declare class AstScanner {
     private options;
     private detectedTexts;
+    /** Identifiers whose call/bracket expressions contain already-translated strings. */
     private translationFunctionNames;
+    /**
+       * Import source matchers.
+       * Each entry is either an exact string (npm package) or a path-suffix matcher
+       * function built from a relative/alias path.
+       */
+    private importSourceMatchers;
     constructor(options: AstScanOptions);
     scan(): DetectedText[];
+    /**
+     * Walk import declarations; when the source matches a known translation
+     * import, collect all named/default imports as translation function names.
+     */
     private collectTranslationImports;
+    /** Returns true if the import source string should be treated as a translation library. */
+    private isTranslationImportSource;
     private isInsideTranslationCall;
     private addDetected;
     private mapAttrToContext;

package/dist/index.js

@@ -43,7 +43,7 @@ var parser = __toESM(require("@babel/parser"));
 var import_traverse = __toESM(require("@babel/traverse"));
 var t = __toESM(require("@babel/types"));
 var import_ai_localize_shared = require("ai-localize-shared");
-var TRANSLATION_IMPORT_SOURCES = /* @__PURE__ */ new Set([
+var BUILTIN_TRANSLATION_IMPORT_SOURCES = /* @__PURE__ */ new Set([
   "react-i18next",
   "i18next",
   "vue-i18n",
@@ -52,9 +52,32 @@ var TRANSLATION_IMPORT_SOURCES = /* @__PURE__ */ new Set([
 var AstScanner = class {
   options;
   detectedTexts = [];
-  translationFunctionNames = /* @__PURE__ */ new Set(["t", "$t", "i18n", "translate"]);
+  /** Identifiers whose call/bracket expressions contain already-translated strings. */
+  translationFunctionNames;
+  /**
+     * Import source matchers.
+     * Each entry is either an exact string (npm package) or a path-suffix matcher
+     * function built from a relative/alias path.
+     */
+  importSourceMatchers;
   constructor(options) {
     this.options = options;
+    this.translationFunctionNames = /* @__PURE__ */ new Set(["t", "$t", "i18n", "translate"]);
+    this.importSourceMatchers = Array.from(BUILTIN_TRANSLATION_IMPORT_SOURCES).map(
+      (pkg) => (src) => src === pkg
+    );
+    const cc = options.codemodConfig;
+    if (cc) {
+      if (cc.translationFunction) {
+        this.translationFunctionNames.add(cc.translationFunction);
+      }
+      if (cc.hookName) {
+        this.translationFunctionNames.add(cc.hookName);
+      }
+      if (cc.importPackage) {
+        this.importSourceMatchers.push(buildImportMatcher(cc.importPackage));
+      }
+    }
   }
   scan() {
     const { content } = this.options;
@@ -113,9 +136,7 @@ var AstScanner = class {
         if (t.isObjectProperty(nodePath.parent) && nodePath.parent.key === nodePath.node) return;
         if (t.isJSXAttribute(nodePath.parent)) {
           const attrName = t.isJSXIdentifier(nodePath.parent.name) ? nodePath.parent.name.name.toLowerCase() : "";
-          if (attrName === "classname" || attrName === "class") {
-            return;
-          }
+          if (attrName === "classname" || attrName === "class") return;
           return;
         }
         if (this.isInsideTranslationCall(nodePath)) return;
@@ -149,17 +170,32 @@ var AstScanner = class {
     });
     return this.detectedTexts;
   }
+  /**
+   * Walk import declarations; when the source matches a known translation
+   * import, collect all named/default imports as translation function names.
+   */
   collectTranslationImports(ast) {
     for (const node of ast.program.body) {
       if (!t.isImportDeclaration(node)) continue;
-      if (!TRANSLATION_IMPORT_SOURCES.has(node.source.value)) continue;
+      const source = node.source.value;
+      if (!this.isTranslationImportSource(source)) continue;
       for (const specifier of node.specifiers) {
         if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.local)) {
           this.translationFunctionNames.add(specifier.local.name);
         }
+        if (t.isImportDefaultSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+          this.translationFunctionNames.add(specifier.local.name);
+        }
+        if (t.isImportNamespaceSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+          this.translationFunctionNames.add(specifier.local.name);
+        }
       }
     }
   }
+  /** Returns true if the import source string should be treated as a translation library. */
+  isTranslationImportSource(source) {
+    return this.importSourceMatchers.some((match) => match(source));
+  }
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   isInsideTranslationCall(nodePath) {
     let current = nodePath.parentPath;
@@ -174,6 +210,12 @@ var AstScanner = class {
           return true;
         }
       }
+      if (t.isMemberExpression(node) && node.computed) {
+        const obj = node.object;
+        if (t.isIdentifier(obj) && this.translationFunctionNames.has(obj.name)) {
+          return true;
+        }
+      }
       current = current.parentPath;
     }
     return false;
@@ -213,7 +255,11 @@ var AstScanner = class {
       while ((m = jsxTextRegex.exec(line)) !== null) {
         const text = (0, import_ai_localize_shared.normalizeText)(m[1]);
         if (!(0, import_ai_localize_shared.isHumanReadableText)(text)) continue;
-        const key = (0, import_ai_localize_shared.generateLocaleKey)(this.options.filePath, text, this.options.sourceRoot || "src");
+        const key = (0, import_ai_localize_shared.generateLocaleKey)(
+          this.options.filePath,
+          text,
+          this.options.sourceRoot || "src"
+        );
         results.push({
           filePath: this.options.filePath,
           line: idx + 1,
@@ -229,6 +275,23 @@ var AstScanner = class {
     return results;
   }
 };
+function buildImportMatcher(importPackage) {
+  const normalisedPkg = normalisePath(importPackage);
+  const pkgSegments = normalisedPkg.split("/").filter(Boolean);
+  return (source) => {
+    if (source === importPackage) return true;
+    const normSource = normalisePath(source);
+    const srcSegments = normSource.split("/").filter(Boolean);
+    if (pkgSegments.length === 0) return false;
+    const n = pkgSegments.length;
+    if (srcSegments.length < n) return false;
+    const tail = srcSegments.slice(-n);
+    return tail.every((seg, i) => seg.toLowerCase() === pkgSegments[i].toLowerCase());
+  };
+}
+function normalisePath(p) {
+  return p.replace(/\\/g, "/").replace(/^(@\/|\.{1,2}\/)+/, "").replace(/^@/, "");
+}
 
 // src/asset-scanner.ts
 var fs = __toESM(require("fs"));
@@ -390,7 +453,7 @@ var ProjectScanner = class {
   assetScanner;
   constructor(config) {
     this.config = config;
-    this.sourceRoot = path3.join(process.cwd(), config.sourceDir);
+    this.sourceRoot = path3.resolve(process.cwd(), config.sourceDir);
     this.assetScanner = new AssetScanner(config.aws?.legacyCdnPattern);
     if (config.incrementalCache) {
       this.cache = new IncrementalScanCache(
@@ -400,10 +463,25 @@ var ProjectScanner = class {
   }
   async scan(options = {}) {
     const startTime = Date.now();
-    const filesToScan = options.files?.length ? options.files : (0, import_ai_localize_shared4.collectFiles)(this.sourceRoot, import_ai_localize_shared4.SOURCE_EXTENSIONS, [
-      ...import_ai_localize_shared4.DEFAULT_IGNORE_DIRS,
-      ...this.config.ignorePatterns || []
-    ]);
+    let filesToScan = [];
+    if (options.files?.length) {
+      filesToScan = options.files;
+    } else {
+      const allFiles = (0, import_ai_localize_shared4.collectFiles)(this.sourceRoot, import_ai_localize_shared4.SOURCE_EXTENSIONS, [
+        ...import_ai_localize_shared4.DEFAULT_IGNORE_DIRS,
+        ...this.config.ignorePatterns || []
+      ]);
+      if (this.config.includePatterns && this.config.includePatterns.length > 0) {
+        filesToScan = allFiles.filter((file) => {
+          return this.config.includePatterns.some((pattern) => {
+            const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+            return new RegExp(regexPattern).test(file);
+          });
+        });
+      } else {
+        filesToScan = allFiles;
+      }
+    }
     const allTexts = [];
     const allAssets = [];
     const allLegacyUrls = [];
@@ -443,7 +521,12 @@ var ProjectScanner = class {
     } catch {
       return { texts: [], assets: [], legacyUrls: [] };
     }
-    const scanner = new AstScanner({ filePath, content, sourceRoot: this.config.sourceDir });
+    const scanner = new AstScanner({
+      filePath,
+      content,
+      sourceRoot: this.sourceRoot,
+      codemodConfig: this.config.codemods
+    });
     const texts = scanner.scan();
     const { assets, legacyCdnUrls } = this.assetScanner.scanFile(filePath);
     this.cache?.setCachedResult(filePath, texts);

package/dist/index.mjs

@@ -8,7 +8,7 @@ import {
   TEXT_ATTRIBUTE_NAMES,
   generateLocaleKey
 } from "ai-localize-shared";
-var TRANSLATION_IMPORT_SOURCES = /* @__PURE__ */ new Set([
+var BUILTIN_TRANSLATION_IMPORT_SOURCES = /* @__PURE__ */ new Set([
   "react-i18next",
   "i18next",
   "vue-i18n",
@@ -17,9 +17,32 @@ var TRANSLATION_IMPORT_SOURCES = /* @__PURE__ */ new Set([
 var AstScanner = class {
   options;
   detectedTexts = [];
-  translationFunctionNames = /* @__PURE__ */ new Set(["t", "$t", "i18n", "translate"]);
+  /** Identifiers whose call/bracket expressions contain already-translated strings. */
+  translationFunctionNames;
+  /**
+     * Import source matchers.
+     * Each entry is either an exact string (npm package) or a path-suffix matcher
+     * function built from a relative/alias path.
+     */
+  importSourceMatchers;
   constructor(options) {
     this.options = options;
+    this.translationFunctionNames = /* @__PURE__ */ new Set(["t", "$t", "i18n", "translate"]);
+    this.importSourceMatchers = Array.from(BUILTIN_TRANSLATION_IMPORT_SOURCES).map(
+      (pkg) => (src) => src === pkg
+    );
+    const cc = options.codemodConfig;
+    if (cc) {
+      if (cc.translationFunction) {
+        this.translationFunctionNames.add(cc.translationFunction);
+      }
+      if (cc.hookName) {
+        this.translationFunctionNames.add(cc.hookName);
+      }
+      if (cc.importPackage) {
+        this.importSourceMatchers.push(buildImportMatcher(cc.importPackage));
+      }
+    }
   }
   scan() {
     const { content } = this.options;
@@ -78,9 +101,7 @@ var AstScanner = class {
         if (t.isObjectProperty(nodePath.parent) && nodePath.parent.key === nodePath.node) return;
         if (t.isJSXAttribute(nodePath.parent)) {
           const attrName = t.isJSXIdentifier(nodePath.parent.name) ? nodePath.parent.name.name.toLowerCase() : "";
-          if (attrName === "classname" || attrName === "class") {
-            return;
-          }
+          if (attrName === "classname" || attrName === "class") return;
           return;
         }
         if (this.isInsideTranslationCall(nodePath)) return;
@@ -114,17 +135,32 @@ var AstScanner = class {
     });
     return this.detectedTexts;
   }
+  /**
+   * Walk import declarations; when the source matches a known translation
+   * import, collect all named/default imports as translation function names.
+   */
   collectTranslationImports(ast) {
     for (const node of ast.program.body) {
       if (!t.isImportDeclaration(node)) continue;
-      if (!TRANSLATION_IMPORT_SOURCES.has(node.source.value)) continue;
+      const source = node.source.value;
+      if (!this.isTranslationImportSource(source)) continue;
       for (const specifier of node.specifiers) {
         if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.local)) {
           this.translationFunctionNames.add(specifier.local.name);
         }
+        if (t.isImportDefaultSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+          this.translationFunctionNames.add(specifier.local.name);
+        }
+        if (t.isImportNamespaceSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+          this.translationFunctionNames.add(specifier.local.name);
+        }
       }
     }
   }
+  /** Returns true if the import source string should be treated as a translation library. */
+  isTranslationImportSource(source) {
+    return this.importSourceMatchers.some((match) => match(source));
+  }
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   isInsideTranslationCall(nodePath) {
     let current = nodePath.parentPath;
@@ -139,6 +175,12 @@ var AstScanner = class {
           return true;
         }
       }
+      if (t.isMemberExpression(node) && node.computed) {
+        const obj = node.object;
+        if (t.isIdentifier(obj) && this.translationFunctionNames.has(obj.name)) {
+          return true;
+        }
+      }
       current = current.parentPath;
     }
     return false;
@@ -178,7 +220,11 @@ var AstScanner = class {
       while ((m = jsxTextRegex.exec(line)) !== null) {
         const text = normalizeText(m[1]);
         if (!isHumanReadableText(text)) continue;
-        const key = generateLocaleKey(this.options.filePath, text, this.options.sourceRoot || "src");
+        const key = generateLocaleKey(
+          this.options.filePath,
+          text,
+          this.options.sourceRoot || "src"
+        );
         results.push({
           filePath: this.options.filePath,
           line: idx + 1,
@@ -194,6 +240,23 @@ var AstScanner = class {
     return results;
   }
 };
+function buildImportMatcher(importPackage) {
+  const normalisedPkg = normalisePath(importPackage);
+  const pkgSegments = normalisedPkg.split("/").filter(Boolean);
+  return (source) => {
+    if (source === importPackage) return true;
+    const normSource = normalisePath(source);
+    const srcSegments = normSource.split("/").filter(Boolean);
+    if (pkgSegments.length === 0) return false;
+    const n = pkgSegments.length;
+    if (srcSegments.length < n) return false;
+    const tail = srcSegments.slice(-n);
+    return tail.every((seg, i) => seg.toLowerCase() === pkgSegments[i].toLowerCase());
+  };
+}
+function normalisePath(p) {
+  return p.replace(/\\/g, "/").replace(/^(@\/|\.{1,2}\/)+/, "").replace(/^@/, "");
+}
 
 // src/asset-scanner.ts
 import * as fs from "fs";
@@ -355,7 +418,7 @@ var ProjectScanner = class {
   assetScanner;
   constructor(config) {
     this.config = config;
-    this.sourceRoot = path3.join(process.cwd(), config.sourceDir);
+    this.sourceRoot = path3.resolve(process.cwd(), config.sourceDir);
     this.assetScanner = new AssetScanner(config.aws?.legacyCdnPattern);
     if (config.incrementalCache) {
       this.cache = new IncrementalScanCache(
@@ -365,10 +428,25 @@ var ProjectScanner = class {
   }
   async scan(options = {}) {
     const startTime = Date.now();
-    const filesToScan = options.files?.length ? options.files : collectFiles(this.sourceRoot, SOURCE_EXTENSIONS, [
-      ...DEFAULT_IGNORE_DIRS,
-      ...this.config.ignorePatterns || []
-    ]);
+    let filesToScan = [];
+    if (options.files?.length) {
+      filesToScan = options.files;
+    } else {
+      const allFiles = collectFiles(this.sourceRoot, SOURCE_EXTENSIONS, [
+        ...DEFAULT_IGNORE_DIRS,
+        ...this.config.ignorePatterns || []
+      ]);
+      if (this.config.includePatterns && this.config.includePatterns.length > 0) {
+        filesToScan = allFiles.filter((file) => {
+          return this.config.includePatterns.some((pattern) => {
+            const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+            return new RegExp(regexPattern).test(file);
+          });
+        });
+      } else {
+        filesToScan = allFiles;
+      }
+    }
     const allTexts = [];
     const allAssets = [];
     const allLegacyUrls = [];
@@ -408,7 +486,12 @@ var ProjectScanner = class {
     } catch {
       return { texts: [], assets: [], legacyUrls: [] };
     }
-    const scanner = new AstScanner({ filePath, content, sourceRoot: this.config.sourceDir });
+    const scanner = new AstScanner({
+      filePath,
+      content,
+      sourceRoot: this.sourceRoot,
+      codemodConfig: this.config.codemods
+    });
     const texts = scanner.scan();
     const { assets, legacyCdnUrls } = this.assetScanner.scanFile(filePath);
     this.cache?.setCachedResult(filePath, texts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-scanner",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "AST-based hardcoded text scanner for frontend applications",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -17,8 +17,8 @@
     "@babel/traverse": "^7.23.9",
     "@babel/types": "^7.23.9",
     "glob": "^10.3.10",
-    "ai-localize-shared": "2.0.0",
-    "ai-localize-config": "2.0.0"
+    "ai-localize-shared": "2.0.1",
+    "ai-localize-config": "2.0.1"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.20.5",

package/src/ast-scanner.ts

@@ -2,7 +2,7 @@ import * as parser from '@babel/parser';
 import traverse from '@babel/traverse';
 import * as t from '@babel/types';
 
-import type { DetectedText, TextContext } from 'ai-localize-shared';
+import type { DetectedText, TextContext, CodemodConfig } from 'ai-localize-shared';
 import {
   isHumanReadableText,
   normalizeText,
@@ -14,13 +14,37 @@ export interface AstScanOptions {
   filePath: string;
   content: string;
   sourceRoot?: string;
+  /**
+   * Optional codemod config from ai-localize.config.json.
+   *
+   * The scanner uses this to recognise already-translated strings even when
+   * the project uses a custom i18n library or a locally-defined hook:
+   *
+   *   importPackage — matched against import source strings. Supports:
+   *     - npm package names:    "react-i18next", "my-i18n-lib"
+   *     - path aliases:    "@/hooks/useTranslation", "@/i18n"
+   *     - relative paths:       "../../hooks/useTranslation"
+   *     Matching is done by checking whether the import source equals the value
+   *     OR ends with the last path segment(s) of the value (normalised).
+   *
+   *   hookName — the hook identifier (e.g. "useTranslation", "useI18n").
+   *   Added directly to the translation-function names set regardless of
+   *     how the hook is imported.  This means even default imports, re-exports
+   *     or barrel aliases are handled correctly:
+   *       import useT from '../../hooks/useT'  (default import, hookName="useT")
+   *
+   *   translationFunction — the accessor returned by the hook (e.g. "t").
+   *     Added directly to the translation-function names set.
+   */
+  codemodConfig?: CodemodConfig;
 }
 
-const TRANSLATION_IMPORT_SOURCES = new Set([
+/** Well-known i18n library import sources (npm package names). */
+const BUILTIN_TRANSLATION_IMPORT_SOURCES = new Set([
   'react-i18next',
   'i18next',
   'vue-i18n',
-  '@ngx-translate/core',
+'@ngx-translate/core',
 ]);
 
 /**
@@ -29,28 +53,67 @@ const TRANSLATION_IMPORT_SOURCES = new Set([
 export class AstScanner {
   private options: AstScanOptions;
   private detectedTexts: DetectedText[] = [];
-  private translationFunctionNames = new Set<string>(['t', '$t', 'i18n', 'translate']);
+
+  /** Identifiers whose call/bracket expressions contain already-translated strings. */
+  private translationFunctionNames: Set<string>;
+
+/**
+   * Import source matchers.
+   * Each entry is either an exact string (npm package) or a path-suffix matcher
+   * function built from a relative/alias path.
+   */
+  private importSourceMatchers: Array<(source: string) => boolean>;
 
   constructor(options: AstScanOptions) {
     this.options = options;
+
+    // Seed default translation function names
+    this.translationFunctionNames = new Set<string>(['t', '$t', 'i18n', 'translate']);
+
+    // Build import-source matchers from builtin list
+    this.importSourceMatchers = Array.from(BUILTIN_TRANSLATION_IMPORT_SOURCES).map(
+      (pkg) => (src: string) => src === pkg
+    );
+
+    const cc = options.codemodConfig;
+    if (cc) {
+      // translationFunction — seed directly; no import lookup needed
+      if (cc.translationFunction) {
+        this.translationFunctionNames.add(cc.translationFunction);
+      }
+
+      // hookName — seed directly so the hook identifier is always recognised
+      // regardless of how it is imported (named, default, aliased, re-exported).
+      if (cc.hookName) {
+        this.translationFunctionNames.add(cc.hookName);
+      }
+
+      // importPackage — build a matcher that handles:
+      //   1. exact npm package name  "react-i18next"
+      //   2. path alias      "@/hooks/useTranslation"
+      //   3. relative path      "../../hooks/useTranslation"
+      if (cc.importPackage) {
+        this.importSourceMatchers.push(buildImportMatcher(cc.importPackage));
+      }
+    }
   }
 
   scan(): DetectedText[] {
     const { content } = this.options;
 
-    let ast: t.File;
+ let ast: t.File;
     try {
-ast = parser.parse(content, {
+      ast = parser.parse(content, {
         sourceType: 'module',
         plugins: [
-  'jsx',
-      'typescript',
-       'decorators-legacy',
-          'classProperties',
-     'optionalChaining',
-      'nullishCoalescingOperator',
-    'dynamicImport',
-          'exportDefaultFrom',
+          'jsx',
+          'typescript',
+ 'decorators-legacy',
+  'classProperties',
+        'optionalChaining',
+          'nullishCoalescingOperator',
+          'dynamicImport',
+      'exportDefaultFrom',
         ],
         errorRecovery: true,
       });
@@ -58,122 +121,155 @@ ast = parser.parse(content, {
       return this.regexFallbackScan();
     }
 
+    // Collect translation function names from imports before scanning text
     this.collectTranslationImports(ast);
 
     traverse(ast, {
       JSXText: (nodePath) => {
-        const text = normalizeText(nodePath.node.value);
+      const text = normalizeText(nodePath.node.value);
         if (!isHumanReadableText(text)) return;
         if (this.isInsideTranslationCall(nodePath)) return;
-        this.addDetected(
-          text,
-          nodePath.node.loc?.start.line ?? 0,
+     this.addDetected(
+  text,
+       nodePath.node.loc?.start.line ?? 0,
           nodePath.node.loc?.start.column ?? 0,
-          'jsx-text',
-'JSXText'
-        );
+  'jsx-text',
+ 'JSXText'
+  );
       },
 
-      JSXAttribute: (nodePath) => {
+ JSXAttribute: (nodePath) => {
         const attrName = t.isJSXIdentifier(nodePath.node.name)
-          ? nodePath.node.name.name
-        : '';
-    if (!TEXT_ATTRIBUTE_NAMES.has(attrName.toLowerCase())) return;
-   const valueNode = nodePath.node.value;
-if (!t.isStringLiteral(valueNode)) return;
-      const text = normalizeText(valueNode.value);
+    ? nodePath.node.name.name
+          : '';
+        if (!TEXT_ATTRIBUTE_NAMES.has(attrName.toLowerCase())) return;
+        const valueNode = nodePath.node.value;
+   if (!t.isStringLiteral(valueNode)) return;
+const text = normalizeText(valueNode.value);
         if (!isHumanReadableText(text)) return;
-    if (this.isInsideTranslationCall(nodePath)) return;
-      const context = this.mapAttrToContext(attrName);
+        if (this.isInsideTranslationCall(nodePath)) return;
+        const context = this.mapAttrToContext(attrName);
         this.addDetected(
-  text,
+          text,
           valueNode.loc?.start.line ?? 0,
-        valueNode.loc?.start.column ?? 0,
+          valueNode.loc?.start.column ?? 0,
           context,
           'JSXAttribute'
         );
       },
 
       StringLiteral: (nodePath) => {
-        if (t.isImportDeclaration(nodePath.parent)) return;
+if (t.isImportDeclaration(nodePath.parent)) return;
         if (t.isObjectProperty(nodePath.parent) && nodePath.parent.key === nodePath.node) return;
-        
-        // Ignore className and similar attributes containing CSS classes
+
+        // Ignore className and similar CSS-class attributes
         if (t.isJSXAttribute(nodePath.parent)) {
-          const attrName = t.isJSXIdentifier(nodePath.parent.name) ? nodePath.parent.name.name.toLowerCase() : '';
-          if (attrName === 'classname' || attrName === 'class') {
-            return;
-          }
-          return; // Ignore other unhandled JSX attributes here as well based on previous logic
+          const attrName = t.isJSXIdentifier(nodePath.parent.name)
+  ? nodePath.parent.name.name.toLowerCase()
+            : '';
+          if (attrName === 'classname' || attrName === 'class') return;
+   return;
         }
 
         if (this.isInsideTranslationCall(nodePath)) return;
-        
-        // Improve heuristic to avoid matching CSS classes / HTML tags in standard string literals
+
         const val = nodePath.node.value;
-        if (/^[a-z][a-z0-9_.-]*$/.test(val) || /^#?[0-9a-fA-F]+$/.test(val) || (/^[\w-]+\s[\w- ]+$/.test(val) && !val.includes(','))) {
-            return; // Probably a CSS class name, ID, color hex, or just words without punctuation that are often classes
-        }
+        if (
+  /^[a-z][a-z0-9_.-]*$/.test(val) ||
+          /^#?[0-9a-fA-F]+$/.test(val) ||
+          (/^[\w-]+\s[\w- ]+$/.test(val) && !val.includes(','))
+  ) {
+     return; // Likely a CSS class, ID, hex colour, or plain word pair
+  }
 
         const text = normalizeText(nodePath.node.value);
+     if (!isHumanReadableText(text)) return;
+        this.addDetected(
+       text,
+     nodePath.node.loc?.start.line ?? 0,
+   nodePath.node.loc?.start.column ?? 0,
+    'string-literal',
+     'StringLiteral'
+        );
+      },
+
+      TemplateLiteral: (nodePath) => {
+    if (nodePath.node.expressions.length > 0) return;
+if (this.isInsideTranslationCall(nodePath)) return;
+        const text = normalizeText(nodePath.node.quasis[0]?.value.cooked ?? '');
         if (!isHumanReadableText(text)) return;
         this.addDetected(
           text,
-          nodePath.node.loc?.start.line ?? 0,
-          nodePath.node.loc?.start.column ?? 0,
-          'string-literal',
-          'StringLiteral'
+nodePath.node.loc?.start.line ?? 0,
+    nodePath.node.loc?.start.column ?? 0,
+          'template-literal',
+        'TemplateLiteral'
         );
       },
-
- TemplateLiteral: (nodePath) => {
-        if (nodePath.node.expressions.length > 0) return;
-        if (this.isInsideTranslationCall(nodePath)) return;
-     const text = normalizeText(nodePath.node.quasis[0]?.value.cooked ?? '');
- if (!isHumanReadableText(text)) return;
-     this.addDetected(
-text,
-          nodePath.node.loc?.start.line ?? 0,
-          nodePath.node.loc?.start.column ?? 0,
-       'template-literal',
-          'TemplateLiteral'
-  );
-   },
     });
 
     return this.detectedTexts;
   }
 
+  /**
+   * Walk import declarations; when the source matches a known translation
+   * import, collect all named/default imports as translation function names.
+   */
   private collectTranslationImports(ast: t.File): void {
     for (const node of ast.program.body) {
       if (!t.isImportDeclaration(node)) continue;
-      if (!TRANSLATION_IMPORT_SOURCES.has(node.source.value)) continue;
- for (const specifier of node.specifiers) {
-     if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+ const source = node.source.value;
+      if (!this.isTranslationImportSource(source)) continue;
+   for (const specifier of node.specifiers) {
+        if (t.isImportSpecifier(specifier) && t.isIdentifier(specifier.local)) {
           this.translationFunctionNames.add(specifier.local.name);
+}
+     // Default import: import useT from '../../hooks/useT'
+        if (t.isImportDefaultSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+          this.translationFunctionNames.add(specifier.local.name);
+      }
+// Namespace import: import * as i18n from '...'
+        if (t.isImportNamespaceSpecifier(specifier) && t.isIdentifier(specifier.local)) {
+ this.translationFunctionNames.add(specifier.local.name);
         }
       }
     }
   }
 
+  /** Returns true if the import source string should be treated as a translation library. */
+private isTranslationImportSource(source: string): boolean {
+    return this.importSourceMatchers.some((match) => match(source));
+  }
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private isInsideTranslationCall(nodePath: any): boolean {
     let current = nodePath.parentPath;
     while (current) {
       const node = current.node;
+
+      // Function-call style: t('key')
       if (t.isCallExpression(node)) {
         const callee = node.callee;
         if (t.isIdentifier(callee) && this.translationFunctionNames.has(callee.name)) {
-          return true;
-        }
- if (
-          t.isMemberExpression(callee) &&
-          t.isIdentifier(callee.property) &&
-        this.translationFunctionNames.has(callee.property.name)
+    return true;
+      }
+  if (
+   t.isMemberExpression(callee) &&
+      t.isIdentifier(callee.property) &&
+          this.translationFunctionNames.has(callee.property.name)
         ) {
+    return true;
+        }
+      }
+
+   // Bracket-notation accessor: t['key']  (MemberExpression, computed=true)
+   if (t.isMemberExpression(node) && node.computed) {
+        const obj = node.object;
+        if (t.isIdentifier(obj) && this.translationFunctionNames.has(obj.name)) {
           return true;
         }
-    }
+      }
+
       current = current.parentPath;
     }
     return false;
@@ -189,19 +285,19 @@ text,
     const key = generateLocaleKey(
     this.options.filePath,
       text,
-      this.options.sourceRoot || 'src'
+   this.options.sourceRoot || 'src'
     );
     this.detectedTexts.push({
       filePath: this.options.filePath,
       line,
       column,
-text,
-      suggestedKey: key,
-    context,
-  nodeType,
-      alreadyTranslated: false,
-    });
-  }
+  text,
+    suggestedKey: key,
+      context,
+      nodeType,
+  alreadyTranslated: false,
+  });
+}
 
   private mapAttrToContext(attrName: string): TextContext {
     const lower = attrName.toLowerCase();
@@ -218,23 +314,87 @@ text,
     const lines = this.options.content.split('\n');
     lines.forEach((line, idx) => {
       let m: RegExpExecArray | null;
- jsxTextRegex.lastIndex = 0;
+   jsxTextRegex.lastIndex = 0;
       while ((m = jsxTextRegex.exec(line)) !== null) {
         const text = normalizeText(m[1]);
         if (!isHumanReadableText(text)) continue;
-  const key = generateLocaleKey(this.options.filePath, text, this.options.sourceRoot || 'src');
+        const key = generateLocaleKey(
+          this.options.filePath,
+          text,
+      this.options.sourceRoot || 'src'
+        );
         results.push({
-          filePath: this.options.filePath,
-     line: idx + 1,
+      filePath: this.options.filePath,
+          line: idx + 1,
           column: m.index,
-     text,
- suggestedKey: key,
-        context: 'jsx-text',
+          text,
+          suggestedKey: key,
+       context: 'jsx-text',
           nodeType: 'regex-fallback',
    alreadyTranslated: false,
-        });
- }
+  });
+      }
     });
     return results;
   }
 }
+
+/**
+ * Builds an import-source matcher function for the given `importPackage` value.
+ *
+ * Handles three cases:
+ *
+ * 1. Exact npm package name — "react-i18next", "my-i18n-lib"
+ *    Matches when the import source string equals the value exactly.
+ *
+ * 2. Path alias — "@/hooks/useTranslation", "@/i18n"
+ *    Matches when the import source equals the value OR ends with the
+ *    normalised path suffix (with or without the alias prefix).
+ *
+ * 3. Relative path — "../../hooks/useTranslation", "./i18n/hook"
+ *    Because relative paths resolve differently per file, we match by
+ *    comparing the **last N segments** of the import source with the
+ *    last N segments of the configured value (case-insensitive, stripping
+ *    leading dots and slashes).  This is intentionally lenient so that
+ *  `hooks/useTranslation` matches both `../../hooks/useTranslation` and
+ *    `./hooks/useTranslation`.
+ *
+ * Examples:
+ *   importPackage="../../hooks/useTranslation"
+ *     matches  "../../hooks/useTranslation"  ✓
+ *     matches  "./hooks/useTranslation"     ✓  (same tail segments)
+ *     matches  "../hooks/useTranslation"      ✓
+ *   importPackage="@/i18n/hook"
+ *     matches  "@/i18n/hook"     ✓
+ * matches  "i18n/hook"       ✓
+ */
+function buildImportMatcher(importPackage: string): (source: string) => boolean {
+  // Normalise: strip leading ./ ../ @ and collapse slashes
+  const normalisedPkg = normalisePath(importPackage);
+  const pkgSegments = normalisedPkg.split('/').filter(Boolean);
+
+  return (source: string): boolean => {
+    // 1. Exact match (covers plain npm package names and exact alias paths)
+  if (source === importPackage) return true;
+
+    // 2. Suffix / tail-segment match
+    const normSource = normalisePath(source);
+    const srcSegments = normSource.split('/').filter(Boolean);
+
+    if (pkgSegments.length === 0) return false;
+
+    // Check if the source ends with the same N tail segments as the package
+    const n = pkgSegments.length;
+    if (srcSegments.length < n) return false;
+    const tail = srcSegments.slice(-n);
+    return tail.every((seg, i) => seg.toLowerCase() === pkgSegments[i].toLowerCase());
+  };
+}
+
+/** Strips leading dots, slashes and @ from a path string for comparison purposes. */
+function normalisePath(p: string): string {
+  return p
+    .replace(/\\/g, '/')
+    .replace(/^(@\/|\.{1,2}\/)+/, '') // strip leading ./ ../ @/
+    .replace(/^@/, ''); // strip bare @ prefix
+}

package/src/project-scanner.ts

@@ -27,52 +27,69 @@ export class ProjectScanner {
 
   constructor(config: LocalizationConfig) {
     this.config = config;
-    this.sourceRoot = path.join(process.cwd(), config.sourceDir);
+    // Resolve to absolute path so key-generator can use path.relative()
+    // and never produce keys that include ancestor directory segments.
+ this.sourceRoot = path.resolve(process.cwd(), config.sourceDir);
     this.assetScanner = new AssetScanner(config.aws?.legacyCdnPattern);
     if (config.incrementalCache) {
       this.cache = new IncrementalScanCache(
-      path.join(process.cwd(), config.cacheDir || '.ai-localize-cache')
+        path.join(process.cwd(), config.cacheDir || '.ai-localize-cache')
       );
     }
   }
 
   async scan(options: ScanOptions = {}): Promise<ScanResult> {
     const startTime = Date.now();
-    const filesToScan = options.files?.length
-      ? options.files
-      : collectFiles(this.sourceRoot, SOURCE_EXTENSIONS, [
- ...DEFAULT_IGNORE_DIRS,
-          ...(this.config.ignorePatterns || []),
+    let filesToScan: string[] = [];
+
+    if (options.files?.length) {
+  filesToScan = options.files;
+  } else {
+      const allFiles = collectFiles(this.sourceRoot, SOURCE_EXTENSIONS, [
+  ...DEFAULT_IGNORE_DIRS,
+        ...(this.config.ignorePatterns || []),
    ]);
 
+      if (this.config.includePatterns && this.config.includePatterns.length > 0) {
+    filesToScan = allFiles.filter(file => {
+return this.config.includePatterns!.some(pattern => {
+            const regexPattern = pattern.replace(/\*/g, '.*').replace(/\?/g, '.');
+  return new RegExp(regexPattern).test(file);
+   });
+      });
+      } else {
+        filesToScan = allFiles;
+      }
+    }
+
     const allTexts: DetectedText[] = [];
-    const allAssets: AssetReference[] = [];
+ const allAssets: AssetReference[] = [];
     const allLegacyUrls: LegacyCdnUrl[] = [];
 
-  const chunkSize = Math.max(
-  1,
+    const chunkSize = Math.max(
+      1,
   Math.min(50, Math.ceil(filesToScan.length / (os.cpus().length || 4)))
     );
     const chunks = this.chunkArray(filesToScan, chunkSize);
 
     for (const chunk of chunks) {
-const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
-      for (const r of results) {
+    const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
+ for (const r of results) {
         allTexts.push(...r.texts);
         allAssets.push(...r.assets);
         allLegacyUrls.push(...r.legacyUrls);
       }
     }
 
-    this.cache?.persist();
+ this.cache?.persist();
 
     return {
-  framework: this.config.framework,
+framework: this.config.framework,
       scannedFiles: filesToScan.length,
       detectedTexts: allTexts,
     assets: allAssets,
       legacyCdnUrls: allLegacyUrls,
-    duration: Date.now() - startTime,
+      duration: Date.now() - startTime,
       timestamp: new Date().toISOString(),
     };
   }
@@ -93,9 +110,18 @@ const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
       content = readFileSync(filePath, 'utf-8');
     } catch {
       return { texts: [], assets: [], legacyUrls: [] };
- }
+    }
 
-    const scanner = new AstScanner({ filePath, content, sourceRoot: this.config.sourceDir });
+    // Pass the absolute sourceRoot so normalizePath uses path.relative()
+    // and strips only the project source directory — not ancestor segments.
+    // Also pass codemods config so the scanner recognises user-defined
+    // translation functions/hooks and skips already-translated strings.
+    const scanner = new AstScanner({
+      filePath,
+      content,
+      sourceRoot: this.sourceRoot,
+      codemodConfig: this.config.codemods,
+    });
     const texts = scanner.scan();
     const { assets, legacyCdnUrls } = this.assetScanner.scanFile(filePath);
 
@@ -107,7 +133,7 @@ const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
   private chunkArray<T>(array: T[], size: number): T[][] {
     const chunks: T[][] = [];
     for (let i = 0; i < array.length; i += size) {
-      chunks.push(array.slice(i, i + size));
+   chunks.push(array.slice(i, i + size));
     }
     return chunks;
   }