Manual de usuario (completo) — Traductor Digixop Pro

1. Qué hace el plugin y qué no hace

1.1 Objetivo

Traductor Digixop Pro crea o actualiza entradas de WordPress en otros idiomas según la configuración de WPML, usando Google Cloud Translation de dos formas:

En ambos casos el resultado son posts vinculados por WPML (mismo trid), listos para revisión, publicación o edición manual.

1.2 “Traducción automática de toda la web”

En el menú Traductor Digixop, la opción Traducir web completa recorre en cola los contenidos que hayas marcado como traducibles (idioma origen → idioma que elijas).

• Sí hace: genera o actualiza posts traducidos en WordPress (como si pulsaras “traducir” muchas veces).
• No hace: no intercepta cada visita ni traduce pantallas sin tener antes entradas en ese idioma. Los visitantes siguen viendo lo que WPML ya sirve en cada idioma.

1.3 Lo que el plugin no sustituye

• WPML String Translation y traducciones de tema/plugins a nivel .mo/String Translation: el plugin no reemplaza ese módulo para cadenas del tema fuera del contenido de entradas/menús/taxonomías cubiertas aquí.
• Slugs (post_name): no se traducen automáticamente con este flujo.
• Creación de términos de taxonomía solo por “asignar términos traducidos”: si WPML no tiene aún el término equivalente, la asignación no inventa nombres; para nombres y descripciones de términos usa la herramienta de Taxonomías (apartado 10).

2. Requisitos e instalación

2.1 Requisitos

• WordPress 6.x recomendado.
• WPML activo (Multilingual CMS u bundle que exponga wpml_object_id, idiomas y traducciones de entradas).
• HTTPS en la URL del sitio para activar la licencia (obligatorio en el flujo actual).
• Opcional pero habitual: ACF, Elementor, plugins SEO (Yoast / Rank Math) para las extensiones descritas más abajo.

2.2 Instalación

1. Sube la carpeta del plugin a wp-content/plugins/ (o instala el ZIP desde Plugins → Añadir nuevo si te lo proporcionan empaquetado).
2. Activa Traductor Digixop Pro.
3. Abre Traductor Digixop en el menú lateral de administración (también accesible vía Ajustes → Traductor Digixop en instalaciones que mantengan el enlace).
4. Activa la licencia, elige DTL o BYO, configura idioma origen, idiomas destino y tipos de contenido traducibles.

En la primera activación del plugin se crean opciones por defecto (incluido idioma origen alineado con el idioma por defecto de WPML si está disponible).

3. Acceso al panel y vista general

La pantalla principal es un escritorio unificado (admin-unified-view.php):

• Cabecera y métricas: saldo de caracteres (modo DTL), estado de licencia, fecha de caducidad si aplica.
• Licencia: campo de clave, botones Activar / Desactivar.
• Ajustes de traducción: tarjetas de modo DTL / BYO, idiomas, tipos de contenido, extracto, taxonomías, ACF, Elementor, SEO Pro, memoria de traducción, glosario UI, listas de exclusión.
• Traducción masiva del sitio: selector de idioma destino y arranque del proceso por lotes internos.
• Traducción automática de menús (WPML): herramienta dedicada para elementos Custom Link.

Mantén esta página abierta cuando ejecutes procesos largos; el navegador debe poder completar las peticiones AJAX en cadena.

4. Licencia, HTTPS y modos DTL / BYO

4.1 Activación

El plugin envía la clave al endpoint configurado (por defecto activate-license.php en tu API Digixop), junto con la URL del sitio, para validar y registrar la instancia. El servidor puede aplicar la política una licencia vinculada a un dominio; si intentas activar en otro dominio sin desactivar antes, verás el mensaje de error devuelto por la API.

Sin HTTPS en home_url(), la activación se rechaza de forma explícita.

4.2 Desactivación

Útil al migrar de dominio o al traspasar el proyecto. Libera la instancia en el servidor según la implementación de activate-license.php.

4.3 Elegir DTL o BYO

