In one paragraph
HTML lang attribute missing means the document does not declare a non-empty default language in the markup this check reads. Set lang on the root element to the actual primary language and mark meaningful language changes within the page. The declaration supports pronunciation and other language-sensitive processing, but behaviour depends on client capabilities. A narrow scanner pattern is not a complete language-tag validator.
Why it matters
WCAG 3.1.1 requires the default human language to be programmatically determinable. A language declaration can help speech software select suitable pronunciation when the relevant voice and settings are available. It can also affect hyphenation and other language-dependent rendering.
Do not promise that every screen reader switches perfectly or that a language tag controls every date and number format. User settings, installed voices, browser behaviour, and application localisation all matter. Language tagging describes content; it does not translate it.
BCP 47 supports more than a two-letter language plus region. Script distinctions and other valid subtags can be appropriate. A correct tag outside a simple regex should not be replaced with a less accurate one merely to satisfy a report.
How WebAuditOS evaluates this finding
The supplied custom rule reads lang on html for parsed HTML. Missing or empty values fail; a value matching its narrow shape passes; other non-empty values warn. Unparseable responses are not graded. It also covers related axe presence and validity findings in the source specification.
The documented shape expects a lowercase two- or three-letter primary code with an optional two-letter region. Valid tags such as zh-Hans, or differently cased valid forms, can warn. A regex-shaped tag does not necessarily identify the actual content language or prove registry validity. Judge those questions separately.
How to fix it
- Identify the document's real primary language, including translated routes and CMS-generated screens. Do not derive it solely from the visitor's location or a developer's operating-system setting.
- Emit the appropriate root attribute in the shared template. For Czech content, an example is:
<html lang="cs">Use a more specific valid language tag only when the distinction accurately describes the content and is useful. Do not choose a region at random.
- Mark meaningful passages in another language where required. For example:
<p lang="en">Delivery is available throughout Europe.</p>Apply the language to the actual passage. WCAG's language-of-parts requirement includes exceptions such as proper names and some technical or adopted terms; not every foreign-looking word needs a wrapper.
- Ensure localisation changes update the document declaration as well as visible text. Client-side route transitions can leave the previous language behind. Test direct navigation and in-app language switching.
- Keep language separate from directionality. A language tag does not universally replace the need for appropriate dir handling and layout design for right-to-left content.
- Validate tags using an appropriate standards-aware reference, not only this scanner's shape. Preserve valid script distinctions and document a checker limitation when its warning conflicts with a correct implementation.
- Test representative speech output and rendered typography where relevant. A missing installed voice can limit a test environment, so do not diagnose that alone as proof the tag is wrong.
- Rescan the affected pages and review their main language manually. Do not claim an html lang repair determines Google's language selection, implements hreflang, or guarantees international ranking.
What the fix can break
A wrong global value can make every translated route misleading. Set language from maintained content or route metadata and verify fallback routes and errors.
Changing lang can affect typographic behaviour such as hyphenation or font selection. Test the intended scripts and languages rather than assuming the edit is invisible.
Over-tagging every loanword can create distracting voice changes. Apply the relevant language requirements thoughtfully instead of treating the page as a sequence of guessed language codes.
Questions
Is a region mandatory?
No. A suitable primary language such as cs or en can be sufficient. Add specificity when accurate and justified.
Why does a valid script tag warn?
The documented custom matcher is narrower than BCP 47. A warning may reflect that limitation rather than invalid content.
Does lang replace hreflang?
No. Document language and search alternate-language annotations serve different purposes.
Which related checks help?
Review link names, image alternatives, and the automation limits guide.