Cómo traducir los campos dinámicos del checkout de WooCommerce con GTranslate (fragments AJAX en JSON)

Si usas GTranslate para traducir una tienda WooCommerce y has notado que algunos campos del checkout (por ejemplo los datos de facturación) aparecen traducidos al cargar la página pero vuelven al idioma original después, este artículo explica por qué ocurre y cómo solucionarlo de forma definitiva.

Los síntomas

En una tienda con el idioma original en español y traducción al inglés mediante GTranslate, el usuario que navega en inglés accede a la página de finalizar compra (https://mitienda.com/en/finalizar-compra/) y observa lo siguiente:

1. Los campos del formulario de facturación (Billing Details) se cargan inicialmente en inglés.
2. Un instante después, el checkout se refresca solo y esos mismos campos vuelven a mostrarse en español.

El resultado es que campos personalizados como Segundo apellido, Población, Provincia, ¿Cómo nos has conocido? o el botón de finalizar pedido acaban mostrándose en el idioma original, mientras que el resto de la página sí está correctamente traducida. Para un cliente que ha elegido inglés, esto rompe la experiencia justo en el paso más sensible de la compra.

Por qué ocurre

WooCommerce recarga el checkout dinámicamente mediante AJAX. Cada vez que cambia algo relevante (el método de envío, el país, el contenido del carrito, un campo personalizado, etc.), WooCommerce vuelve a pedir al servidor el HTML del formulario y lo inyecta de nuevo en la página. Esa respuesta AJAX no es HTML plano: es un objeto JSON que contiene, entre otras cosas, un conjunto de fragments (fragmentos de HTML) que reemplazan partes de la página sin recargarla entera.

Aquí está la clave del problema: GTranslate, por defecto, no traduce el contenido de los objetos JSON. GTranslate traduce el HTML que se sirve en la carga inicial de la página, pero cuando WooCommerce devuelve los fragments dentro de una respuesta JSON por AJAX, ese contenido pasa «por debajo del radar» del traductor y se inserta en la página tal cual, en el idioma original.

Por eso el comportamiento es tan característico: la primera pintura de la página está traducida (viene del HTML inicial que GTranslate sí procesa), pero la recarga dinámica no lo está (viene del JSON que GTranslate ignora). El usuario percibe un «parpadeo» en el que los campos pasan del inglés al español.

Este problema no es exclusivo del checkout ni de este sitio concreto: puede aparecer en cualquier funcionalidad de WooCommerce (o de cualquier plugin) que actualice contenido mediante fragments AJAX en formato JSON.

La solución

La solución consiste en indicar a GTranslate qué debe traducir dentro de esas respuestas JSON, y ajustar un par de reglas de reemplazo en el HTML. Todo se configura desde el panel de control de GTranslate, en https://my.gtranslate.io/settings. No requiere tocar código del tema ni del plugin.

Paso 1: Traducir las claves JSON

Ve a la pestaña Advanced Settings y localiza el bloque Translate JSON Keys. Como indica el propio panel, por defecto GTranslate no traduce objetos JSON, pero permite definir manualmente qué claves de esos objetos sí deben traducirse. Puedes acceder directamente aquí: https://my.gtranslate.io/settings#advanced

Pulsa Add y añade las siguientes claves:

Qué hace cada una:

• message (Text): traduce el contenido de la clave message, que WooCommerce y otros plugins usan habitualmente para avisos y mensajes que se muestran al usuario (texto plano).
• fragments.* (HTML): es la clave decisiva para este problema. El comodín * indica a GTranslate que traduzca todos los fragmentos dentro del objeto fragments, y el formato HTML le dice que el contenido es marcado HTML (no texto plano), de modo que respete las etiquetas y traduzca solo el texto visible. Con esto, los campos del checkout que WooCommerce recarga por AJAX pasan por el traductor y dejan de revertir al idioma original.

Paso 2: Reemplazos en el HTML original

Ve a la pestaña Find and Replace, bloque Replace in original HTML («Add search strings to be replaced before translation»). Aquí se definen sustituciones que se aplican antes de traducir. Puedes acceder directamente aquí: https://my.gtranslate.io/settings#find-and-replace

Pulsa Add para cada regla.

Regla A — Normalizar la URL de la REST API:

Esto convierte la URL absoluta de la REST API de WooCommerce en una ruta relativa. Es importante porque GTranslate sirve el sitio bajo el prefijo de idioma (/en/), y una URL absoluta al dominio original puede hacer que las peticiones AJAX salgan del contexto traducido. Con la ruta relativa /wp-json/, las llamadas se mantienen dentro del idioma activo.

Regla B — Traducir el valor de atributos:

Añade el atributo data-gt-translate-attributes de GTranslate, que le indica que debe traducir el valor de determinados atributos HTML (por defecto GTranslate solo traduce texto visible, no valores de atributos). Esto es útil cuando un campo muestra su etiqueta o su valor desde un atributo en lugar del contenido del elemento.

Regla C — Traducir el botón de pedido:

El botón de finalizar compra de WooCommerce lleva la clase button alt. Añadiéndole el atributo de traducción de GTranslate se asegura que su etiqueta (por ejemplo «Realizar el pedido» / «Ordering») se traduzca correctamente aunque forme parte del contenido recargado dinámicamente.

Este es el aspecto del botón de pedido en la página de pago, que junto con el resto del formulario debe quedar correctamente traducido:

Cómo comprobar el resultado

Una vez guardados los cambios, hay que evitar que la caché sirva la versión antigua. Un truco rápido para forzar una recarga limpia es añadir un parámetro de consulta cualquiera a la URL, por ejemplo:

https://mitienda.com/en/finalizar-compra/?cache=00

Al llevar un parámetro distinto, la página se sirve sin caché y puedes verificar que:

• Los campos de facturación cargan en inglés y se mantienen en inglés tras la recarga AJAX.
• El botón de finalizar pedido aparece traducido.
• Ya no se produce el «parpadeo» del idioma.

Conviene probar todo el flujo real: añadir un producto al carrito, ir al checkout y comprobar que ningún campo revierte al idioma original al interactuar con el formulario (cambiar país, método de envío, etc.).

Resumen

El problema no es que GTranslate «falle» al traducir, sino que el contenido recargado por AJAX viaja dentro de un objeto JSON y GTranslate no traduce JSON por defecto. La solución pasa por declarar explícitamente las claves JSON a traducir (message como texto y fragments.* como HTML) y, complementariamente, normalizar la URL de la REST API y marcar con data-gt-translate-attributes los atributos y botones que también deben traducirse. Es una configuración que se hace una sola vez desde el panel de GTranslate y que puedes replicar en cualquier otra tienda WooCommerce que presente el mismo síntoma.

Foto de Ze Vieira en Unsplash