Pitch: Como estruturei um site estático em 5 idiomas: hreflang, sitemap com xhtml:link e os erros que quase cometi
Nos últimos meses montei um catálogo pequeno de ferramentas de IA em 5 idiomas (EN/JA/KO/ES/PT). O produto em si é simples; o que deu trabalho foi fazer o multi-idioma direito. Compartilho o que aprendi, porque muito tutorial de i18n para por "traduza as strings".
1. Um idioma por caminho, não por cookie ou Accept-Language
Escolhi subdiretórios: /en/, /ja/, /ko/, /es/, /pt/. Motivos:
- Cada versão tem uma URL própria e indexável. Se você troca o idioma via cookie ou cabeçalho na mesma URL, o buscador geralmente só enxerga uma versão.
- Dá para compartilhar o link já no idioma certo.
- Não precisa de lógica no servidor: tudo pode ser estático.
Detalhe fácil de esquecer: o atributo <html lang> precisa mudar por página (lang="pt", lang="ko"…). Leitores de tela e a hifenização do navegador dependem disso.
2. hreflang: todos apontam para todos (inclusive para si mesmos)
Cada página tem um bloco assim no <head>:
Regras que aprendi:
- O conjunto precisa ser recíproco. Se /pt/ aponta para /ja/, /ja/ tem que apontar de volta para /pt/. Senão o sinal é ignorado.
- A página inclui a si mesma na lista.
x-defaultdiz qual versão mostrar quando nenhum idioma bate. Usei inglês.- O canonical de cada idioma aponta para a própria página (/pt/ → /pt/), nunca para a versão em inglês. Se o canonical de /pt/ apontasse para /en/, você diria ao buscador que as outras versões são duplicatas, contradizendo o hreflang.
- Dica geral: vale gerar esse bloco a partir de uma única lista de idiomas, em vez de escrever na mão em 5 idiomas × N páginas.
3. Sitemap com xhtml:link
Além do <head>, dá para declarar as alternativas no sitemap:
(lembre de declarar xmlns:xhtml="http://www.w3.org/1999/xhtml" no <urlset>). Cada URL de cada idioma entra como <url> própria, com a lista completa de alternativas. Para páginas como "sobre", "privacidade" e "divulgação de afiliados", fiz o mesmo: 4 páginas × 5 idiomas = 20 entradas.
4. Segurança de graça: CSP restritiva
Como o site é estático e não tem formulário, deu para usar uma Content-Security-Policy bem fechada: default-src 'self'; script-src 'self'; form-action 'none'; frame-ancestors 'none', liberando no connect-src só o domínio de analytics. Junto: X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy desligando câmera/microfone/geolocalização. Em site estático isso custa quase nada e evita surpresas se algum script de terceiro tentar entrar.
5. O que ainda não resolvi bem
- Raiz (/): hoje a raiz serve o conteúdo em inglês direto. Um redirect para /en/ (ou uma página de escolha de idioma) talvez fosse mais limpo.
- Tradução de conteúdo que muda: preços de ferramentas mudam o tempo todo. Manter 5 idiomas sincronizados é muito mais difícil do que traduzir a interface.
Contexto
O site é o TOOLPORT, um catálogo de 57 ferramentas de IA em 13 categorias com preços e planos gratuitos conferidos nas páginas oficiais, sem ranking: https://toolportmarket.com/pt/?utm_source=tabnews&utm_medium=community&utm_campaign=tabnews_i18n
Se alguém já lidou com hreflang em escala (centenas de páginas × idiomas), queria saber como vocês validam a reciprocidade. Uma checagem automática (por exemplo, um script que lê cada página e confere se todas as alternativas apontam de volta) parece o caminho mais seguro.