はじめに

この記事は 2023 年の MDN 翻訳 Advent Calendar 向けに作成したものです。

こんにちは。debiru です。好きな次世代 grep は ag (the-silver-searcher) です。次世代 grep を利用してない？そんな人がいるんですか！

さて、今日は、MDN の記事を読んでいるときに記事中のプレビューが表示されないなどの不具合を見つけたらどうすべきかについて解説していきます。

記事に埋め込まれたデモコードのプレビュー

MDN でこのような記事を見たことはあるでしょうか。

"Try it" というセクションに JavaScript Demo が埋め込まれていて、実際のコードの動作結果を確認することができるようになっています。

MDN ではデモコードの埋め込みにはいくつか種類があり、上記のような実際に動作確認ができるタイプのデモコードは Interactive Example と呼ばれています。

埋め込みに失敗しているデモコード

たまたまページを閲覧していたら、日本語訳の Null 合体代入 (??=) のページで埋め込みに失敗しているデモコードを見つけました。

そこで私は何をしたか

修正したいわけですが、ここで私は次のことを考えました。

なんでデモコード動いてないの……。
英語版はどうなっているだろう。
interactive-examples リポジトリの変更履歴はどうなっているのだろう。
- 変更したなら参照しているコンテンツ側も書き換えないとダメだろうに何考えてるんだ（おこ）。
同様に埋め込みに失敗しているページは他に何があるだろうか。

そうなのです。このページだけを修正すれば済む話ではないのです。MDN のドキュメント整備というのは体系的に行われるべきなのです。同様の問題が起こっている箇所を全て洗い出しましょう。

埋め込みデモコード（マクロ）の種類

EmbedInteractiveExample - {{EmbedInteractiveExample("pages/js/array-push.html")}}
- https://developer.mozilla.org/ja/docs/web/javascript/reference/global_objects/array/push
EmbedLiveSample - {{EmbedLiveSample("Examples")}}
- https://developer.mozilla.org/ja/docs/Glossary/Inline-level_content
EmbedGHLiveSample - {{EmbedGHLiveSample("learning-area/html/forms/range-example/index.html", '100%', 200)}}
- https://developer.mozilla.org/ja/docs/learn/forms/html5_input_types
EmbedYoutube - {{EmbedYouTube("IK97XMibEws")}}
- https://developer.mozilla.org/ja/docs/learn/accessibility/what_is_accessibility
JSFiddleEmbed - {{JSFiddleEmbed("https://jsfiddle.net/rybr720u/","","350")}}
- https://developer.mozilla.org/ja/docs/games/techniques/3d_on_the_web/building_up_a_basic_demo_with_three.js

この中で、MDN リソースとしてデモコードが正常に埋め込まれているのかを検証可能なのは EmbedInteractiveExample と EmbedGHLiveSample だけです。

EmbedLiveSample は外部ファイルからの読み込みではなく同一ページ中にあるコードを利用してデモを展開するので読み込みに失敗するということがありません。EmbedYoutube と JSDiddleEmbed は MDN 外の外部リソースなので読み込もうとしているリソースの存在有無を確認することが容易にはできません。

今回は、スコープを広げる理由も特にないので EmbedInteractiveExample に絞って調査することにしました。

関連ページ

https://developer.mozilla.org/ja/docs/MDN/Writing_guidelines/Page_structures/Code_examples
https://developer.mozilla.org/ja/docs/MDN/Writing_guidelines/Howto/Images_media
https://github.com/mdn/yari/blob/main/kumascript/macros/JSFiddleEmbed.ejs

EmbedInteractiveExample マクロのフォーマット

マクロが正常に読み込めるかどうかを検証するために、まずマクロのフォーマットを確認する必要があります。

{{EmbedInteractiveExample("pages/css/grid.html")}}
{{EmbedInteractiveExample("pages/tabbed/dl.html", "tabbed-standard")}}
{{EmbedInteractiveExample("pages/js/string-slice.html", "taller")}}

適当に translated-content リポジトリの中を ag (grep) したところ、上記のようなマクロを見つけました。第 2 引数はなんだろう。

ということで実装を読むわけです。すると、埋め込みウィジェットの高さを決定するための引数であることがわかりました。つまり埋め込みの可否自体には関係ありません。

ということで第 1 引数を検証していけばよいことが分かりました。

対応する Interactive Example の実体

Interactive Example の実体は interactive-examples リポジトリで管理されています。

pages/tabbed/dl.html という指定に対して、実体が存在するかどうかを確認するにはどうすればよいのでしょうか。ということで tabbed などと ag (grep) してみると、meta.json ファイルにその記述があることが分かりました。

