# HTML XML Lang Mismatch > Use when applies to XHTML documents and polyglot HTML 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. Check when auditing documents served as application/xhtml+xml or documents that include both attributes. - Skill: `thedaviddias/html-xml-lang-mismatch` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add thedaviddias/html-xml-lang-mismatch` - Raw SKILL.md: https://api.skillmd.com/api/skills/thedaviddias/html-xml-lang-mismatch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: thedaviddias (https://skillmd.com/u/thedaviddias) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/thedaviddias/html-xml-lang-mismatch --- # Match lang and xml:lang attributes 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 `lang` and `xml:lang` are present on ``, 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) ## Check Inspect the `` 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 `` 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