• DTL: recomendado si quieres centralizar facturación por caracteres y no exponer tu API Key de Google en WordPress. Necesitas licencia válida y saldo.
• BYO: recomendado si ya tienes facturación directa con Google y controlas cuotas en Google Cloud Console. Debes introducir la API Key en ajustes y guardar; al volver a DTL, la clave local puede limpiarse según la lógica de guardado del plugin.

La prioridad la marca la opción guardada (translation_mode), no “si hay API key entonces BYO”.

5. Saldo de caracteres: qué se cobra y qué se ahorra

5.1 Dónde se descuenta

En DTL, el proxy descuenta saldo por los caracteres de los segmentos enviados en cada petición exitosa. El plugin puede omitir segmentos que ya tengan traducción en la memoria local (ver sección 12): esos no viajan al proxy y, por tanto, no consumen saldo DTL.

5.2 Estimación antes de un lote

En traducciones masivas desde listados, el flujo puede estimar caracteres antes de traducir para comprobar si hay saldo suficiente (cuando aplica).

5.3 BYO

El consumo lo mides en Google Cloud (facturación y cuotas del proyecto); el plugin no muestra “saldo Digixop” para ese modo.

6. Ajustes de traducción (idiomas, tipos de contenido, opciones)

6.1 Idioma origen

Debe coincidir con el idioma del contenido fuente en WPML. Si traduces un post que WPML marca en otro idioma, el plugin omite la acción con un mensaje del tipo “No está en el idioma de origen configurado”.

6.2 Idiomas destino

Solo los marcados aparecen como botones en la columna Traducción y en las acciones masivas “Traducir a …”. Si no marcas ninguno, el plugin puede usar todos los idiomas activos excepto el origen (comportamiento por defecto amplio).

6.3 Tipos de contenido traducibles

Lista basada en tipos públicos; el plugin añade automáticamente tipos necesarios como elementor_library (plantillas Elementor) y nav_menu_item (elementos de menú) cuando existen en el sitio, para que puedas traducirlos desde sus listados si los incluyes en la selección.

6.4 Opciones principales

7. Traducción desde listados de entradas

7.1 Columna “Traducción”

En cada fila verás un control por idioma destino. Al pulsar:

1. Se muestra un overlay de progreso.
2. Al terminar: éxito (recarga del listado para refrescar iconos WPML), omitido (mensaje breve) o error.

7.2 Acciones en lote (bulk)

1. Marca las casillas de los posts.
2. En Acciones en lote, elige Traducir a [idioma].
3. Aplicar. El flujo moderno usa transient + AJAX para no depender solo de sessionStorage (mejor en modo privado o políticas estrictas del navegador).

Los estados posibles por elemento: traducido, omitido, error. El resumen final puede incluir caracteres procesados en la petición.

8. Traducción masiva del sitio (“web completa”)

En Traductor Digixop → Traducción masiva del sitio:

1. Elige Traducir web completa a: [idioma].
2. Pulsa Comenzar traducción.

El plugin busca contenido en el idioma origen configurado y lo procesa en serie (creación o actualización según opciones y existencia de traducción). Es la forma más cómoda de vaciar colas grandes tras la configuración inicial.

Recomendaciones:

• Haz una copia de seguridad antes de procesar miles de entradas.
• Verifica saldo DTL o cuotas Google en BYO.
• Si usas “Actualizar traducción si el original cambió”, las retraducciones repetirán solo lo necesario y la memoria amortizará texto repetido.

9. Traducción automática de menús (WPML)

9.1 Alcance real

El plugin traduce únicamente elementos de menú de tipo “Custom Link” (nav_menu_item con _menu_item_type = custom), típicamente el texto visible del enlace (campo título del ítem).

No traduce automáticamente:

• Ítems que son páginas o entradas enlazadas por ID (el título visible suele venir del post enlazado: traduce primero el post).
• Estructuras de menú que dependan solo de WPML String Translation fuera de estos ítems.

