Internacionalização e hreflang em projetos Astro

Você publicou um artigo em português e a tradução em inglês. Para o leitor, a relação é óbvia. Para um buscador, são duas URLs diferentes, com textos diferentes. É preciso dizer explicitamente que uma é a versão localizada da outra.

Esse é o papel do hreflang: uma anotação que liga páginas equivalentes em idiomas ou regiões diferentes. Este texto explica as regras oficiais do Google, a relação com o atributo lang do HTML e como gerar as anotações em um projeto Astro. Os códigos são exemplos mínimos.

Se você ainda está montando a estrutura do site, comece pelo tutorial como criar um site internacional com Astro.

O que o hreflang faz e o que não faz

Segundo a documentação do Google sobre versões localizadas de uma página, o hreflang informa que um conjunto de páginas são variantes localizadas do mesmo conteúdo. Com isso, o buscador pode mostrar ao usuário a versão no idioma dele.

O hreflang não serve para detectar o idioma. A mesma página afirma que o Google não usa o hreflang nem o atributo lang do HTML para identificar o idioma de uma página. Isso é feito por algoritmos que analisam o texto. Na prática: se a página em /pt-br/ estiver com o corpo em inglês, nenhuma anotação conserta isso.

A documentação também esclarece quando versões em idiomas diferentes contam como conteúdo duplicado: só quando o conteúdo principal continua sem tradução. Traduzir apenas o menu e o rodapé não cria uma versão localizada.

As três formas de declarar

O Google aceita três métodos e diz que eles são equivalentes do ponto de vista dele. Usar mais de um não traz vantagem na busca.

• Tags no HTML. Elementos <link rel="alternate" hreflang="..."> dentro do <head>.
• Cabeçalho HTTP. Um cabeçalho Link na resposta do servidor, com o mesmo conjunto de versões.
• Sitemap XML. Cada <url> do sitemap lista suas variantes com elementos xhtml:link.

Em sites estáticos, as tags no HTML e o sitemap são as opções mais diretas. O importante é que as duas fontes digam exatamente a mesma coisa, se você usar ambas.

As regras que mais derrubam projetos

Reciprocidade

É a regra central. Cada versão de idioma precisa listar a si mesma e todas as outras versões. Se duas páginas não apontam uma para a outra, o Google ignora as anotações. O conjunto de links deve ser idêntico em todas as versões.

Exemplo, para uma página com versão em inglês e em português do Brasil:

<!-- exemplo: o mesmo bloco aparece nas duas páginas -->
<link rel="alternate" hreflang="en" href="https://exemplo.com/en/what-is-ai/" />
<link rel="alternate" hreflang="pt-BR" href="https://exemplo.com/pt-br/o-que-e-ia/" />
<link rel="alternate" hreflang="x-default" href="https://exemplo.com/en/what-is-ai/" />

URLs completas

As URLs precisam incluir protocolo e domínio. https://exemplo.com/en/ funciona. /en/ e //exemplo.com/en/ não. As versões podem estar em domínios diferentes.

Códigos de idioma e região

O primeiro código é o idioma, no padrão ISO 639-1 (en, pt, es). Um segundo código opcional indica a região, no padrão ISO 3166-1 alfa-2 (BR, PT, US). Alguns pontos da documentação do Google:

• Região sozinha não vale. BR não é um valor válido; pt-BR é.
• Códigos fora desses padrões, como es-419 (espanhol da América Latina), não são aceitos.
• Os valores não diferenciam maiúsculas de minúsculas, mas por convenção a região vai em maiúsculas.
• Códigos reservados como EU, UN e UK não têm efeito. O Reino Unido é GB.

O W3C, consórcio que mantém padrões da web, dá uma regra complementar no guia como escolher uma etiqueta de idioma: use a etiqueta mais curta possível e acrescente região só quando ela traz informação necessária. Se você só tem uma versão em português, pt pode bastar. Se quer deixar claro que é o português do Brasil, pt-BR é válido para o W3C e para o Google.

x-default: a página para quem sobra

O valor x-default não é um idioma. Segundo o Google, ele indica a página de reserva para usuários cujas configurações de idioma não correspondem a nenhuma versão disponível. A documentação o descreve como pensado principalmente para páginas de seleção de idioma.

Quando o site não tem uma página de seleção, uma opção é apontar o x-default para a edição principal. É a escolha do Token & Tech, descrita adiante.

Canonical e hreflang juntos

A tag canonical (rel="canonical") indica qual URL é a versão principal quando há páginas duplicadas. O erro clássico em sites multilíngues é apontar o canonical da versão em português para a versão em inglês. Isso diz ao buscador que a página em português é uma cópia.

O guia do Google sobre URLs canônicas orienta, ao usar hreflang, a especificar uma página canônica no mesmo idioma, ou o melhor substituto se ela não existir. O mesmo guia diz que, para fins de canonicalização, o Google prefere URLs que fazem parte de grupos de hreflang. Na prática, cada tradução aponta o canonical para si mesma.

lang e hreflang não são a mesma coisa

O atributo lang declara o idioma do conteúdo da própria página. O W3C recomenda sempre usá-lo na tag html, com etiquetas no padrão BCP 47, e marcar trechos em outro idioma com lang no elemento que os envolve. Para idiomas da direita para a esquerda, como o árabe, o atributo dir também é necessário.

