@lang-tag/cli 0.19.0 → 0.20.0

package/algorithms/index.cjs

@@ -214,7 +214,7 @@ function pathBasedConfigGenerator(options = {}) {
       );
       path$1 = transformedParts.join(".");
     }
-    const newConfig = event.config ? { ...event.config } : {};
+    const newConfig = event.getCurrentConfig();
     if (clearOnDefaultNamespace && namespace === actualFallbackNamespace) {
       if (path$1) {
         newConfig.path = path$1;
@@ -442,13 +442,10 @@ function configKeeper(options = {}) {
     if (keepMode !== "namespace" && keepMode !== "path" && keepMode !== "both") {
       return;
     }
-    let restoredConfig;
+    let restoredConfig = event.getCurrentConfig();
     if (event.savedConfig === null) {
-      restoredConfig = { ...event.config };
       delete restoredConfig.namespace;
       delete restoredConfig.path;
-    } else {
-      restoredConfig = { ...event.savedConfig };
     }
     let needsSave = false;
     const restorePropertyIfNeeded = (propertyKey) => {

package/algorithms/index.js

@@ -196,7 +196,7 @@ function pathBasedConfigGenerator(options = {}) {
       );
       path2 = transformedParts.join(".");
     }
-    const newConfig = event.config ? { ...event.config } : {};
+    const newConfig = event.getCurrentConfig();
     if (clearOnDefaultNamespace && namespace === actualFallbackNamespace) {
       if (path2) {
         newConfig.path = path2;
@@ -424,13 +424,10 @@ function configKeeper(options = {}) {
     if (keepMode !== "namespace" && keepMode !== "path" && keepMode !== "both") {
       return;
     }
-    let restoredConfig;
+    let restoredConfig = event.getCurrentConfig();
     if (event.savedConfig === null) {
-      restoredConfig = { ...event.config };
       delete restoredConfig.namespace;
       delete restoredConfig.path;
-    } else {
-      restoredConfig = { ...event.savedConfig };
     }
     let needsSave = false;
     const restorePropertyIfNeeded = (propertyKey) => {

package/index.cjs

@@ -8,12 +8,13 @@ const globby = require("globby");
 const path = require("path");
 const JSON5 = require("json5");
 const promises = require("fs/promises");
-const path$1 = require("pathe");
 const url = require("url");
+const path$1 = require("pathe");
 require("case");
 const namespaceCollector = require("./chunks/namespace-collector.cjs");
 const micromatch = require("micromatch");
 const acorn = require("acorn");
+const tsMorph = require("ts-morph");
 const mustache = require("mustache");
 const checkbox = require("@inquirer/checkbox");
 const confirm = require("@inquirer/confirm");
@@ -564,7 +565,9 @@ async function $LT_CollectCandidateFilesWithTags(props) {
         langTagConfig: config
       });
     }
-    tags = $LT_FilterEmptyNamespaceTags(tags, logger);
+    if (!props.skipEmptyNamespaceCheck) {
+      tags = $LT_FilterEmptyNamespaceTags(tags, logger);
+    }
     const relativeFilePath = path.relative(cwd, filePath);
     candidates.push({ relativeFilePath, tags });
   }
@@ -905,9 +908,30 @@ async function $LT_WriteToCollections({
   }
   await config.collect.collector.postWrite(changedCollections);
 }
+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);
+}
+function formatFileUrlForDisplay(filePath) {
+  return url.pathToFileURL(filePath).href.replace(/\[/g, "%5B").replace(/\]/g, "%5D").replace(/\(/g, "%28").replace(/\)/g, "%29");
+}
+function formatExecutionTime(milliseconds) {
+  if (milliseconds >= 1e3) {
+    const seconds = milliseconds / 1e3;
+    return `${seconds.toFixed(1)}s`;
+  }
+  return `${Math.round(milliseconds)}ms`;
+}
 const LANG_TAG_DEFAULT_CONFIG = {
   tagName: "lang",
   isLibrary: false,
+  enforceLibraryTagPrefix: true,
   includes: ["src/**/*.{js,ts,jsx,tsx}"],
   excludes: ["node_modules", "dist", "build"],
   localesDirectory: "locales",
@@ -968,6 +992,7 @@ This will enable import of language tags from external packages.
     }
   },
   translationArgPosition: 1,
+  hideDistDir: "dist",
   onConfigGeneration: async (event) => {
     event.logger.info(
       "Config generation event is not configured. Add onConfigGeneration handler to customize config generation."
@@ -1006,6 +1031,9 @@ async function $LT_ReadConfig(projectPath) {
     if (!config.collect.collector) {
       throw new Error("Collector not found! (config.collect.collector)");
     }
+    if (config.isLibrary && (config.enforceLibraryTagPrefix ?? true) && config.tagName && !config.tagName.startsWith("_")) {
+      config.tagName = `_${config.tagName}`;
+    }
     return config;
   } catch (error) {
     throw error;
@@ -1350,9 +1378,9 @@ async function logTagConflictInfo(tagInfo, prefix, conflictPath, translationArgP
         console.error("Failed to colorize config:", error);
       }
     }
-    const encodedPath = encodeURI(filePath);
+    const fileUrl = formatFileUrlForDisplay(filePath);
     console.log(
-      `${ANSI.gray}${prefix}${ANSI.reset} ${ANSI.cyan}file://${encodedPath}${ANSI.reset}${ANSI.gray}:${lineNum}${ANSI.reset}`
+      `${ANSI.gray}${prefix}${ANSI.reset} ${ANSI.cyan}${fileUrl}${ANSI.reset}${ANSI.gray}:${lineNum}${ANSI.reset}`
     );
     printLines(colorizedWhole.split("\n"), startLine, errorLines, condense);
   } catch (error) {
@@ -1482,9 +1510,14 @@ async function $LT_GetCommandEssentials() {
   };
 }
 async function $LT_CMD_Collect(options) {
+  const startTime = Date.now();
   const { config, logger } = await $LT_GetCommandEssentials();
   logger.info("Collecting translations from source files...");
-  const files = await $LT_CollectCandidateFilesWithTags({ config, logger });
+  const files = await $LT_CollectCandidateFilesWithTags({
+    config,
+    logger,
+    skipEmptyNamespaceCheck: config.isLibrary
+  });
   if (config.debug) {
     for (let file of files) {
       logger.debug("Found {count} translations tags inside: {file}", {
@@ -1493,8 +1526,19 @@ async function $LT_CMD_Collect(options) {
       });
     }
   }
+  const totalTags = files.reduce((sum, file) => sum + file.tags.length, 0);
   if (config.isLibrary) {
+    if (totalTags === 0 && (config.enforceLibraryTagPrefix ?? true) && config.tagName) {
+      const baseTagName = config.tagName.startsWith("_") ? config.tagName.substring(1) : config.tagName;
+      console.log("");
+      logger.warn(
+        '⚠️  No translation tags found in your library code.\n	This might be because enforceLibraryTagPrefix is enabled.\n	Remember: your tag function must be named {prefixedBaseTagName} (with "_" prefix), not {baseTagName}.\n	Example: export function {prefixedBaseTagName}(...) instead of export function {baseTagName}(...)\n	The prefix prevents the tag from appearing in TypeScript autocomplete after compilation.',
+        { prefixedBaseTagName: `_${baseTagName}`, baseTagName }
+      );
+    }
     await $LT_WriteAsExportFile({ config, logger, files });
+    const executionTime = formatExecutionTime(Date.now() - startTime);
+    logger.debug("Collection completed ({time})", { time: executionTime });
     return;
   }
   try {
@@ -1503,10 +1547,6 @@ async function $LT_CMD_Collect(options) {
       files,
       config
     });
-    const totalTags = files.reduce(
-      (sum, file) => sum + file.tags.length,
-      0
-    );
     logger.debug("Found {totalTags} translation tags", { totalTags });
     await $LT_WriteToCollections({
       config,
@@ -1514,15 +1554,252 @@ async function $LT_CMD_Collect(options) {
       logger,
       clean: options?.clean
     });
+    const executionTime = formatExecutionTime(Date.now() - startTime);
+    logger.debug("Collection completed ({time})", { time: executionTime });
   } catch (e) {
     const prefix = "LangTagConflictResolution:";
     if (e.message.startsWith(prefix)) {
       logger.error(e.message.substring(prefix.length));
+      const executionTime = formatExecutionTime(Date.now() - startTime);
+      logger.debug("Collection completed ({time})", {
+        time: executionTime
+      });
       return;
     }
     throw e;
   }
 }
+function $LT_HideExportsInDtsFile(dtsFilePath, variableNames) {
+  const originalContent = fs.readFileSync(dtsFilePath, "utf-8");
+  const project = new tsMorph.Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+    skipLoadingLibFiles: true
+  });
+  const sourceFile = project.addSourceFileAtPath(dtsFilePath);
+  let hasChanges = false;
+  const exportsToHide = [];
+  const processedStatements = /* @__PURE__ */ new Set();
+  for (const declaration of sourceFile.getVariableDeclarations()) {
+    const name = declaration.getName();
+    if (variableNames.has(name)) {
+      const parent = declaration.getParent();
+      if (parent && parent.getKindName() === "VariableDeclarationList") {
+        const varList = parent;
+        const grandParent = varList.getParent();
+        if (grandParent && grandParent.getKindName() === "VariableStatement") {
+          const varStatement = grandParent;
+          if (varStatement.hasExportKeyword()) {
+            if (!processedStatements.has(varStatement)) {
+              processedStatements.add(varStatement);
+              exportsToHide.push(name);
+              varStatement.toggleModifier("export", false);
+              hasChanges = true;
+            }
+          }
+        }
+      }
+    }
+  }
+  if (!hasChanges) {
+    return {
+      hiddenCount: 0,
+      modifiedContent: originalContent,
+      originalContent
+    };
+  }
+  const modifiedContent = sourceFile.getFullText();
+  return {
+    hiddenCount: exportsToHide.length,
+    modifiedContent,
+    originalContent
+  };
+}
+function extractPrefixesFromIncludes(includes) {
+  const prefixes = /* @__PURE__ */ new Set();
+  for (const pattern of includes) {
+    const groupMatch = pattern.match(/^\(([^)]+)\)\/\*\*/);
+    if (groupMatch) {
+      const options = groupMatch[1].split("|").map((s) => s.trim());
+      options.forEach((opt) => prefixes.add(opt));
+      continue;
+    }
+    const simpleMatch = pattern.match(/^([^/]+)\/\*\*/);
+    if (simpleMatch) {
+      prefixes.add(simpleMatch[1]);
+      continue;
+    }
+    const singleMatch = pattern.match(/^([^/]+)\//);
+    if (singleMatch) {
+      prefixes.add(singleMatch[1]);
+    }
+  }
+  return Array.from(prefixes);
+}
+function findMatchingDtsFile(sourceFilePath, sourceRelativePath, dtsFileMap, config) {
+  const sourceBaseName = path.basename(
+    sourceFilePath,
+    path.extname(sourceFilePath)
+  );
+  const relativePathKey = sourceRelativePath.replace(
+    /\.(ts|tsx|js|jsx)$/,
+    ""
+  );
+  let dtsFilePath = dtsFileMap.get(relativePathKey);
+  if (dtsFilePath) {
+    return { dtsFilePath, strategy: "relative-path" };
+  }
+  if (config?.includes) {
+    const prefixes = extractPrefixesFromIncludes(config.includes);
+    for (const prefix of prefixes) {
+      const prefixPattern = new RegExp(
+        `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`
+      );
+      if (prefixPattern.test(sourceRelativePath)) {
+        const strippedPath = sourceRelativePath.replace(
+          prefixPattern,
+          ""
+        );
+        const strippedPathKey = strippedPath.replace(
+          /\.(ts|tsx|js|jsx)$/,
+          ""
+        );
+        dtsFilePath = dtsFileMap.get(strippedPathKey);
+        if (dtsFilePath) {
+          return {
+            dtsFilePath,
+            strategy: "includes-prefix-stripped"
+          };
+        }
+      }
+    }
+  }
+  dtsFilePath = dtsFileMap.get(sourceBaseName);
+  if (dtsFilePath) {
+    return { dtsFilePath, strategy: "base-name" };
+  }
+  return { dtsFilePath: null, strategy: null };
+}
+async function $LT_MatchSourceToDtsFiles(files, distPath, cwd, config) {
+  const sourceFileToVariables = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const sourceFilePath = path.resolve(cwd, file.relativeFilePath);
+    const variableNames = /* @__PURE__ */ new Set();
+    for (const tag of file.tags) {
+      if (tag.variableName) {
+        variableNames.add(tag.variableName);
+      }
+    }
+    if (variableNames.size > 0) {
+      sourceFileToVariables.set(sourceFilePath, variableNames);
+    }
+  }
+  if (sourceFileToVariables.size === 0) {
+    return [];
+  }
+  const dtsFiles = await globby.globby("**/*.d.ts", {
+    cwd: distPath,
+    absolute: true
+  });
+  if (dtsFiles.length === 0) {
+    return [];
+  }
+  const dtsFileMap = /* @__PURE__ */ new Map();
+  for (const dtsFile of dtsFiles) {
+    const relativeDtsPath = path.relative(distPath, dtsFile);
+    const baseName = path.basename(dtsFile, ".d.ts");
+    const relativePathWithoutExt = relativeDtsPath.replace(/\.d\.ts$/, "");
+    dtsFileMap.set(relativePathWithoutExt, dtsFile);
+    dtsFileMap.set(baseName, dtsFile);
+  }
+  const matches = [];
+  const processedDtsFiles = /* @__PURE__ */ new Set();
+  for (const [sourceFilePath, variableNames] of sourceFileToVariables) {
+    const sourceRelativePath = path.relative(cwd, sourceFilePath);
+    const match = findMatchingDtsFile(
+      sourceFilePath,
+      sourceRelativePath,
+      dtsFileMap,
+      config
+    );
+    if (!match.dtsFilePath) {
+      continue;
+    }
+    if (processedDtsFiles.has(match.dtsFilePath)) {
+      continue;
+    }
+    processedDtsFiles.add(match.dtsFilePath);
+    matches.push({
+      sourceFilePath,
+      sourceRelativePath,
+      dtsFilePath: match.dtsFilePath,
+      variableNames
+    });
+  }
+  return matches;
+}
+async function $LT_CMD_HideCompiledExports(options) {
+  const { config, logger } = await $LT_GetCommandEssentials();
+  const distDir = options?.distDir || config.hideDistDir || "dist";
+  const distPath = path.resolve(process$1.cwd(), distDir);
+  if (!fs.existsSync(distPath)) {
+    logger.warn("Dist directory does not exist: {distPath}", { distPath });
+    return;
+  }
+  logger.info("Scanning source files for lang-tag variables...");
+  const files = await $LT_CollectCandidateFilesWithTags({
+    config,
+    logger,
+    skipEmptyNamespaceCheck: true
+  });
+  const matches = await $LT_MatchSourceToDtsFiles(
+    files,
+    distPath,
+    process$1.cwd(),
+    config
+  );
+  if (matches.length === 0) {
+    logger.info(
+      "No lang-tag variables found in source files or no matching .d.ts files found."
+    );
+    return;
+  }
+  logger.info("Found {count} .d.ts files to process", {
+    count: matches.length
+  });
+  let hiddenCount = 0;
+  for (const match of matches) {
+    try {
+      const result = $LT_HideExportsInDtsFile(
+        match.dtsFilePath,
+        match.variableNames
+      );
+      if (!result.hiddenCount) {
+        continue;
+      }
+      fs.writeFileSync(match.dtsFilePath, result.modifiedContent, "utf-8");
+      hiddenCount += result.hiddenCount;
+      const hiddenVariables = Array.from(match.variableNames).join(", ");
+      logger.debug(
+        "Hidden exports from {file}: {variables} (from {sourceFile})",
+        {
+          file: path.relative(process$1.cwd(), match.dtsFilePath),
+          variables: hiddenVariables,
+          sourceFile: match.sourceRelativePath
+        }
+      );
+    } catch (error) {
+      logger.warn("Error processing file {file}: {error}", {
+        file: match.sourceRelativePath,
+        error: error.message || String(error)
+      });
+    }
+  }
+  logger.success("Hidden {hiddenCount} exports from {fileCount} files.", {
+    hiddenCount,
+    fileCount: matches.length
+  });
+}
 async function $LT_CollectExportFiles(logger) {
   const nodeModulesPath = path$1.join(process$1.cwd(), "node_modules");
   if (!fs.existsSync(nodeModulesPath)) {
@@ -1641,11 +1918,11 @@ async function generateImportFiles(config, logger, importManager) {
     const content = renderTemplate$2(templateData);
     await $LT_EnsureDirectoryExists(path.dirname(filePath));
     await promises.writeFile(filePath, content, "utf-8");
-    const encodedFilePath = encodeURI(filePath);
+    const fileUrl = formatFileUrlForDisplay(filePath);
     logger.success('Created tag file: "{file}"', {
       file: importedFile.pathRelativeToImportDir
     });
-    logger.debug(" └── link: file://{path}", { path: encodedFilePath });
+    logger.debug(" └── link: {url}", { url: fileUrl });
   }
 }
 class ImportManager {
@@ -2144,7 +2421,10 @@ async function detectInitTagOptions(options, config) {
   const isTypeScript = options.typescript !== void 0 ? options.typescript : detectTypeScript(packageJson);
   const isReact = options.react !== void 0 ? options.react : detectReact(packageJson);
   const isLibrary = options.library !== void 0 ? options.library : config.isLibrary;
-  const tagName = options.name || config.tagName || "lang";
+  let tagName = options.name || config.tagName || "lang";
+  if (isLibrary && (config.enforceLibraryTagPrefix ?? true) && !tagName.startsWith("_")) {
+    tagName = `_${tagName}`;
+  }
   const fileExtension = isLibrary && isReact ? isTypeScript ? "tsx" : "jsx" : isTypeScript ? "ts" : "js";
   return {
     tagName,
@@ -2245,22 +2525,22 @@ async function $LT_CMD_InitTagFile(options = {}) {
       "2. Create your translation objects and use the tag function"
     );
     logger.info('3. Run "lang-tag collect" to extract translations');
+    if (renderOptions.isLibrary && renderOptions.tagName.startsWith("_") && (config.enforceLibraryTagPrefix ?? true)) {
+      console.log("");
+      logger.info(
+        '📌 Important: Library tag prefix enforcement is enabled\n	Your tag uses "_" prefix: {tagName} (instead of {baseTagName})\n	This prevents the tag from appearing in TypeScript autocomplete after compilation\n	Always use {tagName} (with prefix) in your library code\n	This is a best practice for library internals - it keeps your API clean\n	The prefix is automatically added by the enforceLibraryTagPrefix option\n	To disable this behavior, set enforceLibraryTagPrefix: false in your config',
+        {
+          tagName: renderOptions.tagName,
+          baseTagName: renderOptions.tagName.substring(1)
+        }
+      );
+    }
   } catch (error) {
     logger.error("Failed to write file: {error}", {
       error: error?.message
     });
   }
 }
-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;
@@ -2294,13 +2574,23 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path$12) {
         event.isSaved = true;
         event.savedConfig = updatedConfig;
         logger.debug(
-          'Called save for "{path}" with config "{config}" triggered by: ("{trigger}")',
+          'Called save for "{path}"{varName} with config "{config}" triggered by: ("{trigger}")',
           {
             path: path$12,
             config: JSON.stringify(updatedConfig),
-            trigger: triggerName || "-"
+            trigger: triggerName || "-",
+            varName: tag.variableName ? `(${tag.variableName})` : ""
           }
         );
+      },
+      getCurrentConfig: () => {
+        if (event.savedConfig !== void 0 && event.savedConfig !== null) {
+          return { ...event.savedConfig };
+        }
+        if (event.config) {
+          return { ...event.config };
+        }
+        return {};
       }
     };
     await config.onConfigGeneration(event);
