Translation of IDs of headings

[debiru]

On the page /docs/README.md#translating-heading-ids says:

When translating headings, you don't need to translate the ID too; the rest of the slug is not translated, so this keeps it all consistent.

In practice, however, it appears that the IDs of headings are translated and described in each language.

So here's my question. Is it more appropriate to write the IDs of headings in English or to translate it? I also heard a rumor that the policy was changed at the time of markdown conversion from HTML format.

If you know the circumstances, including how to describe the headings and IDs and the background of how it works, I would appreciate it if you could enlighten me.

[schalkneethling]

Hey @debiru, thank you for starting the discussion. There was a time when even the slugs on MDN Web Docs were translated, but as you mentioned, when the markdown conversion happened, a decision was made to switch everything to English concerning slugs and ids. Some of this is for consistency across the site, but there have also been bugs in the past when an unsupported character was used in a slug or ID.

There may also be other reasons for the change, but I believe these were the main reasons. Was your question purely out of interest, or is it part of a larger question or discussion?

[debiru]

Was your question purely out of interest, or is it part of a larger question or discussion?

The reason I asked this question is because it was pointed out to me that there is no ja documentation in repository of https://github.com/mdn/translated-content/tree/main/docs and I had to create a new one.

In doing so, I wanted to confirm that the English version of the guide stated that the IDs of headings should not be translated. I believe the actual localized document has the IDs of headings translated.

when the markdown conversion happened, a decision was made to switch everything to English concerning slugs and ids.

Huh? Is it still recommended to write the heading ID in English in the localized version, even after it is markdown conversion?

For example, suppose the English version of the file is described as follows:

## Tutorials

How should this be written in the Japanese version?

case-1:

## チュートリアル

case-2:

<h2 id="tutorials">チュートリアル</h2>

Currently, most articles in each language should be written in case-1. In that case, the heading ID would be translated. Does this mean that it is recommended to write this in case-2? I would like to know whether case-1 or case-2 is the appropriate way to write headings in the localized version of the document.

[debiru]

/docs/README.md#translating-heading-ids

Is the content of this section still applicable now that the document has been markdownized? Or is it already outdated?

I am trying to determine how to write the appropriate headings for the localized version.

[debiru]

I am a contributor to the Japanese localization, and struggling with this issue again.

In translating an in-page link to a section that only exists in the en-US version into the ja version, I ran into a situation where I had to pre-specify an unknown hash fragment.

During our translation work on page A, if there is a link from page A to page B#about-the-spec, but the section about-the-spec only exists in the en-US version (page B translation has not caught up), we are stuck on how to describe that link on the translation side. If the link is only present in the en-US version (the translation of page B has not caught up), the translator is at a loss as to how to describe the link. This is because about-the-spec is an en-US-only heading ID, and the Japanese version may translate the heading ID as 仕様について in the future.

Such a problem could be prevented if the policy was to not translate heading IDs, but at least in the Japanese localization, articles are maintained with the policy of translating heading IDs (using the markdown heading syntax as is).

Should the heading ID really be translated in each localized version? I highly doubt it.

[Josh-Cena]

BTW, there's a Markdown syntax ## チュートリアル {#tutorials} if we want to keep the heading IDs English :)

[debiru]

The MDN markdown specification does not seem to support that syntax ## heading {#id}. Local preview using content or yari repository did not work.

[Josh-Cena]

Yes, it's an extension syntax. I'm saying if we want to (a) use Markdown headings (b) not translate IDs, there's a syntax we can adopt in Yari.

[YujiSoftware]

I want extension syntax.
Because mdn/translated-content has a lot of broken issues with EmbedLiveSample.

Related: mdn/yari#4971