Runnable HTML Docs: lang Attribute

Q: What should I put in the html lang attribute?

A language code from the BCP 47 standard: en for English, es for Spanish, fr for French, ja for Japanese. Add a region only when it matters, as in en-US, en-GB or pt-BR.

Q: Should I use lang="en" or lang="en-US"?

Both are valid. en is enough for most English pages. Use en-US or en-GB when the regional variety matters, for example for spelling, dates or pronunciation of some words.

Q: How do I mark text in another language?

Add lang to the element around it: bon appétit . Screen readers switch pronunciation for that phrase, and CSS can style it with :lang(fr).

Q: What is the difference between lang and hreflang?

lang says what language an element's content is in. hreflang goes on a link and says what language the linked page is in, which is how sites point search engines to the other language versions of a page.

Set the page language

Put the lang attribute on the <html> element, with the code of the language your page is written in:

<!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>

The attribute has no visible effect on this paragraph, but it changes how the page is handled: a screen reader reads it with an English voice, the browser uses it when deciding whether to offer a translation, and a spell checker can use it to pick the English dictionary. Without it, tools have to guess, and a screen reader set to another language may read the English text with the wrong pronunciation.

Language codes

The value is a language tag from the BCP 47 standard. Most are a two letter language code, optionally followed by a region or a script:

Code	Language
`en`	English
`en-US`, `en-GB`	English as used in the United States, the United Kingdom
`es`, `es-MX`	Spanish, Spanish as used in Mexico
`pt-BR`	Portuguese as used in Brazil
`fr`, `de`, `it`	French, German, Italian
`ar`, `he`	Arabic, Hebrew (right to left, see below)
`ja`, `ko`	Japanese, Korean
`zh-Hans`, `zh-Hant`	Chinese in simplified, traditional characters

Codes are case insensitive, but the convention is lowercase language and uppercase region. Only add a region when the variety matters; en is a complete and correct value.

Things lang changes that you can see

Most effects of lang are for software, but a few show up on screen. Quotation marks from the <q> element follow the language, and so do case rules:

<!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>

Each row gets its own style of quotation marks. In the last column, the same text-transform: uppercase gives "ISTANBUL" in English and "İSTANBUL" in Turkish, because Turkish keeps the dot on a capital i. Change the Turkish row's lang to en and the dot disappears. Automatic hyphenation (hyphens: auto in CSS) also depends on lang: the browser needs to know the language to know where words may break.

Mark phrases in another language

lang works on any element, not only <html>. When a page in one language quotes a phrase in another, wrap the phrase and give it its own code. CSS can target languages with the :lang() selector:

<!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>

A screen reader switches to French pronunciation for "bon appétit" and back to English after it. :lang(fr) also matches fr-CA and any other French variant, and it matches elements that inherit the language from an ancestor, which an attribute selector like [lang="fr"] would miss.

Right to left languages: dir

Arabic, Hebrew, Persian and Urdu are written from right to left. lang names the language; the dir attribute sets the direction. A whole page in Arabic uses both on <html>:

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

For a short right to left phrase inside a left to right page, put both on the element around it:

<!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>

The blockquote lines up on the right and its green bar moves to the right as well, because border-inline-start follows the direction. Using logical properties such as margin-inline-start instead of margin-left keeps layouts correct in both directions.

lang vs hreflang

lang describes the content of an element. hreflang goes on a link and describes the page it points to. Sites with translations list every version in the <head> so search engines can send each reader to the right one:

<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/">

Each translated page still sets its own lang on <html>: lang="de" on the German one.

Common mistakes

Leaving lang out. Many templates forget it; set it next to the doctype on every page.
Copying lang="en" into translated pages. A German page marked as English is read with English pronunciation. Match the content.
Using a country code as a language. lang="jp" and lang="gr" are not Japanese and Greek; the codes are ja and el.
Using lang to set direction. lang="ar" alone does not make text run right to left. Add dir="rtl".
Writing lang="en_US". The separator is a hyphen: en-US.

Frequently Asked Questions

What does the lang attribute do in HTML?

It declares the language of the element's content. Screen readers use it to pick the right voice and pronunciation, browsers use it to offer translation, choose quotation marks and hyphenate, and some spell checkers use it to pick a dictionary.

What should I put in the html lang attribute?

A language code from the BCP 47 standard: en for English, es for Spanish, fr for French, ja for Japanese. Add a region only when it matters, as in en-US, en-GB or pt-BR.

Should I use lang="en" or lang="en-US"?

Both are valid. en is enough for most English pages. Use en-US or en-GB when the regional variety matters, for example for spelling, dates or pronunciation of some words.

Does the lang attribute affect SEO?

Google has said it detects the language from the text itself and does not rely on the lang attribute. Set it correctly anyway: other search engines, translation tools and screen readers use it. For linking translated versions of a page, use hreflang links.

How do I mark text in another language?

Add lang to the element around it: <span lang="fr">bon appétit</span>. Screen readers switch pronunciation for that phrase, and CSS can style it with :lang(fr).

What is the difference between lang and hreflang?

lang says what language an element's content is in. hreflang goes on a link and says what language the linked page is in, which is how sites point search engines to the other language versions of a page.

Related concepts