@abdess76/i18nkit 1.0.0

package/bin/core/types.js

@@ -0,0 +1,297 @@
+'use strict';
+
+/**
+ * @fileoverview Shared type definitions for the i18nkit library.
+ * All types are JSDoc-only for editor intellisense and documentation generation.
+ * @module types
+ */
+
+/**
+ * @typedef {Object} DetectedTech
+ * @property {string} id
+ * @property {string} label
+ * @property {string} type - 'framework', 'library', or 'i18n'
+ * @property {string} version
+ */
+
+/**
+ * @typedef {Object} DetectionResult
+ * @property {DetectedTech} framework
+ * @property {Array<DetectedTech>} libraries
+ * @property {DetectedTech} i18n
+ * @property {Array<string>} plugins
+ * @property {Array<DetectedTech>} details
+ */
+
+/**
+ * @typedef {Object} LangFile
+ * @property {string} name
+ * @property {string} path
+ */
+
+/**
+ * @typedef {Object} IcuMismatch
+ * @property {string} key
+ * @property {Array<string>} hasIcu
+ * @property {Array<string>} missingIcu
+ */
+
+/**
+ * @typedef {Object} IdenticalValue
+ * @property {string} key
+ * @property {string} value
+ */
+
+/**
+ * @typedef {Object} IcuMessage
+ * @property {string} key
+ * @property {Array<string>} langs
+ */
+
+/**
+ * @typedef {Object} SyncResult
+ * @property {Set<string>} allKeys
+ * @property {Array<LangFile>} langFiles
+ * @property {Object<string, Array<string>>} missingByLang
+ * @property {Array<IdenticalValue>} identicalValues
+ * @property {Array<IcuMessage>} icuMessages
+ * @property {Array<IcuMismatch>} icuMismatches
+ */
+
+/**
+ * @typedef {Object} SyncCheckResult
+ * @property {boolean} success
+ * @property {number} exitCode
+ * @property {SyncResult} result
+ */
+
+/**
+ * @typedef {Object} DynamicPattern
+ * @property {string} file
+ * @property {string} pattern
+ */
+
+/**
+ * @typedef {Object} OrphanResult
+ * @property {boolean} success
+ * @property {number} exitCode
+ * @property {Array<string>} orphanKeys
+ * @property {Array<string>} usedKeys
+ * @property {Array<string>} allKeys
+ * @property {Array<DynamicPattern>} dynamicPatterns
+ */
+
+/**
+ * @typedef {Object} TranslateResult
+ * @property {boolean} success
+ * @property {number} translated
+ * @property {number} failed
+ */
+
+/**
+ * @typedef {Object} ModifiedFile
+ * @property {string} file
+ * @property {number} count
+ */
+
+/**
+ * @typedef {Object} ApplyResult
+ * @property {boolean} success
+ * @property {boolean} aborted
+ * @property {number} totalFiles
+ * @property {number} totalReplacements
+ * @property {Array<ModifiedFile>} modifiedFiles
+ */
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} file
+ * @property {number} line
+ * @property {string} original
+ * @property {string} key
+ * @property {string} scope
+ */
+
+/**
+ * @typedef {Object} ExitCodes
+ * @property {number} success
+ * @property {number} untranslated
+ */
+
+/**
+ * @typedef {Object} TranslateOptions
+ * @property {string} i18nDir
+ * @property {Object} provider
+ * @property {boolean} useDeepL
+ * @property {string} email
+ * @property {boolean} verbose
+ * @property {boolean} dryRun
+ * @property {Function} log
+ */
+
+/**
+ * @typedef {Object} SyncOptions
+ * @property {string} i18nDir
+ * @property {string} format - 'nested' or 'flat'
+ * @property {Function} log
+ * @property {boolean} strict
+ * @property {ExitCodes} exitCodes
+ */
+
+/**
+ * @typedef {Object} OrphanOptions
+ * @property {string} i18nDir
+ * @property {string} srcDir
+ * @property {string} format - 'nested' or 'flat'
+ * @property {Array<string>} excludedFolders
+ * @property {boolean} verbose
+ * @property {boolean} strict
+ * @property {Function} log
+ * @property {ExitCodes} exitCodes
+ */
+
+/**
+ * @typedef {Object} ApplyOptions
+ * @property {string} srcDir
+ * @property {string} backupDir
+ * @property {Object} adapter
+ * @property {boolean} backup
+ * @property {boolean} dryRun
+ * @property {boolean} verbose
+ * @property {boolean} interactive
+ * @property {Function} log
+ */
+
+/**
+ * @typedef {Object} WatchOptions
+ * @property {string} srcDir
+ * @property {Array<string>} excludedFolders
+ * @property {Function} onFileChange
+ * @property {Function} onStart
+ * @property {Function} log
+ */
+
+/**
+ * @typedef {Object} FileContent
+ * @property {string} template
+ * @property {string} typescript
+ * @property {string} type - 'component' or 'html'
+ */
+
+/**
+ * @typedef {Object} ExtractedKey
+ * @property {string} key
+ * @property {string} original
+ * @property {string} scope
+ * @property {string} file
+ * @property {number} line
+ */
+
+/**
+ * @typedef {Object} ExtractResult
+ * @property {Array<ExtractedKey>} findings
+ * @property {Object<string, string>} keys
+ * @property {number} filesScanned
+ * @property {number} keysExtracted
+ */
+
+/**
+ * @typedef {Object} FsAdapter
+ * @property {Object} fs
+ * @property {Object} fsp
+ */
+
+/**
+ * @typedef {Object} PluginMeta
+ * @property {string} description
+ * @property {string} category
+ */
+
+/**
+ * @typedef {Object} PluginOption
+ * @property {string} flag
+ * @property {string} description
+ * @property {boolean} required
+ */
+
+/**
+ * @typedef {Object} PluginEnv
+ * @property {string} name
+ * @property {string} description
+ */
+
+/**
+ * @typedef {Object} Plugin
+ * @property {string} name
+ * @property {string} type - 'parser', 'adapter', or 'provider'
+ * @property {PluginMeta} meta
+ * @property {string} source - 'builtin', 'local', or 'npm'
+ * @property {number} priority
+ * @property {Array<string>} extensions
+ * @property {Array<PluginOption>} options
+ * @property {Array<PluginEnv>} env
+ * @property {Array<string>} examples
+ * @property {Function} detect
+ * @property {Function} extract
+ * @property {Function} transform
+ * @property {Function} translate
+ * @property {Function} translateBatch
+ */
+
+/**
+ * @typedef {Object} PluginError
+ * @property {string} source
+ * @property {string} plugin
+ * @property {string} error
+ * @property {Array<string>} errors
+ */
+
+/**
+ * @typedef {Object} PluginRegistry
+ * @property {Array<Plugin>} parsers
+ * @property {Array<Plugin>} adapters
+ * @property {Array<Plugin>} providers
+ * @property {Array<Plugin>} all
+ * @property {Map<string, Plugin>} byName
+ * @property {Array<PluginError>} errors
+ */
+
+/**
+ * @typedef {Object} PluginValidation
+ * @property {boolean} valid
+ * @property {Array<string>} errors
+ */
+
+/**
+ * @typedef {Object} DetectionContext
+ * @property {DetectedTech} framework
+ * @property {Array<DetectedTech>} libraries
+ * @property {DetectedTech} i18n
+ * @property {Object} packageJson
+ */
+
+/**
+ * @typedef {Object} CommandOption
+ * @property {string} flag
+ * @property {string} description
+ * @property {boolean} required
+ */
+
+/**
+ * @typedef {Object} CommandMeta
+ * @property {string} description
+ * @property {string} category
+ */
+
+/**
+ * @typedef {Object} Command
+ * @property {string} name
+ * @property {string} description
+ * @property {string} category
+ * @property {Array<string>} aliases
+ * @property {Array<CommandOption>} options
+ * @property {CommandMeta} meta
+ * @property {Function} run
+ */
+
+module.exports = {};

