Docs executáveis de HTML: Atributo lang

Q: O que colocar no atributo lang do html?

Um código de idioma do padrão BCP 47: en para inglês, es para espanhol, fr para francês, ja para japonês. Adicione uma região só quando ela importar, como em en-US, en-GB ou pt-BR.

Q: Devo usar lang="en" ou lang="en-US"?

Os dois são válidos. en basta para a maioria das páginas em inglês. Use en-US ou en-GB quando a variante regional importa, por exemplo para ortografia, datas ou a pronúncia de algumas palavras. Para português do Brasil, pt-BR é o valor comum.

Q: Como marcar um texto em outro idioma?

Adicione lang ao elemento em volta dele: bon appétit . Os leitores de tela trocam a pronúncia nessa expressão, e o CSS pode estilizá-la com :lang(fr).

Q: Qual a diferença entre lang e hreflang?

lang diz em que idioma está o conteúdo de um elemento. hreflang vai num link e diz em que idioma está a página de destino, que é como os sites apontam aos buscadores as outras versões de idioma de uma página.

Defina o idioma da página

Coloque o atributo lang no elemento <html>, com o código do idioma em que a sua página está escrita:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>lang</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <p>Hello! This page is in English.</p>
  <p id="out" style="color: #6b7280;"></p>
  <script>
    document.getElementById('out').textContent =
      'Page language: ' + document.documentElement.lang +
      '. Your browser language: ' + navigator.language + '.';
  </script>
</body>
</html>

O atributo não tem efeito visível neste parágrafo, mas muda como a página é tratada: um leitor de tela o lê com uma voz em inglês, o navegador o usa para decidir se oferece uma tradução, e um corretor ortográfico pode usá-lo para escolher o dicionário de inglês. Sem ele, as ferramentas precisam adivinhar, e um leitor de tela configurado para outro idioma pode ler o texto em inglês com a pronúncia errada.

Códigos de idioma

O valor é uma tag de idioma do padrão BCP 47. A maioria é um código de idioma de duas letras, seguido opcionalmente por uma região ou um sistema de escrita:

Código	Idioma
`en`	Inglês
`en-US`, `en-GB`	Inglês dos Estados Unidos, do Reino Unido
`es`, `es-MX`	Espanhol, espanhol do México
`pt-BR`	Português do Brasil
`fr`, `de`, `it`	Francês, alemão, italiano
`ar`, `he`	Árabe, hebraico (da direita para a esquerda, veja abaixo)
`ja`, `ko`	Japonês, coreano
`zh-Hans`, `zh-Hant`	Chinês em caracteres simplificados, tradicionais

Os códigos não diferenciam maiúsculas de minúsculas, mas a convenção é idioma em minúsculas e região em maiúsculas. Só adicione uma região quando a variante importar; en é um valor completo e correto.

O que o lang muda e dá para ver

