📦 ngx-i18n-scan

June 23, 2025 · View on GitHub

A powerful and user-friendly CLI tool for managing internationalization (i18n) in Angular projects. It scans source code to extract translation keys, updates translation JSON files, and detects/replaces hardcoded text, ensuring your application is ready for global audiences.

✨ Features

✅ Extract Translation Keys: Automatically extracts i18n keys from Angular source files (.ts, .html).
🛠 Manage Missing Keys: Adds missing keys to translation JSON files with "TODO" values.
🧹 Clean Unused Keys: Detects and removes unused translation keys from JSON files.
🔁 Handle Duplicates: Identifies and removes duplicate keys in JSON files.
🔍 Hardcoded Text Detection: Scans .html and .component.ts files for hardcoded strings in UI elements and components (e.g., Swal.fire properties like title, confirmButtonText).
🌍 Automatic Text Replacement: Replaces hardcoded strings with @ngx-translate/core translation keys (e.g., this.translateService.instant('text.key') in TypeScript, {{ 'text.key' | translate }} in HTML).
📋 Detailed Summary: Provides a clear report of present, new, unused, and duplicate keys, plus hardcoded text findings.

📋 Prerequisites

Node.js: Version 14 or higher.
Angular: Version 10 or higher (compatible with NgModule-based and standalone components).
@ngx-translate/core: Required for hardcoded text replacement.
Translation JSON: A JSON file (e.g., src/assets/i18n/en.json) for storing translation keys and values.

📦 Installation

Install the CLI tool globally:
```
npm install -g ngx-i18n-scan
```

Install @ngx-translate/core in your Angular project:

npm install @ngx-translate/core @ngx-translate/http-loader --save

Configure @ngx-translate/core in your Angular application:

For Angular < 17 (NgModule-based): Update src/app/app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { HttpClientModule, HttpClient } from '@angular/common/http';
import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
import { AppComponent } from './app.component';

export function HttpLoaderFactory(http: HttpClient) {
    return new TranslateHttpLoader(http, './assets/i18n/', '.json');
}

@NgModule({
    declarations: [AppComponent],
    imports: [
        BrowserModule,
        HttpClientModule,
        TranslateModule.forRoot({
            loader: {
                provide: TranslateLoader,
                useFactory: HttpLoaderFactory,
                deps: [HttpClient]
            }
        })
    ],
    bootstrap: [AppComponent]
})
export class AppModule {}

For Angular 17+ (Standalone Components): Update src/app/app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideHttpClient } from '@angular/common/http';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
import { provideTranslateService } from '@ngx-translate/core';

export const appConfig: ApplicationConfig = {
    providers: [
        provideHttpClient(),
        provideTranslateService({
            loader: {
                provide: TranslateHttpLoader,
                useFactory: (http: HttpClient) => new TranslateHttpLoader(http, './assets/i18n/', '.json'),
                deps: [HttpClient]
            }
        })
    ]
};

Initialize the default language in src/app/app.component.ts:

import { Component } from '@angular/core';
import { TranslateService } from '@ngx-translate/core';

@Component({
    selector: 'app-root',
    standalone: true,
    template: `...`
})
export class AppComponent {
    constructor(translate: TranslateService) {
        translate.setDefaultLang('en');
        translate.use('en');
    }
}

Ensure a translation JSON file exists (e.g., src/assets/i18n/en.json):
```
{}
```

🚀 Usage

Run the CLI with the following command:

ngx-i18n-scan [options]

The tool automatically detects:

Source Directory: Defaults to ./src in the project root.
Translation JSON: Searches for i18n folders and prompts you to select a JSON file if multiple are found.

You can manually specify paths using --src and --json to override automatic detection.

Examples

Automatic Detection:

ngx-i18n-scan --detect-hardcoded --replace-hardcoded

Manual Paths:

ngx-i18n-scan --src ./src --json ./assets/i18n/en.json --detect-hardcoded --replace-hardcoded

⚙️ Available Options

