@abdess76/i18nkit 1.0.0

package/bin/plugins/parser-typescript.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const parserUtils = require('../core/parser-utils');
+
+const TS_EXTRACTION_PATTERNS = [
+  { regex: /\blabel\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_labels' },
+  { regex: /\btitle\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_titles' },
+  { regex: /\btext\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_text' },
+  { regex: /\bmessage\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_messages' },
+  { regex: /\bsummary\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_messages' },
+  { regex: /\bdetail\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_messages' },
+  { regex: /\bheader\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_titles' },
+  { regex: /\bplaceholder\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_placeholders' },
+  { regex: /\btooltip\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_tooltips' },
+  { regex: /\bdescription\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_text' },
+  { regex: /\bhint\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_text' },
+  { regex: /\bcaption\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_text' },
+  { regex: /\bcontent\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_text' },
+  { regex: /\bconfirmationMessage\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_messages' },
+  { regex: /\berrorMessage\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_messages' },
+  { regex: /\bsuccessMessage\s*:\s*['"]([^'"]+)['"]/gi, context: 'ts_messages' },
+];
+
+function shouldIgnoreTs(text) {
+  return parserUtils.shouldIgnore(text) || parserUtils.isTranslationKey(text);
+}
+
+module.exports = {
+  name: 'parser-typescript',
+  type: 'parser',
+
+  meta: {
+    description: 'Extract i18n strings from TypeScript object literals',
+    version: '1.0.0',
+  },
+
+  extensions: ['.ts', '.component.ts'],
+  priority: 30,
+
+  options: [
+    {
+      flag: '--extract-ts',
+      type: 'boolean',
+      description: 'Extract from TypeScript files (disabled by default)',
+    },
+  ],
+
+  examples: ['i18nkit --extract --extract-ts'],
+
+  detect(ctx) {
+    return ctx.pkg.dependencies?.typescript || ctx.files.includes('tsconfig.json');
+  },
+
+  TS_EXTRACTION_PATTERNS,
+
+  extract(content, filePath, options = {}) {
+    const { extractTsObjects = false } = options;
+    if (!extractTsObjects) {
+      return [];
+    }
+    const cleaned = parserUtils.cleanTranslocoCode(content);
+    return parserUtils.extractWithPatterns(cleaned, TS_EXTRACTION_PATTERNS, {
+      shouldIgnoreFn: shouldIgnoreTs,
+    });
+  },
+};

package/bin/plugins/provider-deepl.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const DEEPL_FREE_ENDPOINT = 'https://api-free.deepl.com/v2/translate';
+const DEEPL_PRO_ENDPOINT = 'https://api.deepl.com/v2/translate';
+
+function getEndpoint(apiKey) {
+  return apiKey.endsWith(':fx') ? DEEPL_FREE_ENDPOINT : DEEPL_PRO_ENDPOINT;
+}
+
+function getApiKey(options) {
+  const apiKey = options.apiKey || process.env.DEEPL_API_KEY;
+  if (!apiKey) {
+    throw new Error('DEEPL_API_KEY environment variable required for DeepL provider');
+  }
+  return apiKey;
+}
+
+function buildDeepLRequest(texts, ctx) {
+  return {
+    method: 'POST',
+    headers: { Authorization: `DeepL-Auth-Key ${ctx.apiKey}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      text: texts,
+      source_lang: ctx.fromLang.toUpperCase(),
+      target_lang: ctx.toLang.toUpperCase(),
+    }),
+  };
+}
+
+async function translate(text, ctx) {
+  const result = await translateBatch([text], ctx);
+  return result[0];
+}
+
+async function translateBatch(texts, ctx) {
+  const apiKey = getApiKey(ctx);
+  const response = await fetch(getEndpoint(apiKey), buildDeepLRequest(texts, { ...ctx, apiKey }));
+  if (!response.ok) {
+    throw new Error(`DeepL API error: ${response.status} - ${await response.text()}`);
+  }
+  const data = await response.json();
+  return data.translations.map(t => t.text);
+}
+
+module.exports = {
+  name: 'provider-deepl',
+  type: 'provider',
+
+  meta: {
+    description: 'High-quality translation via DeepL API (requires API key)',
+    version: '1.0.0',
+  },
+
+  options: [{ flag: '--deepl', type: 'boolean', description: 'Use DeepL API instead of MyMemory' }],
+
+  env: [{ name: 'DEEPL_API_KEY', required: true, description: 'DeepL API key (free or pro)' }],
+
+  examples: [
+    'DEEPL_API_KEY=xxx i18nkit translate fr:en --deepl',
+    'i18nkit translate fr:en --deepl',
+  ],
+
+  translate,
+  translateBatch,
+};

package/bin/plugins/provider-mymemory.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const MAX_TEXT_LENGTH = 500;
+const API_BATCH_SIZE = 5;
+const API_DELAY_MS = 100;
+
+const translationCache = new Map();
+
+const buildLangPair = (src, tgt) => `${src}|${tgt}`;
+const buildCacheKey = (from, to, text) => `${from}:${to}:${text}`;
+
+function buildMyMemoryUrl(ctx) {
+  const { text, sourceLang, targetLang, email } = ctx;
+  const base = `https://api.mymemory.translated.net/get?q=${encodeURIComponent(text)}&langpair=${buildLangPair(sourceLang, targetLang)}`;
+  return email ? `${base}&de=${encodeURIComponent(email)}` : base;
+}
+
+function checkResponseStatus(data) {
+  if (data.responseStatus !== 200) {
+    throw new Error(data.responseDetails || 'Unknown error');
+  }
+}
+
+function validateMyMemoryResponse(data) {
+  if (!data?.responseData?.translatedText) {
+    throw new Error('Invalid API response');
+  }
+  checkResponseStatus(data);
+  return data.responseData.translatedText;
+}
+
+function getCachedOrNull(cacheKey) {
+  return translationCache.has(cacheKey) ? translationCache.get(cacheKey) : null;
+}
+
+async function fetchTranslation(ctx) {
+  const { text, fromLang, toLang, email } = ctx;
+  const url = buildMyMemoryUrl({ text, sourceLang: fromLang, targetLang: toLang, email });
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+  return validateMyMemoryResponse(await response.json());
+}
+
+function handleTextTooLong(text, maxLength, verbose) {
+  if (verbose) {
+    console.log(`  [WARN] Text too long (${text.length} chars), keeping original`);
+  }
+  return text;
+}
+
+function handleTranslationError(error, text, verbose) {
+  if (verbose) {
+    console.log(`  [WARN] Translation failed: ${error.message}`);
+  }
+  return text;
+}
+
+function parseTranslateOptions(options = {}) {
+  return {
+    email: options.email || null,
+    verbose: options.verbose || false,
+    maxLength: options.maxLength || MAX_TEXT_LENGTH,
+  };
+}
+
+async function doTranslate(ctx) {
+  const { text, fromLang, toLang, email } = ctx;
+  const result = await fetchTranslation({ text, fromLang, toLang, email });
+  translationCache.set(buildCacheKey(fromLang, toLang, text), result);
+  return result;
+}
+
+async function translate(ctx) {
+  const { text, fromLang, toLang, options = {} } = ctx;
+  const opts = parseTranslateOptions(options);
+  if (text.length > opts.maxLength) {
+    return handleTextTooLong(text, opts.maxLength, opts.verbose);
+  }
+  const cached = getCachedOrNull(buildCacheKey(fromLang, toLang, text));
+  if (cached) {
+    return cached;
+  }
+  try {
+    return await doTranslate({ text, fromLang, toLang, email: opts.email });
+  } catch (error) {
+    return handleTranslationError(error, text, opts.verbose);
+  }
+}
+
+function processBatchResult(ctx) {
+  const { result, original, translationMap, verbose = false } = ctx;
+  if (result.status === 'fulfilled') {
+    translationMap.set(original, result.value);
+    return false;
+  }
+  translationMap.set(original, original);
+  if (verbose) {
+    console.warn(`  [WARN] Failed: "${original.substring(0, 30)}..."`);
+  }
+  return true;
+}
+
+async function processBatch(batch, ctx) {
+  const { fromLang, toLang, translationMap, options = {} } = ctx;
+  const results = await Promise.allSettled(
+    batch.map(text => translate({ text, fromLang, toLang, options })),
+  );
+  let failures = 0;
+  results.forEach((result, j) => {
+    if (
+      processBatchResult({ result, original: batch[j], translationMap, verbose: options.verbose })
+    ) {
+      failures++;
+    }
+  });
+  return failures;
+}
+
+function notifyProgress(onProgress, processed, total) {
+  if (onProgress) {
+    onProgress(processed, total);
+  }
+}
+
+async function delayIfNeeded(processed, total, delayMs) {
+  if (processed < total) {
+    await new Promise(resolve => {
+      setTimeout(resolve, delayMs);
+    });
+  }
+}
+
+function parseBatchOptions(options = {}) {
+  return {
+    batchSize: options.batchSize || API_BATCH_SIZE,
+    delayMs: options.delayMs || API_DELAY_MS,
+    onProgress: options.onProgress || null,
+  };
+}
+
+async function processBatchIteration(ctx) {
+  const { batch, batchCtx, opts, texts, i } = ctx;
+  const failures = await processBatch(batch, batchCtx);
+  const processed = Math.min(i + opts.batchSize, texts.length);
+  notifyProgress(opts.onProgress, processed, texts.length);
+  await delayIfNeeded(processed, texts.length, opts.delayMs);
+  return failures;
+}
+
+async function translateBatch(ctx) {
+  const { texts, fromLang, toLang, options = {} } = ctx;
+  const opts = parseBatchOptions(options);
+  const translationMap = new Map();
+  let failedCount = 0;
+  const batchCtx = { fromLang, toLang, translationMap, options };
+  for (let i = 0; i < texts.length; i += opts.batchSize) {
+    failedCount += await processBatchIteration({
+      batch: texts.slice(i, i + opts.batchSize),
+      batchCtx,
+      opts,
+      texts,
+      i,
+    });
+  }
+  return { translationMap, failedCount };
+}
+
+module.exports = {
+  name: 'provider-mymemory',
+  type: 'provider',
+
+  meta: {
+    description: 'Free translation via MyMemory API (rate limited)',
+    version: '1.0.0',
+  },
+
+  options: [
+    { flag: '--mymemory', type: 'boolean', description: 'Use MyMemory API (default provider)' },
+    { flag: '--email <email>', type: 'string', description: 'Email for higher rate limits' },
+  ],
+
+  env: [
+    { name: 'MYMEMORY_EMAIL', required: false, description: 'Email for higher API rate limits' },
+  ],
+
+  examples: ['i18nkit translate fr:en', 'i18nkit translate fr:en --email user@example.com'],
+
+  translate: ctx => translate(ctx),
+  translateBatch: ctx => translateBatch(ctx),
+};

package/package.json

@@ -0,0 +1,123 @@
+{
+  "name": "@abdess76/i18nkit",
+  "version": "1.0.0",
+  "description": "Universal i18n CLI - extract translation keys, sync language files, detect missing translations. Extensible plugin architecture.",
+  "author": {
+    "name": "Abdessamad DERRAZ",
+    "url": "https://github.com/Abdess"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./bin/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "i18nkit": "./bin/cli.js",
+    "i18n": "./bin/cli.js"
+  },
+  "main": "./bin/cli.js",
+  "types": "./types/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.0.0",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10.0.0",
+      "onFail": "warn"
+    }
+  },
+  "packageManager": "npm@10.9.2",
+  "publishConfig": {
+    "provenance": true,
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin",
+    "types",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "localization",
+    "l10n",
+    "translation",
+    "extract",
+    "sync",
+    "cli",
+    "transloco",
+    "angular",
+    "primeng",
+    "zero-dependency",
+    "missing-translations",
+    "orphan-keys",
+    "plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abdess/i18nkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Abdess/i18nkit/issues"
+  },
+  "homepage": "https://github.com/Abdess/i18nkit#readme",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Abdess"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage tests/**/*.test.js",
+    "test:watch": "node --test --watch tests/**/*.test.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "validate": "npm run lint && npm run format:check && npm run typecheck && npm test",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:serve": "npx serve docs/api",
+    "prepare": "husky",
+    "prepublishOnly": "npm run validate",
+    "prepack": "npm run validate",
+    "version": "npm run format && git add -A",
+    "postversion": "git push && git push --tags",
+    "release": "npm version patch && npm publish"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.2",
+    "clean-jsdoc-theme": "^4.3.0",
+    "eslint": "^9.17.0",
+    "globals": "^15.14.0",
+    "husky": "^9.1.7",
+    "jsdoc": "^4.0.4",
+    "lint-staged": "^15.3.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2"
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,yml,yaml}": [
+      "prettier --write"
+    ]
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * i18nkit - Universal i18n toolkit
+ * @packageDocumentation
+ */
+
+export interface I18nKitConfig {
+  /** Source directory to scan (default: 'src/app') */
+  src?: string;
+  /** Default language code */
+  lang?: string;
+  /** i18n files directory (default: 'src/assets/i18n') */
+  i18nDir?: string;
+  /** Output format: 'nested' or 'flat' (default: 'nested') */
+  format?: 'nested' | 'flat';
+  /** Create backups before modifying files (default: true) */
+  backup?: boolean;
+  /** Folders to exclude from scanning */
+  excludedFolders?: string[];
+  /** Extract from TypeScript object literals (default: false) */
+  extractTsObjects?: boolean;
+  /** Include already translated strings (default: false) */
+  includeTranslated?: boolean;
+  /** CI mode: enables strict and json (default: false) */
+  ci?: boolean;
+  /** Verbose output (default: false) */
+  verbose?: boolean;
+  /** JSON report output (default: false) */
+  json?: boolean;
+  /** Dry run mode (default: false) */
+  dryRun?: boolean;
+  /** Strict mode - exit 1 on issues (default: false) */
+  strict?: boolean;
+  /** Auto-apply translations (default: false) */
+  autoApply?: boolean;
+  /** Interactive mode for confirmations (default: false) */
+  interactive?: boolean;
+  /** Watch mode (default: false) */
+  watch?: boolean;
+  /** Use DeepL API instead of MyMemory (default: false) */
+  deepl?: boolean;
+  /** Email for MyMemory rate limit */
+  email?: string;
+  /** Languages to initialize */
+  initLangs?: string[];
+}
+
+export interface ExtractionResult {
+  file: string;
+  text: string;
+  rawText: string;
+  displayText: string;
+  context: string;
+  key: string;
+  attr?: string;
+  isNew: boolean;
+}
+
+export interface ExtractionStats {
+  files: number;
+  clean: number;
+  needsWork: number;
+  total: number;
+  added: number;
+  byContext: Record<string, number>;
+}
+
+export interface SyncResult {
+  totalKeys: number;
+  languages: number;
+  missingKeys: number;
+  identicalValues: number;
+  icuMessages: number;
+  icuMismatches: number;
+}
+
+export interface OrphanResult {
+  totalKeys: number;
+  usedKeys: number;
+  orphanKeys: number;
+  dynamicPatterns: number;
+}
+
+export const EXIT_SUCCESS: 0;
+export const EXIT_UNTRANSLATED: 1;
+export const EXIT_ERROR: 2;