見出しに日本語を直接記述するのをやめませんか？

[debiru]

現状の問題

英語版のドキュメントが次のように書かれているとします。

## Specifications

{{Specifications}}

これを日本語版に書き直すとき、次のように現状では書かれています。

## 仕様書

{{Specifications}}

それぞれの HTML の出力結果は以下です。

<h2 id="specifications"><a href="#specifications">Specifications</a></h2>

<h2 id="仕様書"><a href="#仕様書">仕様書</a></h2>

ここで、2つの問題が生じています。

• (p1) 訳語の不統一：Specifications に対応する日本語が 仕様書 に統一されておらず、仕様 と書かれたりもしている。
• (p2) 見出しIDの対応が取れない：ページ内リンクを使おうとすると、見出しのIDが日本語になってしまっており、ハッシュフラグメント付きの英語版のドキュメントURLから言語切替ができない。

具体例

(p1) については、https://developer.mozilla.org/en-US/docs/Web/SVG/Element/a の SVG 要素ページの見出し語などが特に揺れていたりします。

[content] $ pwd
/path/to/content/files/en-us/web/svg/element
[content] $ ag '{{svginfo}}' -B2 | ag '##' | sed -E 's/.+## //' | sort -u
Usage context
Usage notes

[translated-content] $ pwd
/path/to/translated-content/files/ja/web/svg/element
[translated-content] $ ag '{{svginfo}}' -B2 | ag '##' | sed -E 's/.+## //' | sort -u
Usage notes
使用メモ
使用場所
使用場面
利用メモ
使い方メモ
利用ノート
使用上のメモ
使用上の注意
使用可能な場所
利用可能な場所
使用コンテキスト
利用コンテキスト

提案

日本語版ドキュメントで、次のように記述しては如何でしょうか。

## {{__("Specifications")}}

{{Specifications}}

別途、辞書ファイルにて Specifications を日本語に翻訳し、__() マクロによって自動的に日本語に変換する。

これにより、次のような HTML を生成することが可能になります。

<h2 id="specifications"><a href="#specifications">仕様書</a></h2>

利点

• (m1) 翻訳時、英語版の見出しをそのままマクロ化するだけで済み、訳語が揺れることがない。
• (m2) 英語版の見出しと、日本語版の見出しを対応付けることができる。存在する見出しの不一致を検出できる。
• (m3) 見出しが訳されて id が変化したのにリンクの [～](～#id) が訳されていないものが多い mdn/translated-content#11562 のような問題を解決できる。

個人的には特に (m2) の利点が大きいです。存在する見出しの不一致を検出できることで、英語版への追従漏れを検出しやすくなります。

質問

• (q1) そもそも、ローカライズ版では「見出しID」を翻訳すべきだったのでしょうか。翻訳することに決まった経緯を教えて欲しいです。
• (q2) 技術的に、提案で示したようなマクロを導入することは可能でしょうか。ちなみに、このマクロは日本語版に限らず全てのローカライズ版で使える想定のものです。
  • 提案の方法では ## 記法を使っているので、## 記法で任意の ID が設定できるように https://github.com/orgs/mdn/discussions/387#discussioncomment-6067425 で示されているような Markdown 側の記法の拡張をする必要がある。

[potappo]

(q1)に関しては、以下が経緯となります。※Slackだと後々見えなくなるので、こちらに明記しておきます。
#586 (comment)

(q2)
辞書ファイルの実装についてもう少し具体化しないと、上手く管理できるのかなど、利点だけでなく、問題点もあるのかなと思います。

Markdown 側の記法の拡張としては、アンカー ID を見出し項目と異なる ID に変更できる拡張記法がパーサーによっては存在するようです。そちらの実装を Yari で利用しているパーサーに加えるという方向もありなのかもと思いました。
https://qiita.com/Yarakashi_Kikohshi/items/af0b334af1a1e73a5661#-custom-ids