i18ntk 2.3.7 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18ntk",
-  "version": "2.3.7",
+  "version": "2.4.0",
   "description": "🚀 The fastest internationalization toolkit with 97% performance boost! Zero-dependency, enterprise-grade internationalization for React, Vue, Angular, Python, Java, PHP & more. Features PIN protection, auto framework detection, 7+ UI languages, and comprehensive translation management. Perfect for startups to enterprises.",
   "keywords": [
     "i18n",
@@ -213,7 +213,7 @@
     "languages:select": "node settings/settings-cli.js",
     "languages:list": "node settings/settings-cli.js --list-languages",
     "languages:status": "node settings/settings-cli.js --language-status",
-    "lint:locales": "node scripts/lint-locales.js" 
+    "lint:locales": "node scripts/lint-locales.js"
   },
   "engines": {
     "node": ">=16.0.0",
@@ -224,26 +224,29 @@
   },
   "preferGlobal": true,
   "versionInfo": {
-    "version": "2.3.7",
-    "releaseDate": "12/04/2026",
-    "lastUpdated": "12/04/2026",
+    "version": "2.4.0",
+    "releaseDate": "16/04/2026",
+    "lastUpdated": "16/04/2026",
     "maintainer": "Vlad Noskov",
     "changelog": "./CHANGELOG.md",
     "documentation": "./README.md",
     "apiReference": "./docs/api/API_REFERENCE.md",
     "majorChanges": [
+      "LOGGING: Introduced centralized structured logger with silent-by-default production behavior and DEBUG_MODE/JSON_LOG toggles.",
+      "SECURITY: Added internal path whitelist detection to prevent false-positive traversal warnings for package/project internals.",
+      "I18N: Added missing-key warning TTL cache to eliminate repeated translation-key spam during builds.",
       "HOTFIX: Removed deprecated package-path fallback that caused production build warnings for non-exported subpaths.",
       "CRITICAL FIX: Resolved sizing and usage-analysis regressions in v2 command flow.",
       "PACKAGING: Reduced publish footprint by removing internal development scripts and legacy fixed-file artifacts.",
       "SECURITY: Hardened release checks and added explicit support guidance to update from pre-2.3.5 versions.",
       "CONFIG: Added cross-process file locking for .i18ntk-config writes to prevent production rename races.",
       "CONFIG: Made autosave runtime-safe with non-throwing save failures and I18NTK_DISABLE_AUTOSAVE support.",
-      "SECURITY: Hardened reset/backup path handling and made npm update checks explicit opt-in.",
-      "CLI: Added npm registry version check with upgrade warning for out-of-date installs.",
+      "SECURITY: Hardened reset/backup path handling and disabled manager backup-route execution in current builds.",
+      "CLI: Removed npm registry startup update checks to eliminate outbound network calls in scanner-restricted environments.",
       "I18N: Completed internal UI locale parity and actionable untranslated-key cleanup across supported languages."
     ],
     "breakingChanges": [],
-    "nextVersion": "2.4.0",
+    "nextVersion": "2.4.1",
     "supportedNodeVersions": ">=16.0.0",
     "supportedFrameworks": {
       "react-i18next": ">=11.0.0",
@@ -265,7 +268,7 @@
       "spring-boot": ">=2.5.0",
       "laravel": ">=8.0.0"
     },
-    "supportPolicy": "Versions earlier than 2.3.7 may be unstable or insecure. Upgrade to 2.3.6 or newer."
+    "supportPolicy": "Versions earlier than 2.4.0 may be unstable or insecure. Upgrade to 2.4.0 or newer."
   },
   "_comment": "This package is zero-dependency and uses only native Node.js modules"
 }

package/utils/config-manager.js

@@ -1,8 +1,9 @@
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
-const SecurityUtils = require('./security');
+const os = require('os');
+const crypto = require('crypto');
+const SecurityUtils = require('./security');
+const { logger } = require('./logger');
 
 // Determine package directory and user project root
 const packageDir = path.resolve(__dirname, '..');
@@ -19,7 +20,55 @@ const CONFIG_LOCK_PATH = `${PROJECT_CONFIG_PATH}.lock`;
 const CONFIG_LOCK_TIMEOUT_MS = 5000;
 const CONFIG_LOCK_STALE_MS = 15000;
 const CONFIG_LOCK_RETRY_MS = 50;