package/bin/core/watcher.js

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * @fileoverview File system watcher for incremental extraction.
+ * Monitors .ts/.html files with debouncing and recursive support.
+ * @module watcher
+ */
+
+const fs = require('./fs-adapter');
+const path = require('path');
+
+const WATCH_DEBOUNCE_MS = 500;
+const watchDebounceMap = new Map();
+
+function isWatchableFile(filename) {
+  if (!filename || !/\.(ts|html)$/.test(filename)) {
+    return false;
+  }
+  return !/\.(spec|test|e2e|mock)\./.test(filename);
+}
+
+function createWatchHandler(options = {}) {
+  const { srcDir, onFileChange, log = console.log } = options;
+
+  return filePath => {
+    const now = Date.now();
+    if (now - (watchDebounceMap.get(filePath) || 0) < WATCH_DEBOUNCE_MS) {
+      return;
+    }
+    watchDebounceMap.set(filePath, now);
+    log(
+      `\n[${new Date().toLocaleTimeString()}] Change detected: ${path.relative(srcDir, filePath)}`,
+    );
+    if (onFileChange) {
+      onFileChange(filePath);
+    }
+  };
+}
+
+function watchSubdirectory(dir, handleChange, excludedFolders) {
+  for (const file of fs.readdirSync(dir)) {
+    if (excludedFolders.includes(file)) {
+      continue;
+    }
+    const filePath = path.join(dir, file);
+    if (fs.statSync(filePath).isDirectory()) {
+      watchSubdirectory(filePath, handleChange, excludedFolders);
+    }
+  }
+  fs.watch(dir, { recursive: false }, (_, filename) => {
+    if (!isWatchableFile(filename)) {
+      return;
+    }
+    const filePath = path.join(dir, filename);
+    if (fs.existsSync(filePath)) {
+      handleChange(filePath);
+    }
+  });
+}
+
+function watchDirRecursive(dir, handleChange, excludedFolders = []) {
+  if (!fs.existsSync(dir)) {
+    return;
+  }
+  watchSubdirectory(dir, handleChange, excludedFolders);
+}
+
+function setupRecursiveWatch(ctx) {
+  const { srcDir, excludedFolders, handleChange, log } = ctx;
+  const watcher = fs.watch(srcDir, { recursive: true }, (_, filename) => {
+    if (!isWatchableFile(filename) || excludedFolders.some(f => filename.includes(f))) {
+      return;
+    }
+    const filePath = path.join(srcDir, filename);
+    if (fs.existsSync(filePath)) {
+      handleChange(filePath);
+    }
+  });
+  watcher.on('error', err => console.error('Watch error:', err.message));
+  log('Using recursive watch (native support)');
+}
+
+function setupFallbackWatch(ctx) {
+  const { srcDir, excludedFolders, handleChange, log } = ctx;
+  log('Recursive watch not supported, using directory watchers');
+  watchDirRecursive(srcDir, handleChange, excludedFolders);
+}
+
+function logWatchHeader(srcDir, log) {
+  log('Transloco Watch Mode');
+  log('='.repeat(50));
+  log(`Watching: ${srcDir}\nPress Ctrl+C to stop\n`);
+}
+
+function initWatch(ctx) {
+  try {
+    setupRecursiveWatch(ctx);
+  } catch {
+    setupFallbackWatch(ctx);
+  }
+}
+
+/**
+ * Watches source directory for .ts/.html changes
+ * @param {WatchOptions} [options]
+ * @example
+ * watchFiles({ srcDir: './src', onFileChange: path => extract(path) });
+ */
+function watchFiles(options = {}) {
+  const { srcDir, excludedFolders = [], onFileChange, onStart, log = console.log } = options;
+  logWatchHeader(srcDir, log);
+  const handleChange = createWatchHandler({ srcDir, onFileChange, log });
+  initWatch({ srcDir, excludedFolders, handleChange, log });
+  if (onStart) {
+    onStart();
+  }
+}
+
+module.exports = { watchFiles };

