HTML Lang Codes
html lang codes lang codes reference documents bcp 47 on html/elements, hreflang alternate links bcp 47 language tags in html
Introduction
BCP 47 language tags in HTML (lang, hreflang, xml:lang legacy) drive screen reader pronunciation, hyphenation, font selection, and international SEO. Staff engineers implement hreflang reciprocation, regional variants (en-GB vs en-US), and lang on fragments for mixed-language quotes.
Business problem
Business pressure: Missing html lang=en causes VoiceOver wrong guess; hreflang without return links — Google ignores entire cluster; legal pages wrong locale indexed.
- SEO: hreflang errors in Search Console after CMS migration common Sev-2 for international teams.
- A11y: SR mispronounces product names in wrong language voice.
- Legal: Regulators require local language pages identifiable.
Why this feature exists
Platform motivation: BCP 47 standardizes language subtags — language-region-script-variant; html lang inherits to descendants unless overridden.
- History: lang attribute long-standing; hreflang link rel for alternates
- Alternative rejected: Geo IP only without lang markup — crawlers need explicit signals.
- Modern role: translate attribute no on brand terms within foreign paragraphs.
Browser internals
Lang processing: :lang() CSS selector; hyphenation; font matching; AT selects TTS voice; spellcheck uses lang.
- Parser: lang on html element primary; invalid subtags ignored partially — validate tags.
- DOM: lang property on elements; xml:lang only in XML serialization.
- Script impact: Intl API uses same BCP 47 tags.
Rendering workflow
Rendering: lang affects font fallback metrics slightly — CJK fonts load per lang hint in some browsers; preload locale fonts in HTML head per template.
- Critical path: Wrong font subset loading if lang wrong — FOUT CLS.
- Layout: CJK line break rules language-dependent.
- Paint: Ruby annotations lang-specific.
Feature deep dive
Reference patterns: ;
; hreflang on link rel=alternate with href absolute; x-default for fallback; lang must match visible content primary language.
- Valid tags: en, en-US, zh-Hans, pt-BR — validate with language-subtag-registry.
- hreflang: Each page lists all alternates including self; reciprocal required.
- dir: Pair rtl langs (ar, he) with dir=rtl on html.
<!DOCTYPE html><html lang="en-US"><head><link rel="alternate" hreflang="en-US" href="https://example.com/us/"><link rel="alternate" hreflang="fr-FR" href="https://example.com/fr/"><link rel="alternate" hreflang="x-default" href="https://example.com/"></head><body><p>The French motto is <q lang="fr">Liberté, égalité, fraternité</q>.</p></body></html>
Accessibility analysis
Lang a11y: Required on html; override on foreign phrases; affects braille display and pronunciation; don't set wrong lang to force voice aesthetic.
- Screen readers: lang switch mid-sentence on quoted foreign text.
- Keyboard: N/A.
- WCAG: 3.1.1 language of page; 3.1.2 language of parts.
SEO impact
hreflang SEO: Documented in Google international SEO guide; errors: missing return, wrong lang code, non-canonical href, hreflang pointing to redirect chains.
- Crawl: x-default for unmatched users; separate URLs per locale preferred over cookie lang only.
- Rich results: inLanguage in schema aligns with lang.
- Core Web Vitals: Per-locale font preload strategy.
Security considerations
Low direct risk: lang injection in CMS if reflected — minimal; hreflang open redirect if href attacker-controlled — sanitize URLs.
- XSS: Indirect via template injection in hreflang href.
- CSP: N/A.
- Phishing: Homograph URLs in hreflang cluster — process review.
Performance impact
Perf: Loading all locale font files without lang-specific subsetting wastes bandwidth — subset per template lang.
- LCP: CJK web font LCP sensitive — lang drives font choice.
- INP: N/A.
- CLS: Font swap per wrong lang metrics.
Real production example
hreflang generator: SSG builds alternate link tags from locale routing table; CI validates reciprocation graph.
Enterprise usage
Enterprise: Localization platform exports lang on html per locale template; automated hreflang audit in release pipeline.
- Design system: Document lang+dir requirements per locale component.
- CMS: Locale field drives lang attribute automatically.
- CI gates: hreflang reciprocation test fails build.
Common production failures
What breaks in prod: hreflang pointed to HTTP redirect chain — Google dropped all alternates — EU revenue wrong locale 3 weeks.
- Incident: html lang=en on 100% Japanese page — SR unusable.
- SEO regression: Missing x-default — unmatched traffic to wrong store.
- Perf regression: Loaded all locale fonts on one page lang=en only.
Architecture review questions
- Does html element have correct lang for primary content?
- Are foreign phrases wrapped with lang override?
- Is hreflang reciprocal and uses absolute URLs?
- Is x-default defined for global fallback?
- Is dir=rtl paired with Arabic/Hebrew lang?
Hands-on project
Project: Build two-locale mini site with correct lang, dir where needed, reciprocal hreflang, and foreign phrase lang override.
- Deliverable: en + one other locale pages.
- Verify: hreflang validator green; SR language switch test.
- Stretch: schema inLanguage property.
Interview questions
How do hreflang link tags work in HTML for international SEO?(Advanced)
link rel=alternate hreflang=code href=absolute URL on each locale version listing all alternates including self; must be reciprocal; use correct BCP 47 tags; x-default for fallback; href must return 200 same content language; avoid redirect chains; integrate with canonical strategy.
Follow-up: hreflang vs html lang difference?
How does lang attribute affect accessibility?(Advanced)
Sets default document language for AT pronunciation and spelling; lang on inline elements switches voice for foreign text; wrong lang worse than missing on phrases; pair with dir for RTL; WCAG 3.1.1 page and 3.1.2 parts requirements.
Follow-up: translate=no when?
What enterprise pipeline validates language tags?(Advanced)
Locale ID from CMS maps to BCP 47; CI hreflang graph reciprocation; HTML lang lint on templates; Search Console international report monitoring; ADR for x-default policy; font subset per locale in head preload.
Follow-up: zh-Hans vs zh-Hant example?
Try it yourself
Edit the HTML, CSS, or JS panels — the preview updates as you type.
Try it yourself
Summary
Lang codes reference documents BCP 47 on html/elements, hreflang alternate links for international SEO, dir pairing, and screen reader pronunciation — enterprise pipelines validate reciprocation in CI.