Translator Widget - Phase 3 Commercial Edition

🌍 Modern Multi-Language Translation Plugin for Web Applications

A production-ready, commercial-grade translation widget that supports multiple languages, advanced features, and enterprise capabilities.

✨ Phase 3 Commercial Features

🎨 Advanced Language Management

• Dynamic Language Control: Enable/disable languages on-the-fly
• Priority Reordering: Customize language display order
• Lazy Loading: Optimized performance with on-demand translation loading
• Fallback Support: Graceful handling of missing translations

⚙️ Admin Panel & Settings UI

• Visual Settings Panel: Change theme, position, and languages without code
• Real-time Configuration: Instant application of settings changes
• Responsive Design: Works perfectly on desktop and mobile devices
• Theme Support: Light, dark, and auto themes with system detection

📊 Analytics & Reporting System

• Usage Tracking: Monitor translation statistics and user behavior
• Language Analytics: Track which languages are most used
• Session Data: Monitor user engagement and activity patterns
• API Integration: Export analytics data for external dashboards

🔒 License System

• Free Tier: 2 languages, basic features
• Pro Tier: 10 languages, analytics, admin panel
• Enterprise Tier: Unlimited languages, server-side translation, full support
• Key Validation: Secure license verification system

🖥️ Server-Side Translation (Enterprise)

• Secure Processing: Keep sensitive content on your servers
• Enhanced Privacy: No client-side exposure of translation data
• Custom Integration: Full control over translation workflows
• Enterprise Security: Meets corporate security requirements

🎯 Enhanced Event System

• Comprehensive Events: Monitor all widget activities
• Custom Handlers: Integrate with your application logic
• Error Handling: Robust error reporting and recovery
• Performance Monitoring: Track translation performance metrics

🚀 Quick Start

CDN Integration (Recommended)

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/style.min.css">

<!-- JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/translator.min.js"></script>

<!-- Initialize -->
<script>
    Translator.init({
        apiUrl: '/api/translations',
        licenseKey: 'PRO-1234567890123456', // Optional
        defaultLang: 'en',
        languages: ['en', 'fa', 'ar', 'tr'],
        position: 'bottom-right',
        theme: 'auto'
    });
</script>

NPM Installation

npm install [email protected]

import Translator from 'translator-widget';
import 'translator-widget/dist/style.min.css';

Translator.init({
    apiUrl: '/api/translations',
    licenseKey: 'PRO-1234567890123456',
    defaultLang: 'en',
    languages: ['en', 'fa', 'ar', 'tr'],
    position: 'bottom-right',
    theme: 'auto'
});

⚙️ Configuration Options

Basic Configuration

Translator.init({
    // Required: Your translation API endpoint
    apiUrl: '/api/translations',
    
    // Optional: License key for Pro/Enterprise features
    licenseKey: 'PRO-1234567890123456',
    
    // Default language (ISO 639-1 code)
    defaultLang: 'en',
    
    // Array of supported languages
    languages: ['en', 'fa', 'ar', 'tr', 'es', 'fr'],
    
    // Widget position
    position: 'bottom-right', // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
    
    // Theme setting
    theme: 'auto', // 'light', 'dark', 'auto'
    
    // Enable analytics (Pro/Enterprise only)
    enableAnalytics: true,
    
    // Server-side translation (Enterprise only)
    serverSideTranslation: false,
    
    // Show admin panel (Pro/Enterprise only)
    showAdminPanel: true,
    
    // Fallback language for missing translations
    fallbackLanguage: 'en',
    
    // Enable lazy loading for better performance
    lazyLoading: true
});

License Key Formats

• Free: FREE-12345678 (2 languages, no analytics)
• Pro: PRO-1234567890123456 (10 languages, analytics, admin panel)
• Enterprise: ENT-123456789012345678901234 (unlimited, all features)

📊 Analytics API

Get Analytics Data

const translator = Translator.getInstance();
const analytics = translator.getAnalytics();

console.log('Total translations:', analytics.translations);
console.log('Languages used:', analytics.languages);
console.log('Session start:', new Date(analytics.sessionStart));
console.log('Last active:', new Date(analytics.lastActive));

Clear Analytics

translator.clearAnalytics();

🎯 Event System

Available Events

// Widget initialization
document.addEventListener('translator:initialized', (event) => {
    console.log('Widget initialized:', event.detail);
});

