Hreflang en WordPress real: el problema de URL encoding que silencia tu SEO internacional

Implementar hreflang correctamente en una web multi-idioma es uno de esos problemas que parece resuelto en cualquier tutorial y se rompe sistemáticamente en producción. La causa casi siempre no es conceptual: es una diferencia minúscula en cómo el servidor codifica las URLs entrantes versus cómo tú las escribes en tu mapeo.

El caso real: 17 versiones de idioma en silencio

Una web con un cluster multi-idioma de 17 versiones de la misma landing (una en español, dieciséis traducciones a otros idiomas). Cada versión debería emitir 17 etiquetas <link rel="alternate" hreflang="..."> cruzando todas las alternativas, más un x-default. Sin hreflang correcto, Google trata cada versión como contenido duplicado o aproximadamente duplicado, y termina mostrando solo una en SERP de cualquier país.

La primera implementación falló. El snippet PHP estaba bien escrito conceptualmente: un array con clave-URL y valor-array de hreflangs por idioma, un hook wp_head que comparaba $_SERVER['REQUEST_URI'] con las claves del array y emitía las etiquetas. En producción, el array nunca matcheaba.

La causa: REQUEST_URI no es un string canónico

$_SERVER['REQUEST_URI'] no es un string canónico. Es lo que el servidor recibe del cliente, que puede traer:

• Caracteres URL-encoded en mayúsculas o minúsculas: %2F o %2f. Equivalentes para el browser, distintos para una comparación de strings PHP.
• Trailing slash o sin trailing slash, según la configuración del servidor y los redirects activos.
• Querystrings residuales de tracking (?utm_source=...) que no estaban en el array.
• Caracteres acentuados codificados en UTF-8 o en encoding del sistema, dependiendo de versión de Apache/Nginx.

En el array PHP del snippet, las claves estaban escritas en formato canónico (lowercase, sin querystring, con trailing slash). Pero REQUEST_URI traía las URLs en formato real-del-cliente. Conclusión: el matching fallaba en silencio en el 100% de los casos, los hreflang no se emitían, y el problema era invisible (no había error PHP, no había log, simplemente no aparecían las etiquetas en HTML).

La solución: una función de normalización aplicada a ambos lados

Una función de normalización aplicada a ambos lados de la comparación:

function avafa_b45_norm($path) {
    $p = parse_url($path, PHP_URL_PATH);
    $p = strtolower(urldecode($p));
    if (substr($p, -1) !== '/') $p .= '/';
    return $p;
}

Esta función:

• Extrae solo el path (descarta querystring y fragment).
• Aplica urldecode para convertir %2F y similares a su equivalente canónico.
• Pasa todo a minúsculas.
• Garantiza trailing slash.

Aplicada al REQUEST_URI actual y a cada clave del array antes de comparar, el matching pasa de fallar a ser perfecto.

Por qué este bug es tan común y tan oculto

Hreflang es un caso particular de un patrón general en WordPress: comparas URLs entrantes con URLs declaradas y asumes que ambos formatos coinciden. El asumido es siempre falso. La regla operativa es: antes de cualquier comparación de URLs en código backend, normaliza siempre.

Otros sitios donde aparece el mismo bug:

• Filtros condicionales que se aplican «solo en ciertas URLs».
• Snippets de redirección que comparan path actual con path destino.
• Lógica de schema condicional que decide qué emitir según URL.
• Sistemas de tracking que loggean URLs específicas.

En cada uno de estos casos, el código funciona en local con URLs limpias y se rompe en producción cuando llegan URLs reales con encoding inconsistente.

El protocolo de validación tras implementar hreflang

Cuando implementes hreflang, no confíes en que «el snippet está activo». Valida directamente con un fetch al HTML servido en cada URL relevante. Una rutina mínima:

1. Lista de URLs del cluster (las 17 alternativas en este caso).
2. Para cada una, fetch del HTML.
3. Parsear el HTML y contar las etiquetas <link rel="alternate" hreflang>.
4. Verificar que cada URL emite el número correcto de hreflangs (en este caso, 17 + x-default = 18).
5. Verificar que los href apuntan a URLs reales (responden 200, no 404).

Si una URL emite menos hreflangs de los esperados, el problema es siempre el matching del snippet, no el contenido del array.

Tres detalles que multiplican el ROI de hreflang

1. El x-default no es opcional

Indica qué versión mostrar cuando ninguna de las declaradas matchea el idioma del usuario. Casi siempre es la versión en inglés o la del país principal. Omitirlo no es un error técnico pero deja a Google decidiendo, y la decisión rara vez es la mejor.

2. Bidireccionalidad obligatoria

Cada versión debe declarar a TODAS las demás, incluida ella misma. Si la versión española declara la inglesa pero la inglesa no declara la española, Google considera el cluster roto y desactiva las traducciones del SERP.

3. Detección de idioma real del contenido

No basta con declarar <html lang="es">. Si el contenido principal del post está en inglés porque alguien lo tradujo y olvidó cambiar el lang, Google detecta la discrepancia y baja la confianza. La auditoría debe detectar idioma real del bloque de contenido (no del body completo, que contiene el menú en otro idioma) y reportar discrepancias.

50 líneas de PHP frente a SaaS premium

Hreflang es uno de esos temas donde «la teoría es fácil, la implementación es donde mueres». Las herramientas SaaS de SEO internacional cobran cantidades absurdas precisamente porque saben que el cliente no quiere lidiar con normalizar REQUEST_URI ni con auditar la bidireccionalidad. Pero todo lo que hacen se reduce a 50 líneas de PHP bien escritas en un snippet WPCode. El truco no es complicado: es siempre normalizar antes de comparar.

¿Por qué elegimos a Avafa Consulting como nuestra agencia SEO? Tuvimos la oportunidad de trabajar anteriormente con Víctor García y su equipo en otro proyecto, y la experiencia fue muy positiva tanto por su profesionalismo como por los resultados obtenidos.

Ruben Albardias Idiarte
Communication & Digital Marketing Manager

Elegimos a Avafa Consulting por su enfoque estratégico del SEO como eje central de crecimiento digital... Su experiencia en eCommerce y Marketplaces es bien sabida.

Laia Valero
CEO de DESKandSITm