# Manual de desarrollador — Traductor Digixop Pro

**Versión:** alineada con el plugin **2.0.11**.  
**Audiencia:** integradores, agencias y equipos que despliegan el plugin, conectan **Google Cloud** en modo BYO o montan **proxy / licencias propios**.

> **Seguridad:** este documento describe **nombres** de opciones, constantes, endpoints y formularios. **No** incluye claves API, secretos de webhook, contraseñas de base de datos ni datos reales de producción. Esas credenciales solo en **`wp-config.php`**, variables de entorno del servidor o gestores secretos, **nunca** en el repositorio público.

---

## Índice

1. [Arquitectura en una página](#1-arquitectura-en-una-página)
2. [Arranque del plugin y archivos clave](#2-arranque-del-plugin-y-archivos-clave)
3. [Opciones y metadatos en WordPress](#3-opciones-y-metadatos-en-wordpress)
4. [Constantes `wp-config.php` (referencia)](#4-constantes-wp-configphp-referencia)
5. [Modo BYO: conectar tu propio Google Cloud](#5-modo-byo-conectar-tu-propio-google-cloud)
6. [Modo DTL: contrato del proxy (sin secretos)](#6-modo-dtl-contrato-del-proxy-sin-secretos)
7. [Activación de licencia (cliente → tu servidor)](#7-activación-de-licencia-cliente--tu-servidor)
8. [Memoria de traducción (tabla local)](#8-memoria-de-traducción-tabla-local)
9. [AJAX administrativo (`action` names)](#9-ajax-administrativo-action-names)
10. [Filtros y acciones (extensión)](#10-filtros-y-acciones-extensión)
11. [WPML, Elementor y huella del original](#11-wpml-elementor-y-huella-del-original)
12. [Empaquetado y depuración](#12-empaquetado-y-depuración)
13. [Referencias](#13-referencias)

---

## 1. Arquitectura en una página

```
┌───────────────────── WordPress ─────────────────────┐
│  Traductor Digixop Pro                             │
│  ├─ UI: admin-unified-view.php                     │
│  ├─ Lógica: class-digixop-translator-lite.php      │
│  ├─ Licencia: class-digixop-translator-license.php │
│  └─ TM: class-digixop-translation-cache.php      │
│         └── tabla {prefix}dx_translations_cache    │
└──────────────────────┬───────────────────────────┘
                         │
         ┌───────────────┴───────────────┐
         ▼                               ▼
   translation_mode=DTL          translation_mode=BYO
         │                               │
         ▼                               ▼
  HTTPS POST JSON                 Google Translate API v2
  a tu translate-proxy.php      (clave en ajustes o env)
```

- **DTL:** el navegador del admin no llama a Google; el **servidor WordPress** llama a **tu** proxy. El proxy (en tu infra) valida licencia/saldo y llama a Google con una clave **solo de servidor**.
- **BYO:** el **mismo** servidor WordPress llama a Google con la API Key configurada (idealmente restringida en Google Cloud).

---

## 2. Arranque del plugin y archivos clave

| Ruta | Rol |
|------|-----|
| `traductor-digixop-pro.php` | Constantes por defecto, carga de includes, activación (opciones + creación de tabla TM). |
| `includes/class-digixop-translator-lite.php` | Núcleo: traducción, AJAX, listados, WPML/ACF/Elementor. |
| `includes/class-digixop-translator-license.php` | POST a `activate-license.php`, transient de caché, saldo local. |
| `includes/class-digixop-translation-cache.php` | PDO/wpdb sobre `dx_translations_cache`. |
| `includes/admin-unified-view.php` | Plantilla del escritorio unificado. |
| `includes/digixop-translator-languages.php` | Mapas de idiomas y etiquetas. |

El text domain del plugin es **`traductor-digixop-lite`** (histórico); las traducciones `.po` van bajo `languages/`.

---

## 3. Opciones y metadatos en WordPress

| Clave / constante | Uso |
|-------------------|-----|
| `digixop_translator_lite_options` (`Digixop_Translator_Lite::OPTION_KEY`) | Modo DTL/BYO, idiomas, tipos de entrada, flags ACF/Elementor/SEO, memoria, glosarios, blacklist. |
| `digixop_translator_license` (`OPTION_EXT_STATE`) | Estado de licencia devuelto por tu API (clave, IDs, fechas). |
| `digixop_translator_local_balance_remaining` | Saldo mostrado en UI; se actualiza tras respuestas exitosas del proxy. |
| `digixop_translator_local_expiration_date` | Caducidad mostrada. |
| `digixop_tdl_ext_cached` (transient) | Caché 24 h de validez para reducir llamadas. |
| `_digixop_src_fingerprint` (post meta en traducción) | Huella del original para retraducción condicional. |

**No** guardes secretos de servidor en `wp_options` salvo que aceptes el riesgo: para BYO la API Key puede ir en **variables de entorno** o constantes PHP si adaptas el despliegue (el plugin admite clave en ajustes para el flujo estándar).

---

## 4. Constantes `wp-config.php` (referencia)

Definir **antes** de cargar el plugin. Valores sensibles: usar placeholders en documentación (`https://tu-api.example/...`).

| Constante | Propósito |
|-----------|-----------|
| `DIGIXOP_SAAS_API_BASE` | Base URL de tu API (si centralizas rutas). |
| `DIGIXOP_TDL_TRANSLATE_PROXY_URL` | URL completa del script proxy de traducción (HTTPS). |
| `DIGIXOP_TDL_LICENSE_ACTIVATE_URL` | URL de activación JSON. |
| `DIGIXOP_TDL_LICENSE_DEACTIVATE_URL` | URL de desactivación. |
| `DIGIXOP_TDL_PROXY_USE_JSON` | `true` (recomendado): cuerpo JSON al proxy; `false`: form-urlencoded legacy. |
| `DIGIXOP_TDL_BUY_CREDITS_URL` | URL del checkout o página de recarga (UI). |
| `DIGIXOP_TDL_BUY_CREDITS_LICENSE_PARAM` | Nombre del parámetro query para adjuntar licencia; vacío para desactivar. |
| `DIGIXOP_TDL_ELEMENTOR_SAFE_COPY` | `true`: copiar `_elementor_data` sin traducir (diagnóstico). |
| `DIGIXOP_TRANSLATOR_DEBUG` | Logs más verbosos en entornos controlados. |

Lista breve también en `README.md` de la raíz del repositorio.

---

## 5. Modo BYO: conectar tu propio Google Cloud

Objetivo: que el sitio WordPress llame a **`https://translation.googleapis.com/language/translate/v2`** con credenciales de **tu** proyecto.

### Checklist (sin valores secretos)

1. Crea un **proyecto** en [Google Cloud Console](https://console.cloud.google.com/).
2. Habilita la API **Cloud Translation API**.
3. Crea credenciales tipo **API key** (v2 usa API key, no cuenta de servicio para este flujo del plugin).
4. **Restringe la clave** en Google: por IP del servidor, por referrer HTTP (si aplica), y por API (solo Translation). Así una filtración en BD de WordPress da menos superficie de abuso.
5. En WordPress: **Traductor Digixop → Ajustes**, modo **BYO**, pega la clave solo si tu política de seguridad lo permite; alternativa: inyectar la clave vía constante/entorno si extendéis el plugin (requiere código propio).
6. Controla **cuotas y facturación** en Google; el plugin no implementa “tope” propio en BYO más allá de lo que devuelva Google.

Nunca commitees la clave en Git ni la pegues en tickets de soporte públicos.

---

## 6. Modo DTL: contrato del proxy (sin secretos)

El cliente envía un **POST HTTPS** a `DIGIXOP_TDL_TRANSLATE_PROXY_URL`. Detalle de campos, cabeceras y códigos: **`docs/API-SAAS.md`**.

Resumen para implementar tu propio proxy:

- Lee `license_key`, `source_lang`, `target_lang`, array `texts` (y opcionalmente `google_format`, `system_prompt`, `site_url`).
- Valida la licencia contra **tu** almacén (p. ej. MySQL).
- Descuenta saldo **de forma coherente** con tu negocio (antes o después de llamar a Google; documenta reembolsos si falla el proveedor).
- Llama a **Google v2** desde el servidor con una clave **que no sale** en WordPress.
- Responde JSON con `translations` alineadas con el orden de `texts`, más `balance_remaining` (y opcionalmente `expiration_date`, `request_id`).
- Errores: usa HTTP apropiado o `success: false` + campo `error` legible (el plugin 2.0.11+ lo muestra al usuario).

---

## 7. Activación de licencia (cliente → tu servidor)

El plugin no embebe la lógica de Polar/Lemon: envía JSON a **`activate-license.php`** (URLs configurables).

Tu servidor debe:

- Validar HTTPS del cliente (el plugin ya exige HTTPS en el sitio para activar).
- Devolver un JSON compatible con lo que espera `class-digixop-translator-license.php` (`activated`, `license_key`, `instance`, `balance_remaining`, `error`, etc. — ver código fuente y ejemplos en `dist-server/`).
- Aplicar políticas (p. ej. **un dominio por licencia**) sin exponer secretos internos en el mensaje de error.

**No** publiques en docs el contenido real de `config.php` del servidor.

---

## 8. Memoria de traducción (tabla local)

- **Tabla:** `{wpdb->prefix}dx_translations_cache`
- **Clave:** `hash_id` = `md5(texto_original + lang_dest + kind)` con `kind` en `p` (plano) o `h` (html).
- **Instalación:** `Digixop_Translation_Cache::install()` vía activación del plugin.
- **Vacía:** acción AJAX `digixop_empty_translation_memory` (capability `manage_options`).

El proxy **no** ve entradas resueltas solo en memoria: el plugin las filtra antes de armar el payload.

---

## 9. AJAX administrativo (`action` names)

Todos bajo `admin-ajax.php`, autenticados, con nonces según acción.

| `action` | Rol resumido |
|----------|----------------|
| `digixop_translate_single` | Traduce un post (o ítem de menú) por ID e idioma. |
| `digixop_translate_bulk_check_quota` | Estima caracteres / comprobar cupo antes del lote. |
| `digixop_translate_bulk_resume` | Recupera cola de lote tras redirect. |
| `digixop_translate_wpml_taxonomy` | Traduce términos WPML pendientes. |
| `digixop_empty_translation_memory` | TRUNCATE de la tabla TM. |
| `digixop_invalidate_glossary_terms_cache` | Borrado selectivo por términos del glosario. |
| `digixop_get_all_translatable_ids` | Lista IDs para “web completa”. |
| `digixop_get_menu_custom_link_ids` | IDs de ítems de menú Custom Link. |
| `digixop_license_activate` | Activa licencia (clase License). |
| `digixop_license_deactivate` | Desactiva licencia. |

Permisos: traducción usa la capability del plugin (`CAP_TRANSLATE`); licencia y memoria suelen exigir `manage_options` — comprobar en el método concreto antes de exponer en multisite.

---

## 10. Filtros y acciones (extensión)

| Hook | Tipo | Uso típico |
|------|------|------------|
| `digixop_translator_quota_reload_url` | filtro | URL de recarga cuando hay 402 / cupo. |
| `digixop_translator_buy_credits_url` | filtro | Sustituir URL de compra de créditos. |
| `digixop_translator_buy_credits_license_param` | filtro | Nombre del parámetro query para la licencia. |
| `digixop_translator_language_badge_colors` | filtro | Paleta de badges de idioma en listas. |
| `digixop_translator_update_translation_when_source_changes` | filtro | Forzar o anular retraducción por huella (`bool`, `$post_id`, `$lang`). |
| `digixop_translator_glossary_rules_updated` | acción | Disparada al guardar glosario UI; argumentos: términos afectados, idioma destino (cadena). |

Para iconos o más extensiones, busca en el código `apply_filters` / `do_action` adicionales tras actualizar versión.

---

## 11. WPML, Elementor y huella del original

- Traducciones nuevas enlazan con `wpml_set_element_language_details` y `trid` existente.
- **Elementor:** se decodifica `_elementor_data`; no aplicar `stripslashes` agresivo sobre el JSON completo (riesgo de romper el parseo — el plugin ya evita el patrón incorrecto).
- **Huella:** `compute_post_source_fingerprint` mezcla título, extracto, cuerpo o JSON Elementor + ACF opcional; el meta `_digixop_src_fingerprint` en el post traducido permite omitir retraducción si no hubo cambios.

---

## 12. Empaquetado y depuración

- Script **`build.sh release`**: genera ZIP sin carpeta `docs/` ni secretos.
- Log archivo: `wp-content/uploads/digixop-translator.log` (según permisos y eventos BYO).
- `DIGIXOP_TRANSLATOR_DEBUG`: solo en staging; desactivar en producción para no filtrar contexto sensible en logs compartidos.

---

## 13. Referencias

| Documento | Contenido |
|-------------|------------|
| [API-SAAS.md](./API-SAAS.md) | Contrato del proxy y JSON. |
| [SERVIDOR-API-DIGIXOP.md](./SERVIDOR-API-DIGIXOP.md) | Despliegue `dist-server/`. |
| [LICENCIAS.md](./LICENCIAS.md) | Flujo de activación en WordPress. |
| [MANUAL-USUARIO-TRADUCTOR-DIGIXOP-PRO.md](./MANUAL-USUARIO-TRADUCTOR-DIGIXOP-PRO.md) | Guía funcional para clientes. |

---

*Fin del manual de desarrollador — Traductor Digixop Pro 2.0.11*