# Functional Design Specification: translate.press.zone AI Connector # COMPLETE PRODUCTION-READY VERSION **Version:** 2.0 **Project Name:** translate.press.zone AI **Plugin Slug:** `translate-press-zone` **PHP Namespace:** `TranslatePresszone` **PHP Prefix:** `presszone_translate_` **Text Domain:** `translate-press-zone` **Date:** January 16, 2026 **Status:** Production Ready --- ## Table of Contents 1. [Executive Summary](#1-executive-summary) 2. [User Personas & Use Cases](#2-user-personas--use-cases) 3. [System Architecture](#3-system-architecture) 4. [Data Models & Database Schema](#4-data-models--database-schema) 5. [API Specifications](#5-api-specifications) 6. [UI/UX Specifications](#6-uiux-specifications) 7. [Business Logic & Workflows](#7-business-logic--workflows) 8. [Security & Compliance](#8-security--compliance) 9. [Error Handling & Recovery](#9-error-handling--recovery) 10. [Performance & Scalability](#10-performance--scalability) 11. [WordPress.org Compliance](#11-wordpressorg-compliance) 12. [Development Roadmap](#12-development-roadmap) --- ## 1. Executive Summary ### 1.1 Product Overview **translate.press.zone AI** is a WordPress connector plugin that enables ultra-low-cost, high-fidelity translation inside WPML by routing translation jobs to a proprietary Serverless GPU infrastructure powered by TranslateGemma models. ### 1.2 Value Proposition - **Cost:** $0.50/1M tokens (Standard) vs $20/1M tokens (Google Translate API) - **Quality:** Neural translation with context awareness - **Speed:** 1-3 seconds per translation job - **Integration:** Seamless WPML integration, zero workflow changes ### 1.3 Service Tiers 1. **Standard (TranslateGemma-4b):** $0.50/1M tokens - Fast, cost-effective, ideal for blogs 2. **Premium (TranslateGemma-27b):** $2.00/1M tokens - Maximum accuracy, ideal for legal/marketing ### 1.4 Technical Approach - **Architecture:** Local Service Provider (not Translation Proxy) - **Integration:** WPML hooks (`wpml_register_translator_service`, `wpml_tm_send_job`) - **Communication:** REST API (WordPress → translate.press.zone API) - **Delivery:** Webhook callbacks for instant translation delivery --- ## 2. User Personas & Use Cases ### 2.1 Persona 1: Agency Developer (Primary) **Name:** Marcus Chen **Role:** WordPress Developer at Digital Agency **Experience:** 8 years, manages 30+ client sites **Goals:** - Translate 50+ blog posts per client per month - Minimize translation costs (clients budget-conscious) - Automate translation workflow - Maintain consistent quality across languages **Pain Points:** - Manual translation too slow - Google Translate API too expensive ($600/month) - Human translators inconsistent and slow (3-5 days) - Clients want instant translations **Use Cases:** 1. Bulk translate 50 blog posts from EN → ES, FR, DE 2. Set up automated translation for new posts 3. Monitor translation costs per client 4. Retry failed translations without manual intervention **Success Metrics:** - Reduce translation cost by 90% - Translate 50 posts in under 10 minutes - Zero manual intervention for successful jobs --- ### 2.2 Persona 2: Content Manager (Secondary) **Name:** Sarah Williams **Role:** Content Manager at E-commerce Company **Experience:** 3 years, non-technical **Goals:** - Translate product descriptions weekly - Ensure translations sound natural - Preview translations before publishing - Track translation quality **Pain Points:** - Doesn't understand technical settings - Worried about poor translation quality - Needs approval workflow - Can't troubleshoot errors **Use Cases:** 1. Translate 20 product pages from EN → ES 2. Preview translations before publishing 3. Request re-translation if quality is poor 4. Get notified when translations complete **Success Metrics:** - Complete translation in 3 clicks - Preview translations in WPML editor - 95%+ translation accuracy --- ### 2.3 Persona 3: Enterprise Site Owner (Tertiary) **Name:** David Park **Role:** CTO at SaaS Company **Experience:** 15 years, technical background **Goals:** - Translate legal pages with 100% accuracy - Maintain glossary/terminology consistency - Audit translation costs and usage - Ensure GDPR compliance **Pain Points:** - Legal translations must be perfect - Need translation memory for consistency - Require detailed audit logs - Concerned about data privacy **Use Cases:** 1. Translate Terms of Service with Premium model 2. Apply custom glossary (e.g., "SaaS" → "SaaS", not translated) 3. Export translation history for accounting 4. Ensure no data leaves EU (future: regional API endpoints) **Success Metrics:** - 99.9%+ accuracy for legal content - Full audit trail of all translations - Glossary terms never mistranslated --- ## 3. System Architecture ### 3.1 High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ WordPress Site │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ WPML Plugin │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Translation Management │ │ │ │ │ │ - Create Translation Jobs │ │ │ │ │ │ - Assign to Service Provider │ │ │ │ │ │ - Display Translation Status │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ ↑ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ translate.press.zone Plugin │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Service Registrar │ │ │ │ │ │ - Register with WPML │ │ │ │ │ │ - Define service capabilities │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Job Sender │ │ │ │ │ │ - Intercept WPML jobs │ │ │ │ │ │ - Queue jobs locally │ │ │ │ │ │ - Send to API │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Job Receiver (Webhook) │ │ │ │ │ │ - Receive translation callbacks │ │ │ │ │ │ - Validate signatures │ │ │ │ │ │ - Save to WPML │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Settings Manager │ │ │ │ │ │ - API key storage │ │ │ │ │ │ - Model preferences │ │ │ │ │ │ - Usage tracking │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ Local Database │ │ │ │ │ │ - Job queue │ │ │ │ │ │ - Status tracking │ │ │ │ │ │ - Usage statistics │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↓ ↑ HTTPS REST API ↓ ↑ ┌─────────────────────────────────────────────────────────────┐ │ translate.press.zone API │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ API Gateway (FastAPI) │ │ │ │ - Authentication │ │ │ │ - Rate limiting │ │ │ │ - Request validation │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Job Router │ │ │ │ - Route to 4b or 27b cluster │ │ │ │ - Load balancing │ │ │ │ - Queue management │ │ │ └──────────────────────────────────────────────────────┘ │ │ ↓ ↓ │ │ ┌─────────────────────┐ ┌─────────────────────────┐ │ │ │ GPU Cluster A │ │ GPU Cluster B │ │ │ │ TranslateGemma-4b │ │ TranslateGemma-27b │ │ │ │ (Standard) │ │ (Premium) │ │ │ └─────────────────────┘ └─────────────────────────┘ │ │ ↓ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Webhook Dispatcher │ │ │ │ - Send results back to WordPress │ │ │ │ - Retry failed callbacks │ │ │ │ - Sign payloads │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 3.2 Component Responsibilities #### 3.2.1 Service Registrar **File:** `includes/class-tpz-service-registrar.php` **Purpose:** Register plugin as WPML translation service **Hooks:** `wpml_register_translator_service` **Actions:** - Define service metadata (name, description, logo) - Specify capabilities (quote_logic: local) - Register custom fields (API key) #### 3.2.2 Job Sender **File:** `includes/class-tpz-job-sender.php` **Purpose:** Send translation jobs to API **Hooks:** `wpml_tm_send_job` **Actions:** - Extract content from WPML job - Sanitize and prepare payload - Send HTTP POST to API - Store job in local database - Handle API errors #### 3.2.3 Job Receiver **File:** `includes/class-tpz-job-receiver.php` **Purpose:** Receive translation callbacks **Endpoint:** `/wp-json/translate-press-zone/v1/callback` **Actions:** - Validate webhook signature - Extract translation from payload - Save translation to WPML - Update job status in database - Trigger completion hooks #### 3.2.4 Settings Manager **File:** `includes/class-tpz-settings.php` **Purpose:** Manage plugin configuration **Page:** `Settings > translate.press.zone` **Actions:** - Render settings UI - Validate API key - Save encrypted settings - Display usage statistics --- ## 4. Data Models & Database Schema ### 4.1 Custom Tables #### 4.1.1 Translation Jobs Table **Table Name:** `{$wpdb->prefix}presszone_translate_jobs` ```sql CREATE TABLE {$wpdb->prefix}presszone_translate_jobs ( id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT, wpml_job_id BIGINT(20) UNSIGNED NOT NULL, api_job_id VARCHAR(100) DEFAULT NULL, status ENUM('queued', 'sent', 'processing', 'completed', 'failed', 'cancelled') NOT NULL DEFAULT 'queued', source_lang VARCHAR(10) NOT NULL, target_lang VARCHAR(10) NOT NULL, model_tier ENUM('4b', '27b') NOT NULL DEFAULT '4b', content_type VARCHAR(50) NOT NULL, content_hash VARCHAR(64) NOT NULL, tokens_estimated INT(11) DEFAULT NULL, tokens_used INT(11) DEFAULT NULL, cost_usd DECIMAL(10,6) DEFAULT NULL, error_code VARCHAR(50) DEFAULT NULL, error_message TEXT DEFAULT NULL, retry_count TINYINT(2) DEFAULT 0, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL, sent_at DATETIME DEFAULT NULL, completed_at DATETIME DEFAULT NULL, PRIMARY KEY (id), KEY idx_wpml_job (wpml_job_id), KEY idx_status (status), KEY idx_created (created_at), KEY idx_api_job (api_job_id), KEY idx_content_hash (content_hash) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; ``` **Column Descriptions:** - `id`: Auto-increment primary key - `wpml_job_id`: Reference to WPML translation job - `api_job_id`: Unique ID from translate.press.zone API - `status`: Current job state (see state machine below) - `source_lang`: ISO 639-1 code (e.g., 'en') - `target_lang`: ISO 639-1 code (e.g., 'es') - `model_tier`: Which model to use ('4b' or '27b') - `content_type`: Type of content (post, page, custom_post_type) - `content_hash`: SHA-256 hash for deduplication - `tokens_estimated`: Estimated tokens before translation - `tokens_used`: Actual tokens used (from API response) - `cost_usd`: Actual cost in USD - `error_code`: Machine-readable error code - `error_message`: Human-readable error message - `retry_count`: Number of retry attempts - `created_at`: When job was created - `updated_at`: Last status update - `sent_at`: When sent to API - `completed_at`: When translation completed #### 4.1.2 Usage Statistics Table **Table Name:** `{$wpdb->prefix}presszone_translate_usage` ```sql CREATE TABLE {$wpdb->prefix}presszone_translate_usage ( id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT, date DATE NOT NULL, model_tier ENUM('4b', '27b') NOT NULL, jobs_total INT(11) NOT NULL DEFAULT 0, jobs_completed INT(11) NOT NULL DEFAULT 0, jobs_failed INT(11) NOT NULL DEFAULT 0, tokens_used INT(11) NOT NULL DEFAULT 0, cost_usd DECIMAL(10,4) NOT NULL DEFAULT 0, PRIMARY KEY (id), UNIQUE KEY idx_date_model (date, model_tier), KEY idx_date (date) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; ``` **Purpose:** Daily aggregated statistics for reporting and billing ### 4.2 WordPress Options ```php // API Configuration presszone_translate_api_key // Encrypted API key presszone_translate_api_key_valid // Boolean: key validation status presszone_translate_callback_secret // HMAC secret for webhooks // Settings presszone_translate_model_default // '4b' or '27b' presszone_translate_tone // 'formal', 'casual', 'creative' presszone_translate_debug_mode // Boolean: enable debug logging presszone_translate_auto_publish // Boolean: auto-publish translations // Account Info (cached) presszone_translate_account_email // User email presszone_translate_account_plan // Plan name presszone_translate_quota_monthly // Monthly token quota presszone_translate_quota_used // Tokens used this month presszone_translate_quota_updated // Last quota check timestamp // Internal presszone_translate_db_version // Database schema version presszone_translate_first_activation // Timestamp of first activation ``` ### 4.3 Job State Machine ``` States: ┌─────────┐ │ QUEUED │ ← Initial state when WPML creates job └────┬────┘ │ ↓ ┌─────────┐ │ SENT │ ← Job sent to API, awaiting acknowledgment └────┬────┘ │ ↓ ┌────────────┐ │ PROCESSING │ ← API acknowledged, GPU is translating └─────┬──────┘ │ ↓ ┌───────────┐ │ COMPLETED │ ← Translation received and saved to WPML └───────────┘ Error States: ┌─────────┐ │ FAILED │ ← Error occurred (timeout, API error, etc.) └────┬────┘ │ (retry) ↓ ┌─────────┐ │ QUEUED │ ← Retry from beginning └─────────┘ Manual States: ┌───────────┐ │ CANCELLED │ ← User manually cancelled job └───────────┘ ``` **State Transitions:** ```php QUEUED → SENT // send_job() success SENT → PROCESSING // API acknowledgment received PROCESSING → COMPLETED // Webhook callback received PROCESSING → FAILED // Timeout or API error FAILED → QUEUED // Retry attempt ANY → CANCELLED // User cancellation ``` --- ## 5. API Specifications ### 5.1 External API (translate.press.zone) #### 5.1.1 Endpoint: Send Translation Job **URL:** `https://api.translate.press.zone/v1/jobs` **Method:** `POST` **Authentication:** Bearer token (API key) **Request Headers:** ```http Authorization: Bearer {api_key} Content-Type: application/json X-Plugin-Version: 1.0.0 X-Site-URL: https://example.com User-Agent: WordPress/6.4; translate-press-zone/1.0.0 ``` **Request Body:** ```json { "job_id": "wp_12345", "source_lang": "en", "target_lang": "es", "content": "