// Language change started
document.addEventListener('translator:languageChange', (event) => {
    console.log('Changing to language:', event.detail.language);
});

// Language change completed
document.addEventListener('translator:languageChanged', (event) => {
    console.log('Language changed to:', event.detail.language);
});

// Translation completed
document.addEventListener('translator:translationComplete', (event) => {
    console.log('Translated', event.detail.count, 'texts to', event.detail.language);
});

// Settings changed
document.addEventListener('translator:settingsChanged', (event) => {
    console.log('Settings updated:', event.detail.config);
});

// Analytics updated
document.addEventListener('translator:analyticsUpdate', (event) => {
    console.log('Analytics updated:', event.detail.analytics);
});

// Cache updated
document.addEventListener('translator:cacheUpdate', (event) => {
    console.log('Cache updated for key:', event.detail.key);
});

// Cache cleared
document.addEventListener('translator:cacheCleared', () => {
    console.log('Cache cleared');
});

// Analytics cleared
document.addEventListener('translator:analyticsCleared', () => {
    console.log('Analytics cleared');
});

// Error occurred
document.addEventListener('translator:error', (event) => {
    console.error('Translation error:', event.detail.error);
});

// Widget destroyed
document.addEventListener('translator:destroyed', () => {
    console.log('Widget destroyed');
});

🔧 API Reference

Core Methods

const translator = Translator.getInstance();

// Get current language
const currentLang = translator.getCurrentLanguage();

// Get supported languages
const languages = translator.getSupportedLanguages();

// Get enabled languages
const enabledLanguages = translator.getEnabledLanguages();

// Get configuration
const config = translator.getConfig();

// Get license information
const licenseInfo = translator.getLicenseInfo();

// Clear translation cache
translator.clearCache();

// Clear analytics data
translator.clearAnalytics();

// Destroy widget
translator.destroy();

Language Management

// Enable a language
translator.languageManager.enableLanguage('es');

// Disable a language
translator.languageManager.disableLanguage('fr');

// Reorder languages
translator.languageManager.reorderLanguages(['en', 'es', 'fr', 'de']);

// Get enabled languages
const enabled = translator.languageManager.getEnabledLanguages();

🏗️ Framework Integration

React/Next.js

import { useEffect } from 'react';
import Translator from 'translator-widget';
import 'translator-widget/dist/style.min.css';

function App() {
    useEffect(() => {
        Translator.init({
            apiUrl: '/api/translations',
            licenseKey: 'PRO-1234567890123456',
            defaultLang: 'en',
            languages: ['en', 'fa', 'ar', 'tr'],
            position: 'bottom-right',
            theme: 'auto'
        });

        // Cleanup on unmount
        return () => {
            const instance = Translator.getInstance();
            if (instance) {
                instance.destroy();
            }
        };
    }, []);

    return (
        <div>
            <h1>Welcome to my React app</h1>
            <p>This content will be translated automatically.</p>
        </div>
    );
}

Vue.js

<template>
    <div>
        <h1>Welcome to my Vue app</h1>
        <p>This content will be translated automatically.</p>
    </div>
</template>

<script>
import Translator from 'translator-widget';
import 'translator-widget/dist/style.min.css';

export default {
    name: 'App',
    mounted() {
        Translator.init({
            apiUrl: '/api/translations',
            licenseKey: 'PRO-1234567890123456',
            defaultLang: 'en',
            languages: ['en', 'fa', 'ar', 'tr'],
            position: 'bottom-right',
            theme: 'auto'
        });
    },
    beforeUnmount() {
        const instance = Translator.getInstance();
        if (instance) {
            instance.destroy();
        }
    }
};
</script>

WordPress

Add to your theme's functions.php:

