i18ntk 1.5.2 → 1.6.0

package/README.md

@@ -1,225 +1,171 @@
-# 🌍 i18ntk - The Ultimate i18n Translation Management Toolkit
-
-![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG)
-
-**Version:** 1.5.2  
-**Last Updated:** 2025-08-06  
-**GitHub Repository:** [vladnoskv/i18ntk](https://github.com/vladnoskv/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/) [![Downloads](https://img.shields.io/npm/dm/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![GitHub stars](https://img.shields.io/github/stars/vladnoskv/i18ntk?style=social)](https://github.com/vladnoskv/i18ntk)
-
-**🚀 The fastest way to manage translations across any framework or vanilla JavaScript projects**
-
-**Framework Support:** Works **with or without** i18n frameworks. i18ntk manages translation files and validation - it does NOT implement translations on pages. Compatible with any frameworks using standard JSON translation files. 
-
-> **Zero dependencies** | **71% smaller package** | **Works with any framework** | **Enterprise-grade security**
-
-**Key Features of v1.5.2**
-- Further package optimizations reduced size from 536kB to under 500kB
-- Updated documentation to reflect more up to date and clear instructions
-- Added more detailed examples and use cases in the documentation.
-- Changed GitHub urls to `https://github.com/vladnoskv/i18ntk` for reporting a bug, and across documentation.
-- No core functionality was changed, minor changes and removal of legacy code.
-
-## 🚀 Quick Start
-
-```bash
-npm install -g i18ntk    # Install globally
-npx i18ntk --help        # Show help
-npx i18ntk --version     # Show version
-npx i18ntk               # Run Main Manage Menu
-npx i18ntk init          # Initialize project
-npx i18ntk manage        # Interactive Menu
-npx i18ntk analyze       # Analyze translations
-```
-
-📖 **Complete Setup Guide**: [docs/core/SETUP.md](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/SETUP.md)
-
-## ✨ Why Choose i18ntk?
-
-### 🎯 **Universal Compatibility**
-- **Works with any framework** - React, Vue, Angular, Svelte, or vanilla JavaScript
-- **Zero runtime dependencies** - Won't bloat your bundle
-- **Standard JSON format** - Compatible with i18next, LinguiJS, and more
-
-### ⚡ **Lightning Fast**
-- **71% package size reduction** - From 1.7MB to just 499kB (unpacked) and 100kB (packed)
-- **1,600-1,900 operations/second** - Benchmarked performance
-- **Instant startup** - No heavy dependencies to load
-
-### 🔐 **Enterprise Security**
-- **AES-256-GCM encryption** - Enterprise-grade PIN protection
-- **7-language support** - English, German, Spanish, French, Russian, Japanese, Chinese
-- **Session management** - Automatic timeouts and secure handling
-
-### 📊 **Professional Tools**
-- **Real-time analysis** - Detect missing translations instantly
-- **Interactive menus** - No complex configuration required
-- **CI/CD ready** - Pre-built workflows for GitHub Actions, GitLab CI
-- **Comprehensive reports** - JSON, compact, or human-readable formats
-
-## ✨ What's New in v1.5.1
-
-### 🆕 Framework Clarification & Documentation Overhaul
-- **Clear framework guidance** - Explicitly supports **with or without** i18n frameworks
-- **Streamlined README** - Concise overview with detailed docs linked to GitHub
-- **Updated GitHub URL** - New home at [vladnoskv/i18ntk](https://github.com/vladnoskv/i18ntk)
-- **Enhanced compatibility** - Works with i18next, LinguiJS, and vanilla JavaScript
-- **Translation file standardization** - Uses JSON format compatible with all major frameworks
-
-### 📊 Performance & Reliability
-- **Zero runtime dependencies** - Pure Node.js implementation
-- **71% package size reduction** - From 1.7MB to 499kB
-- **Verified benchmarks** - 1,600-1,900 operations/second across all scales
-
-
-## 🎯 Framework Integration
-
-Works with **any** framework or vanilla JavaScript. Uses standard JSON translation files compatible with:
-
-| Framework | Compatibility | Integration Time |
-|-----------|---------------|------------------|
-| **i18next** | ✅ Native | 2 minutes |
-| **LinguiJS** | ✅ JSON format | 2 minutes |
-| **React** | ✅ Standard imports | 3 minutes |
-| **Vue.js** | ✅ Standard imports | 3 minutes |
-| **Angular** | ✅ TypeScript ready | 4 minutes |
-| **Vanilla JS** | ✅ Direct usage | 1 minute |
-
-📖 **Integration Guide**: [docs/core/FRAMEWORK_INTEGRATION.md](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/FRAMEWORK_INTEGRATION.md)
-
-### 🔧 **Quick Integration Examples**
-
-**React Example:**
-```javascript
-// Before i18ntk
-import en from './locales/en.json'
-import es from './locales/es.json'
-
-// After i18ntk - automatically validated and optimized
-import translations from './locales' // i18ntk managed
-```
-
-**Vanilla JS Example:**
-```javascript
-// i18ntk validates and optimizes your JSON files
-const translations = await import(`./locales/${lang}.json`)
-```
-
-## 🔍 Troubleshooting & Support
-
-📖 **Troubleshooting Guide**: [docs/core/TROUBLESHOOTING.md](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/TROUBLESHOOTING.md)
-
-## 🔄 CI/CD Integration
-
-Pre-built workflows for GitHub Actions, GitLab CI, and Docker.
-
-📖 **CI/CD Guide**: [docs/development/CI_CD_INTEGRATION.md](https://github.com/vladnoskv/i18ntk/blob/main/docs/development/CI_CD_INTEGRATION.md)
-
-## 📊 Project Health Dashboard
-
-### Quick Health Check
-```bash
-# One-command health check
-i18ntk summary --format=json > health-report.json
-
-# Continuous monitoring
-watch -n 30 'i18ntk summary --format=compact'
-```
-
-### Key Metrics to Monitor
-- **Translation completeness**: Aim for 100% across all languages
-- **Missing keys**: Should be 0 in production
-- **Validation errors**: Must be 0 before deployment
-- **Performance**: <5 seconds for datasets <10K keys
-- **Memory usage**: Monitor for datasets >25K keys
-
-## 🎯 Best Practices
-
-### Development Workflow
-1. **Daily**: Run `i18ntk analyze` to catch missing keys early
-2. **Pre-commit**: Add validation hooks with `i18ntk validate`
-3. **Pre-release**: Generate comprehensive reports with `i18ntk summary`
-4. **CI/CD**: Include validation in your pipeline
-
-### Team Collaboration
-- **Shared configuration**: Commit `settings/i18ntk-config.json` to version control
-- **Language standards**: Define primary language for development
-- **Review process**: Include translation reviews in PR templates
-- **Documentation**: Maintain translation guidelines for your team
-
-### Performance Optimization
-- **Regular cleanup**: Remove unused translations monthly
-- **Modular structure**: Split large translation files by feature/domain
-- **Caching**: Implement caching for CI/CD environments
-- **Monitoring**: Set up alerts for translation completeness drops
-
-## 🚀 Get Started in 30 Seconds
-
-### **Step 1: Install**
-```bash
-npm install -g i18ntk
-```
-
-### **Step 2: Initialize**
-```bash
-npx i18ntk init
-```
-
-### **Step 3: Analyze**
-```bash
-npx i18ntk analyze
-```
-
-### **Step 4: Manage**
-```bash
-npx i18ntk manage
-```
-
----
-
-## ⚖️ Package Identity & Legal Notice
-
-### **📋 Package Attribution**
-- **Package Name**: `i18ntk` 
-- **Author**: Vladimir Noskov (@vladnoskv)
-- **Repository**: https://github.com/vladnoskv/i18ntk
-- **NPM Registry**: https://www.npmjs.com/package/i18ntk
-- **License**: MIT
-- **Current Version**: 1.5.2 (Released: August 6, 2025)
-
-### **🔍 Identity Disclaimer**
-
-This package (`i18ntk` by vladnoskv) is an **independent, standalone internationalization management toolkit** and is **not affiliated with, endorsed by, or connected to** any other packages, tools, or services using similar names.
-
-### **✅ Version Accuracy Guarantee**
-
-All version information is current as of **August 6, 2025**:
-- **Package Version**: 1.5.2
-- **Release Date**: 2025-08-06
-- **Node.js Compatibility**: >=16.0.0
-- **Zero Runtime Dependencies**: Verified ✓
-- **Package Size**: 499.0kB unpacked, 103.5kB packed
-
-## 📚 Documentation
-
-Complete documentation available at [vladnoskv/i18ntk](https://github.com/vladnoskv/i18ntk):
-
-- **[Setup Guide](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/SETUP.md)** - Getting started
-- **[CLI Commands](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/COMMANDS.md)** - Command reference
-- **[Framework Integration](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/FRAMEWORK_INTEGRATION.md)** - Framework setup
-- **[Language Support](https://github.com/vladnoskv/i18ntk/blob/main/docs/core/LANGUAGE_SUPPORT.md)** - Language setup
-- **[Changelog](https://github.com/vladnoskv/i18ntk/blob/main/CHANGELOG.md)** - Version history
-
----
-
-## ⭐ Trusted by Developers Worldwide
-
-**Join hundreds (soon thousands) of developers** who have streamlined their internationalization workflow with i18ntk.
-
-- ✅ **Zero configuration** - Works out of the box
-- ✅ **Production ready** - Battle-tested in enterprise environments  
-- ✅ **Active development** - Regular updates and improvements
-- ✅ **Community driven** - Built by developers, for developers
-
-### **Made with ❤️ for the developer community** P.S I'm looking for a JOB!
+# 🌍 i18ntk - The Ultimate i18n Translation Management Toolkit
+
+![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG)
+
+**Version:** 1.6.0  
+**Last Updated:** 2025-08-08  
+**GitHub Repository:** [vladnoskv/i18ntk](https://github.com/vladnoskv/i18ntk)
+
+[![npm](https://img.shields.io/npm/dt/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![npm version](https://badge.fury.io/js/i18ntk.svg)](https://badge.fury.io/js/i18ntk) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/) [![Downloads](https://img.shields.io/npm/dm/i18ntk.svg)](https://www.npmjs.com/package/i18ntk) [![GitHub stars](https://img.shields.io/github/stars/vladnoskv/i18ntk?style=social)](https://github.com/vladnoskv/i18ntk)
+
+**🚀 The fastest way to manage translations across any framework or vanilla JavaScript projects**
+
+**Framework Support:** Auto-detects popular libraries (React i18next, Vue i18n, i18next, Nuxt i18n, Svelte i18n) or works without a framework. i18ntk manages translation files and validation—it does NOT implement translations on pages.
+
+> **Zero dependencies** | **Optimized smaller package** | **Works with any framework** | **Enterprise-grade security**
+
+> **v1.6.0** - **Ultra-extreme performance improvements to the i18ntk toolkit with 97% speed improvement** ⚡ Under 30ms for 200k keys (vs 1.2 seconds), up to 86% package size reduction, zero runtime dependencies.
+
+## 🚀 Quick Start
+
+```bash
+# Install globally
+npm install -g i18ntk@1.6.0
+
+# Interactive setup
+npx i18ntk init
+
+# Basic commands
+i18ntk analyze --source ./src
+i18ntk complete --config=extreme
+i18ntk validate --source ./locales
+```
+
+## ⚡ Performance
+
+| Mode | Time (200k keys) | Memory | Package Size |
+|------|------------------|--------|--------------|
+| **Extreme** | **38.90ms** | 0.61MB | 115KB-830KB |
+| Ultra | 336.8ms | 0.64MB | Configurable |
+| Optimized | 847.9ms | 0.45MB | Full package |
+
+## 🎯 Key Features
+
+- **Ultra Performance**: 97% speed improvement with extreme optimization
+- **Smart Sizing**: Interactive locale optimizer (up to 86% size reduction)
+- **Enterprise Security**: Admin PIN protection & comprehensive validation
+- **Zero Dependencies**: Lightweight, production-ready
+- **7 Languages**: English, Spanish, French, German, Japanese, Russian, Chinese 
+- **Framework Support**: Auto-detects React i18next, Vue i18n, Angular, Next i18next, Nuxt i18n, Svelte i18n
+
+### 📸 Screenshots
+
+| **Logo & Branding** | **Framework Detection** |
+|:-------------------:|:----------------------:|
+| ![i18ntk Logo](docs/screenshots/i18ntk-logo-public.PNG) | ![Framework Check](docs/screenshots/i18ntk-check-framwork.PNG) |
+
+| **Management Interface** | **Initialization Menu** |
+|:------------------------:|:------------------------:|
+| ![i18ntk Management](docs/screenshots/i18ntk-manage-menu.PNG) | ![Init Menu](docs/screenshots/i18ntk-menu-init.PNG) |
+
+| **Language Selection** | **Language Change** |
+|:----------------------:|:-------------------:|
+| ![Language Selection](docs/screenshots/i18ntk-menu-init-language.PNG) | ![Language Change](docs/screenshots/i18ntk-menu-language-change.PNG) |
+
+## 📊 Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `init` | Setup project | `i18ntk init --interactive` |
+| `analyze` | Find missing translations | `i18ntk analyze --source ./src` |
+| `complete` | Generate translations | `i18ntk complete --config=extreme` |
+| `validate` | Check translation quality | `i18ntk validate --strict` |
+| `sync` | Sync across languages | `i18ntk sync --languages en,es,fr` |
+| `usage` | Analyze usage patterns | `i18ntk usage --format=json` |
+
+## 🔧 Configuration
+
+Create `.i18ntk.config.js`:
+
+```javascript
+module.exports = {
+    // All paths are relative to your project root
+  sourceDir: './locales',
+  outputDir: './i18ntk-reports',
+  defaultLanguage: 'en',
+  supportedLanguages: ['en', 'es', 'fr', 'de'],
+  performance: {
+    mode: 'extreme', // extreme | ultra | optimized
+    batchSize: 1000,
+    concurrency: 16
+  }
+};
+```
+
+## 🌍 Language Optimization
+
+```bash
+# Interactive locale selection
+node scripts/locale-optimizer.js --interactive
+
+# Keep specific languages
+node scripts/locale-optimizer.js --keep en,es,de
+
+# Restore all languages
+node scripts/locale-optimizer.js --restore
+
+# Check sizes
+node scripts/locale-optimizer.js --list
+```
+
+## 🏗️ Integration Examples
+
+### React
+```javascript
+// Extract from React components
+i18ntk extract --source ./src --framework react
+
+// Setup i18next
+import i18n from './i18n';
+i18next.init({ resources: i18n, lng: 'en' });
+```
+
+### Vue
+```javascript
+// Extract from Vue components  
+i18ntk extract --source ./src --framework vue
+
+// Setup vue-i18n
+import { createI18n } from 'vue-i18n';
+const i18n = createI18n({ locale: 'en', messages: translations });
+```
+
+
+## 🔒 Security Features
+
+- **Admin PIN Protection**: File role-based access control
+- **Input Sanitization**: Path traversal prevention
+- **File Validation**: Safe file operations
+- **Session Management**: Automatic timeout & cleanup
+
+## 📋 Project Structure
+
+```
+your-project/
+├── src/
+│   └── components/
+├── locales/           # Translation files
+│   ├── en.json
+│   ├── es.json
+│   └── ...
+├── i18ntk-reports/      # Generated reports
+└── .i18ntk.config.js  # Configuration
+```
+
+## 🚨 Important Notes
+
+- **Locale files are backed up automatically** before optimization
+- **Use interactive optimizer** for safe locale management
+- **Zero breaking changes** from v1.5.x to v1.6.0
+- **All improvements applied automatically** on update
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/vladnoskv/i18ntk/issues)
+- **Documentation**: [Complete docs](./docs)
+- **Performance**: [Benchmark results](./benchmarks/results)
+- **Version**: `i18ntk --version`
+
+---
+
+**Made for the global development community** ❤️