@abdess76/i18nkit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 01-12-2025
+
+### Added
+
+- Initial release
+- Zero-dependency CLI for i18n extraction
+- Angular + Transloco support with PrimeNG patterns
+- Auto-apply feature to replace hardcoded strings
+- Sync check to compare language files
+- Orphan key detection
+- Translation API integration (MyMemory + DeepL)
+- Watch mode for development
+- CI mode with strict validation
+- Configuration file support (i18nkit.config.js, i18nkit.config.json)
+- Custom key mapping (.i18n-keys.json)
+- Backup system before modifications
+- Interactive mode for confirmations
+- Dry-run mode for previews
+- Flat and nested output formats
+- ICU message format support
+- ES2024 features (Array.fromAsync, Promise.withResolvers, Set.difference)
+
+### Technical
+
+- Pure Node.js implementation (no external dependencies)
+- Requires Node.js >= 22.0.0
+- Uses modern JavaScript patterns and optimizations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Abdessamad DERRAZ
+
+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,309 @@
+# i18nkit
+
+![i18nkit](assets/logo-with-title.png)
+
+[![npm](https://img.shields.io/npm/v/i18nkit.svg)](https://npmjs.com/package/i18nkit)
+[![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![zero-deps](https://img.shields.io/badge/dependencies-0-blue.svg)](package.json)
+[![docs](https://img.shields.io/badge/API-docs-blue.svg)](https://abdess.github.io/i18nkit/)
+
+---
+
+Universal i18n toolkit: extract translation keys, sync language files, detect
+missing translations. Zero dependencies, extensible via plugins.
+
+## Why i18nkit?
+
+Managing translations is tedious: find hardcoded strings, create translation
+keys, keep language files in sync. **i18nkit automates it.**
+
+| Problem                          | Solution                       |
+| -------------------------------- | ------------------------------ |
+| Hardcoded strings in templates   | Auto-extract translatable text |
+| Manual pipe/function replacement | Auto-apply in one command      |
+| Missing translations across lang | Sync check with CI integration |
+| Unused keys bloating bundles     | Orphan detection to clean up   |
+| Manual translation copy-paste    | API translation (free + pro)   |
+
+## Current Support
+
+- **Angular + Transloco** - Full support out of the box
+- **PrimeNG components** - Auto-extraction of translatable attributes
+
+Extensible via plugins for other frameworks and libraries.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install --save-dev i18nkit
+```
+
+### 2. Add scripts to package.json
+
+```json
+{
+  "scripts": {
+    "i18n": "i18nkit --lang fr --merge",
+    "i18n:apply": "i18nkit --auto-apply --init-langs en,fr",
+    "i18n:check": "i18nkit --check-sync --strict",
+    "i18n:orphans": "i18nkit --find-orphans --strict",
+    "i18n:translate": "i18nkit --translate fr:en",
+    "i18n:watch": "i18nkit --watch",
+    "i18n:ci": "npm run i18n:check && npm run i18n:orphans"
+  }
+}
+```
+
+### 3. Run
+
+```bash
+# First time: extract + apply + create language files
+npm run i18n:apply
+
+# Development: watch mode
+npm run i18n:watch
+
+# Before commit / CI
+npm run i18n:ci
+```
+
+## How It Works
+
+**Before:**
+
+```html
+<h1>Welcome to our app</h1>
+<button label="Submit" />
+<input placeholder="Enter your name" />
+```
+
+**After:**
+
+```html
+<h1>{{ 'home.titles.welcome_to_our_app' | transloco }}</h1>
+<button [label]="'home.buttons.submit' | transloco" />
+<input [placeholder]="'home.forms.enter_your_name' | transloco" />
+```
+
+**Generated `fr.json`:**
+
+```json
+{
+  "home": {
+    "titles": { "welcome_to_our_app": "Welcome to our app" },
+    "buttons": { "submit": "Submit" },
+    "forms": { "enter_your_name": "Enter your name" }
+  }
+}
+```
+
+## Commands
+
+| Script                   | Command                     | Description                  |
+| ------------------------ | --------------------------- | ---------------------------- |
+| `npm run i18n`           | `--lang fr --merge`         | Extract, merge with existing |
+| `npm run i18n:apply`     | `--auto-apply --init-langs` | Extract + replace + create   |
+| `npm run i18n:check`     | `--check-sync --strict`     | Validate files are in sync   |
+| `npm run i18n:orphans`   | `--find-orphans --strict`   | Find unused keys             |
+| `npm run i18n:translate` | `--translate fr:en`         | Translate via API            |
+| `npm run i18n:watch`     | `--watch`                   | Re-run on file changes       |
+
+## Configuration
+
+Create `i18nkit.config.js` in your project root:
+
+```javascript
+module.exports = {
+  src: 'src/app',
+  i18nDir: 'src/assets/i18n',
+  lang: 'fr',
+  format: 'nested',
+  backup: true,
+  excludedFolders: ['node_modules', 'dist', '.git'],
+};
+```
+
+Or `i18nkit.config.json`:
+
+```json
+{
+  "src": "src/app",
+  "i18nDir": "src/assets/i18n",
+  "lang": "fr",
+  "format": "nested"
+}
+```
+
+## Supported Patterns
+
+### HTML Templates
+
+| Pattern      | Example                            |
+| ------------ | ---------------------------------- |
+| Text content | `<h1>Welcome</h1>`                 |
+| Attributes   | `alt`, `title`, `placeholder`      |
+| Angular 17+  | `@if`, `@for`, `@switch`, `@defer` |
+
+### Component Libraries
+
+| Library          | Extracted Attributes         |
+| ---------------- | ---------------------------- |
+| PrimeNG          | `label`, `tooltip`, `header` |
+| Angular Material | `placeholder`, `label`       |
+| Bootstrap        | `title`, `alt`               |
+
+## Translation APIs
+
+```bash
+# Free: MyMemory API
+npm run i18n:translate
+
+# Free with higher rate limit
+npx i18nkit --translate fr:en --email you@example.com
+
+# Pro: DeepL API (best quality)
+DEEPL_API_KEY=xxx npx i18nkit --translate fr:en --deepl
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: i18n
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npm run i18n:ci
+```
+
+## Key Mapping
+
+Override auto-generated keys with `.i18n-keys.json`:
+
+```json
+{
+  "Welcome to our app": "common.welcome",
+  "Submit": "buttons.submit",
+  "Cancel": "buttons.cancel"
+}
+```
+
+## Plugin System
+
+i18nkit is built to be extended. Create plugins for any framework, library, or
+translation service.
+
+| Plugin Type  | Purpose                    | Example Use Case   |
+| ------------ | -------------------------- | ------------------ |
+| **parser**   | Extract strings from files | Vue, Svelte, React |
+| **adapter**  | Transform to i18n syntax   | i18next, vue-i18n  |
+| **provider** | Translate via API          | Google, AWS, Azure |
+
+### Quick Example
+
+```javascript
+// plugins/my-parser.js
+module.exports = {
+  name: 'parser-vue',
+  type: 'parser',
+  meta: { description: 'Extract from Vue SFC' },
+  extensions: ['.vue'],
+  detect: ctx => ctx.pkg.dependencies?.['vue'],
+  extract(content) {
+    return [{ text: 'Hello', context: 'greeting' }];
+  },
+};
+```
+
+```javascript
+// i18nkit.config.js
+module.exports = {
+  plugins: ['./plugins/my-parser.js'],
+};
+```
+
+**Full guide:** [PLUGINS.md](PLUGINS.md)
+
+### Community Plugins
+
+Publish your plugin to npm:
+
+```bash
+npm publish i18nkit-parser-svelte
+```
+
+i18nkit auto-discovers packages named `i18nkit-*` or `@yourorg/i18nkit-*`.
+
+**Want to contribute?** Check [builtin plugins](bin/plugins/) for reference
+implementations.
+
+## Options
+
+```text
+--src <path>          Source directory (default: src/app)
+--i18n-dir <path>     i18n directory (default: src/assets/i18n)
+--lang <code>         Language code
+--format <type>       nested | flat (default: nested)
+--merge               Merge with existing translations
+--auto-apply          Extract and apply pipes
+--init-langs <codes>  Create language files (e.g., en,fr,es)
+--check-sync          Compare language files
+--find-orphans        Find unused keys
+--translate <src:tgt> Translate via API (e.g., fr:en)
+--deepl               Use DeepL API
+--watch               Watch mode
+--dry-run             Preview only
+--strict              Exit 1 on issues
+--ci                  CI mode (strict + json output)
+--verbose             Detailed output
+```
+
+## Exit Codes
+
+| Code | Meaning                                            |
+| ---- | -------------------------------------------------- |
+| 0    | Success                                            |
+| 1    | Missing translations or sync problems (`--strict`) |
+| 2    | Error (file not found, parse error)                |
+
+## API Documentation
+
+Full API reference:
+[abdess.github.io/i18nkit](https://abdess.github.io/i18nkit/)
+
+## Requirements
+
+- Node.js >= 22.0.0
+
+## Contributing
+
+i18nkit welcomes community contributions:
+
+- **Plugins** - Create parsers for new frameworks, adapters for i18n libraries,
+  or providers for translation APIs
+- **Bug reports** - Open an issue with reproduction steps
+- **Feature requests** - Suggest improvements via GitHub issues
+
+See [PLUGINS.md](PLUGINS.md) for the plugin development guide.
+
+## License
+
+MIT
+
+---
+
+[GitHub](https://github.com/Abdess/i18nkit) ·
+[npm](https://npmjs.com/package/i18nkit) ·
+[Issues](https://github.com/Abdess/i18nkit/issues) · [Plugin Guide](PLUGINS.md)

package/bin/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { createContext, detectCommand, EXIT_CODES } = require('./core/context');
+const { getCommand } = require('./commands');
+const core = require('./core');
+
+const args = process.argv.slice(2);
+const commandName = detectCommand(args);
+const command = getCommand(commandName);
+
+if (!command) {
+  console.error(`Unknown command: ${commandName}`);
+  process.exit(EXIT_CODES.ERROR);
+}
+
+function handleError(err, verbose) {
+  console.error('Error:', err.message);
+  if (verbose) {
+    console.error(err.stack);
+  }
+
+  const backups = core.getBackupFiles();
+  if (backups.size > 0) {
+    console.log('\nRestoring backups...');
+    console.log(`Restored ${core.restoreBackups()} file(s)`);
+  }
+
+  process.exit(EXIT_CODES.ERROR);
+}
+
+async function main() {
+  const ctx = createContext(args);
+
+  try {
+    const result = await command.run(ctx);
+    const exitCode = result?.exitCode ?? EXIT_CODES.SUCCESS;
+
+    if (exitCode !== null) {
+      process.exit(exitCode);
+    }
+  } catch (err) {
+    handleError(err, ctx.verbose);
+  }
+}
+
+main();

package/bin/commands/apply.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * @fileoverview Apply command - replaces source text with translation keys.
+ * Applies findings from report.json to source files with backup support.
+ * @module commands/apply
+ */
+
+const { getArgValue, applyTranslations } = require('../core');
+
+function getApplyOptions(ctx) {
+  const { srcDir, backupDir, adapter, backup, dryRun, verbose, interactive, log } = ctx;
+  return { srcDir, backupDir, adapter, backup, dryRun, verbose, interactive, log };
+}
+
+function validateApplyFile(applyFile, exitCodes) {
+  if (!applyFile) {
+    console.error('Missing --apply <report.json> argument');
+    return { exitCode: exitCodes.ERROR };
+  }
+  return null;
+}
+
+module.exports = {
+  name: 'apply',
+  category: 'apply',
+  description: 'Apply translations from a report file to source files',
+
+  options: [
+    { flag: '--apply <report.json>', description: 'Path to the report file' },
+    { flag: '--backup', description: 'Create backups before modifying (default: on)' },
+    { flag: '--no-backup', description: 'Disable backup creation' },
+    { flag: '--interactive', description: 'Ask for confirmation before changes' },
+  ],
+
+  examples: ['i18nkit --apply .i18n/report.json', 'i18nkit --apply report.json --no-backup'],
+
+  async run(ctx) {
+    const { args, config, exitCodes } = ctx;
+    const applyFile = getArgValue(args, config, '--apply', null, null);
+    const error = validateApplyFile(applyFile, exitCodes);
+    if (error) {
+      return error;
+    }
+    await applyTranslations(applyFile, getApplyOptions(ctx));
+    return { exitCode: exitCodes.SUCCESS };
+  },
+};

package/bin/commands/check-sync.js

@@ -0,0 +1,35 @@
+'use strict';
+
+/**
+ * @fileoverview Check-sync command - validates i18n file consistency.
+ * Detects missing keys, identical values, and ICU format mismatches.
+ * @module commands/check-sync
+ */
+
+const { checkSync } = require('../core');
+
+module.exports = {
+  name: 'check-sync',
+  category: 'validation',
+  description: 'Compare language files for missing or identical keys',
+
+  options: [
+    { flag: '--strict', description: 'Exit with error if missing or untranslated keys found' },
+  ],
+
+  examples: ['i18nkit --check-sync', 'i18nkit --check-sync --strict'],
+
+  async run(ctx) {
+    const { i18nDir, format, strict, log, exitCodes } = ctx;
+
+    const result = await checkSync({
+      i18nDir,
+      format,
+      strict,
+      log,
+      exitCodes: { success: exitCodes.SUCCESS, untranslated: exitCodes.UNTRANSLATED },
+    });
+
+    return { exitCode: result.exitCode ?? exitCodes.SUCCESS };
+  },
+};