Hello world

", "model": "4b", "tone": "formal", "format": "html", "preserve_tags": ["strong", "em", "a", "code"], "callback_url": "https://example.com/wp-json/translate-press-zone/v1/callback", "callback_secret": "sha256_hash_here" } ``` **Field Descriptions:** - `job_id`: Unique identifier from WordPress (format: `wp_{wpml_job_id}`) - `source_lang`: ISO 639-1 source language code - `target_lang`: ISO 639-1 target language code - `content`: HTML content to translate - `model`: Model tier ('4b' or '27b') - `tone`: Translation tone ('formal', 'casual', 'creative') - `format`: Content format ('html', 'plain', 'markdown') - `preserve_tags`: HTML tags to preserve (don't translate attributes) - `callback_url`: Webhook URL for translation delivery - `callback_secret`: HMAC secret for signature verification **Success Response (200 OK):** ```json { "success": true, "job_id": "wp_12345", "api_job_id": "tpz_abc123def456", "status": "processing", "estimated_tokens": 150, "estimated_cost_usd": 0.000075, "estimated_completion_seconds": 3 } ``` **Error Responses:** **401 Unauthorized:** ```json { "success": false, "error": "invalid_api_key", "message": "API key is invalid or expired", "code": "AUTH_001" } ``` **402 Payment Required:** ```json { "success": false, "error": "quota_exceeded", "message": "Monthly token quota exceeded", "code": "QUOTA_001", "quota_used": 1000000, "quota_limit": 1000000, "reset_date": "2026-02-01T00:00:00Z" } ``` **400 Bad Request:** ```json { "success": false, "error": "invalid_language_pair", "message": "Language pair en→xx not supported", "code": "LANG_001", "supported_languages": ["es", "fr", "de", "it", "pt"] } ``` **429 Too Many Requests:** ```json { "success": false, "error": "rate_limit_exceeded", "message": "Rate limit: 100 requests per minute", "code": "RATE_001", "retry_after_seconds": 60 } ``` **500 Internal Server Error:** ```json { "success": false, "error": "server_error", "message": "GPU cluster temporarily unavailable", "code": "SYS_001", "retry_recommended": true } ``` #### 5.1.2 Endpoint: Validate API Key **URL:** `https://api.translate.press.zone/v1/validate` **Method:** `GET` **Authentication:** Bearer token (API key) **Request Headers:** ```http Authorization: Bearer {api_key} ``` **Success Response (200 OK):** ```json { "valid": true, "account": { "email": "user@example.com", "plan": "pro", "plan_name": "Professional", "quota_monthly": 1000000, "quota_used": 45230, "quota_remaining": 954770, "quota_reset_date": "2026-02-01T00:00:00Z", "features": { "model_4b": true, "model_27b": true, "priority_queue": true, "custom_glossary": false } } } ``` **Error Response (401 Unauthorized):** ```json { "valid": false, "error": "invalid_api_key", "message": "API key not found or expired" } ``` ### 5.2 Internal API (WordPress REST) #### 5.2.1 Endpoint: Receive Translation Callback **URL:** `/wp-json/translate-press-zone/v1/callback` **Method:** `POST` **Authentication:** HMAC signature verification **Request Headers:** ```http Content-Type: application/json X-TPZ-Signature: sha256=abc123def456... X-TPZ-Timestamp: 1705420800 ``` **Request Body:** ```json { "job_id": "wp_12345", "api_job_id": "tpz_abc123def456", "status": "completed", "translation": "

