@lang-tag/cli 0.15.0 → 0.17.0

package/README.md

@@ -1,6 +1,5 @@
 # Lang-tag CLI
 
-
 A professional solution for managing translations in modern JavaScript/TypeScript projects, especially those using component-based architectures. `lang-tag` simplifies internationalization by allowing you to define translation keys directly within the components where they are used. Translations become local, callable function objects with full TypeScript support, IntelliSense, and compile-time safety.
 
 ## Key Benefits
@@ -15,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 directory-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.
 
@@ -31,6 +30,7 @@ Full functionality is available through an advanced CLI that keeps your applicat
 ### Practical and Flexible Architecture
 
 The solution provides:
+
 - **Framework agnostic** – works with any JavaScript/TypeScript project and integrates easily with libraries like react-i18next
 - **Library ecosystem support** - create reusable component libraries with embedded lang-tag translations that consuming lang-tag applications can easily import/integrate and override
 - **Full TypeScript support** - complete type safety with IntelliSense for all translation keys and interpolation parameters
@@ -49,21 +49,24 @@ Instead of maintaining separate translation files and complex key mappings, tran
 // Component with colocated translations using custom i18n tag
 import { i18n } from '../utils/i18n';
 
-const translations = i18n({
-    greeting: 'Welcome {{name}} to our store!',
-    orderSummary: 'You have {{count}} items in your cart.',
-    actions: {
-        proceed: 'Proceed to Payment',
-        cancel: 'Cancel Order'
+const translations = i18n(
+    {
+        greeting: 'Welcome {{name}} to our store!',
+        orderSummary: 'You have {{count}} items in your cart.',
+        actions: {
+            proceed: 'Proceed to Payment',
+            cancel: 'Cancel Order',
+        },
+    },
+    {
+        namespace: 'orders',
+        path: 'components.checkout',
     }
-}, {
-    namespace: 'orders',
-    path: 'components.checkout'
-});
+);
 
 function CheckoutComponent({ name, count }) {
     const t = translations.useT();
-    
+
     return (
         <div>
             <h2>{t.greeting({ name })}</h2>
@@ -82,16 +85,19 @@ function CheckoutComponent({ name, count }) {
 The `lang-tag` ecosystem provides tooling to transform colocated definitions into production-ready translation files:
 
 **Collection & Organization**
+
 - The `lang-tag collect` command discovers translation tags throughout your codebase
 - Translations are organized into namespace-based JSON files (e.g., `public/locales/en/orders.json`)
 - Hierarchical key structures can be automatically generated based on configuration rules (eg.: based on component paths)
 
 **Dynamic Configuration Management**
+
 - Configuration parameters can be automatically generated using `onConfigGeneration` rules
 - Namespace and path assignments can be derived from custom logic (eg.: by file structure, component location)
 - The `lang-tag regenerate-tags` command updates source code configurations dynamically
 
 **Development-Time Optimization**
+
 - Watch mode (`lang-tag watch`) provides real-time translation collection during development
 - Changes to translation definitions trigger automatic regeneration of translation files
 - Full TypeScript integration ensures compile-time validation of translation keys and parameters
@@ -99,16 +105,19 @@ The `lang-tag` ecosystem provides tooling to transform colocated definitions int
 ### Enterprise Integration Capabilities
 
 **Framework Agnostic Architecture**
+
 - Core library provides building blocks (like `createCallableTranslations`) for creating custom tag functions
 - Seamless integration with existing i18n libraries (i18next, react-i18next, etc.)
 - Maintains compatibility with current translation workflows while enhancing developer experience
 
 **Library Ecosystem Support**
+
 - Component libraries can embed translations using `.lang-tag.exports.json` manifests
 - The `lang-tag import` command automatically discovers and integrates library translations
 - Consuming applications maintain full control over translation overrides and customization
 
 **Type-Safe Translation Experience**
+
 - Complete TypeScript support with IntelliSense for all translation keys
 - Compile-time validation of interpolation parameters
 - Callable translation objects provide intuitive API with full type inference
@@ -134,4 +143,4 @@ For detailed setup, usage, and advanced features, please refer to the documentat
 - [React-i18next Example](docs/react-i18n-example.md)
 - [Library Support](docs/library-support.md)
 - [API Reference](docs/api-reference.md)
-- [Flexible Translation Definitions](docs/flexible-translations.md)
+- [Flexible Translation Definitions](docs/flexible-translations.md)

package/algorithms/case-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Available case transformation types supported by the case library.
+ */
+export type CaseType = 'no' | 'camel' | 'capital' | 'constant' | 'dot' | 'header' | 'kebab' | 'lower' | 'param' | 'pascal' | 'path' | 'sentence' | 'snake' | 'swap' | 'title' | 'upper';
+/**
+ * Applies case transformation to a string using the case library.
+ *
+ * @param str - The string to transform
+ * @param caseType - The case transformation type
+ * @returns The transformed string
+ */
+export declare function applyCaseTransform(str: string, caseType: CaseType): string;

package/algorithms/collector/dictionary-collector.d.ts

@@ -1,5 +1,5 @@
-import { TranslationsCollector } from './type.ts';
-import { LangTagCLIProcessedTag } from '../../config.ts';
+import { TranslationsCollector } from './type';
+import { LangTagCLIProcessedTag } from '../../type';
 interface Options {
     appendNamespaceToPath: boolean;
 }

package/algorithms/collector/index.d.ts

@@ -5,6 +5,6 @@
  * during the collection process. Each collector implements a different strategy
  * for organizing translations (e.g., single dictionary vs. namespace-based files).
  */
-export { DictionaryCollector } from './dictionary-collector.ts';
-export { NamespaceCollector } from './namespace-collector.ts';
-export { type TranslationsCollector } from './type.ts';
+export { DictionaryCollector } from './dictionary-collector';
+export { NamespaceCollector } from './namespace-collector';
+export { type TranslationsCollector } from './type';

package/algorithms/collector/namespace-collector.d.ts

@@ -1,5 +1,5 @@
-import { TranslationsCollector } from './type.ts';
-import { LangTagCLIProcessedTag } from '../../config.ts';
+import { TranslationsCollector } from './type';
+import { LangTagCLIProcessedTag } from '../../type';
 export declare class NamespaceCollector extends TranslationsCollector {
     private clean;
     private languageDirectory;

package/algorithms/collector/type.d.ts

@@ -1,5 +1,5 @@
-import { LangTagCLIConfig, LangTagCLIProcessedTag } from '../../config.ts';
-import { LangTagCLILogger } from '../../logger.ts';
+import { LangTagCLILogger } from '../../logger';
+import { LangTagCLIConfig, LangTagCLIProcessedTag } from '../../type';
 export declare abstract class TranslationsCollector {
     config: LangTagCLIConfig;
     logger: LangTagCLILogger;

package/algorithms/config-generation/config-keeper.d.ts

@@ -1,4 +1,4 @@
-import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+import { LangTagCLIConfigGenerationEvent } from '../../type';
 export type ConfigKeeperMode = 'namespace' | 'path' | 'both';
 export interface ConfigKeeperOptions {
     /**

package/algorithms/config-generation/index.d.ts

@@ -4,6 +4,6 @@
  * These algorithms customize how translation tag configurations are generated
  * during collection and regeneration.
  */
-export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions } from './path-based-config-generator.ts';
-export { configKeeper, type ConfigKeeperOptions, type ConfigKeeperMode } from './config-keeper.ts';
-export { prependNamespaceToPath, type PrependNamespaceToPathOptions } from './prepend-namespace-to-path.ts';
+export { pathBasedConfigGenerator, type PathBasedConfigGeneratorOptions, } from './path-based-config-generator';
+export { configKeeper, type ConfigKeeperOptions, type ConfigKeeperMode, } from './config-keeper';
+export { prependNamespaceToPath, type PrependNamespaceToPathOptions, } from './prepend-namespace-to-path';

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

@@ -1,4 +1,5 @@
-import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+import { LangTagCLIConfigGenerationEvent } from '../../type';
+import { CaseType } from '../case-utils';
 export interface PathBasedConfigGeneratorOptions {
     /**
      * Whether to include the filename (without extension) as part of the path segments.
@@ -120,14 +121,14 @@ export interface PathBasedConfigGeneratorOptions {
      * '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';
+    namespaceCase?: CaseType;
     /**
      * 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';
+    pathCase?: CaseType;
     /**
      * Fallback namespace to use when no segments remain after filtering.
      * Defaults to the defaultNamespace from langTagConfig.collect.defaultNamespace if not provided.

package/algorithms/config-generation/prepend-namespace-to-path.d.ts

@@ -1,4 +1,4 @@
-import { LangTagCLIConfigGenerationEvent } from '../../config.ts';
+import { LangTagCLIConfigGenerationEvent } from '../../type';
 /**
  * Options for the prependNamespaceToPath algorithm.
  */

package/algorithms/import/flexible-import-algorithm.d.ts

@@ -0,0 +1,232 @@
+import { LangTagCLIImportEvent } from '../../type';
+import { CaseType } from '../case-utils';
+/**
+ * Available case transformation options for variable names.
+ * Only includes transformations that produce valid JavaScript identifiers.
+ */
+export type VariableNameCaseType = 'no' | 'camel' | 'capital' | 'constant' | 'lower' | 'pascal' | 'snake' | 'swap' | 'upper';
+/**
+ * Case transformation configuration for file paths.
+ * Can be a string for uniform case transformation, or an object with separate
+ * case transformations for directories and files.
+ */
+export type FilePathCaseType = CaseType | {
+    directories?: CaseType;
+    files?: CaseType;
+};
+export interface VariableNameOptions {
+    /**
+     * Whether to prefix variable names with package name to avoid conflicts.
+     * @default false
+     */
+    prefixWithPackageName?: boolean;
+    /**
+     * How to handle scoped package names (e.g., '@scope/package').
+     * - 'remove-scope': Remove @scope/ part, keep only package name
+     * - 'replace': Remove @ and replace / with underscores
+     * @default 'replace'
+     */
+    scopedPackageHandling?: 'remove-scope' | 'replace';
+    /**
+     * Case transformation to apply to variable names.
+     * Available options: 'camel', 'capital', 'constant', 'lower', 'no', 'pascal', 'snake', 'swap', 'upper'
+     * @default 'no'
+     */
+    case?: VariableNameCaseType;
+    /**
+     * Whether to sanitize variable names by replacing invalid characters with $.
+     * This ensures the final variable name is a valid JavaScript identifier.
+     * @default true
+     */
+    sanitizeVariableName?: boolean;
+    /**
+     * How to handle tags without variableName.
+     * - 'skip': Skip tags without variableName
+     * - 'auto-generate': Generate names like 'translations1', 'translations2', etc. (default)
+     * - Function: Custom function to generate variable names
+     * @default 'auto-generate'
+     */
+    handleMissingVariableName?: 'skip' | 'auto-generate' | ((tag: any, packageName: string, fileName: string, index: number) => string);
+    /**
+     * Custom function to generate variable names, completely overriding original names from export.
+     * When provided, this function will be used instead of the original variableName from the export.
+     *
+     * Note: The returned custom name will still be processed by all other transformations
+     * (case transformation, sanitization, prefixWithPackageName, etc.).
+     *
+     * @param context - Context information about the import
+     * @returns The custom variable name, or null to fall back to original naming logic
+     *
+     * @example
+     * ```typescript
+     * customVariableName: (context) => {
+     *   // Generate names based on package and file structure
+     *   const packagePrefix = context.packageName.replace('@company/', '').replace('-', '');
+     *   const fileBase = context.fileName.split('/').pop()?.replace('.ts', '') || 'unknown';
+     *   return `${packagePrefix}_${fileBase}_${context.tagIndex + 1}`;
+     *   // This will still be processed by case transformation, sanitization, etc.
+     * }
+     * ```
+     */
+    customVariableName?: (context: {
+        packageName: string;
+        fileName: string;
+        originalVariableName: string | undefined;
+        tagIndex: number;
+        tag: any;
+    }) => string | null;
+}
+export interface FilePathOptions {
+    /**
+     * Whether to group all translations from each package into a single file.
+     * If false, preserves the original file structure from the library.
+     * @default false
+     */
+    groupByPackage?: boolean;
+    /**
+     * Whether to include package name in the file path.
+     * @default false
+     */
+    includePackageInPath?: boolean;
+    /**
+     * How to handle scoped package names in file paths (e.g., '@scope/package').
+     * - 'remove-scope': Remove @scope/ part, keep only package name
+     * - 'replace': Remove @ and replace / with dashes
+     * @default 'replace'
+     */
+    scopedPackageHandling?: 'remove-scope' | 'replace';
+    /**
+     * Case transformation to apply to file names and path segments.
+     * Can be a string for uniform case transformation, or an object with separate
+     * case transformations for directories and files.
+     * Available options: 'camel', 'capital', 'constant', 'dot', 'header', 'kebab',
+     * 'lower', 'no', 'param', 'pascal', 'path', 'sentence', 'snake', 'swap', 'title', 'upper'
+     * @default 'no'
+     */
+    case?: FilePathCaseType;
+}
+export interface FlexibleImportAlgorithmOptions {
+    /**
+     * Options for controlling variable name generation.
+     */
+    variableName?: VariableNameOptions;
+    /**
+     * Options for controlling file path generation.
+     */
+    filePath?: FilePathOptions;
+    /**
+     * Inclusion rules for filtering imports.
+     * If undefined, all packages and namespaces are processed.
+     * If defined, only matching packages and namespaces are processed.
+     */
+    include?: {
+        /**
+         * List of package name patterns to include from import.
+         * Supports wildcards with * (e.g., '@company/*', 'ui-*')
+         * @default undefined (include all)
+         */
+        packages?: string[];
+        /**
+         * List of namespace patterns to include from import.
+         * Supports wildcards with * (e.g., 'ui.*', '*.common')
+         * @default undefined (include all)
+         */
+        namespaces?: string[];
+    };
+    /**
+     * Exclusion rules for filtering imports.
+     * Applied after inclusion rules.
+     */
+    exclude?: {
+        /**
+         * List of package name patterns to exclude from import.
+         * Supports wildcards with * (e.g., '@company/*', 'ui-*')
+         * @default []
+         */
+        packages?: string[];
+        /**
+         * List of namespace patterns to exclude from import.
+         * Supports wildcards with * (e.g., 'admin.*', '*.internal')
+         * @default []
+         */
+        namespaces?: string[];
+    };
+    /**
+     * Function to remap/override configs before saving imported tags.
+     * Allows modification of namespace, path, and other config properties
+     * based on package name, file path, or other context.
+     *
+     * @param originalConfig - The original config from the imported tag
+     * @param context - Context information about the import
+     * @returns The modified config object, or null to remove the config from the tag
+     *
+     * @example
+     * ```typescript
+     * configRemap: (config, context) => {
+     *   // Override namespace based on package name
+     *   if (context.packageName === 'ui-components') {
+     *     return { ...config, namespace: 'ui' };
+     *   }
+     *
+     *   // Remove config for certain packages (tag will be imported without config)
+     *   if (context.packageName === 'no-config-package') {
+     *     return null;
+     *   }
+     *
+     *   // Add prefix to all paths
+     *   if (config.path) {
+     *     return { ...config, path: `lib.${config.path}` };
+     *   }
+     *
+     *   return config;
+     * }
+     * ```
+     */
+    configRemap?: (originalConfig: any, context: {
+        packageName: string;
+        fileName: string;
+        variableName: string;
+        tagIndex: number;
+    }) => any | null;
+}
+/**
+ * Default import algorithm that imports translations from libraries.
+ *
+ * This algorithm provides flexible options for organizing imported translations
+ * while preserving the ability to customize the import process.
+ *
+ * @param options - Configuration options for the import algorithm
+ * @returns A function compatible with LangTagCLIConfig.import.onImport
+ *
+ * @example
+ * ```typescript
+ * import { flexibleImportAlgorithm } from '@lang-tag/cli/algorithms';
+ *
+ * export default {
+ *   import: {
+ *     onImport: flexibleImportAlgorithm({
+ *       variableName: {
+ *         prefixWithPackageName: true,
+ *         scopedPackageHandling: 'replace', // '@scope/package' -> 'scope_package'
+ *         case: 'camel', // 'scope_package_myVar' -> 'scopePackageMyVar'
+ *         handleMissingVariableName: 'auto-generate' // Generate 'translations1', 'translations2', etc.
+ *       },
+ *       filePath: {
+ *         groupByPackage: true,
+ *         scopedPackageHandling: 'remove-scope', // '@scope/package' -> 'package'
+ *         case: 'kebab' // 'package.ts' -> 'package.ts' (no change), 'my-file.ts' -> 'my-file.ts'
+ *       },
+ *       include: {
+ *         packages: ['@company/*', 'ui-*'],
+ *         namespaces: ['ui.*', '*.common']
+ *       },
+ *       exclude: {
+ *         packages: ['@company/internal-*'],
+ *         namespaces: ['admin.*', '*.internal']
+ *       }
+ *     })
+ *   }
+ * };
+ * ```
+ */
+export declare function flexibleImportAlgorithm(options?: FlexibleImportAlgorithmOptions): (event: LangTagCLIImportEvent) => void;

package/algorithms/import/index.d.ts

@@ -4,4 +4,5 @@
  * These algorithms customize how library translations are imported
  * and organized in your project.
  */
-export {};
+export { flexibleImportAlgorithm, type FlexibleImportAlgorithmOptions, type FilePathCaseType, type VariableNameCaseType, } from './flexible-import-algorithm';
+export { simpleMappingImportAlgorithm, type SimpleMappingImportAlgorithmOptions, type PackageMapping, type FileMapping, } from './simple-mapping-import-algorithm';

package/algorithms/import/simple-mapping-import-algorithm.d.ts

@@ -0,0 +1,120 @@
+import { LangTagCLIImportEvent } from '../../type';
+/**
+ * Mapping for a specific file within a package.
+ * Defines which variables to import and optionally rename them.
+ */
+export interface FileMapping {
+    /**
+     * Source file path within the package
+     * @example 'components/button.ts'
+     */
+    sourceFile: string;
+    /**
+     * Target file path where variables should be imported
+     * @example 'ui/buttons.ts'
+     */
+    targetFile: string;
+    /**
+     * Map of variable names to import and their optional new names.
+     * If no new name is provided, the original name is used.
+     * @example { 'primaryButton': 'button', 'secondaryButton': 'secondary' }
+     */
+    variables: Record<string, string | undefined>;
+}
+/**
+ * Mapping for a specific package.
+ * Defines which files to import and how to map their variables.
+ */
+export interface PackageMapping {
+    /**
+     * Package name to match
+     * @example '@company/ui-components'
+     */
+    packageName: string;
+    /**
+     * Array of file mappings for this package
+     */
+    files: FileMapping[];
+}
+/**
+ * Options for the simple mapping import algorithm.
+ */
+export interface SimpleMappingImportAlgorithmOptions {
+    /**
+     * Array of package mappings defining how to import from each package
+     */
+    mappings: PackageMapping[];
+    /**
+     * Global config remapping function applied to all imported tags
+     */
+    configRemap?: (originalConfig: any, context: {
+        packageName: string;
+        sourceFile: string;
+        targetFile: string;
+        variableName: string;
+        originalVariableName: string;
+    }) => any | null;
+}
+/**
+ * Simple mapping import algorithm that provides straightforward control over
+ * how library translations are imported based on explicit package->file->variable mappings.
+ *
+ * This algorithm allows you to:
+ * - Specify exactly which packages to import from
+ * - Map specific files from packages to target files
+ * - Select which variables to import and optionally rename them
+ * - Skip packages/files/variables not explicitly mapped
+ *
+ * @param options - Configuration options for the simple mapping algorithm
+ * @returns A function compatible with LangTagCLIConfig.import.onImport
+ *
+ * @example
+ * ```typescript
+ * import { simpleMappingImportAlgorithm } from '@lang-tag/cli/algorithms';
+ *
+ * export default {
+ *   import: {
+ *     onImport: simpleMappingImportAlgorithm({
+ *       mappings: [
+ *         {
+ *           packageName: '@company/ui-components',
+ *           files: [
+ *             {
+ *               sourceFile: 'components/button.ts',
+ *               targetFile: 'ui/buttons.ts',
+ *               variables: {
+ *                 'primaryButton': 'button',
+ *                 'secondaryButton': 'secondary',
+ *                 'tertiaryButton': undefined // keep original name
+ *               }
+ *             },
+ *             {
+ *               sourceFile: 'components/input.ts',
+ *               targetFile: 'ui/inputs.ts',
+ *               variables: {
+ *                 'textInput': 'input',
+ *                 'passwordInput': 'password'
+ *               }
+ *             }
+ *           ]
+ *         },
+ *         {
+ *           packageName: '@company/utils',
+ *           files: [
+ *             {
+ *               sourceFile: 'helpers.ts',
+ *               targetFile: 'utils/helpers.ts',
+ *               variables: {
+ *                 'formatDate': undefined,
+ *                 'formatCurrency': 'currency'
+ *               }
+ *             }
+ *           ]
+ *         }
+ *       ]
+ *     })
+ *   }
+ * };
+ * ```
+ */
+export declare function simpleMappingImportAlgorithm(options: SimpleMappingImportAlgorithmOptions): (event: LangTagCLIImportEvent) => void;