Como definir o idioma de uma página criada por IA

Uma landing page em português pode chegar ao navegador com <html lang="en"> porque o agente reutilizou um template. Visualmente, nada parece quebrado. Para síntese de voz, tradução, hifenização e outros recursos que processam texto, a página declarou a regra errada.

O problema também aparece em sites multilíngues. A rota em espanhol herda português, uma citação em inglês não marca a mudança ou o seletor troca o conteúdo sem atualizar o idioma do documento.

Este guia mostra como escolher a língua predominante, usar lang sem exagero, validar o HTML produzido e retestar a versão publicada.

O idioma é parte do contrato do documento

O critério 3.1.1 da WCAG 2.2 exige que a língua humana padrão da página possa ser determinada programaticamente. O critério 3.1.2 trata de trechos e frases em outra língua, com exceções para nomes próprios, termos técnicos, palavras de idioma indeterminado e expressões incorporadas ao idioma ao redor.

Essa informação ajuda tecnologias assistivas a escolher regras de pronúncia. Navegadores e outras ferramentas também podem usar o idioma para processamento de texto e oferta de tradução.

Em uma página em português do Brasil, a declaração básica é:

<!doctype html>
<html lang="pt-BR">

Não use lang="br". BR é a região, não a língua. O idioma é pt, com o subtipo regional opcional BR.

Check 1: identifique a língua predominante da rota

Não escolha o valor pelo país do negócio, domínio ou idioma do painel. Leia o conteúdo entregue naquela URL.

Pergunte:

• em qual língua estão título, navegação e conteúdo principal?
• qual língua domina quando há mais de uma?
• a rota representa uma versão traduzida completa?
• mensagens de validação e conteúdo carregado depois seguem a mesma língua?
• header e footer pertencem ao mesmo locale da página?

Uma página brasileira com termos como “deploy”, “login” e “checkout” ainda pode ter português como idioma padrão. A WCAG reconhece exceções para termos técnicos e expressões incorporadas ao uso ao redor.

Se duas línguas aparecem em proporção semelhante, a orientação da W3C para idioma da página recomenda usar como padrão a primeira língua presente. Na prática, uma rota de marketing ganha clareza quando cada versão tem uma língua predominante definida.

Check 2: use uma tag válida e suficientemente específica

A técnica H57 da W3C orienta colocar lang no elemento html, usar uma tag válida segundo BCP 47 e refletir a língua principal.

Exemplos comuns:

<html lang="pt-BR">
<html lang="pt-PT">
<html lang="en">
<html lang="es">

Use a região quando ela descreve uma variação relevante do conteúdo. Não monte tags por intuição. A orientação de internacionalização da W3C aponta o BCP 47 e o registro de subtags da IANA como referências.

Evite valores como:

<html lang="portuguese">
<html lang="BR">
<html lang="pt_BR">

O idioma não é um nome livre, e subtags usam hífen em vez de underscore.

Check 3: corrija a fonte do template

Não edite apenas o HTML da pasta de build se o framework recria o arquivo a cada execução. Localize onde o documento raiz define o atributo.

Procure por:

<html lang=
document.documentElement.lang
locale
defaultLocale
layout raiz
template HTML

Em site de uma língua, mantenha uma constante simples perto do documento raiz. Em site com rotas traduzidas, derive o valor do locale validado da rota. Não aceite qualquer string da URL como lang.

Depois gere a build e abra o HTML resultante. O artigo de revisão de HTML semântico explica por que a fonte e o documento entregue precisam ser avaliados separadamente.

Check 4: marque mudanças reais de idioma

Quando uma frase ou passagem muda de língua, aplique lang no menor contêiner que cobre o trecho completo:

<p>
  A equipe resumiu o princípio como
  <q lang="en">build once, verify in public</q>.
</p>

Para uma citação inteira:

<blockquote lang="es">El sitio debe probarse en la URL publicada.</blockquote>

O valor é herdado pelos descendentes até outro elemento declarar uma mudança. Não repita lang em cada palavra de um parágrafo já marcado.

Também não marque automaticamente toda palavra de origem estrangeira. “MCP”, “deploy”, nomes de produto e termos técnicos podem se encaixar nas exceções ou no vocabulário usado pelo público. Marcação excessiva pode produzir trocas de voz mais incômodas do que a pronúncia original.

Quando houver dúvida, teste a passagem com as tecnologias assistivas previstas e peça revisão a alguém que conheça o idioma.

Check 5: não confunda idioma com direção do texto

lang identifica a língua. dir controla a direção base quando necessário.

Conteúdo em árabe ou hebraico pode exigir uma decisão de direção além da tag de idioma:

<p lang="ar" dir="rtl">...</p>

Não adicione dir="rtl" apenas porque uma língua costuma usar escrita da direita para a esquerda. Valores, nomes, código e trechos mistos podem precisar de isolamento ou direção automática. Esse trabalho pede conteúdo real para teste, não uma substituição mecânica em todo elemento.