A maioria dos efeitos do lang é para programas, mas alguns aparecem na tela. As aspas do elemento <q> seguem o idioma, e as regras de maiúsculas também:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Visible effects</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; font-size: 18px; }
    td { padding: 4px 12px; border-bottom: 1px solid #e5e7eb; }
    .up { text-transform: uppercase; }
  </style>
</head>
<body>
  <table>
    <tr><td>English</td><td lang="en"><q>quote</q></td><td lang="en" class="up">istanbul</td></tr>
    <tr><td>French</td><td lang="fr"><q>quote</q></td><td lang="fr" class="up">istanbul</td></tr>
    <tr><td>German</td><td lang="de"><q>quote</q></td><td lang="de" class="up">istanbul</td></tr>
    <tr><td>Japanese</td><td lang="ja"><q>quote</q></td><td lang="ja" class="up">istanbul</td></tr>
    <tr><td>Turkish</td><td lang="tr"><q>quote</q></td><td lang="tr" class="up">istanbul</td></tr>
  </table>
</body>
</html>

Cada linha ganha o seu estilo de aspas. Na última coluna, o mesmo text-transform: uppercase dá "ISTANBUL" em inglês e "İSTANBUL" em turco, porque o turco mantém o ponto num i maiúsculo. Troque o lang da linha turca por en e o ponto desaparece. A hifenização automática (hyphens: auto no CSS) também depende do lang: o navegador precisa saber o idioma para saber onde as palavras podem ser quebradas.

Marque expressões em outro idioma

lang funciona em qualquer elemento, não só no <html>. Quando uma página num idioma cita uma expressão em outro, envolva a expressão e dê a ela o seu próprio código. O CSS pode mirar idiomas com o seletor :lang():

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Mixed languages</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    :lang(fr), :lang(es) { font-style: italic; color: #2563eb; }
  </style>
</head>
<body>
  <p>The chef said <span lang="fr">bon appétit</span> and left.</p>
  <p>Our team motto is <span lang="es">poco a poco</span>: little by little.</p>
</body>
</html>

Um leitor de tela passa para a pronúncia francesa em "bon appétit" e volta para o inglês depois. :lang(fr) também corresponde a fr-CA e a qualquer outra variante do francês, e corresponde a elementos que herdam o idioma de um ancestral, o que um seletor de atributo como [lang="fr"] não pegaria.

Idiomas da direita para a esquerda: dir

Árabe, hebraico, persa e urdu são escritos da direita para a esquerda. lang diz o idioma; o atributo dir define a direção. Uma página inteira em árabe usa os dois no <html>:

<html lang="ar" dir="rtl">

Para uma expressão curta da direita para a esquerda dentro de uma página da esquerda para a direita, coloque os dois no elemento em volta dela:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>dir</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    blockquote { border-inline-start: 4px solid #16a34a; margin: 12px 0; padding-inline-start: 12px; }
  </style>
</head>
<body>
  <p>The Arabic word for hello is <span lang="ar" dir="rtl">مرحبا</span>.</p>
  <blockquote lang="ar" dir="rtl">مرحبا بكم في الموقع</blockquote>
</body>
</html>

O blockquote se alinha à direita e a sua barra verde também vai para a direita, porque border-inline-start segue a direção. Usar propriedades lógicas como margin-inline-start em vez de margin-left mantém os layouts corretos nas duas direções.

lang vs hreflang

lang descreve o conteúdo de um elemento. hreflang vai num link e descreve a página para onde ele aponta. Sites com traduções listam todas as versões no <head> para que os buscadores mandem cada leitor para a versão certa:

<link rel="alternate" hreflang="en" href="https://example.com/">
<link rel="alternate" hreflang="de" href="https://example.com/de/">
<link rel="alternate" hreflang="x-default" href="https://example.com/">

Cada página traduzida continua definindo o seu próprio lang no <html>: lang="de" na versão em alemão.

Erros comuns

Deixar o lang de fora. Muitos templates esquecem; defina-o ao lado do doctype em toda página.
Copiar lang="en" para páginas traduzidas. Uma página em alemão marcada como inglês é lida com pronúncia inglesa. Faça o código corresponder ao conteúdo.
Usar um código de país como idioma. lang="jp" e lang="gr" não são japonês e grego; os códigos são ja e el.
Usar lang para definir a direção. lang="ar" sozinho não faz o texto correr da direita para a esquerda. Adicione dir="rtl".
Escrever lang="en_US". O separador é um hífen: en-US.

Perguntas frequentes

O que o atributo lang faz no HTML?

Ele declara o idioma do conteúdo do elemento. Os leitores de tela o usam para escolher a voz e a pronúncia certas, os navegadores o usam para oferecer tradução, escolher as aspas e hifenizar, e alguns corretores ortográficos o usam para escolher o dicionário.

O que colocar no atributo lang do html?

Um código de idioma do padrão BCP 47: en para inglês, es para espanhol, fr para francês, ja para japonês. Adicione uma região só quando ela importar, como em en-US, en-GB ou pt-BR.

Devo usar lang="en" ou lang="en-US"?

Os dois são válidos. en basta para a maioria das páginas em inglês. Use en-US ou en-GB quando a variante regional importa, por exemplo para ortografia, datas ou a pronúncia de algumas palavras. Para português do Brasil, pt-BR é o valor comum.

O atributo lang afeta o SEO?

O Google já disse que detecta o idioma pelo próprio texto e não depende do atributo lang. Defina-o corretamente mesmo assim: outros buscadores, ferramentas de tradução e leitores de tela o usam. Para ligar versões traduzidas de uma página, use links hreflang.

Como marcar um texto em outro idioma?

Adicione lang ao elemento em volta dele: <span lang="fr">bon appétit</span>. Os leitores de tela trocam a pronúncia nessa expressão, e o CSS pode estilizá-la com :lang(fr).

Qual a diferença entre lang e hreflang?

lang diz em que idioma está o conteúdo de um elemento. hreflang vai num link e diz em que idioma está a página de destino, que é como os sites apontam aos buscadores as outras versões de idioma de uma página.

Conceitos relacionados