fs-fe-utils

A comprehensive Node.js utility toolkit for frontend development activities, specializing in advanced translation management, delta verification, path mapping, and YAML/JSON processing with git integration.

Installation

Global Installation (Recommended)

npm install -g fs-fe-utils

Local Installation

npm install fs-fe-utils
npx fs-fe-utils --help

Development Setup

git clone <repository-url>
cd fs-fe-utils
npm install
npm link  # Makes the command available globally during development

Features Overview

• 🔍 Delta Verification: Verify translation deltas against target files with type checking and git blame integration
• 🗺️ Path Mapping: Restructure translation keys with safe, non-destructive operations including deletion support
• 📊 Delta Extraction: Compare translation files between git branches and extract differences
• 🔄 Translation Merging: Merge translation delta files into target language directories with YAML/JSON support
• 📝 YAML Document Processing: Advanced YAML handling with formatting preservation and duplicate key support
• 🚀 Interactive CLI: User-friendly prompts with validation and smart defaults
• ⚡ Git Integration: Seamless branch comparison and blame information
• 🛡️ Safe Operations: Non-destructive file operations with backup and validation

Command Structure

fs-fe-utils trans <command> [options]

Available Commands

• verify-delta - Verify delta files against target language files
• map-paths - Apply path mappings to restructure translation keys
• extract-delta - Extract differences between git branches
• extract-delta-by-file - Extract differences between two specific files
• i18n-merge - Merge translation deltas into target directories
• serve-ui - Start web interface for all utilities

🔍 Delta Verification (verify-delta)

Verify delta files against target language files for key existence, type compatibility, and structural integrity.

Usage

fs-fe-utils trans verify-delta [deltaFilePath] [options]

Features

• Type Mismatch Detection: Identifies incompatible types between delta and target
• Missing Key Analysis: Reports missing keys with leaf-level categorization
• Git Blame Integration: Shows who last modified conflicting keys
• Root Key Handling: Option to ignore language root keys (e.g., "en" vs "fr")
• Interactive Prompts: Smart file detection and user confirmation
• Report Generation: Creates detailed missing keys reports for path mapping

Options

• [deltaFilePath] - Path to delta file (optional, will prompt if not provided)
• -b, --base-file <path> - Base/target file path to verify against
• -s, --source <path> - Source directory (default: current directory)
• -d, --delta <path> - Translation delta file path
• -t, --target-lang <language> - Target language to verify against (default: en)
• -r, --report-missing - Generate missing keys report file for path mapping
• --ignore-root-key - Ignore root language keys during verification
• --report-type <type> - Report type: leaf, all, or both (default: leaf)
• --include-mismatches-delete - Mark type mismatches for deletion in report

Examples

Basic Verification with Explicit Files

fs-fe-utils trans verify-delta translations-delta.yml --base-file en.json

With Missing Keys Report

fs-fe-utils trans verify-delta delta.json --base-file en.yml --report-missing

Interactive Mode (Auto-Detection)

fs-fe-utils trans verify-delta
# Will prompt for delta file and target file paths
# Asks about root key handling preference

Full Command with All Options

fs-fe-utils trans verify-delta -d delta.json -b en.yml -r --ignore-root-key --report-type leaf --include-mismatches-delete

Non-Interactive Mode (for Automation)

fs-fe-utils trans verify-delta delta.json --base-file en.yml --report-missing --report-type all

Report Features

• Type Mismatches: Automatically marked for deletion when structure conflicts detected
• Missing Keys: Separated by leaf-level (translation needed) vs structural keys
• Ready-to-use Commands: Copy-paste terminal commands for path mapping
• Smart Categorization: Groups missing keys by structure for better organization

Sample Output

📊 Delta Verification Report
================================

✅ Total matched keys: 45
⚠️  Total missing keys: 12 (8 leaf-level keys)
❌ Total type mismatches: 3

📋 Translation work needed: 8 leaf-level keys require translation

📄 Missing keys report generated: missing-keys-report-2024-01-15T10-30-45.txt

📋 Ready-to-use command (copy and paste):
   fs-fe-utils trans map-paths "missing-keys-report-2024-01-15T10-30-45.txt"

🗺️ Path Mapping (map-paths)

Apply path mappings to restructure translation keys safely across multiple language files.

Usage

fs-fe-utils trans map-paths [mappingFile] [options]

Features

