README

Empowering Multilingual WordPress Sites with Advanced Translation Capabilities

NativeLang is a comprehensive WordPress plugin designed to significantly enhance your website's multilingual capabilities. Built as an advanced extension for the popular Polylang plugin, NativeLang adds powerful translation features, intelligent caching, and seamless multisite support that make it easier than ever to manage and deliver content in multiple languages.

🚀 Key Features

Core Translation Features

🔄 Automatic Content Translation: Real-time translation of posts, pages, titles, and widgets using Google Translate API
🎯 Smart Menu Translation: Automatic translation of navigation menus with emoji support and custom mappings
🧠 Intelligent Caching: Advanced caching system with automatic expiration and cleanup to reduce API calls
📊 Translation Quality Control: Built-in quality assessment with metrics and error handling

User Interface & Experience

🌍 Language Switcher Widget: Customizable language switcher with flags, dropdowns, and multiple display options
🎨 Emoji Support: Rich emoji integration for enhanced visual language identification
📱 Responsive Design: Mobile-optimized interface with accessibility features
⚡ Real-time Updates: Live translation status with progress indicators

Advanced Features

🏢 Multisite Support: Full WordPress Multisite compatibility with domain mapping
🔧 Developer-Friendly: Extensive hooks, filters, and APIs for customization
📈 Performance Optimized: Minimal database queries with intelligent memory management
🛡️ Security Focused: Secure cache handling with proper sanitization and validation

Administrative Tools

⚙️ Admin Dashboard: Comprehensive settings page with cache management and statistics
📊 Analytics: Detailed translation metrics and performance monitoring
🔄 Bulk Operations: Mass cache clearing and translation management
🧪 Testing Suite: Built-in test framework for validation and debugging

📦 Architecture Overview

NativeLang follows a modular architecture designed for performance, maintainability, and extensibility:

Core Components

🏗️ Main Plugin Class (NativeMind): Singleton pattern with comprehensive hook management
💾 Cache System (NativeMindCache): Advanced file-based caching with automatic cleanup
🌐 Internationalization (i18n.php): Complete language support with Polylang integration
🔧 Utility Functions (functions.php): Helper functions for common operations
🌍 Multisite Support (multisite/): Domain mapping and multi-language site management

Integration Points

WordPress Core: Deep integration with WordPress hooks and filters
Polylang Plugin: Seamless extension of Polylang's capabilities
Google Translate API: Reliable translation service with fallback handling
WordPress Multisite: Native support for network installations

🛠️ Installation & Setup

Prerequisites

WordPress 5.0 or higher
PHP 7.4 or higher
Polylang plugin installed and activated
Google Translate API key (for automatic translations)

Installation Methods

Via Composer (Recommended)

composer require nativemind/wp-translation

Manual Installation

Download Plugin Files:

# Download and extract to your WordPress plugins directory
/wp-content/plugins/nativemind-wp-translation/

Configure Polylang:
- Install and activate Polylang
- Set up your languages in Polylang settings
- Configure default language
Activate NativeLang:
- Go to WordPress Admin → Plugins
- Activate "NativeMind Plugin"

Configure API Key:

Option 1: Environment Variable (Recommended)

# Set in your server environment or wp-config.php
define('GOOGLE_TRANSLATE_API_KEY', 'your-api-key-here');

Option 2: Copy Template File

# Copy the template and add your API key
cp translateTextGoogle.php.example translateTextGoogle.php
# Edit translateTextGoogle.php and add your API key

Multisite Setup (Optional):

// Edit multisite/my_domains.php
cybo_add_extra_domain( 'your-domain.com', '/', 1 );

🎯 Usage Guide

Basic Usage

Language Switcher

Add language switcher anywhere using:

Shortcode:

[nm_language_switcher show_flags="true" show_names="true" dropdown="false"]

PHP Function:

echo nm_get_language_switcher(array(
    'show_flags' => true,
    'show_names' => true,
    'dropdown' => false
));

Widget:

Go to Appearance → Widgets
Add "NativeMind Language Switcher" widget

Menu Translation

