From 7a7441d13b93999fdd3c2f4ba82865806c50790f Mon Sep 17 00:00:00 2001
From: Anthony Johnson <aj@ohess.org>
Date: Mon, 16 Aug 2021 19:09:05 -0600
Subject: [PATCH] Make ARIA labels more verbose and easier to translate

Translators pointed out how the ARIA labels weren't descriptive,
especially because the translators don't have the same context around
the strings and HTML structure.

I added some translator context, so transifex can at least describe what
the string is used for, but also updated some of the strings to be more
descriptive. I dropped "breadcrumb" because it's colloquial language
that almost certainly won't translate well.
---
 sphinx_rtd_theme/breadcrumbs.html | 6 ++++--
 sphinx_rtd_theme/footer.html      | 1 +
 sphinx_rtd_theme/layout.html      | 6 ++++--
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/sphinx_rtd_theme/breadcrumbs.html b/sphinx_rtd_theme/breadcrumbs.html
index 722e266b..005b2ecd 100644
--- a/sphinx_rtd_theme/breadcrumbs.html
+++ b/sphinx_rtd_theme/breadcrumbs.html
@@ -18,7 +18,8 @@
 
 {%- set display_vcs_links = display_vcs_links if display_vcs_links is defined else True %}
 
-<div role="navigation" aria-label="{{ _('Breadcrumbs') }}">
+{#- Translators: This is an ARIA section label for page links, including previous/next page link and links to GitHub/GitLab/etc. -#}
+<div role="navigation" aria-label="{{ _('Page navigation') }}">
   <ul class="wy-breadcrumbs">
     {%- block breadcrumbs %}
       <li><a href="{{ pathto(master_doc) }}" class="icon icon-home"></a> &raquo;</li>
@@ -62,7 +63,8 @@
   </ul>
 
   {%- if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
-  <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="{{ _('Breadcrumbs') }}">
+  {#- Translators: This is an ARIA section label for sequential page links, such as previous and next page links. -#}
+  <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="{{ _('Sequential page navigation') }}">
       {%- if prev %}
         <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> {{ _('Previous') }}</a>
       {%- endif %}
diff --git a/sphinx_rtd_theme/footer.html b/sphinx_rtd_theme/footer.html
index 90e02634..1a395c9c 100644
--- a/sphinx_rtd_theme/footer.html
+++ b/sphinx_rtd_theme/footer.html
@@ -1,5 +1,6 @@
 <footer>
   {%- if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+    {#- Translators: This is an ARIA section label for the footer section of the page. -#}
     <div class="rst-footer-buttons" role="navigation" aria-label="{{ _('Footer') }}">
       {%- if prev %}
         <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> {{ _('Previous') }}</a>
diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html
index e33c8006..1d701197 100644
--- a/sphinx_rtd_theme/layout.html
+++ b/sphinx_rtd_theme/layout.html
@@ -169,7 +169,8 @@
         </div>
 
         {%- block navigation %}
-        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="{{ _('Main') }}">
+        {#- Translators: This is an ARIA section label for the main navigation menu -#}
+        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="{{ _('Navigation menu') }}">
           {%- block menu %}
             {%- set toctree = toctree(maxdepth=theme_navigation_depth|int,
                                       collapse=theme_collapse_navigation|tobool,
@@ -190,7 +191,8 @@
     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 
       {#- MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
-      <nav class="wy-nav-top" aria-label="{{ _('Top') }}" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
+      {#- Translators: This is an ARIA section label for the navigation menu that is visible when viewing the page on mobile devices -#}
+      <nav class="wy-nav-top" aria-label="{{ _('Mobile navigation menu') }}" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
         {%- block mobile_nav %}
           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
           <a href="{{ pathto(master_doc) }}">{{ project }}</a>