@abdess76/i18nkit 1.0.0

package/bin/core/parser-utils.js

@@ -0,0 +1,187 @@
+'use strict';
+
+/**
+ * @fileoverview Shared text extraction patterns and utilities for all parsers.
+ * Handles HTML entities, ignore patterns, and Transloco expression cleanup.
+ * @module parser-utils
+ */
+
+/**
+ * @typedef {Object} ExtractedText
+ * @property {string} text
+ * @property {string} rawText
+ * @property {string} context
+ * @property {string} [attr]
+ */
+
+const IGNORE_PATTERNS = [
+  /^\s*$/,
+  /^\d+(\.\d+)?$/,
+  /^[a-z]+:\/\//i,
+  /^#[0-9a-f]{3,8}$/i,
+  /^(true|false|null|undefined)$/i,
+  /^\{\{[^}]*\}\}$/,
+  /^@(if|for|switch|else|case|defer|empty|placeholder|loading|error)\b/,
+  /^&\w+;$/,
+  /&[a-z]+;/i,
+  /^\d+(px|rem|em|vh|vw|%|°|deg|ms|s)$/,
+  /^[<>{}[\]()]+$/,
+  /\w+\(\)$/,
+];
+
+const HTML_ENTITIES = {
+  '&amp;': '&',
+  '&lt;': '<',
+  '&gt;': '>',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&apos;': "'",
+  '&nbsp;': ' ',
+  '&ndash;': '–',
+  '&mdash;': '—',
+  '&laquo;': '«',
+  '&raquo;': '»',
+  '&euro;': '€',
+  '&copy;': '©',
+  '&reg;': '®',
+};
+
+const ICON_CLASS_PATTERN =
+  /class="[^"]*\b(?:material-symbols|pi-icon|pi pi-|fa[rsbldt]?(?:\s|"|-)|icon\b|bi-|symbol)/i;
+
+/**
+ * Decodes HTML entities to their character equivalents.
+ * @param {string} str
+ * @returns {string}
+ * @example decodeHtmlEntities('&amp;') // '&'
+ */
+function decodeHtmlEntities(str) {
+  if (!str) {
+    return str;
+  }
+  let result = str;
+  for (const [entity, char] of Object.entries(HTML_ENTITIES)) {
+    result = result.replaceAll(entity, char);
+  }
+  return result.replace(/&#(\d+);/g, (_, code) => String.fromCharCode(parseInt(code, 10)));
+}
+
+/**
+ * Determines if text should be ignored (too short, numeric, URL, etc.).
+ * @param {string} text
+ * @returns {boolean}
+ */
+function shouldIgnore(text) {
+  if (!text) {
+    return true;
+  }
+  const trimmed = text.trim();
+  return trimmed.length < 2 || trimmed.length > 500 || IGNORE_PATTERNS.some(p => p.test(trimmed));
+}
+
+function isIconContainer(match) {
+  return ICON_CLASS_PATTERN.test(match);
+}
+
+/**
+ * Removes already-translated Transloco expressions from template.
+ * @param {string} template
+ * @param {boolean} [skipTranslated=true]
+ * @returns {string}
+ */
+function cleanTranslocoExpressions(template, skipTranslated = true) {
+  if (!skipTranslated) {
+    return template;
+  }
+  return template
+    .replace(/\{\{[^}]*\|\s*transloco[^}]*(\{[^}]*\})?[^}]*\}\}/g, '')
+    .replace(/\[[\w.-]+\]="[^"]*\|\s*transloco[^"]*"/g, '')
+    .replace(/\{\{\s*t\s*\([^)]*\)\s*\}\}/g, '')
+    .replace(/"'[^']+'\s*\|\s*transloco[^"]*"/g, '""')
+    .replace(/\*transloco\s*=\s*"[^"]*"/g, '')
+    .replace(/\*transloco\s*=\s*'[^']*'/g, '');
+}
+
+/**
+ * Removes Transloco function calls from TypeScript code.
+ * @param {string} code
+ * @returns {string}
+ */
+function cleanTranslocoCode(code) {
+  return code
+    .replace(/translate\s*\(\s*['"][^'"]+['"]\s*\)/g, '')
+    .replace(/transloco\s*\(\s*['"][^'"]+['"]\s*\)/g, '')
+    .replace(/\|\s*transloco/g, '');
+}
+
+function extractMatchText(match, group, decodeFn) {
+  const rawText = (match[group] || '').trim().replace(/\s+/g, ' ');
+  return { rawText, text: decodeFn(rawText) };
+}
+
+function shouldAddMatch(ctx) {
+  const { text, key, seen, shouldIgnoreFn } = ctx;
+  return !shouldIgnoreFn(text) && !seen.has(key);
+}
+
+function processPatternMatch(match, pattern, ctx) {
+  const { options, seen, results } = ctx;
+  const { context, group = 1, attr } = pattern;
+  if (isIconContainer(match[0])) {
+    return;
+  }
+  const { rawText, text } = extractMatchText(match, group, options.decodeFn);
+  const key = `${context}:${text}`;
+  if (shouldAddMatch({ text, key, seen, shouldIgnoreFn: options.shouldIgnoreFn })) {
+    seen.add(key);
+    results.push({ text, rawText, context, attr });
+  }
+}
+
+function getExtractOptions(options) {
+  return {
+    shouldIgnoreFn: options.shouldIgnoreFn || shouldIgnore,
+    decodeFn: options.decodeFn || decodeHtmlEntities,
+  };
+}
+
+function processPatternMatches(content, pattern, ctx) {
+  for (const match of content.matchAll(pattern.regex)) {
+    processPatternMatch(match, pattern, ctx);
+  }
+}
+
+/**
+ * Extracts translatable text using regex patterns.
+ * @param {string} content
+ * @param {Array<Object>} patterns
+ * @param {Object} [options]
+ * @returns {Array<ExtractedText>}
+ */
+function extractWithPatterns(content, patterns, options = {}) {
+  const results = [];
+  const ctx = { options: getExtractOptions(options), seen: new Set(), results };
+  for (const pattern of patterns) {
+    processPatternMatches(content, pattern, ctx);
+  }
+  return results;
+}
+
+/**
+ * Checks if text looks like a translation key (dot-separated).
+ * @param {string} text
+ * @returns {boolean}
+ * @example isTranslationKey('common.buttons.save') // true
+ */
+function isTranslationKey(text) {
+  return /^[a-z][a-z0-9]*(\.[a-z][a-z0-9_]*)+$/i.test(text);
+}
+
+module.exports = {
+  decodeHtmlEntities,
+  shouldIgnore,
+  cleanTranslocoExpressions,
+  cleanTranslocoCode,
+  extractWithPatterns,
+  isTranslationKey,
+};

