Give every website and book nav landmark a distinct, localizable label (#14813)

Website and book pages emit up to six <nav> landmarks. Before this
change, only the breadcrumbs had a label, and it was hardcoded English
("breadcrumb"). Assistive technology listed the rest as identical
"navigation" entries, and axe flagged the pages under landmark-unique.

Each landmark now gets a distinct label from a new set of language
keys, all nouns so they hold up under translation (bare adjectives like
"Main" don't survive into languages where the word is a bound prefix or
needs to agree with a noun):

- Navbar: navigation-site-label ("Site")
- Sidebar: adaptive — "Site" with no navbar, navigation-section-label
  ("Section") when a navbar is also present
- Mobile nav strip: navigation-toolbar-label ("Toolbar")
- Previous/next page nav: navigation-page-label ("Page")
- Breadcrumbs (both copies): navigation-breadcrumbs-label
  ("Breadcrumbs")
- Table of contents (html and revealjs): aria-labelledby pointing at
  its existing localized heading, no new key

All keys are overridable per-document or site-wide via `language:`
metadata, and translated across all 33 bundled language files.

Verified axe landmark-unique passes across navbar/sidebar/book
combinations and viewport sizes, and confirmed with the VoiceOver
landmark rotor that each landmark announces a distinct name.

Fixes #14376.

Author: cwickham

news/changelog-1.11.md

@@ -12,6 +12,9 @@ All changes included in 1.11:
 - ([#14615](https://github.com/quarto-dev/quarto-cli/issues/14615)): Fix invalid `role="menu"` on the website navbar's collapse toggle button, flagged by axe-core (`aria-allowed-role`) and WAVE (`aria-role-mismatch`).
 - ([#12116](https://github.com/quarto-dev/quarto-cli/issues/12116), [#4935](https://github.com/quarto-dev/quarto-cli/issues/4935)): Website sidebar section toggles are now `<button>` elements, so they are keyboard accessible and properly announced.
 - ([#14774](https://github.com/quarto-dev/quarto-cli/issues/14774)): Fix missing keyboard focus indicator on the code tools button and on a website's sidebar toggle and sidebar search buttons.
+- ([#14376](https://github.com/quarto-dev/quarto-cli/issues/14376)): Add a distinct, localizable `aria-label` to each navigation landmark of websites and books: the navbar (`Site`), the sidebar (`Section`, or `Site` when there is no navbar), the narrow-viewport toolbar (`Toolbar`), the previous/next page navigation (`Page`), and the breadcrumbs (`Breadcrumbs`) (previously hardcoded English `breadcrumb`). The new `navigation-*-label` language keys can be overridden with `language:` metadata.
+- ([#14376](https://github.com/quarto-dev/quarto-cli/issues/14376)): Translate the new `navigation-*-label` keys in all 33 built-in language files. The values are drawn from existing human-translated interface strings (LibreOffice, GNOME, Wikidata) and each one carries a comment naming its source; values that were adapted rather than used verbatim are marked `needs review`.
+- ([#14376](https://github.com/quarto-dev/quarto-cli/issues/14376)): Label the table of contents `<nav>` with its localized title (`aria-labelledby`), in `html` and `revealjs` output, so assistive technology can tell it apart from other navigation landmarks.
 
 ## Formats
 

src/config/constants.ts

@@ -305,6 +305,12 @@ export const kToggleDarkMode = "toggle-dark-mode";
 export const kToggleReaderMode = "toggle-reader-mode";
 export const kToggleNavigation = "toggle-navigation";
 
+export const kNavigationSiteLabel = "navigation-site-label";
+export const kNavigationSectionLabel = "navigation-section-label";
+export const kNavigationToolbarLabel = "navigation-toolbar-label";
+export const kNavigationPageLabel = "navigation-page-label";
+export const kNavigationBreadcrumbsLabel = "navigation-breadcrumbs-label";
+
 export const kCopyButtonTooltip = "copy-button-tooltip";
 export const kCopyButtonTooltipSuccess = "copy-button-tooltip-success";
 export const kBackToTop = "back-to-top";
@@ -434,6 +440,11 @@ export const kLanguageDefaultsKeys = [
   kToggleReaderMode,
   kToggleSidebar,
   kToggleSection,
+  kNavigationSiteLabel,
+  kNavigationSectionLabel,
+  kNavigationToolbarLabel,
+  kNavigationPageLabel,
+  kNavigationBreadcrumbsLabel,
   kCopyButtonTooltip,
   kCopyButtonTooltipSuccess,
   kBackToTop,

src/config/types.ts

@@ -157,6 +157,11 @@ import {
   kMathml,
   kMergeIncludes,
   kMermaidFormat,
+  kNavigationBreadcrumbsLabel,
+  kNavigationSiteLabel,
+  kNavigationPageLabel,
+  kNavigationToolbarLabel,
+  kNavigationSectionLabel,
   kNotebookLinks,
   kNotebookPreserveCells,
   kNotebookPreviewBack,
@@ -703,6 +708,11 @@ export interface FormatLanguage {
   [kToggleReaderMode]?: string;
   [kToggleSection]?: string;
   [kToggleSidebar]?: string;
+  [kNavigationSiteLabel]?: string;
+  [kNavigationSectionLabel]?: string;
+  [kNavigationToolbarLabel]?: string;
+  [kNavigationPageLabel]?: string;
+  [kNavigationBreadcrumbsLabel]?: string;
   [kSearchMatchingDocumentsText]?: string;
   [kSearchCopyLinkTitle]?: string;
   [kSearchMoreMatchText]?: string;

src/project/types/website/website-navigation.ts

@@ -130,6 +130,7 @@ import {
 import {
   kBackToTop,
   kIncludeInHeader,
+  kNavigationBreadcrumbsLabel,
   kNumberSections,
   kRepoActionLinksEdit,
   kRepoActionLinksIssue,
@@ -472,7 +473,7 @@ function navigationHtmlPostprocessor(
     );
     if (secondaryNavTitleEl) {
       if (showBreadCrumbs) {
-        const navEl = makeBreadCrumbs(doc);
+        const navEl = makeBreadCrumbs(doc, language);
         if (secondaryNavTitleEl.parentElement) {
           secondaryNavTitleEl.parentElement.replaceChild(
             navEl,
@@ -506,6 +507,7 @@ function navigationHtmlPostprocessor(
       if (navigation.breadCrumbs && navigation.breadCrumbs.length > 1) {
         const titleBreadCrumbEl = makeBreadCrumbs(
           doc,
+          language,
           ["quarto-title-breadcrumbs", "d-none", "d-lg-block"],
         );
         // See if there is deeper target
@@ -907,7 +909,11 @@ async function resolveFooter(
   return footer;
 }
 
-function makeBreadCrumbs(doc: Document, clz?: string[]) {
+function makeBreadCrumbs(
+  doc: Document,
+  language: FormatLanguage,
+  clz?: string[],
+) {
   // Make bootstrap breadcrumbs
   const navEl = doc.createElement("nav");
   navEl.classList.add("quarto-page-breadcrumbs");
@@ -916,7 +922,7 @@ function makeBreadCrumbs(doc: Document, clz?: string[]) {
       navEl.classList.add(cls);
     });
   }
-  navEl.setAttribute("aria-label", "breadcrumb");
+  navEl.setAttribute("aria-label", language[kNavigationBreadcrumbsLabel]!);
 
   const olEl = doc.createElement("ol");
   olEl.classList.add("breadcrumb");

src/resources/editor/tools/vs-code.mjs

@@ -10596,6 +10596,11 @@ var require_yaml_intelligence_resources = __commonJS({
                   null
                 ]
               },
+              "navigation-site-label": "string",
+              "navigation-section-label": "string",
+              "navigation-toolbar-label": "string",
+              "navigation-page-label": "string",
+              "navigation-breadcrumbs-label": "string",
               "crossref-fig-title": "string",
               "crossref-tbl-title": "string",
               "crossref-lst-title": "string",
@@ -25884,12 +25889,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 218590,
+        _internalId: 218600,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 218582,
+            _internalId: 218592,
             type: "enum",
             enum: [
               "png",
@@ -25905,7 +25910,7 @@ var require_yaml_intelligence_resources = __commonJS({
             exhaustiveCompletions: true
           },
           theme: {
-            _internalId: 218589,
+            _internalId: 218599,
             type: "anyOf",
             anyOf: [
               {

src/resources/editor/tools/yaml/all-schema-definitions.json

@@ -3564,6 +3564,11 @@
               null
             ]
           },
+          "navigation-site-label": "string",
+          "navigation-section-label": "string",
+          "navigation-toolbar-label": "string",
+          "navigation-page-label": "string",
+          "navigation-breadcrumbs-label": "string",
           "crossref-fig-title": "string",
           "crossref-tbl-title": "string",
           "crossref-lst-title": "string",
@@ -18852,12 +18857,12 @@
     "mermaid": "%%"
   },
   "handlers/mermaid/schema.yml": {
-    "_internalId": 218590,
+    "_internalId": 218600,
     "type": "object",
     "description": "be an object",
     "properties": {
       "mermaid-format": {
-        "_internalId": 218582,
+        "_internalId": 218592,
         "type": "enum",
         "enum": [
           "png",
@@ -18873,7 +18878,7 @@
         "exhaustiveCompletions": true
       },
       "theme": {
-        "_internalId": 218589,
+        "_internalId": 218599,
         "type": "anyOf",
         "anyOf": [
           {

src/resources/editor/tools/yaml/web-worker.js

@@ -1,4 +1,4 @@
-<nav id="$idprefix$TOC" role="doc-toc">
+<nav id="$idprefix$TOC" role="doc-toc"$if(toc-title)$ aria-labelledby="$idprefix$toc-title"$endif$>
   $if(toc-title)$
   <h2 id="$idprefix$toc-title">$toc-title$</h2>
   $endif$ 

src/resources/editor/tools/yaml/yaml-intelligence-resources.json

@@ -1,5 +1,5 @@
 <section id="$idprefix$TOC">
-<nav role="doc-toc"> 
+<nav role="doc-toc"$if(toc-title)$ aria-labelledby="$idprefix$toc-title"$endif$>
 $if(toc-title)$
 <h2 id="$idprefix$toc-title">$toc-title$</h2>
 $endif$