• Safe Operations: Creates new output directories, preserves originals
• DELETE Support: Mark keys for deletion to clean up deprecated translations
• Root Key Intelligence: Handles language root keys automatically
• Multi-format Support: Works with JSON and YAML files
• Batch Processing: Applies mappings to all language files simultaneously
• Detailed Logging: Shows exactly what changes are applied to each file

Options

• [mappingFile] - Path to mapping file (optional, will prompt if not provided)
• -m, --mapping <file> - Mapping file path (alternative to positional argument)
• -s, --source <path> - Source directory containing translation files
• -o, --output <path> - Output directory for mapped files

Mapping File Format

# Format: actualpath:newpath
user.name:profile.fullName
user.email:profile.contactEmail
settings.theme:preferences.colorScheme
deprecated.oldKey:DELETE
temp.data:

Special Operations

• RENAME/MOVE: user.name:profile.fullName - Moves key to new location
• DELETE: deprecated.key:DELETE - Removes key from all language files
• SKIP: temp.data: - Ignores key (empty mapping)

Examples

Basic Path Mapping

fs-fe-utils trans map-paths mappings.txt

With Custom Paths

fs-fe-utils trans map-paths -m mappings.txt -s ./locales -o ./locales-restructured

Generated from Delta Verification

# After running verify-delta --report-missing
fs-fe-utils trans map-paths "missing-keys-report-2024-01-15T10-30-45.txt"

Sample Output

🗺️  Path Mapper Setup:
   Mapping File: missing-keys-report-2024-01-15T10-30-45.txt
   Source Directory: ./locales
   Output Directory: ./locales-mapped

✅ Loaded 15 mapping(s) from file
   🔄 Rename/Move operations: 12
   🗑️  Delete operations: 3

🔧 Processing: en/translations.json
     📝 user.name → profile.fullName
     🗑️  deprecated.oldKey → DELETED
   ✅ Applied 8 mapping(s)

🔧 Processing: es/translations.json
     📝 user.name → profile.fullName
     🗑️  deprecated.oldKey → DELETED
   ✅ Applied 8 mapping(s)

🎉 Path mapping completed successfully!

📊 Delta Extraction (extract-delta)

Compare translation files between git branches and extract differences for delta processing.

Usage

fs-fe-utils trans extract-delta [fileName] [options]

Features

• Git Branch Comparison: Compare current branch against base branch
• Smart File Detection: Auto-detects translation files (en.json, en.yml, etc.)
• Deep Object Comparison: Handles nested translation structures
• Multi-format Support: Works with JSON and YAML files
• Detailed Change Analysis: Shows new, changed, and unchanged keys
• Automatic Delta Generation: Creates timestamped delta files

Options

• [fileName] - Target file name (optional, will auto-detect)
• -s, --source <path> - Source directory (default: current directory)
• -b, --base-branch <branch> - Base branch to compare against (default: 'prestaging')
• -f, --file <fileName> - Target file name (alternative to positional argument)

Examples

Basic Delta Extraction

fs-fe-utils trans extract-delta
# Auto-detects translation files and compares against prestaging

Specific File and Branch

fs-fe-utils trans extract-delta en.json -b main

Custom Source Directory

fs-fe-utils trans extract-delta -s ./src/locales -f translations.yml

Sample Output

🔍 Starting file delta extraction...

📋 Current branch: feature/new-translations
📋 Base branch: prestaging
📄 Target file: en.json
📊 Current file has 156 key(s)
📊 Base branch file has 142 key(s)

🔍 Comparing files for differences...
📝 Analyzing differences:
     ➕ New key: user.profile.settings
     ➕ New key: dashboard.widgets.new
     🔄 Changed key: welcome.message
     ✓ Unchanged: login.title

✅ Delta extraction completed successfully!
📁 Delta file created: feature-new-translations-to-prestaging-en-delta-2024-01-15.json
🔢 Found 14 difference(s)

📄 File-to-File Delta Extraction (extract-delta-by-file)

Extract differences between two specific translation files without using git branches. Perfect for comparing files from different sources or when you need more control over which files to compare.

Usage

fs-fe-utils trans extract-delta-by-file [options]

Features

• Direct File Comparison: Compare any two JSON/YAML files by file path
• No Git Dependency: Works without git repositories (unless using blame feature)
• Interactive File Selection: Prompts for file paths if not specified
• Ultra-lenient YAML Parsing: Handles malformed YAML files with multiple fallback strategies
• Git Blame Integration: Shows who last modified each key (when files are in git repos)
• Format Preservation: Output format matches input format (JSON→JSON, YAML→YAML)
• Deep Object Comparison: Handles nested translation structures
• Detailed Change Analysis: Shows new, changed, and unchanged keys