package/bin/core/paths.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * @fileoverview Path resolution for i18n directories and output files.
+ * Merges CLI arguments with config file settings.
+ * @module paths
+ */
+
+const path = require('path');
+const { getArgValue } = require('./config');
+const { DEFAULT_EXCLUDED_FOLDERS } = require('./file-walker');
+
+function resolveI18nDir(args, config, cwd) {
+  return getArgValue(args, config, {
+    flag: '--i18n-dir',
+    configKey: 'i18nDir',
+    defaultValue: path.join(cwd, 'src', 'assets', 'i18n'),
+  });
+}
+
+function resolveSrcDir(args, config, cwd) {
+  return getArgValue(args, config, {
+    flag: '--src',
+    configKey: 'src',
+    defaultValue: path.join(cwd, 'src', 'app'),
+  });
+}
+
+function resolveOutputFile(ctx) {
+  const { args, config, i18nDir, lang } = ctx;
+  return getArgValue(args, config, {
+    flag: '--output',
+    configKey: 'output',
+    defaultValue: path.join(i18nDir, lang ? `${lang}.json` : 'extracted.json'),
+  });
+}
+
+/**
+ * Resolves all paths needed for extraction and translation
+ * @param {Object} ctx
+ * @returns {Object}
+ */
+function resolvePaths(ctx) {
+  const { args, config, cwd, lang = null } = ctx;
+  const i18nDir = resolveI18nDir(args, config, cwd);
+  const reportDir = path.join(cwd, '.i18n');
+  return {
+    srcDir: resolveSrcDir(args, config, cwd),
+    i18nDir,
+    reportDir,
+    backupDir: path.join(reportDir, 'backup'),
+    outputFile: resolveOutputFile({ args, config, i18nDir, lang }),
+    keyMappingFile: path.join(cwd, '.i18n-keys.json'),
+    excludedFolders: config.excludedFolders || DEFAULT_EXCLUDED_FOLDERS,
+  };
+}
+
+module.exports = {
+  resolvePaths,
+};

