MDNのドキュメント翻訳にコントリビュートしてみた

MDN Web Docsの翻訳にコントリビュートしてみたので備忘録です。
2022.10.14

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

どうも。CX事業本部Delivery部のえーたん(@eetann092)です。

MDN Web Docsがオープンソースのプロジェクトであることはご存知ですか?本家の英語版のリポジトリはmdn/content、翻訳プロジェクトのリポジトリはmdn/translated-contentです。

先日、この翻訳プロジェクトにコントリビュートしてみたので、その備忘録を残しておきます。

手順を知りたい

翻訳プロジェクトへのコントリビュート手順は、 以下のページに日本語で掲載されています。GitHubアカウントの作り方から丁寧に解説してあります。

独自のMarkdown記法について知りたい

以前筆者がコントリビュートしたときはHTMLで書きましたが、最近Markdown記法に変わったようです。

翻訳であればゼロからコンテンツを作るわけではないため、MDNドキュメント独自のMarkdown記法について知らなくても良いかもしれません。 記法自体は以下のドキュメントにまとまっています。

筆者は気になったので一部調べてみました。

{{WebExtAPIRef("runtime.onMessage()")}}のように書くと、階層runtime以下にあるruntime.onMessage()のページへのリンクを書くことができます。日本語版が存在すれば日本語版へのリンク、存在しなければ英語版のリンクになります。

-」の次の行が「インデントと- :」で始まる部分は、定義リストになります。 定義リストは、語句とその説明を表す要素です。

以下に記法の例とプレビューの画像を掲載します。

- {{WebExtAPIRef("runtime.getURL()")}}
  - : hogeです。
- {{WebExtAPIRef("runtime.PlatformInfo")}}
  - : fooです。
- 語句
  - : 語句の説明を書く所。普通のリストとは違う。
- {{WebExtAPIRef("runtime.reload()")}}
  - : barです。

---

- hoge
  - 普通のリストです
- foo
  - bar

プレビューしたい

Markdownで書いたファイルは、プレビューで確認できます。以下がプレビュー画面の例です。

translated-contentのREADMEや前述のMDN Web Docs ドキュメント翻訳の始め方にもプレビュー方法が書かれています。 翻訳版をプレビューするには、contentリポジトリも必要です。 筆者はREADMEの一部を読み飛ばしてしまい、プレビューできずにしばらく時間を無駄にしていました。

READMEの"Content repo setup"contentリポジトリでの準備の説明です。環境変数の設定はこちらで行います。 "Working in the translated-content repo"translated-contentリポジトリでの作業の説明です。

翻訳にあたって表記のルールを知りたい

表記のルールは執筆スタイルガイド便利なリンク集などに書かれている以下のリンクが参考になります(Mozilla JapanコミュニティのSlackで確認しました)。

筆者はこれらのリンクを知らずにPull Requestを出したため、実際のレビューでは「ブラウザをブラウザーへの統一する」などのご指摘いただきました。 目grepならぬ目textlintでは限界があるため、各自テキストエディタでtextlintとそのルールを設定すると良さそうですね。

(2022年11月4日追記)
目grepならぬ目textlintでは限界があるため、mdn-textlint-jaを使うと良さそうです。以下の記事にmdn-textlint-jaについて書きました。