Front-end17 min de lecture
SEO multilingue avec React : hreflang, prérendu, sitemap
Comment j'ai amené mon blog React en 4 langues sur Google et dans la recherche par IA : prérendu, hreflang, canonical, JSON-LD, sitemap, RSS et llms.txt, code réel.

Quand j'ai décidé d'écrire des articles ici, j'avais un seul objectif : quelqu'un cherche une question sur Google et tombe sur mon site. En portugais, en anglais, en espagnol ou en français.
Le problème, c'est que mon portfolio était une SPA. Chaque URL renvoyait le même HTML, avec une <div id="root"> vide et les mêmes balises de partage. Pour un blog, c'est presque invisible.
Cet article raconte ce que j'ai changé pour que chaque article existe vraiment pour les moteurs de recherche, dans les 4 langues. Et comme l'article vit sur le blog lui-même, tout ce que vous voyez ici est le code qui tourne en ce moment.
TL;DR#
- Faites du prérendu. React Router 7 génère un HTML prêt par URL au build, sans serveur. Le robot reçoit le texte, le titre et les balises sans exécuter de JavaScript.
- Une URL par langue, avec les mots traduits :
/artigos,/en/articles,/es/articulos,/fr/articles. - hreflang sur toutes les versions, chacune pointant vers elle-même et vers les autres, plus un
x-default. Seules les traductions publiées y figurent. - Sans traduction, canonical vers l'original. La page existe dans la langue de l'URL, mais ne concurrence pas le texte en portugais.
- JSON-LD
BlogPostingetBreadcrumbList, et une couverture par langue dansog:image. - Le build génère le reste : sitemap avec hreflang et
lastmod, un flux RSS par langue,llms.txtet un vrai404.html. - Le build bloque aussi les erreurs : frontmatter validé avec zod, image sans
altet couverture manquante font échouer le build.
Le point de départ : une SPA qui disait la même chose sur chaque URL#
Voici le index.html du portfolio avant le blog, raccourci :
<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>Et le vercel.json envoyait n'importe quel chemin vers lui :
{
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}Trois problèmes pour un blog :
- Le HTML n'avait pas de contenu. Le texte n'apparaissait qu'après l'exécution du JavaScript dans le navigateur. Le titre de chaque page aussi : il changeait via
document.title, côté client. - Le canonical pointait vers l'accueil sur chaque URL. Un article disait « ma version officielle, c'est la page d'accueil ».
- Il n'y avait pas de 404. N'importe quelle adresse inventée renvoyait 200 avec le même HTML.
Google sait exécuter du JavaScript : la documentation JavaScript SEO décrit trois phases, exploration, rendu et indexation. Mais la même page dit que le prérendu reste une excellente idée, parce qu'il rend le site plus rapide et parce que tous les robots n'exécutent pas le JavaScript. Elle a même une section sur mon troisième problème : le soft 404 des SPA, quand une page qui n'existe pas répond comme si elle existait.
Le prérendu avec React Router 7#
Le tournant, c'est le passage du site au mode framework de React Router 7, avec prerender. Au build, il visite chaque URL et enregistre le HTML prêt. En production, il n'y a pas de serveur : ce ne sont que des fichiers statiques.
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 ConfigLe détail que je préfère : la liste des pages prérendues et le sitemap sortent de la même fonction, listSitePages. Une page ne peut pas être dans le sitemap sans exister, ni exister sans y être.
Chaque route exporte un meta avec ses balises, et React Router les écrit dans le <head> du HTML généré. Le titre, la description et le canonical sont donc déjà dans le fichier, avant tout JavaScript.
Le vercel.json a perdu le rewrite. Maintenant, il sert seulement le dossier du build (raccourci) :
{
"buildCommand": "npm run build",
"outputDirectory": "build/client",
"cleanUrls": true,
"trailingSlash": false
}Et le 404 est redevenu un 404. La route * est prérendue en /404 et la fin du build la renomme en 404.html, le fichier que Vercel sert pour les adresses inconnues :
curl -s -o /dev/null -w '%{http_code}\n' https://www.yasminlopes.dev/artigos/nao-existe
# 404Une URL par langue#
Google recommande une URL différente pour chaque langue, plutôt que de changer le texte par cookie ou selon les réglages du navigateur. Et il demande de ne pas rediriger automatiquement la personne vers la langue que vous pensez qu'elle parle.
Ici, chaque URL du blog naît dans un seul fichier :
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}`Le portugais est l'original et n'a pas de préfixe. Les traductions ont le préfixe et les mots traduits : en français, vous voyez articles et parcours dans la barre d'adresse. Les routes, les liens, le hreflang, le sitemap et le RSS appellent ces fonctions, donc une URL ne sort jamais différente d'un endroit à l'autre.
Les routes sont générées à partir de la même liste de langues :
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}` }),
]
})Les fichiers suivent la même idée. Chaque article est un dossier, avec l'original et les traductions côte à côte : content/artigos/<slug>/pt-br.mdx, en.mdx, es.mdx et fr.mdx.
hreflang : quatre versions qui se pointent#
Le hreflang dit à Google « cette page existe aussi dans ces autres langues, à ces adresses ». Les règles qui comptent, d'après la documentation sur les versions localisées :
- Chaque version se liste elle-même et toutes les autres.
- Il faut un lien retour. Si la page A pointe vers B et que B ne pointe pas vers A, les balises sont ignorées. C'est ainsi qu'un site tiers ne peut pas se déclarer traduction du vôtre.
x-defaultest la page pour qui parle une langue que vous n'avez pas.- On peut le déclarer dans le HTML, dans un en-tête HTTP ou dans le sitemap. Les trois se valent. J'utilise le HTML et le sitemap.
- Google n'utilise pas le hreflang pour détecter la langue de la page. Il la détecte seul. Le hreflang sert à relier les versions.
Toutes les pages du site passent par la même fonction, pageMeta. C'est elle qui transforme la liste des versions en balises :
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
]
}Regardez la ligne 3 : une seule langue ne génère aucun hreflang. Et le x-default est toujours le portugais, l'original et la seule version garantie.
C'est l'article qui décide quelles versions y figurent : uniquement les traductions publiées. Une traduction en brouillon n'apparaît jamais dans le hreflang, parce qu'elle n'existe pas dans le build de production, et un hreflang vers une page 404 ne fait que gêner.
Voici le HTML en ligne en ce moment, de la version anglaise de l'article sur 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"/>Le <html lang> suit aussi la page : lang="en" sur la version anglaise. Google ne s'en sert pas pour détecter la langue, mais les lecteurs d'écran et le traducteur du navigateur, oui.
Sans traduction : canonical vers l'original#
Chaque article existe à chaque URL. Si je publie un article seulement en portugais, /en/articles/<slug> ne renvoie pas de 404 : il affiche l'original avec un court avis indiquant qu'il n'y a pas encore de traduction.
C'est bien pour qui navigue sur le site en anglais, mais ça crée un risque : le même texte en portugais sur deux URL. Selon le guide sur la canonicalisation, des versions dans des langues différentes ne sont des doublons que si le contenu principal est dans la même langue. Et c'est exactement le cas ici : l'URL est anglaise, mais le texte est portugais.
La solution est dans le commentaire de articleMeta :
/**
* 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)
// ...
}Dans le fallback, article est l'original en portugais, donc ownPath devient /artigos/<slug> et le canonical pointe là. Et la liste des versions est vide : pas de hreflang. Le sitemap fait le même calcul et marque cette page comme non indexable, elle n'y est donc même pas listée.
Données structurées : BlogPosting et BreadcrumbList#
En plus des balises, chaque article porte un JSON-LD avec deux objets. Google prend en charge BlogPosting et recommande l'auteur, la date de publication, la date de modification, le titre et l'image. Aucune propriété n'est obligatoire, et les données structurées ne garantissent aucun résultat particulier dans la recherche.
{
'@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 est une propriété de schema.org qui relie la traduction à l'original par son @id. Google ne la cite pas parmi celles qu'il utilise, et ce n'est pas grave : je l'ai mise pour que la relation soit explicite pour quiconque lit le JSON-LD, et elle coûte une ligne.
Le second objet est un BreadcrumbList : accueil, articles, parcours et l'article, avec les noms dans la langue de la page.
La couverture aussi est traduite#
Chaque langue a sa propre image de partage. capa-en.png porte le titre en anglais, et le og:image de la version anglaise pointe vers elle :
<meta property="og:locale" content="en_US"/>
<meta property="og:image" content="https://www.yasminlopes.dev/artigos/o-que-e-mcp/capa-en.png"/>Le og:locale change avec, et les autres versions sont listées en og:locale:alternate. Avant le blog, chaque lien du site devenait la même carte avec le og.png de l'accueil.
Sitemap, RSS et llms.txt sortent du build#
Une fois que React Router a tout prérendu, le buildEnd appelle finalizeStaticBuild, qui écrit les fichiers qui ne sont pas des 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
}Le sitemap#
Chaque article publié devient une entrée avec lastmod et ses versions en xhtml:link. Voici celle de l'article sur MCP, tirée du sitemap.xml en ligne :
<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>Trois choix ici viennent directement de la documentation sur les sitemaps :
- Le
lastmodest la date de l'article, le champatualizadodu frontmatter ou ladata. Jamais la date du build. Google n'utilise lelastmodque s'il est exact de façon constante. - Il n'y a ni
prioritynichangefreq. Google ignore les deux. - Toutes les URL sont absolues. Elles passent par
absoluteUrl, qui utilise toujourshttps://www.yasminlopes.dev.
Le robots.txt est court et pointe vers le sitemap :
User-agent: *
Allow: /
Sitemap: https://www.yasminlopes.dev/sitemap.xmlUn flux RSS par langue#
Le portugais a toujours un flux (/rss.xml). Les autres langues ont le leur (/fr/rss.xml et compagnie) dès qu'elles ont un article publié. Chaque page du blog pointe vers le flux de sa langue avec un <link rel="alternate" type="application/rss+xml">, ce que cherchent les lecteurs RSS.
llms.txt : un pari bon marché#
Le llms.txt est une proposition de Jeremy Howard, de septembre 2024 : un fichier Markdown à la racine du site, avec un titre, un résumé et des listes de liens, pensé pour être lu par les modèles de langage. Le mien liste chaque article publié dans chaque langue :
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)Soyons honnêtes : c'est une proposition, pas un standard, et rien ne garantit qu'un moteur de recherche lise ce fichier. Google lui-même, sur sa page consacrée aux fonctionnalités d'IA dans la recherche, dit qu'il n'est pas nécessaire de créer de nouveaux fichiers pour l'IA ni de balisage spécial pour apparaître dans les AI Overviews. La condition, c'est que la page soit indexée et puisse s'afficher avec un extrait. Autrement dit, ce qui amène le blog dans la recherche par IA, c'est le bon vieux SEO : un HTML avec le contenu, une URL propre, rien de bloqué.
Je garde le llms.txt parce qu'il sort gratuitement du même build et que c'est un index propre du blog. Mais je ne compte pas dessus.
Le build bloque ce qui gâcherait le résultat#
Une bonne partie du SEO ici, ce ne sont pas des balises : c'est ne rien laisser publier de travers. Le frontmatter de chaque langue passe par un schéma zod :
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'),
}(Les messages d'erreur sont en portugais parce que c'est moi qui les lis.) Une correction honnête à ces messages : Google n'a pas de limite officielle de caractères pour le titre ni pour la description. Les pages sur les liens de titre et les extraits disent que le texte est tronqué selon la largeur de l'écran. Les 60 et 170 sont des règles maison, pour tenir dans le résultat dans la plupart des cas.
Le schéma est .strict() : un champ mal orthographié fait échouer le build, en indiquant le fichier. Et d'autres choses sont vérifiées avant publication :
- Une image sans
altfait échouer le build, avec le fichier et la ligne. Les lecteurs d'écran et Google Images en dépendent. - Chaque image devient AVIF et WebP en jusqu'à quatre largeurs (480, 960, 1600 et 2400), avec
widthetheightmesurés. La page ne saute pas pendant le chargement des images. - Un article publié sans couverture fait échouer le build. Chaque langue utilise sa propre
capa-<langue>.png, ou celle de l'original. - Les brouillons n'entrent pas dans le build de production. Dans
npm run dev, ils apparaissent, avecnoindex.
www, 308 et URL absolues#
Le domaine sans www répond par une redirection 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-mcpCette redirection vient de la configuration de domaine de Vercel, pas du code. D'après la documentation sur les redirections, 301 et 308 sont toutes deux permanentes, et une redirection permanente est un signal fort sur l'URL canonique.
Côté code, l'adresse officielle vit dans une seule constante :
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 et llms.txt passent par elle. Google demande des URL absolues dans le canonical, et ainsi aucune adresse sans www ou en http ne s'échappe.
Prochaine étape : Search Console et Bing#
Tout ce qui précède est en ligne. Il reste à prévenir les moteurs de recherche, et c'est ce que je vais faire maintenant. Je n'ai pas encore de données d'indexation ni de trafic à montrer : quand j'en aurai, je reviendrai ici.
Le plan, si vous voulez suivre :
- Créer une propriété de domaine dans Google Search Console. Elle couvre
wwwet sanswww,httpethttpsd'un coup. La validation se fait par un enregistrement TXT dans le DNS, qui doit rester en place ensuite. - Envoyer le sitemap dans le rapport Sitemaps, en collant
https://www.yasminlopes.dev/sitemap.xml. Lerobots.txtpointe déjà vers lui, mais en l'envoyant je vois les erreurs dans le tableau de bord. - Inspecter une URL par langue pour vérifier que Google voit le canonical et les versions comme je l'attends.
- Ajouter le site à Bing Webmaster Tools et envoyer le même sitemap. Bing prend aussi en charge IndexNow, un moyen de signaler tout de suite qu'une URL a changé.
Ce que j'ai appris#
Le prérendu a résolu plus que le SEO. Le même HTML que lit le robot est ce qui s'affiche en premier pour qui ouvre le lien sur un téléphone lent. Et la carte de partage appartient maintenant à l'article, plus à l'accueil.
Une source pour chaque chose. Les URL sortent de paths.ts, les pages de listSitePages, les adresses absolues de absoluteUrl. Quand hreflang, sitemap et routes utilisent la même fonction, ils ne peuvent pas se contredire.
Ne déclarez pas ce qui n'existe pas. hreflang seulement pour les traductions publiées, sitemap seulement avec les pages indexables, lastmod seulement avec la vraie date du texte. Chaque signal faux est une raison pour le moteur de douter des autres.
Le build est le meilleur relecteur SEO. J'oublie un alt, j'écris mal un champ, je fais une description trop longue. Le build ne laisse rien passer.
Points d'attention#
- Un hreflang sans lien retour est ignoré. Si une version ne pointe pas en retour, toute la paire perd son effet. Générer toutes les balises depuis la même liste l'évite.
- Pas de hreflang sur la page de fallback. Un texte portugais sur une URL
/enest un doublon de l'original : canonical vers l'original, et c'est tout. - Ne redirigez pas selon la langue du navigateur. Laissez la personne choisir, avec un sélecteur qui mène à l'URL traduite.
- Un composant qui lit
windowau rendu casse le prérendu. Au build, il n'y a pas de navigateur. Ici, j'utilise unuseIsClient, qui vautfalsependant le prérendu et l'hydratation, pour n'afficher ces parties que côté client. - Canonical, redirections et sitemap sont des signaux, pas des ordres. Google choisit l'URL canonique en pesant tout ensemble. Plus ils concordent, mieux c'est.
llms.txtne remplace rien. Si la page n'est pas indexée, le fichier n'aide pas.
Références#
- Google : principes de base du SEO JavaScript
- Google : versions localisées de vos pages (hreflang)
- Google : sites multirégionaux et multilingues
- Google : canonicalisation et comment indiquer une URL canonique
- Google : créer et envoyer un sitemap
- Google : redirections
- Google : données structurées d'article
- Google : liens de titre et extraits
- Google : fonctionnalités d'IA et votre site
- Search Console : valider la propriété et envoyer un sitemap
- llms.txt (proposition)
- schema.org : translationOfWork
- React Router : pre-rendering
À lire aussi

Front-end16 min de lecture
Créer des vidéos avec l'IA et Remotion : un cas réel

Front-end17 min de lecture
Partager un mot de passe en toute sécurité : Yush expliqué

Front-end14 min de lecture
Vite 8 avec Rolldown : j'ai mesuré le build de mon site