package/bin/core/plugin-interface.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * @fileoverview Plugin validation and help formatting.
+ * Validates plugin structure and generates CLI help output.
+ * @module plugin-interface
+ */
+
+/** @type {Array<string>} */
+const PLUGIN_TYPES = ['parser', 'adapter', 'provider'];
+
+const checkName = p =>
+  (!p.name || typeof p.name !== 'string') && 'Plugin must have a string "name"';
+const checkType = p =>
+  (!p.type || !PLUGIN_TYPES.includes(p.type)) &&
+  `Plugin type must be one of: ${PLUGIN_TYPES.join(', ')}`;
+const checkMeta = p => !p.meta?.description && 'Plugin must have meta.description';
+
+function validateBasicFields(plugin) {
+  return [checkName(plugin), checkType(plugin), checkMeta(plugin)].filter(Boolean);
+}
+
+function validateTypeSpecificMethods(plugin) {
+  const methodErrors = {
+    parser: () =>
+      typeof plugin.extract !== 'function' &&
+      'Parser plugins must have an extract(content, filePath, options) method',
+    adapter: () =>
+      typeof plugin.transform !== 'function' &&
+      'Adapter plugins must have a transform(content, text, key, context) method',
+    provider: () =>
+      typeof plugin.translate !== 'function' &&
+      typeof plugin.translateBatch !== 'function' &&
+      'Provider plugins must have translate() or translateBatch() method',
+  };
+  const validator = methodErrors[plugin.type];
+  return validator ? validator() : false;
+}
+
+/**
+ * Validates a plugin has required fields and methods.
+ * @param {Plugin} plugin
+ * @returns {PluginValidation}
+ */
+function validatePlugin(plugin) {
+  const errors = validateBasicFields(plugin);
+  const typeError = validateTypeSpecificMethods(plugin);
+  if (typeError) {
+    errors.push(typeError);
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function formatPluginBasic(plugin) {
+  const source = plugin.source || 'builtin';
+  return [`  ${plugin.name} (${source})`, `    ${plugin.meta?.description || 'No description'}`];
+}
+
+function formatPluginOptions(plugin) {
+  if (!plugin.options?.length) {
+    return [];
+  }
+  return plugin.options.map(opt => `    ${opt.flag.padEnd(20)} ${opt.description}`);
+}
+
+/**
+ * Formats plugin information for CLI help output.
+ * @param {Plugin} plugin
+ * @returns {string}
+ */
+function formatPluginHelp(plugin) {
+  const lines = formatPluginBasic(plugin);
+  if (plugin.extensions?.length) {
+    lines.push(`    Extensions: ${plugin.extensions.join(', ')}`);
+  }
+  lines.push(...formatPluginOptions(plugin));
+  if (plugin.env?.length) {
+    lines.push(`    Env: ${plugin.env.map(e => e.name).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { validatePlugin, formatPluginHelp };

package/bin/core/plugin-resolver-utils.js

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * @fileoverview Plugin discovery utilities for builtin, local, and npm sources.
+ * Scans directories and resolves plugin modules.
+ * @module plugin-resolver-utils
+ */
+
+const fs = require('./fs-adapter');
+const path = require('path');
+
+const BUILTIN_DIR = path.join(__dirname, '..', 'plugins');
+const LOCAL_DIR = '.i18n/plugins';
+
+/** @type {Record<string, string>} */
+const BUILTIN_ALIASES = {
+  '@i18nkit/parser-angular': 'parser-angular',
+  '@i18nkit/parser-primeng': 'parser-primeng',
+  '@i18nkit/parser-typescript': 'parser-typescript',
+  '@i18nkit/adapter-transloco': 'adapter-transloco',
+  '@i18nkit/provider-mymemory': 'provider-mymemory',
+  '@i18nkit/provider-deepl': 'provider-deepl',
+};
+
+const DEFAULT_PARSERS = ['parser-angular', 'parser-primeng', 'parser-typescript'];
+const DEFAULT_ADAPTER = 'adapter-transloco';
+const DEFAULT_PROVIDER = 'provider-mymemory';
+const TYPE_TO_PLURAL = Object.freeze({
+  parser: 'parsers',
+  adapter: 'adapters',
+  provider: 'providers',
+});
+
+const tryLoadPath = p => (fs.existsSync(p) ? require(p) : null);
+
+/**
+ * Resolves plugin from builtin or local directories.
+ * @param {string} identifier
+ * @param {string} cwd
+ * @returns {Plugin|null}
+ */
+function resolveFromBuiltinOrLocal(identifier, cwd) {
+  const aliased = BUILTIN_ALIASES[identifier] || identifier;
+  return (
+    tryLoadPath(path.join(BUILTIN_DIR, `${aliased}.js`)) ||
+    tryLoadPath(path.join(cwd, LOCAL_DIR, `${aliased}.js`))
+  );
+}
+
+/**
+ * Resolves plugin from relative path.
+ * @param {string} identifier
+ * @param {string} cwd
+ * @returns {Plugin|null}
+ */
+function resolveFromRelative(identifier, cwd) {
+  if (!identifier.startsWith('./') && !identifier.startsWith('../')) {
+    return null;
+  }
+  return tryLoadPath(path.resolve(cwd, identifier));
+}
+
+/**
+ * Resolves plugin from npm package.
+ * @param {string} identifier
+ * @returns {Plugin}
+ * @throws {Error} If plugin not found
+ */
+function resolveFromNpm(identifier) {
+  try {
+    return require(identifier);
+  } catch {
+    throw new Error(`Plugin not found: ${identifier}`);
+  }
+}
+
+function scanDir(dir, mapper) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(dir)
+    .filter(f => f.endsWith('.js'))
+    .map(mapper)
+    .filter(p => p?.name);
+}
+
+/**
+ * Scans builtin plugins directory.
+ * @returns {Plugin[]}
+ */
+function scanBuiltin() {
+  return scanDir(BUILTIN_DIR, f => {
+    try {
+      return require(path.join(BUILTIN_DIR, f));
+    } catch {
+      return null;
+    }
+  });
+}
+
+/**
+ * Scans local .i18n/plugins directory.
+ * @param {string} cwd
+ * @returns {Plugin[]}
+ */
+function scanLocal(cwd) {
+  return scanDir(path.join(cwd, LOCAL_DIR), f => {
+    try {
+      return require(path.join(cwd, LOCAL_DIR, f));
+    } catch {
+      return null;
+    }
+  });
+}
+
+function scanScopedDir(nodeModules, scope) {
+  const scopeDir = path.join(nodeModules, scope);
+  if (!fs.existsSync(scopeDir)) {
+    return [];
+  }
+  return fs.readdirSync(scopeDir).map(pkg => {
+    try {
+      return require(path.join(scopeDir, pkg));
+    } catch {
+      return null;
+    }
+  });
+}
+
+/**
+ * Scans npm packages for i18nkit-* and @i18nkit/* plugins.
+ * @param {string} cwd
+ * @returns {Plugin[]}
+ */
+function scanNpm(cwd) {
+  const nodeModules = path.join(cwd, 'node_modules');
+  if (!fs.existsSync(nodeModules)) {
+    return [];
+  }
+  const prefixed = fs
+    .readdirSync(nodeModules)
+    .filter(d => d.startsWith('i18nkit-'))
+    .map(d => {
+      try {
+        return require(path.join(nodeModules, d));
+      } catch {
+        return null;
+      }
+    });
+  const scoped = scanScopedDir(nodeModules, '@i18nkit');
+  return [...prefixed, ...scoped].filter(p => p?.name);
+}
+
+module.exports = {
+  DEFAULT_PARSERS,
+  DEFAULT_ADAPTER,
+  DEFAULT_PROVIDER,
+  TYPE_TO_PLURAL,
+  resolveFromBuiltinOrLocal,
+  resolveFromRelative,
+  resolveFromNpm,
+  scanBuiltin,
+  scanLocal,
+  scanNpm,
+};

package/bin/core/plugin-resolver.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * @fileoverview Plugin resolution engine with caching and auto-discovery.
+ * Resolves plugins from builtin, local (.i18n/plugins), and npm sources.
+ * @module plugin-resolver
+ */
+
+const { validatePlugin } = require('./plugin-interface');
+const {
+  DEFAULT_PARSERS,
+  DEFAULT_ADAPTER,
+  DEFAULT_PROVIDER,
+  TYPE_TO_PLURAL,
+  resolveFromBuiltinOrLocal,
+  resolveFromRelative,
+  resolveFromNpm,
+  scanBuiltin,
+  scanLocal,
+  scanNpm,
+} = require('./plugin-resolver-utils');
+
+/**
+ * Plugin resolution and registry management.
+ * Caches resolved plugins and maintains a registry of discovered plugins.
+ */
+class PluginResolver {
+  /**
+   * @param {string} [cwd=process.cwd()] - Working directory for resolution
+   */
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+    /** @type {Map<string, Plugin>} */
+    this.cache = new Map();
+    /** @type {PluginRegistry|null} */
+    this.registry = null;
+  }
+
+  /**
+   * Resolves a plugin by identifier (name, path, or npm package).
+   * @param {string} identifier - Plugin identifier
+   * @returns {Plugin|null}
+   */
+  resolve(identifier) {
+    if (this.cache.has(identifier)) {
+      return this.cache.get(identifier);
+    }
+    const plugin =
+      resolveFromBuiltinOrLocal(identifier, this.cwd) ||
+      resolveFromRelative(identifier, this.cwd) ||
+      resolveFromNpm(identifier);
+    this.cache.set(identifier, plugin);
+    return plugin;
+  }
+
+  /**
+   * Discovers all available plugins from all sources.
+   * @returns {PluginRegistry}
+   */
+  discoverAll() {
+    if (this.registry) {
+      return this.registry;
+    }
+    this.registry = {
+      parsers: [],
+      adapters: [],
+      providers: [],
+      all: [],
+      byName: new Map(),
+      errors: [],
+    };
+    this._loadFromSource('builtin', () => this._scanBuiltin());
+    this._loadFromSource('local', () => this._scanLocal());
+    this._loadFromSource('npm', () => this._scanNpm());
+    return this.registry;
+  }
+
+  _loadFromSource(sourceName, loader) {
+    try {
+      for (const plugin of loader()) {
+        this._registerPlugin({ ...plugin, source: sourceName });
+      }
+    } catch (err) {
+      this.registry.errors.push({ source: sourceName, error: err.message });
+    }
+  }
+
+  _handleInvalidPlugin(plugin, validation) {
+    this.registry.errors.push({
+      plugin: plugin.name || 'unknown',
+      source: plugin.source,
+      errors: validation.errors,
+    });
+  }
+
+  _addPluginToRegistry(plugin) {
+    this.registry.byName.set(plugin.name, plugin);
+    this.registry.all.push(plugin);
+    this.cache.set(plugin.name, plugin);
+    const plural = TYPE_TO_PLURAL[plugin.type];
+    if (plural) {
+      this.registry[plural].push(plugin);
+    }
+  }
+
+  _registerPlugin(plugin) {
+    const validation = validatePlugin(plugin);
+    if (!validation.valid) {
+      this._handleInvalidPlugin(plugin, validation);
+      return;
+    }
+    if (!this.registry.byName.has(plugin.name)) {
+      this._addPluginToRegistry(plugin);
+    }
+  }
+
+  _scanBuiltin() {
+    return scanBuiltin();
+  }
+
+  _scanLocal() {
+    return scanLocal(this.cwd);
+  }
+
+  _scanNpm() {
+    return scanNpm(this.cwd);
+  }
+
+  /**
+   * @param {'parser'|'adapter'|'provider'} type
+   * @returns {Plugin[]}
+   */
+  getByType(type) {
+    return this.discoverAll()[TYPE_TO_PLURAL[type]] || [];
+  }
+
+  /**
+   * @param {string} name
+   * @returns {Plugin|undefined}
+   */
+  getByName(name) {
+    return this.discoverAll().byName.get(name);
+  }
+
+  /**
+   * Filters plugins by detection context (framework, libraries detected).
+   * @param {DetectionContext} context
+   * @returns {Plugin[]}
+   */
+  filterByDetection(context) {
+    return this.discoverAll().all.filter(plugin => {
+      if (typeof plugin.detect !== 'function') {
+        return false;
+      }
+      try {
+        return plugin.detect(context);
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  /**
+   * Loads plugins from configuration with defaults.
+   * @param {Object} [config={}]
+   * @param {string[]} [config.parsers] - Parser plugin names
+   * @param {string} [config.adapter] - Adapter plugin name
+   * @param {string} [config.provider] - Provider plugin name
+   * @returns {{parsers: Plugin[], adapter: Plugin, provider: Plugin}}
+   */
+  loadFromConfig(config = {}) {
+    const parsers = (config.parsers || DEFAULT_PARSERS)
+      .map(name => this.resolve(name))
+      .sort((a, b) => (a.priority || 100) - (b.priority || 100));
+    return {
+      parsers,
+      adapter: this.resolve(config.adapter || DEFAULT_ADAPTER),
+      provider: this.resolve(config.provider || DEFAULT_PROVIDER),
+    };
+  }
+
+  reset() {
+    this.cache.clear();
+    this.registry = null;
+  }
+}
+
+/** @type {PluginResolver|null} */
+let defaultResolver = null;
+
+/**
+ * Gets or creates the default resolver for the given working directory.
+ * @param {string} [cwd=process.cwd()]
+ * @returns {PluginResolver}
+ */
+function getResolver(cwd = process.cwd()) {
+  if (!defaultResolver || defaultResolver.cwd !== cwd) {
+    defaultResolver = new PluginResolver(cwd);
+  }
+  return defaultResolver;
+}
+
+/**
+ * Convenience function to load plugins from config.
+ * @param {Object} [config={}]
+ * @param {string} [cwd=process.cwd()]
+ * @returns {{parsers: Plugin[], adapter: Plugin, provider: Plugin}}
+ */
+const loadPlugins = (config = {}, cwd = process.cwd()) => getResolver(cwd).loadFromConfig(config);
+
+module.exports = { getResolver, loadPlugins };