ai-localize-scanner 2.0.0 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # ai-localize-scanner
 
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-localize-shared@2.0.3
+  - ai-localize-config@2.0.3
+
+## 2.0.2
+
+### Minor Changes
+
+- **AST scanner seeds translation-fn names from codemods config** — translation function names configured under `codemods.translationFunction` are now automatically recognised by the AST scanner so already-translated strings are correctly skipped
+
+### Patch Changes
+
+- **Bug fix — locale key prefix with absolute sourceRoot** — `normalizePath()` now calls `path.relative()` when `sourceRoot` is an absolute path; `ProjectScanner` passes the resolved absolute `sourceRoot` to `AstScanner`, preventing ancestor path segments leaking into generated locale keys
+- Updated dependencies
+  - ai-localize-config@2.0.2
+  - ai-localize-shared@2.0.2
+
+## 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,43 @@
-import { DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
+import { KeyStyle, CodemodConfig, DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
 
 interface AstScanOptions {
     filePath: string;
     content: string;
     sourceRoot?: string;
+    /**
+     * Controls the format of the generated locale key for each detected text.
+   *
+     * - `"path"` (default) — hierarchical dot-notation key derived from file path + text:
+     *     `settings.settings_page.save_changes`
+     *
+     * - `"screaming_snake"` — UPPER_SNAKE_CASE key derived solely from the text value:
+     *     "Save Changes" → `SAVE_CHANGES`
+     *     "Max Count"  → `MAX_COUNT`
+     */
+    keyStyle?: KeyStyle;
+    /**
+     * 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 +45,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,43 @@
-import { DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
+import { KeyStyle, CodemodConfig, DetectedText, AssetReference, LegacyCdnUrl, LocalizationConfig, ScanResult } from 'ai-localize-shared';
 
 interface AstScanOptions {
     filePath: string;
     content: string;
     sourceRoot?: string;
+    /**
+     * Controls the format of the generated locale key for each detected text.
+   *
+     * - `"path"` (default) — hierarchical dot-notation key derived from file path + text:
+     *     `settings.settings_page.save_changes`
+     *
+     * - `"screaming_snake"` — UPPER_SNAKE_CASE key derived solely from the text value:
+     *     "Save Changes" → `SAVE_CHANGES`
+     *     "Max Count"  → `MAX_COUNT`
+     */
+    keyStyle?: KeyStyle;
+    /**
+     * 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 +45,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,15 +210,22 @@ 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;
   }
   addDetected(text, line, column, context, nodeType) {
-    const key = (0, import_ai_localize_shared.generateLocaleKey)(
+    const key = (0, import_ai_localize_shared.generateKeyByStyle)(
       this.options.filePath,
       text,
-      this.options.sourceRoot || "src"
+      this.options.sourceRoot || "src",
+      this.options.keyStyle || "path"
     );
     this.detectedTexts.push({
       filePath: this.options.filePath,
@@ -213,7 +256,12 @@ 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.generateKeyByStyle)(
+          this.options.filePath,
+          text,
+          this.options.sourceRoot || "src",
+          this.options.keyStyle || "path"
+        );
         results.push({
           filePath: this.options.filePath,
           line: idx + 1,
@@ -229,6 +277,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 +455,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 +465,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 +523,13 @@ 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,
+      keyStyle: this.config.keyStyle ?? "path"
+    });
     const texts = scanner.scan();
     const { assets, legacyCdnUrls } = this.assetScanner.scanFile(filePath);
     this.cache?.setCachedResult(filePath, texts);

package/dist/index.mjs

@@ -6,9 +6,9 @@ import {
   isHumanReadableText,
   normalizeText,
   TEXT_ATTRIBUTE_NAMES,
-  generateLocaleKey
+  generateKeyByStyle
 } 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,15 +175,22 @@ 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;
   }
   addDetected(text, line, column, context, nodeType) {
-    const key = generateLocaleKey(
+    const key = generateKeyByStyle(
       this.options.filePath,
       text,
-      this.options.sourceRoot || "src"
+      this.options.sourceRoot || "src",
+      this.options.keyStyle || "path"
     );
     this.detectedTexts.push({
       filePath: this.options.filePath,
@@ -178,7 +221,12 @@ 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 = generateKeyByStyle(
+          this.options.filePath,
+          text,
+          this.options.sourceRoot || "src",
+          this.options.keyStyle || "path"
+        );
         results.push({
           filePath: this.options.filePath,
           line: idx + 1,
@@ -194,6 +242,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 +420,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 +430,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 +488,13 @@ 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,
+      keyStyle: this.config.keyStyle ?? "path"
+    });
     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.3",
   "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.3",
+    "ai-localize-config": "2.0.3"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.20.5",

package/src/ast-scanner.ts

@@ -2,21 +2,56 @@ 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, KeyStyle } from 'ai-localize-shared';
 import {
   isHumanReadableText,
   normalizeText,
   TEXT_ATTRIBUTE_NAMES,
-  generateLocaleKey,
+  generateKeyByStyle,
 } from 'ai-localize-shared';
 
 export interface AstScanOptions {
   filePath: string;
   content: string;
   sourceRoot?: string;
+  /**
+   * Controls the format of the generated locale key for each detected text.
+ *
+   * - `"path"` (default) — hierarchical dot-notation key derived from file path + text:
+   *     `settings.settings_page.save_changes`
+   *
+   * - `"screaming_snake"` — UPPER_SNAKE_CASE key derived solely from the text value:
+   *     "Save Changes" → `SAVE_CHANGES`
+   *     "Max Count"  → `MAX_COUNT`
+   */
+  keyStyle?: KeyStyle;
+  /**
+   * 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',
@@ -29,10 +64,49 @@ 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[] {
@@ -40,24 +114,25 @@ export class AstScanner {
 
     let ast: t.File;
     try {
-ast = parser.parse(content, {
-        sourceType: 'module',
+      ast = parser.parse(content, {
+  sourceType: 'module',
         plugins: [
-  'jsx',
-      'typescript',
-       'decorators-legacy',
+          'jsx',
+ 'typescript',
+      'decorators-legacy',
           'classProperties',
      'optionalChaining',
-      'nullishCoalescingOperator',
-    'dynamicImport',
-          'exportDefaultFrom',
+     'nullishCoalescingOperator',
+       'dynamicImport',
+    'exportDefaultFrom',
         ],
         errorRecovery: true,
       });
-    } catch {
+ } catch {
       return this.regexFallbackScan();
     }
 
+    // Collect translation function names from imports before scanning text
     this.collectTranslationImports(ast);
 
     traverse(ast, {
@@ -66,30 +141,30 @@ ast = parser.parse(content, {
         if (!isHumanReadableText(text)) return;
         if (this.isInsideTranslationCall(nodePath)) return;
         this.addDetected(
-          text,
-          nodePath.node.loc?.start.line ?? 0,
-          nodePath.node.loc?.start.column ?? 0,
+    text,
+   nodePath.node.loc?.start.line ?? 0,
+    nodePath.node.loc?.start.column ?? 0,
           'jsx-text',
-'JSXText'
-        );
+          'JSXText'
+    );
       },
 
       JSXAttribute: (nodePath) => {
         const attrName = t.isJSXIdentifier(nodePath.node.name)
           ? nodePath.node.name.name
-        : '';
-    if (!TEXT_ATTRIBUTE_NAMES.has(attrName.toLowerCase())) return;
+          : '';
+        if (!TEXT_ATTRIBUTE_NAMES.has(attrName.toLowerCase())) return;
    const valueNode = nodePath.node.value;
-if (!t.isStringLiteral(valueNode)) return;
-      const text = normalizeText(valueNode.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);
-        this.addDetected(
-  text,
+        if (this.isInsideTranslationCall(nodePath)) return;
+        const context = this.mapAttrToContext(attrName);
+     this.addDetected(
+   text,
           valueNode.loc?.start.line ?? 0,
-        valueNode.loc?.start.column ?? 0,
-          context,
+  valueNode.loc?.start.column ?? 0,
+      context,
           'JSXAttribute'
         );
       },
@@ -97,83 +172,115 @@ if (!t.isStringLiteral(valueNode)) return;
       StringLiteral: (nodePath) => {
         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;
+  if (!isHumanReadableText(text)) return;
         this.addDetected(
           text,
-          nodePath.node.loc?.start.line ?? 0,
-          nodePath.node.loc?.start.column ?? 0,
+  nodePath.node.loc?.start.line ?? 0,
+       nodePath.node.loc?.start.column ?? 0,
           'string-literal',
-          'StringLiteral'
+   'StringLiteral'
         );
       },
 
- TemplateLiteral: (nodePath) => {
+      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,
+        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',
+          'template-literal',
           'TemplateLiteral'
-  );
-   },
+     );
+  },
     });
 
-    return this.detectedTexts;
+  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);
+   }
       }
     }
   }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+  /** 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;
-      if (t.isCallExpression(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.isIdentifier(callee) && this.translationFunctionNames.has(callee.name)) {
+     return true;
         }
- if (
-          t.isMemberExpression(callee) &&
+        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;
@@ -186,20 +293,21 @@ text,
     context: TextContext,
     nodeType: string
   ): void {
-    const key = generateLocaleKey(
-    this.options.filePath,
+    const key = generateKeyByStyle(
+  this.options.filePath,
       text,
-      this.options.sourceRoot || 'src'
+      this.options.sourceRoot || 'src',
+      this.options.keyStyle || 'path'
     );
     this.detectedTexts.push({
       filePath: this.options.filePath,
       line,
       column,
-text,
-      suggestedKey: key,
-    context,
-  nodeType,
-      alreadyTranslated: false,
+      text,
+    suggestedKey: key,
+      context,
+      nodeType,
+ alreadyTranslated: false,
     });
   }
 
@@ -217,24 +325,89 @@ text,
     const jsxTextRegex = />([^<>{}\n]+)</g;
     const lines = this.options.content.split('\n');
     lines.forEach((line, idx) => {
-      let m: RegExpExecArray | null;
- jsxTextRegex.lastIndex = 0;
+    let m: RegExpExecArray | null;
+  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 = generateKeyByStyle(
+          this.options.filePath,
+    text,
+          this.options.sourceRoot || 'src',
+          this.options.keyStyle || 'path'
+ );
         results.push({
-          filePath: this.options.filePath,
-     line: idx + 1,
+      filePath: this.options.filePath,
+    line: idx + 1,
           column: m.index,
-     text,
+        text,
  suggestedKey: key,
-        context: 'jsx-text',
+   context: 'jsx-text',
           nodeType: 'regex-fallback',
-   alreadyTranslated: false,
+ 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,36 +27,53 @@ 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')
+    this.cache = new IncrementalScanCache(
+        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 allLegacyUrls: LegacyCdnUrl[] = [];
 
-  const chunkSize = Math.max(
-  1,
-  Math.min(50, Math.ceil(filesToScan.length / (os.cpus().length || 4)))
+    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)));
+      const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
       for (const r of results) {
         allTexts.push(...r.texts);
         allAssets.push(...r.assets);
@@ -67,12 +84,12 @@ const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
     this.cache?.persist();
 
     return {
-  framework: this.config.framework,
-      scannedFiles: filesToScan.length,
+      framework: this.config.framework,
+   scannedFiles: filesToScan.length,
       detectedTexts: allTexts,
-    assets: allAssets,
+      assets: allAssets,
       legacyCdnUrls: allLegacyUrls,
-    duration: Date.now() - startTime,
+      duration: Date.now() - startTime,
       timestamp: new Date().toISOString(),
     };
   }
@@ -89,14 +106,25 @@ const results = await Promise.all(chunk.map((f) => this.scanFile(f)));
 
     let content: string;
     try {
-      const { readFileSync } = await import('fs');
-      content = readFileSync(filePath, 'utf-8');
+   const { readFileSync } = await import('fs');
+   content = readFileSync(filePath, 'utf-8');
     } catch {
       return { texts: [], assets: [], legacyUrls: [] };
- }
+    }
 
-    const scanner = new AstScanner({ filePath, content, sourceRoot: this.config.sourceDir });
-    const texts = scanner.scan();
+    // 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.
+    // keyStyle controls whether keys are path-based (default) or SCREAMING_SNAKE.
+    const scanner = new AstScanner({
+      filePath,
+      content,
+      sourceRoot: this.sourceRoot,
+      codemodConfig: this.config.codemods,
+      keyStyle: this.config.keyStyle ?? 'path',
+    });
+  const texts = scanner.scan();
     const { assets, legacyCdnUrls } = this.assetScanner.scanFile(filePath);
 
     this.cache?.setCachedResult(filePath, texts);