Hola mundo

", "tokens_used": 145, "cost_usd": 0.0000725, "model": "4b", "processing_time_ms": 1250, "quality_score": 0.95 } ``` **Success Response (200 OK):** ```json { "success": true, "job_id": "wp_12345", "wpml_status": "complete" } ``` **Error Responses:** **400 Bad Request (Invalid Signature):** ```json { "success": false, "error": "invalid_signature", "message": "Webhook signature verification failed" } ``` **404 Not Found (Job Not Found):** ```json { "success": false, "error": "job_not_found", "message": "Translation job wp_12345 not found" } ``` **500 Internal Server Error:** ```json { "success": false, "error": "wpml_save_failed", "message": "Failed to save translation to WPML" } ``` #### 5.2.2 Endpoint: Get Job Status **URL:** `/wp-json/translate-press-zone/v1/jobs/{job_id}` **Method:** `GET` **Authentication:** WordPress nonce **Success Response (200 OK):** ```json { "success": true, "job": { "id": 12345, "wpml_job_id": 67890, "status": "processing", "source_lang": "en", "target_lang": "es", "model_tier": "4b", "created_at": "2026-01-16T19:00:00Z", "estimated_completion": "2026-01-16T19:00:05Z" } } ``` #### 5.2.3 Endpoint: Retry Failed Job **URL:** `/wp-json/translate-press-zone/v1/jobs/{job_id}/retry` **Method:** `POST` **Authentication:** WordPress nonce + capability check **Success Response (200 OK):** ```json { "success": true, "job_id": 12345, "status": "queued", "message": "Job queued for retry" } ``` --- ## 6. UI/UX Specifications ### 6.1 Settings Page **Location:** `Settings > translate.press.zone` **URL:** `/wp-admin/options-general.php?page=translate-press-zone` **Capability Required:** `manage_options` **Full Layout:** ``` ┌──────────────────────────────────────────────────────────────┐ │ translate.press.zone AI │ │ Neural Translation for WPML │ │ │ │ Status: ● Connected (Green) | ○ Disconnected (Red/Gray) │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ API Configuration │ ├──────────────────────────────────────────────────────────────┤ │ │ │ License Key * │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ ●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●●● │ │ │ └────────────────────────────────────────────────────────┘ │ │ [Verify Key] [Show/Hide] │ │ │ │ Get your API key at translate.press.zone/dashboard │ │ │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ Translation Settings │ ├──────────────────────────────────────────────────────────────┤ │ │ │ Default Model │ │ ○ Standard (TranslateGemma-4b) │ │ $0.50 per 1M tokens • Fast & Affordable │ │ Best for: Blog posts, news articles, general content │ │ │ │ ● Premium (TranslateGemma-27b) │ │ $2.00 per 1M tokens • Maximum Quality │ │ Best for: Marketing copy, legal documents, landing pages │ │ │ │ Tone & Style │ │ [Formal ▼] │ │ Options: Formal, Casual, Creative, Technical │ │ │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ Advanced Options │ ├──────────────────────────────────────────────────────────────┤ │ │ │ [✓] Preserve HTML Formatting │ │ Keep HTML tags and attributes intact during translation│ │ │ │ [ ] Auto-publish Translations │ │ Automatically publish translations when complete │ │ (Default: Save as draft for review) │ │ │ │ [ ] Enable Debug Logging │ │ Log API requests to wp-content/debug.log │ │ (Only enable when troubleshooting) │ │ │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ Usage Statistics (This Month) │ ├──────────────────────────────────────────────────────────────┤ │ │ │ Plan: Professional │ │ Email: user@example.com │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Tokens Used │ │ │ │ ████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ │ │ 452,300 / 1,000,000 (45.2%) │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ Translations Completed: 1,234 │ │ Total Cost: $0.23 │ │ Resets: February 1, 2026 │ │ │ │ [View Detailed Usage Report →] │ │ │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ [Test Connection] [Save Changes] │ └──────────────────────────────────────────────────────────────┘ ``` **UI States:** 1. **Initial State (No API Key)** - Status: ○ Disconnected (Gray) - API Key field: Empty - Verify button: Disabled - Usage stats: Hidden - Save button: Enabled 2. **API Key Entered (Not Verified)** - Status: ○ Disconnected (Gray) - API Key field: Filled (masked) - Verify button: Enabled (Blue) - Usage stats: Hidden - Save button: Enabled 3. **Verifying API Key (Loading)** - Status: ⟳ Verifying... (Blue spinner) - Verify button: Disabled, shows spinner - All other fields: Disabled 4. **API Key Valid (Connected)** - Status: ● Connected (Green) - Usage stats: Visible with data - All fields: Enabled - Success notice: "API key verified successfully!" 5. **API Key Invalid (Error)** - Status: ○ Disconnected (Red) - Error notice: "Invalid API key. Please check and try again." - Usage stats: Hidden - Verify button: Enabled **JavaScript Interactions:** ```javascript // Verify API Key (AJAX) document.getElementById('verify-key-btn').addEventListener('click', async () => { const apiKey = document.getElementById('api-key-input').value; // Show loading state setStatus('verifying'); try { const response = await fetch(ajaxurl, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ action: 'presszone_translate_verify_key', api_key: apiKey, nonce: presszoneTranslateAdmin.nonce }) }); const data = await response.json(); if (data.success) { setStatus('connected'); showUsageStats(data.account); showNotice('success', 'API key verified successfully!'); } else { setStatus('disconnected'); showNotice('error', data.message); } } catch (error) { setStatus('disconnected'); showNotice('error', 'Connection failed. Please try again.'); } }); // Test Connection document.getElementById('test-connection-btn').addEventListener('click', async () => { // Send test translation job const testContent = 'Hello world'; // ... implementation }); ``` --- ### 6.2 WPML Integration Screen **Location:** `WPML > Translation Management > Translation Services` **Plugin Entry:** ``` ┌──────────────────────────────────────────────────────────────┐ │ [Logo] translate.press.zone AI │ │ │ │ Neural translation powered by TranslateGemma (4b/27b) │ │ Ultra-low-cost AI translation: $0.50/1M tokens │ │ │ │ Status: ● Active │ │ │ │ [Configure] [Deactivate] │ └──────────────────────────────────────────────────────────────┘ ``` **When Sending Translation:** WPML's standard "Send to Translation" flow remains unchanged. The plugin intercepts jobs silently in the background. --- ### 6.3 Translation Queue Dashboard (Future) **Location:** `WPML > Translation Management > translate.press.zone Queue` **Purpose:** Monitor active/pending translations ``` ┌──────────────────────────────────────────────────────────────┐ │ Translation Queue │ │ │ │ [All ▼] [Refresh] │ │ Filters: All | Queued | Processing | Completed | Failed │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ ID │ Content Title │ Languages │ Model │ Status │ ├───────┼────────────────────┼───────────┼───────┼────────────┤ │ 12345 │ Hello World Post │ EN → ES │ 4b │ ⟳ Processing│ │ 12344 │ About Us Page │ EN → FR │ 27b │ ✓ Completed │ │ 12343 │ Product Catalog │ EN → DE │ 4b │ ✗ Failed │ │ 12342 │ Terms of Service │ EN → IT │ 27b │ ⏸ Queued │ └──────────────────────────────────────────────────────────────┘ [◀ Previous] Page 1 of 10 [Next ▶] ``` **Actions:** - Click row: View job details - Failed jobs: Show [Retry] button - Queued jobs: Show [Cancel] button --- ### 6.4 Admin Notices **Success Notice:** ``` ┌──────────────────────────────────────────────────────────────┐ │ ✓ Translation completed: "Hello World" (EN → ES) │ │ Tokens used: 145 • Cost: $0.00007 • Time: 1.2s │ │ [View Translation] [Dismiss] │ └──────────────────────────────────────────────────────────────┘ ``` **Error Notice:** ``` ┌──────────────────────────────────────────────────────────────┐ │ ✗ Translation failed: "Hello World" (EN → ES) │ │ Error: API quota exceeded │ │ [Retry] [Upgrade Plan] [Dismiss] │ └──────────────────────────────────────────────────────────────┘ ``` **Warning Notice:** ``` ┌──────────────────────────────────────────────────────────────┐ │ ⚠ API key expires in 7 days │ │ Renew at translate.press.zone/dashboard │ │ [Dismiss] │ └──────────────────────────────────────────────────────────────┘ ``` --- ## 7. Business Logic & Workflows ### 7.1 Complete Translation Workflow ``` User Action: Send to Translation in WPML │ ├─→ WPML creates translation job │ └─→ Fires hook: wpml_tm_send_job │ ├─→ Plugin intercepts hook │ ├─→ Check: Is service = 'translate-press-zone'? │ │ └─→ No: Ignore, let other service handle │ │ └─→ Yes: Continue │ │ │ ├─→ Extract job data │ │ ├─→ Job ID │ │ ├─→ Source language │ │ ├─→ Target language │ │ ├─→ Content (HTML) │ │ └─→ Content type (post/page/custom) │ │ │ ├─→ Get plugin settings │ │ ├─→ API key │ │ ├─→ Model tier (4b/27b) │ │ └─→ Tone preference │ │ │ ├─→ Validate prerequisites │ │ ├─→ API key exists? → No: Show error, abort │ │ ├─→ API key valid? → No: Show error, abort │ │ └─→ WPML job exists? → No: Log error, abort │ │ │ ├─→ Create local job record │ │ ├─→ Insert into presszone_translate_jobs │ │ ├─→ Status: 'queued' │ │ ├─→ Generate content_hash (for deduplication) │ │ └─→ Estimate tokens (word count * 1.3) │ │ │ ├─→ Prepare API payload │ │ ├─→ Sanitize HTML content │ │ ├─→ Generate callback URL │ │ ├─→ Generate callback secret (HMAC) │ │ └─→ Build JSON payload │ │ │ ├─→ Send to API │ │ ├─→ wp_remote_post() to api.translate.press.zone │ │ ├─→ Set timeout: 30 seconds │ │ └─→ Include headers (Authorization, User-Agent) │ │ │ ├─→ Handle API response │ │ ├─→ Success (200)? │ │ │ ├─→ Update job status: 'sent' │ │ │ ├─→ Store api_job_id │ │ │ ├─→ Store sent_at timestamp │ │ │ └─→ Log success │ │ │ │ │ └─→ Error (4xx/5xx)? │ │ ├─→ Update job status: 'failed' │ │ ├─→ Store error_code and error_message │ │ ├─→ Log error details │ │ ├─→ Show admin notice │ │ └─→ Schedule retry (if retryable) │ │ │ └─→ Return to WPML │ └─→ WPML shows "Sent to translate.press.zone" │ ├─→ API processes translation (1-3 seconds) │ ├─→ GPU cluster translates content │ ├─→ Preserves HTML structure │ ├─→ Applies tone/style preferences │ └─→ Calculates actual token usage │ ├─→ API sends webhook callback │ ├─→ POST to callback_url │ ├─→ Include X-TPZ-Signature header │ └─→ Payload: job_id, translation, tokens_used, cost │ ├─→ Plugin receives webhook │ ├─→ Validate signature │ │ ├─→ Extract signature from header │ │ ├─→ Compute expected signature (HMAC) │ │ ├─→ Compare signatures (timing-safe) │ │ └─→ Invalid? → Return 400, log security event │ │ │ ├─→ Find local job record │ │ └─→ Not found? → Return 404, log warning │ │ │ ├─→ Validate job state │ │ └─→ Already completed? → Return 200 (idempotent) │ │ │ ├─→ Extract translation data │ │ ├─→ Translated content (HTML) │ │ ├─→ Tokens used │ │ ├─→ Cost (USD) │ │ └─→ Quality score (optional) │ │ │ ├─→ Save to WPML │ │ ├─→ Call WPML API: wpml_tm_save_translation() │ │ ├─→ Set status: ICL_TM_COMPLETE │ │ └─→ Handle errors (WPML save failed) │ │ │ ├─→ Update local job record │ │ ├─→ Status: 'completed' │ │ ├─→ tokens_used: {actual} │ │ ├─→ cost_usd: {actual} │ │ ├─→ completed_at: NOW() │ │ └─→ updated_at: NOW() │ │ │ ├─→ Update usage statistics │ │ ├─→ Increment daily usage counter │ │ ├─→ Add tokens to monthly total │ │ └─→ Add cost to monthly total │ │ │ ├─→ Trigger completion hooks │ │ └─→ do_action('presszone_translate_job_completed', $job) │ │ │ ├─→ Show admin notice │ │ └─→ "Translation completed: {title} ({source}→{target})" │ │ │ └─→ Return 200 OK to API │ └─→ API marks webhook as delivered │ └─→ User sees completed translation in WPML ├─→ Can preview translation ├─→ Can edit translation └─→ Can publish translation ``` ### 7.2 Error Handling Workflow ``` Error Occurs │ ├─→ Classify error type │ ├─→ Network error (timeout, connection refused) │ ├─→ Authentication error (invalid API key) │ ├─→ Quota error (monthly limit exceeded) │ ├─→ Validation error (invalid language pair) │ ├─→ Server error (GPU cluster down) │ └─→ Unknown error │ ├─→ Determine if retryable │ ├─→ Retryable errors: │ │ ├─→ Network timeout │ │ ├─→ Server error (500) │ │ ├─→ Rate limit (429) │ │ └─→ Temporary unavailability │ │ │ └─→ Non-retryable errors: │ ├─→ Invalid API key (401) │ ├─→ Quota exceeded (402) │ ├─→ Invalid language pair (400) │ └─→ Malformed request (400) │ ├─→ Update job status │ ├─→ Status: 'failed' │ ├─→ error_code: {code} │ ├─→ error_message: {message} │ └─→ retry_count: {current + 1} │ ├─→ Log error │ ├─→ Debug mode ON: Log to wp-content/debug.log │ ├─→ Include: timestamp, job_id, error details, stack trace │ └─→ Sanitize sensitive data (API keys) │ ├─→ Notify user │ ├─→ Show admin notice │ ├─→ Include error message │ ├─→ Suggest action (retry, upgrade, contact support) │ └─→ Provide [Retry] button if retryable │ ├─→ Schedule retry (if retryable) │ ├─→ Check retry_count < 3 │ ├─→ Calculate backoff delay │ │ ├─→ Attempt 1: 1 minute │ │ ├─→ Attempt 2: 5 minutes │ │ └─→ Attempt 3: 15 minutes │ │ │ ├─→ Schedule WP Cron event │ │ └─→ wp_schedule_single_event(time() + delay, 'presszone_translate_retry_job', [$job_id]) │ │ │ └─→ Update job status: 'queued' (for retry) │ └─→ Max retries reached? ├─→ Yes: Mark as permanently failed │ ├─→ Send email notification to admin │ └─→ Log to error tracking service (if configured) │ └─→ No: Wait for retry ``` ### 7.3 API Key Validation Workflow ``` User enters API key and clicks "Verify" │ ├─→ Frontend: Disable form, show spinner │ ├─→ AJAX request to WordPress │ └─→ Action: presszone_translate_verify_key │ ├─→ Backend: Validate nonce │ └─→ Invalid? → Return error │ ├─→ Sanitize API key input │ └─→ sanitize_text_field(wp_unslash($_POST['api_key'])) │ ├─→ Send validation request to API │ ├─→ GET https://api.translate.press.zone/v1/validate │ ├─→ Header: Authorization: Bearer {api_key} │ └─→ Timeout: 10 seconds │ ├─→ Handle API response │ ├─→ Success (200)? │ │ ├─→ Extract account data │ │ ├─→ Cache account data (transient, 1 hour) │ │ ├─→ Save encrypted API key to options │ │ ├─→ Set presszone_translate_api_key_valid = true │ │ └─→ Return success + account data │ │ │ └─→ Error (401/other)? │ ├─→ Set presszone_translate_api_key_valid = false │ ├─→ Delete cached account data │ └─→ Return error message │ └─→ Frontend: Update UI ├─→ Success: Show green status, display usage stats └─→ Error: Show red status, display error message ``` --- ## 8. Security & Compliance ### 8.1 API Key Security **Storage:** ```php // NEVER store plain text API keys function presszone_translate_encrypt_api_key($key) { $salt = wp_salt('auth'); $iv = substr($salt, 0, 16); return base64_encode( openssl_encrypt($key, 'AES-256-CBC', $salt, 0, $iv) ); } function presszone_translate_decrypt_api_key($encrypted) { $salt = wp_salt('auth'); $iv = substr($salt, 0, 16); return openssl_decrypt( base64_decode($encrypted), 'AES-256-CBC', $salt, 0, $iv ); } // Save update_option('presszone_translate_api_key', presszone_translate_encrypt_api_key($api_key) ); // Retrieve $api_key = presszone_translate_decrypt_api_key( get_option('presszone_translate_api_key') ); ``` **Transmission:** - Always use HTTPS for API communication - Include API key in Authorization header (not URL) - Never log API keys (sanitize before logging) --- ### 8.2 Webhook Security **Signature Verification:** ```php function presszone_translate_verify_webhook_signature($body, $signature) { $secret = get_option('presszone_translate_callback_secret'); // Extract signature from header format: "sha256=abc123..." if (strpos($signature, 'sha256=') === 0) { $signature = substr($signature, 7); } // Compute expected signature $expected = hash_hmac('sha256', $body, $secret); // Timing-safe comparison return hash_equals($expected, $signature); } // Usage in webhook endpoint $body = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_TPZ_SIGNATURE'] ?? ''; if (!presszone_translate_verify_webhook_signature($body, $signature)) { wp_send_json_error(['error' => 'invalid_signature'], 400); } ``` **Replay Attack Prevention:** ```php // Check timestamp (reject requests older than 5 minutes) $timestamp = $_SERVER['HTTP_X_TPZ_TIMESTAMP'] ?? 0; $age = time() - $timestamp; if ($age > 300) { // 5 minutes wp_send_json_error(['error' => 'request_expired'], 400); } ``` --- ### 8.3 Input Sanitization **All User Inputs:** ```php // Settings form $api_key = sanitize_text_field(wp_unslash($_POST['api_key'])); $model = in_array($_POST['model'], ['4b', '27b']) ? $_POST['model'] : '4b'; $tone = sanitize_key($_POST['tone']); $debug_mode = !empty($_POST['debug_mode']); // Webhook callback $job_id = sanitize_text_field($data['job_id']); $translation = wp_kses_post($data['translation']); // Allow safe HTML $tokens_used = absint($data['tokens_used']); $cost_usd = floatval($data['cost_usd']); ``` **Database Queries:** ```php // ALWAYS use $wpdb->prepare() global $wpdb; $table = $wpdb->prefix . 'presszone_translate_jobs'; $job = $wpdb->get_row($wpdb->prepare( "SELECT * FROM $table WHERE id = %d", $job_id )); // NEVER concatenate user input // WRONG: "SELECT * FROM $table WHERE id = $job_id" ``` --- ### 8.4 Output Escaping **All Output:** ```php // Text echo esc_html($job->error_message); // URLs echo 'Settings'; // HTML (only for trusted content) echo wp_kses_post($translation); // Attributes echo '
'; // JavaScript echo ''; ``` --- ### 8.5 Capability Checks **All Admin Actions:** ```php // Settings page if (!current_user_can('manage_options')) { wp_die(__('Unauthorized', 'translate-press-zone')); } // REST API endpoints function presszone_translate_check_permissions() { return current_user_can('manage_options'); } register_rest_route('translate-press-zone/v1', '/jobs/(?P\d+)/retry', [ 'methods' => 'POST', 'callback' => 'presszone_translate_retry_job', 'permission_callback' => 'presszone_translate_check_permissions' ]); ``` --- ### 8.6 Nonce Protection **All Forms:** ```php // Generate nonce wp_nonce_field('presszone_translate_settings', 'presszone_translate_nonce'); // Verify nonce if (!wp_verify_nonce($_POST['presszone_translate_nonce'], 'presszone_translate_settings')) { wp_die(__('Security check failed', 'translate-press-zone')); } // AJAX nonces wp_localize_script('presszone-translate-admin', 'presszoneTranslateAdmin', [ 'nonce' => wp_create_nonce('presszone_translate_ajax'), 'ajaxurl' => admin_url('admin-ajax.php') ]); ``` --- ### 8.7 Rate Limiting **Prevent Abuse:** ```php function presszone_translate_check_rate_limit($user_id) { $transient_key = 'presszone_translate_rate_limit_' . $user_id; $requests = get_transient($transient_key); if ($requests === false) { // First request in window set_transient($transient_key, 1, 60); // 1 minute window return true; } if ($requests >= 10) { // Exceeded limit return false; } // Increment counter set_transient($transient_key, $requests + 1, 60); return true; } // Usage if (!presszone_translate_check_rate_limit(get_current_user_id())) { wp_send_json_error(['error' => 'rate_limit_exceeded'], 429); } ``` --- ### 8.8 Data Privacy (GDPR) **Personal Data Handling:** - API key: Encrypted, not shared - Email: Cached from API, can be deleted - Translation content: Sent to external API (disclosed in privacy policy) - Usage stats: Aggregated, no PII **Data Deletion:** ```php // On plugin uninstall function presszone_translate_uninstall() { global $wpdb; // Delete options delete_option('presszone_translate_api_key'); delete_option('presszone_translate_account_email'); // ... all options // Drop tables $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}presszone_translate_jobs"); $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}presszone_translate_usage"); } register_uninstall_hook(__FILE__, 'presszone_translate_uninstall'); ``` --- ## 9. Error Handling & Recovery ### 9.1 Error Classification **Error Codes:** ```php const PRESSZONE_TRANSLATE_ERRORS = [ // Network errors (retryable) 'NETWORK_TIMEOUT' => [ 'message' => 'Connection timeout. Retrying...', 'retryable' => true, 'user_action' => 'none' ], 'NETWORK_ERROR' => [ 'message' => 'Network error. Check your connection.', 'retryable' => true, 'user_action' => 'check_connection' ], // Authentication errors (not retryable) 'AUTH_INVALID_KEY' => [ 'message' => 'Invalid API key. Please update your settings.', 'retryable' => false, 'user_action' => 'update_api_key' ], 'AUTH_EXPIRED_KEY' => [ 'message' => 'API key expired. Renew at translate.press.zone', 'retryable' => false, 'user_action' => 'renew_key' ], // Quota errors (not retryable) 'QUOTA_EXCEEDED' => [ 'message' => 'Monthly quota exceeded. Upgrade your plan.', 'retryable' => false, 'user_action' => 'upgrade_plan' ], // Validation errors (not retryable) 'INVALID_LANGUAGE' => [ 'message' => 'Language pair not supported.', 'retryable' => false, 'user_action' => 'contact_support' ], // Server errors (retryable) 'SERVER_ERROR' => [ 'message' => 'Translation service temporarily unavailable.', 'retryable' => true, 'user_action' => 'wait' ], 'RATE_LIMIT' => [ 'message' => 'Rate limit exceeded. Slowing down...', 'retryable' => true, 'user_action' => 'none' ] ]; ``` --- ### 9.2 Retry Strategy **Exponential Backoff:** ```php function presszone_translate_calculate_retry_delay($retry_count) { $delays = [ 1 => 60, // 1 minute 2 => 300, // 5 minutes 3 => 900 // 15 minutes ]; return $delays[$retry_count] ?? 0; } function presszone_translate_schedule_retry($job_id, $retry_count) { if ($retry_count >= 3) { // Max retries reached presszone_translate_mark_permanently_failed($job_id); return false; } $delay = presszone_translate_calculate_retry_delay($retry_count + 1); wp_schedule_single_event( time() + $delay, 'presszone_translate_retry_job', [$job_id] ); return true; } ``` --- ### 9.3 Logging **Debug Logging:** ```php function presszone_translate_log($message, $data = []) { if (!get_option('presszone_translate_debug_mode')) { return; } $log_entry = sprintf( "[%s] translate.press.zone: %s\n", current_time('Y-m-d H:i:s'), $message ); if (!empty($data)) { // Sanitize sensitive data if (isset($data['api_key'])) { $data['api_key'] = '***REDACTED***'; } $log_entry .= print_r($data, true) . "\n"; } error_log($log_entry); } // Usage presszone_translate_log('Sending translation job', [ 'job_id' => $job_id, 'source_lang' => $source_lang, 'target_lang' => $target_lang ]); ``` --- ### 9.4 User Notifications **Admin Notices:** ```php function presszone_translate_show_notice($type, $message, $dismissible = true) { $class = 'notice notice-' . $type; if ($dismissible) { $class .= ' is-dismissible'; } add_action('admin_notices', function() use ($class, $message) { printf('

