a11y/lang-valid

Why

Screen readers pick the voice and pronunciation rules from lang. An invalid value is ignored, so Polish text may be read with English rules and become unintelligible. Locale codes from other systems (en_US with an underscore) are the usual cause.

Fix

Use a BCP 47 tag: language, then optional script and region, joined by hyphens (en, en-GB, pt-BR, zh-Hant). When the value comes from the app's locale, convert underscores to hyphens once (locale.replace('_', '-')) or use new Intl.Locale(locale).toString().

Examples

<!-- bad -->
<html lang="en_US"> … <p lang="polish">Dzień dobry</p>
<!-- good -->
<html lang="en-US"> … <p lang="pl">Dzień dobry</p>

Sources

• WCAG 2.2, Understanding SC 3.1.1 Language of Page
• WCAG 2.2, Understanding SC 3.1.2 Language of Parts
• W3C Internationalization, Language tags in HTML and XML

Read it in the terminal

npx github:dawidolko/frontend-skills explain a11y/lang-valid