{
  "pages": {
    "blockquote": {
      "exampleCode": "./live-examples/html-examples/text-content/blockquote.html",
      "cssExampleSrc": "./live-examples/html-examples/text-content/css/blockquote.css",
      "fileName": "blockquote.html",
      "title": "HTML Demo: <blockquote>",
      "type": "tabbed",
      "height": "tabbed-standard"
    },
    "dd": {
      "exampleCode": "./live-examples/html-examples/text-content/dd.html",
      "cssExampleSrc": "./live-examples/html-examples/text-content/css/dd.css",
      "fileName": "dd.html",
      "title": "HTML Demo: <dd>",
      "type": "tabbed",
      "height": "tabbed-standard"
    },
    ...
}

interactive-examples リポジトリ内にある meta.json をパースして type プロパティと fileName プロパティの値を拾ってやれば検証できそうな雰囲気が出てきました。

`meta.json` をパースして、実際のドキュメント内のマクロと照合する

照合して一覧表を出力します。

これは実装したものです。

そして、一覧表はこちらです。

URL	不正なマクロ
https://developer.mozilla.org/ja/docs/web/api/reporterror	pages/js/self-reporterror.html
https://developer.mozilla.org/ja/docs/web/javascript/reference/global_objects/intl/segmenter/segment/segments	pages/js/intl-segments-prototype-containing.html
https://developer.mozilla.org/ja/docs/web/javascript/reference/global_objects/intl/segmenter/segment/segments/containing	pages/js/intl-segments-prototype-containing.html
https://developer.mozilla.org/ja/docs/web/javascript/reference/global_objects/map/groupby	pages/js/array-groupbytomap.html
https://developer.mozilla.org/ja/docs/web/javascript/reference/global_objects/string/@@iterator	pages/js/string-iterator.html
https://developer.mozilla.org/ja/docs/web/javascript/reference/operators/nullish_coalescing_assignment	pages/js/expressions-logical-nullish-assignment.html

不正な Interactive Example マクロを記述しているページが 6 件見つかりました。このうち 2 件は、マクロは記述されているもののコメントアウトされていて影響がないページです。というわけで実質問題があるページは 4 件でした。

不正なマクロの修正を開始する

実はここまでは予備調査でした。この調査内容がなくても「適切な」修正自体は可能なはずです。「適切な」というのは、修正すべき箇所を網羅的に修正するという意味です。interactive-examples リポジトリでマクロのキーが変更された時点で、英語版でどのように修正されているのかを追えばよいのです。

不正なマクロに関する英語版の修正履歴

interactive-examples リポジトリでのキーの変更は https://github.com/mdn/interactive-examples/pull/2589 のコミットで行われています。

英語版の記事を管理する content リポジトリでは、https://github.com/mdn/content/pull/28724 のコミットで修正が行われていたことが分かります。

これと同様の修正を日本語版に取り込むべきだったのです。それが漏れていたのが今回の問題の原因でした。これだけが原因かどうかを判断するのに「予備調査」が必要だったわけです。不正なマクロのあった問題のあるページと、このコミットで変更されたページが一致していますよね。

では修正を始めましょう。

すると、なんか一部修正されていることも分かりました。git blame で追ってみると、https://github.com/mdn/translated-content/pull/15489 のコミットがあることが分かりました。

そんなこんなで、実際に修正した Pull-Req がこちらです。

ちょっと待てよ…？

修正したのはいいけど、いま修正したのは「不正なマクロがあるページ」だけでした。

もしかしたら、「あるべきマクロが記述されていない日本語ページ」が存在するかもしれません。ということに気づきました。よし、追加で調査してみましょう。

一覧表をもういっちょ魔改造

英語版のページで使われている Interactive Example マクロの一覧を追加しました。

「英語版にマクロが記述されており、日本語版にマクロが記述されていないページ」の一覧は次の通りです。

Interactive Example マクロが抜けているページを修正しました

122 ページほどありました。マクロの追加位置を自動的に決定できないので手作業で追加しました。ちょっと疲れました。

さいごに

ちょっと記事が長くなってしまいましたね。最後まで読んでいただいた方はありがとうございます。

いかがでしたか。私はこんなことをしながら MDN ドキュメントを日々メンテナンスしています。少しは雰囲気が伝わったでしょうか。

またネタを考えながら明日以降も記事が書けたらよいなと思っていますが、それよりも他の方に 2023 年の MDN 翻訳 Advent Calendar に参加していただけたら嬉しいなと思っています。

ということで、MDN のドキュメントを整備するお話でした。

おわり。