@@ -2315,10 +2605,10 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path$12) {
   if (replacements.length) {
     const newContent = processor.replaceTags(fileContent, replacements);
     await promises.writeFile(file, newContent, "utf-8");
-    const encodedFile = encodeURI(file);
+    const fileUrl = formatFileUrlForDisplay(file);
     logger.info(
-      'Lang tag configurations written for file "{path}" (file://{file}:{line})',
-      { path: path$12, file: encodedFile, line: lastUpdatedLine }
+      'Lang tag configurations written for file "{path}" ({url}:{line})',
+      { path: path$12, url: fileUrl, line: lastUpdatedLine }
     );
     return true;
   }
@@ -2331,6 +2621,7 @@ function isConfigSame(c1, c2) {
   return false;
 }
 async function $LT_CMD_RegenerateTags() {
+  const startTime = Date.now();
   const { config, logger } = await $LT_GetCommandEssentials();
   const files = await globby.globby(config.includes, {
     cwd: process.cwd(),
@@ -2351,11 +2642,13 @@ async function $LT_CMD_RegenerateTags() {
       dirty = true;
     }
   }
+  const executionTime = formatExecutionTime(Date.now() - startTime);
   if (!dirty) {
     logger.info(
       "No changes were made based on the current configuration and files"
     );
   }
+  logger.debug("Regeneration completed ({time})", { time: executionTime });
 }
 function getBasePath(pattern) {
   const globStartIndex = pattern.indexOf("*");
@@ -2464,6 +2757,14 @@ function createCli() {
   ).action(async (options) => {
     await $LT_CMD_InitTagFile(options);
   });
+  commander.program.command("hide-compiled-exports").alias("hce").description(
+    "Hide compiled .d.ts exports of lang-tag variables (remove export modifier, keep type)"
+  ).option(
+    "-d, --dist-dir <dir>",
+    'Dist directory to process (default: from config or "dist")'
+  ).action(async (options) => {
+    await $LT_CMD_HideCompiledExports({ distDir: options.distDir });
+  });
   return commander.program;
 }
 createCli().parse();

package/index.js

@@ -2,18 +2,19 @@
 import { program } from "commander";
 import * as process$1 from "node:process";
 import process__default from "node:process";
-import fs, { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import fs, { readFileSync, existsSync, writeFileSync, readdirSync, statSync } from "fs";
 import { globby } from "globby";
 import * as path from "path";
 import path__default, { dirname, resolve, join, sep } from "path";
 import JSON5 from "json5";
 import { mkdir, writeFile, readFile } from "fs/promises";
-import path$1, { resolve as resolve$1 } from "pathe";
 import { pathToFileURL, fileURLToPath } from "url";
+import path$1, { resolve as resolve$1 } from "pathe";
 import "case";
 import { N as NamespaceCollector } from "./chunks/namespace-collector.js";
 import micromatch from "micromatch";
 import * as acorn from "acorn";
+import { Project } from "ts-morph";
 import mustache from "mustache";
 import checkbox from "@inquirer/checkbox";
 import confirm from "@inquirer/confirm";
@@ -544,7 +545,9 @@ async function $LT_CollectCandidateFilesWithTags(props) {
         langTagConfig: config
       });
     }
-    tags = $LT_FilterEmptyNamespaceTags(tags, logger);
+    if (!props.skipEmptyNamespaceCheck) {
+      tags = $LT_FilterEmptyNamespaceTags(tags, logger);
+    }
     const relativeFilePath = path__default.relative(cwd, filePath);
     candidates.push({ relativeFilePath, tags });
   }
