# Implementation Plan: WPML Alternative Integration (A+B+C+D)

## Overview

Since WPML does not expose a public API for registering custom automatic translation engines, we will implement four alternative integration approaches that work alongside WPML.

**Project:** translate-press-zone
**Namespace:** `TranslatePresszone`
**Text Domain:** `translate-press-zone`

---

## Architecture

### New File Structure

```
translate-press-zone/
├── includes/
│   ├── class-tpz-translation-service.php   # Core API client (NEW)
│   ├── class-tpz-wpml-bridge.php           # WPML save/link helper (NEW)
│   ├── class-tpz-metabox.php               # Option A: Post editor meta box (NEW)
│   ├── class-tpz-bulk-actions.php          # Option D: Bulk actions (NEW)
│   └── ... (existing files)
├── admin/
│   ├── class-tpz-dashboard.php             # Option B: Dashboard controller (NEW)
│   ├── class-tpz-editor-integration.php    # Option C: Editor integration (NEW)
│   ├── views/
│   │   ├── dashboard-page.php              # Option B: Dashboard HTML (NEW)
│   │   └── metabox.php                     # Option A: Meta box HTML (NEW)
│   ├── css/
│   │   ├── admin.css                       # (existing)
│   │   └── dashboard.css                   # Option B: Dashboard styles (NEW)
│   └── js/
│       ├── admin.js                        # (existing)
│       ├── metabox.js                      # Option A: Meta box JS (NEW)
│       ├── dashboard.js                    # Option B: Dashboard JS (NEW)
│       └── editor-integration.js           # Option C: Editor JS (NEW)
```

---

## Phase 0: Core Services (PREREQUISITE)

These must be completed first as all options depend on them.

### Task 0.1: Translation Service Class
**Agent:** `api-integration-expert`
**File:** `includes/class-tpz-translation-service.php`
**Dependencies:** None

Create unified translation service that:
- Accepts source text, source_lang, target_lang
- Calls translate.press.zone API
- Returns translated text
- Handles errors uniformly
- Supports both sync (small content) and async (webhook) modes

```php
class TranslationService {
    public function translate(string $content, string $source_lang, string $target_lang): TranslationResult;
    public function translate_async(int $post_id, string $source_lang, string $target_lang): void;
    public function estimate_tokens(string $content): int;
}
```

### Task 0.2: WPML Bridge Class
**Agent:** `api-integration-expert`
**File:** `includes/class-tpz-wpml-bridge.php`
**Dependencies:** None

Create WPML integration helper that:
- Creates translation post in correct language
- Links translation to original using `wpml_set_element_language_details`
- Copies post meta, taxonomies, featured image
- Handles post types (post, page, custom)
- Returns new translation post ID

```php
class WPMLBridge {
    public function create_translation(int $original_post_id, string $target_lang, string $translated_content, string $translated_title): int;
    public function get_missing_translations(int $post_id): array;
    public function get_original_post(int $post_id): ?WP_Post;
    public function is_wpml_active(): bool;
}
```

---

## Phase 1: Parallel Implementation (A + D)

These can run in parallel as they don't share files.

### Option A: Post Editor Meta Box

#### Task A.1: Meta Box PHP Controller
**Agent:** `frontend-php-expert`
**File:** `includes/class-tpz-metabox.php`
**Dependencies:** Task 0.1, 0.2

- Register meta box for post, page, and custom post types
- Hook: `add_meta_boxes`
- Check if WPML is active
- Get available target languages from WPML
- Register AJAX handlers:
  - `wp_ajax_presszone_translate_post`
  - `wp_ajax_presszone_translate_status`

#### Task A.2: Meta Box View
**Agent:** `admin-panel-expert`
**File:** `admin/views/metabox.php`
**Dependencies:** Task A.1

HTML structure:
- Current language indicator
- Target language checkboxes (from WPML)
- Model tier selector (4b/27b)
- "Translate" button
- Progress/status area
- Link to view translation when complete

#### Task A.3: Meta Box JavaScript
**Agent:** `frontend-js-expert`
**File:** `admin/js/metabox.js`
**Dependencies:** Task A.1, A.2

- Handle translate button click
- AJAX call to translate endpoint
- Show progress indicator
- Poll for status if async
- Display success/error messages
- Update UI with translation links

#### Task A.4: Meta Box Styles
**Agent:** `frontend-styling-expert`
**File:** `admin/css/admin.css` (append)
**Dependencies:** Task A.2

- Meta box layout
- Language checkbox grid
- Progress indicator
- Status messages
- Responsive design

---

### Option D: Bulk Actions (Parallel with A)

#### Task D.1: Bulk Actions Controller
**Agent:** `frontend-php-expert`
**File:** `includes/class-tpz-bulk-actions.php`
**Dependencies:** Task 0.1, 0.2

- Add bulk action to posts list: `bulk_actions-edit-post` filter
- Add bulk action to pages list: `bulk_actions-edit-page` filter
- Handle bulk action: `handle_bulk_actions-edit-post` filter
- Process selected posts
- Queue translations
- Redirect with admin notice

