ai-localize-scanner 2.0.5 → 2.0.7

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # ai-localize-scanner
 
+## 2.0.7
+
+### Minor Changes
+
+- **CSS/utility class filtering in `AstScanner`**:
+  - New `NON_TRANSLATABLE_ATTR_NAMES` set: JSX attributes like `type`, `role`, `method`,
+    `href`, `src`, `rel`, `target`, `id`, `name`, and 20+ others are now skipped.
+  - New `NON_TRANSLATABLE_PROP_KEYS` set: object property values are skipped when the key
+    is a CSS-in-JS property (`fontFamily`, `color`, `display`, etc.) or structural prop.
+  - New `CSS_UTILITY_FN_NAMES` set: string literals inside calls to `clsx`, `cx`, `cn`,
+    `twMerge`, `twJoin`, `classnames`, `styled`, `css`, etc. are now skipped.
+  - `isCssClassString()` applied to every candidate string.
+  - Centralised `isTranslatableText()` private method applies all checks + `ignoreTextPatterns`.
+- **`ignoreTextPatterns` config support** — user-defined regex patterns applied per scan.
+- `regexFallbackScan()` updated to use the same `isTranslatableText()` pipeline.
+- `ProjectScanner` passes `config.ignoreTextPatterns` to `AstScanner`.
+- Added `repository`, `homepage`, `bugs`, `author` fields to `package.json` for npm registry display.
+- Added `sideEffects: false` to enable tree-shaking in bundlers.
+- Added `prepublishOnly` script to ensure the package is built before publishing.
+
+## 2.0.6
+
+### Patch Changes
+
+- Add per-package README.md files so each package displays documentation on npmjs.com
+- Update README version badge to 2.0.6
+
 ## 2.0.3
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 ai-localize-core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# ai-localize-scanner
+
+> Babel AST-based hardcoded text detection + asset scanner for the [ai-localize-core](https://github.com/ai-localize/ai-localize-core) platform.
+
+[![npm version](https://img.shields.io/npm/v/ai-localize-scanner.svg)](https://www.npmjs.com/package/ai-localize-scanner)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## What it does
+
+- Parses JS/TS/JSX/TSX/Vue/Angular source files with `@babel/parser`
+- Detects hardcoded strings in JSX text, attributes, string literals, template literals
+- Skips strings already inside translation calls (`t()`, `useTranslation`, custom hooks)
+- Detects static asset references (images, fonts, CSS, JS)
+- Finds legacy CDN URLs for migration
+- Supports **incremental scanning** (git-aware file hashing cache)
+- Generates deterministic `suggestedKey` for every detected string
+
+## Installation
+
+```bash
+npm install ai-localize-scanner
+```
+
+## Usage
+
+```ts
+import { ProjectScanner } from 'ai-localize-scanner';
+
+const scanner = new ProjectScanner({
+  framework: 'react-vite',
+  sourceDir: 'src',
+  localesDir: 'locales',
+  defaultLanguage: 'en',
+  targetLanguages: ['fr', 'de'],
+});
+
+const result = await scanner.scan();
+// result.detectedTexts — array of DetectedText
+// result.assets         — array of AssetReference
+// result.legacyCdnUrls  — array of LegacyCdnUrl
+// result.scannedFiles   — number of files processed
+// result.duration       — scan time in ms
+```
+
+## Detected text contexts
+
+`jsx-text` · `string-literal` · `jsx-attribute` · `placeholder` · `aria-label` · `title` · `alt` · `button` · `heading` · `label` · `validation` · `tooltip` · `table-header` · `modal` · `toast` · `alert` · `template-literal` · `object-value` · `array-item`
+
+## Key generation
+
+Keys are generated deterministically from file path + text:
+
+```
+src/pages/dashboard/Banner.tsx + "Welcome to the Dashboard"
+  → pages.dashboard.banner.welcome_to_the_dashboard
+```
+
+Set `keyStyle: "screaming_snake"` for UPPER_SNAKE_CASE keys:
+```
+"Save Changes" → SAVE_CHANGES
+```
+
+## Incremental scanning
+
+Enable with `incrementalCache: true` (default). File hashes are stored in `.ai-localize-cache/scan-cache.json`. Only changed files are re-scanned on subsequent runs.
+
+---
+
+## Part of ai-localize-core
+
+Install the CLI for the complete toolset: `npm install -g ai-localize-cli`
+
+MIT © ai-localize-core contributors

package/dist/index.d.mts

@@ -6,38 +6,27 @@ interface AstScanOptions {
     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`
+     *     "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.
+     * the project uses a custom i18n library or a locally-defined hook.
      */
     codemodConfig?: CodemodConfig;
+    /**
+     * Additional regex patterns (as strings) from config.ignoreTextPatterns.
+     * Any scanned string matching at least one pattern is excluded.
+     */
+    ignoreTextPatterns?: string[];
 }
 /**
  * Scans a JS/TS/JSX/TSX file using Babel AST to find hardcoded text.
@@ -45,6 +34,7 @@ interface AstScanOptions {
 declare class AstScanner {
     private options;
     private detectedTexts;
+    private compiledIgnorePatterns;
     /** Identifiers whose call/bracket expressions contain already-translated strings. */
     private translationFunctionNames;
     /**
@@ -55,6 +45,16 @@ declare class AstScanner {
     private importSourceMatchers;
     constructor(options: AstScanOptions);
     scan(): DetectedText[];
+    /**
+     * Central check: is this text worth extracting as a locale key?
+     * Applies isHumanReadableText(), isCssClassString(), and user ignoreTextPatterns.
+     */
+    private isTranslatableText;
+    /**
+     * Returns true when the node path is inside a CSS utility function call:
+     * clsx("a", "b"), cn("x"), twMerge("foo", "bar"), styled("div"), etc.
+     */
+    private isInsideCssUtilityCall;
     /**
      * Walk import declarations; when the source matches a known translation
      * import, collect all named/default imports as translation function names.
@@ -83,7 +83,14 @@ declare class AssetScanner {
 declare class IncrementalScanCache {
     private cachePath;
     private cache;
-    constructor(cacheDir: string);
+    /**
+     * @param cacheDir   Directory where `scan-cache.json` is stored.
+     * @param configHash SHA-256 hash of the resolved config object.
+     *                   When this differs from the persisted value the entire
+     *                   cache is invalidated so that config changes (keyStyle,
+     *                   ignoreTextPatterns, codemods, etc.) are always reflected.
+     */
+    constructor(cacheDir: string, configHash?: string);
     private load;
     isFileChanged(filePath: string): boolean;
     getCachedResult(filePath: string): DetectedText[] | null;
@@ -103,6 +110,16 @@ declare class ProjectScanner {
     private cache?;
     private assetScanner;
     constructor(config: LocalizationConfig);
+    /**
+     * Produces a stable SHA-256 fingerprint of the config fields that affect
+     * scan output.  When any of these change the incremental cache is fully
+     * invalidated so the next run re-scans every file with the new settings.
+     *
+     * Fields intentionally excluded: `incrementalCache`, `cacheDir`, `aws`,
+     * `plugins` — none of those influence what text the AST scanner detects
+     * or how keys are generated.
+     */
+    private hashConfig;
     scan(options?: ScanOptions): Promise<ScanResult>;
     private scanFile;
     private chunkArray;

package/dist/index.d.ts

@@ -6,38 +6,27 @@ interface AstScanOptions {
     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`
+     *     "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.
+     * the project uses a custom i18n library or a locally-defined hook.
      */
     codemodConfig?: CodemodConfig;
+    /**
+     * Additional regex patterns (as strings) from config.ignoreTextPatterns.
+     * Any scanned string matching at least one pattern is excluded.
+     */
+    ignoreTextPatterns?: string[];
 }
 /**
  * Scans a JS/TS/JSX/TSX file using Babel AST to find hardcoded text.
@@ -45,6 +34,7 @@ interface AstScanOptions {
 declare class AstScanner {
     private options;
     private detectedTexts;
+    private compiledIgnorePatterns;
     /** Identifiers whose call/bracket expressions contain already-translated strings. */
     private translationFunctionNames;
     /**
@@ -55,6 +45,16 @@ declare class AstScanner {
     private importSourceMatchers;
     constructor(options: AstScanOptions);
     scan(): DetectedText[];
+    /**
+     * Central check: is this text worth extracting as a locale key?
+     * Applies isHumanReadableText(), isCssClassString(), and user ignoreTextPatterns.
+     */
+    private isTranslatableText;
+    /**
+     * Returns true when the node path is inside a CSS utility function call:
+     * clsx("a", "b"), cn("x"), twMerge("foo", "bar"), styled("div"), etc.
+     */
+    private isInsideCssUtilityCall;
     /**
      * Walk import declarations; when the source matches a known translation
      * import, collect all named/default imports as translation function names.
@@ -83,7 +83,14 @@ declare class AssetScanner {
 declare class IncrementalScanCache {
     private cachePath;
     private cache;
-    constructor(cacheDir: string);
+    /**
+     * @param cacheDir   Directory where `scan-cache.json` is stored.
+     * @param configHash SHA-256 hash of the resolved config object.
+     *                   When this differs from the persisted value the entire
+     *                   cache is invalidated so that config changes (keyStyle,
+     *                   ignoreTextPatterns, codemods, etc.) are always reflected.
+     */
+    constructor(cacheDir: string, configHash?: string);
     private load;
     isFileChanged(filePath: string): boolean;
     getCachedResult(filePath: string): DetectedText[] | null;
@@ -103,6 +110,16 @@ declare class ProjectScanner {
     private cache?;
     private assetScanner;
     constructor(config: LocalizationConfig);
+    /**
+     * Produces a stable SHA-256 fingerprint of the config fields that affect
+     * scan output.  When any of these change the incremental cache is fully
+     * invalidated so the next run re-scans every file with the new settings.
+     *
+     * Fields intentionally excluded: `incrementalCache`, `cacheDir`, `aws`,
+     * `plugins` — none of those influence what text the AST scanner detects
+     * or how keys are generated.
+     */
+    private hashConfig;
     scan(options?: ScanOptions): Promise<ScanResult>;
     private scanFile;
     private chunkArray;