accessibility

Atributo lang em HTML para leitores de ecrã

O MetricSpot lê o atributo `lang` no `<html>`. Sem ele, os leitores de ecrã escolhem a voz errada e a tecnologia assistiva não troca de idioma.

O que esta verificação faz

Lê o atributo lang no elemento raiz <html>. O valor tem de ser uma etiqueta de idioma BCP 47 válida (en, en-GB, es, pt-PT, etc.).

Porque é importante

Leitores de ecrã como NVDA, JAWS e VoiceOver usam este atributo para escolher o sintetizador de voz e a pronúncia corretos. Um lang em falta lê conteúdo em inglês com a voz que o utilizador tiver definida por omissão — muitas vezes espanhol ou alemão, produzindo algaraviada. A WCAG 3.1.1 torna isto um requisito de Nível A; a Lei Europeia da Acessibilidade (em vigor desde junho de 2025) trata um lang em falta como um defeito de conformidade.

Os motores de busca também se apoiam nele para deteção de idioma, em conjunto com hreflang e sinais de conteúdo.

Como corrigir

Define o atributo no elemento raiz:

<html lang="pt">

Para variantes regionais, usa um subtag BCP 47:

<html lang="pt-PT">  <!-- Português europeu -->
<html lang="pt-BR">  <!-- Português do Brasil -->
<html lang="zh-Hant"><!-- Chinês tradicional -->

Astro: define em src/layouts/BaseLayout.astro:

<html lang={Astro.currentLocale ?? "pt"}>

Next.js (App Router): em app/layout.tsx:

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html lang="pt"><body>{children}</body></html>;
}

WordPress: vive em header.php:

<html <?php language_attributes(); ?>>

language_attributes() já emite lang="pt-PT" com base em Definições → Geral → Idioma do site. Não escrevas o valor à força por cima.

Páginas multilingues: adiciona lang ao elemento envolvente quando o conteúdo muda a meio da página:

<p>Os franceses chamam-lhe <span lang="fr">la mode</span>.</p>

É isto que faz com que <span lang="fr"> seja lido com voz francesa em vez de massacrar o sotaque.

Se também serves vários idiomas, emparelha isto com tags hreflang para que o Google envie o utilizador certo para o idioma certo.

Perguntas frequentes

Qual é a diferença entre lang e xml:lang?

lang é o atributo HTML; xml:lang é o equivalente em XHTML/XML. Para documentos HTML5, usa apenas lang. Para documentos poliglotas (raros hoje), define ambos com o mesmo valor.

Posso deixar lang de fora se detetar o idioma com JavaScript?

Não. Os leitores de ecrã analisam o HTML antes do JS correr, e muitos utilizadores de tecnologia assistiva desativam JS por completo. O atributo tem de estar no HTML estático.

Porque é que o Lighthouse marca lang="" como inválido?

Uma string vazia não é uma etiqueta BCP 47 válida. Define um código de idioma real ou remove o atributo (pior — a verificação continua a falhar). O mesmo se aplica a lang="default" ou outros valores marcadores que alguns temas de CMS trazem por omissão.

Fontes

Última atualização 2026-05-11