Todos os artigos

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.

Também em English, Español, Français

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 BlogPosting e BreadcrumbList, capa por idioma no og:image.
  • O build gera o resto: sitemap com hreflang e lastmod, um RSS por idioma, llms.txt e um 404.html de verdade.
  • O build também barra erro: frontmatter validado com zod, imagem sem alt e 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:

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>

E o vercel.json mandava qualquer caminho pra ele:

vercel.json (before)
{
  "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.

O mesmo artigo pra quem não roda JavaScript: antes e depois da pré-renderização

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.

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

O 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):

vercel.json
{
  "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
# 404

Uma 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ó:

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}`

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:

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}` }),
  ]
})

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:

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
  ]
}

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"/>
Cada versão aponta pra si e pras outras três, e o x-default fica com o original

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:

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)
  // ...
}

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.

Com tradução, cada idioma é uma página própria. Sem tradução, a URL existe mas cede o lugar pro original

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.

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` },
  }),
},

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:

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
}
Do MDX aos arquivos que os buscadores leem, tudo num npm run build

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, o atualizado do frontmatter ou a data. Nunca a data do build. O Google só usa o lastmod quando ele é consistente e confere com a página.
  • Não tem priority nem changefreq. O Google ignora os dois.
  • Todas as URLs são absolutas. Elas passam pela absoluteUrl, que usa sempre https://www.yasminlopes.dev.

O robots.txt é curto e aponta pro sitemap:

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

Um 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:

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'),
}

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 alt quebra 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 width e height medidos. A página não pula enquanto as imagens carregam.
  • Artigo publicado sem capa quebra o build. Cada idioma usa a capa-<idioma>.png dele, ou a do original.
  • Rascunho não entra no build de produção. No npm run dev ele aparece, com noindex.

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-mcp

Esse 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ó:

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 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:

  1. Criar uma propriedade de domínio no Google Search Console. Ela cobre www e sem www, http e https de uma vez. A verificação é um registro TXT no DNS, que deve continuar lá depois.
  2. Enviar o sitemap no relatório de Sitemaps, colando https://www.yasminlopes.dev/sitemap.xml. O robots.txt já aponta pra ele, mas enviando eu vejo os erros no painel.
  3. Inspecionar uma URL de cada idioma pra conferir que o Google vê o canonical e as versões do jeito que eu espero.
  4. 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ê window no render quebra a pré-renderização. No build não existe navegador. Aqui eu uso um useIsClient, que é false no 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.txt não substitui nada. Se a página não está indexada, o arquivo não ajuda.

Referências#

Atualizado em

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

Escrito por

Engenheira de software e designer. Escrevo sobre o que encontro construindo apps, APIs e produtos.