Glossary
lang attribute
The `lang` attribute on the `<html>` element declares the language a document is written in, using a BCP 47 language tag such as `en`, `fr-CA` or `pt-BR`. Screen readers use it to choose a pronunciation, browsers use it for hyphenation and for offering translation, and search engines use it as one signal among several about who a page is for. A missing or wrong value is invisible on screen and clearly audible to anyone using speech output.
What the value looks like
A primary subtag naming the language: `en`, `fr`, `de`, `ja`.
An optional region subtag: `en-GB`, `pt-BR`, `zh-Hant-TW`. Use one only when the regional variant actually matters — `en-US` on a page that is simply in English adds nothing.
Tags are case-insensitive, though the convention is lowercase for language and uppercase for region.
The value goes on the `<html>` element and applies to the whole document unless overridden further down.
A script subtag exists for languages written in more than one script, such as `zh-Hans` and `zh-Hant`, and is worth including where the distinction is real.
Marking passages in another language
Any element can carry its own `lang`, overriding the document's for its subtree: a quotation, a book title, a term left untranslated.
WCAG success criterion 3.1.2 requires this for passages in a different language, with narrow exceptions for proper nouns and loanwords in common use.
Without it, a screen reader pronounces the passage using the document's language rules, which for a sentence in another language is usually unintelligible.
Site furniture is the common oversight: a language switcher listing language names should mark each one in its own language.
The `xml:lang` attribute exists for XML documents and is redundant in HTML served as HTML. Setting both is harmless; setting only `xml:lang` in an HTML page has no effect.
What a wrong value does
Speech output uses the declared language's pronunciation rules. A French page declared as English is read with English phonetics and is close to unusable.
Browsers offer to translate a page from the declared language, so a wrong declaration produces a nonsensical translation offer.
Hyphenation and quotation mark conventions follow the declaration, producing subtly wrong typography.
A wrong value is worse than a missing one, because a missing attribute leaves the consumer to guess and a wrong one is trusted.
The failure is entirely invisible on screen. Nothing about a page declared in the wrong language looks different to a sighted reader, which is why it survives review after review.
How to check it
`curl -s https://example.com/page | grep -o '<html[^>]*>'` shows the attribute as served.
Compare the declared value against the actual language of the text. A template that hard-codes one language across a multilingual site is the common finding.
Check that pages in other languages declare their own value rather than inheriting the default from a shared layout.
Check the language switcher and any untranslated site furniture for passages that need their own `lang`.
Frequently asked questions
- Do I need a region in the lang attribute?
- Only when the regional variant matters, such as pt-BR against pt-PT. Adding en-US to a page that is simply in English adds nothing.
- Does the lang attribute affect SEO?
- It is one signal among several about a page's language. Search engines primarily determine language from the content itself.
- What if a page mixes languages?
- Declare the main language on the html element and mark each passage in another language with its own lang attribute.
Sources
Related
VeriFixScan crawls a site and applies its checks to every page it reaches, keeping the evidence behind each finding. Scanning one website is free.
Scan a website