Learn a11y headline and corrections. (#9395)

* headlines for a11y avail * improve description * fix correct answer on Document assessment * example of multiple languages * clarify answer on language * Title
GoogleChrome · Jan 12, 2023 · d83c37f · d83c37f
1 parent f80897e
commit d83c37f
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 10 deletions.
diff --git a/src/site/content/en/blog/learn-accessibility-available/index.md b/src/site/content/en/blog/learn-accessibility-available/index.md
@@ -1,11 +1,11 @@
 ---
 layout: post
-title: Learn Accessibility! is complete
+title: All of Learn Accessibility! is available
 subhead: >
-  All modules in this course are now available.
+  All modules have now been published.
 description: >
-  We launched the final modules for Learn Accessibility, which means you
-  can now take this course from start to finish.
+  We launched the final modules for Learn Accessibility. This means you
+  can take this course from start to finish or in any order you choose.
 date: 2023-01-12
 authors:
   - alexandrawhite

diff --git a/src/site/content/en/learn/accessibility/more-html/document.assess.yml b/src/site/content/en/learn/accessibility/more-html/document.assess.yml
@@ -3,12 +3,12 @@ tabLabel: question
 questions:
   - type: multiple-choice
     cardinality: "1"
-    correctAnswers: "1"
+    correctAnswers: "2"
     stem: Your site is a multi-language online textbook, where multiple languages are shown on one page. What's the best way to tell assistive technology the language of the copy?
     options:
       - content: "Don't worry about it, the AT can automatically read each language."
         rationale: "While some AT may have language detection skills, you can't guarantee the AT will guess correctly."
-      - content: 'Include all languages in the `<html>` element.'
+      - content: 'Include all languages in the `<html>` element. For example `<html lang="en,lt,pl,pt">`'
         rationale: 'The `lang` attribute can only have one language associated with it.'
-      - content: 'Set `lang` on each element.'
-        rationale: 'The AT will primarily rely on the `<html>` attribute to read the document, unless an element is explicitly labeled with a different `lang`. For multi-language text, make sure to add a `lang` attribute around the language which differs from the main HTML document.'
+      - content: 'Set a primary `lang` for the `<html>`, and additional languages on any element which has content in a different language.'
+        rationale: 'The AT will primarily rely on the `<html>` language attribute to read the document. If you have multi-language text, make sure to add a `lang` attribute to the corresponding element (such as a section or paragraph) with the correct two letter ISO code.'
diff --git a/src/site/content/en/learn/accessibility/more-html/index.md b/src/site/content/en/learn/accessibility/more-html/index.md
@@ -82,7 +82,7 @@ title, so be sure to limit your total page title characters.
 The page language attribute ([`lang`](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/lang)) sets the default language for the entire page. This attribute is added to the [`<html>`](https://developer.mozilla.org/docs/Web/HTML/Element/html) tag. A valid language attribute should be added to every page as it signals the AT to which language it should use.
 
 It's recommended that you use two-character
-[ISO language codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
+[ISO language codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
 for greater AT coverage, as many of them do not support
 [extended language codes](https://webaim.org/techniques/language/).
 
@@ -106,11 +106,43 @@ digital product and a frustrated user.
 {% endCompare %}
 </div>
 
+The lang attribute can only have one language associated with it. This means
+the `<html>` attribute can only have one language, even if there are multiple
+languages on the page. Set `lang` to the primary language of the page.
+
+<div class="switcher">
+{% Compare 'worse' %}
+```html
+<html lang="ar,en,fr,pt">...</html>
+```
+
+{% CompareCaption %}
+Multiple languages are not supported.
+{% endCompareCaption %}
+{% endCompare %}
+
+{% Compare 'better' %}
+```html
+<html lang="ar">...</html>
+```
+
+{% CompareCaption %}
+Set only the page's primary language. In this case, the language is Arabic.
+{% endCompareCaption %}
+{% endCompare %}
+</div>
+
 ### Section language
 
 You can also use the language attribute ([lang](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/lang)) for language switches in the content itself. The same basic rules apply as the full-page language attribute, except you add it to the appropriate in-page element instead of on the `<html>` tag.
 
-Remember that the language you add to the `<html>` element cascades down to all the contained elements, so always set the primary language of the page top-level `lang` attribute first. Then for any in-page elements written in a different language, add that lang attribute to the appropriate wrapper element. Doing this will override the top-level language setting until that element is closed.
+Remember that the language you add to the `<html>` element cascades down to all
+the contained elements, so always set the primary language of the page
+top-level `lang` attribute first.
+
+For any in-page elements written in a different language, add that `lang`
+attribute to the appropriate wrapper element. This will override the
+top-level language setting until that element is closed.
 
 <div class="switcher">
 {% Compare 'worse' %}