Functions:
```php
public function add_bulk_actions(array $actions): array;
public function handle_bulk_action(string $redirect_to, string $action, array $post_ids): string;
private function queue_translations(array $post_ids, string $target_lang): int;
```

#### Task D.2: Bulk Action Modal (Optional Enhancement)
**Agent:** `admin-panel-expert`
**File:** `admin/js/bulk-actions.js`
**Dependencies:** Task D.1

- Intercept bulk action submit
- Show modal for language selection
- Confirm before processing
- Optional: show progress for large batches

---

## Phase 2: Dashboard Implementation (B)

### Option B: Bulk Translation Dashboard

#### Task B.1: Dashboard Controller
**Agent:** `admin-panel-expert`
**File:** `admin/class-tpz-dashboard.php`
**Dependencies:** Task 0.1, 0.2

- Register admin menu: `WPML → translate.press.zone` or `Tools → translate.press.zone`
- Permission: `manage_options`
- List posts with missing translations
- Pagination support
- Filter by post type, language
- AJAX handlers:
  - `wp_ajax_presszone_dashboard_translate`
  - `wp_ajax_presszone_dashboard_translate_all`
  - `wp_ajax_presszone_dashboard_status`

#### Task B.2: Dashboard View
**Agent:** `admin-panel-expert`
**File:** `admin/views/dashboard-page.php`
**Dependencies:** Task B.1

Structure:
- Header with stats (X posts need translation)
- Filters: post type, source language, target language
- Table with columns:
  - Checkbox
  - Title
  - Post Type
  - Source Language
  - Missing Languages (badges)
  - Actions (Translate button)
- Bulk actions bar (Translate Selected, Translate All)
- Progress modal for bulk operations

#### Task B.3: Dashboard JavaScript
**Agent:** `frontend-js-expert`
**File:** `admin/js/dashboard.js`
**Dependencies:** Task B.1, B.2

- Table row selection (select all, individual)
- Filter form submission (AJAX reload)
- Single post translate button
- Bulk translate with progress
- Real-time status updates
- Success/error notifications

#### Task B.4: Dashboard Styles
**Agent:** `frontend-styling-expert`
**File:** `admin/css/dashboard.css`
**Dependencies:** Task B.2

- Dashboard layout (header, filters, table)
- Table styling with hover states
- Language badges
- Progress modal
- Responsive design
- Dark mode support

---

## Phase 3: Editor Integration (C)

### Option C: WPML Translation Editor Integration

#### Task C.1: Editor Integration Controller
**Agent:** `api-integration-expert`
**File:** `admin/class-tpz-editor-integration.php`
**Dependencies:** Task 0.1

- Detect WPML translation editor page
- Hook: `admin_enqueue_scripts` with page check
- Enqueue integration script
- AJAX handler: `wp_ajax_presszone_autofill_translation`
- Fetch original content, translate, return structured data

#### Task C.2: Editor Integration JavaScript
**Agent:** `frontend-js-expert`
**File:** `admin/js/editor-integration.js`
**Dependencies:** Task C.1

- Detect WPML Advanced Translation Editor
- Inject "Auto-fill with AI" button in toolbar
- On click:
  - Collect all source fields
  - Send to translation API
  - Populate all target fields with translations
- Show progress during translation
- Handle errors gracefully

#### Task C.3: Editor Integration Styles
**Agent:** `frontend-styling-expert`
**File:** `admin/css/admin.css` (append)
**Dependencies:** Task C.2

- Auto-fill button styling (match WPML UI)
- Loading state
- Success/error indicators

---

## Phase 4: Integration & Testing

### Task 4.1: Update Plugin Bootstrap
**Agent:** `frontend-php-expert`
**File:** `includes/class-tpz-plugin.php`
**Dependencies:** All Phase 0-3 tasks

- Load new classes
- Initialize components conditionally:
  - MetaBox: always on post edit screens
  - BulkActions: always on post list screens
  - Dashboard: always in admin
  - EditorIntegration: only if WPML detected

### Task 4.2: Update Database Schema
**Agent:** `database-expert`
**File:** `includes/class-tpz-database.php`
**Dependencies:** None

Add columns to jobs table:
- `post_id` - WordPress post ID
- `translation_post_id` - Created translation post ID
- `integration_type` - ENUM('metabox', 'bulk', 'dashboard', 'editor')

---

## Execution Order & Parallelization