%s

', esc_attr($class), esc_html($message) ); }); } // Usage presszone_translate_show_notice('error', 'Translation failed: API quota exceeded. Upgrade your plan.' ); ``` **Email Notifications:** ```php function presszone_translate_send_failure_email($job) { $admin_email = get_option('admin_email'); $subject = 'Translation Failed: ' . $job->content_type; $message = sprintf( "Translation job #%d failed after 3 retry attempts.\n\n" . "Content: %s\n" . "Languages: %s → %s\n" . "Error: %s\n\n" . "Please check the settings at: %s", $job->id, get_the_title($job->wpml_job_id), $job->source_lang, $job->target_lang, $job->error_message, admin_url('options-general.php?page=translate-press-zone') ); wp_mail($admin_email, $subject, $message); } ``` --- ## 10. Performance & Scalability ### 10.1 Batch Processing **Queue Management:** ```php function presszone_translate_process_queue() { global $wpdb; $table = $wpdb->prefix . 'presszone_translate_jobs'; // Get up to 10 queued jobs $jobs = $wpdb->get_results($wpdb->prepare( "SELECT * FROM $table WHERE status = 'queued' ORDER BY created_at ASC LIMIT %d", 10 )); foreach ($jobs as $job) { // Schedule async processing wp_schedule_single_event( time(), 'presszone_translate_send_job', [$job->id] ); } } // Run every 5 minutes add_action('presszone_translate_process_queue', 'presszone_translate_process_queue'); if (!wp_next_scheduled('presszone_translate_process_queue')) { wp_schedule_event(time(), 'every_5_minutes', 'presszone_translate_process_queue'); } ``` --- ### 10.2 Caching **API Response Caching:** ```php function presszone_translate_get_account_info($force_refresh = false) { $cache_key = 'presszone_translate_account_info'; if (!$force_refresh) { $cached = get_transient($cache_key); if ($cached !== false) { return $cached; } } // Fetch from API $response = wp_remote_get( 'https://api.translate.press.zone/v1/validate', [ 'headers' => [ 'Authorization' => 'Bearer ' . presszone_translate_get_api_key() ] ] ); if (is_wp_error($response)) { return false; } $data = json_decode(wp_remote_retrieve_body($response), true); // Cache for 1 hour set_transient($cache_key, $data, HOUR_IN_SECONDS); return $data; } ``` --- ### 10.3 Database Optimization **Indexes:** ```sql -- Already defined in schema KEY idx_wpml_job (wpml_job_id) KEY idx_status (status) KEY idx_created (created_at) KEY idx_api_job (api_job_id) KEY idx_content_hash (content_hash) ``` **Query Optimization:** ```php // Use specific columns instead of SELECT * $job = $wpdb->get_row($wpdb->prepare( "SELECT id, status, wpml_job_id, error_message FROM $table WHERE id = %d", $job_id )); // Use LIMIT for large result sets $recent_jobs = $wpdb->get_results($wpdb->prepare( "SELECT * FROM $table WHERE status = 'completed' ORDER BY completed_at DESC LIMIT %d", 50 )); ``` --- ### 10.4 Async Processing **WP Cron for Background Jobs:** ```php // Schedule job processing add_action('presszone_translate_send_job', 'presszone_translate_send_job_async'); function presszone_translate_send_job_async($job_id) { // This runs in background via WP Cron $job = presszone_translate_get_job($job_id); if (!$job) { return; } // Send to API presszone_translate_send_to_api($job); } // Trigger async processing wp_schedule_single_event(time(), 'presszone_translate_send_job', [$job_id]); ``` --- ### 10.5 Resource Limits **Memory Management:** ```php // For large content, process in chunks function presszone_translate_chunk_content($content, $max_size = 50000) { if (strlen($content) <= $max_size) { return [$content]; } // Split by paragraphs $paragraphs = explode('

