{
"slug": "html_lang_attribute",
"term": "HTML lang Attribute",
"category": "accessibility",
"difficulty": "beginner",
"short": "The lang attribute on declares the page's primary language — required for screen readers to select the correct voice profile and pronunciation rules, and for WCAG 2.1 compliance.",
"long": "The lang attribute on the element is one of the highest-impact, lowest-effort accessibility improvements. Screen readers (JAWS, NVDA, VoiceOver, TalkBack) use it to select the appropriate voice engine — without it, the reader uses its default language, producing incomprehensible pronunciation for content in another language. The value must be a valid BCP 47 language tag: 'en' for English, 'en-GB' for British English, 'fr' for French, 'de' for German, 'pl' for Polish. For multilingual pages, individual sections can override with lang on a specific element () — this allows the screen reader to switch voice mid-page. WCAG 2.1 Success Criterion 3.1.1 (Language of Page) is Level A — the minimum accessibility conformance level. Missing lang is both a WCAG A failure and a Lighthouse accessibility score deduction.",
"aliases": [
"lang attribute",
"html language",
"page language",
"language declaration",
"bcp47",
"xml:lang"
],
"tags": [
"accessibility",
"html",
"wcag",
"frontend"
],
"misconception": "The lang attribute only matters for non-English sites — English-language screen reader users are also affected when visiting pages without lang because the reader must guess the language; additionally, browser translation features and spell checkers rely on lang.",
"why_it_matters": "A Polish user visiting a Polish-language site without lang='pl' will hear their screen reader attempt to pronounce Polish words using English phonology rules — the result is completely unintelligible and the page is effectively inaccessible.",
"common_mistakes": [
"Omitting lang entirely — the most common mistake, fails WCAG 3.1.1 Level A.",
"lang='en' on a non-English page — setting the wrong language is worse than omitting it; the screen reader pronounces every word with the wrong phonology.",
"Using an invalid language tag (lang='english', lang='EN-us') — BCP 47 subtags are case-sensitive; the primary tag is lowercase, the region tag is uppercase (lang='en-GB', lang='zh-Hant').",
"Setting lang on instead of — must be on the root element per WCAG specification."
],
"when_to_use": [
"Always — every HTML page must have lang on the element.",
"Add lang on specific elements when a section of the page is in a different language from the page default."
],
"avoid_when": [
"Do not set lang to a language that doesn't match the page content — wrong lang is worse than missing lang for screen reader users."
],
"related": [
"accessibility_aria",
"html_semantic",
"skip_links",
"meta_tags"
],
"prerequisites": [],
"refs": [
"https://www.w3.org/TR/WCAG21/#language-of-page",
"https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang",
"https://www.iana.org/assignments/language-subtag-registry"
],
"bad_code": "\n\n Strona główna\n Witaj na naszej stronie...\n",
"good_code": "\n\n Strona główna\n \n Witaj na naszej stronie...\n \n \"To be or not to be\"
\n \n",
"quick_fix": "Add lang='en' (or appropriate BCP 47 code) to the opening tag",
"severity": "high",
"effort": "low",
"created": "2026-04-06",
"updated": "2026-04-06",
"citation": {
"canonical_url": "https://codeclaritylab.com/glossary/html_lang_attribute",
"html_url": "https://codeclaritylab.com/glossary/html_lang_attribute",
"json_url": "https://codeclaritylab.com/glossary/html_lang_attribute.json",
"source": "CodeClarityLab Glossary",
"author": "P.F.",
"author_url": "https://pfmedia.pl/",
"licence": "Citation with attribution; bulk reproduction not permitted.",
"usage": {
"verbatim_allowed": [
"short",
"common_mistakes",
"avoid_when",
"when_to_use"
],
"paraphrase_required": [
"long",
"code_examples"
],
"multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
"when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
"attribution_examples": {
"inline_mention": "According to CodeClarityLab: ",
"markdown_link": "[HTML lang Attribute](https://codeclaritylab.com/glossary/html_lang_attribute) (CodeClarityLab)",
"footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/html_lang_attribute"
}
}
}
}