Front-end16 min read
Multilingual SEO in React: hreflang, prerendering, sitemap
How I got my React blog in 4 languages into Google and AI search: prerendering, hreflang, canonical, JSON-LD, sitemap, RSS and llms.txt, with the real code.

When I decided to write articles here, I had one goal: someone searches a question on Google and lands on my site. In Portuguese, English, Spanish or French.
The problem: my portfolio was a SPA. Every URL returned the same HTML, with an empty <div id="root"> and the same share tags. For a blog, that is close to invisible.
This post covers what I changed so each article really exists for search engines, in all 4 languages. And since the post lives on the blog itself, everything you see here is the code running right now.
TL;DR#
- Prerender. React Router 7 writes a ready HTML file per URL at build time, with no server. The crawler gets the text, the title and the tags without running JavaScript.
- One URL per language, with translated words:
/artigos,/en/articles,/es/articulos,/fr/articles. - hreflang on every version, each one pointing to itself and to the others, plus an
x-default. Only published translations are listed. - No translation, canonical to the original. The page exists in the URL's language, but it doesn't compete with the Portuguese text.
BlogPostingandBreadcrumbListJSON-LD, and a cover per language inog:image.- The build writes the rest: a sitemap with hreflang and
lastmod, one RSS feed per language,llms.txtand a real404.html. - The build also blocks mistakes: frontmatter validated with zod, an image without
altor a missing cover fails the build.
The starting point: a SPA that said the same thing on every URL#
This was the portfolio's index.html before the blog, trimmed:
<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>And vercel.json sent every path to it:
{
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}Three problems for a blog:
- The HTML had no content. The text only showed up after JavaScript ran in the browser. So did each page's title: it changed through
document.title, on the client. - The canonical pointed to the home page on every URL. An article was saying "my official version is the home page".
- There was no 404. Any made-up address returned 200 with the same HTML.
Google can run JavaScript: the JavaScript SEO docs describe three phases, crawling, rendering and indexing. But the same page says prerendering is still a great idea, because it makes the site faster and because not every bot can run JavaScript. It even has a section about my third problem: the soft 404 in single-page apps, when a page that doesn't exist answers as if it did.
Prerendering with React Router 7#
The turning point was moving the site to React Router 7's framework mode, with prerender. At build time, it visits each URL and saves the ready HTML. In production there is no server: it's all static files.
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 ConfigMy favorite detail: the list of prerendered pages and the sitemap come from the same function, listSitePages. A page can't be in the sitemap without existing, or exist without being in it.
Each route exports a meta with its tags, and React Router writes them into the <head> of the generated HTML. So the title, the description and the canonical are already in the file, before any JavaScript.
vercel.json lost the rewrite. Now it only serves the build folder (trimmed):
{
"buildCommand": "npm run build",
"outputDirectory": "build/client",
"cleanUrls": true,
"trailingSlash": false
}And 404 is a 404 again. The * route is prerendered at /404 and the end of the build renames it to 404.html, the file Vercel serves for unknown addresses:
curl -s -o /dev/null -w '%{http_code}\n' https://www.yasminlopes.dev/artigos/nao-existe
# 404One URL per language#
Google recommends a different URL for each language, instead of swapping the text with cookies or browser settings. It also asks you not to redirect people automatically to the language you think they speak.
Here, every blog URL is born in a single file:
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}`Portuguese is the original and has no prefix. Translations get the prefix and translated words: Spanish readers see articulos and ruta in the address bar. Routes, links, hreflang, the sitemap and RSS all call these functions, so a URL never comes out different from one place to another.
The routes are generated from the same list of languages:
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}` }),
]
})The files follow the same idea. Each article is a folder, with the original and the translations side by side: content/artigos/<slug>/pt-br.mdx, en.mdx, es.mdx and fr.mdx.
hreflang: four versions pointing at each other#
hreflang tells Google "this page also exists in these other languages, at these addresses". The rules that matter, from the localized versions docs:
- Each version lists itself and all the others.
- Links must go both ways. If page A points to B and B doesn't point back to A, the tags are ignored. That's how someone else's site can't declare itself a translation of yours.
x-defaultis the page for people who speak a language you don't have.- You can declare it in the HTML, in an HTTP header or in the sitemap. All three are equivalent. I use HTML and the sitemap.
- Google doesn't use hreflang to detect a page's language. It detects it on its own. hreflang is there to connect the versions.
Every page on the site goes through the same function, pageMeta. That's where the list of versions turns into tags:
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
]
}Look at line 3: a single language produces no hreflang at all. And x-default is always Portuguese, the original and the only version that is guaranteed to exist.
The article decides which versions are listed: only published translations. A draft translation never shows up in hreflang, because it doesn't exist in the production build, and an hreflang to a 404 page only gets in the way.
This is the HTML live right now, from the English version of the MCP post:
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"/><html lang> follows the page too: lang="en" on the English version. Google doesn't use it to detect the language, but screen readers and the browser's translator do.
No translation: canonical to the original#
Every article exists at every URL. If I publish a post only in Portuguese, /en/articles/<slug> isn't a 404: it shows the original with a short notice that there is no translation yet.
That's good for someone browsing the site in English, but it creates a risk: the same Portuguese text at two URLs. According to the canonicalization guide, versions in different languages are only duplicates when the main content is in the same language. And that's exactly the case here: the URL is English, but the text is Portuguese.
The fix is spelled out in the articleMeta comment:
/**
* 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)
// ...
}In the fallback, article is the Portuguese original, so ownPath becomes /artigos/<slug> and the canonical points there. And the list of versions is empty: no hreflang. The sitemap does the same math and marks that page as not indexable, so it isn't even listed.
Structured data: BlogPosting and BreadcrumbList#
Besides the tags, each article carries JSON-LD with two objects. Google supports BlogPosting and recommends author, publish date, modified date, headline and image. No property is required, and structured data doesn't guarantee any special result in search.
{
'@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 is a schema.org property that links the translation to the original by @id. Google doesn't list it among the ones it uses, and that's fine: I added it so the relationship is explicit for anyone reading the JSON-LD, and it costs one line.
The second object is a BreadcrumbList: home, articles, track and the article, with names in the page's language.
The cover is translated too#
Each language has its own share image. capa-en.png has the English title, and the English version's og:image points to it:
<meta property="og:locale" content="en_US"/>
<meta property="og:image" content="https://www.yasminlopes.dev/artigos/o-que-e-mcp/capa-en.png"/>og:locale changes with it, and the other versions are listed as og:locale:alternate. Before the blog, every link to the site became the same card with the home page's og.png.
Sitemap, RSS and llms.txt come out of the build#
After React Router prerenders everything, buildEnd calls finalizeStaticBuild, which writes the files that aren't pages:
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
}The sitemap#
Each published article becomes an entry with lastmod and its versions as xhtml:link. This is the MCP post's entry, straight from the live sitemap.xml:
<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>Three choices here come straight from the sitemap docs:
lastmodis the article's date, theatualizadofield from the frontmatter or thedata. Never the build date. Google only useslastmodwhen it's consistently accurate.- There's no
priorityorchangefreq. Google ignores both. - All URLs are absolute. They go through
absoluteUrl, which always useshttps://www.yasminlopes.dev.
robots.txt is short and points to the sitemap:
User-agent: *
Allow: /
Sitemap: https://www.yasminlopes.dev/sitemap.xmlOne RSS feed per language#
Portuguese always has a feed (/rss.xml). The other languages get theirs (/en/rss.xml and so on) as soon as they have a published article. Each blog page points to its language's feed with a <link rel="alternate" type="application/rss+xml">, which is what feed readers look for.
llms.txt: a cheap bet#
llms.txt is a proposal by Jeremy Howard, from September 2024: a Markdown file at the site root, with a title, a summary and lists of links, meant to be read by language models. Mine lists every published article in each language:
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)To be honest: it's a proposal, not a standard, and nothing guarantees a search engine reads it. Google itself, on its page about AI features in Search, says you don't need new AI text files or special markup to appear in AI Overviews. The requirement is for the page to be indexed and eligible to show with a snippet. In other words, what gets the blog into AI search is the same old SEO: HTML with the content, its own URL, nothing blocked.
I keep llms.txt because it comes for free from the same build and it's a clean index of the blog. But I don't count on it for anything.
The build blocks what would hurt the result#
A good part of the SEO here isn't tags: it's not letting anything ship broken. Each language's frontmatter goes through a zod schema:
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'),
}(The error messages are in Portuguese because I'm the one reading them.) One honest correction to those messages: Google has no official character limit for titles or descriptions. The pages on title links and snippets say the text is truncated to fit the device width. The 60 and 170 are house rules, to fit the result in most cases.
The schema is .strict(): a misspelled field fails the build, naming the file. And more gets checked before publishing:
- An image without
altfails the build, with the file and the line. Screen readers and Google Images depend on it. - Every image becomes AVIF and WebP in up to four widths (480, 960, 1600 and 2400), with measured
widthandheight. The page doesn't jump while images load. - A published article without a cover fails the build. Each language uses its own
capa-<lang>.png, or the original's. - Drafts don't make it into the production build. In
npm run devthey show up, withnoindex.
www, 308 and absolute URLs#
The domain without www answers with a permanent redirect:
curl -sI https://yasminlopes.dev/en/articles/o-que-e-mcp
# HTTP/2 308
# location: https://www.yasminlopes.dev/en/articles/o-que-e-mcpThis redirect comes from Vercel's domain settings, not from the code. According to the redirects docs, 301 and 308 are both permanent, and a permanent redirect is a strong signal of which URL is canonical.
On the code side, the official address lives in a single constant:
export const SITE_URL = 'https://www.yasminlopes.dev'
export function absoluteUrl(path: string) {
return new URL(path, SITE_URL).href
}Canonical, hreflang, og:url, the sitemap, RSS and llms.txt all go through it. Google asks for absolute URLs in the canonical, and this way an address without www or with http never slips out.
Next step: Search Console and Bing#
Everything so far is live. What's left is telling the search engines, and that's what I'm doing next. I don't have indexing or traffic data to show yet: when I do, I'll come back here.
The plan, if you want to follow along:
- Create a domain property in Google Search Console. It covers
wwwand non-www,httpandhttpsat once. Verification is a TXT record in DNS, which should stay there afterwards. - Submit the sitemap in the Sitemaps report, pasting
https://www.yasminlopes.dev/sitemap.xml.robots.txtalready points to it, but submitting it shows the errors in the dashboard. - Inspect one URL per language to check that Google sees the canonical and the versions the way I expect.
- Add the site to Bing Webmaster Tools and submit the same sitemap. Bing also supports IndexNow, a way to announce right away that a URL changed.
What I learned#
Prerendering solved more than SEO. The same HTML the crawler reads is what shows up first for someone opening the link on a slow phone. And the share card now belongs to the article, not the home page.
One source for each thing. URLs come from paths.ts, pages from listSitePages, absolute addresses from absoluteUrl. When hreflang, the sitemap and the routes use the same function, they can't disagree.
Don't declare what doesn't exist. hreflang only for published translations, the sitemap only with indexable pages, lastmod only with the text's real date. Each wrong signal is a reason for a search engine to distrust the others.
The build is the best SEO reviewer. I forget alt, misspell a field, write a description that's too long. The build doesn't let it through.
Watch out for#
- hreflang without a return link is ignored. If one version doesn't point back, the whole pair loses its effect. Generating every tag from the same list avoids that.
- Don't use hreflang on the fallback page. Portuguese text at an
/enURL is a duplicate of the original: canonical to the original, and that's it. - Don't redirect based on the browser language. Let people choose, with a switcher that leads to the translated URL.
- A component that reads
windowduring render breaks prerendering. There's no browser at build time. Here I use auseIsClienthook, which isfalseduring prerender and hydration, to show those parts only on the client. - Canonical, redirects and sitemaps are signals, not orders. Google picks the canonical URL by weighing everything together. The more they agree, the better.
llms.txtdoesn't replace anything. If the page isn't indexed, the file won't help.
References#
- Google: JavaScript SEO basics
- Google: localized versions of your pages (hreflang)
- Google: multi-regional and multilingual sites
- Google: canonicalization and how to specify a canonical URL
- Google: build and submit a sitemap
- Google: redirects
- Google: article structured data
- Google: title links and snippets
- Google: AI features and your website
- Search Console: verify site ownership and submit a sitemap
- llms.txt (proposal)
- schema.org: translationOfWork
- React Router: pre-rendering
Read next

Front-end15 min read
How I make AI videos with Remotion: a real case study

Front-end15 min read
How to share passwords securely: inside Yush

Front-end13 min read
Vite 8 vs Vite 7 with Rolldown: I benchmarked my build