Skip to content

Update rules mapping for SC 3.1.1 Language of Page to address empty content [bf051a, ucwvc8, b5c3f8] #2407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
giacomo-petri wants to merge 8 commits into
base: develop
Choose a base branch
from
Open

Update rules mapping for SC 3.1.1 Language of Page to address empty content [bf051a, ucwvc8, b5c3f8] #2407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
499b506
Update html-page-lang-valid-bf051a.md
giacomo-petri Apr 16, 2026
90831d1
Update html-page-lang-matches-default-ucwvc8.md
giacomo-petri Apr 16, 2026
aa2a706
Update html-page-lang-b5c3f8.md
giacomo-petri Apr 16, 2026
3fc5a94
Update html-page-lang-b5c3f8.md
giacomo-petri Apr 16, 2026
7fa6b33
Update html-page-lang-matches-default-ucwvc8.md
giacomo-petri Apr 16, 2026
0120002
Update html-page-lang-b5c3f8.md
giacomo-petri Apr 16, 2026
259a39d
Update html-page-lang-matches-default-ucwvc8.md
giacomo-petri Apr 16, 2026
22859b0
Update html-page-lang-valid-bf051a.md
giacomo-petri Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion _rules/html-page-lang-b5c3f8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ input_aspects:
- DOM Tree
acknowledgments:
authors:
- Giacomo Petri
- Jey Nandakumar
previous_authors:
- Annika Nietzio
Expand All @@ -32,7 +33,8 @@ acknowledgments:
This rule applies to any [document element](https://dom.spec.whatwg.org/#document-element) if it is an `html` element for which all the following are true:

- is in a [top-level browsing context](https://html.spec.whatwg.org/#top-level-browsing-context); and
- has a [node document](https://dom.spec.whatwg.org/#concept-node-document) with a [content type](https://dom.spec.whatwg.org/#concept-document-content-type) of `text/html`.
- has a [node document](https://dom.spec.whatwg.org/#concept-node-document) with a [content type](https://dom.spec.whatwg.org/#concept-document-content-type) of `text/html`; and
- has at least one [descendant](https://dom.spec.whatwg.org/#concept-tree-descendant) [text node][] which is neither empty nor only [whitespace][]..
Copy link
Copy Markdown
Collaborator

@Jym77 Jym77 Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: Shouldn't the rule also apply if there is only replaced content that needs language (alt text of images, …)?
Maybe use "there is some text inheriting its programmatic language from the document element, which is neither empty nor only whitespace." like in the "element's lang" rule.

Copy link
Copy Markdown
Collaborator Author

@giacomo-petri giacomo-petri Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I had considered that but then forgot about it. And the reason why is that for 3.1.2 rules, the assumption is that the HTML has a lang defined. If no language is set, it becomes tricky. I'll think about how to handle that and how to address the problem of "equivalent" text.


**Note:** `html` elements within `iframe` and `object` elements are not applicable as `iframe` and `object` elements create [nested browsing contexts](https://html.spec.whatwg.org/#nested-browsing-context). However, as these elements are meant to provide a layer of isolation, the declared language of their [parent browsing context](https://html.spec.whatwg.org/#parent-browsing-context) will likely not be inherited, making it possible for empty `lang` attributes in [nested browsing contexts](https://html.spec.whatwg.org/#nested-browsing-context) to also cause accessibility issues.

Expand Down Expand Up @@ -152,4 +154,14 @@ This rule does not apply to a `math` element.
</math>
```

#### Inapplicable Example 3

This rule does not apply to content that is empty or contains only [whitespace][].

```html
<html>
<body></body>
</html>
```

[attribute value]: #attribute-value
14 changes: 13 additions & 1 deletion _rules/html-page-lang-matches-default-ucwvc8.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ input_aspects:
- Language
acknowledgments:
authors:
- Giacomo Petri
- Wilco Fiers
funding:
- WAI-Tools
Expand All @@ -39,7 +40,8 @@ This rule applies to any [document element][] if it is an `html` element for whi
- The [document element][] has a `lang` attribute with a value that has a [known primary language tag][]; and
- The [document element][] is in a [top-level browsing context][]; and
- The [document element][] has a [content type][] of `text/html`; and
- The [document element][] has a defined [default page language][].
- The [document element][] has a defined [default page language][]; and
- The [document element][] has at least one [descendant](https://dom.spec.whatwg.org/#concept-tree-descendant) [text node][] which is neither empty nor only [whitespace][].
Copy link
Copy Markdown
Collaborator

@Jym77 Jym77 Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same remark about having "text inheriting the language".


## Expectation

Expand Down Expand Up @@ -322,6 +324,16 @@ The `lang` [attribute value][] of this page is a [grandfathered tag][grandfather
</html>
```

#### Inapplicable Example 7

This rule does not apply to content that is empty or contains only [whitespace][].

```html
<html lang="em-US">
<body></body>
</html>
```

[attribute value]: #attribute-value
[content type]: https://dom.spec.whatwg.org/#concept-document-content-type 'DOM content type, as of 2020/06/05'
[default page language]: #default-page-language
Expand Down
53 changes: 47 additions & 6 deletions _rules/html-page-lang-valid-bf051a.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ input_aspects:
- DOM Tree
acknowledgments:
authors:
- Giacomo Petri
- Jey Nandakumar
previous_authors:
- Annika Nietzio
Expand All @@ -33,7 +34,8 @@ This rule applies to any [document element](https://dom.spec.whatwg.org/#documen

- has a `lang` attribute that is neither empty ("") nor only [ASCII whitespace](https://infra.spec.whatwg.org/#ascii-whitespace); and
- is in a [top-level browsing context](https://html.spec.whatwg.org/#top-level-browsing-context); and
- has a [node document](https://dom.spec.whatwg.org/#concept-node-document) with a [content type](https://dom.spec.whatwg.org/#concept-document-content-type) of `text/html`.
- has a [node document](https://dom.spec.whatwg.org/#concept-node-document) with a [content type](https://dom.spec.whatwg.org/#concept-document-content-type) of `text/html`; and
- has at least one [descendant](https://dom.spec.whatwg.org/#concept-tree-descendant) [text node][] which is neither empty nor only [whitespace][].
Copy link
Copy Markdown
Collaborator

@Jym77 Jym77 Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same remark about "text inheriting the language".


## Expectation

Expand Down Expand Up @@ -73,18 +75,39 @@ This rule is only applicable to non-embedded HTML pages. HTML pages embedded int

#### Passed Example 1

This `html` element has a `lang` attribute with a [known primary language tag][].
This `html` element has a `lang` attribute with a [known primary language tag][] and non-empty `body` content.

```html
<html lang="FR"></html>
<html lang="it">
<body>
<p>Amo le regole ACT!</p>
</body>
</html>
```

#### Passed Example 2

This `html` element has a `lang` attribute with a [known primary language tag][] and non-empty `title`.

```html
<html lang="it">
<head>
<title>Amo le regole ACT!</title>
</head>
<body></body>
</html>
```

#### Passed Example 3

This `html` element has a `lang` attribute with a [known primary language tag][] even though the [region subtag][] is not.

```html
<html lang="en-US-GB"></html>
<html lang="en-US-GB">
<body>
<p lang="en">I love ACT rules!</p>
</body>
</html>
```

### Failed
Expand All @@ -94,15 +117,23 @@ This `html` element has a `lang` attribute with a [known primary language tag][]
This `html` element has a `lang` attribute, with no [known primary language tag][].

```html
<html lang="em-US"></html>
<html lang="em-US">
<body>
<p lang="en">I love ACT rules!</p>
</body>
</html>
```

#### Failed Example 2

This `html` element has a `lang` attribute, with no [known primary language tag][].

```html
<html lang="#1"></html>
<html lang="#1">
<body>
<p lang="en">I love ACT rules!</p>
</body>
</html>
```

#### Failed Example 3
Expand Down Expand Up @@ -139,6 +170,16 @@ This rule does not apply to `svg` elements.
<svg xmlns="http://www.w3.org/2000/svg" lang="fr"></svg>
```

#### Inapplicable Example 2

This rule does not apply to content that is empty or contains only [whitespace][].

```html
<html lang="em-US">
<body></body>
</html>
```

[grandfathered tags]: https://www.rfc-editor.org/rfc/rfc5646.html#section-2.2.8
[iso 639.2]: https://www.loc.gov/standards/iso639-2/php/code_list.php 'ISO 639.2: Codes for the Representation of Names of Languages'
[region subtag]: https://www.rfc-editor.org/rfc/rfc5646.html#section-2.2.4 'Definition of region subtag'
Expand Down