@@ -885,9 +888,30 @@ async function $LT_WriteToCollections({
   }
   await config.collect.collector.postWrite(changedCollections);
 }
+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);
+}
+function formatFileUrlForDisplay(filePath) {
+  return pathToFileURL(filePath).href.replace(/\[/g, "%5B").replace(/\]/g, "%5D").replace(/\(/g, "%28").replace(/\)/g, "%29");
+}
+function formatExecutionTime(milliseconds) {
+  if (milliseconds >= 1e3) {
+    const seconds = milliseconds / 1e3;
+    return `${seconds.toFixed(1)}s`;
+  }
+  return `${Math.round(milliseconds)}ms`;
+}
 const LANG_TAG_DEFAULT_CONFIG = {
   tagName: "lang",
   isLibrary: false,
+  enforceLibraryTagPrefix: true,
   includes: ["src/**/*.{js,ts,jsx,tsx}"],
   excludes: ["node_modules", "dist", "build"],
   localesDirectory: "locales",
@@ -948,6 +972,7 @@ This will enable import of language tags from external packages.
     }
   },
   translationArgPosition: 1,
+  hideDistDir: "dist",
   onConfigGeneration: async (event) => {
     event.logger.info(
       "Config generation event is not configured. Add onConfigGeneration handler to customize config generation."
@@ -986,6 +1011,9 @@ async function $LT_ReadConfig(projectPath) {
     if (!config.collect.collector) {
       throw new Error("Collector not found! (config.collect.collector)");
     }
+    if (config.isLibrary && (config.enforceLibraryTagPrefix ?? true) && config.tagName && !config.tagName.startsWith("_")) {
+      config.tagName = `_${config.tagName}`;
+    }
     return config;
   } catch (error) {
     throw error;
@@ -1330,9 +1358,9 @@ async function logTagConflictInfo(tagInfo, prefix, conflictPath, translationArgP
         console.error("Failed to colorize config:", error);
       }
     }
-    const encodedPath = encodeURI(filePath);
+    const fileUrl = formatFileUrlForDisplay(filePath);
     console.log(
-      `${ANSI.gray}${prefix}${ANSI.reset} ${ANSI.cyan}file://${encodedPath}${ANSI.reset}${ANSI.gray}:${lineNum}${ANSI.reset}`
+      `${ANSI.gray}${prefix}${ANSI.reset} ${ANSI.cyan}${fileUrl}${ANSI.reset}${ANSI.gray}:${lineNum}${ANSI.reset}`
     );
     printLines(colorizedWhole.split("\n"), startLine, errorLines, condense);
   } catch (error) {
@@ -1462,9 +1490,14 @@ async function $LT_GetCommandEssentials() {
   };
 }
 async function $LT_CMD_Collect(options) {
+  const startTime = Date.now();
   const { config, logger } = await $LT_GetCommandEssentials();
   logger.info("Collecting translations from source files...");
-  const files = await $LT_CollectCandidateFilesWithTags({ config, logger });
+  const files = await $LT_CollectCandidateFilesWithTags({
+    config,
+    logger,
+    skipEmptyNamespaceCheck: config.isLibrary
+  });
   if (config.debug) {
     for (let file of files) {
       logger.debug("Found {count} translations tags inside: {file}", {
@@ -1473,8 +1506,19 @@ async function $LT_CMD_Collect(options) {
       });
     }
   }
+  const totalTags = files.reduce((sum, file) => sum + file.tags.length, 0);
   if (config.isLibrary) {
+    if (totalTags === 0 && (config.enforceLibraryTagPrefix ?? true) && config.tagName) {
+      const baseTagName = config.tagName.startsWith("_") ? config.tagName.substring(1) : config.tagName;
+      console.log("");
+      logger.warn(
+        '⚠️  No translation tags found in your library code.\n	This might be because enforceLibraryTagPrefix is enabled.\n	Remember: your tag function must be named {prefixedBaseTagName} (with "_" prefix), not {baseTagName}.\n	Example: export function {prefixedBaseTagName}(...) instead of export function {baseTagName}(...)\n	The prefix prevents the tag from appearing in TypeScript autocomplete after compilation.',
+        { prefixedBaseTagName: `_${baseTagName}`, baseTagName }
+      );
+    }
     await $LT_WriteAsExportFile({ config, logger, files });
+    const executionTime = formatExecutionTime(Date.now() - startTime);
+    logger.debug("Collection completed ({time})", { time: executionTime });
     return;
   }
   try {
@@ -1483,10 +1527,6 @@ async function $LT_CMD_Collect(options) {
       files,
       config
     });
-    const totalTags = files.reduce(
-      (sum, file) => sum + file.tags.length,
-      0
-    );
     logger.debug("Found {totalTags} translation tags", { totalTags });
     await $LT_WriteToCollections({
       config,
@@ -1494,15 +1534,252 @@ async function $LT_CMD_Collect(options) {
       logger,
       clean: options?.clean
     });
+    const executionTime = formatExecutionTime(Date.now() - startTime);
+    logger.debug("Collection completed ({time})", { time: executionTime });
   } catch (e) {
     const prefix = "LangTagConflictResolution:";
     if (e.message.startsWith(prefix)) {
       logger.error(e.message.substring(prefix.length));
+      const executionTime = formatExecutionTime(Date.now() - startTime);
+      logger.debug("Collection completed ({time})", {
+        time: executionTime
+      });
       return;
     }
     throw e;
   }
 }
+function $LT_HideExportsInDtsFile(dtsFilePath, variableNames) {
+  const originalContent = readFileSync(dtsFilePath, "utf-8");
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+    skipLoadingLibFiles: true
+  });
+  const sourceFile = project.addSourceFileAtPath(dtsFilePath);
+  let hasChanges = false;
+  const exportsToHide = [];
+  const processedStatements = /* @__PURE__ */ new Set();
+  for (const declaration of sourceFile.getVariableDeclarations()) {
+    const name = declaration.getName();
+    if (variableNames.has(name)) {
+      const parent = declaration.getParent();
+      if (parent && parent.getKindName() === "VariableDeclarationList") {
+        const varList = parent;
+        const grandParent = varList.getParent();
+        if (grandParent && grandParent.getKindName() === "VariableStatement") {
+          const varStatement = grandParent;
+          if (varStatement.hasExportKeyword()) {
+            if (!processedStatements.has(varStatement)) {
+              processedStatements.add(varStatement);
+              exportsToHide.push(name);
+              varStatement.toggleModifier("export", false);
+              hasChanges = true;
+            }
+          }
+        }
+      }
+    }
+  }
+  if (!hasChanges) {
+    return {
+      hiddenCount: 0,
+      modifiedContent: originalContent,
+      originalContent
+    };
+  }
+  const modifiedContent = sourceFile.getFullText();
+  return {
+    hiddenCount: exportsToHide.length,
+    modifiedContent,
+    originalContent
+  };
+}
+function extractPrefixesFromIncludes(includes) {
+  const prefixes = /* @__PURE__ */ new Set();
+  for (const pattern of includes) {
+    const groupMatch = pattern.match(/^\(([^)]+)\)\/\*\*/);
+    if (groupMatch) {
+      const options = groupMatch[1].split("|").map((s) => s.trim());
+      options.forEach((opt) => prefixes.add(opt));
+      continue;
+    }
+    const simpleMatch = pattern.match(/^([^/]+)\/\*\*/);
+    if (simpleMatch) {
+      prefixes.add(simpleMatch[1]);
+      continue;
+    }
+    const singleMatch = pattern.match(/^([^/]+)\//);
+    if (singleMatch) {
+      prefixes.add(singleMatch[1]);
+    }
+  }
+  return Array.from(prefixes);
+}
+function findMatchingDtsFile(sourceFilePath, sourceRelativePath, dtsFileMap, config) {
+  const sourceBaseName = path__default.basename(
+    sourceFilePath,
+    path__default.extname(sourceFilePath)
+  );
+  const relativePathKey = sourceRelativePath.replace(
+    /\.(ts|tsx|js|jsx)$/,
+    ""
+  );
+  let dtsFilePath = dtsFileMap.get(relativePathKey);
+  if (dtsFilePath) {
+    return { dtsFilePath, strategy: "relative-path" };
+  }
+  if (config?.includes) {
+    const prefixes = extractPrefixesFromIncludes(config.includes);
+    for (const prefix of prefixes) {
+      const prefixPattern = new RegExp(
+        `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`
+      );
+      if (prefixPattern.test(sourceRelativePath)) {
+        const strippedPath = sourceRelativePath.replace(
+          prefixPattern,
+          ""
+        );
+        const strippedPathKey = strippedPath.replace(
+          /\.(ts|tsx|js|jsx)$/,
+          ""
+        );
+        dtsFilePath = dtsFileMap.get(strippedPathKey);
+        if (dtsFilePath) {
+          return {
+            dtsFilePath,
+            strategy: "includes-prefix-stripped"
+          };
+        }
+      }
+    }
+  }
+  dtsFilePath = dtsFileMap.get(sourceBaseName);
+  if (dtsFilePath) {
+    return { dtsFilePath, strategy: "base-name" };
+  }
+  return { dtsFilePath: null, strategy: null };
+}
+async function $LT_MatchSourceToDtsFiles(files, distPath, cwd, config) {
+  const sourceFileToVariables = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const sourceFilePath = path__default.resolve(cwd, file.relativeFilePath);
+    const variableNames = /* @__PURE__ */ new Set();
+    for (const tag of file.tags) {
+      if (tag.variableName) {
+        variableNames.add(tag.variableName);
+      }
+    }
+    if (variableNames.size > 0) {
+      sourceFileToVariables.set(sourceFilePath, variableNames);
+    }
+  }
+  if (sourceFileToVariables.size === 0) {
+    return [];
+  }
+  const dtsFiles = await globby("**/*.d.ts", {
+    cwd: distPath,
+    absolute: true
+  });
+  if (dtsFiles.length === 0) {
+    return [];
+  }
+  const dtsFileMap = /* @__PURE__ */ new Map();
+  for (const dtsFile of dtsFiles) {
+    const relativeDtsPath = path__default.relative(distPath, dtsFile);
+    const baseName = path__default.basename(dtsFile, ".d.ts");
+    const relativePathWithoutExt = relativeDtsPath.replace(/\.d\.ts$/, "");
+    dtsFileMap.set(relativePathWithoutExt, dtsFile);
+    dtsFileMap.set(baseName, dtsFile);
+  }
+  const matches = [];
+  const processedDtsFiles = /* @__PURE__ */ new Set();
+  for (const [sourceFilePath, variableNames] of sourceFileToVariables) {
+    const sourceRelativePath = path__default.relative(cwd, sourceFilePath);
+    const match = findMatchingDtsFile(
+      sourceFilePath,
+      sourceRelativePath,
+      dtsFileMap,
+      config
+    );
+    if (!match.dtsFilePath) {
+      continue;
+    }
+    if (processedDtsFiles.has(match.dtsFilePath)) {
+      continue;
+    }
+    processedDtsFiles.add(match.dtsFilePath);
+    matches.push({
+      sourceFilePath,
+      sourceRelativePath,
+      dtsFilePath: match.dtsFilePath,
+      variableNames
+    });
+  }
+  return matches;
+}
+async function $LT_CMD_HideCompiledExports(options) {
+  const { config, logger } = await $LT_GetCommandEssentials();
+  const distDir = options?.distDir || config.hideDistDir || "dist";
+  const distPath = path__default.resolve(process__default.cwd(), distDir);
+  if (!existsSync(distPath)) {
+    logger.warn("Dist directory does not exist: {distPath}", { distPath });
+    return;
+  }
+  logger.info("Scanning source files for lang-tag variables...");
+  const files = await $LT_CollectCandidateFilesWithTags({
+    config,
+    logger,
+    skipEmptyNamespaceCheck: true
+  });
+  const matches = await $LT_MatchSourceToDtsFiles(
+    files,
+    distPath,
+    process__default.cwd(),
+    config
+  );
+  if (matches.length === 0) {
+    logger.info(
+      "No lang-tag variables found in source files or no matching .d.ts files found."
+    );
+    return;
+  }
+  logger.info("Found {count} .d.ts files to process", {
+    count: matches.length
+  });
+  let hiddenCount = 0;
+  for (const match of matches) {
+    try {
+      const result = $LT_HideExportsInDtsFile(
+        match.dtsFilePath,
+        match.variableNames
+      );
+      if (!result.hiddenCount) {
+        continue;
+      }
+      writeFileSync(match.dtsFilePath, result.modifiedContent, "utf-8");
+      hiddenCount += result.hiddenCount;
+      const hiddenVariables = Array.from(match.variableNames).join(", ");
+      logger.debug(
+        "Hidden exports from {file}: {variables} (from {sourceFile})",
+        {
+          file: path__default.relative(process__default.cwd(), match.dtsFilePath),
+          variables: hiddenVariables,
+          sourceFile: match.sourceRelativePath
+        }
+      );
+    } catch (error) {
+      logger.warn("Error processing file {file}: {error}", {
+        file: match.sourceRelativePath,
+        error: error.message || String(error)
+      });
+    }
+  }
+  logger.success("Hidden {hiddenCount} exports from {fileCount} files.", {
+    hiddenCount,
+    fileCount: matches.length
+  });
+}
 async function $LT_CollectExportFiles(logger) {
   const nodeModulesPath = path$1.join(process__default.cwd(), "node_modules");
   if (!fs.existsSync(nodeModulesPath)) {
@@ -1621,11 +1898,11 @@ async function generateImportFiles(config, logger, importManager) {
     const content = renderTemplate$2(templateData);
     await $LT_EnsureDirectoryExists(dirname(filePath));
     await writeFile(filePath, content, "utf-8");
-    const encodedFilePath = encodeURI(filePath);
+    const fileUrl = formatFileUrlForDisplay(filePath);
     logger.success('Created tag file: "{file}"', {
       file: importedFile.pathRelativeToImportDir
     });
-    logger.debug(" └── link: file://{path}", { path: encodedFilePath });
+    logger.debug(" └── link: {url}", { url: fileUrl });
   }
 }
 class ImportManager {
@@ -2124,7 +2401,10 @@ async function detectInitTagOptions(options, config) {
   const isTypeScript = options.typescript !== void 0 ? options.typescript : detectTypeScript(packageJson);
   const isReact = options.react !== void 0 ? options.react : detectReact(packageJson);
   const isLibrary = options.library !== void 0 ? options.library : config.isLibrary;
-  const tagName = options.name || config.tagName || "lang";
+  let tagName = options.name || config.tagName || "lang";
+  if (isLibrary && (config.enforceLibraryTagPrefix ?? true) && !tagName.startsWith("_")) {
+    tagName = `_${tagName}`;
+  }
   const fileExtension = isLibrary && isReact ? isTypeScript ? "tsx" : "jsx" : isTypeScript ? "ts" : "js";
   return {
     tagName,
@@ -2225,22 +2505,22 @@ async function $LT_CMD_InitTagFile(options = {}) {
       "2. Create your translation objects and use the tag function"
     );
     logger.info('3. Run "lang-tag collect" to extract translations');
+    if (renderOptions.isLibrary && renderOptions.tagName.startsWith("_") && (config.enforceLibraryTagPrefix ?? true)) {
+      console.log("");
+      logger.info(
+        '📌 Important: Library tag prefix enforcement is enabled\n	Your tag uses "_" prefix: {tagName} (instead of {baseTagName})\n	This prevents the tag from appearing in TypeScript autocomplete after compilation\n	Always use {tagName} (with prefix) in your library code\n	This is a best practice for library internals - it keeps your API clean\n	The prefix is automatically added by the enforceLibraryTagPrefix option\n	To disable this behavior, set enforceLibraryTagPrefix: false in your config',
+        {
+          tagName: renderOptions.tagName,
+          baseTagName: renderOptions.tagName.substring(1)
+        }
+      );
+    }
   } catch (error) {
     logger.error("Failed to write file: {error}", {
       error: error?.message
     });
   }
 }
-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;
@@ -2274,13 +2554,23 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path2) {
         event.isSaved = true;
         event.savedConfig = updatedConfig;
         logger.debug(
-          'Called save for "{path}" with config "{config}" triggered by: ("{trigger}")',
+          'Called save for "{path}"{varName} with config "{config}" triggered by: ("{trigger}")',
           {
             path: path2,
             config: JSON.stringify(updatedConfig),
-            trigger: triggerName || "-"
+            trigger: triggerName || "-",
+            varName: tag.variableName ? `(${tag.variableName})` : ""
           }
         );
+      },
+      getCurrentConfig: () => {
+        if (event.savedConfig !== void 0 && event.savedConfig !== null) {
+          return { ...event.savedConfig };
+        }
+        if (event.config) {
+          return { ...event.config };
+        }
+        return {};
       }
     };
     await config.onConfigGeneration(event);
