# Multilingual Press Zone - Technical Specifications

**Version:** 1.0.0  
**Phase:** Phase 1 - MVP  
**Target:** Beta customers (4 weeks)

---

## Phase 1 Scope

### Goals
- Core multilingual functionality
- 10x faster than WPML
- Production-ready for beta customers
- Foundation for enterprise features

### Out of Scope (Future Phases)
- Translation workflow
- Team management
- Advanced reporting
- API access
- Migration tools

---

## Database Schema (Phase 1)

### Table: wp_mpz_languages

```sql
CREATE TABLE IF NOT EXISTS wp_mpz_languages (
    id BIGINT(20) UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    code VARCHAR(10) NOT NULL COMMENT 'Language code (en, es, fr)',
    locale VARCHAR(20) NOT NULL COMMENT 'Full locale (en_US, es_ES)',
    name VARCHAR(100) NOT NULL COMMENT 'English name',
    native_name VARCHAR(100) NOT NULL COMMENT 'Native name',
    flag_code VARCHAR(10) DEFAULT NULL COMMENT 'Flag emoji code',
    is_default TINYINT(1) DEFAULT 0 COMMENT '1 if default language',
    is_active TINYINT(1) DEFAULT 1 COMMENT '1 if active',
    sort_order INT(11) DEFAULT 0 COMMENT 'Display order',
    url_structure ENUM('subdirectory', 'subdomain', 'parameter') DEFAULT 'subdirectory',
    text_direction ENUM('ltr', 'rtl') DEFAULT 'ltr',
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    
    UNIQUE KEY idx_code (code),
    KEY idx_active (is_active),
    KEY idx_default (is_default)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### Table: wp_mpz_translations

```sql
CREATE TABLE IF NOT EXISTS wp_mpz_translations (
    id BIGINT(20) UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    translation_group_id BIGINT(20) UNSIGNED NOT NULL COMMENT 'Groups related translations',
    element_type VARCHAR(50) NOT NULL COMMENT 'post, page, product, term',
    element_id BIGINT(20) UNSIGNED NOT NULL COMMENT 'Post ID, Term ID, etc',
    language_code VARCHAR(10) NOT NULL COMMENT 'Language of this element',
    source_element_id BIGINT(20) UNSIGNED DEFAULT NULL COMMENT 'Original element ID',
    translation_status ENUM('original', 'translated', 'needs_update', 'draft') DEFAULT 'original',
    content_hash VARCHAR(64) DEFAULT NULL COMMENT 'SHA256 for change detection',
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    
    UNIQUE KEY idx_element (element_type, element_id, language_code),
    KEY idx_group (translation_group_id),
    KEY idx_language (language_code),
    KEY idx_source (source_element_id),
    KEY idx_covering (element_type, language_code, element_id, translation_group_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### Table: wp_mpz_string_translations

```sql
CREATE TABLE IF NOT EXISTS wp_mpz_string_translations (
    id BIGINT(20) UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    string_key VARCHAR(255) NOT NULL COMMENT 'Unique identifier',
    context VARCHAR(100) DEFAULT 'default' COMMENT 'Domain/context',
    original_string TEXT NOT NULL COMMENT 'Original text',
    language_code VARCHAR(10) NOT NULL COMMENT 'Target language',
    translated_string TEXT DEFAULT NULL COMMENT 'Translation',
    translation_status ENUM('pending', 'translated', 'needs_review') DEFAULT 'pending',
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL,
    
    UNIQUE KEY idx_string_lang (string_key(191), language_code, context),
    KEY idx_context (context),
    KEY idx_language (language_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

---

## Class Structure

### Core Classes

```
includes/
├── Core/
│   ├── Plugin.php              # Main plugin singleton
│   ├── Database.php            # Schema management
│   ├── LanguageManager.php     # Language CRUD
│   ├── ContentManager.php      # Translation relationships
│   ├── QueryOptimizer.php      # Query interception
│   └── CacheManager.php        # Cache management
├── Admin/
│   ├── Dashboard.php           # Admin dashboard
│   └── LanguageSettings.php    # Language configuration
└── Frontend/
    ├── LanguageSwitcher.php    # Language switcher
    └── URLManager.php          # URL handling
```

### Class Specifications

#### Plugin.php
```php
namespace MultilingualPressZone\Core;

final class Plugin {
    private static ?self $instance = null;
    private Database $database;
    private LanguageManager $language_manager;
    private ContentManager $content_manager;
    
    public static function instance(): self;
    public function init(): void;
    private function load_dependencies(): void;
    private function register_hooks(): void;
}
```

#### LanguageManager.php
```php
namespace MultilingualPressZone\Core;

class LanguageManager {
    public function get_active_languages(): array;
    public function get_default_language(): string;
    public function get_current_language(): string;
    public function set_current_language(string $code): void;
    public function add_language(array $data): int;
    public function update_language(int $id, array $data): bool;
    public function delete_language(int $id): bool;
}
```

#### ContentManager.php
```php
namespace MultilingualPressZone\Core;

class ContentManager {
    public function get_translations(int $element_id, string $type): array;
    public function get_translation_id(int $element_id, string $lang): ?int;
    public function create_translation(int $source_id, string $lang, array $content): int;
    public function link_translations(array $element_ids, string $type): bool;
    public function get_translation_status(int $element_id): string;
}
```

---

## API Endpoints (Phase 1)

### REST API Routes

```php
// Languages
GET    /wp-json/mpz/v1/languages
POST   /wp-json/mpz/v1/languages
PUT    /wp-json/mpz/v1/languages/{id}
DELETE /wp-json/mpz/v1/languages/{id}

// Translations
GET    /wp-json/mpz/v1/translations/{post_id}
POST   /wp-json/mpz/v1/translations
PUT    /wp-json/mpz/v1/translations/{id}
DELETE /wp-json/mpz/v1/translations/{id}
```

---

## Performance Requirements

### Query Limits
- Max 5 queries per page load
- Max 100ms query execution time
- All queries must use indexes

### Memory Limits
- Max 128MB per request
- Lazy loading for large datasets
- Stream results for bulk operations

### Cache Strategy
- Object cache for all queries (1 hour TTL)
- Transients for language list (24 hour TTL)
- Cache invalidation on updates

---

## Security Requirements

### Input Validation
- Whitelist validation for language codes
- Sanitize all user input
- Type checking with strict types

### Output Escaping
- esc_html() for text content
- esc_attr() for attributes
- esc_url() for URLs
- wp_kses_post() for HTML content

### SQL Security
- Prepared statements for all queries
- No direct SQL concatenation
- Parameterized queries only

### Access Control
- Capability checks on all operations
- Nonce verification for forms
- Permission checks for API endpoints

---

## Testing Requirements

### Unit Tests
- 80%+ code coverage
- Test all public methods
- Mock external dependencies

### Integration Tests
- Test database operations
- Test WordPress integration
- Test cache operations

### Performance Tests
- Benchmark against WPML
- Load test with 100K posts
- Memory profiling

---

## Implementation Checklist

### Week 1: Foundation
- [ ] Plugin structure
- [ ] Database schema
- [ ] Core classes (Plugin, Database)
- [ ] Unit test framework

### Week 2: Core Features
- [ ] LanguageManager implementation
- [ ] ContentManager implementation
- [ ] Query optimization
- [ ] Cache implementation

### Week 3: Admin Interface
- [ ] Language settings page
- [ ] Translation interface
- [ ] Admin dashboard
- [ ] REST API endpoints

### Week 4: Frontend & Testing
- [ ] Language switcher
- [ ] URL management
- [ ] Performance testing
- [ ] Beta customer testing

---

## Success Criteria

### Performance
- ✅ 10x faster than WPML (measured)
- ✅ < 50ms overhead per page
- ✅ < 5 queries per page
- ✅ 80%+ cache hit ratio

### Functionality
- ✅ Add/remove languages
- ✅ Translate posts/pages
- ✅ Language switcher works
- ✅ URL structure works

### Quality
- ✅ 80%+ test coverage
- ✅ No critical bugs
- ✅ Security audit passed
- ✅ Beta customer approval

---

**Status:** Ready for Implementation  
**Next Step:** Create plugin structure and begin coding