package/bin/plugins/adapter-transloco.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const TRANSLATABLE_ATTRS = [
+  'placeholder',
+  'pTooltip',
+  'tooltip',
+  'title',
+  'label',
+  'header',
+  'emptyMessage',
+  'emptyFilterMessage',
+  'summary',
+  'detail',
+  'message',
+  'acceptLabel',
+  'rejectLabel',
+  'chooseLabel',
+  'uploadLabel',
+  'cancelLabel',
+  'prefix',
+  'suffix',
+  'defaultLabel',
+  'selectedItemsLabel',
+  'text',
+];
+
+const ATTR_REPLACEMENT_MAP = Object.fromEntries(
+  TRANSLATABLE_ATTRS.map(attr => [attr, attr === 'aria-label' ? 'attr.aria-label' : attr]),
+);
+
+const TAG_CONTENT_RE =
+  /(<(?:h[1-6]|p|span|div|li|td|th|a|button|label|option)[^>]*>)\s*(.+?)\s*(<\/(?:h[1-6]|p|span|div|li|td|th|a|button|label|option)>)/gi;
+
+const hasTranslocoPipe = content => /\bTranslocoPipe\b/.test(content);
+const hasTranslocoImport = content => /@jsverse\/transloco/.test(content);
+
+function addToExistingImport(content) {
+  return content.replace(
+    /import\s*\{([^}]+)\}\s*from\s*['"]@jsverse\/transloco['"]/,
+    (match, imports) => {
+      const importList = imports.split(',').map(s => s.trim());
+      if (!importList.includes('TranslocoPipe')) {
+        importList.push('TranslocoPipe');
+      }
+      return `import { ${importList.join(', ')} } from '@jsverse/transloco'`;
+    },
+  );
+}
+
+function addNewTranslocoImport(content) {
+  const lastImportMatch = content.match(/^(import\s+.+from\s+['"][^'"]+['"];?\s*\n)/gm);
+  if (!lastImportMatch) {
+    return content;
+  }
+  const lastImport = lastImportMatch.at(-1);
+  const insertPos = content.lastIndexOf(lastImport) + lastImport.length;
+  return `${content.slice(0, insertPos)}import { TranslocoPipe } from '@jsverse/transloco';\n${content.slice(insertPos)}`;
+}
+
+function addPipeToImportsArray(content) {
+  return content.replace(/imports\s*:\s*\[([^\]]+)\]/, (match, imports) => {
+    const importList = imports
+      .split(',')
+      .map(s => s.trim())
+      .filter(Boolean);
+    if (!importList.includes('TranslocoPipe')) {
+      importList.push('TranslocoPipe');
+    }
+    return `imports: [${importList.join(', ')}]`;
+  });
+}
+
+function addTranslocoPipeImport(content) {
+  if (hasTranslocoPipe(content)) {
+    return content;
+  }
+  const withImport =
+    hasTranslocoImport(content) ? addToExistingImport(content) : addNewTranslocoImport(content);
+  return addPipeToImportsArray(withImport);
+}
+
+function replaceAttributes(content, rawText, translocoExpr) {
+  let result = content;
+  let replacements = 0;
+  for (const attr of TRANSLATABLE_ATTRS) {
+    const search = `${attr}="${rawText}"`;
+    if (!result.includes(search)) {
+      continue;
+    }
+    const bindAttr = ATTR_REPLACEMENT_MAP[attr] ?? attr;
+    result = result.replaceAll(search, `[${bindAttr}]=${translocoExpr}`);
+    replacements++;
+  }
+  return { content: result, replacements };
+}
+
+function buildTagReplacement(parts, rawText, key) {
+  const [, open, text, close] = parts;
+  return text.trim() === rawText ? `${open}{{ '${key}' | transloco }}${close}` : parts[0];
+}
+
+function replaceTagContent(content, rawText, key) {
+  const result = content.replace(TAG_CONTENT_RE, (...parts) =>
+    buildTagReplacement(parts, rawText, key),
+  );
+  return { content: result, replaced: result !== content };
+}
+
+function transformTemplate(ctx) {
+  const { content, rawText, key } = ctx;
+  const translocoExpr = `"'${key}' | transloco"`;
+  const result = replaceAttributes(content, rawText, translocoExpr);
+
+  if (result.replacements === 0) {
+    const tagResult = replaceTagContent(result.content, rawText, key);
+    return { content: tagResult.content, replacements: tagResult.replaced ? 1 : 0 };
+  }
+  return result;
+}
+
+module.exports = {
+  name: 'adapter-transloco',
+  type: 'adapter',
+
+  meta: {
+    description: 'Transform extracted strings to Transloco pipe syntax',
+    version: '1.0.0',
+  },
+
+  examples: ['i18nkit --extract --apply (uses Transloco syntax)'],
+
+  detect(ctx) {
+    return (
+      ctx.pkg.dependencies?.['@jsverse/transloco'] || ctx.pkg.dependencies?.['@ngneat/transloco']
+    );
+  },
+
+  TRANSLATABLE_ATTRS,
+  ATTR_REPLACEMENT_MAP,
+
+  transform(ctx) {
+    const { content, rawText, key, context } = ctx;
+    if (context.startsWith('ts_')) {
+      return { content, replacements: 0 };
+    }
+    return transformTemplate({ content, rawText, key });
+  },
+
+  updateImports(tsContent) {
+    return addTranslocoPipeImport(tsContent);
+  },
+
+  addTranslocoPipeImport,
+  replaceAttributes,
+  replaceTagContent,
+};

