lang="pt-BR" no html: por que o leitor de tela lê seu site com sotaque inglês

Uma cliente cega abriu o blog da clínica com o NVDA e ouviu "a-gen-dei-ment ón-line" no lugar de "agendamento on-line". O texto estava em português perfeito. O problema estava numa linha que ninguém lê: <html lang="en">, herdada do template do framework. O leitor de tela acreditou na etiqueta e escolheu a voz inglesa para o site inteiro.

A resposta curta: declare <html lang="pt-BR"> em toda página escrita em português do Brasil e marque com lang próprio cada trecho em outra língua, como uma citação em inglês. Se o site tem versões traduzidas, cada URL declara o idioma do seu próprio conteúdo. É uma linha de código que muda como a página é falada, traduzida, hifenizada e corrigida.

Quem lê o atributo lang e o que faz com ele

O atributo lang diz em qual língua está o conteúdo daquele elemento e de tudo que está dentro dele. Ele é herdado: se o html diz pt-BR, cada parágrafo é português até que algum elemento diga outra coisa.

Vários programas confiam nessa informação. Leitores de tela como NVDA, JAWS e VoiceOver usam o lang para escolher a voz e as regras de pronúncia, desde que a voz daquela língua esteja instalada. Navegadores usam para decidir se oferecem tradução: página em português marcada como inglês pode receber oferta de "traduzir do inglês", ou não receber oferta nenhuma para quem precisaria. A propriedade CSS hyphens: auto só hifeniza corretamente se souber a língua. Corretores ortográficos de campos de texto também podem usar o idioma declarado.

Nas diretrizes WCAG, declarar o idioma da página é critério de nível A, o mais básico, e marcar trechos em outra língua é nível AA. Não é refinamento, é piso.

Como o idioma errado entra no projeto

Quase nunca é decisão. É herança. Os geradores de projeto de quase todo framework criam o template com lang="en", e ninguém volta lá. Em projetos com várias camadas de layout, às vezes o idioma está certo no layout principal e errado num layout secundário usado só pelas páginas de campanha. Em sites com tradução, o valor fica fixo no template em vez de vir da língua da página que está sendo servida.

No caso da clínica, o blog era um Next.js. O lang fica no arquivo de layout raiz, e o gerador tinha deixado en.

Como corrigir, passo a passo

1. Descubra o que está no ar. Abra o código-fonte da página publicada (não o do repositório) e procure a tag <html. No console do navegador, document.documentElement.lang mostra o valor efetivo.
2. Escolha o código certo. Para português do Brasil, pt-BR. Para Portugal, pt-PT. Só pt também é válido, mas perde a variante. Os códigos seguem o padrão BCP 47 e não diferenciam maiúsculas, então pt-br funciona; pt-BR é a forma convencional.
3. Corrija no template raiz. Um lugar só, que todas as páginas herdam. Depois procure outros layouts que também abram <html.
4. Marque os trechos em outra língua. Citações, títulos de obras estrangeiras, frases inteiras em inglês ou espanhol recebem lang no elemento que as envolve.
5. Não marque o que já virou português. Palavras como "software", "login" e "e-mail" fazem parte do vocabulário comum, e nomes próprios não precisam de marcação. As próprias diretrizes abrem essa exceção. Marcar cada palavra estrangeira deixa a leitura picotada, com troca de voz a cada linha.
6. Em site multilíngue, derive o valor da rota. A página em /en/ declara en, a em /pt/ declara pt-BR, e as duas se apontam com hreflang.

O HTML da clínica, corrigido

<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8">
  <title>Agendamento on-line: como marcar sua consulta</title>
  <link rel="alternate" hreflang="pt-BR" href="https://clinica.exemplo.com.br/agendamento">
  <link rel="alternate" hreflang="en" href="https://clinica.exemplo.com.br/en/booking">
</head>
<body>
  <h1>Agendamento on-line</h1>
  <p>O lema do nosso fundador era simples:</p>
  <blockquote lang="en">
    <p>First, do no harm.</p>
  </blockquote>
  <p>O livro <cite lang="es">El amor en los tiempos del cólera</cite> está na sala de espera.</p>
  <p>Faça login com seu e-mail.</p>
</body>
</html>

Repare que "login" e "e-mail" ficaram sem marcação, e o seletor de idioma, se existir, deve ter cada opção marcada com a própria língua: o link "English" com lang="en", para que o leitor de tela pronuncie o nome da língua corretamente.

No framework

No Next.js com App Router, o idioma fica no layout raiz:

// app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="pt-BR">
      <body>{children}</body>
    </html>
  );
}

Em outros frameworks o princípio é o mesmo: ache o arquivo que gera o <html> e corrija ali. Em ASP.NET, é o _Layout.cshtml; em PHP com template próprio, o cabeçalho incluído em todas as páginas; em gerador estático, o layout base. Se o site muda de idioma por rota, o valor vem de uma variável, nunca de texto fixo.

O que o lang não faz

O cabeçalho HTTP Content-Language não substitui o atributo; tecnologias assistivas olham o documento. A meta tag og:locale do Open Graph (que usa sublinhado, como pt_BR) serve para redes sociais e também não substitui. E o lang não traduz nada: ele só descreve. Se a página diz pt-BR e metade do texto é inglês sem marcação, você só trocou de problema.

Para títulos e descrições que o Google mostra, o assunto é outro, tratado em meta tags que o Google lê. Para acentos que viram símbolos estranhos, o culpado é a codificação, não o idioma, como explica acentos que quebram no banco.

Como testar de verdade

No Windows, o NVDA é gratuito: abra a página, pressione a tecla de leitura contínua e ouça os primeiros parágrafos. Se a voz soar inglesa em texto português, o lang está errado ou a voz portuguesa não está instalada. No macOS, o VoiceOver vem no sistema. Ouça também a citação em inglês: a voz deve mudar ali e voltar depois.

Um teste rápido sem leitor: abra a página no Chrome com o navegador configurado em português e veja se ele oferece tradução. Se oferecer "traduzir do inglês" numa página em português, a etiqueta está mentindo.

Erros comuns

• Deixar o lang="en" do gerador. O site inteiro passa a ser lido com pronúncia inglesa, e o navegador oferece tradução errada.
• Remover o atributo para "não errar". Sem lang, cada leitor de tela usa o idioma padrão do usuário, o que funciona para uns e quebra para outros; a página falha o critério básico de acessibilidade.
• Valor fixo em site traduzido. A versão em inglês declara pt-BR, e o leitor fala inglês com regras de português.
• Marcar cada palavra estrangeira. A voz troca a cada "deploy" e "feedback", e a leitura fica mais difícil do que sem marcação.
• Usar código inventado. Valores como br (que é o código do bretão) ou portuguese não significam o que você imagina.

Checklist

• document.documentElement.lang na página publicada retorna pt-BR.
• Todos os layouts que geram <html> foram conferidos, não só o principal.
• Citações e frases inteiras em outra língua têm lang próprio.
• Palavras já incorporadas ao português e nomes próprios ficaram sem marcação.
• Em site multilíngue, o lang vem da rota e as versões se ligam por hreflang.
• Os nomes das línguas no seletor de idioma têm o lang da própria língua.
• A página foi ouvida num leitor de tela pelo menos uma vez.

Abra o console na página principal do seu site, digite document.documentElement.lang e compare com o texto na tela: os dois falam a mesma língua?