Mechanisms to automate translation of heading words

[debiru]

Background

I am a Japanese translation committer. In preparing Japanese articles, the following problems have arisen when translating heading words from the English version.

English document:

## Specifications

Japanese document (A):

## 仕様書

Japanese document (B):

## 仕様

This means that there are inconsistencies of notation in the translation.

There is yet another problem.

In the English version, the following URL can be used for in-page linking.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#specifications

However, in the Japanese version, the URL is as follows.

https://developer.mozilla.org/ja/docs/Web/HTML/Element/Heading_Elements#%E4%BB%95%E6%A7%98%E6%9B%B8

The hash fragment is not "specifications", unlike the English version.

My idea of the ideal situation

English document:

## Specifications

Japanese or other languages documents:

## __("Specifications")

As HTML, it is expanded as follows when Japanese:

<h2 id="specifications">仕様書</h2>

To translate __("Specifications") into "仕様書", use a separate dictionary file.

Is it possible to provide such a mechanism?

See also

https://github.com/orgs/mdn/discussions/387

[caugner]

Hi @debiru, 👋

This is interesting, as both headings (仕様書 and 仕様) are used 6057 and 6258 times respectively. Is there are good reason to use both, or could it make sense to choose one and replace the other occurrences? (This is for @mdn/yari-content-ja to decide.)

As for the heading id, we intentionally derive it from the (translated) heading, as this is the default when rendering Markdown as HTML, and consistent with how GitHub created these (although MDN's heading ids might differ slightly):
https://github.com/mdn/translated-content/blob/f146234390d71eca95ee07023e7c327fcacd30e8/files/ja/web/html/element/heading_elements/index.md#%E4%BB%95%E6%A7%98%E6%9B%B8

Can you explain the problem that these hash fragment differences cause?

[caugner]

Replying to https://github.com/orgs/mdn/discussions/693#discussioncomment-9858963 here to keep threads together:

I don't know how you found that number of times

Good catch, I didn't realize at first that 仕様書 starts with 仕様, so here are the correct numbers:

• 仕様: 190 occurrences, according to: rg '## 仕様$' | wc -l
• 仕様書: 6049 occurrences, according to: rg '## 仕様書$' | wc -l

This suggests that the 仕様 headings should most likely be changed to 仕様書, so I recommend opening a PR to make those headings consistent.

First, it increases the time and effort required during the translation process. During the translation process, the link to the MDN page that exists in the page must be changed from en-US to ja. At this time, if hash fragments are attached, you will have to not only change en-US to ja, but also access the Japanese page to check the Japanese hash fragments.

I understand the problem, and I believe this issue is more prominent with links to other pages that have not yet been translated at the time of translating the page that links there (because yari will make sure to change /ja/ to /en-US/ links for pages that have not yet been translated, because in that case you would need to link to the Japanese url, but using the English anchor).

At the same time, I would argue that this just takes a small amount of time compared to the time to translate a page, and maintaining English headings or anchor names in the translated content likely causes other issues.

Second, if an end-user is working with URLs and wants to derive a Japanese URL from an English URL with hash fragments, simply changing en-US to ja will no longer serve the purpose.

Fair point, we don't support this use case, and we don't plan to support it, because in fact this doesn't seem to be a common use case: For example, in the last 12 months, at most 3 monthly users have accessed a Japanese page with the #specifications hash.

If there is consensus among the localization teams that this problem needs to be addressed, then we're happy to discuss solutions.

Thank you for your understanding.

[debiru]

Thanks for the answer.

So sorry for putting my previous response in a separate tree instead of a reply.

I understand the content of your response. I will hold this matter in abeyance.

By the way, I would like to add that this proposal comes from me personally, not as the Japanese language community.

[debiru]

Hi @caugner, Thanks for the response.

This is interesting, as both headings (仕様書 and 仕様) are used 6057 and 6258 times respectively. Is there are good reason to use both, or could it make sense to choose one and replace the other occurrences?

I don't know how you found that number of times, but it is an example about "仕様書" and "仕様". This is simply a matter of notation shaking. I don't believe that the notations are intentionally separated. I think I would like to solve this problem by means of a translation system using dictionary files.

Can you explain the problem that these hash fragment differences cause?

There are two problems.

First, it increases the time and effort required during the translation process. During the translation process, the link to the MDN page that exists in the page must be changed from en-US to ja. At this time, if hash fragments are attached, you will have to not only change en-US to ja, but also access the Japanese page to check the Japanese hash fragments.

Second, if an end-user is working with URLs and wants to derive a Japanese URL from an English URL with hash fragments, simply changing en-US to ja will no longer serve the purpose.

This would not be a cool URL. refs: https://www.w3.org/Provider/Style/URI.html