package/bin/plugins/parser-angular.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const parserUtils = require('../core/parser-utils');
+
+const EXTRACTION_PATTERNS = [
+  { regex: /<(h[1-6])(?:\s[^>]*)?>([^<]+)<\/\1>/gi, context: 'titles', group: 2, attr: null },
+  {
+    regex: /<(p|span|div|li|td|th)(?:\s[^>]*)?>([^<]+)<\/\1>/gi,
+    context: 'text',
+    group: 2,
+    attr: null,
+  },
+  { regex: /<(a)(?:\s[^>]*)?>([^<]+)<\/\1>/gi, context: 'links', group: 2, attr: null },
+  { regex: /<(button)(?:\s[^>]*)?>([^<]+)<\/\1>/gi, context: 'buttons', group: 2, attr: null },
+  { regex: /<(label)(?:\s[^>]*)?>([^<]+)<\/\1>/gi, context: 'labels', group: 2, attr: null },
+  { regex: /<(option)(?:\s[^>]*)?>([^<]+)<\/\1>/gi, context: 'options', group: 2, attr: null },
+  { regex: /\bplaceholder="([^"]+)"/gi, context: 'placeholders', attr: 'placeholder' },
+  { regex: /\b(?:pTooltip|tooltip)="([^"]+)"/gi, context: 'tooltips', attr: 'pTooltip' },
+  { regex: /\baria-label="([^"]+)"/gi, context: 'aria', attr: 'aria-label' },
+  { regex: /\btitle="([^"]+)"/gi, context: 'titles', attr: 'title' },
+];
+
+module.exports = {
+  name: 'parser-angular',
+  type: 'parser',
+
+  meta: {
+    description: 'Extract i18n strings from Angular HTML templates',
+    version: '1.0.0',
+  },
+
+  extensions: ['.html', '.component.html'],
+  priority: 10,
+
+  options: [
+    {
+      flag: '--skip-translated',
+      type: 'boolean',
+      description: 'Skip already translated strings (default: true)',
+    },
+  ],
+
+  examples: ['i18nkit --extract --src src/app'],
+
+  detect(ctx) {
+    return ctx.pkg.dependencies?.['@angular/core'] || ctx.files.includes('angular.json');
+  },
+
+  EXTRACTION_PATTERNS,
+
+  extract(content, filePath, options = {}) {
+    const { skipTranslated = true } = options;
+    const cleaned = parserUtils.cleanTranslocoExpressions(content, skipTranslated);
+    return parserUtils.extractWithPatterns(cleaned, EXTRACTION_PATTERNS);
+  },
+};

