@lang-tag/cli 0.10.1 → 0.11.1

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/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Predefined algorithms for onConfigGeneration hook.
+ *
+ * These algorithms customize how translation tag configurations are generated
+ * during collection and regeneration.
+ */
+export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions } from './path-based-config-generator.ts';

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

@@ -0,0 +1,110 @@
+import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+export interface PathBasedConfigGeneratorOptions {
+    /**
+     * Whether to include the filename (without extension) as part of the path segments.
+     * @default false
+     */
+    includeFileName?: boolean;
+    /**
+     * 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'
+     */
+    removeBracketedDirectories?: boolean;
+    /**
+     * List of directory names to completely ignore globally.
+     * These will be removed from all paths regardless of their position.
+     * @default []
+     *
+     * @example ['src', 'app', 'components']
+     */
+    ignoreDirectories?: string[];
+    /**
+     * When true, automatically extracts root directory names from the config.includes patterns
+     * and adds them to the ignoreDirectories list.
+     *
+     * @default false
+     *
+     * @example
+     * // With includes: ['src/**\/*.{js,ts,jsx,tsx}']
+     * // Automatically ignores: ['src']
+     *
+     * // With includes: ['(src|app)/**\/*.{js,ts,jsx,tsx}', 'components/**\/*.{jsx,tsx}']
+     * // Automatically ignores: ['src', 'app', 'components']
+     */
+    ignoreIncludesRootDirectories?: boolean;
+    /**
+     * Hierarchical structure for ignoring specific directory patterns.
+     * Keys represent path segments to match, values indicate what to ignore at that level.
+     *
+     * @example
+     * {
+     *   'src': {
+     *     'app': true,  // ignore 'app' when under 'src'
+     *     'features': ['auth', 'admin']  // ignore 'auth' and 'admin' under 'src/features'
+     *   }
+     * }
+     */
+    ignoreStructured?: Record<string, any>;
+    /**
+     * Convert the final namespace to lowercase.
+     * @default false
+     */
+    lowercaseNamespace?: boolean;
+    /**
+     * Case transformation to apply to the namespace.
+     * Available options: 'camel', 'capital', 'constant', 'dot', 'header', 'kebab',
+     * 'lower', 'no', 'param', 'pascal', 'path', 'sentence', 'snake', 'swap', 'title', 'upper'
+     * @default undefined (no transformation)
+     */
+    namespaceCase?: 'camel' | 'capital' | 'constant' | 'dot' | 'header' | 'kebab' | 'lower' | 'no' | 'param' | 'pascal' | 'path' | 'sentence' | 'snake' | 'swap' | 'title' | 'upper';
+    /**
+     * Case transformation to apply to the path segments.
+     * Available options: 'camel', 'capital', 'constant', 'dot', 'header', 'kebab',
+     * 'lower', 'no', 'param', 'pascal', 'path', 'sentence', 'snake', 'swap', 'title', 'upper'
+     * @default undefined (no transformation)
+     */
+    pathCase?: 'camel' | 'capital' | 'constant' | 'dot' | 'header' | 'kebab' | 'lower' | 'no' | 'param' | 'pascal' | 'path' | 'sentence' | 'snake' | 'swap' | 'title' | 'upper';
+    /**
+     * Fallback namespace to use when no segments remain after filtering.
+     * Defaults to the defaultNamespace from langTagConfig.collect.defaultNamespace if not provided.
+     * @default undefined
+     */
+    fallbackNamespace?: string;
+    /**
+     * When true and the generated namespace equals the fallback/default namespace,
+     * the namespace will be omitted from the configuration as it's redundant.
+     * @default true
+     */
+    clearOnDefaultNamespace?: boolean;
+}
+/**
+ * Automatically generates namespace and path configuration based on file path structure.
+ *
+ * This algorithm analyzes the relative file path and intelligently extracts namespace
+ * and path segments according to configurable rules.
+ *
+ * @param options - Configuration options for path-based generation
+ * @returns A function compatible with LangTagCLIConfig.onConfigGeneration
+ *
+ * @example
+ * ```typescript
+ * import { pathBasedConfigGenerator } from '@lang-tag/cli/algorithms';
+ *
+ * export default {
+ *   onConfigGeneration: pathBasedConfigGenerator({
+ *     includeFileName: false,
+ *     removeBracketedDirectories: true,
+ *     ignoreDirectories: ['lib', 'utils'],
+ *     ignoreIncludesRootDirectories: true, // Auto-ignores root directories from includes
+ *     lowercaseNamespace: true,
+ *     fallbackNamespace: 'common'
+ *   })
+ * };
+ * ```
+ */
+export declare function pathBasedConfigGenerator(options?: PathBasedConfigGeneratorOptions): (event: LangTagCLIConfigGenerationEvent) => Promise<void>;

