Accessibility, Translation and Hash-Links

[Alex-Genovese]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

The current hash-link setup causes endless problems when a page link is pasted into google translate

Try blog/releases/3.8 in french for example and you can see how that messes up the headings and sub-headings. Most of the title text ends up getting hidden and there are breaks in the middle.

The links in the side bar are fine. You can right click and copy link https://docusaurus.io/blog/releases/3.8#docusaurus-faster sans probleme.

I have done a lot of looking:

The links contained in #9222
ie, are-your-anchor-links-accessible
seem to have been formative to much of Docusaurus hash-link decision making, but this article does go on to say that is not a perfect answer and does go on to mention Google Translate problems, giving a link to here aria-label-is-a-xenophobe on the topic.

Now given that only 18% of the world speak English and that the sidebar produces perfectly satisfactory sublinks that can be copied, I think that an option to turn off the hash-link feature is something that is needed.

After seeing the comments to yet another hash-link problem here#10634 I came up with a workaround:

.hash-link {
  display: none;
}

.hash-link::before {
  display: none;
}

.hash-link:focus,
*:hover > .hash-link {
  display: none;
}

So, this an issue. The underlying fundamental issue may lie with Google or even with W3.org but it is still something that can be fixed easily here.

If people can test pasting this into custom.css and no-one has any problems with Mac Voice Over and other apps, and if Sébastien is okay with this, I'll write a PR for the Style and Layout Docs

Reproducible demo

No response

Steps to reproduce

https://docusaurus-io.translate.goog/blog/releases/3.8?_x_tr_sl=auto&_x_tr_tl=fr&_x_tr_hl=en&_x_tr_pto=wapp

Expected behavior

Try the translate button top right here https://qqxproject.org/docs/Translation

Actual behavior

Hidden Title Text, in blue, only visible on mouse over. In some cases words are missing altogether.

Your environment

Latest Chrome, Firefox, Edge ...

Self-service

• I'd be willing to fix this bug myself.

[slorber]

This issue is hard to interpret for me.

The current hash-link setup causes endless problems

Can you detail precisely all these problems and your suggested solution for each of them?

I understand our UX is globally not perfect regarding accessibility, but I'd like to approach things in an incremental manner where we don't change the entire UX at once, disrupting the experience of existing sites in a minor version.

When linking to existing issues/articles, please explain what in these references I should pay attention to exactly, and which problem we are trying to solve.

---

If one of those problems is the text added to anchors:

I guess we couild try using the no-translate element on various places so that Google translate gives better results

https://www.stefanjudis.com/today-i-learned/non-translatable-html-elements/

[Alex-Genovese]

If we look at the Stefan Judis TIL that you have cited, we end up down a very deep rabbit hole. It doesn't work well in practice:

And he goes on to give an endless data tree of links highlighting all the issues ....

---

I think what I am saying, put in different words, is that the Docusaurus side bar does an excellent job. So much so that if we are using the side bar we don't need to use problematic hash-links and aria labels. They can now be removed.

and your suggested solution

So, what I have done is highlight the issue and paste up the work-around needed for people to have the option to turn off this problematic code.

I also think this could also solve the #9222 problem of Mac Voice Over reading the titles twice.

Ideally, there should be an if sidebar; then hash-link > display none default algorithm.

It's very easy to overlook the knotty problem of translation in the world of computer development, where almost everybody is conversant in English, or at least needs to be ....

In depends on the target audience and how your website is set up, but the majority of everyday website readers will not be able to follow what we write unless it is at least browser translated.

The 2022 figure for the number of people speaking English is only 18.8%

Can you detail precisely all these problems

Open the blog link https://docusaurus-io.translate.goog/blog/releases/3.8?_x_tr_sl=auto&_x_tr_tl=fr&_x_tr_hl=en&_x_tr_pto=wapp

Open the dev tools. In Firefox, this ctrl-shift-c. Hover over the given example title "Docusaurus # plus rapide". It's quite easy to see what happens to the html and aria-label. Click on the top right 'original' you then see the difference.

If you go to the 'Expected behaviour' example that I have given, this has hash-links disabled. Dev tools will show you the absence of aria-labels.

---

