rspec/rules/S5254/html/rule.adoc

== Why is this an issue?

The ``++<html>++`` element should provide the ``++lang++`` and/or ``++xml:lang++`` attribute in order to identify the default language of a document.


It enables assistive technologies, such as screen readers, to provide a comfortable reading experience by adapting the pronunciation and accent to the language. It also helps braille translation software, telling it to switch the control codes for accented characters for instance.


Other benefits of marking the language include assisting user agents in providing dictionary definitions or helping users benefit from translation tools.

Both the ``++lang++`` and the ``++xml:lang++`` attributes can take only one value.


=== Noncompliant code example

[source,html]
----
<!DOCTYPE html>
<html> <!-- Noncompliant -->
    <head>
          <title>A page written in english</title>
          <meta content="text/html; charset=utf-8" />
    </head>  


    <body>     
    ...   
    </body>
</html>
----


=== Compliant solution

[source,html]
----
<!DOCTYPE html>
<html lang="en">
    <head>
          <title>A page written in english</title>
          <meta content="text/html; charset=utf-8" />
    </head>  


    <body>     
    ...   
    </body>
</html>
----

[source,html]
----
<!DOCTYPE html>
<html lang="en" xml:lang="en">
    <head>
          <title>A page written in english</title>
          <meta content="text/html; charset=utf-8" />
    </head>  


    <body>     
    ...   
    </body>
</html>
----


== Resources

* https://www.w3.org/TR/WCAG20-TECHS/html.html#H57[WCAG2, H57] - Using language attributes on the html element
* https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-meaning-doc-lang-id[WCAG2, 3.1.1] - Language of Page

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Add "lang" and/or "xml:lang" attributes to this "<html>" element


=== Highlighting

Highlight the <html> element


endif::env-github,rspecator-view[]
-												migrate rule descriptions to new education format

											
										
										
											2023-05-03 11:06:20 +02:00
+								== Why is this an issue?
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
+								The ``++<html>++`` element should provide the ``++lang++`` and/or ``++xml:lang++`` attribute in order to identify the default language of a document.
 								It enables assistive technologies, such as screen readers, to provide a comfortable reading experience by adapting the pronunciation and accent to the language. It also helps braille translation software, telling it to switch the control codes for accented characters for instance.
-												Modify rule S5254: Remove dead link (#3962)


											
										
										
											2024-06-04 12:18:07 +02:00
+								Other benefits of marking the language include assisting user agents in providing dictionary definitions or helping users benefit from translation tools.
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
 								Both the ``++lang++`` and the ``++xml:lang++`` attributes can take only one value.
-												Fix the missing default metadata fields

											
										
										
											2021-04-28 18:08:03 +02:00
-												migrate rule descriptions to new education format

											
										
										
											2023-05-03 11:06:20 +02:00
+								=== Noncompliant code example
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
-												RULEAPI-661: Add syntax coloring


											
										
										
											2022-02-04 17:28:24 +01:00
+								[source,html]
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
+								----
 								<!DOCTYPE html>
 								<html> <!-- Noncompliant -->
 								    <head>
 								          <title>A page written in english</title>
 								          <meta content="text/html; charset=utf-8" />
 								    </head>
 								    <body>
 								    ...
 								    </body>
 								</html>
 								----
-												Fix the missing default metadata fields

											
										
										
											2021-04-28 18:08:03 +02:00
-												migrate rule descriptions to new education format

											
										
										
											2023-05-03 11:06:20 +02:00
+								=== Compliant solution
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
-												RULEAPI-661: Add syntax coloring


											
										
										
											2022-02-04 17:28:24 +01:00
+								[source,html]
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
+								----
 								<!DOCTYPE html>
 								<html lang="en">
 								    <head>
 								          <title>A page written in english</title>
 								          <meta content="text/html; charset=utf-8" />
 								    </head>
 								    <body>
 								    ...
 								    </body>
 								</html>
 								----
-												RULEAPI-661: Add syntax coloring


											
										
										
											2022-02-04 17:28:24 +01:00
+								[source,html]
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
+								----
 								<!DOCTYPE html>
 								<html lang="en" xml:lang="en">
 								    <head>
 								          <title>A page written in english</title>
 								          <meta content="text/html; charset=utf-8" />
 								    </head>
 								    <body>
 								    ...
 								    </body>
 								</html>
 								----
-												Fix the missing default metadata fields

											
										
										
											2021-04-28 18:08:03 +02:00
-												migrate rule descriptions to new education format

											
										
										
											2023-05-03 11:06:20 +02:00
+								== Resources
-												Restructure one-lang rspecs

											
										
										
											2021-04-28 16:49:39 +02:00
 								* https://www.w3.org/TR/WCAG20-TECHS/html.html#H57[WCAG2, H57] - Using language attributes on the html element
 								* https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-meaning-doc-lang-id[WCAG2, 3.1.1] - Language of Page
-												Fix the missing default metadata fields

											
										
										
											2021-04-28 18:08:03 +02:00
-												RULEAPI-666: Migrate the "List of parameters", "Highlighting" and "Message" fields from jira RSPEC (#346)


											
										
										
											2021-09-20 15:38:42 +02:00
+								ifdef::env-github,rspecator-view[]
 								'''
 								== Implementation Specification
 								(visible only on this page)
-												Inline adoc when include has no additional value (#1940)

Inline adoc files when they are included exactly once.

Also fix language tags because this inlining gives us better information
on what language the code is written in.
											
										
										
											2023-05-25 14:18:12 +02:00
+								=== Message
 								Add "lang" and/or "xml:lang" attributes to this "<html>" element
 								=== Highlighting
 								Highlight the <html> element
-												RULEAPI-666: Migrate the "List of parameters", "Highlighting" and "Message" fields from jira RSPEC (#346)


											
										
										
											2021-09-20 15:38:42 +02:00
 								endif::env-github,rspecator-view[]