Skip to content

thedaviddias/Front-End-Checklist / skills/html-xml-lang-mismatch

html-xml-lang-mismatch

Verified

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.

FileKindSize
SKILL.mdskill md3.1 KB
references/rule.mdmarkdown3.6 KB

references/rule.md

View on GitHub
# 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.

**Priority:** medium · **Difficulty:** beginner · **Time:** 5 min

---
When using both `lang` and `xml:lang` on the same element, they must have the exact same value. The [HTML Living Standard](https://html.spec.whatwg.org/multipage/dom.html#attr-lang) and [W3C language declaration guidance](https://www.w3.org/International/questions/qa-html-language-declarations) both treat mismatches as contradictory language signals to parsers and user agents.
## Code Example

```html
<!-- ✅ 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 use `xml: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 `lang` to detect the source language.
- **WCAG Compliance**: [SC 3.1.1 Language of Page](https://www.w3.org/TR/WCAG21/#language-of-page) requires the page language to be programmatically determinable, and [BCP 47](https://www.rfc-editor.org/info/rfc5646/) 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 `lang` on `<html>` and omit `xml:lang`.
- If you add `xml:lang` for compatibility reasons, always keep it in sync with `lang`.
- Use subtags consistently — if one attribute has `en-GB`, the other must also have `en-GB`, not just `en`.

## 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.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall