Front-end16 min de leitura
SEO em React: meu blog em 4 idiomas no Google e nas IAs
Como levei meu blog React em 4 idiomas pro Google e pras buscas por IA: pré-renderização, hreflang, canonical, JSON-LD, sitemap, RSS e llms.txt, com o código real.

Quando eu decidi escrever artigos aqui, o objetivo era um só: alguém pesquisa uma dúvida no Google e cai no meu site. Em português, em inglês, em espanhol ou em francês.
O problema é que o meu portfólio era uma SPA. Toda URL devolvia o mesmo HTML, com uma <div id="root"> vazia e as mesmas tags de compartilhamento. Pra um blog, isso é quase invisível.
Esse post conta o que eu mudei pra cada artigo existir de verdade pros buscadores, nos 4 idiomas. E como o post mora no próprio blog, tudo que aparece aqui é o código que está rodando agora.
TL;DR#
- Pré-renderize. O React Router 7 gera um HTML pronto por URL no build, sem servidor. O robô recebe o texto, o título e as tags sem rodar JavaScript.
- Uma URL por idioma, com as palavras traduzidas:
/artigos,/en/articles,/es/articulos,/fr/articles. - hreflang em todas as versões, cada uma apontando pra si e pras outras, mais um
x-default. Só entram as traduções publicadas. - Sem tradução, canonical pro original. A página existe no idioma da URL, mas não disputa com o texto em português.
- JSON-LD
BlogPostingeBreadcrumbList, capa por idioma noog:image. - O build gera o resto: sitemap com hreflang e
lastmod, um RSS por idioma,llms.txte um404.htmlde verdade. - O build também barra erro: frontmatter validado com zod, imagem sem
alte capa faltando quebram o build.
O ponto de partida: uma SPA que dizia a mesma coisa em toda URL#
Esse era o index.html do portfólio antes do blog, resumido:
<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>E o vercel.json mandava qualquer caminho pra ele:
{
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}Três problemas pra um blog:
- O HTML não tinha conteúdo. O texto só aparecia depois do JavaScript rodar no navegador. O título de cada página também: ele mudava com
document.title, já no cliente. - O canonical apontava pra home em toda URL. Um artigo dizia "a versão oficial de mim é a página inicial".
- Não existia 404. Qualquer endereço inventado devolvia 200 com o mesmo HTML.
O Google consegue rodar JavaScript: a documentação de JavaScript SEO descreve três fases, rastreamento, renderização e indexação. Mas a mesma página diz que pré-renderizar ainda é uma ótima ideia, porque deixa o site mais rápido e porque nem todo robô roda JavaScript. E ela tem uma seção só sobre o meu terceiro problema: o soft 404 das SPAs, quando uma página que não existe responde como se existisse.
Pré-renderização com o React Router 7#
A virada foi passar o site pro modo framework do React Router 7, com prerender. No build, ele visita cada URL e salva o HTML pronto. Em produção não tem servidor: é tudo arquivo estático.
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 ConfigO detalhe que eu mais gosto: a lista de páginas pré-renderizadas e o sitemap saem da mesma função, a listSitePages. Não tem como uma página entrar no sitemap sem existir, nem existir sem entrar.
Cada página exporta um meta com as tags dela, e o React Router escreve isso no <head> do HTML gerado. Então o título, a descrição e o canonical já vêm no arquivo, antes de qualquer JavaScript.
O vercel.json perdeu o rewrite. Agora ele só serve a pasta do build (resumido):
{
"buildCommand": "npm run build",
"outputDirectory": "build/client",
"cleanUrls": true,
"trailingSlash": false
}E o 404 voltou a ser 404. A rota * é pré-renderizada em /404 e o fim do build renomeia pra 404.html, que é o arquivo que a Vercel serve pra endereço desconhecido:
curl -s -o /dev/null -w '%{http_code}\n' https://www.yasminlopes.dev/artigos/nao-existe
# 404Uma URL por idioma#
O Google recomenda uma URL diferente pra cada idioma, em vez de trocar o texto por cookie ou pela configuração do navegador. E pede pra não redirecionar a pessoa sozinho pro idioma que você acha que ela fala.
Aqui, toda URL do blog nasce num arquivo só:
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}`O português é o original e fica sem prefixo. As traduções ganham o prefixo e as palavras traduzidas: quem lê em espanhol vê articulos e ruta na barra de endereço. As rotas, os links, o hreflang, o sitemap e o RSS chamam essas funções, então uma URL nunca sai diferente de um lugar pro outro.
As rotas são geradas a partir da mesma lista de idiomas:
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}` }),
]
})Os arquivos seguem a mesma ideia. Cada artigo é uma pasta, com o original e as traduções lado a lado: content/artigos/<slug>/pt-br.mdx, en.mdx, es.mdx e fr.mdx.
hreflang: as quatro versões se apontando#
O hreflang diz ao Google "essa página existe também nesses outros idiomas, nesses endereços". As regras que importam, da documentação de versões localizadas:
- Cada versão lista a si mesma e todas as outras.
- Precisa ter volta. Se a página A aponta pra B e B não aponta pra A, as tags são ignoradas. É assim que um site alheio não consegue se declarar tradução do seu.
- O
x-defaulté a página pra quem fala um idioma que você não tem. - Dá pra declarar no HTML, num cabeçalho HTTP ou no sitemap. Os três valem o mesmo. Eu uso HTML e sitemap.
- O Google não usa o hreflang pra descobrir o idioma da página. Ele detecta sozinho. O hreflang serve pra ligar as versões.
Todas as páginas do site passam pela mesma função, a pageMeta. É ela que transforma a lista de versões em 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
]
}Repare na linha 3: um idioma sozinho não gera hreflang nenhum. E o x-default é sempre o português, que é o original e a única versão garantida.
E quem decide quais versões entram é o artigo: só as traduções publicadas. Uma tradução em rascunho nunca aparece no hreflang, porque ela não existe no build de produção, e um hreflang pra uma página 404 só atrapalha.
Esse é o HTML que está no ar agora, da versão em inglês do 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"/>O <html lang> também acompanha a página: lang="en" na versão em inglês. O Google não usa isso pra detectar o idioma, mas leitor de tela e tradutor do navegador usam.
O caso sem tradução: canonical pro original#
Todo artigo existe em todas as URLs. Se eu publico um post só em português, /en/articles/<slug> não dá 404: mostra o original com um aviso curto de que ainda não tem tradução.
Isso é bom pra quem navega no site em inglês, mas cria um risco: o mesmo texto em português em duas URLs. Pelo guia de canonicalização, versões em idiomas diferentes só são duplicatas se o conteúdo principal está no mesmo idioma. E é exatamente o caso aqui: a URL é inglesa, mas o texto é português.
A solução está no comentário da 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)
// ...
}No fallback, o article é o original em português, então o ownPath vira /artigos/<slug> e o canonical aponta pra lá. E a lista de versões fica vazia: sem hreflang. O sitemap faz a mesma conta e marca essa página como não indexável, então ela nem é listada.
Dados estruturados: BlogPosting e BreadcrumbList#
Além das tags, cada artigo leva um JSON-LD com dois objetos. O Google aceita BlogPosting e recomenda autor, data de publicação, data de atualização, título e imagem. Não tem campo obrigatório, e dados estruturados não garantem nenhum resultado especial na busca.
{
'@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` },
}),
},O translationOfWork é uma propriedade do schema.org que liga a tradução ao original pelo @id. O Google não lista ela entre as que usa, e tudo bem: eu coloquei pra relação ficar explícita pra qualquer um que leia o JSON-LD, e o custo é uma linha.
O segundo objeto é um BreadcrumbList: início, artigos, trilha e o artigo, com os nomes no idioma da página.
A capa também é traduzida#
Cada idioma tem a própria imagem de compartilhamento. A capa-en.png tem o título em inglês, e o og:image da versão em inglês aponta pra ela:
<meta property="og:locale" content="en_US"/>
<meta property="og:image" content="https://www.yasminlopes.dev/artigos/o-que-e-mcp/capa-en.png"/>O og:locale muda junto, e as outras versões entram como og:locale:alternate. Antes do blog, todo link do site virava o mesmo cartão com o og.png da home.
Sitemap, RSS e llms.txt saem do build#
Depois que o React Router pré-renderiza tudo, o buildEnd chama a finalizeStaticBuild, que escreve os arquivos que não são páginas:
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
}O sitemap#
Cada artigo publicado vira uma entrada com lastmod e as versões em xhtml:link. Esse é o do post sobre MCP, direto do sitemap.xml no ar:
<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>Três escolhas aqui vêm direto da documentação de sitemap:
- O
lastmodé a data do artigo, oatualizadodo frontmatter ou adata. Nunca a data do build. O Google só usa olastmodquando ele é consistente e confere com a página. - Não tem
prioritynemchangefreq. O Google ignora os dois. - Todas as URLs são absolutas. Elas passam pela
absoluteUrl, que usa semprehttps://www.yasminlopes.dev.
O robots.txt é curto e aponta pro sitemap:
User-agent: *
Allow: /
Sitemap: https://www.yasminlopes.dev/sitemap.xmlUm RSS por idioma#
O português sempre tem feed (/rss.xml). Os outros idiomas ganham o deles (/en/rss.xml e companhia) assim que têm um artigo publicado. Cada página do blog aponta pro feed do seu idioma com um <link rel="alternate" type="application/rss+xml">, que é o que leitores de RSS procuram.
llms.txt: uma aposta barata#
O llms.txt é uma proposta do Jeremy Howard, de setembro de 2024: um arquivo em Markdown na raiz do site, com um título, um resumo e listas de links, pensado pra ser lido por modelos de linguagem. O meu lista todo artigo publicado em 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)Sendo honesta: é uma proposta, não um padrão, e nada garante que um buscador leia esse arquivo. O próprio Google, na página sobre recursos de IA na busca, diz que você não precisa criar arquivos novos pra IA nem marcação especial pra aparecer nas Visões Gerais de IA. O requisito é a página estar indexada e poder aparecer com snippet. Ou seja, o que leva o blog pras buscas por IA é o mesmo SEO de sempre: HTML com o conteúdo, URL própria, nada bloqueado.
Eu mantenho o llms.txt porque ele sai de graça do mesmo build e é um índice limpo do blog. Mas não conto com ele pra nada.
O build barra o que estragaria o resultado#
Boa parte do SEO aqui não é tag: é não deixar publicar errado. O frontmatter de cada idioma passa por um schema em 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'),
}Um ajuste de honestidade nas mensagens: o Google não tem limite oficial de caracteres pro título nem pra descrição. As páginas sobre title e snippet dizem que o texto é cortado conforme a largura da tela. Os 60 e os 170 são regra da casa, pra caber no resultado na maioria dos casos.
O schema é .strict(): campo com erro de digitação quebra o build, apontando o arquivo. E tem mais coisa conferida antes de publicar:
- Imagem sem
altquebra o build, com o arquivo e a linha. Leitor de tela e Google Imagens dependem disso. - Toda imagem vira AVIF e WebP em até quatro larguras (480, 960, 1600 e 2400), com
widtheheightmedidos. A página não pula enquanto as imagens carregam. - Artigo publicado sem capa quebra o build. Cada idioma usa a
capa-<idioma>.pngdele, ou a do original. - Rascunho não entra no build de produção. No
npm run devele aparece, comnoindex.
www, 308 e URLs absolutas#
O domínio sem www responde com um redirecionamento 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-mcpEsse redirecionamento vem da configuração de domínio da Vercel, não do código. Pela documentação de redirecionamentos, 301 e 308 são os dois permanentes, e um redirecionamento permanente é um sinal forte de qual URL é a canônica.
Do lado do código, o endereço oficial mora numa constante só:
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 e llms.txt passam por ela. O Google pede URL absoluta no canonical, e assim nunca escapa um endereço sem www ou com http.
Próximo passo: Search Console e Bing#
Tudo até aqui está no ar. O que falta é avisar os buscadores, e é o que eu vou fazer agora. Ainda não tenho dados de indexação nem de tráfego pra mostrar: quando tiver, eu volto aqui.
O plano, pra quem quiser seguir junto:
- Criar uma propriedade de domínio no Google Search Console. Ela cobre
wwwe semwww,httpehttpsde uma vez. A verificação é um registro TXT no DNS, que deve continuar lá depois. - Enviar o sitemap no relatório de Sitemaps, colando
https://www.yasminlopes.dev/sitemap.xml. Orobots.txtjá aponta pra ele, mas enviando eu vejo os erros no painel. - Inspecionar uma URL de cada idioma pra conferir que o Google vê o canonical e as versões do jeito que eu espero.
- Cadastrar o site no Bing Webmaster Tools e enviar o mesmo sitemap. O Bing também aceita o IndexNow, um jeito de avisar na hora que uma URL mudou.
O que aprendi#
Pré-renderizar resolveu mais do que SEO. O mesmo HTML que o robô lê é o que aparece primeiro pra quem abre o link num celular lento. E o cartão de compartilhamento passou a ser do artigo, não da home.
Uma fonte pra cada coisa. As URLs saem do paths.ts, as páginas saem da listSitePages, os endereços absolutos saem da absoluteUrl. Quando hreflang, sitemap e rota usam a mesma função, eles não têm como discordar.
Não declare o que não existe. Hreflang só pras traduções publicadas, sitemap só com as páginas indexáveis, lastmod só com a data real do texto. Cada sinal errado é um motivo pro buscador desconfiar dos outros.
O build é o melhor revisor de SEO. Eu esqueço alt, erro o nome de campo, escrevo descrição comprida. O build não deixa passar.
Cuidados#
- hreflang sem volta é ignorado. Se uma versão não aponta de volta, o par inteiro perde o efeito. Gerar todas as tags da mesma lista evita isso.
- Não use hreflang na página de fallback. Texto em português numa URL
/ené duplicata do original: canonical pro original, e só. - Não redirecione por idioma do navegador. Deixe a pessoa escolher, com um seletor que leva pra URL traduzida.
- Componente que lê
windowno render quebra a pré-renderização. No build não existe navegador. Aqui eu uso umuseIsClient, que éfalseno pré-render e na hidratação, pra só mostrar essas partes no cliente. - Canonical, redirecionamento e sitemap são sinais, não ordens. O Google decide a URL canônica considerando tudo junto. Quanto mais eles concordam, melhor.
llms.txtnão substitui nada. Se a página não está indexada, o arquivo não ajuda.
Referências#
- Google: JavaScript SEO basics
- Google: versões localizadas da página (hreflang)
- Google: sites multirregionais e multilíngues
- Google: canonicalização e como indicar a URL canônica
- Google: como criar um sitemap
- Google: redirecionamentos
- Google: dados estruturados de artigo
- Google: title e snippet
- Google: recursos de IA e o seu site
- Search Console: verificar a propriedade e enviar o sitemap
- llms.txt (proposta)
- schema.org: translationOfWork
- React Router: pré-renderização
Leia também

Front-end14 min de leitura
Como eu crio vídeos com IA usando Remotion: um caso real

Front-end15 min de leitura
Como compartilhar senhas com segurança: o Yush por dentro

Front-end13 min de leitura
Vite 8 com Rolldown na prática: medi o build do meu site