@lang-tag/cli 0.14.0 → 0.16.0

package/config.d.ts

@@ -1,5 +1,6 @@
 import { LangTagTranslationsConfig } from 'lang-tag';
 import { LangTagCLILogger } from './logger.ts';
+import { TranslationsCollector } from './algorithms';
 export interface LangTagCLIConfig {
     /**
      * Tag name used to mark translations in code.
@@ -17,11 +18,37 @@ export interface LangTagCLIConfig {
      */
     excludes: string[];
     /**
-     * Output directory for generated translation namespace files (e.g., common.json, errors.json).
-     * @default 'locales/en'
+     * Root directory for translation files.
+     * The actual file structure depends on the collector implementation used.
+     * @default 'locales'
+     * @example With baseLanguageCode='en' and localesDirectory='locales':
+     *   - NamespaceCollector (default): locales/en/common.json, locales/en/errors.json
+     *   - DictionaryCollector: locales/en.json (all translations in one file)
      */
-    outputDir: string;
+    localesDirectory: string;
+    /**
+     * The language in which translation values/messages are written in the codebase.
+     * This determines the source language for your translations.
+     * @default 'en'
+     * @example 'en' - Translation values are in English: lang({ helloWorld: 'Hello World' })
+     * @example 'pl' - Translation values are in Polish: lang({ helloWorld: 'Witaj Świecie' })
+     */
+    baseLanguageCode: string;
+    /**
+     * Indicates whether this configuration is for a translation library.
+     * If true, generates an exports file (`.lang-tag.exports.json`) instead of locale files.
+     * @default false
+     */
+    isLibrary: boolean;
     collect?: {
+        /**
+         * Translation collector that defines how translation tags are organized into output files.
+         * If not specified, NamespaceCollector is used by default.
+         * @default NamespaceCollector
+         * @example DictionaryCollector - All translations in single file per language
+         * @example NamespaceCollector - Separate files per namespace within language directory
+         */
+        collector?: TranslationsCollector;
         /**
          * @default 'common'
          */
@@ -50,50 +77,6 @@ export interface LangTagCLIConfig {
          */
         onCollectFinish?: (event: LangTagCLICollectFinishEvent) => void;
     };
-    import: {
-        /**
-         * Output directory for generated files containing imported library tags.
-         * @default 'src/lang-libraries'
-         */
-        dir: string;
-        /**
-         * The import statement used in generated library files to import the project's `lang` tag function.
-         * @default 'import { lang } from "@/my-lang-tag-path"'
-         */
-        tagImportPath: string;
-        /**
-         * A function to customize the generated file name and export name for imported library tags.
-         * Allows controlling how imported tags are organized and named within the generated files.
-         */
-        onImport: (params: LangTagCLIOnImportParams, actions: LangTagCLIOnImportActions) => void;
-        /**
-         * A function called after all lang-tags were imported
-         */
-        onImportFinish?: () => void;
-    };
-    /**
-     * Determines the position of the translation argument in the `lang()` function.
-     * If `1`, translations are in the first argument (`lang(translations, options)`).
-     * If `2`, translations are in the second argument (`lang(options, translations)`).
-     * @default 1
-     */
-    translationArgPosition: 1 | 2;
-    /**
-     * Primary language used for the library's translations.
-     * Affects default language settings when used in library mode.
-     * @default 'en'
-     */
-    language: string;
-    /**
-     * Indicates whether this configuration is for a translation library.
-     * If true, generates an exports file (`.lang-tag.exports.json`) instead of locale files.
-     * @default false
-     */
-    isLibrary: boolean;
-    /**
-     * Whether to flatten the translation keys. (Currently unused)
-     * @default false
-     */
     /**
      * A function called for each found lang tag before processing.
      * Allows dynamic modification of the tag's configuration (namespace, path, etc.)
@@ -123,36 +106,36 @@ export interface LangTagCLIConfig {
      * ```
      */
     onConfigGeneration: (event: LangTagCLIConfigGenerationEvent) => Promise<void>;
+    import: {
+        /**
+         * Output directory for generated files containing imported library tags.
+         * @default 'src/lang-libraries'
+         */
+        dir: string;
+        /**
+         * The import statement used in generated library files to import the project's `lang` tag function.
+         * @default 'import { lang } from "@/my-lang-tag-path"'
+         */
+        tagImportPath: string;
+        /**
+         * A function to customize the generated file name and export name for imported library tags.
+         * Allows controlling how imported tags are organized and named within the generated files.
+         */
+        onImport: (event: LangTagCLIImportEvent) => void;
+        /**
+         * A function called after all lang-tags were imported
+         */
+        onImportFinish?: () => void;
+    };
+    /**
+     * Determines the position of the translation argument in the `lang()` function.
+     * If `1`, translations are in the first argument (`lang(translations, options)`).
+     * If `2`, translations are in the second argument (`lang(options, translations)`).
+     * @default 1
+     */
+    translationArgPosition: 1 | 2;
     debug?: boolean;
 }
-/**
- * Parameters passed to the `onImport` configuration function.
- */
-export interface LangTagCLIOnImportParams {
-    /** The name of the package from which the tag is being imported. */
-    packageName: string;
-    /** The relative path to the source file within the imported package. */
-    importedRelativePath: string;
-    /** The original variable name assigned to the lang tag in the source library file, if any. */
-    originalExportName: string | undefined;
-    /** Parsed JSON translation object from the imported tag. */
-    translations: Record<string, any>;
-    /** Configuration object associated with the imported tag. */
-    config: LangTagTranslationsConfig;
-    /** A mutable object that can be used to pass data between multiple `onImport` calls for the same generated file. */
-    fileGenerationData: any;
-}
-/**
- * Actions that can be performed within the onImport callback.
- */
-export interface LangTagCLIOnImportActions {
-    /** Sets the desired file for the generated import. */
-    setFile: (file: string) => void;
-    /** Sets the desired export name for the imported tag. */
-    setExportName: (name: string) => void;
-    /** Sets the configuration for the currently imported tag. */
-    setConfig: (config: LangTagTranslationsConfig) => void;
-}
 type Validity = 'ok' | 'invalid-param-1' | 'invalid-param-2' | 'translations-not-found';
 export interface LangTagCLIProcessedTag {
     fullMatch: string;
@@ -180,6 +163,43 @@ export interface LangTagCLIConflict {
     tagB: LangTagCLITagConflictInfo;
     conflictType: 'path_overwrite' | 'type_mismatch';
 }
+export interface LangTagCLIImportManager {
+    importTag(pathRelativeToImportDir: string, tag: LangTagCLIImportedTag): void;
+    getImportedFiles(): LangTagCLIImportedTagsFile[];
+    getImportedFilesCount(): number;
+    hasImportedFiles(): boolean;
+}
+export interface LangTagCLIImportedTag {
+    variableName: string;
+    translations: any;
+    config: any | null;
+}
+export interface LangTagCLIImportedTagsFile {
+    pathRelativeToImportDir: string;
+    tags: LangTagCLIImportedTag[];
+}
+export interface LangTagCLIExportData {
+    baseLanguageCode: string;
+    files: LangTagCLIExportDataFile[];
+}
+export interface LangTagCLIExportDataFile {
+    relativeFilePath: string;
+    tags: LangTagCLIExportDataTag[];
+}
+export interface LangTagCLIExportDataTag {
+    variableName: string | undefined;
+    translations: object;
+    config: object | undefined;
+}
+export interface LangTagCLIImportEvent {
+    exports: {
+        packageJSON: any;
+        exportData: LangTagCLIExportData;
+    }[];
+    langTagConfig: LangTagCLIConfig;
+    logger: LangTagCLILogger;
+    importManager: LangTagCLIImportManager;
+}
 export interface LangTagCLIConfigGenerationEvent {
     /** The absolute path to the source file being processed. */
     readonly absolutePath: string;

package/flexible-import-algorithm-C-S1c742.js

@@ -0,0 +1,311 @@
+import { mkdir, writeFile, readFile, rm } from "fs/promises";
+import { dirname, resolve } from "path";
+import path, { resolve as resolve$1, join } from "pathe";
+import process__default from "node:process";
+import * as caseLib from "case";
+import micromatch from "micromatch";
+function applyCaseTransform(str, caseType) {
+  if (caseType === "no") {
+    return str;
+  }
+  const caseFunction = caseLib[caseType];
+  if (typeof caseFunction === "function") {
+    return caseFunction(str);
+  }
+  return str;
+}
+class TranslationsCollector {
+  config;
+  logger;
+}
+async function $LT_EnsureDirectoryExists(filePath) {
+  await mkdir(filePath, { recursive: true });
+}
+async function $LT_RemoveDirectory(dirPath) {
+  try {
+    await rm(dirPath, { recursive: true, force: true });
+  } catch (error) {
+  }
+}
+async function $LT_RemoveFile(filePath) {
+  try {
+    await rm(filePath, { force: true });
+  } catch (error) {
+  }
+}
+async function $LT_WriteJSON(filePath, data) {
+  await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+async function $LT_ReadJSON(filePath) {
+  const content = await readFile(filePath, "utf-8");
+  return JSON.parse(content);
+}
+async function $LT_WriteFileWithDirs(filePath, content) {
+  const dir = dirname(filePath);
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch (error) {
+  }
+  await writeFile(filePath, content, "utf-8");
+}
+async function $LT_ReadFileContent(relativeFilePath) {
+  const cwd = process.cwd();
+  const absolutePath = resolve(cwd, relativeFilePath);
+  return await readFile(absolutePath, "utf-8");
+}
+class NamespaceCollector extends TranslationsCollector {
+  clean;
+  languageDirectory;
+  aggregateCollection(namespace) {
+    return namespace;
+  }
+  transformTag(tag) {
+    return tag;
+  }
+  async preWrite(clean) {
+    this.clean = clean;
+    this.languageDirectory = path.join(this.config.localesDirectory, this.config.baseLanguageCode);
+    if (clean) {
+      this.logger.info("Cleaning output directory...");
+      await $LT_RemoveDirectory(this.languageDirectory);
+    }
+    await $LT_EnsureDirectoryExists(this.languageDirectory);
+  }
+  async resolveCollectionFilePath(collectionName) {
+    return resolve$1(
+      process__default.cwd(),
+      this.languageDirectory,
+      collectionName + ".json"
+    );
+  }
+  async onMissingCollection(collectionName) {
+    if (!this.clean) {
+      this.logger.warn(`Original namespace file "{namespace}.json" not found. A new one will be created.`, { namespace: collectionName });
+    }
+  }
+  async postWrite(changedCollections) {
+    if (!changedCollections?.length) {
+      this.logger.info("No changes were made based on the current configuration and files");
+      return;
+    }
+    const n = changedCollections.map((n2) => `"${n2}.json"`).join(", ");
+    this.logger.success("Updated namespaces {outputDir} ({namespaces})", {
+      outputDir: this.config.localesDirectory,
+      namespaces: n
+    });
+  }
+}
+function flexibleImportAlgorithm(options = {}) {
+  const {
+    variableName = {},
+    filePath = {},
+    include,
+    exclude = {},
+    configRemap
+  } = options;
+  const { packages: includePackages, namespaces: includeNamespaces } = include || {};
+  const { packages: excludePackages = [], namespaces: excludeNamespaces = [] } = exclude;
+  return (event) => {
+    const { exports, importManager, logger } = event;
+    for (const { packageJSON, exportData } of exports) {
+      const packageName = packageJSON.name || "unknown-package";
+      if (includePackages && !matchesAnyPattern(packageName, includePackages)) {
+        logger.debug(`Skipping package not in include list: ${packageName}`);
+        continue;
+      }
+      if (matchesAnyPattern(packageName, excludePackages)) {
+        logger.debug(`Skipping excluded package: ${packageName}`);
+        continue;
+      }
+      logger.debug(`Processing library: ${packageName}`);
+      for (const file of exportData.files) {
+        const originalFileName = file.relativeFilePath;
+        const targetFilePath = generateFilePath(packageName, originalFileName, filePath);
+        for (let i = 0; i < file.tags.length; i++) {
+          const tag = file.tags[i];
+          const tagNamespace = tag.config?.namespace;
+          if (includeNamespaces && tagNamespace && !matchesAnyPattern(tagNamespace, includeNamespaces)) {
+            logger.debug(`Skipping namespace not in include list: ${tagNamespace}`);
+            continue;
+          }
+          if (tagNamespace && matchesAnyPattern(tagNamespace, excludeNamespaces)) {
+            logger.debug(`Skipping excluded namespace: ${tagNamespace}`);
+            continue;
+          }
+          const finalVariableName = generateVariableName(tag.variableName, packageName, originalFileName, i, variableName, tag);
+          if (finalVariableName === null) {
+            logger.debug(`Skipping tag without variableName in ${join(packageName, originalFileName)}`);
+            continue;
+          }
+          let finalConfig = tag.config;
+          if (configRemap) {
+            const remappedConfig = configRemap(tag.config, {
+              packageName,
+              fileName: originalFileName,
+              variableName: finalVariableName,
+              tagIndex: i
+            });
+            if (remappedConfig === null) {
+              logger.debug(`Removing config due to configRemap returning null in ${join(packageName, originalFileName)}`);
+              finalConfig = null;
+            } else {
+              finalConfig = remappedConfig;
+            }
+          }
+          importManager.importTag(targetFilePath, {
+            variableName: finalVariableName,
+            translations: tag.translations,
+            config: finalConfig
+          });
+          logger.debug(`Imported: ${finalVariableName} -> ${targetFilePath}`);
+        }
+      }
+    }
+  };
+}
+function sanitizeVariableName(name) {
+  let sanitized = name.replace(/[^a-zA-Z0-9_$]/g, "$");
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "$" + sanitized;
+  }
+  if (sanitized === "") {
+    sanitized = "$";
+  }
+  return sanitized;
+}
+function applyCaseTransformToPath(filePath, caseType) {
+  if (typeof caseType === "string") {
+    const segments = filePath.split("/");
+    const fileName = segments[segments.length - 1];
+    const directorySegments = segments.slice(0, -1);
+    const transformedDirectories = directorySegments.map((dir) => applyCaseTransform(dir, caseType));
+    const transformedFileName = applyCaseTransformToFileName(fileName, caseType);
+    if (transformedDirectories.length === 0) {
+      return transformedFileName;
+    }
+    return [...transformedDirectories, transformedFileName].join("/");
+  }
+  if (typeof caseType === "object") {
+    const { directories = "no", files = "no" } = caseType;
+    const segments = filePath.split("/");
+    const fileName = segments[segments.length - 1];
+    const directorySegments = segments.slice(0, -1);
+    const transformedDirectories = directorySegments.map((dir) => applyCaseTransform(dir, directories));
+    const transformedFileName = applyCaseTransformToFileName(fileName, files);
+    if (transformedDirectories.length === 0) {
+      return transformedFileName;
+    }
+    return [...transformedDirectories, transformedFileName].join("/");
+  }
+  return filePath;
+}
+function normalizePackageName(packageName, scopedPackageHandling = "replace", context = "variableName") {
+  switch (scopedPackageHandling) {
+    case "remove-scope":
+      let result = packageName.replace(/^@[^/]+\//, "");
+      if (context === "variableName") {
+        result = result.replace(/[^a-zA-Z0-9_$]/g, "_");
+      }
+      return result;
+    case "replace":
+    default:
+      let normalized = packageName.replace(/@/g, "").replace(/\//g, context === "variableName" ? "_" : "-");
+      if (context === "variableName") {
+        normalized = normalized.replace(/[^a-zA-Z0-9_$]/g, "_");
+      }
+      return normalized;
+  }
+}
+function generateVariableName(originalVariableName, packageName, fileName, index, options, tag) {
+  const {
+    prefixWithPackageName = false,
+    scopedPackageHandling = "replace",
+    case: caseType = "no",
+    sanitizeVariableName: shouldSanitize = true,
+    handleMissingVariableName = "auto-generate",
+    customVariableName
+  } = options;
+  if (customVariableName) {
+    const customName = customVariableName({
+      packageName,
+      fileName,
+      originalVariableName,
+      tagIndex: index,
+      tag
+    });
+    if (customName !== null) {
+      originalVariableName = customName;
+    }
+  }
+  if (!originalVariableName) {
+    switch (handleMissingVariableName) {
+      case "skip":
+        return null;
+      case "auto-generate":
+        originalVariableName = `translations${index + 1}`;
+        break;
+      default:
+        if (typeof handleMissingVariableName === "function") {
+          originalVariableName = handleMissingVariableName({}, packageName, fileName, index);
+        } else {
+          return null;
+        }
+    }
+  }
+  let finalName = originalVariableName;
+  if (prefixWithPackageName) {
+    const normalizedPackageName = normalizePackageName(packageName, scopedPackageHandling, "variableName");
+    finalName = `${normalizedPackageName}_${originalVariableName}`;
+  }
+  const transformedName = applyCaseTransform(finalName, caseType);
+  return shouldSanitize ? sanitizeVariableName(transformedName) : transformedName;
+}
+function generateFilePath(packageName, originalFileName, options) {
+  const { groupByPackage = false, includePackageInPath = false, scopedPackageHandling = "replace", case: caseType = "no" } = options;
+  if (groupByPackage) {
+    const normalizedPackageName = normalizePackageName(packageName, scopedPackageHandling, "filePath");
+    const fileName = `${normalizedPackageName}.ts`;
+    return applyCaseTransformToFileName(fileName, typeof caseType === "string" ? caseType : caseType.files || "no");
+  } else if (includePackageInPath) {
+    const normalizedPackageName = normalizePackageName(packageName, scopedPackageHandling, "filePath");
+    if (typeof caseType === "string") {
+      const transformedPackageName = applyCaseTransform(normalizedPackageName, caseType);
+      const transformedFilePath = applyCaseTransformToPath(originalFileName, caseType);
+      return join(transformedPackageName, transformedFilePath);
+    } else {
+      const transformedPackageName = applyCaseTransform(normalizedPackageName, caseType.directories || "no");
+      const transformedFilePath = applyCaseTransformToPath(originalFileName, caseType);
+      return join(transformedPackageName, transformedFilePath);
+    }
+  } else {
+    return applyCaseTransformToPath(originalFileName, caseType);
+  }
+}
+function applyCaseTransformToFileName(fileName, caseType) {
+  if (caseType === "no") {
+    return fileName;
+  }
+  const lastDotIndex = fileName.lastIndexOf(".");
+  if (lastDotIndex === -1) {
+    return applyCaseTransform(fileName, caseType);
+  }
+  const nameWithoutExt = fileName.substring(0, lastDotIndex);
+  const extension = fileName.substring(lastDotIndex);
+  const transformedName = applyCaseTransform(nameWithoutExt, caseType);
+  return transformedName + extension;
+}
+function matchesAnyPattern(str, patterns) {
+  return micromatch.isMatch(str, patterns);
+}
+export {
+  $LT_ReadFileContent as $,
+  NamespaceCollector as N,
+  TranslationsCollector as T,
+  $LT_ReadJSON as a,
+  $LT_WriteJSON as b,
+  $LT_EnsureDirectoryExists as c,
+  $LT_WriteFileWithDirs as d,
+  $LT_RemoveFile as e,
+  flexibleImportAlgorithm as f,
+  applyCaseTransform as g
+};