Para português, inglês e espanhol em alfabeto latino, o foco deste guia continua sendo lang.

Check 6: revise páginas que mudam de idioma no cliente

Alguns sites trocam o conteúdo sem navegar para outra rota. Nesse caso, atualizar os textos e esquecer o elemento raiz deixa o documento com a língua anterior.

Depois da troca, confira:

• document.documentElement.lang;
• título da página;
• navegação e conteúdo principal;
• mensagens de formulário;
• conteúdo de modal e banner;
• alternativas de imagem;
• metadados e links alternativos quando o projeto os usa;
• estado persistido e comportamento ao recarregar.

Prefira rotas estáveis para cada locale quando SEO, compartilhamento e histórico importam. Uma troca apenas em memória pode criar uma página difícil de reproduzir e validar.

O guia de revisão de title e meta description ajuda a manter metadados alinhados ao idioma e à intenção da rota.

Check 7: teste conteúdo carregado depois

Formulários, consentimento, chat, checkout e widgets de terceiros podem introduzir outra língua após o carregamento.

Execute a tarefa principal e procure:

• erro em inglês dentro de formulário em português;
• botão traduzido, mas nome acessível antigo;
• iframe cujo idioma não pode ser controlado pelo documento pai;
• mensagem de sucesso fora do locale atual;
• fallback de API na língua padrão do serviço;
• conteúdo inserido sem herdar o lang esperado.

O artigo de teste de formulários em landing pages cobre os estados de erro, rede e sucesso. Para controles, complete a revisão com o guia de nomes acessíveis de links e botões.

Check 8: escute a página

Um validador pode confirmar que pt-BR tem formato válido. Ele não prova que a página predominante está em português brasileiro nem que uma mudança foi marcada no contêiner certo.

Faça um teste curto com leitor de tela:

1. abra a página em uma sessão limpa;
2. confirme a língua ou voz escolhida;
3. leia título, navegação e primeiro parágrafo;
4. percorra uma passagem em outro idioma;
5. acione formulário ou componente dinâmico;
6. troque de locale, quando houver;
7. recarregue e repita.

Pronúncia varia entre leitores de tela, sintetizadores, vozes instaladas e sistemas. Não transforme uma diferença de voz em garantia universal. Registre ambiente, versão e resultado. O guia de teste com leitor de tela oferece um roteiro maior para a página.

Automação ajuda a manter o contrato

Checks automáticos podem detectar:

• ausência de lang em html;
• tag vazia ou inválida;
• locale da rota incompatível com o valor configurado;
• página traduzida que herdou o idioma padrão;
• mudanças de idioma sem atributo em casos conhecidos;
• underscore ou código de região usado sozinho.

Eles não determinam com segurança a língua predominante de uma página curta, decidem se uma palavra já faz parte do vocabulário do público nem avaliam a pronúncia de todas as combinações.

Uma boa regra automatizada verifica contratos conhecidos. A revisão editorial decide o restante.

Prompt copiável para o agente

Revise a declaração de idioma deste site antes da publicação.

Escopo:
- fonte e commit: [referência]
- rotas e locales: [lista]
- língua esperada por rota: [mapa]
- conteúdo multilíngue conhecido: [trechos ou componentes]

1. Localize onde o documento raiz define lang.
2. Compare cada rota com a língua predominante do conteúdo entregue.
3. Valide as tags segundo BCP 47 e use região somente quando necessária.
4. Inventarie passagens que mudam de idioma e marque apenas mudanças reais.
5. Teste troca de locale e conteúdo carregado depois da página.
6. Preserve copy, URLs, metadados, tracking e comportamento aprovado.
7. Gere a build, inspecione o HTML final e entregue evidências por rota.

Se o agente não conhece a língua do conteúdo ou encontra uma mistura sem locale aprovado, ele deve parar e pedir a decisão editorial. Não deve inferir o mercado pelo domínio.

Publique e confirme a língua da versão ativa

No Site no Ar, os arquivos dentro de public/ formam o conteúdo servido conforme a documentação de Publicação. A correção local só chega ao público depois de deploy concluir com sucesso.

Na URL publicada:

• inspecione o atributo lang do elemento html;
• confirme título, conteúdo e mensagens dinâmicas;
• teste ao menos uma passagem em outra língua;
• troque de locale e recarregue, quando aplicável;
• verifique formulário, menu e modal;
• registre a Version e o resultado do teste.

Se a build publicada não corresponde ao arquivo revisado, corrija o pacote e republique o mesmo Site. Criar outra URL esconde o erro e quebra a continuidade da validação.

Uma página não precisa marcar cada palavra estrangeira. Precisa declarar sua língua predominante, identificar mudanças que afetam a leitura e manter essa informação correta na rota que o público realmente abre.