ai-localize-cli 2.0.5 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ai-localize-cli
 
+## 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.5
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,537 @@
+# ai-localize-core
+
+> Enterprise-grade deterministic localization + CloudFront CDN migration platform for React, Vue, and Angular.
+
+**No AI. No cloud API. Fully offline. Reproducible outputs.**
+
+[![npm version](https://img.shields.io/npm/v/ai-localize-cli.svg)](https://www.npmjs.com/package/ai-localize-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Version](https://img.shields.io/badge/version-2.0.5-blue)](CHANGELOG.md)
+
+---
+
+## What's New in v2.0.5
+
+| Fix | Details |
+|---|---|
+| **`validate` always returned "valid"** | `MissingKeyValidator` now correctly detects keys where the target language value equals the English source placeholder. These are seeded automatically by `extract` and must be replaced with real translations. Error message: `Missing translation for "key" in "fr" (value equals source)` |
+| **`full-migrate` appeared to only generate a report** | `staticKeys` from config is now wired through to the extractor. `--dry-run` now shows a full preview. Validation and report are correctly skipped in dry-run mode. |
+| **`report` crashed with `RangeError: Invalid count value`** | Coverage % went negative when all keys were untranslated (missingKeys counted per-language). Now clamped to `[0, 100]`. All bar renderers guard against negative `String.repeat()`. |
+
+---
+
+## What it does
+
+`ai-localize-core` automates the full localization lifecycle using static AST analysis:
+
+1. **Scan** — finds every hardcoded UI string in your source code
+2. **Extract** — generates deterministic locale JSON files (`en.json`, `fr.json`, …)
+3. **Codemod** — injects `useTranslation()` and wraps strings with `t('key')` automatically
+4. **Validate** — catches missing, unused, duplicate, and placeholder-mismatch keys
+5. **Report** — produces a comprehensive HTML report with legends and full details
+6. **CDN Migrate** — uploads assets to S3, replaces legacy CDN URLs with CloudFront paths
+
+---
+
+## Supported Frameworks
+
+| Framework | Detection | Codemods | Default i18n Library |
+|---|---|---|---|
+| React (CRA, Vite, Next.js) | ✅ | ✅ | `react-i18next` |
+| Angular (ngx-translate, i18n) | ✅ | ✅ | `@ngx-translate/core` |
+| Vue 3 (vue-i18n) | ✅ | ✅ | `vue-i18n` |
+| jQuery / Vanilla JS | ✅ | — | — |
+| JSP | ✅ | — | — |
+| Custom hook (any architecture) | ✅ | ✅ | configurable |
+
+---
+
+## Installation
+
+```bash
+# Global install (gives you the `ai-localize` command everywhere)
+npm install -g ai-localize-cli
+
+# Or as a project dev dependency
+npm install --save-dev ai-localize-cli
+
+# Or use without installing
+npx ai-localize-cli <command>
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize — creates ai-localize.config.json with all options
+cd your-project
+npx ai-localize init
+
+# 2. Scan for hardcoded text
+npx ai-localize scan
+
+# 3. Extract locale files
+npx ai-localize extract
+# → locales/en/translation.json, locales/fr/translation.json …
+
+# 4. Preview codemods (dry run first!)
+npx ai-localize full-migrate --dry-run
+
+# 5. Apply codemods
+npx ai-localize full-migrate
+
+# 6. Validate locale files
+npx ai-localize validate
+
+# 7. Generate HTML report
+npx ai-localize report
+# → .ai-localize-reports/report-2026-05-26T12-00-00.html
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `ai-localize init` | Initialize config with auto-detected framework + all fields |
+| `ai-localize scan` | Scan source for hardcoded text + asset references |
+| `ai-localize extract` | Generate locale JSON files |
+| `ai-localize validate` | Check for missing / unused / duplicate / placeholder-mismatch keys. Also flags keys whose target value still equals the English source (un-translated placeholders seeded by `extract`). |
+| `ai-localize cleanup` | Remove unused locale keys |
+| `ai-localize report` | Generate a comprehensive HTML report |
+| `ai-localize full-migrate` | Run the full pipeline: scan → extract → codemod → validate → report |
+| `ai-localize migrate-cdn` | Upload assets to S3 + replace legacy CDN URLs + invalidate CloudFront |
+| `ai-localize upload-assets` | Upload static assets to S3 |
+| `ai-localize replace-cdn` | Replace legacy CDN URLs using an existing asset manifest |
+
+### Common options (all commands)
+
+| Option | Description |
+|---|---|
+| `--cwd <path>` | Working directory (default: `process.cwd()`) |
+| `--dry-run` | Preview changes without writing files |
+
+### `scan` options
+
+| Option | Description |
+|---|---|
+| `--incremental` | Only scan git-changed files |
+| `--staged` | Only scan git-staged files |
+| `--output <path>` | Save full scan results as JSON |
+| `--extract-cdns <path>` | Save discovered CDN/legacy URLs to JSON |
+
+### `report` options
+
+| Option | Description |
+|---|---|
+| `--output-dir <path>` | Report directory (default: `.ai-localize-reports`) |
+| `--filename <name>` | Custom filename (default: `report-<timestamp>.html`) |
+
+### `full-migrate` options
+
+| Option | Description |
+|---|---|
+| `--no-codemods` | Skip codemod injection phase |
+| `--no-report` | Skip HTML report generation |
+| `--report-dir <path>` | Report directory (default: `.ai-localize-reports`) |
+
+---
+
+## Configuration
+
+Running `npx ai-localize init` creates `ai-localize.config.json` with every field included:
+
+```json
+{
+  "framework": "react-vite",
+  "defaultLanguage": "en",
+  "targetLanguages": ["fr", "de"],
+  "sourceDir": "src",
+  "localesDir": "locales",
+  "localeStructure": "nested",
+  "ignorePatterns": ["node_modules", "dist", ".git", "coverage"],
+  "includePatterns": [],
+  "keyPrefix": "",
+  "namespaces": [],
+  "incrementalCache": true,
+  "cacheDir": ".ai-localize-cache",
+  "codemods": {
+    "importPackage": "react-i18next",
+    "hookName": "useTranslation",
+    "translationFunction": "t",
+    "namespace": "",
+    "accessorStyle": "function"
+  },
+  "aws": {
+    "region": "us-east-1",
+    "bucket": "",
+    "distributionId": "",
+    "cdnBaseUrl": "",
+    "legacyCdnPattern": "",
+    "assetsPrefix": "assets",
+    "profile": ""
+  },
+  "plugins": []
+}
+```
+
+### Config field reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `framework` | string | `"unknown"` | Framework — controls which codemod runs. Values: `"react"` `"react-cra"` `"react-vite"` `"react-nextjs"` `"angular"` `"angular-ngx"` `"angular-i18n"` `"vue"` `"vue-i18n"` `"jquery"` `"vanilla-js"` `"jsp"` `"unknown"` |
+| `defaultLanguage` | string | `"en"` | Source language code (any BCP-47 tag) |
+| `targetLanguages` | string[] | `[]` | Languages to generate locale files for |
+| `sourceDir` | string | `"src"` | Root directory to scan |
+| `localesDir` | string | `"locales"` | Where locale files are written |
+| `localeStructure` | `"nested"` \| `"flat"` | `"nested"` | `"nested"` — one file per language+namespace (`locales/en/translation.json`). `"flat"` — one file per language, all keys merged (`locales/en.json`) |
+| `keyStyle` | `"path"` \| `"screaming_snake"` | `"path"` | `"path"` — hierarchical dot-notation from file path + text: `settings.page.save_changes`. `"screaming_snake"` — UPPER_SNAKE_CASE from text value: `"Save Changes"` → `SAVE_CHANGES` |
+| `staticKeys` | object | `{}` | Key/value pairs injected into every locale file regardless of scanning. Use for enum labels, status codes, or strings not hardcoded in source files. Example: `{"MAX_COUNT":"Max Count","ALLOWED":"Allowed"}` |
+| `ignorePatterns` | string[] | `["node_modules","dist",…]` | Dirs/patterns to skip |
+| `includePatterns` | string[] | — | If set, only scan matching files (supports `*` and `**` globs) |
+| `keyPrefix` | string | — | Prefix added to every generated key (e.g. `"myapp"` → `"myapp.components.button.save"`) |
+| `namespaces` | string[] | — | Explicit namespace list. If omitted, derived from first path segment after `sourceDir` |
+| `incrementalCache` | boolean | `true` | Cache file hashes for faster re-runs |
+| `cacheDir` | string | `".ai-localize-cache"` | Cache directory |
+| `codemods` | object | — | Codemod injection options (see below) |
+| `aws` | object | — | AWS S3 + CloudFront settings |
+| `plugins` | string[] | `[]` | Custom plugin module paths |
+
+---
+
+## Locale File Layout
+
+### `localeStructure: "nested"` (default)
+
+```
+locales/
+  en/
+    common.json
+    dashboard.json
+  fr/
+    common.json
+    dashboard.json
+```
+
+### `localeStructure: "flat"`
+
+```
+locales/
+  en.json    ← all namespaces merged
+  fr.json
+```
+
+Set in config:
+```json
+{ "localeStructure": "flat" }
+```
+
+---
+
+## Codemod Configuration
+
+The `codemods` block controls what code is injected. All fields are optional with framework-specific defaults.
+
+| Field | Default | Description |
+|---|---|---|
+| `importPackage` | `"react-i18next"` | npm package **or** project-relative path (e.g. `"src/hooks/useTranslation"`) |
+| `hookName` | `"useTranslation"` | Hook function to import and call |
+| `translationFunction` | `"t"` | Accessor destructured from the hook |
+| `namespace` | — | Argument to the hook: `useTranslation("common")` |
+| `accessorStyle` | `"function"` | `"function"` → `t('key')` · `"bracket"` → `t['key']` |
+
+### Standard react-i18next
+
+```json
+{
+  "codemods": {
+    "importPackage": "react-i18next",
+    "hookName": "useTranslation",
+    "translationFunction": "t"
+  }
+}
+```
+
+Injects:
+```tsx
+import { useTranslation } from 'react-i18next';
+// inside component:
+const { t } = useTranslation();
+return <h1>{t('header.welcome')}</h1>;
+```
+
+### Custom local hook (per-file path resolution)
+
+```json
+{
+  "codemods": {
+    "importPackage": "src/hooks/useTranslation",
+ "hookName": "useTranslation",
+    "translationFunction": "t"
+  }
+}
+```
+
+The codemod automatically computes the correct relative path **per file**:
+
+| File | Injected import |
+|---|---|
+| `src/App.tsx` | `import { useTranslation } from './hooks/useTranslation'` |
+| `src/components/Button.tsx` | `import { useTranslation } from '../../hooks/useTranslation'` |
+| `src/pages/dashboard/Header.tsx` | `import { useTranslation } from '../../../hooks/useTranslation'` |
+
+### Bracket notation
+
+```json
+{
+  "codemods": {
+    "accessorStyle": "bracket"
+  }
+}
+```
+
+Generates `t['some.key']` instead of `t('some.key')`.
+
+---
+
+## Scanner: Recognising Custom Translation Calls
+
+Set `codemods.importPackage` and the scanner will automatically skip strings already wrapped by your custom hook — they won't be re-reported as hardcoded text.
+
+**Supported import path formats:**
+
+| Format | Example |
+|---|---|
+| npm package | `"react-i18next"` |
+| Scoped npm package | `"@angular/core"` |
+| Project-relative path | `"src/hooks/useTranslation"` |
+| Path alias | `"@/hooks/useTranslation"` |
+| Relative path | `"../../hooks/useTranslation"` |
+
+All relative/alias forms match by **tail segment comparison**, so `hooks/useTranslation` matches `../../hooks/useTranslation`, `./hooks/useTranslation`, and `@/hooks/useTranslation`.
+
+---
+
+## HTML Report
+
+Running `npx ai-localize report` generates a self-contained HTML file:
+
+```bash
+npx ai-localize report
+# → .ai-localize-reports/report-2026-05-26T12-00-00.html
+
+npx ai-localize report --output-dir ./audit --filename localization-audit.html
+```
+
+The report contains:
+- **8 summary cards** — Files Scanned, Hardcoded Texts, Keys Generated, Missing Translations, Unused Keys, Assets Found, Assets Uploaded, Legacy CDN URLs
+- **Explainer box** — why Hardcoded Texts and Keys Generated may differ
+- **Hardcoded Texts table** — file, line, text, suggested key, context
+- **Missing Translations table** — key, language, file, message
+- **Unused Keys table** — keys to clean up
+- **Assets table** — uploaded asset paths, S3 keys, CloudFront URLs
+- Each section has a **legend** explaining what the data means and what action to take
+
+---
+
+## AWS / CDN Migration
+
+Fill in the `aws` block in your config (or use environment variables):
+
+```json
+{
+  "aws": {
+ "region": "us-east-1",
+    "bucket": "my-assets-bucket",
+    "distributionId": "E1ABCDEFGHIJKL",
+    "cdnBaseUrl": "https://d123.cloudfront.net",
+    "legacyCdnPattern": "https://old-legacy-cdn.company.com",
+    "assetsPrefix": "static-assets/v1"
+  }
+}
+```
+
+Or via `.env`:
+```bash
+AWS_S3_BUCKET=my-assets-bucket
+AWS_CF_DISTRIBUTION_ID=E1ABCDEFGHIJKL
+AI_LOCALIZE_CDN_BASE_URL=https://d123.cloudfront.net
+AI_LOCALIZE_LEGACY_CDN_PATTERN=https://old-legacy-cdn.company.com
+```
+
+One-step CDN migration:
+```bash
+npx ai-localize migrate-cdn --assets-dir ./public --invalidate
+```
+
+---
+
+## Before / After Example
+
+**Before:**
+```tsx
+export const Banner = () => (
+  <div>
+    <h1>Welcome to the Dashboard</h1>
+    <p>Manage your campaigns easily.</p>
+    <button>Get Started</button>
+  </div>
+);
+```
+
+**After `npx ai-localize full-migrate`:**
+```tsx
+import { useTranslation } from 'react-i18next';
+
+export const Banner = () => {
+  const { t } = useTranslation();
+  return (
+    <div>
+      <h1>{t('banner.welcome_to_the_dashboard')}</h1>
+      <p>{t('banner.manage_your_campaigns_easily')}</p>
+    <button>{t('banner.get_started')}</button>
+    </div>
+  );
+};
+```
+
+**Generated `locales/en/common.json`:**
+```json
+{
+  "banner.get_started": "Get Started",
+  "banner.manage_your_campaigns_easily": "Manage your campaigns easily.",
+  "banner.welcome_to_the_dashboard": "Welcome to the Dashboard"
+}
+```
+
+**Generated `locales/fr/common.json`** (seeded with English values for translators):
+```json
+{
+  "banner.get_started": "Get Started",
+  "banner.manage_your_campaigns_easily": "Manage your campaigns easily.",
+  "banner.welcome_to_the_dashboard": "Welcome to the Dashboard"
+}
+```
+
+> **Tip — run `validate` after seeding:** New target-language entries are seeded with
+> the English source value. `ai-localize validate` flags these as
+> `"Missing translation (value equals source)"` until real translations are provided.
+
+---
+
+## Key Generation
+
+Keys are generated deterministically from the file path + text:
+
+```
+src/pages/dashboard/Banner.tsx + "Welcome to the Dashboard"
+  → pages.dashboard.banner.welcome_to_the_dashboard
+```
+
+Format: `<folder>.<folder>.<component>.<slugified_text>`
+
+- Relative to `sourceDir`
+- CamelCase segments are snake_cased
+- Text is lowercased, punctuation stripped, spaces replaced with `_`, truncated to 60 chars
+- Duplicate strings across files share the same key
+
+---
+
+## Programmatic API
+
+```ts
+import { ProjectScanner } from 'ai-localize-scanner';
+import { LocaleExtractor, LocaleWriter } from 'ai-localize-locale-engine';
+import { CodemodRunner } from 'ai-localize-codemods';
+import { LocaleValidator } from 'ai-localize-validators';
+import { buildReport, generateHtmlReport } from 'ai-localize-reporting';
+
+const config = {
+  framework: 'react-vite',
+  defaultLanguage: 'en',
+  targetLanguages: ['fr'],
+  sourceDir: 'src',
+  localesDir: 'locales',
+};
+
+// Scan
+const scanner = new ProjectScanner(config);
+const scanResult = await scanner.scan();
+
+// Extract
+const extractor = new LocaleExtractor({ defaultLanguage: 'en', targetLanguages: ['fr'] });
+const { localeFiles } = extractor.extract(scanResult.detectedTexts);
+
+// Write
+const writer = new LocaleWriter({ localesDir: './locales' });
+writer.write(localeFiles);
+
+// Validate
+const validator = new LocaleValidator({ localesDir: './locales', sourceDir: './src', defaultLanguage: 'en', targetLanguages: ['fr'] });
+const validation = validator.validate();
+
+// Report
+const report = buildReport({ scanResult, validationResult: validation });
+generateHtmlReport(report, './report.html');
+```
+
+---
+
+## Monorepo Packages
+
+| Package | npm install | Description |
+|---|---|---|
+| `ai-localize-shared` | `npm i ai-localize-shared` | Shared types, utilities, constants |
+| `ai-localize-config` | `npm i ai-localize-config` | Config loading + Zod validation |
+| `ai-localize-framework-detectors` | `npm i ai-localize-framework-detectors` | Auto-detect React / Angular / Vue |
+| `ai-localize-scanner` | `npm i ai-localize-scanner` | Babel AST scanner + incremental scanning |
+| `ai-localize-codemods` | `npm i ai-localize-codemods` | React / Vue / Angular i18n injection |
+| `ai-localize-locale-engine` | `npm i ai-localize-locale-engine` | Locale file extraction, writing, merging |
+| `ai-localize-validators` | `npm i ai-localize-validators` | Missing / unused / duplicate key validation |
+| `ai-localize-aws-cloudfront` | `npm i ai-localize-aws-cloudfront` | S3 upload + CloudFront invalidation |
+| `ai-localize-reporting` | `npm i ai-localize-reporting` | HTML + CLI report generation |
+| `ai-localize-cli` | `npm i -g ai-localize-cli` | Full CLI (`ai-localize` command) |
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Localization check
+  run: |
+    npx ai-localize scan
+    npx ai-localize validate
+    npx ai-localize report --output-dir ./reports
+```
+
+### Pre-commit hook
+
+```bash
+npx ai-localize scan --staged
+npx ai-localize validate
+```
+
+---
+
+## Full Documentation
+
+See [`INSTRUCTION_GUIDE.md`](INSTRUCTION_GUIDE.md) for the complete developer guide including:
+- All CLI options with examples
+- Full config field reference
+- Codemod config deep-dive
+- Custom hook integration
+- Locale layout options
+- CDN migration walkthrough
+- HTML report guide
+- Troubleshooting
+
+---
+
+## License
+
+MIT © ai-localize-core contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-cli",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "CLI for ai-localize-core: scan, extract, validate, codemod and migrate CDN",
   "bin": {
     "ai-localize": "./dist/cli.js"
@@ -35,15 +35,15 @@
     "chalk": "^5.3.0",
     "ora": "^8.0.1",
     "inquirer": "^9.2.12",
-    "ai-localize-shared": "2.0.5",
-    "ai-localize-config": "2.0.5",
-    "ai-localize-codemods": "2.0.5",
-    "ai-localize-framework-detectors": "2.0.5",
-    "ai-localize-scanner": "2.0.5",
-    "ai-localize-locale-engine": "2.0.5",
-    "ai-localize-validators": "2.0.5",
-    "ai-localize-aws-cloudfront": "2.0.5",
-    "ai-localize-reporting": "2.0.5"
+    "ai-localize-shared": "2.0.6",
+    "ai-localize-framework-detectors": "2.0.6",
+    "ai-localize-codemods": "2.0.6",
+    "ai-localize-locale-engine": "2.0.6",
+    "ai-localize-scanner": "2.0.6",
+    "ai-localize-config": "2.0.6",
+    "ai-localize-validators": "2.0.6",
+    "ai-localize-reporting": "2.0.6",
+    "ai-localize-aws-cloudfront": "2.0.6"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.7",