@lang-tag/cli 0.11.0 → 0.11.2

package/README.md

@@ -14,7 +14,7 @@ The core is optimized for performance, with a bundle size of just **~1KB** ([che
 
 ### Effortless translation structure
 
-Instead of manually managing centralized translation files, `lang-tag` lets you colocate keys within components and automatically organizes them into namespaces based on your project structure. For example, all components in `components/orders` or pages in `pages/order` share the `orders` namespace. You define a simple folder-to-namespace mapping once, and `lang-tag` handles merging and file organization—while you retain full control over how namespaces are merged. 
+Instead of manually managing centralized translation files, `lang-tag` lets you colocate keys within components and automatically organizes them into namespaces based on your project structure. For example, all components in `components/orders` or pages in `pages/order` share the `orders` namespace. You define a simple directory-to-namespace mapping once, and `lang-tag` handles merging and file organization—while you retain full control over how namespaces are merged. 
 
 > Set your rules, then let `lang-tag` do the rest.
 
@@ -23,7 +23,7 @@ Instead of manually managing centralized translation files, `lang-tag` lets you
 Full functionality is available through an advanced CLI that keeps your application bundle size untouched:
 
 - **Automatic translation collection** – `lang-tag collect` scans your project for translation tags and aggregates them into organized JSON files (e.g., `public/locales/en/common.json`), based on your configuration
-- **Dynamic configuration updates** – `lang-tag regenerate-tags` automatically refreshes translation settings in your code, using rules defined in your configuration (e.g., mapping namespaces based on folder structure)
+- **Dynamic configuration updates** – `lang-tag regenerate-tags` automatically refreshes translation settings in your code, using rules defined in your configuration (e.g., mapping namespaces based on directory structure)
 - **Third-party translation import** – `lang-tag import` detects and integrates translations from external libraries, adapting them to your project’s translation system
 - **Watch mode** – `lang-tag watch` monitors your source files for changes and automatically re-collects/re-generates translations when needed
 

package/algorithms/config-generation/path-based-config-generator.d.ts

@@ -6,26 +6,26 @@ export interface PathBasedConfigGeneratorOptions {
      */
     includeFileName?: boolean;
     /**
-     * Whether to completely remove folders wrapped in brackets () or [].
-     * If false, only the brackets are removed from folder names.
+     * Whether to completely remove directories wrapped in brackets () or [].
+     * If false, only the brackets are removed from directory names.
      * @default true
      *
      * @example
      * - true: 'app/(admin)/users' -> 'app/users'
      * - false: 'app/(admin)/users' -> 'app/admin/users'
      */
-    removeBracketedFolders?: boolean;
+    removeBracketedDirectories?: boolean;
     /**
-     * List of folder names to completely ignore globally.
+     * List of directory names to completely ignore globally.
      * These will be removed from all paths regardless of their position.
      * @default []
      *
      * @example ['src', 'app', 'components']
      */
-    ignoreFolders?: string[];
+    ignoreDirectories?: string[];
     /**
-     * When true, automatically extracts root folder names from the config.includes patterns
-     * and adds them to the ignoreFolders list.
+     * When true, automatically extracts root directory names from the config.includes patterns
+     * and adds them to the ignoreDirectories list.
      *
      * @default false
      *
@@ -36,9 +36,9 @@ export interface PathBasedConfigGeneratorOptions {
      * // With includes: ['(src|app)/**\/*.{js,ts,jsx,tsx}', 'components/**\/*.{jsx,tsx}']
      * // Automatically ignores: ['src', 'app', 'components']
      */
-    ignoreIncludesRootFolders?: boolean;
+    ignoreIncludesRootDirectories?: boolean;
     /**
-     * Hierarchical structure for ignoring specific folder patterns.
+     * Hierarchical structure for ignoring specific directory patterns.
      * Keys represent path segments to match, values indicate what to ignore at that level.
      *
      * @example
@@ -98,9 +98,9 @@ export interface PathBasedConfigGeneratorOptions {
  * export default {
  *   onConfigGeneration: pathBasedConfigGenerator({
  *     includeFileName: false,
- *     removeBracketedFolders: true,
- *     ignoreFolders: ['lib', 'utils'],
- *     ignoreIncludesRootFolders: true, // Auto-ignores root folders from includes
+ *     removeBracketedDirectories: true,
+ *     ignoreDirectories: ['lib', 'utils'],
+ *     ignoreIncludesRootDirectories: true, // Auto-ignores root directories from includes
  *     lowercaseNamespace: true,
  *     fallbackNamespace: 'common'
  *   })

package/algorithms/index.cjs

@@ -22,9 +22,9 @@ const caseLib__namespace = /* @__PURE__ */ _interopNamespaceDefault(caseLib);
 function pathBasedConfigGenerator(options = {}) {
   const {
     includeFileName = false,
-    removeBracketedFolders = true,
-    ignoreFolders = [],
-    ignoreIncludesRootFolders = false,
+    removeBracketedDirectories = true,
+    ignoreDirectories = [],
+    ignoreIncludesRootDirectories = false,
     ignoreStructured = {},
     lowercaseNamespace = false,
     namespaceCase,
@@ -35,10 +35,10 @@ function pathBasedConfigGenerator(options = {}) {
   return async (event) => {
     const { relativePath, langTagConfig } = event;
     const actualFallbackNamespace = fallbackNamespace ?? langTagConfig.collect?.defaultNamespace;
-    let finalIgnoreFolders = [...ignoreFolders];
-    if (ignoreIncludesRootFolders && langTagConfig.includes) {
-      const extractedFolders = extractRootFoldersFromIncludes(langTagConfig.includes);
-      finalIgnoreFolders = [.../* @__PURE__ */ new Set([...finalIgnoreFolders, ...extractedFolders])];
+    let finalIgnoreDirectories = [...ignoreDirectories];
+    if (ignoreIncludesRootDirectories && langTagConfig.includes) {
+      const extractedDirectories = extractRootDirectoriesFromIncludes(langTagConfig.includes);
+      finalIgnoreDirectories = [.../* @__PURE__ */ new Set([...finalIgnoreDirectories, ...extractedDirectories])];
     }
     let pathSegments = relativePath.split(path.sep).filter(Boolean);
     if (pathSegments.length === 0) {
@@ -54,12 +54,12 @@ function pathBasedConfigGenerator(options = {}) {
     pathSegments = pathSegments.map((segment) => {
       const bracketMatch = segment.match(/^[\(\[](.+)[\)\]]$/);
       if (bracketMatch) {
-        return removeBracketedFolders ? null : bracketMatch[1];
+        return removeBracketedDirectories ? null : bracketMatch[1];
       }
       return segment;
     }).filter((seg) => seg !== null);
     pathSegments = applyStructuredIgnore(pathSegments, ignoreStructured);
-    pathSegments = pathSegments.filter((seg) => !finalIgnoreFolders.includes(seg));
+    pathSegments = pathSegments.filter((seg) => !finalIgnoreDirectories.includes(seg));
     let namespace;
     let path$1;
     if (pathSegments.length >= 1) {
@@ -139,8 +139,8 @@ function applyCaseTransform(str, caseType) {
   }
   return str;
 }
-function extractRootFoldersFromIncludes(includes) {
-  const folders = /* @__PURE__ */ new Set();
+function extractRootDirectoriesFromIncludes(includes) {
+  const directories = /* @__PURE__ */ new Set();
   for (const pattern of includes) {
     let cleanPattern = pattern.replace(/^\.\//, "");
     const match = cleanPattern.match(/^([^/]+)/);
@@ -148,12 +148,12 @@ function extractRootFoldersFromIncludes(includes) {
     const firstSegment = match[1];
     const groupMatch = firstSegment.match(/^[\(\[]([^\)\]]+)[\)\]]$/);
     if (groupMatch) {
-      const groupFolders = groupMatch[1].split("|").map((f) => f.trim());
-      groupFolders.forEach((folder) => folders.add(folder));
+      const groupDirectories = groupMatch[1].split("|").map((f) => f.trim());
+      groupDirectories.forEach((directory) => directories.add(directory));
     } else {
-      folders.add(firstSegment);
+      directories.add(firstSegment);
     }
   }
-  return Array.from(folders);
+  return Array.from(directories);
 }
 exports.pathBasedConfigGenerator = pathBasedConfigGenerator;

package/algorithms/index.js

@@ -3,9 +3,9 @@ import * as caseLib from "case";
 function pathBasedConfigGenerator(options = {}) {
   const {
     includeFileName = false,
-    removeBracketedFolders = true,
-    ignoreFolders = [],
-    ignoreIncludesRootFolders = false,
+    removeBracketedDirectories = true,
+    ignoreDirectories = [],
+    ignoreIncludesRootDirectories = false,
     ignoreStructured = {},
     lowercaseNamespace = false,
     namespaceCase,
@@ -16,10 +16,10 @@ function pathBasedConfigGenerator(options = {}) {
   return async (event) => {
     const { relativePath, langTagConfig } = event;
     const actualFallbackNamespace = fallbackNamespace ?? langTagConfig.collect?.defaultNamespace;
-    let finalIgnoreFolders = [...ignoreFolders];
-    if (ignoreIncludesRootFolders && langTagConfig.includes) {
-      const extractedFolders = extractRootFoldersFromIncludes(langTagConfig.includes);
-      finalIgnoreFolders = [.../* @__PURE__ */ new Set([...finalIgnoreFolders, ...extractedFolders])];
+    let finalIgnoreDirectories = [...ignoreDirectories];
+    if (ignoreIncludesRootDirectories && langTagConfig.includes) {
+      const extractedDirectories = extractRootDirectoriesFromIncludes(langTagConfig.includes);
+      finalIgnoreDirectories = [.../* @__PURE__ */ new Set([...finalIgnoreDirectories, ...extractedDirectories])];
     }
     let pathSegments = relativePath.split(sep).filter(Boolean);
     if (pathSegments.length === 0) {
@@ -35,12 +35,12 @@ function pathBasedConfigGenerator(options = {}) {
     pathSegments = pathSegments.map((segment) => {
       const bracketMatch = segment.match(/^[\(\[](.+)[\)\]]$/);
       if (bracketMatch) {
-        return removeBracketedFolders ? null : bracketMatch[1];
+        return removeBracketedDirectories ? null : bracketMatch[1];
       }
       return segment;
     }).filter((seg) => seg !== null);
     pathSegments = applyStructuredIgnore(pathSegments, ignoreStructured);
-    pathSegments = pathSegments.filter((seg) => !finalIgnoreFolders.includes(seg));
+    pathSegments = pathSegments.filter((seg) => !finalIgnoreDirectories.includes(seg));
     let namespace;
     let path;
     if (pathSegments.length >= 1) {
@@ -120,8 +120,8 @@ function applyCaseTransform(str, caseType) {
   }
   return str;
 }
-function extractRootFoldersFromIncludes(includes) {
-  const folders = /* @__PURE__ */ new Set();
+function extractRootDirectoriesFromIncludes(includes) {
+  const directories = /* @__PURE__ */ new Set();
   for (const pattern of includes) {
     let cleanPattern = pattern.replace(/^\.\//, "");
     const match = cleanPattern.match(/^([^/]+)/);
@@ -129,13 +129,13 @@ function extractRootFoldersFromIncludes(includes) {
     const firstSegment = match[1];
     const groupMatch = firstSegment.match(/^[\(\[]([^\)\]]+)[\)\]]$/);
     if (groupMatch) {
-      const groupFolders = groupMatch[1].split("|").map((f) => f.trim());
-      groupFolders.forEach((folder) => folders.add(folder));
+      const groupDirectories = groupMatch[1].split("|").map((f) => f.trim());
+      groupDirectories.forEach((directory) => directories.add(directory));
     } else {
-      folders.add(firstSegment);
+      directories.add(firstSegment);
     }
   }
-  return Array.from(folders);
+  return Array.from(directories);
 }
 export {
   pathBasedConfigGenerator

package/config.d.ts

@@ -99,9 +99,28 @@ export interface LangTagCLIConfig {
      * Allows dynamic modification of the tag's configuration (namespace, path, etc.)
      * based on the file path or other context.
      *
+     * **IMPORTANT:** The `event.config` object is deeply frozen and immutable. Any attempt
+     * to directly modify it will throw an error. To update the configuration, you must
+     * use `event.save(newConfig)` with a new configuration object.
+     *
      * Changes made inside this function are **applied only if you explicitly call**
      * `event.save(configuration)`. Returning a value or modifying the event object
      * without calling `save()` will **not** update the configuration.
+     *
+     * @example
+     * ```ts
+     * onConfigGeneration: async (event) => {
+     *   // ❌ This will throw an error:
+     *   // event.config.namespace = "new-namespace";
+     *
+     *   // ✅ Correct way to update:
+     *   event.save({
+     *     ...event.config,
+     *     namespace: "new-namespace",
+     *     path: "new.path"
+     *   });
+     * }
+     * ```
      */
     onConfigGeneration: (event: LangTagCLIConfigGenerationEvent) => Promise<void>;
     debug?: boolean;
@@ -163,14 +182,19 @@ export interface LangTagCLIConflict {
 }
 export interface LangTagCLIConfigGenerationEvent {
     /** The absolute path to the source file being processed. */
-    absolutePath: string;
+    readonly absolutePath: string;
     /** The path of the source file relative to the project root (where the command was invoked). */
-    relativePath: string;
+    readonly relativePath: string;
     /** True if the file being processed is located within the configured library import directory (`config.import.dir`). */
-    isImportedLibrary: boolean;
-    /** The configuration object extracted from the lang tag's options argument (e.g., `{ namespace: 'common', path: 'my.path' }`). */
-    config: LangTagTranslationsConfig | undefined;
-    langTagConfig: LangTagCLIConfig;
+    readonly isImportedLibrary: boolean;
+    /**
+     * The configuration object extracted from the lang tag's options argument (e.g., `{ namespace: 'common', path: 'my.path' }`).
+     *
+     * **This object is deeply frozen and immutable.** Any attempt to modify it will throw an error in strict mode.
+     * To update the configuration, use the `save()` method with a new configuration object.
+     */
+    readonly config: Readonly<LangTagTranslationsConfig> | undefined;
+    readonly langTagConfig: LangTagCLIConfig;
     /**
      * Tells CLI to replace tag configuration
      * undefined = means configuration will be removed

package/index.cjs

@@ -168,7 +168,7 @@ class $LT_TagProcessor {
   replaceTags(fileContent, replacements) {
     const replaceMap = /* @__PURE__ */ new Map();
     replacements.forEach((R) => {
-      if (!R.translations && !R.config) {
+      if (!R.translations && !R.config && R.config !== null) {
         throw new Error("Replacement data is required!");
       }
       const tag = R.tag;
@@ -182,7 +182,7 @@ class $LT_TagProcessor {
         throw new Error(`Tag translations are invalid object! Translations: ${newTranslationsString}`);
       }
       let newConfigString = R.config;
-      if (!newConfigString) newConfigString = tag.parameterConfig;
+      if (!newConfigString && newConfigString !== null) newConfigString = tag.parameterConfig;
       if (newConfigString) {
         try {
           if (typeof newConfigString === "string") JSON5.parse(newConfigString);
@@ -426,6 +426,16 @@ function $LT_FilterEmptyNamespaceTags(tags, logger) {
     return true;
   });
 }
+function deepFreezeObject(obj) {
+  const propNames = Object.getOwnPropertyNames(obj);
+  for (const name of propNames) {
+    const value = obj[name];
+    if (value && typeof value === "object") {
+      deepFreezeObject(value);
+    }
+  }
+  return Object.freeze(obj);
+}
 async function checkAndRegenerateFileLangTags(config, logger, file, path$12) {
   let libraryImportsDir = config.import.dir;
   if (!libraryImportsDir.endsWith(path.sep)) libraryImportsDir += path.sep;
@@ -440,14 +450,15 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path$12) {
   for (let tag of tags) {
     let newConfig = void 0;
     let shouldUpdate = false;
+    const frozenConfig = tag.parameterConfig ? deepFreezeObject(tag.parameterConfig) : tag.parameterConfig;
     await config.onConfigGeneration({
       langTagConfig: config,
-      config: tag.parameterConfig,
+      config: frozenConfig,
       absolutePath: file,
       relativePath: path$12,
       isImportedLibrary: path$12.startsWith(libraryImportsDir),
       save: (updatedConfig) => {
-        newConfig = updatedConfig;
+        newConfig = updatedConfig || null;
         shouldUpdate = true;
       }
     });
@@ -1422,12 +1433,12 @@ async function generateDefaultConfig() {
   return `${importStatement}
 
 const generationAlgorithm = pathBasedConfigGenerator({
-    ignoreIncludesRootFolders: true,
-    removeBracketedFolders: true,
+    ignoreIncludesRootDirectories: true,
+    removeBracketedDirectories: true,
     namespaceCase: 'kebab',
     pathCase: 'camel',
     clearOnDefaultNamespace: true,
-    ignoreFolders: ['core', 'utils', 'helpers']
+    ignoreDirectories: ['core', 'utils', 'helpers']
 });
 
 /** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */

package/index.js

@@ -148,7 +148,7 @@ class $LT_TagProcessor {
   replaceTags(fileContent, replacements) {
     const replaceMap = /* @__PURE__ */ new Map();
     replacements.forEach((R) => {
-      if (!R.translations && !R.config) {
+      if (!R.translations && !R.config && R.config !== null) {
         throw new Error("Replacement data is required!");
       }
       const tag = R.tag;
@@ -162,7 +162,7 @@ class $LT_TagProcessor {
         throw new Error(`Tag translations are invalid object! Translations: ${newTranslationsString}`);
       }
       let newConfigString = R.config;
-      if (!newConfigString) newConfigString = tag.parameterConfig;
+      if (!newConfigString && newConfigString !== null) newConfigString = tag.parameterConfig;
       if (newConfigString) {
         try {
           if (typeof newConfigString === "string") JSON5.parse(newConfigString);
@@ -406,6 +406,16 @@ function $LT_FilterEmptyNamespaceTags(tags, logger) {
     return true;
   });
 }
+function deepFreezeObject(obj) {
+  const propNames = Object.getOwnPropertyNames(obj);
+  for (const name of propNames) {
+    const value = obj[name];
+    if (value && typeof value === "object") {
+      deepFreezeObject(value);
+    }
+  }
+  return Object.freeze(obj);
+}
 async function checkAndRegenerateFileLangTags(config, logger, file, path2) {
   let libraryImportsDir = config.import.dir;
   if (!libraryImportsDir.endsWith(sep)) libraryImportsDir += sep;
@@ -420,14 +430,15 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path2) {
   for (let tag of tags) {
     let newConfig = void 0;
     let shouldUpdate = false;
+    const frozenConfig = tag.parameterConfig ? deepFreezeObject(tag.parameterConfig) : tag.parameterConfig;
     await config.onConfigGeneration({
       langTagConfig: config,
-      config: tag.parameterConfig,
+      config: frozenConfig,
       absolutePath: file,
       relativePath: path2,
       isImportedLibrary: path2.startsWith(libraryImportsDir),
       save: (updatedConfig) => {
-        newConfig = updatedConfig;
+        newConfig = updatedConfig || null;
         shouldUpdate = true;
       }
     });
@@ -1402,12 +1413,12 @@ async function generateDefaultConfig() {
   return `${importStatement}
 
 const generationAlgorithm = pathBasedConfigGenerator({
-    ignoreIncludesRootFolders: true,
-    removeBracketedFolders: true,
+    ignoreIncludesRootDirectories: true,
+    removeBracketedDirectories: true,
     namespaceCase: 'kebab',
     pathCase: 'camel',
     clearOnDefaultNamespace: true,
-    ignoreFolders: ['core', 'utils', 'helpers']
+    ignoreDirectories: ['core', 'utils', 'helpers']
 });
 
 /** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lang-tag/cli",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "type": "module",
   "publishConfig": {
     "access": "public"