```
┌─────────────────────────────────────────────────────────────┐
│ PHASE 0: Core Services (Sequential - Prerequisites)         │
│                                                             │
│   Task 0.1 ──────► Task 0.2                                │
│   (TranslationService)  (WPMLBridge)                       │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 1: Parallel Batch 1                                   │
│                                                             │
│   ┌─────────────────┐     ┌─────────────────┐              │
│   │ OPTION A        │     │ OPTION D        │              │
│   │ (Meta Box)      │     │ (Bulk Actions)  │              │
│   │                 │     │                 │              │
│   │ A.1 → A.2       │     │ D.1 → D.2       │              │
│   │      ↓          │     │                 │              │
│   │ A.3 + A.4       │     │                 │              │
│   │ (parallel)      │     │                 │              │
│   └─────────────────┘     └─────────────────┘              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 2: Parallel Batch 2                                   │
│                                                             │
│   ┌─────────────────┐     ┌─────────────────┐              │
│   │ OPTION B        │     │ OPTION C        │              │
│   │ (Dashboard)     │     │ (Editor)        │              │
│   │                 │     │                 │              │
│   │ B.1 → B.2       │     │ C.1 → C.2       │              │
│   │      ↓          │     │      ↓          │              │
│   │ B.3 + B.4       │     │     C.3         │              │
│   │ (parallel)      │     │                 │              │
│   └─────────────────┘     └─────────────────┘              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ PHASE 4: Integration (Sequential)                           │
│                                                             │
│   Task 4.1 ──────► Task 4.2                                │
│   (Bootstrap)       (Database)                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Agent Assignments Summary

| Task | Agent | Files | Parallel Group |
|------|-------|-------|----------------|
| 0.1 | api-integration-expert | class-tpz-translation-service.php | Phase 0 |
| 0.2 | api-integration-expert | class-tpz-wpml-bridge.php | Phase 0 |
| A.1 | frontend-php-expert | class-tpz-metabox.php | Phase 1A |
| A.2 | admin-panel-expert | metabox.php | Phase 1A |
| A.3 | frontend-js-expert | metabox.js | Phase 1A |
| A.4 | frontend-styling-expert | admin.css | Phase 1A |
| D.1 | frontend-php-expert | class-tpz-bulk-actions.php | Phase 1D |
| D.2 | admin-panel-expert | bulk-actions.js | Phase 1D |
| B.1 | admin-panel-expert | class-tpz-dashboard.php | Phase 2B |
| B.2 | admin-panel-expert | dashboard-page.php | Phase 2B |
| B.3 | frontend-js-expert | dashboard.js | Phase 2B |
| B.4 | frontend-styling-expert | dashboard.css | Phase 2B |
| C.1 | api-integration-expert | class-tpz-editor-integration.php | Phase 2C |
| C.2 | frontend-js-expert | editor-integration.js | Phase 2C |
| C.3 | frontend-styling-expert | admin.css | Phase 2C |
| 4.1 | frontend-php-expert | class-tpz-plugin.php | Phase 4 |
| 4.2 | database-expert | class-tpz-database.php | Phase 4 |

---

## Parallel Execution Plan

### Batch 1 (Phase 0) - Sequential
```
Agent: api-integration-expert
Tasks: 0.1, 0.2
```

### Batch 2 (Phase 1) - 2 Parallel Agents
```
Agent 1: frontend-php-expert + admin-panel-expert + frontend-js-expert + frontend-styling-expert
  → Tasks: A.1, A.2, A.3, A.4 (Option A complete)

Agent 2: frontend-php-expert + admin-panel-expert
  → Tasks: D.1, D.2 (Option D complete)
```

### Batch 3 (Phase 2) - 2 Parallel Agents
```
Agent 1: admin-panel-expert + frontend-js-expert + frontend-styling-expert
  → Tasks: B.1, B.2, B.3, B.4 (Option B complete)

Agent 2: api-integration-expert + frontend-js-expert + frontend-styling-expert
  → Tasks: C.1, C.2, C.3 (Option C complete)
```

### Batch 4 (Phase 4) - Sequential
```
Agent: frontend-php-expert + database-expert
Tasks: 4.1, 4.2
```

---

## Success Criteria

### Option A (Meta Box)
- [ ] Meta box appears on post/page edit screens
- [ ] Shows available target languages from WPML
- [ ] Translate button triggers API call
- [ ] Translation saved and linked in WPML
- [ ] Success message with link to translation

### Option B (Dashboard)
- [ ] Menu item appears under WPML or Tools
- [ ] Lists all posts with missing translations
- [ ] Filter by post type and language works
- [ ] Single post translation works
- [ ] Bulk translation works with progress
- [ ] Translations linked correctly in WPML

### Option C (Editor Integration)
- [ ] Auto-fill button appears in WPML editor
- [ ] Clicking fetches and fills all fields
- [ ] Progress indicator during translation
- [ ] User can review before saving

### Option D (Bulk Actions)
- [ ] Bulk action appears in posts/pages list
- [ ] Selecting posts and applying works
- [ ] Admin notice shows results
- [ ] Translations created and linked

---

## Security Requirements

All implementations must:
- Verify nonces on all AJAX calls
- Check `current_user_can('edit_posts')` or appropriate capability
- Sanitize all inputs
- Escape all outputs
- Use `$wpdb->prepare()` for queries
- Log errors appropriately

---

## Notes

- WPML detection: Check `defined('ICL_SITEPRESS_VERSION')`
- Language codes: Use WPML's language codes (en, es, fr, etc.)
- Post linking: Use `wpml_set_element_language_details` action
- Translation status: WPML uses `icl_translations` table