It's all about options. I think the side bar does an excellent job. But informing people and giving them the tools to adjust their websites to suit their particular audience is the issue to address.

In my humble opinion, something at least needs to be added to the style guide docs ....

[slorber]

I guess when you say "sidebar" (left), you mean headings table of contents (right)?

We acknowledge the importance of localization, and also have support to translate a site. But I agree auto-translation is also valuable and many sites only support one language. There's also a request to auto-translate the site ourselves before publishing it instead of using browser features: #11226

Open the dev tools. In Firefox, this ctrl-shift-c. Hover over the given example title "Docusaurus # plus rapide". It's quite easy to see what happens to the html and aria-label. Click on the top right 'original' you then see the difference.

Can you please precisely describe what happens. What are the inputs, what are the translated outputs, on a per browser basis, and how can we improve them.

In my humble opinion, something at least needs to be added to the style guide docs ....

What is the style guide docs?

[Alex-Genovese]

I guess when you say "sidebar" (left), you mean headings table of contents (right)?

Yes. My first time working with Docusaurus ... The ToC that auto-generates on the right. That does an excellent job of supplying all the links. 👍

Can you please precisely describe what happens. What are the inputs, what are the translated outputs, on a per browser basis, and how can we improve them.

Just mouse-over any titles, in the main body, that the ToC, on the right, has listed. The messed up display is clear as day, if you are viewing an auto-translated page. Struggling to know what you want here? There must be thousands of case examples ...

how can we improve them

Explain to people how creating a custom css and adding display none can be used as an option:

.hash-link {
  display: none;
}

.hash-link::before {
  display: none;
}

.hash-link:focus,
*:hover > .hash-link {
  display: none;
}

What is the style guide docs?

If we put a short paragraph here in the Style and Layout Docs as previously stated:

If people can test pasting this into custom.css and no-one has any problems with Mac Voice Over and other apps, and if Sébastien is okay with this, I'll write a PR for the Style and Layout Docs

Where the guide explains how to make a custom css file.

We can explain that if websites are showing the auto-generated Table of Contents, on the right, then the ToC will produce the copyable links and that removing hash-links will make things easier for auto-translate. And, probably, will help with the partially sighted or blind who need to use screen readers ...

[Alex-Genovese]

Unless, of course I am talking to a poor AI bot that can't use a mouse and has been tasked by @slorber with answering issues ... 🤣

[slorber]

I'm not an AI bot, but still think the way you present your bug is kind of messy and hard to interpret.

So far, the only thing I can understand in all this is about this display problem on hover on auto-translated pages

I don't understand why you want to document how to add some custom CSS classes instead of fixing the underlying problem for all by adding that CSS to our theme. I may not agree with your solution, but in any case we don't want to document things; we want to provide a good solution out of the box.

---

If there are other issues than this display problem, please be very concrete

• If it's a visual problem, show a screenshot or record a video where the problem is visible
• If it's an accessibility issue related to the HTML markup, please give us the actual/expected markup as a code block

[Alex-Genovese]

You should be able to freeze frame and OCR this video. You should now be able to detect how the title text remains hidden and fails to display on the screen. You should be also able to detect the mouse over which, when done, highlights the problem that web developers are facing.

docs-video-2025-08-02.mp4

[slorber]

So, I see 2 visual problems:

The h2 title being hidden unless we :hover:

The h3 title having an anchor with a label:

All this related to Google Translate thinking it needs to translate the anchor.

---

I just added translate="no", and as I thought, this seems to solve the problem.

Do you still see those issues here?

https://deploy--preview--11360----docusaurus--2-netlify-app.translate.goog/blog/releases/3.8/?_x_tr_sl=auto&_x_tr_tl=fr&_x_tr_hl=fr&_x_tr_pto=wapp

PR: #11360

I'm not saying there's absolutely no accessibility issue, but at least the 2 visual glitches you reported are fixed, right?

If you have other accessibility issues to report, that could be part of different issues (one per problem)

[Alex-Genovese]

I am pleased to see that supplying the video helped you solve the main problem. I have taken note on how this worked. 👍

I am also very impressed with how you managed to put the PR together, and how you managed to get such a quick code review and merge it all.