# Functional Design Specification: translate.press.zone AI Connector

**Version:** 1.1  
**Project Name:** translate.press.zone AI  
**Plugin Slug:** `translate-press-zone-ai`  
**PHP Prefix:** `TPZ_`  
**Date:** January 16, 2026  
**Status:** Ready for Development  

---

## 1. Executive Summary
**translate.press.zone AI** is a WordPress connector plugin that enables ultra-low-cost, high-fidelity translation inside WPML by routing traffic to a proprietary Serverless GPU infrastructure.

It bridges the gap between WordPress content and open-source models, offering two distinct tiers of service:
1.  **Standard (TranslateGemma-4b):** High speed, extremely low cost ($0.50/1M tokens), ideal for bulk content and blogs.
2.  **Premium (TranslateGemma-27b):** Maximum nuance and reasoning, ideal for landing pages, legal text, and complex creative copy.

---

## 2. System Architecture

### 2.1 The "Connector" Model
Instead of acting as a full "Translation Proxy" (which requires complex XML-RPC servers), this plugin functions as a **Local Service Provider**. It sits inside WordPress, intercepts jobs, and communicates via REST API to the `translate.press.zone` backend.

### 2.2 Data Flow Diagram

[ WordPress Admin ] | v [ WPML "Translation Basket" ] | v [ TPZ Connector Plugin ] <-- (Converts WP Jobs to JSON) | v (HTTPS POST) [ translate.press.zone API ] | +--> [ Routing Layer ] | +--> [ GPU Cluster A: TranslateGemma-4b (Standard) ] | +--> [ GPU Cluster B: TranslateGemma-27b (Premium) ]


---

## 3. User Experience (UI/UX)

### 3.1 Screen 1: Plugin Configuration (Settings)
**Location:** `Settings > translate.press.zone`

**UI Elements:**
1.  **Header:** Logo + Connection Status (Red "Disconnected" / Green "Active").
2.  **API Key Input:**
    * Label: "License Key"
    * Input: `text` (masked)
    * Description: "Enter your key from [translate.press.zone/dashboard]."
    * Action: `Verify Key` (AJAX button).
3.  **Model Selection (Global Default):**
    * Dropdown:
        * `Standard - TranslateGemma-4b (Best Value)`
        * `Premium - TranslateGemma-27b (Best Quality)`
    * *Note: This sets the default flag sent to the API.*
4.  **Tone & Context (Optional):**
    * Dropdown: `Formal`, `Casual`, `Creative`.
    * *Technical Note: This appends a system prompt instruction to the API payload.*
5.  **Debug Mode:** Toggle switch to log API payloads to `wp-content/debug.log`.

### 3.2 Screen 2: WPML Service Activation
**Location:** `WPML > Translation Management > Translation Services`

* **Integration:** The plugin automatically injects itself into this list using the `wpml_register_translator_service` hook.
* **Visuals:**
    * **Name:** `translate.press.zone AI`
    * **Logo:** (Plugin Asset)
    * **Description:** "Neural translation powered by TranslateGemma (4b/27b)."
    * **Action:** "Activate" button.

---

## 4. Technical Specification: The WPML Hook System

### 4.1 Service Registration
We use the `wpml_register_translator_service` hook. This tells WPML that a local translator exists and is ready to accept jobs.

**File:** `includes/class-tpz-service-registrar.php`