package/algorithms/import/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Predefined algorithms for onImport hook.
+ *
+ * These algorithms customize how library translations are imported
+ * and organized in your project.
+ */
+export {};

package/algorithms/index.cjs

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const path = require("pathe");
+const caseLib = require("case");
+function _interopNamespaceDefault(e) {
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
+  if (e) {
+    for (const k in e) {
+      if (k !== "default") {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+const caseLib__namespace = /* @__PURE__ */ _interopNamespaceDefault(caseLib);
+function pathBasedConfigGenerator(options = {}) {
+  const {
+    includeFileName = false,
+    removeBracketedDirectories = true,
+    ignoreDirectories = [],
+    ignoreIncludesRootDirectories = false,
+    ignoreStructured = {},
+    lowercaseNamespace = false,
+    namespaceCase,
+    pathCase,
+    fallbackNamespace,
+    clearOnDefaultNamespace = true
+  } = options;
+  return async (event) => {
+    const { relativePath, langTagConfig } = event;
+    const actualFallbackNamespace = fallbackNamespace ?? langTagConfig.collect?.defaultNamespace;
+    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) {
+      return;
+    }
+    const fileName = pathSegments[pathSegments.length - 1];
+    const fileNameWithoutExt = fileName.replace(/\.[^.]+$/, "");
+    if (includeFileName) {
+      pathSegments[pathSegments.length - 1] = fileNameWithoutExt;
+    } else {
+      pathSegments = pathSegments.slice(0, -1);
+    }
+    pathSegments = pathSegments.map((segment) => {
+      const bracketMatch = segment.match(/^[\(\[](.+)[\)\]]$/);
+      if (bracketMatch) {
+        return removeBracketedDirectories ? null : bracketMatch[1];
+      }
+      return segment;
+    }).filter((seg) => seg !== null);
+    pathSegments = applyStructuredIgnore(pathSegments, ignoreStructured);
+    pathSegments = pathSegments.filter((seg) => !finalIgnoreDirectories.includes(seg));
+    let namespace;
+    let path$1;
+    if (pathSegments.length >= 1) {
+      namespace = pathSegments[0];
+      if (pathSegments.length > 1) {
+        path$1 = pathSegments.slice(1).join(".");
+      }
+    } else {
+      namespace = actualFallbackNamespace;
+    }
+    if (namespace) {
+      if (lowercaseNamespace) {
+        namespace = namespace.toLowerCase();
+      }
+      if (namespaceCase) {
+        namespace = applyCaseTransform(namespace, namespaceCase);
+      }
+    }
+    if (path$1 && pathCase) {
+      const pathParts = path$1.split(".");
+      const transformedParts = pathParts.map((part) => applyCaseTransform(part, pathCase));
+      path$1 = transformedParts.join(".");
+    }
+    const newConfig = {};
+    if (clearOnDefaultNamespace && namespace === actualFallbackNamespace) {
+      if (path$1) {
+        newConfig.path = path$1;
+      } else {
+        event.save(void 0);
+        return;
+      }
+    } else {
+      if (namespace) {
+        newConfig.namespace = namespace;
+      }
+      if (path$1) {
+        newConfig.path = path$1;
+      }
+    }
+    if (Object.keys(newConfig).length > 0) {
+      event.save(newConfig);
+    }
+  };
+}
+function applyStructuredIgnore(segments, structure) {
+  const result = [];
+  let currentStructure = structure;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment in currentStructure) {
+      const rule = currentStructure[segment];
+      if (rule === true) {
+        currentStructure = structure;
+        continue;
+      } else if (Array.isArray(rule)) {
+        result.push(segment);
+        if (i + 1 < segments.length && rule.includes(segments[i + 1])) {
+          i++;
+        }
+        currentStructure = structure;
+        continue;
+      } else if (typeof rule === "object" && rule !== null) {
+        result.push(segment);
+        currentStructure = rule;
+        continue;
+      }
+    }
+    result.push(segment);
+    currentStructure = structure;
+  }
+  return result;
+}
+function applyCaseTransform(str, caseType) {
+  const caseFunction = caseLib__namespace[caseType];
+  if (typeof caseFunction === "function") {
+    return caseFunction(str);
+  }
+  return str;
+}
+function extractRootDirectoriesFromIncludes(includes) {
+  const directories = /* @__PURE__ */ new Set();
+  for (const pattern of includes) {
+    let cleanPattern = pattern.replace(/^\.\//, "");
+    const match = cleanPattern.match(/^([^/]+)/);
+    if (!match) continue;
+    const firstSegment = match[1];
+    const groupMatch = firstSegment.match(/^[\(\[]([^\)\]]+)[\)\]]$/);
+    if (groupMatch) {
+      const groupDirectories = groupMatch[1].split("|").map((f) => f.trim());
+      groupDirectories.forEach((directory) => directories.add(directory));
+    } else {
+      directories.add(firstSegment);
+    }
+  }
+  return Array.from(directories);
+}
+exports.pathBasedConfigGenerator = pathBasedConfigGenerator;