@@ -2295,10 +2585,10 @@ async function checkAndRegenerateFileLangTags(config, logger, file, path2) {
   if (replacements.length) {
     const newContent = processor.replaceTags(fileContent, replacements);
     await writeFile(file, newContent, "utf-8");
-    const encodedFile = encodeURI(file);
+    const fileUrl = formatFileUrlForDisplay(file);
     logger.info(
-      'Lang tag configurations written for file "{path}" (file://{file}:{line})',
-      { path: path2, file: encodedFile, line: lastUpdatedLine }
+      'Lang tag configurations written for file "{path}" ({url}:{line})',
+      { path: path2, url: fileUrl, line: lastUpdatedLine }
     );
     return true;
   }
@@ -2311,6 +2601,7 @@ function isConfigSame(c1, c2) {
   return false;
 }
 async function $LT_CMD_RegenerateTags() {
+  const startTime = Date.now();
   const { config, logger } = await $LT_GetCommandEssentials();
   const files = await globby(config.includes, {
     cwd: process.cwd(),
@@ -2331,11 +2622,13 @@ async function $LT_CMD_RegenerateTags() {
       dirty = true;
     }
   }
+  const executionTime = formatExecutionTime(Date.now() - startTime);
   if (!dirty) {
     logger.info(
       "No changes were made based on the current configuration and files"
     );
   }
+  logger.debug("Regeneration completed ({time})", { time: executionTime });
 }
 function getBasePath(pattern) {
   const globStartIndex = pattern.indexOf("*");
@@ -2444,6 +2737,14 @@ function createCli() {
   ).action(async (options) => {
     await $LT_CMD_InitTagFile(options);
   });
+  program.command("hide-compiled-exports").alias("hce").description(
+    "Hide compiled .d.ts exports of lang-tag variables (remove export modifier, keep type)"
+  ).option(
+    "-d, --dist-dir <dir>",
+    'Dist directory to process (default: from config or "dist")'
+  ).action(async (options) => {
+    await $LT_CMD_HideCompiledExports({ distDir: options.distDir });
+  });
   return program;
 }
 createCli().parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lang-tag/cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,8 @@
     "json5": "^2.2.3",
     "micromatch": "^4.0.8",
     "mustache": "^4.2.0",
-    "pathe": "^2.0.3"
+    "pathe": "^2.0.3",
+    "ts-morph": "^24.0.0"
   },
   "keywords": [
     "i18n",

package/templates/tag/base-app.mustache

@@ -1,8 +1,8 @@
 {{#isTypeScript}}
 import {
-    CallableTranslations,
-    LangTagTranslations,
-    LangTagTranslationsConfig,
+    type CallableTranslations,
+    type LangTagTranslations,
+    type LangTagTranslationsConfig,
     createCallableTranslations
 } from 'lang-tag';
 {{/isTypeScript}}
@@ -10,7 +10,7 @@ import {
 import { createCallableTranslations } from 'lang-tag';
 {{/isTypeScript}}
 {{#isReact}}
-import React, { ReactNode, useMemo } from 'react';
+import React, { type ReactNode, useMemo } from 'react';
 {{/isReact}}
 
 {{#isTypeScript}}

package/templates/tag/base-library.mustache

@@ -1,9 +1,9 @@
 {{#isTypeScript}}
 import {
-    CallableTranslations,
-    LangTagTranslations,
-    LangTagTranslationsConfig,
-    PartialFlexibleTranslations,
+    type CallableTranslations,
+    type LangTagTranslations,
+    type LangTagTranslationsConfig,
+    type PartialFlexibleTranslations,
     createCallableTranslations,
     normalizeTranslations,
     lookupTranslation
@@ -17,7 +17,7 @@ import React, {
     createContext,
     useContext,
     useMemo,
-    ReactNode
+    type ReactNode
 } from 'react';
 {{/isReact}}
 

package/templates/tag/placeholder.mustache

@@ -30,8 +30,16 @@ export function processPlaceholders(
         }
 
         const key = placeholder.trim();
-        if (params && key in params) {
-            parts.push(params[key]);
+        const value = params?.[key];
+
+        if (React.isValidElement(value)) {
+            parts.push(value);
+        } else if (
+            typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean'
+        ) {
+            parts.push(String(value));
         } else {
             parts.push('');
         }
@@ -49,12 +57,11 @@ export function processPlaceholders(
         return parts.join('');
     }
 
-    return parts.map((part, index) => {
-        if (React.isValidElement(part)) {
-            return React.cloneElement(part, { key: index });
-        }
-        return React.createElement(React.Fragment, { key: index }, part);
-    }){{#isTypeScript}} as unknown as string{{/isTypeScript}};
+    return parts.map((part, index) =>
+        React.isValidElement(part)
+            ? React.cloneElement(part, { key: index })
+            : React.createElement(React.Fragment, { key: index }, part)
+    ){{#isTypeScript}} as unknown as string{{/isTypeScript}};
 }
 {{/isReact}}
 

package/type.d.ts

@@ -40,6 +40,17 @@ export interface LangTagCLIConfig {
      * @default false
      */
     isLibrary: boolean;
+    /**
+     * When true and isLibrary is true, automatically adds "_" prefix to tagName
+     * to prevent the tag from being suggested in TypeScript autocomplete after compilation.
+     * This ensures that library tags remain internal and are not exposed in .d.ts files.
+     * @default true
+     * @example
+     * // With enforceLibraryTagPrefix: true and tagName: "lang"
+     * // Generated tag function will be: export function _lang(...)
+     * // Config tagName also will be automatically set to "_lang"
+     */
+    enforceLibraryTagPrefix?: boolean;
     collect?: {
         /**
          * Translation collector that defines how translation tags are organized into output files.
@@ -134,6 +145,12 @@ export interface LangTagCLIConfig {
      * @default 1
      */
     translationArgPosition: 1 | 2;
+    /**
+     * Directory containing compiled TypeScript declaration files (.d.ts) to remove export modifier.
+     * Used by the `hide-compiled-exports` command to remove exports of lang-tag variables.
+     * @default 'dist'
+     */
+    hideDistDir?: string;
     debug?: boolean;
 }
 type Validity = 'ok' | 'invalid-param-1' | 'invalid-param-2' | 'translations-not-found';
@@ -234,6 +251,23 @@ export interface LangTagCLIConfigGenerationEvent {
      * null = means configuration will be removed
      **/
     save(config: LangTagTranslationsConfig | null, triggerName?: string): void;
+    /**
+     * Returns the current configuration object that should be used as a base for modifications.
+     * This method provides a reusable way to get the active configuration:
+     * - If `save()` was called, returns `savedConfig` (a mutable copy)
+     * - Otherwise, returns `config` (a mutable copy)
+     * - If neither exists, returns an empty object `{}`
+     *
+     * The returned object is always a shallow copy, so it can be safely modified.
+     *
+     * @example
+     * ```ts
+     * const currentConfig = event.getCurrentConfig();
+     * currentConfig.namespace = 'new-namespace';
+     * event.save(currentConfig);
+     * ```
+     */
+    getCurrentConfig(): LangTagTranslationsConfig;
 }
 export interface LangTagCLICollectConfigFixEvent {
     config: LangTagTranslationsConfig;