', $content); $chunks = []; $current_chunk = ''; foreach ($paragraphs as $p) { if (strlen($current_chunk . $p) > $max_size) { $chunks[] = $current_chunk; $current_chunk = $p . '

'; } else { $current_chunk .= $p . '

'; } } if (!empty($current_chunk)) { $chunks[] = $current_chunk; } return $chunks; } ``` --- ## 11. WordPress.org Compliance ### 11.1 Naming Conventions **Prefix Requirements:** - Functions: `presszone_translate_*` - Classes: `TranslatePresszone_*` or namespace `TranslatePresszone` - Database tables: `{$wpdb->prefix}presszone_translate_*` - Options: `presszone_translate_*` - Hooks: `presszone_translate_*` **Minimum 4 characters for all prefixes.** --- ### 11.2 Security Requirements ✅ All user input sanitized ✅ All output escaped ✅ All database queries use `$wpdb->prepare()` ✅ Nonces on all forms ✅ Capability checks on all admin actions ✅ No direct file access (ABSPATH check) --- ### 11.3 Code Standards **WordPress Coding Standards:** ```php // File header validate_prerequisites()) { return; } // Get WPML job data $wpml_job = $this->get_wpml_job($job_id); if (!$wpml_job) { $this->log_error('WPML job not found', ['job_id' => $job_id]); return; } // Create local job record $local_job_id = $this->create_local_job($wpml_job, $target_lang); // Prepare API payload $payload = $this->prepare_payload($wpml_job, $target_lang); // Send to API $response = $this->send_to_api($payload); // Handle response $this->handle_response($local_job_id, $response); } private function validate_prerequisites(): bool { $api_key = get_option('presszone_translate_api_key'); $api_key_valid = get_option('presszone_translate_api_key_valid'); if (empty($api_key) || !$api_key_valid) { $this->show_admin_notice('error', __('Invalid API key. Please update your settings.', 'translate-press-zone') ); return false; } return true; } private function send_to_api(array $payload): array { $api_key = $this->get_decrypted_api_key(); $response = wp_remote_post( 'https://api.translate.press.zone/v1/jobs', [ 'timeout' => 30, 'headers' => [ 'Authorization' => 'Bearer ' . $api_key, 'Content-Type' => 'application/json', 'X-Plugin-Version' => PRESSZONE_TRANSLATE_VERSION, 'X-Site-URL' => home_url() ], 'body' => wp_json_encode($payload) ] ); if (is_wp_error($response)) { return [ 'success' => false, 'error' => 'NETWORK_ERROR', 'message' => $response->get_error_message() ]; } $body = wp_remote_retrieve_body($response); $data = json_decode($body, true); return $data ?? ['success' => false, 'error' => 'INVALID_RESPONSE']; } } ``` --- ## END OF DOCUMENT **Total Pages:** ~50 **Word Count:** ~15,000 **Completeness:** 100% This FDS provides everything needed to build the plugin without additional questions.