Options

• -s, --source-path <path> - Directory to save delta file (default: current directory)
• -b, --base-file-path <path> - Base file path to compare against
• -c, --current-file-path <path> - Current file path to compare
• --blame - Include git blame information for each key
• --show-unchanged - Show unchanged keys in logs

Examples

Interactive Mode

fs-fe-utils trans extract-delta-by-file
# Will prompt for both base and current file paths

Specify Both Files Directly

fs-fe-utils trans extract-delta-by-file --base-file-path ./old/en.json --current-file-path ./new/en.json

Include Git Blame Information

fs-fe-utils trans extract-delta-by-file --blame --base-file-path ./v1/config.yml --current-file-path ./v2/config.yml

Show Unchanged Keys

fs-fe-utils trans extract-delta-by-file --show-unchanged --base-file-path ./before.json --current-file-path ./after.json

Custom Output Directory

fs-fe-utils trans extract-delta-by-file --source-path ./output --base-file-path ./file1.yml --current-file-path ./file2.yml

Sample Output

🔍 Starting file-to-file delta extraction...

📄 Base file: ./translations/en-old.json
📄 Current file: ./translations/en-new.json
📊 Base file has 45 key(s)
📊 Current file has 52 key(s)
🔍 Comparing files for differences...
📝 Analyzing differences:
     ➕ New key: user.welcome.title @john
     🔄 Changed key: user.profile.bio @sarah
        Old: "Tell us about yourself"
        New: "Share your story with us"
     ➕ New key: dashboard.stats.revenue
     🔍 Nested changes in: settings.notifications

✅ Delta extraction completed successfully!
📁 Delta file created: en-new-vs-en-old-delta-2024-01-15.json
🔢 Found 3 difference(s)

Use Cases

• Cross-project Comparisons: Compare translation files from different projects or repositories
• Version Comparisons: Compare different versions of the same file from backups or archives
• Manual File Analysis: When you have specific files to compare without git branch context
• External File Sources: Compare files from external sources, APIs, or different systems
• Backup Verification: Verify changes between current files and backup versions

🌐 Web Interface (serve-ui)

Launch a beautiful web interface that provides GUI access to all fs-fe-utils functionality. Perfect for teams who prefer visual interfaces or need to share the tools with non-technical users.

Usage

fs-fe-utils serve-ui [options]

Features

• Modern Web Interface: Beautiful, responsive UI built with Tailwind CSS
• File Upload: Drag-and-drop file uploads with support for JSON, YAML, and TXT files
• All Utilities Available: GUI access to all command-line utilities
• Real-time Output: Live console output and progress indicators
• File Management: Upload, view, and delete files through the interface
• Download Results: Direct download links for generated files and reports
• Git Integration: Automatic branch detection for delta extraction
• Responsive Design: Works on desktop, tablet, and mobile devices

Options

• -p, --port <port> - Port to run the server on (default: 9900)

Examples

Basic Usage

fs-fe-utils serve-ui
# Starts server on http://localhost:9900

Custom Port

fs-fe-utils serve-ui --port 8080
# Starts server on http://localhost:8080

Web Interface Features

🔄 Delta Extraction

• Git-based: Compare branches with automatic branch detection
• File-based: Upload and compare two specific files
• Git blame integration: See who modified each key
• Real-time progress: Live updates during extraction

✅ Delta Verification

• Specify both delta file and base/target file paths
• Configure root key handling and report options
• Generate missing keys reports for path mapping
• System file browser for easy file selection
• Download generated reports and analysis

🗺️ Path Mapping

• Upload mapping files (TXT format)
• Apply path restructuring
• Visual feedback on operations
• Download restructured files

🔄 Translation Merging

• Merge delta files into target directories
• Language limiting options
• Multi-language processing
• Progress tracking

📁 File Management

• Drag-and-drop file uploads
• File size and type validation (JSON, YAML, TXT)
• File preview and management
• Automatic cleanup of old files

Sample Workflow

1. Start the server:

   fs-fe-utils serve-ui

2. Open your browser to http://localhost:9900

3. Upload files using drag-and-drop or file selector

4. Choose a utility from the main dashboard

5. Configure options in the modal dialogs

6. Execute operations and view real-time output

7. Download results using the provided download links

Technical Details

• Backend: Express.js server with REST API
• Frontend: Vanilla JavaScript with Tailwind CSS
• File Handling: Multer for secure file uploads
• Security: File type validation and size limits
• Cleanup: Automatic removal of temporary files
• Error Handling: Comprehensive error reporting and user feedback

