HTML lang attribute accessibility: declaring the language of the page and of its parts (WCAG 3.1.1 and 3.1.2)

Why the HTML lang attribute matters for accessibility

The W3C explains that assistive technologies and conventional browsers render text more accurately when the language of the page is identified. In practice, three things depend on it: screen readers load the pronunciation rules of the declared language, visual browsers display characters and scripts correctly, and media players show captions correctly.

The aim of 3.1.1 is therefore that authors provide, in the page itself, the information user agents need to present text and linguistic content correctly. Criterion 3.1.2 extends the same logic inside the page: each passage in another language can be presented with its own presentation and pronunciation rules, whether the user relies on a graphical browser, a screen reader, a braille display or a voice browser.

The W3C gives a telling example: without language markup, a speech synthesizer may read the French word "voiture" as "voyture".

The W3C lists these beneficiaries of the two criteria:

• People who use a screen reader or other text-to-speech technology.
• People who find it hard to read written material fluently and accurately, for example recognizing characters or decoding words.
• People with certain cognitive, language and learning disabilities who use text-to-speech software.
• People who rely on captions for synchronized media.

Success Criterion 3.1.1: declare the default language of the page

According to the W3C, the default human language of a web page is its default text-processing language. When a page contains several languages, the default language is the one used most. If several languages are used equally, the first one used is the default.

The W3C example is an HTML page produced in Germany, mostly in German with some English: the default language is German (de), set by the lang attribute on the html element. The matching sufficient technique is H57, "Using the language attribute on the HTML element". For PDF documents, technique PDF16 (the /Lang entry in the document catalog) sets the default language; PDF19, which specifies the language of a passage or phrase through the Lang entry, is also listed among the sufficient techniques. Declaring the default language in the HTTP header (SVR5) is only an advisory technique, not a sufficient one.

<!DOCTYPE html>
<html lang="de">
  <head>
    <meta charset="utf-8">
    <title>Startseite</title>
  </head>
  <body>
    <!-- content mostly in German -->
  </body>
</html>

A valid language code in the lang attribute

Adding the attribute is not enough: its value has to be usable. The test rules attached to 3.1.1 check that the HTML page has a lang attribute, that this attribute holds a valid language tag, that the lang and xml:lang attributes have matching values, and that the language subtag matches the default language. The last two rules still have "proposed" status.

Criterion 3.1.2 has test rules too: an element with a lang attribute must have a valid language tag, and (proposed rule) the language subtag of an HTML element carrying lang must match the language of its content. The language code of a passage must therefore be a valid language tag too, just like the one on the html element.

The W3C examples use simple codes such as de, fr or es, but also more precise tags: transliterated Chinese in pinyin can be marked zh-Latn-pinyin.

• The page has a lang attribute on the html element.
• The value is a valid language tag, with no typo.
• The lang and xml:lang values match (proposed test rule).
• The language subtag matches the default language (proposed test rule).

Success Criterion 3.1.2: mark changes of language in the page

Criterion 3.1.2 requires that the human language of each passage or phrase can be programmatically determined. A phrase can be a single word, so an isolated word is covered unless it falls under an exception. Text with no other language specified inherits the default language of the page, which means a page written entirely in one language meets this criterion automatically.

The sufficient technique is H58, "Using language attributes to identify changes in the human language". The W3C example: in an English sentence about the DDR, the German phrase "Treppenwitz der Weltgeschichte" is marked as German so that screen readers switch pronunciation rules.

Markup also helps visual browsers display scripts correctly, especially when switching between left-to-right and right-to-left languages or between alphabets. It lets braille software follow language changes and apply the right codes, and it supports dictionary lookups and future machine translation tools.

Here is illustrative markup inspired by this W3C example (the English sentence is abbreviated):

<p lang="en">…
  <span lang="de">Treppenwitz der Weltgeschichte</span>
…</p>

The exceptions: proper names, technical terms, everyday vocabulary

Criterion 3.1.2 explicitly excludes proper names, technical terms, words of indeterminate language, and words or phrases that have become part of the vernacular of the immediately surrounding text.

For proper names, the W3C uses "Albert Camus" in an English philosophy document: no language change is needed. Technical terms, often left untranslated across languages, are illustrated by Homo sapiens, Alpha Centauri, hertz and habeas corpus. For vernacular words, "rendezvous" has been adopted into English, and "podcast" in a French sentence needs no markup.

When in doubt, the W3C suggests a simple question: would the word be pronounced the same way in the surrounding language? Marking the original language of a foreign word anyway remains a good practice, not a requirement, that improves pronunciation.

Multilingual sites: language switcher and links

Even when targeting Level A, the W3C Working Group strongly encourages developers of multilingual sites to follow Success Criterion 3.1.2. The typical case is the language switcher: in the W3C example, each link to another version uses the language's own name ("Deutsch", "Italiano", "Français", "繁體中文"), each with its own lang attribute.

Another W3C example: a link whose title is in English, while the nested span containing "Español" has lang="es".

Be careful when testing: screen readers announce "flat" accessible names, for instance in a list of links, which drop language changes. Moving the lang attribute onto the element itself may help in some cases. Because this is a user agent limitation, it is not a failure of the criterion, but auditors must check the markup, not just the spoken output. The W3C also notes that pronunciation quality varies across screen readers and speech synthesizers.

To spot a missing or invalid lang attribute quickly, you can run a free test with Conformly, then turn on continuous monitoring to be alerted if a new template brings the error back.

<nav aria-label="Languages">
  <ul>
    <li><a href="/de/" lang="de">Deutsch</a></li>
    <li><a href="/it/" lang="it">Italiano</a></li>
    <li><a href="/fr/" lang="fr">Français</a></li>
  </ul>
</nav>

Frequently asked questions

Further reading on Conformly

• Fix an undeclared page language
• Fix an invalid language code
• RGAA criterion 8.3 on default language

Sources

This article relies on the official sources listed at the end of the page.

• W3C — Comprendre 3.1.1
• W3C — Comprendre 3.1.2