Content Language Declared
Every shipped HTML document must declare the primary content language via `<html lang='...'>`. Content blocks in a different language must be marked with `lang='...'` on the containing element.
$ aoe install @community/constraint-content-language-declaredProjection
Always in _index.xml · the agent never has to ask for this.
ContentLanguageDeclared [constraint] v1.0.0
Every shipped HTML document must declare the primary content language via <html lang='...'>. Content blocks in a different language must be marked with lang='...' on the containing element.
Loaded when retrieval picks the atom as adjacent / supporting.
ContentLanguageDeclared [constraint] v1.0.0
Every shipped HTML document must declare the primary content language via <html lang='...'>. Content blocks in a different language must be marked with lang='...' on the containing element.
Target
- root element of every shipped HTML document
- language switches inside long-form content
Severity
high
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Values
- Required: (or appropriate BCP-47 tag) at the document root
- Required:
/ for inline language switches
- Required:
- Forbidden: with no lang attribute
- Forbidden: lang='' empty value
- Forbidden: non-BCP-47 codes (e.g., lang='english', lang='zhcn')
Exceptions
- Email templates rendered into a known-locale client (lang inherits from envelope).
- Code-only fragments (e.g., a JSON viewer) where prose language is irrelevant — still set lang on the wrapper for consistency.
Approved Alternatives
- Set lang at the framework root: Next.js
<Html lang='en'>, Nuxtapp.head.htmlAttrs.lang, SvelteKit<html lang='%lang%'>. - Detect locale at the edge (Cloudflare Workers / Next middleware) and inject lang server-side.
- Use BCP-47 tags: en, en-US, zh-Hans, ja, fr-CA.
Enforcement
axe-core rule html-has-lang + html-lang-valid + valid-lang. Lighthouse a11y category. Build-time check in SSR templates.
Loaded when retrieval picks the atom as a focal / direct hit.
ContentLanguageDeclared [constraint] v1.0.0
Every shipped HTML document must declare the primary content language via <html lang='...'>. Content blocks in a different language must be marked with lang='...' on the containing element.
Target
- root element of every shipped HTML document
- language switches inside long-form content
Severity
high
Meta
- License: Apache-2.0
- License Provenance: package-authorship-claim
Values
- Required: (or appropriate BCP-47 tag) at the document root
- Required:
/ for inline language switches
- Required:
- Forbidden: with no lang attribute
- Forbidden: lang='' empty value
- Forbidden: non-BCP-47 codes (e.g., lang='english', lang='zhcn')
Exceptions
- Email templates rendered into a known-locale client (lang inherits from envelope).
- Code-only fragments (e.g., a JSON viewer) where prose language is irrelevant — still set lang on the wrapper for consistency.
Approved Alternatives
- Set lang at the framework root: Next.js
<Html lang='en'>, Nuxtapp.head.htmlAttrs.lang, SvelteKit<html lang='%lang%'>. - Detect locale at the edge (Cloudflare Workers / Next middleware) and inject lang server-side.
- Use BCP-47 tags: en, en-US, zh-Hans, ja, fr-CA.
Enforcement
axe-core rule html-has-lang + html-lang-valid + valid-lang. Lighthouse a11y category. Build-time check in SSR templates.
Relations
related: [@community/constraint-accessibility-aa-minimum, @w3c/source-wcag-22, @community/tool-axe-core]
Rationale
Screen readers select the correct pronunciation engine based on lang. Without it, English content is read in the user's default voice (e.g., a French screen-reader pronouncing English content as if it were French — incomprehensible). Search engines, translation tools, browser spellcheck, and hyphenation also rely on lang. WCAG 2.2 SC 3.1.1 (Language of Page) is Level A — non-negotiable.
Source
aoe-engine/examples/frontend-design/primes/compiled/@community/constraint-content-language-declared/atom.yaml