package/algorithms/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Predefined algorithms for lang-tag-cli configuration.
+ *
+ * These algorithms can be used in your lang-tag-cli config file
+ * to customize how tags are processed during collection and regeneration.
+ */
+export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions } from './config-generation/index.ts';

package/algorithms/index.js

@@ -0,0 +1,142 @@
+import { sep } from "pathe";
+import * as caseLib from "case";
+function pathBasedConfigGenerator(options = {}) {
+  const {
+    includeFileName = false,
+    removeBracketedDirectories = true,
+    ignoreDirectories = [],
+    ignoreIncludesRootDirectories = false,
+    ignoreStructured = {},
+    lowercaseNamespace = false,
+    namespaceCase,
+    pathCase,
+    fallbackNamespace,
+    clearOnDefaultNamespace = true
+  } = options;
+  return async (event) => {
+    const { relativePath, langTagConfig } = event;
+    const actualFallbackNamespace = fallbackNamespace ?? langTagConfig.collect?.defaultNamespace;
+    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) {
+      return;
+    }
+    const fileName = pathSegments[pathSegments.length - 1];
+    const fileNameWithoutExt = fileName.replace(/\.[^.]+$/, "");
+    if (includeFileName) {
+      pathSegments[pathSegments.length - 1] = fileNameWithoutExt;
+    } else {
+      pathSegments = pathSegments.slice(0, -1);
+    }
+    pathSegments = pathSegments.map((segment) => {
+      const bracketMatch = segment.match(/^[\(\[](.+)[\)\]]$/);
+      if (bracketMatch) {
+        return removeBracketedDirectories ? null : bracketMatch[1];
+      }
+      return segment;
+    }).filter((seg) => seg !== null);
+    pathSegments = applyStructuredIgnore(pathSegments, ignoreStructured);
+    pathSegments = pathSegments.filter((seg) => !finalIgnoreDirectories.includes(seg));
+    let namespace;
+    let path;
+    if (pathSegments.length >= 1) {
+      namespace = pathSegments[0];
+      if (pathSegments.length > 1) {
+        path = pathSegments.slice(1).join(".");
+      }
+    } else {
+      namespace = actualFallbackNamespace;
+    }
+    if (namespace) {
+      if (lowercaseNamespace) {
+        namespace = namespace.toLowerCase();
+      }
+      if (namespaceCase) {
+        namespace = applyCaseTransform(namespace, namespaceCase);
+      }
+    }
+    if (path && pathCase) {
+      const pathParts = path.split(".");
+      const transformedParts = pathParts.map((part) => applyCaseTransform(part, pathCase));
+      path = transformedParts.join(".");
+    }
+    const newConfig = {};
+    if (clearOnDefaultNamespace && namespace === actualFallbackNamespace) {
+      if (path) {
+        newConfig.path = path;
+      } else {
+        event.save(void 0);
+        return;
+      }
+    } else {
+      if (namespace) {
+        newConfig.namespace = namespace;
+      }
+      if (path) {
+        newConfig.path = path;
+      }
+    }
+    if (Object.keys(newConfig).length > 0) {
+      event.save(newConfig);
+    }
+  };
+}
+function applyStructuredIgnore(segments, structure) {
+  const result = [];
+  let currentStructure = structure;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment in currentStructure) {
+      const rule = currentStructure[segment];
+      if (rule === true) {
+        currentStructure = structure;
+        continue;
+      } else if (Array.isArray(rule)) {
+        result.push(segment);
+        if (i + 1 < segments.length && rule.includes(segments[i + 1])) {
+          i++;
+        }
+        currentStructure = structure;
+        continue;
+      } else if (typeof rule === "object" && rule !== null) {
+        result.push(segment);
+        currentStructure = rule;
+        continue;
+      }
+    }
+    result.push(segment);
+    currentStructure = structure;
+  }
+  return result;
+}
+function applyCaseTransform(str, caseType) {
+  const caseFunction = caseLib[caseType];
+  if (typeof caseFunction === "function") {
+    return caseFunction(str);
+  }
+  return str;
+}
+function extractRootDirectoriesFromIncludes(includes) {
+  const directories = /* @__PURE__ */ new Set();
+  for (const pattern of includes) {
+    let cleanPattern = pattern.replace(/^\.\//, "");
+    const match = cleanPattern.match(/^([^/]+)/);
+    if (!match) continue;
+    const firstSegment = match[1];
+    const groupMatch = firstSegment.match(/^[\(\[]([^\)\]]+)[\)\]]$/);
+    if (groupMatch) {
+      const groupDirectories = groupMatch[1].split("|").map((f) => f.trim());
+      groupDirectories.forEach((directory) => directories.add(directory));
+    } else {
+      directories.add(firstSegment);
+    }
+  }
+  return Array.from(directories);
+}
+export {
+  pathBasedConfigGenerator
+};