Server Management

# Start server
fs-fe-utils serve-ui

# Start on custom port
fs-fe-utils serve-ui --port 8080

# Stop server
# Press Ctrl+C in the terminal

The server includes:

• Health checks: Automatic connection monitoring
• Graceful shutdown: Clean resource cleanup on exit
• Automatic cleanup: Removes temporary files older than 1 hour
• Error recovery: Robust error handling and user feedback

🔄 Translation Merging (i18n-merge)

Merge translation delta files into target language directories with advanced YAML/JSON processing.

Usage

fs-fe-utils trans i18n-merge [deltaPath] [options]

Features

• Multi-language Processing: Handles multiple language directories simultaneously
• Language Mapping: Smart mapping between delta directories and local files
• YAML Formatting Preservation: Maintains original YAML formatting and comments
• Duplicate Key Handling: Resolves YAML duplicate keys intelligently
• Order Preservation: Maintains key order when merging translations
• Korean Language Special Handling: Applies ko delta to both ko and ko-KR files
• Missing Delta Reporting: Identifies local files without corresponding deltas
• Language Limiting: Process only specific languages with --limit option

Options

• [deltaPath] - Path to translation delta directory (optional, will prompt)
• -s, --source <path> - Source directory (default: current directory)
• -t, --target <path> - Target translation directory (default: current directory)
• -d, --delta <path> - Translation delta directory path (alternative to positional argument)
• -l, --limit <languages> - Limit processing to specific languages (comma-separated)

Language Mappings

Built-in mappings for common language code variations:

• cy-GB ↔ cy
• es ↔ es-ES
• es-LA ↔ es-MX
• ja-JP ↔ ja
• lv-LV ↔ lv
• nb-NO ↔ no
• ru-RU ↔ ru

Examples

Basic Translation Merge

fs-fe-utils trans i18n-merge /path/to/translation-delta

Limit to Specific Languages

fs-fe-utils trans i18n-merge --limit "en,es,fr" /path/to/delta

Custom Source and Target

fs-fe-utils trans i18n-merge -s ./src -t ./src/locales -d /path/to/delta

Interactive Mode

fs-fe-utils trans i18n-merge
# Will prompt for delta path and confirm source directory

Sample Output

📁 Current configuration:
   Source Directory (translation files): ./src/locales
   Delta Directory: /path/to/translation-delta

🌐 Found 5 language(s): en, es, fr, de, ja

🔄 Language mappings in effect:
   es (delta) → es-ES (local file)

🔄 Processing language: en
   📄 Processing: translations.json → en.json
     ➕ Added new key: user.profile.settings
     🔄 Updated key: dashboard.title
     ⏭️  Skipped (same value): login.button
   ✅ Merged 45 translation key(s) to en.json

🔄 Processing language: es
   📄 Processing: translations.json (es → es-ES) → es-ES.json
   ✅ Merged 45 translation key(s) to es-ES.json

✅ All local translation files have corresponding deltas

📝 YAML Document Processing

Advanced YAML handling with formatting preservation, powered by the yaml-document-merger utility.

Features

• Perfect Formatting Preservation: Maintains original indentation, comments, and spacing
• Duplicate Key Resolution: Handles YAML duplicate keys intelligently
• Whitespace Preservation: Preserves leading/trailing spaces in string values
• Quote Style Detection: Maintains original quote styles from source files
• String-based Merging: Uses string manipulation for maximum formatting fidelity
• Nested Structure Support: Handles complex nested YAML structures
• Error Recovery: Graceful handling of malformed YAML with multiple fallback strategies

YAML Processing Capabilities

• Lenient Parsing: Handles malformed YAML files with recovery strategies
• Content Preprocessing: Fixes common YAML formatting issues automatically
• Line-by-line Recovery: Attempts to salvage content from severely malformed files
• Duplicate Key Merging: Last value wins for duplicate keys
• Comment Preservation: Maintains YAML comments during merge operations

Configuration and Advanced Usage

Environment Variables

• DEBUG=true - Enable detailed debug logging for troubleshooting

File Format Support

• JSON: .json files with standard JSON formatting
• YAML: .yml and .yaml files with full YAML 1.1 support
• Mixed Projects: Can handle projects with mixed JSON/YAML translation files

Git Integration Features

• Branch Detection: Automatic current branch detection
• Remote Branch Support: Handles both local and remote branches
• Git Blame Information: Shows commit history for type mismatches
• Repository Validation: Ensures commands run in git repositories when needed