Create menus in WordPress as usual
Use #LANGUAGE# placeholder for current language display
Add emojis to menu items for visual enhancement

Advanced Configuration

Custom Translation Mappings

// Add to i18n/menu/custom.php
$nm_custom = array(
    'en' => array(
        'Home' => 'Home',
        'About' => 'About Us'
    ),
    'ru' => array(
        'Home' => 'Главная',
        'About' => 'О нас'
    )
);

Cache Management

// Clear all cache
$cleared = NativeMindCache::clear_all();

// Get cache statistics  
$stats = NativeMindCache::get_stats();

// Manual cache control
$cache_key = NativeMindCache::generate_cache_key($content, 'en', 'ru');
NativeMindCache::set($cache_key, $translated_content);

Multisite Domain Mapping

// Configure in multisite/my_domains.php
cybo_add_extra_domain( 'en.example.com', '/', 1 );  // English site
cybo_add_extra_domain( 'ru.example.com', '/', 2 );  // Russian site
cybo_add_extra_domain( 'example.ru', '/', 2 );      // Alternative Russian domain

🔧 Developer API

Hooks and Filters

Actions

// Plugin initialization
do_action('nm_plugin_loaded');

// Translation events
do_action('nm_translation_start', $content, $from_lang, $to_lang);
do_action('nm_translation_complete', $translated_content, $original_content);
do_action('nm_translation_error', $error_message, $content);

// Cache events
do_action('nm_cache_cleared');
do_action('nm_cache_cleanup');

Filters

// Modify translation before processing
$content = apply_filters('nm_pre_translate', $content, $from_lang, $to_lang);

// Modify translated content
$translated = apply_filters('nm_post_translate', $translated_content, $original_content);

// Customize language switcher output
$switcher_html = apply_filters('nm_language_switcher_html', $html, $args);

// Modify cache key generation
$cache_key = apply_filters('nm_cache_key', $cache_key, $content, $lang_from, $lang_to);

Custom Functions

Translation Quality Check

$quality = nm_check_translation_quality($original, $translated);
echo "Quality Score: " . $quality['quality_score'] . "%";

Browser Language Detection

$browser_lang = nm_get_browser_language();
if ($browser_lang !== 'en') {
    // Redirect to appropriate language site
    nm_auto_redirect_language();
}

Custom Flag Emojis

$flag = nm_get_flag_emoji('de'); // Returns 🇩🇪

🧪 Testing

Test Suite

Run the comprehensive test suite:

// Access via browser
http://yoursite.com/wp-content/plugins/nativelang-wordpress/test_cache.php

// Or include in code
include 'test_cache.php';
$test = new NativeMindTest();
$test->run_all_tests();

Manual Testing Checklist

Plugin activation without errors
Polylang integration working
Language switcher displays correctly
Menu translations functional
Cache operations working
Admin dashboard accessible
Multisite domain mapping (if applicable)

📊 Performance & Optimization

Caching Strategy

File-based caching with automatic expiration (7 days default)
Memory caching for repeated translations within single request
Intelligent cache keys incorporating blog ID, network ID, and content hash
Automatic cleanup via WordPress cron jobs

Performance Tips

API Key Management: Use environment variables for API keys
Cache Tuning: Adjust cache expiration based on content update frequency
Selective Translation: Don't translate administrative content
CDN Integration: Serve static assets via CDN for better performance

🛡️ Security Considerations

Data Protection

All user input is properly sanitized and validated
Cache files are protected with .htaccess rules
API keys should be stored securely (not in version control)
CSRF protection on all admin actions

Best Practices

Regular cache cleanup to prevent disk space issues
Monitor API usage to avoid quota limits
Use HTTPS for all translation API calls
Implement proper error handling and logging

🐛 Troubleshooting

Common Issues

"Polylang not found" Error

Solution: Install and activate Polylang plugin first.

Translations Not Appearing

Possible Causes:

Invalid Google Translate API key
Network connectivity issues
Cache directory permissions
Polylang configuration incomplete

Debug Steps:

Check API key validity
Verify cache directory is writable
Enable WordPress debug logging
Run test suite for diagnostics

Language Switcher Not Displaying