i18ntk 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,11 +1,57 @@
 # Changelog
 
-All notable changes to the I18N Management Toolkit are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-**Current Version:** 1.2.2 (2025-08-02) - **CRITICAL BUG FIX FOR CUSTOM LOCALE SUPPORT** 🚨
+**Current Version:** 1.3.0 (2025-08-02) - **SCRIPT DIRECTORY CONFIGURATION & PATH RESOLUTION FIXES** 🚀
+
+### 🆕 New Features
+- **Per-Script Directory Configuration**: Added support for custom directory overrides for each script type (analyze, complete, init, manage, sizing, summary, usage, validate)
+- **Enhanced Path Guidance**: Added current working directory display and relative path examples in CLI prompts
+- **Improved Internationalization**: Added comprehensive translation keys for all new configuration options
+
+### 🐛 Bug Fixes
+- **Fixed Path Resolution**: Corrected directory path resolution to properly use relative paths from project root instead of script directory
+- **Fixed Settings Loading**: Scripts now correctly follow configured directory settings instead of defaulting to hardcoded paths
+- **Translation Key Completeness**: Added missing translation keys for new configuration options
+
+### 📁 Configuration Improvements
+- **Custom Script Directories**: Each script can now have its own source directory configured independently
+- **Settings CLI Enhancement**: Added new menu option for configuring script-specific directories
+- **Backward Compatibility**: All existing configurations continue to work without changes
+
+### ⚠️ Deployment Notes
+- **Testing Recommended**: Test on a development branch before deploying to production
+- **No Breaking Changes**: Existing configurations remain compatible
+- **Path Resolution**: Relative paths now resolve correctly from project root directory
+
+**Previous Version:** 1.2.3 (2025-08-02) - **KEY USAGE & UPDATE FEATURE**
+
+## [1.2.3] - 2025-08-02
+**⚠️ DEPRECATED:**
+### 🚀 New Features
+- **Added**: Update package feature to settings CLI for easy `npm update i18ntk`
+- **Enhanced**: Key usage checking now correctly scans directories based on settings
+- **Improved**: Complete coverage scanning ensures all relevant files are processed
+
+### 🐛 Bug Fixes
+- **Fixed**: Key usage and complete coverage tools now respect configured `sourceDir` and `i18nDir`
+- **Fixed**: Removed any potential hardcoded directory paths in key scanning logic
+
+### 🔧 Technical Details
+- **Issue**: Key usage and complete coverage tools were not always respecting user-defined directory settings.
+- **Root Cause**: Inconsistent directory resolution logic in `i18ntk-usage.js` and `i18ntk-complete.js`.
+- **Resolution**: Ensured both tools consistently retrieve `sourceDir` and `i18nDir` from `settingsManager.getSettings()`.
+- **Impact**: Accurate key usage analysis and complete translation coverage based on user configuration.
 
 ## [1.2.2] - 2025-08-02
 
+**⚠️ DEPRECATED:** This version contains a critical bug affecting custom locale directory configuration. Please upgrade to v1.2.3 immediately.
+
+### 🚨 Critical Bug Fix
+- **Fixed**: Resolved `settingsManager.setDirectories is not a function` error when adding custom locale support
+- **Fixed**: Corrected settings management to use proper `getSettings()` and `saveSettings()` methods instead of non-existent `setDirectories()`
+- **Enhanced**: Improved stability when configuring custom translation directories
+- **Fixed**: Directory configuration now properly persists across sessions
+
 ### 🚨 Critical Bug Fix
 - **Fixed**: Resolved `settingsManager.setDirectories is not a function` error when adding custom locale support
 - **Fixed**: Corrected settings management to use proper `getSettings()` and `saveSettings()` methods instead of non-existent `setDirectories()`

package/LICENSE

@@ -18,4 +18,6 @@ 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.
+SOFTWARE.
+
+Last Updated: 02/08/2025

package/README.md

