@lang-tag/cli 0.9.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TheTonsOfCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# Lang-tag: Component-Colocated Translation Management / Translation Engine Proxy
+
+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
+
+### Lightweight Core (~1KB)
+
+The core is optimized for performance, with a bundle size of just **~1KB** ([check on Bundlephobia](https://bundlephobia.com/package/lang-tag)). It provides essential TypeScript types and minimal utilities to help you build a custom `lang-tag` setup tailored to your project.
+
+- **Component-local translations** – define translations directly within components, avoiding scattered key structures
+- **Light structure, full control** – only the translation object shape is enforced; naming, config, functions, and libraries are all up to you
+- **Flexible library support** – integrate third-party packages effortlessly, with support for both classic mappings and fully customized `lang-tag` flows
+
+### Effortless translation structure
+
+Instead of manually managing centralized translation files, `lang-tag` lets you colocate keys within components and automatically organizes them into namespaces based on your project structure. For example, all components in `components/orders` or pages in `pages/order` share the `orders` namespace. You define a simple folder-to-namespace mapping once, and `lang-tag` handles merging and file organization—while you retain full control over how namespaces are merged. 
+
+> Set your rules, then let `lang-tag` do the rest.
+
+### Advanced CLI (zero bundle impact)
+
+Full functionality is available through an advanced CLI that keeps your application bundle size untouched:
+
+- **Automatic translation collection** – `lang-tag collect` scans your project for translation tags and aggregates them into organized JSON files (e.g., `public/locales/en/common.json`), based on your configuration
+- **Dynamic configuration updates** – `lang-tag regenerate-tags` automatically refreshes translation settings in your code, using rules defined in your configuration (e.g., mapping namespaces based on folder structure)
+- **Third-party translation import** – `lang-tag import` detects and integrates translations from external libraries, adapting them to your project’s translation system
+- **Watch mode** – `lang-tag watch` monitors your source files for changes and automatically re-collects/re-generates translations when needed
+
+### 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
+- **Flexible integration** - seamlessly integrates with existing i18n libraries (i18next, react-i18next) while maintaining your current translation workflow
+- **Automation-first** - comprehensive CLI tools for collection, import, regeneration, and watch modes to streamline the entire translation workflow
+
+## Core Concept
+
+`lang-tag` allows translation management by enabling component-colocated translation definitions. This approach eliminates the traditional complexity of managing distributed translation files and hierarchical key structures, allowing developers to define translations directly where they are consumed.
+
+### Component-Colocated Translation Pattern
+
+Instead of maintaining separate translation files and complex key mappings, translations are defined inline within components:
+
+```tsx
+// 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'
+    }
+}, {
+    namespace: 'orders',
+    path: 'components.checkout'
+});
+
+function CheckoutComponent({ name, count }) {
+    const t = translations.useT();
+    
+    return (
+        <div>
+            <h2>{t.greeting({ name })}</h2>
+            <p>{t.orderSummary({ count })}</p>
+            <div>
+                <button>{t.actions.proceed()}</button>
+                <button>{t.actions.cancel()}</button>
+            </div>
+        </div>
+    );
+}
+```
+
+### Automated Translation Workflow
+
+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
+
+### 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
+
+## Installation
+
+```bash
+npm install lang-tag
+# or
+yarn add lang-tag
+# or
+pnpm add lang-tag
+```
+
+## Documentation
+
+For detailed setup, usage, and advanced features, please refer to the documentation:
+
+- [Getting Started & Basic Usage](docs/getting-started.md)
+- [CLI Usage](docs/cli-usage.md)
+- [Advanced Features](docs/advanced-features.md)
+- [Integrations](docs/integrations.md)
+- [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)

package/cli/config.d.ts

@@ -0,0 +1,191 @@
+import { LangTagTranslationsConfig } from '../index.ts';
+import { LangTagCLILogger } from './logger.ts';
+export interface LangTagCLIConfig {
+    /**
+     * Tag name used to mark translations in code.
+     * @default 'lang'
+     */
+    tagName: string;
+    /**
+     * Glob patterns specifying directories/files to include when searching for translations.
+     * @default ['src/** /*.{js,ts,jsx,tsx}']
+     */
+    includes: string[];
+    /**
+     * Glob patterns specifying directories/files to exclude when searching for translations.
+     * @default ['node_modules', 'dist', 'build', '** /*.test.ts']
+     */
+    excludes: string[];
+    /**
+     * Output directory for generated translation namespace files (e.g., common.json, errors.json).
+     * @default 'locales/en'
+     */
+    outputDir: string;
+    collect?: {
+        /**
+         * @default 'common'
+         */
+        defaultNamespace?: string;
+        /**
+         * When true, conflicts are not reported when two translation tags have the same path but identical values.
+         * This is useful for shared translations that appear in multiple files with the same content.
+         * @default true
+         */
+        ignoreConflictsWithMatchingValues?: boolean;
+        /**
+         * A function called when the collected translation configuration needs to be fixed or validated.
+         * Allows modification of the configuration before it's saved to the output files.
+         */
+        onCollectConfigFix?: (event: LangTagCLICollectConfigFixEvent) => LangTagTranslationsConfig;
+        /**
+         * A function called when a single conflict is detected between translation tags.
+         * Allows custom resolution logic for handling individual conflicts.
+         * Return true to continue processing, false to stop execution.
+         */
+        onConflictResolution?: (event: LangTagCLIConflictResolutionEvent) => Promise<void>;
+        /**
+         * A function called after all conflicts have been collected and processed.
+         * Allows custom logic to decide whether to continue or stop based on all conflicts.
+         * Return true to continue processing, false to stop execution.
+         */
+        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.)
+     * based on the file path or other context.
+     * If it returns `undefined`, the tag's configuration is not automatically generated or updated.
+     */
+    onConfigGeneration: (params: LangTagCLIOnConfigGenerationParams) => LangTagTranslationsConfig | undefined;
+    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;
+}
+/**
+ * Parameters passed to the `onConfigGeneration` configuration function.
+ */
+export interface LangTagCLIOnConfigGenerationParams {
+    /** The absolute path to the source file being processed. */
+    fullPath: string;
+    /** The path of the source file relative to the project root (where the command was invoked). */
+    path: string;
+    /** True if the file being processed is located within the configured library import directory (`config.import.dir`). */
+    isImportedLibrary: boolean;
+    /** The configuration object extracted from the lang tag's options argument (e.g., `{ namespace: 'common', path: 'my.path' }`). */
+    config: LangTagTranslationsConfig;
+}
+type Validity = 'ok' | 'invalid-param-1' | 'invalid-param-2' | 'translations-not-found';
+export interface LangTagCLIProcessedTag {
+    fullMatch: string;
+    parameter1Text: string;
+    parameter2Text?: string;
+    parameterTranslations: any;
+    parameterConfig?: any;
+    variableName?: string;
+    /** Character index in the whole text where the match starts */
+    index: number;
+    /** Line number (1-based) where the match was found */
+    line: number;
+    /** Column number (1-based) where the match starts in the line */
+    column: number;
+    validity: Validity;
+}
+export interface LangTagCLITagConflictInfo {
+    tag: LangTagCLIProcessedTag;
+    relativeFilePath: string;
+    value: any;
+}
+export interface LangTagCLIConflict {
+    path: string;
+    tagA: LangTagCLITagConflictInfo;
+    tagB: LangTagCLITagConflictInfo;
+    conflictType: 'path_overwrite' | 'type_mismatch';
+}
+export interface LangTagCLICollectConfigFixEvent {
+    config: LangTagTranslationsConfig;
+    langTagConfig: LangTagCLIConfig;
+}
+export interface LangTagCLIConflictResolutionEvent {
+    conflict: LangTagCLIConflict;
+    logger: LangTagCLILogger;
+    /** Breaks translation collection process */
+    exit(): void;
+}
+export interface LangTagCLICollectFinishEvent {
+    conflicts: LangTagCLIConflict[];
+    logger: LangTagCLILogger;
+    /** Breaks translation collection process */
+    exit(): void;
+}
+export declare const LANG_TAG_DEFAULT_CONFIG: LangTagCLIConfig;
+export {};