package/config.d.ts

@@ -170,6 +170,7 @@ export interface LangTagCLIConfigGenerationEvent {
     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;
     /**
      * Tells CLI to replace tag configuration
      * undefined = means configuration will be removed

package/index.cjs

@@ -441,6 +441,7 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path$12) {
     let newConfig = void 0;
     let shouldUpdate = false;
     await config.onConfigGeneration({
+      langTagConfig: config,
       config: tag.parameterConfig,
       absolutePath: file,
       relativePath: path$12,
@@ -1414,13 +1415,22 @@ async function detectModuleSystem() {
     return "cjs";
   }
 }
-function getExportStatement(moduleSystem) {
-  return moduleSystem === "esm" ? "export default config;" : "module.exports = config;";
-}
 async function generateDefaultConfig() {
   const moduleSystem = await detectModuleSystem();
-  const exportStatement = getExportStatement(moduleSystem);
-  return `/** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */
+  const importStatement = moduleSystem === "esm" ? `import { pathBasedConfigGenerator } from '@lang-tag/cli/algorithms';` : `const { pathBasedConfigGenerator } = require('@lang-tag/cli/algorithms');`;
+  const exportStatement = moduleSystem === "esm" ? "export default config;" : "module.exports = config;";
+  return `${importStatement}
+
+const generationAlgorithm = pathBasedConfigGenerator({
+    ignoreIncludesRootDirectories: true,
+    removeBracketedDirectories: true,
+    namespaceCase: 'kebab',
+    pathCase: 'camel',
+    clearOnDefaultNamespace: true,
+    ignoreDirectories: ['core', 'utils', 'helpers']
+});
+
+/** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */
 const config = {
     tagName: 'lang',
     isLibrary: false,
@@ -1431,13 +1441,9 @@ const config = {
         // We do not modify imported configurations
         if (event.isImportedLibrary) return;
 
-        // const config = event.config || {};
-        //
-        // if (!config.path) {
-        //     config.path = 'test';
-        //     config.namespace = 'testNamespace';
-        //     event.save(config);
-        // }
+        if (event.config?.manual) return;
+        
+        await generationAlgorithm(event);
     },
     collect: {
         defaultNamespace: 'common',

package/index.js

@@ -421,6 +421,7 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path2) {
     let newConfig = void 0;
     let shouldUpdate = false;
     await config.onConfigGeneration({
+      langTagConfig: config,
       config: tag.parameterConfig,
       absolutePath: file,
       relativePath: path2,
@@ -1394,13 +1395,22 @@ async function detectModuleSystem() {
     return "cjs";
   }
 }
-function getExportStatement(moduleSystem) {
-  return moduleSystem === "esm" ? "export default config;" : "module.exports = config;";
-}
 async function generateDefaultConfig() {
   const moduleSystem = await detectModuleSystem();
-  const exportStatement = getExportStatement(moduleSystem);
-  return `/** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */
+  const importStatement = moduleSystem === "esm" ? `import { pathBasedConfigGenerator } from '@lang-tag/cli/algorithms';` : `const { pathBasedConfigGenerator } = require('@lang-tag/cli/algorithms');`;
+  const exportStatement = moduleSystem === "esm" ? "export default config;" : "module.exports = config;";
+  return `${importStatement}
+
+const generationAlgorithm = pathBasedConfigGenerator({
+    ignoreIncludesRootDirectories: true,
+    removeBracketedDirectories: true,
+    namespaceCase: 'kebab',
+    pathCase: 'camel',
+    clearOnDefaultNamespace: true,
+    ignoreDirectories: ['core', 'utils', 'helpers']
+});
+
+/** @type {import('@lang-tag/cli/config').LangTagCLIConfig} */
 const config = {
     tagName: 'lang',
     isLibrary: false,
@@ -1411,13 +1421,9 @@ const config = {
         // We do not modify imported configurations
         if (event.isImportedLibrary) return;
 
-        // const config = event.config || {};
-        //
-        // if (!config.path) {
-        //     config.path = 'test';
-        //     config.namespace = 'testNamespace';
-        //     event.save(config);
-        // }
+        if (event.config?.manual) return;
+        
+        await generationAlgorithm(event);
     },
     collect: {
         defaultNamespace: 'common',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lang-tag/cli",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -22,6 +22,11 @@
     ".": {
       "import": "./index.js",
       "require": "./index.cjs"
+    },
+    "./algorithms": {
+      "types": "./algorithms/index.d.ts",
+      "import": "./algorithms/index.js",
+      "require": "./algorithms/index.cjs"
     }
   },
   "peerDependencies": {
@@ -29,6 +34,7 @@
   },
   "dependencies": {
     "acorn": "^8.15.0",
+    "case": "^1.6.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "globby": "^14.1.0",