-let autosaveDisabledWarned = false;
+let autosaveDisabledWarned = false;
+let defaultConfigNoticeShown = false;
+let configFallbackNoticeShown = false;
+
+function logInfo(message, details) {
+  logger.info(message, details);
+}
+
+function logWarn(message, details) {
+  logger.warn(message, details);
+}
+
+function logError(message, details) {
+  logger.error(message, details);
+}
+
+function notifyDefaultConfig(reason, error) {
+  if (defaultConfigNoticeShown) {
+    return;
+  }
+  defaultConfigNoticeShown = true;
+
+  logger.info('Using default configuration (reason: configuration error)', { reason });
+  if (logger.isDebugMode() && error) {
+    logger.debug(`Default configuration reason details: ${error.message}`, {
+      stack: error.stack
+    });
+  }
+}
+
+function notifyConfigFallback(error) {
+  if (!configFallbackNoticeShown) {
+    configFallbackNoticeShown = true;
+    logger.info('Using default configuration (reason: configuration error)', {
+      reason: 'configuration error'
+    });
+  }
+
+  logger.recordFirstError('config:load-fallback', {
+    message: error && error.message ? error.message : 'Unknown configuration error',
+    stack: error && error.stack ? error.stack : null
+  });
+
+  if (logger.isDebugMode() && error) {
+    logger.debug(`Configuration load fallback details: ${error.message}`, {
+      stack: error.stack
+    });
+  }
+}
 
 // Setup tracking file
 const SETUP_COMPLETED_FILE = path.join(PROJECT_SETTINGS_DIR, 'setup.json');
@@ -381,7 +430,7 @@ function tryReadJson(filePath) {
 
     const data = SecurityUtils.safeReadFileSync(filePath, path.dirname(filePath), 'utf8');
     if (!data || data.trim() === '') {
-      console.warn(`[i18ntk] Warning: Empty or invalid JSON file at ${filePath}`);
+      logWarn(`[i18ntk] Warning: Empty or invalid JSON file at ${filePath}`);
       return null;
     }
 
@@ -390,18 +439,18 @@ function tryReadJson(filePath) {
       return parsed;
     }
 
-    console.error(`[i18ntk] Error parsing JSON from ${filePath}: Invalid JSON content`);
+    logError(`[i18ntk] Error parsing JSON from ${filePath}: Invalid JSON content`);
     // Create a backup of the corrupted file
     const backupPath = `${filePath}.corrupted-${Date.now()}.bak`;
     try {
       SecurityUtils.safeWriteFileSync(backupPath, data, path.dirname(backupPath), 'utf8');
-      console.warn(`[i18ntk] Created backup of corrupted config at ${backupPath}`);
+      logWarn(`[i18ntk] Created backup of corrupted config at ${backupPath}`);
     } catch (backupError) {
-      console.error(`[i18ntk] Failed to create backup of corrupted config: ${backupError.message}`);
+      logError(`[i18ntk] Failed to create backup of corrupted config: ${backupError.message}`);
     }
     return null;
   } catch (error) {
-    console.error(`[i18ntk] Error reading config file at ${filePath}: ${error.message}`);
+    logError(`[i18ntk] Error reading config file at ${filePath}: ${error.message}`);
     return null;
   }
 }
@@ -420,11 +469,11 @@ async function migrateLegacyIfNeeded(baseCfg) {
         // Best-effort removal of legacy file to prevent future use
         try { fs.unlinkSync(LEGACY_CONFIG_PATH); } catch (_) {}
         // Deprecation notice
-        console.warn('[i18ntk] Deprecated config location detected (~/.i18ntk). Configuration was migrated to project .i18ntk-config.');
+        logWarn('[i18ntk] Deprecated config location detected (~/.i18ntk). Configuration was migrated to project .i18ntk-config.');
         return merged;
       } catch (_) {
         // If write fails, fall back to in-memory config without deleting legacy
-        console.warn('[i18ntk] Deprecated config location detected (~/.i18ntk). Using migrated settings in memory; failed to persist to .i18ntk-config.');
+        logWarn('[i18ntk] Deprecated config location detected (~/.i18ntk). Using migrated settings in memory; failed to persist to .i18ntk-config.');
         return merged;
       }
     }
