Todos los artículos

Front-end17 min de lectura

SEO multilingüe en React: hreflang, prerender y sitemap

Cómo llevé mi blog React en 4 idiomas a Google y a las búsquedas con IA: prerender, hreflang, canonical, JSON-LD, sitemap, RSS y llms.txt, con el código real.

También en Português, English, Français

Cuando decidí escribir artículos aquí, tenía un solo objetivo: alguien busca una duda en Google y llega a mi sitio. En portugués, en inglés, en español o en francés.

El problema es que mi portafolio era una SPA. Toda URL devolvía el mismo HTML, con un <div id="root"> vacío y las mismas etiquetas para compartir. Para un blog, eso es casi invisible.

Este post cuenta lo que cambié para que cada artículo exista de verdad para los buscadores, en los 4 idiomas. Y como el post vive en el propio blog, todo lo que ves aquí es el código que está corriendo ahora.

TL;DR#

  • Prerenderiza. React Router 7 genera un HTML listo por URL en el build, sin servidor. El robot recibe el texto, el título y las etiquetas sin ejecutar JavaScript.
  • Una URL por idioma, con las palabras traducidas: /artigos, /en/articles, /es/articulos, /fr/articles.
  • hreflang en todas las versiones, cada una apuntando a sí misma y a las demás, más un x-default. Solo entran las traducciones publicadas.
  • Sin traducción, canonical al original. La página existe en el idioma de la URL, pero no compite con el texto en portugués.
  • JSON-LD BlogPosting y BreadcrumbList, y una portada por idioma en el og:image.
  • El build genera el resto: sitemap con hreflang y lastmod, un RSS por idioma, llms.txt y un 404.html de verdad.
  • El build también frena errores: frontmatter validado con zod, imagen sin alt y portada que falta rompen el build.

El punto de partida: una SPA que decía lo mismo en toda URL#

Este era el index.html del portafolio antes del blog, resumido:

index.html (before)
<title>Yasmin Lopes, Software Engineer & Designer</title>
<link rel="canonical" href="https://www.yasminlopes.dev/" />
<meta property="og:image" content="https://www.yasminlopes.dev/og.png" />
<!-- ... -->
<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
</body>

Y el vercel.json mandaba cualquier ruta hacia él:

