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 (y qué sí añade)

• WPML String Translation sigue registrando/almacenando cadenas del tema. Desde 2.0.12+ Digixop añade una herramienta en esa pantalla para traducir cadenas ya registradas por lotes (con control de saldo). No registra cadenas nuevas.
• 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).
• Dominio/contexto WPML de cada cadena: el glosario UI no filtra por dominio; aplica por idioma destino y por texto (sección 13). Etiquetas de menú: por el título del ítem (nav_menu_item).

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): traduce etiquetas visibles de ítems de menú (§9 y §19).

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.

8.1 ¿Vuelve a empezar de cero si relanzo la traducción masiva?

No. El plugin no borra traducciones ya hechas.

Sirve para retomar un lote interrumpido. Las entradas en borrador no pasan a publicadas solas al cambiar la opción de publicación.

8.2 Orden recomendado (WooCommerce, blog y home Elementor)

1. Ajustes: product, post, page; opcional Publicar directamente.
2. Productos WooCommerce (ES → EU).
3. Entradas del blog.
4. Taxonomías (categorías, etiquetas).
5. Páginas (home, legales).
6. Menús — etiquetas visibles (§9) + WP Menus Sync.

Traducir solo la home deja cuadrículas Elementor vacías hasta que existan productos y entradas publicados en EU (ver 16.1).

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

Esta sección es crítica en sitios reales: la mayoría de menús (incluido móvil) usan enlaces a páginas, no Custom Link, y la etiqueta casi nunca coincide con el título de la página. DTP traduce la etiqueta de navegación, no sustituye la sincronización WPML.

9.1 Etiqueta de menú ≠ título de la página

En Apariencia → Menús, el texto de navegación se guarda en el título del ítem (nav_menu_item). Traducir solo la página no cambia la etiqueta si fue personalizada («Programa», «Info», etc.).

9.2 Qué traduce la herramienta (desde v2.0.17)

Traductor Digixop → Traducción automática de menús procesa todos los ítems del idioma origen con etiqueta no vacía:

• Enlace personalizado (custom)
• Página / entrada / CPT (post_type) — traduce la etiqueta, no sustituye traducir la página
• Categoría / taxonomía (taxonomy)

No aplica a menús solo en plantillas Elementor (§9.6) ni a cadenas del tema (§10.3).

9.3 Orden de trabajo recomendado

1. Traducir contenido enlazado (páginas, posts, productos).
2. Traducir taxonomías si aplica.
3. Traducir menús con DTP (por idioma destino).
4. WPML → Sincronización de menús (estructura, móvil/desktop).
5. Revisar front + Glosario UI.

9.4 Qué hace DTP al traducir un ítem

• Traduce la etiqueta (post_title).
• Crea/actualiza la traducción WPML del ítem.
• Copia metadatos y remapea el enlace a la página/término traducido, padre y menú nav_menu equivalente.

9.5 Si dice «No se encontraron elementos…»

Cero ítems en el idioma origen de DTP con etiqueta en WPML. Comprueba: idioma origen en Ajustes, etiquetas no vacías, ítems registrados en ES (no solo EU), menú WP vs Elementor. En plugin < 2.0.17 solo buscaba Custom Link.

9.6 Menús en cabecera Elementor

Traduce la plantilla elementor_library del header. Si el widget usa menú WP, también §9 tras traducir contenido.

9.7 Sincronización de menús WPML

WP Menus Sync alinea estructura entre idiomas. DTP no lo sustituye. Ejecútalo tras Traducir menús si faltan ítems o el orden difiere.

9.8 Uso en el panel

1. Traductor Digixop → Traducción automática de menús.
2. Elige idioma destino → Traducir menús.
3. Revisa el log. Si «Ya existe traducción», activa Actualizar traducción si el original cambió.

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.

10.3 WPML String Translation (cadenas del tema)

Ruta: WPML → Traducción de cadenas. Panel Traductor Digixop — WPML String Translation:

• Idioma destino, Solo sin traducir, Usar filtros de la URL, Máx. cadenas (hasta 2000 por trabajo).
• Estimar y traducir: cuenta cadenas y caracteres, comprueba saldo DTL/BYO, confirma y procesa en lotes de 20.

No registra strings nuevas. Si icl_strings ya tiene cientos de miles de filas, filtra en WPML y traduce por subconjuntos; limpia cadenas obsoletas con backup.

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)

El idioma destino lo define la acción de traducción (EU, EN…), no la línea del glosario. Formatos: sin prefijo (todos los destinos), eu: Inicio -> Hasiera, bloque [eu].

Menús: si el título fuente es exactamente Inicio, se fuerza la traducción de la regla para ese destino. Corrección: eu: Hasi -> Hasiera si la API devolvió “Hasi”.

[eu]
eu: Inicio -> Hasiera
eu: Hasi -> Hasiera

[en]
en: Inicio -> Home
en: Start -> Home

Tras guardar: Forzar limpieza de estos términos o retraducir. Prompt DTL incluye reglas del destino; BYO depende más del post-proceso.

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 etiquetas de menú comparadas 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.

16.1 Cuadrículas Elementor vacías en el idioma traducido

Síntoma: títulos y botones traducidos en /eu/, pero cuadrículas de productos o blog vacías. En el idioma original sí hay contenido.

Causa: widgets dinámicos (Products, Posts, Loop Grid) consultan entradas en el idioma actual. Sin productos/entradas traducidos y publicados en EU, la consulta devuelve cero resultados.

Qué hacer: traduce y publica product y post; taxonomías si filtran cuadrículas; comprueba estado Publicado en EU. Ver orden en 8.2.

16.2 WooCommerce: duplicar en WPML y traducir con DTP

Flujo A (recomendado): productos solo en ES → DTP crea y traduce EU.

Flujo B: duplicar ES→EU en WPML (enlazado) → traducir desde ES con «Actualizar traducción si el original cambió» activa → DTP rellena textos en la ficha EU existente.

Publica productos EU o usa Publicar directamente en Ajustes. Traduce categorías/atributos en WPML si aplica.

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, el plugin muestra el mensaje concreto.

17.4 WPML, rendimiento y tablas de cadenas

Digixop no registra cadenas en icl_strings al traducir entradas/Elementor/ACF. Guardas durante guardados automáticos. Si las tablas ST son enormes (504), actualiza el plugin, limpia cadenas obsoletas en WPML (backup) y traduce ST con filtros y límite.

18. Preguntas frecuentes (FAQ)

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

19. Flujos WPML no estándar: qué hace DTP y qué debes hacer tú

WPML documenta un flujo ideal; en sitios con Elementor, WooCommerce, menús móviles y etiquetas personalizadas, varios pasos no funcionan como espera un administrador nuevo.

19.1 Tabla de referencia rápida

19.2 Menús: flujo recomendado

Contenido → Taxonomías → Traducir menús (DTP) → WP Menus Sync → Revisión front + Glosario

19.3 Elementor + WPML + DTP

• Textos fijos del diseño → traducir elementor_library.
• Listados dinámicos → traducir product, post, etc.
• Maquetación rota → DIGIXOP_TDL_ELEMENTOR_SAFE_COPY (§11.2).

19.4 Qué DTP no sustituye de WPML

Emparejar idiomas, WP Menus Sync, registro de strings, URLs/hreflang. DTP automatiza textos dentro de ese marco.

19.5 Checklist soporte

1. DTP ≥ 2.0.17 (menús).
2. Idioma origen = idioma de los ítems.
3. Contenido enlazado traducido y publicado.
4. Menú WP vs Elementor identificado.
5. WP Menus Sync ejecutado.

20. 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.