function enqueue_translator_widget() {
    wp_enqueue_style(
        'translator-widget',
        'https://cdn.jsdelivr.net/npm/[email protected]/dist/style.min.css',
        array(),
        '3.0.0'
    );
    
    wp_enqueue_script(
        'translator-widget',
        'https://cdn.jsdelivr.net/npm/[email protected]/dist/translator.min.js',
        array(),
        '3.0.0',
        true
    );
    
    wp_add_inline_script('translator-widget', '
        Translator.init({
            apiUrl: "/wp-json/translator/v1/translate",
            licenseKey: "PRO-1234567890123456",
            defaultLang: "en",
            languages: ["en", "fa", "ar", "tr"],
            position: "bottom-right",
            theme: "auto"
        });
    ');
}
add_action('wp_enqueue_scripts', 'enqueue_translator_widget');

Shopify

Add to your theme's layout/theme.liquid:

<head>
    <!-- ... other head content ... -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/style.min.css">
</head>
<body>
    <!-- ... your content ... -->
    
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/translator.min.js"></script>
    <script>
        Translator.init({
            apiUrl: '/apps/translator/translate',
            licenseKey: 'PRO-1234567890123456',
            defaultLang: 'en',
            languages: ['en', 'fa', 'ar', 'tr'],
            position: 'bottom-right',
            theme: 'auto'
        });
    </script>
</body>

🔌 API Endpoint Requirements

Your translation API should accept POST requests with the following format:

Client-Side Translation (Default)

Request:

{
    "lang": "fa",
    "texts": ["Hello world", "Welcome to our website"]
}

Response:

["سلام دنیا", "به وب‌سایت ما خوش آمدید"]

Server-Side Translation (Enterprise)

Request:

{
    "lang": "fa",
    "texts": ["Hello world", "Welcome to our website"],
    "returnHtml": true
}

Response:

["سلام دنیا", "به وب‌سایت ما خوش آمدید"]

🚫 Content Exclusion

Add the data-no-translate attribute to elements you don't want translated:

<p>This will be translated</p>
<p data-no-translate>This will NOT be translated</p>

📱 Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

💰 Pricing & Licensing

Free Tier

• Languages: 2 languages maximum
• Features: Basic translation, caching
• Analytics: Disabled
• Admin Panel: Disabled
• Price: Free

Pro Tier ($29/month)

• Languages: 10 languages maximum
• Features: All Free features + analytics, admin panel
• Analytics: Enabled with detailed reporting
• Admin Panel: Full settings interface
• Support: Email support
• Price: $29/month

Enterprise Tier ($99/month)

• Languages: Unlimited
• Features: All Pro features + server-side translation
• Analytics: Advanced analytics with API access
• Admin Panel: Full admin interface
• Server-Side: Secure server-side translation processing
• Support: Priority support with dedicated account manager
• Price: $99/month

🔧 Development

Building from Source

# Clone the repository
git clone https://github.com/your-org/translator-widget.git
cd translator-widget

# Install dependencies
npm install

# Development mode
npm run dev

# Build for production
npm run build

# Preview build
npm run preview

Project Structure

plugin/
├── dist/                 # Production build output
│   ├── translator.min.js # Minified UMD bundle
│   ├── translator.esm.js # ES Module bundle
│   ├── style.min.css     # Minified CSS
│   └── flags/            # SVG flag icons
├── src/                  # Source code
│   ├── translator.js     # Main plugin code
│   ├── style.css         # Styles
│   └── flags/            # Source flag icons
├── flags/                # Flag SVGs
├── example.html          # Demo page
├── package.json          # NPM configuration
├── vite.config.js        # Build configuration
├── build.js              # Custom build script
└── README.md             # This file

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

• Documentation: https://github.com/your-org/translator-widget
• Issues: https://github.com/your-org/translator-widget/issues
• Email: [email protected]
• Discord: Join our community

🚀 Changelog

Version 3.0.0 (Phase 3 Commercial)

• ✨ Added advanced language management
• ⚙️ Implemented admin panel and settings UI
• 📊 Added analytics and reporting system
• 🔒 Implemented license key validation
• 🖥️ Added server-side translation (Enterprise)
• 🎯 Enhanced event system
• 🏗️ Added Free/Pro/Enterprise tiers
• 📱 Improved responsive design
• 🔧 Enhanced build system

Version 2.0.0 (Phase 2)

• 📦 Universal module support (ESM + UMD)
• 🎨 Theme system with light/dark/auto modes
• 📍 Configurable widget positioning
• 💾 Translation caching with localStorage
• 🔄 Dynamic content translation with MutationObserver
• 📱 Mobile-responsive design
• 🏗️ Vite build system

Version 1.0.0 (Phase 1)

• 🌍 Basic multi-language translation
• 🎯 Simple widget interface
• 🔧 Basic configuration options
• 📄 Initial documentation

Made with ❤️ by the AI Translation Team