9.2 Uso de la herramienta en el panel

1. Ve a Traductor Digixop → Traducción automática de menús.
2. Elige idioma destino y Traducir menús.
3. Observa el log de progreso.

Orden recomendado en documentación de producto: primero contenido y páginas, luego menús, para que los títulos generados coincidan con el contexto ya traducido.

10. Taxonomías: asignación en posts y traducción de términos

10.1 “Asignar términos traducidos” al traducir un post

Con la opción activa, al crear/actualizar una traducción de entrada el plugin asigna a la traducción los términos equivalentes en el idioma destino usando WPML. Si un término no tiene traducción enlazada en WPML, no se inventa: debes crear/traducir el término antes (WPML Taxonomy Translation o la herramienta Digixop).

10.2 Traducir nombres y descripciones de términos (WPML)

En WPML → Taxonomy Translation (ruta exacta según versión de WPML), aparece un bloque Traductor Digixop para taxonomías WPML:

1. Elige la taxonomía (categorías, etiquetas, CPT tax, etc.).
2. Elige idioma destino.
3. Opcional: lista de IDs de términos separados por comas para limitar el lote.
4. Traducir términos pendientes.

El proceso crea/vincula términos en WPML (wpml_set_element_language_details) y traduce nombre y descripción con el mismo motor DTL/BYO que el resto del plugin.

11. Qué campos se traducen (contenido, Elementor, ACF, SEO)

11.1 Siempre (salvo exclusiones y tipos especiales)

• Título (post_title).
• Contenido (post_content) excepto cuando el post tiene datos de Elementor en _elementor_data: en ese caso el diseño vive en el JSON y el contenido no se manda al traductor como HTML principal (se traduce el JSON).

11.2 Elementor

• Se traducen textos en settings de widgets reconocidos; se evitan tipos peligrosos (code, shortcode, etc.).
• Widget HTML: se respeta lo que va dentro de <style> y <script>; se traduce el HTML con texto visible.
• Constante opcional DIGIXOP_TDL_ELEMENTOR_SAFE_COPY en wp-config.php: si está a true, se copia _elementor_data sin traducir (útil en casos extremos de ruptura de maquetación; desactivada por defecto).

11.3 ACF y SEO

Ver tabla en sección 6. Los metadatos SEO requieren Pro y casilla correspondiente.

12. Memoria de traducción (caché local de segmentos)

12.1 Qué es

Una tabla en la base de datos del sitio: {prefijo}dx_translations_cache (el prefijo es el de tu instalación WordPress, p. ej. wp_dx_translations_cache).

Cada fila guarda un segmento (texto original, texto traducido, idioma destino) con clave hash derivada de texto + idioma + tipo (kind: texto plano vs HTML) para evitar colisiones.

12.2 Cuándo ahorra caracteres (DTL)

Antes de llamar a la API, el plugin consulta la memoria por segmentos idénticos. Los aciertos se reutilizan sin enviar ese texto al proxy: ahorro directo de saldo.

12.3 Activar / vaciar

• Activar Memoria de Traducción: interruptor en ajustes.
• Vaciar Memoria de Traducción: borra toda la tabla de caché del sitio (no borra posts ni licencia). Requiere permisos de administración (manage_options en el flujo AJAX).

12.4 Relación con el glosario UI

Al guardar reglas del Glosario UI, el plugin puede invalidar entradas de caché que contengan los términos afectados, para que la próxima traducción aplique las nuevas reglas. También existe la acción Forzar limpieza de estos términos junto al campo del glosario.

13. Glosario UI, glosario protegido y campos excluidos

13.1 Glosario UI (Origen -> Traducción)

• Una regla por línea, formato Término -> Traducción.
• Sirve para post-procesado al español (p. ej. uniformar “Home” → “Inicio”) y para construir el system_prompt enviado al proxy en DTL (el motor remoto puede respetar mejor la terminología).
• Al guardar, se disparan limpiezas selectivas de memoria asociadas a los términos tocados.