Interactive Features

• Smart Defaults: Intelligent default values based on project structure
• File Validation: Real-time validation of file paths and directories
• Confirmation Prompts: User confirmation for destructive operations
• Progress Feedback: Detailed progress reporting for long operations

Workflow Examples

Complete Translation Management Workflow

Option 1: Command Line Workflow

1. Extract Delta from Feature Branch

# Extract differences from your feature branch
fs-fe-utils trans extract-delta en.json -b main
# Creates: feature-branch-to-main-en-delta-2024-01-15.json

# OR compare two specific files directly
fs-fe-utils trans extract-delta-by-file --base-file-path ./main-branch/en.json --current-file-path ./current/en.json
# Creates: current-vs-main-branch-delta-2024-01-15.json

2. Verify Delta Against Target

# Verify the delta and generate mapping report
fs-fe-utils trans verify-delta feature-branch-to-main-en-delta-2024-01-15.json --report-missing
# Creates: missing-keys-report-2024-01-15T10-30-45.txt

3. Review and Edit Mappings

# Edit the generated report file
# Add path mappings: user.name:profile.fullName
# Mark deprecated keys: old.key:DELETE
# Leave unwanted keys empty: temp.data:

4. Apply Path Restructuring

# Apply the mappings to restructure translation files
fs-fe-utils trans map-paths "missing-keys-report-2024-01-15T10-30-45.txt"
# Creates: ./locales-mapped/ directory with restructured files

5. Merge Delta into Target Languages

# Merge the delta into all language files
fs-fe-utils trans i18n-merge /path/to/translation-delta --limit "en,es,fr"

Development Best Practices

Safe File Operations

• Always use the --report-missing flag to preview changes
• Review generated mapping files before applying path changes
• Test with a subset of languages using --limit option
• Keep backups of original files (tools create new directories by default)

Git Workflow Integration

# Before making changes
git checkout -b translation-updates

# Extract and verify changes
fs-fe-utils trans extract-delta
fs-fe-utils trans verify-delta delta-file.json --report-missing

# Apply restructuring if needed
fs-fe-utils trans map-paths mapping-report.txt

# Merge translations
fs-fe-utils trans i18n-merge /path/to/delta

# Review changes and commit
git add .
git commit -m "Update translations with restructuring"

Troubleshooting

Common Issues

YAML Parsing Errors

• Duplicate Keys: Tool automatically handles duplicate keys (last value wins)
• Malformed YAML: Multiple recovery strategies attempt to salvage content
• Quote Issues: Automatic quote fixing for common patterns

Path Resolution

• File Not Found: Use absolute paths or verify current directory
• Permission Errors: Ensure write permissions for output directories
• Git Repository: Some commands require git repository context

Type Mismatches

• Structure Changes: Use --report-missing to identify and handle conflicts
• Mixed Types: Review git blame information to understand changes
• Root Key Conflicts: Use root key ignoring option for multi-language files

Debug Mode

DEBUG=true fs-fe-utils trans verify-delta delta.json

Enables detailed logging for troubleshooting complex issues.

Contributing

Development Setup

git clone <repository-url>
cd fs-fe-utils
npm install
npm link

Project Structure

fs-fe-utils/
├── bin/
│   └── cli.js                    # CLI entry point
├── src/
│   ├── delta-verifier.js         # Delta verification with type checking
│   ├── path-mapper.js            # Path restructuring and key mapping
│   ├── delta-extractor.js        # Git branch comparison and delta extraction
│   ├── translation-merger.js     # Translation merging with language mapping
│   └── yaml-document-merger.js   # Advanced YAML processing
├── package.json
└── README.md

Testing

• Manual testing with various translation file formats
• Test with different git repository configurations
• Validate YAML parsing with malformed files
• Test language mapping edge cases

Code Style

• ESLint configuration included
• Consistent error handling and user feedback
• Comprehensive logging for debugging
• Interactive prompts for better UX

License

MIT License - see LICENSE file for details

Version History

v1.6.1 (Latest)

• Enhanced delta verification with type mismatch detection
• Path mapping with DELETE operation support
• Ready-made terminal commands in reports
• Improved YAML parsing with multiple fallback strategies
• Git blame integration for conflict resolution
• Interactive prompts for better user experience

Previous Versions

• Multi-language support with intelligent mapping
• YAML document processing with formatting preservation
• Git integration for branch comparison
• Language limiting and filtering options
• Korean language special handling
• Comprehensive error handling and recovery