@abdess76/i18nkit 1.0.0

package/bin/core/index.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * @fileoverview i18nkit core library public API.
+ * Exposes all extraction, translation, and synchronization utilities.
+ * @module i18nkit/core
+ */
+
+const json = require('./json-utils');
+const keys = require('./key-generator');
+const files = require('./file-walker');
+const backup = require('./backup');
+const sync = require('./sync-checker');
+const orphans = require('./orphan-finder');
+const apply = require('./applier');
+const translate = require('./translator');
+const watch = require('./watcher');
+const plugins = require('./plugin-resolver');
+const config = require('./config');
+const detector = require('./detector');
+const help = require('./help-generator');
+const fsAdapter = require('./fs-adapter');
+const logUtils = require('./log-utils');
+
+module.exports = {
+  setFsAdapter: fsAdapter.setAdapter,
+  resetFsAdapter: fsAdapter.resetAdapter,
+
+  getArgValue: config.getArgValue,
+
+  readJsonFile: json.readJsonFile,
+  readJsonFileSync: json.readJsonFileSync,
+  writeJsonFile: json.writeJsonFile,
+  flattenJson: json.flattenJson,
+  unflattenJson: json.unflattenJson,
+  mergeDeep: json.mergeDeep,
+  setNestedValue: json.setNestedValue,
+  normalizeData: json.normalizeData,
+
+  logListWithLimit: logUtils.logListWithLimit,
+
+  slugify: keys.slugify,
+  pathToScope: keys.pathToScope,
+
+  collectFiles: files.collectFiles,
+  getFileContent: files.getFileContent,
+
+  restoreBackups: backup.restoreBackups,
+  getBackupFiles: backup.getBackupFiles,
+
+  checkSync: sync.checkSync,
+  findOrphans: orphans.findOrphans,
+  applyFindings: apply.applyFindings,
+  applyTranslations: apply.applyTranslations,
+  translateFile: translate.translateFile,
+  watchFiles: watch.watchFiles,
+
+  loadPlugins: plugins.loadPlugins,
+  getResolver: plugins.getResolver,
+
+  detectProject: detector.detectProject,
+  generateFullHelp: help.generateFullHelp,
+};

package/bin/core/json-utils.js