@@ -1,21 +1,27 @@
-# i18ntk - Enterprise i18n Management Toolkit
-
-**Version:** 1.2 – **PRODUCTION READY** with enhanced documentation and npm metadata cleanup! 🌍
-
-**⚠️ Important Notice:** All previous versions (< 1.2) are now deprecated due to critical bugs and issues. Please upgrade to v1.1.5 for the most stable experience. We recommend backing up your project before upgrading. 
-
-**🎉 Thank You:** 200+ downloads in the first week! Thank you for your support and patience as we resolved the functional issues. My First Published Project. 
+# i18ntk -  i18n Management Toolkit
 
 [![version](https://badge.fury.io/js/i18ntk.svg)](https://badge.fury.io/js/i18ntk)
 [![npm](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/)
 
-**i18ntk** (i18n Toolkit) is a comprehensive, internationalization management toolkit for JavaScript/TypeScript projects. It provides a complete CLI suite with multi-language support and advanced analysis capabilities for managing translations efficiently.
+**Version:** 1.3.0 – **i18ntk** (i18n Toolkit) is a comprehensive, internationalization management toolkit for JavaScript/TypeScript projects. It provides a complete CLI suite with multi-language support and advanced analysis capabilities for managing translations efficiently.
+
+## 🔧 Key Features
+
+- **Flexible Configuration**: Customize script directories and file formats in `settings.json`
+- **Path Resolution**: Automatically resolves relative paths based on project structure
+- **Comprehensive Commands**: Includes analyze, complete, manage, validate, and more
+- **Multi-Language Support**: UI available in 7 languages with partial internationalization
+- **Production-Ready**: Tested extensively in various environments
+
+**⚠️ Important Notice:** All previous versions (< 1.3.0) are now deprecated due to critical bugs and issues. Please upgrade to v1.3.0 for the most stable experience. We recommend backing up your project before upgrading and testing on a development branch first. 
+
+**🎉 Thank You:** 500+ downloads in the first week! Thank you for your support and patience as I resolve the functional issues. My First Published Package, please update to the latest version as any previous bugs were probably fixed. 
 
 ## ⚠️ Important Disclaimer
 
-**Important: This is an independent, community-driven toolkit** - not affiliated with any official i18n organization or team. Originally developed as a personal solution for translation management, i18ntk has evolved into a feature-rich internationalization toolkit available to the broader development community. The toolkit is designed to be framework-agnostic and highly adaptable:
+**Important: This is an independent, community-driven toolkit** generated with the help of AI tools therefore, bugs and errors are prone to happen, please report an issue if you find one. Also, this package is not affiliated with any official i18n organization or team. Originally developed as a personal solution for my own translation management, i18ntk has evolved into a feature-rich internationalization toolkit available to the broader development community. The toolkit is designed to be framework-agnostic and highly adaptable:
 
 - Works with any translation file format configured in the settings
 - Operates independently (no i18n framework required)
@@ -23,7 +29,8 @@
 - Easily extensible through code modifications or AI-assisted configuration
 - Flexible enough to accommodate diverse project requirements
 
-While maintaining its independence, i18ntk strives to follow i18n best practices and standards to ensure compatibility with existing workflows. Although we test thoroughly, we cannot guarantee 100% compatibility with all i18n frameworks or systems. Users are encouraged to test i18ntk with their specific setup and adjust settings as needed or find an alternative solution.
+While maintaining its independence, i18ntk strives to follow i18n best practices and standards to ensure compatibility with existing workflows. Although we test thoroughly, we cannot guarantee 100% compatibility with all i18n frameworks or systems and don't accept liability if there are any issues, we recommend running this toolkit on a fresh project. Users are encouraged to test i18ntk with their specific setup and adjust settings as needed or find an alternative solution. Thank you for trying i18ntk, if you have any issues or suggestions, please feel free to open an issue on the GitHub repository!
+
 
 ## 🚀 Quick Start
 
@@ -79,23 +86,36 @@ npx i18ntk --version  # 📋 Show detailed version information
 npx i18ntk -v         # 📋 Show detailed version information (short flag)
 ```
 
-**Note:** v1.1.4 is production-ready with full core functionality. Console UI translation support is at approximately 95% with English fallback for missing keys. Core features work flawlessly - only translation completion remains.
-
 **Important:** Direct command execution (e.g., `npx i18ntk usage`) now bypasses the interactive menu, allowing for more streamlined workflows and scripting.
 
-## ✨ What's New in v1.1.5
+## ✨ What's New in v1.3.0
 
-### 🧹 Documentation & Metadata Cleanup
-- **Enhanced**: Updated all documentation to reflect current version and best practices
-- **Improved**: Cleaned up npm package metadata for better clarity
-- **Fixed**: Repository URLs and homepage links in package configuration
-- **Updated**: Installation instructions and version references throughout documentation
+### 🆕 Script Directory Configuration
+- **New**: Added per-script directory configuration support for maximum flexibility
+- **Fixed**: Path resolution now correctly uses relative paths from project root
+- **Enhanced**: Added comprehensive internationalization for all new configuration options
+- **Improved**: Settings CLI now includes script directory configuration menu
+- **Added**: Current working directory display and path guidance in CLI prompts
 
 ### 🐛 Previous Version Deprecation
-- **Status**: All versions < 1.1.5 are now deprecated due to critical bugs
-- **Recommendation**: Immediate upgrade to v1.1.5 for stable functionality
+- **Status**: All versions < 1.3.0 are now deprecated due to critical bugs
+- **Recommendation**: Immediate upgrade to v1.3.0 for stable functionality
 - **Migration**: Major-breaking-changes upgrading from any 1.0.x version. Uninstall, and reinstall and rerun initilization.
 
+### ⬆️ Update Package Functionality
+- **New Feature**: Added `Update Package` option to the settings CLI for easy `npm update i18ntk` execution.
+- **Convenience**: Simplifies keeping the toolkit up-to-date directly from the interactive menu.
+
+### 🔍 Enhanced Directory Handling
+- **Improvement**: All scripts now correctly scan directories based on settings configurations
+- **Accuracy**: Path resolution fixed to respect relative paths from project root
+- **Bug Fix**: Resolved "Source directory not found" errors with proper path handling
+
+### 🎯 Improved Complete Coverage Scanning
+- **Enhancement**: Complete coverage scanning now accurately handles directory configurations.
+- **Reliability**: Ensures all relevant files are scanned for comprehensive analysis.
+- **Consistency**: Aligns with `i18ntk-usage.js` in respecting `sourceDir` and `i18nDir` settings.
+
 ### 📁 Enhanced Project Organization
 - **Improved**: Configuration files now properly organized in `settings/` directory
 - **Enhanced**: All reports centralized in `i18ntk-reports/` directory for better organization
@@ -103,7 +123,7 @@ npx i18ntk -v         # 📋 Show detailed version information (short flag)
 - **Updated**: Documentation reflects new file structure and locations
 
 ### 🎉 Community Milestone
-- **Achievement**: 200+ downloads in the first week
+- **Achievement**: 500+ downloads in the first week
 - **Gratitude**: Thank you for your patience as we resolved functional issues
 - **Commitment**: Continued focus on stability and user experience
 
@@ -113,6 +133,8 @@ npx i18ntk -v         # 📋 Show detailed version information (short flag)
 
 **🏠 [Documentation Index](./docs/INDEX.md)** - Quick navigation to all documentation
 
+**📁 [Script Directory Guide](./docs/SCRIPT_DIRECTORY_GUIDE.md)** - Configure custom directories for each script type (v1.3.0+)
+
 **📊 [Translation Status](./docs/TRANSLATION_STATUS.md)** - Current translation completion status
 
 **🔧 [API Reference](./docs/api/API_REFERENCE.md)** - Complete API documentation
@@ -146,25 +168,6 @@ npx i18ntk -v         # 📋 Show detailed version information (short flag)
 
 > **📖 For detailed setup and usage instructions, see [Documentation](./docs/README.md)**
 
-## 🛠️ Core Commands
-
-### NPM Scripts (Recommended)
-
-| Command | Description | Direct Usage |
-|---------|-------------|-------------|
-| `npm run i18ntk` | Interactive management interface | `node main/i18ntk-manage.js` |
-| `npm run i18ntk:autorun` | Automated complete workflow | `node main/i18ntk-autorun.js` |
-| `npm run i18ntk:init` | Initialize i18n configuration | `node main/i18ntk-init.js` |
-| `npm run i18ntk:analyze` | Analyze translation completeness | `node main/i18ntk-analyze.js` |
-| `npm run i18ntk:validate` | Validate translation integrity | `node main/i18ntk-validate.js` |
-| `npm run i18ntk:complete` | Complete missing translations | `node main/i18ntk-complete.js` |
-| `npm run i18ntk:usage` | Analyze translation key usage | `node main/i18ntk-usage.js` |
-| `npm run i18ntk:sizing` | Generate sizing reports | `node main/i18ntk-sizing.js` |
-| `npm run i18ntk:summary` | Generate summary reports | `node main/i18ntk-summary.js` |
-| `npm run i18ntk:debug` | Debug and diagnostics | `node dev/debug/debugger.js` |
-
-> **📖 For complete command reference, see [API Documentation](./docs/api/API_REFERENCE.md)**
-
 ## 📊 Reports and Analysis
 
 The toolkit generates comprehensive reports in the `i18ntk-reports/` directory:
@@ -187,11 +190,6 @@ Requests for additional languages are welcome!
 
 ## 🧪 Development and Testing
 
-### Debug Tools
-```bash
-# Main debug interface
-npm run i18ntk:debug
-
 > **📖 For comprehensive debug tools documentation, see [Debug Tools](./docs/debug/DEBUG_TOOLS.md)**
 
 
@@ -220,7 +218,10 @@ npm run i18ntk:debug
 
 ---
 
-**Version:** 1.2.2 – Critical bug fix for custom locale support! 🎯
+**Version:** 1.3.0  
+**Release Date:** 02/08/2025  
+**Previous Versions:** 1.2.x, 1.1.x, 1.0.x series 
+
 ## 📄 License
 
 This project is licensed under the MIT License - see the `LICENSE` file for details.

package/docs/README.md

@@ -1,6 +1,6 @@
 # I18N Management Toolkit - Documentation Hub
 
-**Version:** 1.1.5  
+**Version:** 1.3.0  
 **Last Updated:** August 2, 2025  
 **Maintainer:** Vladimir Noskov  
 
@@ -8,12 +8,32 @@
 
 **This is NOT an official i18n team product or affiliated with any i18n organization.** This toolkit was originally created as a personal project to help manage my own translation files, which was then enhanced with additional features, internationalization support, and made available to the community. It should work with any `en.json` translation files, even without i18n installed, and includes custom logic and settings that can be customized to fit your specific project needs. With simple code modifications or AI-assisted edits, you can easily adapt it to your project's requirements.
 
+## 🆕 What's New in v1.3.0
+
+### Major Features
+- **🎯 Per-Script Directory Configuration** - Configure custom directories for each script type
+- **🔧 Fixed Path Resolution** - Analyzing logic now correctly follows settings
+- **🌍 Enhanced Internationalization** - Continued support for global applications
+- **⚙️ Custom Directory Overrides** - Override any script directory via CLI arguments
+- **📋 Improved Settings CLI** - Enhanced configuration management
+
+### Key Benefits
+- **Flexibility**: Use different directory structures for different script types
+- **Reliability**: Path resolution now works correctly with relative paths
+- **Backward Compatibility**: Existing configurations continue to work
+- **Migration Support**: Easy upgrade path from v1.2.x
+
+📖 **[See Script Directory Guide](./SCRIPT_DIRECTORY_GUIDE.md)** for detailed configuration instructions.
+
 ## 📚 Welcome to the Documentation Hub
 
 This is your central hub for all I18N Management Toolkit documentation. Whether you're just getting started or looking for advanced configuration options, you'll find everything you need here.
 
 ## 🚀 Quick Start
 
+### ⚠️ Deployment Warning
+**We do not recommend using on a deployment server without testing on a branch first to see the file changes and process.** Always test v1.3.0 configuration changes in a development environment before production deployment.
+
 ### New to i18ntk?
 Start with these essential documents:
 
@@ -92,11 +112,12 @@ docs/reports/
 
 ## 🎯 Common Use Cases
 
-### 🆕 Setting Up a New Project
+### 🆕 Setting Up a New Project (v1.3.0)
 1. **[Installation Guide](../INSTALLATION.md)** - Install i18ntk locally (recommended) or globally
-2. **[Initialization](./api/API_REFERENCE.md#i18ntk-init)** - Set up i18n structure (`npx i18ntk init`)
-3. **[Configuration](./api/CONFIGURATION.md#primary-configuration-files)** - Configure for your framework
-4. **[First Analysis](./api/API_REFERENCE.md#i18ntk-analyze)** - Analyze your translations (`npx i18ntk analyze`)
+2. **[Script Directory Guide](./SCRIPT_DIRECTORY_GUIDE.md)** - Configure custom directories for each script type
+3. **[Initialization](./api/API_REFERENCE.md#i18ntk-init)** - Set up i18n structure (`npx i18ntk init`)
+4. **[Configuration](./api/CONFIGURATION.md#primary-configuration-files)** - Configure for your framework
+5. **[First Analysis](./api/API_REFERENCE.md#i18ntk-analyze)** - Analyze your translations (`npx i18ntk analyze`)
 
 ### 🔍 Analyzing Existing Projects
 1. **[Usage Analysis](./api/API_REFERENCE.md#i18ntk-usage)** - Find unused/missing keys (`npx i18ntk usage`)
@@ -110,11 +131,12 @@ docs/reports/
 3. **[Debug Tools](./debug/DEBUG_TOOLS.md)** - Troubleshoot issues
 4. **[Quality Assurance](../README.md#-quality-assurance)** - Ensure 100% coverage
 
-### 🚀 Production Deployment
-1. **[Final Validation](./api/API_REFERENCE.md#i18ntk-validate)** - Pre-deployment checks (`npx i18ntk validate`)
-2. **[Performance Analysis](./api/API_REFERENCE.md#i18ntk-sizing)** - Optimize bundle size (`npx i18ntk sizing`)
-3. **[Testing](../README.md#-testing)** - Run comprehensive tests
-4. **[Documentation](./api/CONFIGURATION.md)** - Document your setup
+### 🚀 Production Deployment (v1.3.0)
+1. **[Script Directory Guide](./SCRIPT_DIRECTORY_GUIDE.md)** - Configure production directory paths
+2. **[Testing on Branch](./SCRIPT_DIRECTORY_GUIDE.md#testing-your-configuration)** - Test configuration on development branch
+3. **[Final Validation](./api/API_REFERENCE.md#i18ntk-validate)** - Pre-deployment checks (`npx i18ntk validate`)
+4. **[Performance Analysis](./api/API_REFERENCE.md#i18ntk-sizing)** - Optimize bundle size (`npx i18ntk sizing`)
+5. **[Deployment Verification](./SCRIPT_DIRECTORY_GUIDE.md#migration-guide)** - Verify all scripts work correctly
 
 ## 🌍 Language Support
 
@@ -182,14 +204,14 @@ For enterprise support, custom integrations, or consulting services, please cont
 ## 🔄 Version History
 
 ### Recent Releases
-- **[v1.1.5](../CHANGELOG.md)** - Documentation & Metadata Cleanup (Current)
-- **[v1.1.4](../CHANGELOG.md)** - Internationalization Completion **(DEPRECATED)**
-- **[v1.1.3](../CHANGELOG.md)** - Translation System Enhancement **(DEPRECATED)**
-- **[v1.1.2](../CHANGELOG.md)** - Enhanced CLI Experience **(DEPRECATED)**
-- **[v1.1.1](../CHANGELOG.md)** - Interactive Menu & Locale Fixes **(DEPRECATED)**
-- **[v1.1.0](../CHANGELOG.md)** - Enhanced CLI & Non-Interactive Mode **(DEPRECATED)**
-
-**⚠️ Note:** All versions < 1.1.5 are deprecated. Please upgrade immediately.
+- **[v1.3.0](../CHANGELOG.md)** - Script Directory Configuration & Path Resolution Fixes (Current)
+- **[v1.2.3](../CHANGELOG.md)** - Documentation & Metadata Cleanup **(DEPRECATED)**
+- **[v1.1.5](../CHANGELOG.md)** - Internationalization Completion **(DEPRECATED)**
+- **[v1.1.4](../CHANGELOG.md)** - Translation System Enhancement **(DEPRECATED)**
+- **[v1.1.3](../CHANGELOG.md)** - Enhanced CLI Experience **(DEPRECATED)**
+- **[v1.1.2](../CHANGELOG.md)** - Interactive Menu & Locale Fixes **(DEPRECATED)**
+
+**⚠️ Note:** All versions < 1.3.0 are deprecated. Please upgrade immediately.
 
 ### Migration Guides
 - **[Upgrading to v1.0.0](../RELEASE_NOTES_v1.0.0.md#-migration-guide)** - Seamless upgrade from dev versions

package/docs/SCRIPT_DIRECTORY_GUIDE.md

@@ -0,0 +1,224 @@
+# Script Directory Configuration Guide
+
+## Overview
+
+Starting with **i18ntk v1.3.0**, we've introduced powerful new features for managing script directories and fixed critical path resolution issues. This guide explains how to configure custom directories for each script type and take advantage of the improved path handling.
+
+## 🆕 New Features in v1.3.0
+
+### 1. Per-Script Directory Configuration
+
+Each script type can now have its own source directory configured independently. This allows for maximum flexibility in organizing your i18n files.
+
+#### Supported Script Types
+- **analyze** - Translation analysis reports
+- **complete** - Translation completion tool
+- **init** - Project initialization
+- **manage** - Main management interface
+- **sizing** - Translation sizing analysis
+- **summary** - Summary reports
+- **usage** - Usage analysis
+- **validate** - Validation checks
+
+### 2. Fixed Path Resolution
+
+We've corrected how relative paths are resolved to ensure they always work from your project root directory, eliminating the "Source directory not found" errors.
+
+## Configuration Methods
+
+### Method 1: Settings CLI (Recommended)
+
+```bash
+# Launch the interactive settings manager
+node main/i18ntk-manage.js --command=settings
+
+# Or directly
+node settings/settings-cli.js
+```
+
+Navigate to **"Script Directory Configuration"** to configure individual directories for each script type.
+
+### Method 2: Manual Configuration
+
+Edit your settings file (`settings/settings.json`) to add custom directory configurations:
+
+```json
+{
+  "scriptDirectories": {
+    "analyze": "./src/i18n/locales",
+    "complete": "./translations",
+    "init": "./locales",
+    "manage": "./i18n/locales",
+    "sizing": "./src/i18n/sizing",
+    "summary": "./reports/i18n",
+    "usage": "./src/i18n/usage",
+    "validate": "./src/i18n/locales"
+  },
+  "sourceDir": "./locales"
+}
+```
+
+### Method 3: CLI Arguments
+
+Use command-line arguments to override directories for specific runs:
+
+```bash
+# Override source directory for analyze
+node main/i18ntk-analyze.js --source-dir=./src/i18n/locales
+
+# Override for complete
+node main/i18ntk-complete.js --source-dir=./translations
+```
+
+## Path Resolution Priority
+
+The toolkit uses the following priority order for determining source directories:
+
+1. **CLI Arguments** (`--source-dir`) - Highest priority
+2. **Script-Specific Configuration** (`scriptDirectories.<script>`)
+3. **Global Configuration** (`sourceDir`)
+4. **Default Directory** (`./locales`) - Lowest priority
+
+## Usage Examples
+
+### Example 1: Multi-Directory Setup
+
+Organize your i18n files across multiple directories:
+
+```
+project/
+├── src/
+│   └── i18n/
+│       ├── locales/          # Main translations
+│       ├── admin-locales/   # Admin interface translations
+│       └── public-locales/  # Public-facing translations
+├── legacy/
+│   └── translations/        # Legacy translation files
+└── settings/
+    └── settings.json
+```
+
+Configuration:
+
+```json
+{
+  "scriptDirectories": {
+    "analyze": "./src/i18n/locales",
+    "complete": "./legacy/translations",
+    "manage": "./src/i18n/admin-locales"
+  }
+}
+```
+
+### Example 2: Development vs Production
+
+Use different directories for development and production:
+
+```json
+{
+  "scriptDirectories": {
+    "analyze": "./src/i18n/dev-locales",
+    "validate": "./src/i18n/prod-locales"
+  }
+}
+```
+
+## Path Guidance Features
+
+### Current Working Directory Display
+
+The settings CLI now displays your current working directory and provides helpful hints:
+
+```
+📁 Current directory: /home/user/myproject
+💡 Tip: Use relative paths like "./src/i18n/locales" or "../translations"
+```
+
+### Relative Path Examples
+
+- ✅ `./src/i18n/locales` - Relative to project root
+- ✅ `../translations` - Relative to parent directory
+- ✅ `/absolute/path/to/locales` - Absolute path
+- ❌ `src/i18n/locales` - Missing `./` prefix (may cause issues)
+
+## Migration Guide
+
+### From v1.2.x to v1.3.0
+
+1. **No Breaking Changes**: Your existing configurations will continue to work
+2. **Optional Upgrade**: The new features are opt-in
+3. **Path Resolution**: Existing relative paths will now work correctly
+
+### Testing Your Configuration
+
+Before deploying to production, test your configuration:
+
+```bash
+# Test with a specific directory
+node main/i18ntk-analyze.js --source-dir=./test-locales --dry-run
+
+# Verify all scripts work with your new configuration
+npm run i18ntk:settings
+```
+
+## Internationalization Support
+
+All new configuration options are fully internationalized with support for:
+- English (en)
+- German (de)
+- Spanish (es)
+- French (fr)
+- Portuguese (pt)
+- Russian (ru)
+- Japanese (ja)
+- Chinese (zh)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Source directory not found"**
+   - Ensure the directory exists
+   - Use relative paths from project root
+   - Check file permissions
+
+2. **Settings not applied**
+   - Verify `scriptDirectories` configuration in settings.json
+   - Check for syntax errors in JSON
+   - Ensure settings file is in the correct location
+
+3. **CLI arguments not working**
+   - Use the correct argument format: `--source-dir=./path`
+   - Ensure no spaces around the equals sign
+
+### Debug Commands
+
+```bash
+# Check current settings
+node settings/settings-cli.js --show
+
+# Test path resolution
+node main/i18ntk-analyze.js --source-dir=./test-path --dry-run
+
+# Validate configuration
+node main/i18ntk-validate.js --config-only
+```
+
+## Best Practices
+
+1. **Use Relative Paths**: Always use relative paths from project root for portability
+2. **Test Before Deploying**: Always test directory configurations on a development branch
+3. **Document Your Setup**: Keep a record of your directory structure and configurations
+4. **Use Version Control**: Commit your settings.json to version control for team consistency
+5. **Backup Settings**: Create backups before making significant configuration changes
+
+## Support
+
+For issues or questions:
+- Check the [troubleshooting section](#troubleshooting)
+- Review the [CHANGELOG.md](../CHANGELOG.md)
+- Open an issue on [GitHub](https://github.com/vladnoskv/i18n-management-toolkit-main/issues)
+
+---
+
+*This guide is part of i18ntk v1.3.0. For previous versions, see the [documentation](../docs/).*