vercel.json (before)
{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

Tres problemas para un blog:

  • El HTML no tenía contenido. El texto solo aparecía después de que el JavaScript corría en el navegador. El título de cada página también: cambiaba con document.title, ya en el cliente.
  • El canonical apuntaba a la home en toda URL. Un artículo decía "mi versión oficial es la página de inicio".
  • No existía el 404. Cualquier dirección inventada devolvía 200 con el mismo HTML.

Google puede ejecutar JavaScript: la documentación de JavaScript SEO describe tres fases, rastreo, renderizado e indexación. Pero la misma página dice que prerenderizar sigue siendo una gran idea, porque hace el sitio más rápido y porque no todos los robots ejecutan JavaScript. Y tiene una sección solo sobre mi tercer problema: el soft 404 de las SPA, cuando una página que no existe responde como si existiera.

El mismo artículo para quien no ejecuta JavaScript: antes y después del prerender

Prerender con React Router 7#

El cambio clave fue pasar el sitio al modo framework de React Router 7, con prerender. En el build, visita cada URL y guarda el HTML listo. En producción no hay servidor: todo son archivos estáticos.

react-router.config.ts
import type { Config } from '@react-router/dev/config'
import { listSitePages } from './vite/site-pages.ts'
import { finalizeStaticBuild } from './vite/static-build.ts'
 
/**
 * Static site: every page is prerendered to HTML at build time (no server at runtime).
 * The page list lives in `vite/site-pages.ts`, shared with the sitemap.
 */
export default {
  appDirectory: 'src',
  ssr: false,
  prerender: async () => (await listSitePages()).map((page) => page.path),
  buildEnd: ({ reactRouterConfig }) => finalizeStaticBuild(reactRouterConfig.buildDirectory),
} satisfies Config

El detalle que más me gusta: la lista de páginas prerenderizadas y el sitemap salen de la misma función, listSitePages. Una página no puede entrar al sitemap sin existir, ni existir sin entrar.

Cada ruta exporta un meta con sus etiquetas, y React Router lo escribe en el <head> del HTML generado. Así, el título, la descripción y el canonical ya vienen en el archivo, antes de cualquier JavaScript.

El vercel.json perdió el rewrite. Ahora solo sirve la carpeta del build (resumido):

vercel.json
{
  "buildCommand": "npm run build",
  "outputDirectory": "build/client",
  "cleanUrls": true,
  "trailingSlash": false
}

Y el 404 volvió a ser 404. La ruta * se prerenderiza en /404 y el final del build la renombra a 404.html, que es el archivo que Vercel sirve para direcciones desconocidas:

curl -s -o /dev/null -w '%{http_code}\n' https://www.yasminlopes.dev/artigos/nao-existe
# 404

Una URL por idioma#

Google recomienda una URL distinta para cada idioma, en vez de cambiar el texto por cookie o por la configuración del navegador. Y pide no redirigir automáticamente a la persona al idioma que crees que habla.

Aquí, toda URL del blog nace en un solo archivo:

src/features/articles/paths.ts
const URLS: Record<Locale, { base: string; trail: string; feed: string; file: string }> = {
  'pt-BR': { base: '/artigos', trail: 'trilha', feed: '/rss.xml', file: 'pt-br' },
  en: { base: '/en/articles', trail: 'track', feed: '/en/rss.xml', file: 'en' },
  es: { base: '/es/articulos', trail: 'ruta', feed: '/es/rss.xml', file: 'es' },
  fr: { base: '/fr/articles', trail: 'parcours', feed: '/fr/rss.xml', file: 'fr' },
}
 
export const articlePath = (slug: string, locale: Locale) => `${URLS[locale].base}/${slug}`

El portugués es el original y no lleva prefijo. Las traducciones llevan el prefijo y las palabras traducidas: quien lee en español ve articulos y ruta en la barra de direcciones. Las rutas, los enlaces, el hreflang, el sitemap y el RSS llaman a estas funciones, así que una URL nunca sale distinta de un lugar a otro.

Las rutas se generan a partir de la misma lista de idiomas:

src/routes.ts
const blogRoutes = ARTICLE_LOCALES.flatMap((locale) => {
  const base = articlesPath(locale).slice(1)
  return [
    route(base, 'routes/articles.tsx', { id: `articles-${locale}` }),
    route(`${base}/${trailSegment(locale)}/:trail`, 'routes/articles-trail.tsx', { id: `articles-trail-${locale}` }),
    route(`${base}/:slug`, 'routes/article.tsx', { id: `article-${locale}` }),
  ]
})

Los archivos siguen la misma idea. Cada artículo es una carpeta, con el original y las traducciones lado a lado: content/artigos/<slug>/pt-br.mdx, en.mdx, es.mdx y fr.mdx.

hreflang: las cuatro versiones apuntándose#

El hreflang le dice a Google "esta página también existe en estos otros idiomas, en estas direcciones". Las reglas que importan, de la documentación de versiones localizadas:

  • Cada versión se lista a sí misma y a todas las demás.
  • Tiene que haber vuelta. Si la página A apunta a B y B no apunta a A, las etiquetas se ignoran. Así un sitio ajeno no puede declararse traducción del tuyo.
  • El x-default es la página para quien habla un idioma que no tienes.
  • Se puede declarar en el HTML, en un encabezado HTTP o en el sitemap. Los tres valen lo mismo. Yo uso HTML y sitemap.
  • Google no usa el hreflang para descubrir el idioma de la página. Lo detecta solo. El hreflang sirve para conectar las versiones.

Todas las páginas del sitio pasan por la misma función, pageMeta. Es ella la que convierte la lista de versiones en etiquetas:

src/core/seo/page-meta.ts
export function pageMeta({ title, description, path, image, lang = 'en', noIndex, alternates = [], feed, article, jsonLd }: PageMetaInput) {
  const url = absoluteUrl(path)
  const languages = alternates.length > 1 ? alternates : []
  const xDefault = languages.find((alternate) => alternate.locale === 'pt-BR') ?? languages[0]
 
  const tags = [
    { title },
    { name: 'description', content: description },
    { tagName: 'link', rel: 'canonical', href: url },
    ...languages.map((alternate) => ({ tagName: 'link', rel: 'alternate', hrefLang: alternate.locale, href: absoluteUrl(alternate.path) })),
    xDefault && { tagName: 'link', rel: 'alternate', hrefLang: 'x-default', href: absoluteUrl(xDefault.path) },
    // ... Open Graph, Twitter card and JSON-LD
  ]
}

Fíjate en la línea 3: un idioma solo no genera ningún hreflang. Y el x-default siempre es el portugués, que es el original y la única versión garantizada.

Y quien decide qué versiones entran es el artículo: solo las traducciones publicadas. Una traducción en borrador nunca aparece en el hreflang, porque no existe en el build de producción, y un hreflang a una página 404 solo estorba.

Este es el HTML que está en línea ahora, de la versión en inglés del post sobre MCP:

curl -s https://www.yasminlopes.dev/en/articles/o-que-e-mcp | grep -oE '<link rel="(canonical|alternate)"[^>]*>'
<link rel="canonical" href="https://www.yasminlopes.dev/en/articles/o-que-e-mcp"/>
<link rel="alternate" hrefLang="pt-BR" href="https://www.yasminlopes.dev/artigos/o-que-e-mcp"/>
<link rel="alternate" hrefLang="en" href="https://www.yasminlopes.dev/en/articles/o-que-e-mcp"/>
<link rel="alternate" hrefLang="es" href="https://www.yasminlopes.dev/es/articulos/o-que-e-mcp"/>
<link rel="alternate" hrefLang="fr" href="https://www.yasminlopes.dev/fr/articles/o-que-e-mcp"/>
<link rel="alternate" hrefLang="x-default" href="https://www.yasminlopes.dev/artigos/o-que-e-mcp"/>
<link rel="alternate" type="application/rss+xml" title="Yasmin Lopes, articles" href="/en/rss.xml"/>
Cada versión apunta a sí misma y a las otras tres, y el x-default se queda con el original

El <html lang> también acompaña a la página: lang="en" en la versión en inglés. Google no lo usa para detectar el idioma, pero los lectores de pantalla y el traductor del navegador sí.

Sin traducción: canonical al original#

Todo artículo existe en todas las URL. Si publico un post solo en portugués, /en/articles/<slug> no da 404: muestra el original con un aviso corto de que todavía no hay traducción.

Eso es bueno para quien navega el sitio en inglés, pero crea un riesgo: el mismo texto en portugués en dos URL. Según la guía de canonicalización, las versiones en idiomas distintos solo son duplicados si el contenido principal está en el mismo idioma. Y es justo el caso: la URL es inglesa, pero el texto es portugués.

La solución está en el comentario de articleMeta:

src/features/articles/article-seo.ts
/**
 * An article page. Its own version: canonical to itself, hreflang to every published translation.
 * A fallback (no translation, original shown): canonical to the original and no hreflang, so the
 * same text is never indexed twice.
 */
export function articleMeta(article: ArticleMeta, pageLocale: Locale, fallback: boolean) {
  const copy = DICTIONARIES[pageLocale].articles
  const ownPath = articlePath(article.slug, article.locale)
  const url = absoluteUrl(ownPath)
  const trail = copy.trails[article.trilha].label
  const versions = fallback
    ? []
    : published(ARTICLES.filter((other) => other.slug === article.slug)).map((other) => other.locale)
  // ...
}

En el fallback, article es el original en portugués, así que ownPath pasa a ser /artigos/<slug> y el canonical apunta ahí. Y la lista de versiones queda vacía: sin hreflang. El sitemap hace la misma cuenta y marca esa página como no indexable, así que ni siquiera aparece.

Con traducción, cada idioma es una página propia. Sin traducción, la URL existe pero le cede el lugar al original

Datos estructurados: BlogPosting y BreadcrumbList#

Además de las etiquetas, cada artículo lleva un JSON-LD con dos objetos. Google acepta BlogPosting y recomienda autor, fecha de publicación, fecha de actualización, título e imagen. No hay campo obligatorio, y los datos estructurados no garantizan ningún resultado especial en la búsqueda.

src/features/articles/article-seo.ts
{
  '@type': 'BlogPosting',
  '@id': `${url}#article`,
  headline: article.titulo,
  description: article.descricao,
  image: absoluteUrl(article.capa),
  datePublished: article.data,
  dateModified: article.atualizado ?? article.data,
  inLanguage: article.locale,
  author: personJsonLd(),
  publisher: { '@id': personJsonLd()['@id'] },
  ...(article.locale !== BASE_LOCALE && {
    translationOfWork: { '@id': `${absoluteUrl(articlePath(article.slug, BASE_LOCALE))}#article` },
  }),
},

translationOfWork es una propiedad de schema.org que conecta la traducción con el original por el @id. Google no la lista entre las que usa, y está bien: la puse para que la relación quede explícita para cualquiera que lea el JSON-LD, y cuesta una línea.

El segundo objeto es un BreadcrumbList: inicio, artículos, ruta y el artículo, con los nombres en el idioma de la página.

La portada también se traduce#

Cada idioma tiene su propia imagen para compartir. La capa-en.png lleva el título en inglés, y el og:image de la versión en inglés apunta a ella:

<meta property="og:locale" content="en_US"/>
<meta property="og:image" content="https://www.yasminlopes.dev/artigos/o-que-e-mcp/capa-en.png"/>

El og:locale cambia junto, y las otras versiones entran como og:locale:alternate. Antes del blog, todo enlace del sitio se convertía en la misma tarjeta con el og.png de la home.

Sitemap, RSS y llms.txt salen del build#

Después de que React Router prerenderiza todo, el buildEnd llama a finalizeStaticBuild, que escribe los archivos que no son páginas:

vite/static-build.ts
export async function finalizeStaticBuild(buildDirectory: string) {
  const client = join(buildDirectory, 'client')
  const [pages, published] = await Promise.all([listSitePages(), listPublishedArticles()])
 
  await writeOutput(client, 'sitemap.xml', renderSitemap(pages))
  await writeOutput(client, 'llms.txt', renderLlmsTxt(published))
  for (const locale of ARTICLE_LOCALES) {
    const inLocale = published.filter((article) => article.locale === locale)
    if (locale === BASE_LOCALE || inLocale.length > 0) await writeOutput(client, feedPath(locale), renderRss(locale, inLocale))
  }
  // ... removes the SPA fallback and moves /404 to 404.html
}
Del MDX a los archivos que leen los buscadores, todo en un npm run build

El sitemap#

Cada artículo publicado se convierte en una entrada con lastmod y las versiones en xhtml:link. Esta es la del post sobre MCP, directo del sitemap.xml en línea:

<url>
  <loc>https://www.yasminlopes.dev/artigos/o-que-e-mcp</loc>
  <lastmod>2026-11-16</lastmod>
  <xhtml:link rel="alternate" hreflang="pt-BR" href="https://www.yasminlopes.dev/artigos/o-que-e-mcp" />
  <xhtml:link rel="alternate" hreflang="en" href="https://www.yasminlopes.dev/en/articles/o-que-e-mcp" />
  <xhtml:link rel="alternate" hreflang="es" href="https://www.yasminlopes.dev/es/articulos/o-que-e-mcp" />
  <xhtml:link rel="alternate" hreflang="fr" href="https://www.yasminlopes.dev/fr/articles/o-que-e-mcp" />
  <xhtml:link rel="alternate" hreflang="x-default" href="https://www.yasminlopes.dev/artigos/o-que-e-mcp" />
</url>

Tres decisiones aquí vienen directo de la documentación de sitemap:

  • El lastmod es la fecha del artículo, el campo atualizado del frontmatter o la data. Nunca la fecha del build. Google solo usa el lastmod cuando es consistente y coincide con la página.
  • No hay priority ni changefreq. Google ignora los dos.
  • Todas las URL son absolutas. Pasan por absoluteUrl, que siempre usa https://www.yasminlopes.dev.

El robots.txt es corto y apunta al sitemap:

User-agent: *
Allow: /
 
Sitemap: https://www.yasminlopes.dev/sitemap.xml

Un RSS por idioma#

El portugués siempre tiene feed (/rss.xml). Los otros idiomas reciben el suyo (/es/rss.xml y compañía) en cuanto tienen un artículo publicado. Cada página del blog apunta al feed de su idioma con un <link rel="alternate" type="application/rss+xml">, que es lo que buscan los lectores de RSS.

llms.txt: una apuesta barata#

El llms.txt es una propuesta de Jeremy Howard, de septiembre de 2024: un archivo en Markdown en la raíz del sitio, con un título, un resumen y listas de enlaces, pensado para que lo lean los modelos de lenguaje. El mío lista cada artículo publicado en cada idioma:

curl -s https://www.yasminlopes.dev/llms.txt | head -7
# Yasmin Lopes
 
> Hands-on articles about React, React Native, TypeScript and back-end by Yasmin Lopes, drawn from real production problems.
 
Every article is written in Portuguese first, then translated to English, Spanish and French. Feeds: https://www.yasminlopes.dev/rss.xml, https://www.yasminlopes.dev/en/rss.xml, https://www.yasminlopes.dev/es/rss.xml, https://www.yasminlopes.dev/fr/rss.xml. Sitemap: https://www.yasminlopes.dev/sitemap.xml.
 
## Artigos de front-end, mobile e engenharia de software (pt-BR)

Siendo honesta: es una propuesta, no un estándar, y nada garantiza que un buscador lea este archivo. El propio Google, en la página sobre funciones de IA en la Búsqueda, dice que no necesitas crear archivos nuevos para la IA ni marcado especial para aparecer en las AI Overviews. El requisito es que la página esté indexada y pueda aparecer con snippet. O sea, lo que lleva el blog a las búsquedas con IA es el mismo SEO de siempre: HTML con el contenido, URL propia, nada bloqueado.

Mantengo el llms.txt porque sale gratis del mismo build y es un índice limpio del blog. Pero no cuento con él para nada.

El build frena lo que arruinaría el resultado#

Buena parte del SEO aquí no son etiquetas: es no dejar publicar algo mal. El frontmatter de cada idioma pasa por un schema en zod:

vite/articles/schema.ts
const translatable = {
  titulo: z.string().trim().min(10).max(60, 'até 60 caracteres (o Google corta o resto)'),
  tituloCapa: z.string().trim().min(5).max(48, 'até 48 caracteres (3 linhas na capa 1200x630)'),
  descricao: z
    .string()
    .trim()
    .min(50, 'descrição curta demais pro Google (mín. 50)')
    .max(170, 'o Google corta acima de ~160 caracteres'),
}

(Los mensajes de error están en portugués porque la que los lee soy yo.) Una corrección honesta a esos mensajes: Google no tiene un límite oficial de caracteres para el título ni para la descripción. Las páginas sobre title y snippet dicen que el texto se corta según el ancho de la pantalla. Los 60 y los 170 son reglas de la casa, para que quepa en el resultado en la mayoría de los casos.

El schema es .strict(): un campo mal escrito rompe el build, señalando el archivo. Y hay más cosas que se revisan antes de publicar:

  • Una imagen sin alt rompe el build, con el archivo y la línea. Los lectores de pantalla y Google Imágenes dependen de eso.
  • Toda imagen se convierte en AVIF y WebP en hasta cuatro anchos (480, 960, 1600 y 2400), con width y height medidos. La página no salta mientras cargan las imágenes.
  • Un artículo publicado sin portada rompe el build. Cada idioma usa su propia capa-<idioma>.png, o la del original.
  • Los borradores no entran al build de producción. En npm run dev aparecen, con noindex.

www, 308 y URL absolutas#

El dominio sin www responde con una redirección permanente:

curl -sI https://yasminlopes.dev/en/articles/o-que-e-mcp
# HTTP/2 308
# location: https://www.yasminlopes.dev/en/articles/o-que-e-mcp

Esta redirección viene de la configuración de dominio de Vercel, no del código. Según la documentación de redirecciones, 301 y 308 son las dos permanentes, y una redirección permanente es una señal fuerte de cuál URL es la canónica.

Del lado del código, la dirección oficial vive en una sola constante:

src/core/seo/site.ts
export const SITE_URL = 'https://www.yasminlopes.dev'
 
export function absoluteUrl(path: string) {
  return new URL(path, SITE_URL).href
}

Canonical, hreflang, og:url, sitemap, RSS y llms.txt pasan por ella. Google pide URL absoluta en el canonical, y así nunca se escapa una dirección sin www o con http.

Próximo paso: Search Console y Bing#

Todo lo anterior ya está en línea. Lo que falta es avisar a los buscadores, y es lo que voy a hacer ahora. Todavía no tengo datos de indexación ni de tráfico para mostrar: cuando los tenga, vuelvo aquí.

El plan, por si quieres seguirlo:

  1. Crear una propiedad de dominio en Google Search Console. Cubre www y sin www, http y https de una vez. La verificación es un registro TXT en el DNS, que debe quedarse ahí después.
  2. Enviar el sitemap en el informe de Sitemaps, pegando https://www.yasminlopes.dev/sitemap.xml. El robots.txt ya apunta a él, pero enviándolo veo los errores en el panel.
  3. Inspeccionar una URL de cada idioma para comprobar que Google ve el canonical y las versiones como espero.
  4. Registrar el sitio en Bing Webmaster Tools y enviar el mismo sitemap. Bing también acepta IndexNow, una forma de avisar al momento que una URL cambió.

Lo que aprendí#

Prerenderizar resolvió más que el SEO. El mismo HTML que lee el robot es lo primero que aparece para quien abre el enlace en un móvil lento. Y la tarjeta para compartir pasó a ser del artículo, no de la home.

Una fuente para cada cosa. Las URL salen de paths.ts, las páginas de listSitePages, las direcciones absolutas de absoluteUrl. Cuando hreflang, sitemap y rutas usan la misma función, no tienen cómo contradecirse.

No declares lo que no existe. hreflang solo para traducciones publicadas, sitemap solo con páginas indexables, lastmod solo con la fecha real del texto. Cada señal equivocada es un motivo para que el buscador desconfíe de las demás.

El build es el mejor revisor de SEO. Me olvido del alt, escribo mal un campo, hago una descripción demasiado larga. El build no lo deja pasar.

Cuidados#

  • hreflang sin vuelta se ignora. Si una versión no apunta de vuelta, el par entero pierde el efecto. Generar todas las etiquetas desde la misma lista lo evita.
  • No uses hreflang en la página de fallback. Texto en portugués en una URL /en es un duplicado del original: canonical al original, y nada más.
  • No redirijas por el idioma del navegador. Deja que la persona elija, con un selector que lleve a la URL traducida.
  • Un componente que lee window en el render rompe el prerender. En el build no hay navegador. Aquí uso un useIsClient, que es false en el prerender y en la hidratación, para mostrar esas partes solo en el cliente.
  • Canonical, redirecciones y sitemap son señales, no órdenes. Google elige la URL canónica considerando todo junto. Cuanto más coinciden, mejor.
  • llms.txt no reemplaza nada. Si la página no está indexada, el archivo no ayuda.

Referencias#

  • Front-end
  • seo
  • react
  • react-router
  • hreflang
  • i18n
  • vite

Escrito por

Ingeniera de software y diseñadora. Escribo sobre lo que encuentro construyendo apps, APIs y productos.