Match lang and xml:lang attributes
The lang and xml:lang attributes on the html element must have identical values to avoid conflicting language signals across HTML and XML parsers.
- If both `lang` and `xml:lang` are present on `<html>`, their values must be identical
- `xml:lang` is only needed for XHTML or polyglot documents (valid as both HTML and XML)
- For standard HTML5 documents, only `lang` is required — `xml:lang` is redundant
- The primary language tag must be a valid BCP 47 language code (e.g., `en`, `en-US`, `fr`, `zh-Hant`)
- Relates to WCAG 2.1 SC 3.1.1 (Language of Page)
Rule Details
When using both lang and xml:lang on the same element, they must have the exact same value. The HTML Living Standard (opens in new tab) and W3C language declaration guidance (opens in new tab) both treat mismatches as contradictory language signals to parsers and user agents.
Code Example
<!-- ✅ Correct HTML5 document: only lang needed -->
<!DOCTYPE html>
<html lang="en">
<!-- ✅ Correct polyglot/XHTML document: both present and identical -->
<html lang="fr" xml:lang="fr">
<!-- ❌ Incorrect: values differ -->
<html lang="en" xml:lang="fr">
<!-- ❌ Incorrect: dialect mismatch — en vs en-US -->
<html lang="en" xml:lang="en-US">
<!-- ❌ Incorrect: invalid language tag -->
<html lang="english">Why It Matters
- Parser Compatibility: HTML parsers use
lang; XML parsers usexml:lang. Polyglot documents must satisfy both. - Screen Readers: Conflicting attributes can cause the wrong speech synthesis language profile to be selected.
- Translation Tools: Browser auto-translate features rely on
langto detect the source language. - WCAG Compliance: SC 3.1.1 Language of Page (opens in new tab) requires the page language to be programmatically determinable, and BCP 47 (opens in new tab) defines the language tags that make that possible.
When to Use Each Attribute
| Document Type | lang | xml:lang |
|---|---|---|
Standard HTML5 (text/html) | Required | Not needed |
XHTML (application/xhtml+xml) | Recommended | Required |
| Polyglot HTML (valid as both) | Required | Required (same value) |
Best Practices
- For new HTML5 projects, use only
langon<html>and omitxml:lang. - If you add
xml:langfor compatibility reasons, always keep it in sync withlang. - Use subtags consistently — if one attribute has
en-GB, the other must also haveen-GB, not justen.
Exceptions
- Evaluate the rendered experience before treating a static-code smell as a blocker; interaction timing, browser behavior, and assistive technology output often determine severity.
- Not every secondary accessibility issue deserves equal weight; prioritize the issue that most directly blocks perception, operation, or understanding.
- Avoid adding redundant markup or ARIA solely to satisfy a rule when a simpler semantic implementation would eliminate the issue entirely.
Standards
- Align the implementation with WCAG 2.1 SC 3.1.1: Language of Page and verify the rendered experience, not only the source code.
- Align the implementation with HTML Living Standard: The lang and xml:lang attributes and verify the rendered experience, not only the source code.
- Align the implementation with W3C: Declaring language in HTML and verify the rendered experience, not only the source code.
Verification
Automated Checks
- Inspect the browser accessibility tree or accessibility pane for the relevant element, role, or accessible name.
- Run an automated accessibility checker such as axe or Lighthouse where applicable.
Manual Checks
- Test the affected UI with keyboard-only navigation and confirm the rule holds in the rendered experience.
- Re-test one representative user flow with a screen reader if this rule affects a key interaction.
Use with AI
Copy these prompts to use with your AI assistant, or install the MCP server to use directly from Claude, Cursor, or Windsurf.
Check
Verify implementation
Inspect the `<html>` element for both `lang` and `xml:lang` attributes. If both are present, verify their values are identical (including subtags — `en` vs `en-US` is a mismatch). Also verify that the value is a valid BCP 47 language tag. Flag if the values differ in any way.
Fix
Auto-fix issues
If `lang` and `xml:lang` are present but differ: update both to the same valid BCP 47 language code matching the primary language of the document content. If this is a standard HTML5 document (served as text/html), remove `xml:lang` — it is unnecessary. If this is XHTML or a polyglot document, keep both and ensure they are identical.
Explain
Learn more
WCAG 2.1 SC 3.1.1 requires that the default human language of each web page can be programmatically determined. The `lang` attribute on `<html>` serves this purpose for HTML parsers. The `xml:lang` attribute serves the same purpose for XML parsers. When a document must be valid as both HTML and XML (polyglot), both attributes must be present and identical. A mismatch means the document claims different languages depending on which parser reads it, which can cause screen readers, translation tools, and spell checkers to use wrong language rules.
Review
Code review
Review the rendered markup and interactive states that affect Match lang and xml:lang attributes. Flag exact elements, roles, labels, focus behavior, or keyboard interactions that violate the rule, and note how to verify the fix with browser accessibility tooling or assistive tech.