Flag	Description
`--src <path>`	Path to your Angular source directory (default: `./src`).
`--json <path>`	Path to your translation JSON file (e.g., `en.json`).
`--add-missing`	Automatically add missing keys to the JSON with `"TODO"` values.
`--list-missing`	List missing keys not found in the JSON file.
`--remove-unused`	Remove unused translation keys from the JSON file.
`--list-unused`	List unused keys found in the JSON file.
`--remove-duplicates`	Remove duplicate keys from the JSON file.
`--list-duplicates`	List duplicate keys found in the JSON file.
`--detect-hardcoded`	Detect hardcoded text in `.html` and `.component.ts` files.
`--replace-hardcoded`	Replace hardcoded text with translation keys (requires `--detect-hardcoded`).

🧪 Example Commands

✅ Detect and Replace Hardcoded Text (Automatic Detection)

Scans for hardcoded strings and replaces them with @ngx-translate/core keys:

ngx-i18n-scan --detect-hardcoded --replace-hardcoded

Output Example:

🔍 Found 4 hardcoded string(s):
1. Employee saved successfully! ➜ text.employee.saved.successfully
2. Okay ➜ text.okay
3. Welcome ➜ text.welcome
4. Enter name ➜ text.enter.name
💾 Updated src/app/pages/employees/add-update-employee/add-update-employee.component.ts
💾 Updated src/app/pages/employees/add-update-employee/add-update-employee.component.html
✅ Hardcoded text replaced and translation JSON updated.

Result:

TypeScript: Swal.fire({ title: 'Employee saved successfully!' }) → Swal.fire({ title: this.translateService.instant('text.employee.saved.successfully') })
HTML: <h1>Welcome</h1> → <h1>{{ 'text.welcome' | translate }}</h1>
JSON: Adds keys like "text.employee.saved.successfully": "Employee saved successfully!"

✅ Detect and Replace with Manual Paths

Same as above but with specified paths:

ngx-i18n-scan --src ./src --json ./assets/i18n/en.json --detect-hardcoded --replace-hardcoded

🛠 Add Missing Keys

Extracts keys from source and adds missing ones to JSON:

ngx-i18n-scan --add-missing

🧹 Remove Unused Keys

Removes keys from JSON that aren’t used in the source:

ngx-i18n-scan --remove-unused

🔁 List and Remove Duplicates

Identifies and removes duplicate keys in JSON:

ngx-i18n-scan --list-duplicates --remove-duplicates

📂 Output Format

Translation JSON: Uses a flat key structure with dot notation:

{
  "text.employee.saved.successfully": "Employee saved successfully!",
  "text.okay": "Okay",
  "text.welcome": "Welcome"
}

TypeScript Modifications (with --replace-hardcoded):
- Adds TranslateService import and constructor injection.
- Replaces hardcoded strings in Swal.fire properties (title, message, confirmButtonText, cancelButtonText, html) with this.translateService.instant('text.key').
HTML Modifications (with --replace-hardcoded):
- Replaces hardcoded text with {{ 'text.key' | translate }}.
- Updates placeholders with placeholder="{{ 'text.key' | translate }}".

📈 Output Summary

After execution, the CLI provides a detailed report:

📊 Summary Report:
- Present keys: 100
- New keys added: 20
- Unused keys: 5
- Duplicate keys: 2
✅ ngx-i18n-scan process completed.

For hardcoded text detection:

🔍 Found 4 hardcoded string(s):
1. Employee saved successfully! ➜ text.employee.saved.successfully
2. Okay ➜ text.okay
3. Welcome ➜ text.welcome
4. Enter name ➜ text.enter.name

🛠 Troubleshooting

No JSON file found: Ensure src/assets/i18n/en.json exists or use --json <path> to specify a file.
Source directory not found: Verify ./src exists or use --src <path> to specify a directory.
Hardcoded replacements not applied: Confirm @ngx-translate/core is installed and configured.
Formatting issues: The tool preserves original TypeScript formatting; report any issues with file examples.
Angular 17+: For standalone components, ensure provideTranslateService is in app.config.ts.

👨‍💻 Author

Author: Pratik Sonone

📄 License

MIT License. See LICENSE for details.