@@ -445,7 +494,7 @@ function loadConfig() {
 
     // Prevent concurrent loading
     if (configLoadInProgress) {
-      console.warn('[i18ntk] Configuration loading already in progress, returning defaults');
+      logWarn('[i18ntk] Configuration loading already in progress, returning defaults');
       resetRecursionGuard();
       return clone(DEFAULT_CONFIG);
     }
@@ -472,7 +521,7 @@ function loadConfig() {
          // Attempt to migrate to project settings
          // Ignore migration errors; we still return merged cfg in memory
          // eslint-disable-next-line no-unused-vars
-         console.warn('[i18ntk] Detected legacy config at ~/.i18ntk. Migrating to project settings directory...');
+         logWarn('[i18ntk] Detected legacy config at ~/.i18ntk. Migrating to project settings directory...');
          const _ = (async () => { await migrateLegacyIfNeeded(DEFAULT_CONFIG); })();
        }
      }
@@ -481,7 +530,8 @@ function loadConfig() {
      currentConfig = cfg;
      return currentConfig;
    } catch (error) {
-     console.error('[i18ntk] Error in loadConfig:', error.message);
+     logError('[i18ntk] Error in loadConfig', { error: error.message });
+     notifyConfigFallback(error);
      currentConfig = clone(DEFAULT_CONFIG);
      return currentConfig;
    } finally {
@@ -498,7 +548,7 @@ async function saveConfig(cfg = currentConfig) {
     currentConfig = cfg;
     if (!autosaveDisabledWarned) {
       autosaveDisabledWarned = true;
-      console.warn('[i18ntk] Autosave disabled by I18NTK_DISABLE_AUTOSAVE. Keeping configuration in memory only.');
+      logWarn('[i18ntk] Autosave disabled by I18NTK_DISABLE_AUTOSAVE. Keeping configuration in memory only.');
     }
     return false;
   }
@@ -540,7 +590,7 @@ async function saveConfig(cfg = currentConfig) {
       currentConfig = cfg;
       return true;
     } catch (error) {
-      console.error('[i18ntk] Error saving configuration:', error.message);
+      logError('[i18ntk] Error saving configuration', { error: error.message });
       return false;
     } finally {
       if (releaseLock) {
@@ -593,7 +643,7 @@ function getConfig() {
 
      // Check for legacy config for migration
      if (SecurityUtils.safeExistsSync(LEGACY_CONFIG_PATH)) {
-       console.log('📦 Migrating legacy configuration...');
+       logInfo('Migrating legacy configuration');
        const legacyRaw = SecurityUtils.safeReadFileSync(LEGACY_CONFIG_PATH, path.dirname(LEGACY_CONFIG_PATH), 'utf8');
        const legacyConfig = SecurityUtils.safeParseJSON(legacyRaw);
        if (!legacyConfig || typeof legacyConfig !== 'object') {
@@ -601,7 +651,7 @@ function getConfig() {
        }
        const migratedConfig = { ...DEFAULT_CONFIG, ...legacyConfig };
        saveConfig(migratedConfig).catch((err) => {
-         console.warn('[i18ntk] Warning: failed to persist migrated configuration:', err.message);
+         logWarn('[i18ntk] Warning: failed to persist migrated configuration', { error: err.message });
        });
        currentConfig = migratedConfig;
 
@@ -619,18 +669,18 @@ function getConfig() {
      }
 
      // Use package defaults for new installation
-     console.log('📦 Initializing with default configuration...');
-     saveConfig(DEFAULT_CONFIG).catch((err) => {
-       console.warn('[i18ntk] Warning: failed to persist default configuration:', err.message);
-     });
-     currentConfig = DEFAULT_CONFIG;
-     return resolvePaths(DEFAULT_CONFIG);
-
-   } catch (error) {
-     console.warn('⚠️  Error loading configuration, using defaults:', error.message);
-     currentConfig = DEFAULT_CONFIG;
-     return resolvePaths(DEFAULT_CONFIG);
-   }
+     notifyDefaultConfig('default initialization');
+     saveConfig(DEFAULT_CONFIG).catch((err) => {
+       logWarn('[i18ntk] Warning: failed to persist default configuration', { error: err.message });
+     });
+     currentConfig = DEFAULT_CONFIG;
+     return resolvePaths(DEFAULT_CONFIG);
+
+   } catch (error) {
+     notifyConfigFallback(error);
+     currentConfig = DEFAULT_CONFIG;
+     return resolvePaths(DEFAULT_CONFIG);
+   }
 }
 
 async function setConfig(cfg) {
@@ -693,3 +743,7 @@ module.exports = {
   toRelative,
   normalizePathValue,
 }
+
+
+
+

package/utils/config.js

@@ -1,6 +1,7 @@
-const fs = require('fs');
-const path = require('path');
-const SecurityUtils = require('./security');
+const fs = require('fs');
+const path = require('path');
+const SecurityUtils = require('./security');
+const { logger } = require('./logger');
 
 const settingsManager = require('../settings/settings-manager');
 const CONFIG_FILE = 'i18ntk-config.json';
@@ -66,11 +67,11 @@ function loadConfig(cwd = settingsManager.configDir) {
     }
     
     throw new Error('Invalid configuration format');
-  } catch (error) {
-    console.error(`Error loading config: ${error.message}`);
-    return null;
-  }
-}
+  } catch (error) {
+    logger.debug(`Error loading config: ${error.message}`, { stack: error.stack });
+    return null;
+  }
+}
 
 /**
  * Saves configuration to file
@@ -96,11 +97,11 @@ function saveConfig(config, cwd = settingsManager.configDir) {
     );
     
     return true;
-  } catch (error) {
-    console.error(`Error saving config: ${error.message}`);
-    return false;
-  }
-}
+  } catch (error) {
+    logger.error(`Error saving config: ${error.message}`);
+    return false;
+  }
+}
 
 /**
  * Ensures default values for configuration
@@ -127,4 +128,4 @@ module.exports = {
   saveConfig, 
   ensureConfigDefaults,
   validatePath // Exported for testing
-};
+};

package/utils/i18n-helper.js

@@ -1,6 +1,7 @@
 // utils/i18n-helper.js
-const path = require('path');
-const fs = require('fs');
+const path = require('path');
+const fs = require('fs');
+const { logger } = require('./logger');
 
 // Lazy load SecurityUtils to prevent circular dependencies
 let securityUtils;
@@ -200,10 +201,21 @@ function findLocaleFilesAllDirs(lang, preferredDir) {
   return files;
 }
 
-let translations = {};
-let currentLanguage = 'en';
-let isInitialized = false;
-const missingWarned = new Set();
+let translations = {};
+let currentLanguage = 'en';
+let isInitialized = false;
+const missingKeyCache = new Map();
+const missingKeyTtlMs = 5 * 60 * 1000;
+
+function shouldReportMissingKey(key) {
+  const now = Date.now();
+  const expiresAt = missingKeyCache.get(key) || 0;
+  if (expiresAt > now) {
+    return false;
+  }
+  missingKeyCache.set(key, now + missingKeyTtlMs);
+  return true;
+}
 
 function loadTranslations(language) {
   const cfg = safeRequireConfig();
@@ -286,9 +298,11 @@ function loadTranslations(language) {
   currentLanguage = 'en';
   isInitialized = true;
 
-  if (loadErrors.length > 0) {
-    console.warn(`⚠️ No valid UI locale files found. Using built-in English strings.`);
-  }
+  if (loadErrors.length > 0) {
+    logger.warn('No valid UI locale files found. Using built-in English strings.', {
+      errorCount: loadErrors.length
+    });
+  }
 
   return translations;
 }
@@ -337,23 +351,24 @@ function t(key, params = {}) {
     }
   }
 
-  if (typeof value === 'undefined') {
-    if (!missingWarned.has(key)) {
-      missingWarned.add(key);
-      console.warn(`Translation key not found: ${key}`);
-    }
-    return key;
-  }
+  if (typeof value === 'undefined') {
+    if (shouldReportMissingKey(key)) {
+      logger.logMissingTranslationKey(key, 'Configuration error');
+    }
+    return key;
+  }
 
   // If we found a string, interpolate parameters
   if (typeof value === 'string') {
     return interpolateParams(value, params);
   }
 
-  // Return the key if the final value is not a string
-  console.warn(`Translation key does not resolve to a string: ${key}`);
-  return key;
-}
+  // Return the key if the final value is not a string
+  if (shouldReportMissingKey(`${key}:non-string`)) {
+    logger.warn(`Translation key does not resolve to a string: ${key}`);
+  }
+  return key;
+}
 
 /**
  * Interpolate parameters into a translation string