O hreflang, em <link rel="alternate">, descreve outra página. Os dois se complementam. Uma página em português do Brasil teria <html lang="pt-BR"> e, no <head>, os links para suas versões em outros idiomas.

Como gerar hreflang no Astro

O guia de roteamento i18n do Astro cuida de prefixos de idioma, links localizados e fallback. Na versão consultada em 08/10/2026, ele não descreve geração automática de hreflang. Você precisa montá-lo. A receita de i18n da documentação mostra como organizar conteúdo e rotas por idioma, o que é a base para isso.

O ponto de partida é ter, para cada página, a lista de suas traduções. Uma forma simples é dar a cada tradução um identificador comum (por exemplo, um campo group na coleção de conteúdo) e, no build, reunir as páginas que compartilham esse valor.

Com a lista em mãos, um componente pode gerar as tags:

---
// src/components/Hreflang.astro: exemplo mínimo
// Requer `site` definido em astro.config.mjs.
interface Props {
  alternates: { hreflang: string; path: string }[]; // inclui a própria página
  xDefaultPath?: string;
}
const { alternates, xDefaultPath } = Astro.props;
const abs = (path: string) => new URL(path, Astro.site).href;
---
{alternates.length > 1 && alternates.map((a) => (
  <link rel="alternate" hreflang={a.hreflang} href={abs(a.path)} />
))}
{alternates.length > 1 && xDefaultPath && (
  <link rel="alternate" hreflang="x-default" href={abs(xDefaultPath)} />
)}

Duas escolhas deste exemplo merecem explicação. A função abs transforma o caminho em URL completa, como o Google exige. E a condição alternates.length > 1 evita emitir hreflang para páginas que só existem em um idioma.

No sitemap, a mesma lista vira elementos xhtml:link, com o namespace declarado no topo:

<!-- exemplo: trecho de sitemap.xml -->
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://exemplo.com/en/what-is-ai/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://exemplo.com/en/what-is-ai/"/>
    <xhtml:link rel="alternate" hreflang="pt-BR" href="https://exemplo.com/pt-br/o-que-e-ia/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://exemplo.com/en/what-is-ai/"/>
  </url>
  <url>
    <loc>https://exemplo.com/pt-br/o-que-e-ia/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://exemplo.com/en/what-is-ai/"/>
    <xhtml:link rel="alternate" hreflang="pt-BR" href="https://exemplo.com/pt-br/o-que-e-ia/"/>
    <xhtml:link rel="alternate" hreflang="x-default" href="https://exemplo.com/en/what-is-ai/"/>
  </url>
</urlset>

Cada <url> repete o conjunto completo, incluindo a si mesmo. É a reciprocidade aplicada ao sitemap.

Redirecionamento por idioma: por que evitar

É comum querer detectar o idioma do navegador e redirecionar o visitante. O guia do Google sobre sites multilíngues desaconselha redirecionamentos automáticos baseados em um palpite sobre o idioma, e também a adaptação de conteúdo por IP. O motivo técnico: o robô do Google costuma rastrear a partir dos Estados Unidos e sem o cabeçalho Accept-Language. Se o site decide pelo visitante, partes dele podem nunca ser encontradas. A recomendação é oferecer links para as outras versões e deixar a escolha com o leitor.

Caso documentado: o hreflang do Token & Tech

O site desta publicação é feito com Astro e gera o hreflang a partir de um roteador próprio, não do roteamento i18n nativo. Segundo a documentação técnica do projeto:

• Cada página tem um identificador de grupo, compartilhado pelas traduções, e uma marcação de indexável ou não.
• As alternativas de uma página são as outras páginas do mesmo grupo que também são indexáveis. Páginas noindex não recebem nem entram no hreflang.
• O x-default aponta para a versão em português, o idioma original e principal do site, servida na raiz (sem /pt-br/). Se a página não existir em português, não há x-default.
• As etiquetas usadas são en e pt-BR, enquanto as URLs usam /en/ e /pt-br/.
• As tags do <head> e o sitemap são gerados pela mesma lista de rotas, o que impede que digam coisas diferentes.
• Uma página só existe em um idioma quando a tradução real existe. Não há versão gerada com texto de outro idioma.

Erros comuns, em uma lista

Os cinco itens a seguir decorrem diretamente das regras do Google citadas acima:

• Página que não aponta de volta para a outra (sem reciprocidade).
• Página que não se inclui na própria lista.
• URLs relativas em vez de completas.
• Código de região sozinho ou inválido, como UK.
• Canonical de uma tradução apontando para outro idioma.

Na avaliação da redação, vale evitar também dois descuidos frequentes: listar no hreflang páginas noindex, que redirecionam ou que não existem, e publicar conteúdo principal não traduzido sob a URL de outro idioma.

O que levar deste texto

• hreflang liga versões equivalentes; ele não detecta idioma nem substitui uma tradução real.
• Reciprocidade, URLs completas e códigos ISO corretos são as três regras que mais importam.
• No Astro, gere o hreflang a partir de uma lista única de traduções e use essa lista no <head> e no sitemap.
• Canonical sempre no mesmo idioma, lang na tag html e nenhum redirecionamento automático pelo idioma do visitante.