Match lang and xml:lang attributes
SkillDocs & knowledgehtml-xml-lang-mismatch is a skill for AI agents that checks whether a page's lang and xml:lang attributes match. It applies to XHTML and polyglot documents that must parse as both HTML5 and XML, guiding the agent to verify identical, valid BCP 47 values and fix mismatches. This matters because screen readers and EPUB readers may otherwise pick the wrong language.
Available today. Use it from your connected AI after setup.
No other account needed.
1. Have an AI agent that can load skills.
Then ask your AI: use the Match lang and xml:lang attributes skill
What your AI can do with it
- Inspect the <html> element for lang and xml:lang attributes
- Verify lang and xml:lang values are identical and valid BCP 47 codes
- Fix mismatches by aligning both attribute values
- Remove xml:lang from plain HTML5-only documents
- Audit documents served as application/xhtml+xml
Getting started
- 1. Have an AI agent that can load skills.
- 2. Add the html-xml-lang-mismatch skill to the agent's available skills.
- 3. Give the agent an HTML or XHTML document to audit.
- 4. Ask it to check the lang and xml:lang attributes and fix any mismatches.
What this skill tells your AI
The instructions your AI receives, as published by thedaviddias/front-end-checklist in skills/html-xml-lang-mismatch/SKILL.md and read by ahel’s review.
Screen readers use the lang attribute to select the correct voice profile and pronunciation engine. If lang and xml:lang disagree, XML-based processors (including some EPUB readers and older assistive technologies) may use xml:lang and get a different language than intended — causing text to be read aloud in the wrong language. For example, French text read with an English voice profile produces unintelligible output for French-speaking blind users.
Quick Reference
- If both
langandxml:langare present on<html>, their values must be identical xml:langis only needed for XHTML or polyglot documents (valid as both HTML and XML)- For standard HTML5 documents, only
langis required —xml:langis 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)
Check
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
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
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.
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.
For full implementation details, code examples, and framework-specific guidance,
see references/rule.md.
Rule page: https://frontendchecklist.io/en/rules/accessibility/html-xml-lang-mismatch
Signals
- GitHub stars
- 74k
- Forks
- 7k
- Last commit
- Aug 2026
Questions
- When is xml:lang needed?
- For XHTML documents and polyglot documents that must parse correctly as both HTML5 and XML. For modern HTML5-only documents, only lang is needed and xml:lang is not required.
- Why do mismatches matter?
- Screen readers and other XML-based processors like EPUB readers may pick the wrong language and read text aloud incorrectly.
- How does the agent fix a mismatch?
- By aligning both attribute values to the same valid BCP 47 code, or by removing xml:lang from plain HTML5 documents.
Advanced
- Item type
- skill
- Key
html-xml-lang-mismatch- Source
- github.com/thedaviddias/front-end-checklist