```php
class TPZ_Service_Registrar {

    public static function register() {
        add_action( 'wpml_register_translator_service', array( __CLASS__, 'define_service' ) );
    }

    public static function define_service( $services ) {
        $service_data = array(
            'id'                 => 'translate-press-zone', // Unique ID
            'name'               => 'translate.press.zone AI',
            'description'        => 'High-fidelity AI translation (Gemma 4b/27b).',
            'doc_url'            => '[https://translate.press.zone/docs](https://translate.press.zone/docs)',
            'quote_logic'        => 'local', // Crucial: Bypasses remote polling
            'url'                => '[https://translate.press.zone](https://translate.press.zone)',
            'has_settings'       => true,
            'custom_fields_data' => array(
                'api_key' => array(
                    'label'       => 'API Key',
                    'type'        => 'text',
                    'required'    => true
                )
            )
        );

        // Register the service
        do_action( 'wpml_register_translation_service', $service_data );
    }
}

4.2 Sending Jobs (The Interceptor)

When a user clicks "Send to Translation", WPML creates "Translation Jobs". We hook into this event to grab the content and send it to our API.

Hook: wpml_tm_send_job

File: includes/class-tpz-job-sender.php

Logic Flow:

    Verify the job is assigned to translate-press-zone.

    Retrieve job details (ID, Source Lang, Target Lang, Content).

    Sanitize HTML (ensure specific tags like shortcodes are protected).

    Dispatch to API.

Code Stub:
PHP

public function send_job( $job_id, $service, $target_lang ) {
    if ( 'translate-press-zone' !== $service ) {
        return;
    }

    // 1. Get Job Data
    $job_entity = new WPML_TM_Job_Entity( $job_id );
    $original_text = $job_entity->get_original_element()->get_content();
    
    // 2. Get Plugin Settings (Model Preference)
    $model_tier = get_option('tpz_model_tier', '4b'); // '4b' or '27b'

    // 3. Prepare Payload
    $payload = array(
        'job_id'      => $job_id,
        'source_lang' => $job_entity->get_source_language(),
        'target_lang' => $target_lang,
        'content'     => $original_text,
        'model'       => $model_tier,
        'format'      => 'html'
    );

    // 4. Send to External API
    $response = wp_remote_post( '[https://api.translate.press.zone/v1/jobs](https://api.translate.press.zone/v1/jobs)', array(
        'body'    => json_encode( $payload ),
        'headers' => array(
            'Authorization' => 'Bearer ' . get_option('tpz_api_key'),
            'Content-Type'  => 'application/json'
        )
    ) );
}

4.3 Receiving Translations (The Callback)

Since AI translation is near-instant (seconds), we can use a webhook approach. The API will POST back to the WordPress site when done.

Endpoint: https://client-site.com/wp-json/tpz/v1/callback

File: includes/class-tpz-job-receiver.php

Logic:

    Receive JSON payload (job_id, translated_text).

    Validate secret hash (security).

    Insert translation into WPML tables.

Code Stub:
PHP

public function handle_callback( $request ) {
    $job_id = $request->get_param( 'job_id' );
    $translation = $request->get_param( 'translation' );

    // WPML API to save the translation
    // This updates the status to "Complete" in the UI
    wpml_tm_save_translation( array(
        'job_id'      => $job_id,
        'translation' => $translation,
        'status'      => ICL_TM_COMPLETE
    ));

    return new WP_REST_Response( array( 'success' => true ), 200 );
}

5. Security & Validation

    API Key Validation:

        On the settings screen, when the user clicks "Connect", send a dummy request to api.translate.press.zone/v1/validate.

        Store the key only if the API returns 200 OK + quota_remaining.

    HTML Tag Protection:

        Risk: The AI might translate <div class="red"> to <div class="rojo">.

        Solution: The Python backend (Serverless) must use regex to mask HTML tags before feeding into TranslateGemma, or use TranslateGemma's specific "HTML Mode" system prompts.

    Nonce Security:

        All plugin settings forms must use check_admin_referer.

        The Callback API must require a X-TPZ-Signature header to prevent spoofing.

6. Development Checklist
Phase 1: The Plugin Skeleton

    [ ] Create translate-press-zone-ai directory.

    [ ] Setup includes/ folder structure.

    [ ] Create the Settings Page UI (HTML/CSS).

    [ ] Implement TPZ_Service_Registrar and verify it appears in WPML.

Phase 2: The Logic

    [ ] Implement TPZ_Job_Sender.

    [ ] Create a "Mock API" (using Postman or simple PHP script) to test sending data.

    [ ] Implement TPZ_Job_Receiver (REST API Endpoint).

    [ ] Test the full loop: Send Job -> Mock API -> Callback -> WPML shows "Complete".

Phase 3: The AI Integration

    [ ] Connect TPZ_Job_Sender to the real Python/GPU API.

    [ ] Add error handling (e.g., if user has 0 credits, set WPML job status to "Error" and display message).

Phase 4: Polish

    [ ] Add specific support for TranslateGemma-27b toggle in UI.

    [ ] Add "Test Translation" button in settings to verify GPU is waking up.