13.2 Glosario protegido (marcas / nombres propios)

• Una palabra o frase por línea.
• Antes de traducir, el plugin sustituye temporalmente esas coincidencias (límites de palabra) por marcadores, traduce el resto y restaura el texto original en el resultado: el término no se traduce.

13.3 Campos excluidos (blacklist)

• Una entrada por línea: post_title, post_content, post_excerpt o variantes por CPT: mi_cpt:post_title.
• Esos campos se copian sin llamar al traductor (útil para nombres de proyecto, códigos, etc.).

14. Retraducción cuando el original cambia

Si ya existe la traducción WPML y la opción “Actualizar traducción si el original cambió” está activa:

• El plugin calcula una huella (fingerprint) del original (título, extracto, cuerpo o JSON Elementor + ajustes de página Elementor, y bloque ACF si la opción ACF está activa).
• Si la huella no cambió respecto a la guardada en la traducción, responde omitido: “El original no ha cambiado; no es necesario retraducir.”
• Si cambió, actualiza el post traducido en lugar de crear uno nuevo.

Desarrolladores pueden afinar el comportamiento con el filtro digixop_translator_update_translation_when_source_changes.

15. Aprendizaje desde correcciones manuales en WPML

Cuando un usuario guarda manualmente una entrada que WPML considera traducción (no el original), el plugin puede aprender pares título/extracto/contenido (y títulos de Custom Link de menú comparados con su original) y escribirlos en la memoria de traducción para reutilizarlos en el futuro.

No se aprende durante las peticiones AJAX internas del propio plugin (digixop_translate_single, digixop_translate_wpml_taxonomy) para evitar bucles y ruido.

16. Elementor: buenas prácticas y modo seguro

1. Traduce primero una copia de prueba de una plantilla crítica.
2. Si tras una actualización del plugin notas maquetación rota, prueba temporalmente DIGIXOP_TDL_ELEMENTOR_SAFE_COPY en true y retraduce solo ese contenido, o ajusta el HTML del widget afectado.
3. Evita meter JavaScript mezclado con texto traducible en widgets HTML sin necesidad; el parser intenta ser conservador, pero el HTML complejo es siempre más frágil.

17. Permisos, registros y errores frecuentes

17.1 Permisos

Las acciones de traducción en listados requieren la capacidad definida en el plugin (traducir con Digixop / constante interna CAP_TRANSLATE). La licencia y el vaciado de memoria requieren privilegios de administración según el caso.

17.2 Registros

Con DIGIXOP_TRANSLATOR_DEBUG en wp-config.php puedes aumentar el detalle en log. Errores de Google en BYO pueden registrarse en wp-content/uploads/digixop-translator.log cuando el entorno lo permite.

17.3 Errores del proxy (DTL)

Desde la versión 2.0.11, si el servidor responde con JSON success: false y un campo error (por ejemplo saldo insuficiente, licencia inactiva, error 403 de Google en el servidor), el plugin muestra el mensaje concreto en lugar de un error genérico.

18. Preguntas frecuentes (FAQ)

Texto alineado con el manual Markdown (misma redacción).

19. Cierre y soporte

Gracias por usar Traductor Digixop Pro. Este manual describe el comportamiento del plugin en la versión indicada al inicio; para cambios entre versiones consulta siempre el CHANGELOG.md del paquete que hayas instalado.

• Sitio y producto: https://digixop.com/
• Documentación técnica del repositorio (despliegue API, contrato del proxy, QA): carpeta docs/ e INDICE-DOCUMENTACION.md.
• Integradores / desarrolladores (Google BYO, proxy propio, hooks, sin secretos): MANUAL-DESARROLLADOR-TRADUCTOR-DIGIXOP-PRO.md y manual-desarrollador.html.

Nota final: la traducción automática acelera el trabajo editorial, pero la revisión humana sigue siendo recomendable en textos legales, médicos, comerciales críticos o de marca. Combina memoria de traducción, glosarios y el flujo WPML estándar para mantener control total sobre lo publicado.