@@ -0,0 +1,213 @@
+'use strict';
+
+/**
+ * @fileoverview JSON manipulation utilities for nested i18n structures.
+ * Handles flattening, unflattening, deep merging, and ICU message detection.
+ * @module json-utils
+ */
+
+const fs = require('./fs-adapter');
+const path = require('path');
+
+const KEY_SEPARATOR = ':::';
+
+/**
+ * @param {string} filePath
+ * @param {boolean} [verbose=false]
+ * @returns {Object|null}
+ */
+function readJsonFileSync(filePath, verbose = false) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    if (verbose) {
+      console.warn(`Warning: Cannot parse ${filePath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {boolean} [verbose=false]
+ * @returns {Promise<Object|null>}
+ */
+async function readJsonFile(filePath, verbose = false) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    if (verbose) {
+      console.warn(`Warning: Cannot parse ${filePath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object} data
+ * @returns {Promise<void>}
+ */
+async function writeJsonFile(filePath, data) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+function navigateToParent(obj, keyPath) {
+  let current = obj;
+  for (let i = 0; i < keyPath.length - 1; i++) {
+    current[keyPath[i]] ??= {};
+    current = current[keyPath[i]];
+  }
+  return current;
+}
+
+function resolveFinalKey(current, key, value) {
+  if (current[key] && current[key] !== value) {
+    return `${key}_${hashText(value)}`;
+  }
+  return key;
+}
+
+function setNestedValue(obj, keyPath, value) {
+  const current = navigateToParent(obj, keyPath);
+  const originalKey = keyPath.at(-1);
+  const existed = Object.hasOwn(current, originalKey);
+  const finalKey = resolveFinalKey(current, originalKey, value);
+  current[finalKey] = value;
+  return { path: [...keyPath.slice(0, -1), finalKey], isNew: !existed };
+}
+
+function getNestedValue(obj, keyPath) {
+  let current = obj;
+  for (const key of keyPath) {
+    if (!current || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+const isNestedObject = v => typeof v === 'object' && v !== null;
+const buildKey = (prefix, key) => (prefix ? `${prefix}.${key}` : key);
+
+function flattenKeys(obj, prefix = '') {
+  return Object.entries(obj).flatMap(([key, value]) => {
+    const fullKey = buildKey(prefix, key);
+    return isNestedObject(value) ? flattenKeys(value, fullKey) : [fullKey];
+  });
+}
+
+const escapeKey = key => (key.includes('.') ? key.replaceAll('.', KEY_SEPARATOR) : key);
+const unescapeKey = key => (key.includes(KEY_SEPARATOR) ? key.replaceAll(KEY_SEPARATOR, '.') : key);
+
+const isPlainObject = v => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * Flattens nested JSON to dot-notation keys
+ * @param {Object} obj
+ * @param {string} [prefix='']
+ * @returns {Record<string, string>}
+ * @example
+ * flattenJson({ user: { name: 'John' } }) // { 'user.name': 'John' }
+ */
+function flattenJson(obj, prefix = '') {
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    const fullKey = buildKey(prefix, escapeKey(key));
+    return isPlainObject(value) ?
+        { ...acc, ...flattenJson(value, fullKey) }
+      : { ...acc, [fullKey]: value };
+  }, {});
+}
+
+function ensurePath(obj, parts) {
+  return parts.slice(0, -1).reduce((current, part) => {
+    if (!Object.hasOwn(current, part) || !isPlainObject(current[part])) {
+      current[part] = {};
+    }
+    return current[part];
+  }, obj);
+}
+
+/**
+ * Restores nested structure from dot-notation keys
+ * @param {Record<string, string>} obj
+ * @returns {Object}
+ * @example
+ * unflattenJson({ 'user.name': 'John' }) // { user: { name: 'John' } }
+ */
+function unflattenJson(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const parts = key.split('.').map(unescapeKey);
+    ensurePath(result, parts)[parts.at(-1)] = value;
+  }
+  return result;
+}
+
+function mergeValue(result, key, value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (isPlainObject(value)) {
+    return mergeDeep(result[key] ?? {}, value);
+  }
+  return Object.hasOwn(result, key) ? result[key] : value;
+}
+
+/**
+ * Deep merges source into target, preserving existing values
+ * @param {Object} target
+ * @param {Object} source
+ * @returns {Object}
+ */
+function mergeDeep(target, source) {
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    result[key] = mergeValue(result, key, value);
+  }
+  return result;
+}
+
+function hashText(text) {
+  let hash = 0;
+  for (let i = 0; i < text.length; i++) {
+    const char = text.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash |= 0;
+  }
+  return Math.abs(hash).toString(36).substring(0, 6);
+}
+
+/**
+ * Detects ICU MessageFormat syntax (plural, select, selectordinal)
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isICUMessage(value) {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  return /\{[^}]+,\s*(plural|select|selectordinal)\s*,/.test(value);
+}
+
+function normalizeData(data, format) {
+  const isFlat = format === 'flat' || typeof Object.values(data)[0] === 'string';
+  return isFlat ? unflattenJson(data) : data;
+}
+
+module.exports = {
+  readJsonFileSync,
+  readJsonFile,
+  writeJsonFile,
+  setNestedValue,
+  getNestedValue,
+  flattenKeys,
+  flattenJson,
+  unflattenJson,
+  mergeDeep,
+  isICUMessage,
+  normalizeData,
+};

package/bin/core/key-generator.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * @fileoverview Translation key generation from source text.
+ * Slugifies text and derives scope from file paths.
+ * @module key-generator
+ */
+
+const path = require('path');
+const { decodeHtmlEntities } = require('./parser-utils');
+
+const MAX_KEY_LENGTH = 50;
+
+/**
+ * Converts text to a translation key (lowercase, underscored, max 50 chars)
+ * @param {string} text
+ * @returns {string}
+ * @example
+ * slugify("Hello World!") // "hello_world"
+ */
+function slugify(text) {
+  return (
+    decodeHtmlEntities(text)
+      .toLowerCase()
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .replace(/'/g, '')
+      .replace(/[^a-z0-9\s]/g, ' ')
+      .trim()
+      .split(/\s+/)
+      .filter(w => w.length > 1)
+      .slice(0, 6)
+      .join('_')
+      .substring(0, MAX_KEY_LENGTH) || 'text'
+  );
+}
+
+/**
+ * Derives scope array from file path (e.g., "users/profile.component.ts" → ["users", "profile"])
+ * @param {string} filePath
+ * @param {string} baseDir
+ * @returns {string[]}
+ */
+function pathToScope(filePath, baseDir) {
+  const relative = path.relative(baseDir, filePath);
+  const parts = relative.split(path.sep);
+  const fileName = parts
+    .pop()
+    .replace(/\.(component|html|ts)$/g, '')
+    .replace(/\.component$/, '');
+
+  const ignoredFolders = [
+    'components',
+    'pages',
+    'shared',
+    'common',
+    'features',
+    'dialogs',
+    'forms',
+    'ui',
+    'lib',
+  ];
+  const significantParts = parts.filter(p => !ignoredFolders.includes(p));
+
+  const scope = significantParts
+    .concat(fileName !== 'app' && fileName !== parts.at(-1) ? [fileName] : [])
+    .filter(Boolean);
+
+  return scope.length > 0 ? scope : ['app'];
+}
+
+module.exports = {
+  slugify,
+  pathToScope,
+};

package/bin/core/log-utils.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * @fileoverview Logging utilities for CLI output formatting.
+ * @module log-utils
+ */
+
+/**
+ * Logs a list with truncation after limit
+ * @param {Object} ctx
+ */
+function logListWithLimit(ctx) {
+  const { items, label, limit, log, prefix = '  - ', formatter = item => item } = ctx;
+  if (items.length === 0) {
+    return;
+  }
+  log(`${label} (${items.length}):`);
+  items.slice(0, limit).forEach(item => log(`${prefix}${formatter(item)}`));
+  if (items.length > limit) {
+    log(`  ... and ${items.length - limit} more`);
+  }
+}
+
+module.exports = {
+  logListWithLimit,
+};

package/bin/core/orphan-finder.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * @fileoverview Unused translation key detector.
+ * Scans source files to identify orphan keys not referenced in code.
+ * @module orphan-finder
+ */
+
+const path = require('path');
+const fs = require('./fs-adapter');
+const { readJsonFile, flattenKeys, normalizeData } = require('./json-utils');
+const { collectFiles } = require('./file-walker');
+const { isTranslationFile, readI18nDirectory } = require('./sync-checker');
+const { logListWithLimit } = require('./log-utils');
+
+const DYNAMIC_KEY_RE = /(?:translate|transloco)\s*\(\s*[`'"]([^`'"]*)\$\{/g;
+const CONCAT_KEY_RE = /['"`]([^'"`]+)['"]\s*\+\s*(?:\w+|['"`])/g;
+
+async function getLangFiles(i18nDir) {
+  const dirEntries = await readI18nDirectory(i18nDir);
+  return dirEntries.filter(isTranslationFile).map(e => e.name);
+}
+
+async function loadRefData(i18nDir, refFile, format) {
+  const refData = await readJsonFile(path.join(i18nDir, refFile));
+  if (!refData) {
+    throw new Error(`Cannot parse ${refFile}`);
+  }
+  return { refFile, allKeys: flattenKeys(normalizeData(refData, format)) };
+}
+
+async function loadReferenceKeysForOrphans(ctx) {
+  const { i18nDir, format, log } = ctx;
+  const langFiles = await getLangFiles(i18nDir);
+  if (langFiles.length === 0) {
+    log('No language files found.');
+    return null;
+  }
+  return loadRefData(i18nDir, langFiles[0], format);
+}
+
+function detectDynamicPatterns(content, relPath, dynamicPatterns) {
+  for (const match of content.matchAll(DYNAMIC_KEY_RE)) {
+    dynamicPatterns.push({ file: relPath, pattern: `${match[1]}...` });
+  }
+  for (const match of content.matchAll(CONCAT_KEY_RE)) {
+    if (match[1].includes('.') && !match[1].includes(' ')) {
+      dynamicPatterns.push({ file: relPath, pattern: `${match[1]}+...` });
+    }
+  }
+}
+
+function scanFileForKeyUsage(ctx) {
+  const { content, relPath, allKeys, keyUsageMap, dynamicPatterns } = ctx;
+  detectDynamicPatterns(content, relPath, dynamicPatterns);
+
+  const keySet = new Set(allKeys.filter(k => !keyUsageMap.get(k)));
+  if (keySet.size === 0) {
+    return;
+  }
+
+  const keyPattern = new RegExp(
+    `['"\`](${[...keySet].map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})['"\`]`,
+    'g',
+  );
+  for (const match of content.matchAll(keyPattern)) {
+    keyUsageMap.set(match[1], true);
+  }
+}
+
+async function scanAllFilesForKeys(files, ctx) {
+  const { srcDir, allKeys, keyUsageMap, dynamicPatterns, verbose } = ctx;
+  await Promise.all(
+    files.map(async filePath => {
+      try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        scanFileForKeyUsage({
+          content,
+          relPath: path.relative(srcDir, filePath),
+          allKeys,
+          keyUsageMap,
+          dynamicPatterns,
+        });
+      } catch (err) {
+        if (verbose) {
+          console.warn(`Warning: Cannot read ${path.relative(srcDir, filePath)}: ${err.message}`);
+        }
+      }
+    }),
+  );
+}
+
+function partitionKeyUsage(keyUsageMap) {
+  const usedKeys = [];
+  const orphanKeys = [];
+  for (const [key, used] of keyUsageMap) {
+    (used ? usedKeys : orphanKeys).push(key);
+  }
+  return { usedKeys, orphanKeys };
+}
+
+function logDynamicPatterns(dynamicPatterns, log) {
+  if (dynamicPatterns.length === 0) {
+    return;
+  }
+  const uniquePatterns = [...new Set(dynamicPatterns.map(p => p.pattern))];
+  logListWithLimit({
+    items: uniquePatterns,
+    label: `Dynamic key patterns detected`,
+    limit: 5,
+    log,
+    prefix: '  [!] ',
+  });
+  log('  (Some orphans may be false positives due to dynamic keys)\n');
+}
+
+function logOrphanResults(results, log) {
+  const { dynamicPatterns, orphanKeys, allKeys, usedKeys } = results;
+  logDynamicPatterns(dynamicPatterns, log);
+
+  if (orphanKeys.length > 0) {
+    logListWithLimit({ items: orphanKeys, label: 'Orphan keys', limit: 20, log });
+  } else {
+    log('No orphan keys found.');
+  }
+
+  log(`\nSummary\n${'-'.repeat(50)}`);
+  log(`Total keys:      ${allKeys.length}\nUsed keys:       ${usedKeys.length}`);
+  log(`Orphan keys:     ${orphanKeys.length}\nDynamic patterns: ${dynamicPatterns.length}`);
+}
+
+async function scanAndCollect(ctx) {
+  const { srcDir, excludedFolders, allKeys, verbose } = ctx;
+  const keyUsageMap = new Map(allKeys.map(k => [k, false]));
+  const dynamicPatterns = [];
+  const files = await collectFiles(srcDir, excludedFolders);
+  await scanAllFilesForKeys(files, { srcDir, allKeys, keyUsageMap, dynamicPatterns, verbose });
+  const { usedKeys, orphanKeys } = partitionKeyUsage(keyUsageMap);
+  return { usedKeys, orphanKeys, dynamicPatterns, allKeys };
+}
+
+function buildOrphanResult(ctx) {
+  const { results, strict, exitCodes, log } = ctx;
+  const hasOrphans = strict && results.orphanKeys.length > 0;
+  if (hasOrphans) {
+    log('\nOrphan check failed (--strict mode)');
+  }
+  return {
+    success: !hasOrphans,
+    exitCode: hasOrphans ? exitCodes.untranslated : exitCodes.success,
+    ...results,
+  };
+}
+
+function logOrphanHeader(log) {
+  log('Transloco Find Orphan Keys');
+  log('='.repeat(50));
+}
+
+function getOrphanExitCodes(options) {
+  return options.exitCodes || { success: 0, untranslated: 1 };
+}
+
+function handleNoRef(exitCodes) {
+  return { success: true, exitCode: exitCodes.success, orphanKeys: [] };
+}
+
+async function executeOrphanScan(ctx) {
+  const { srcDir, excludedFolders, allKeys, verbose, refFile, log, strict, exitCodes } = ctx;
+  log(`Reference: ${refFile} (${allKeys.length} keys)\nScanning: ${srcDir}\n`);
+  const results = await scanAndCollect({ srcDir, excludedFolders, allKeys, verbose });
+  logOrphanResults(results, log);
+  return buildOrphanResult({ results, strict, exitCodes, log });
+}
+
+function getOrphanDefaults() {
+  return { format: 'nested', excludedFolders: [], verbose: false, strict: false, log: console.log };
+}
+
+function parseOrphanOptions(options) {
+  const defaults = getOrphanDefaults();
+  return { ...defaults, ...options, exitCodes: getOrphanExitCodes(options) };
+}
+
+/**
+ * Scans source files to find translation keys not used in code
+ * @param {OrphanOptions} [options]
+ * @returns {Promise<OrphanResult>}
+ * @example
+ * const { orphanKeys } = await findOrphans({ i18nDir: './src/i18n', srcDir: './src/app' });
+ */
+async function findOrphans(options = {}) {
+  const opts = parseOrphanOptions(options);
+  logOrphanHeader(opts.log);
+  const refResult = await loadReferenceKeysForOrphans({
+    i18nDir: opts.i18nDir,
+    format: opts.format,
+    log: opts.log,
+  });
+  if (!refResult) {
+    return handleNoRef(opts.exitCodes);
+  }
+  return executeOrphanScan({ ...refResult, ...opts });
+}
+
+module.exports = {
+  findOrphans,
+};