[docs] Keep the same header between locales

[jaironalves]

• I have searched the issues of this repository and believe that this is not a duplicate.

Intention

Regardless of how the translation affects the content, it should not affect the anchor (#) that keeps pointing to the content.

Summary 💡

The request is that the translations keep the same header, facilitating the way the links are made available between locales.
Currently when a content is translated, the anchor for this content also changes, resulting in the scenario below.

Examples 🌈

• https://material-ui.com/components/rating/#simple-ratings

• https://material-ui.com/zh/components/rating/#%E7%AE%80%E5%8D%95%E8%AF%84%E5%88%86

Expected

Regardless of locale, same content anchor #

• https://material-ui.com/components/rating/#simple-ratings

• https://material-ui.com/zh/components/rating/#simple-ratings

• https://material-ui.com/pt/components/rating/#simple-ratings

Motivation 🔦

Discussion started on this pull request #20779.

[oliviertassinari]

@jaironalves Thanks, regarding the implementation, it would require to:

1. Change the logic of parseMarkdown.js to process the English version first.
2. In the heading handler, use the English hash for the non-English locales

Done

[eps1lon]

Note that using the id from another translation can break if the translations aren't synced. It's not ideal for the master deploy but manageable. We just need to make sure that we never deploy outdated translations to material-ui.com.

[oliviertassinari]

@eps1lon Great point. Depending on the level of quality we want to provide on the translations, we could either fail or fallback to the translated hash. Maybe the latter? Crowdin guarantees that it will be eventually kept in sync.

[eps1lon]

Crowdin guarantees that it will be eventually kept in sync.

That is hardly a useful guarantee. When is "eventually"?

[oliviertassinari]

@eps1lon The "when" depends on the frequency we merge the changes into the repository. I think that it can be automated. Right now, it's every time we manually do it. For instance, once per release.

[eps1lon]

That's what I was saying: It's not as important if they're out-of-sync on master. But they need to be synced before we deploy material-ui.com which happens on release.