package/bin/plugins/parser-primeng.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const parserUtils = require('../core/parser-utils');
+
+const PRIMENG_PATTERNS = [
+  { regex: /<p-(?:button|splitButton)[^>]*\blabel="([^"]+)"/gi, context: 'buttons', attr: 'label' },
+  {
+    regex: /<p-(?:card|dialog|panel|fieldset)[^>]*\bheader="([^"]+)"/gi,
+    context: 'titles',
+    attr: 'header',
+  },
+  {
+    regex: /<p-(?:tabPanel|accordionTab|steps?)[^>]*\bheader="([^"]+)"/gi,
+    context: 'titles',
+    attr: 'header',
+  },
+  { regex: /<p-column[^>]*\bheader="([^"]+)"/gi, context: 'columns', attr: 'header' },
+  { regex: /<p-table[^>]*\bemptyMessage="([^"]+)"/gi, context: 'messages', attr: 'emptyMessage' },
+  {
+    regex: /<p-confirm[^>]*\b(?:message|header)="([^"]+)"/gi,
+    context: 'messages',
+    attr: 'message',
+  },
+  {
+    regex: /<p-confirm[^>]*\b(?:acceptLabel|rejectLabel)="([^"]+)"/gi,
+    context: 'buttons',
+    attr: 'acceptLabel',
+  },
+  {
+    regex:
+      /<p-(?:dropdown|multiSelect|listbox)[^>]*\b(?:placeholder|emptyMessage|emptyFilterMessage|defaultLabel|selectedItemsLabel)="([^"]+)"/gi,
+    context: 'placeholders',
+    attr: 'placeholder',
+  },
+  {
+    regex: /<p-fileUpload[^>]*\b(?:chooseLabel|uploadLabel|cancelLabel)="([^"]+)"/gi,
+    context: 'buttons',
+    attr: 'chooseLabel',
+  },
+  { regex: /<p-(?:chip|tag)[^>]*\blabel="([^"]+)"/gi, context: 'labels', attr: 'label' },
+  {
+    regex: /<p-(?:inputNumber|calendar)[^>]*\b(?:prefix|suffix)="([^"]+)"/gi,
+    context: 'labels',
+    attr: 'prefix',
+  },
+  {
+    regex: /<p-message[^>]*\b(?:text|summary|detail)="([^"]+)"/gi,
+    context: 'messages',
+    attr: 'text',
+  },
+  { regex: /<p-toast[^>]*\bsummary="([^"]+)"/gi, context: 'messages', attr: 'summary' },
+];
+
+module.exports = {
+  name: 'parser-primeng',
+  type: 'parser',
+
+  meta: {
+    description: 'Extract i18n strings from PrimeNG component attributes',
+    version: '1.0.0',
+  },
+
+  extensions: ['.html', '.component.html'],
+  priority: 20,
+
+  examples: ['i18nkit --extract (auto-activated with PrimeNG)'],
+
+  detect(ctx) {
+    return ctx.pkg.dependencies?.primeng;
+  },
+
+  PRIMENG_PATTERNS,
+
+  extract(content, filePath, options = {}) {
+    const { skipTranslated = true } = options;
+    const cleaned = parserUtils.cleanTranslocoExpressions(content, skipTranslated);
+    return parserUtils.extractWithPatterns(cleaned, PRIMENG_PATTERNS);
+  },
+};