LoginSignup
1
0
MDNとかをみんなで編集！翻訳！ Advent Calendar 2023Day 18
@debiru

MDN Web Docs の関連リポジトリの紹介

Posted at

はじめに

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

こんにちは。debiru です。サニタイズ言うな。DNS 浸透いうなの会から来ました。

今日は、MDN のリポジトリ群について解説しておこうかなと思います。

MDN の主要リポジトリ

MDN の主要なリポジトリが 6 個、そして日本語版コミュニティのリポジトリが 1 個あります。

content リポジトリ

MDN ドキュメントの原語（en-US; 英語）版のリポジトリです。

content/
└── files/
    └── en-us/
        ├── games/
        ├── glossary/
        ├── learn/
        ├── mdn/
        ├── mozilla/
        ├── related/
        ├── web/
        └── webassembly/

リポジトリ下の files/en-us/ ディレクトリ下に、URL に対応するドキュメントファイルが存在しています。

例えば、上記の Baseline/Compatibility のページであれば、次のファイルパスが対応するドキュメントファイルです。

/content/files/en-us/glossary/baseline/compatibility/index.md

英語版ドキュメントファイルの中身

---
title: Baseline (compatibility)
slug: Glossary/Baseline/Compatibility
page-type: glossary-definition
---

{{GlossarySidebar}}

**Baseline** identifies web platform features that work across browsers.
Baseline helps you decide when to use a feature by telling you when it is less likely to cause compatibility problems for your site's visitors.

...

2020 年 12 月 14 日より、MDN は GitHub ベースの新しい Yari プラットフォームで運用しています。英語版のドキュメントを管理する content リポジトリでは、当初 index.html ファイルでドキュメントを管理していましたが、2021 年 5 月頃に index.md の Markdown 形式へ移行されました。

Markdown 形式のドキュメントは、Yaml Front Matter を伴って記述されます。Yaml Front Matter とは MDN に限らず一般的に使われる書式の一つで、Markdown ドキュメントの先頭に YAML を挿入し、ドキュメントのメタデータを管理できるようにするものです。

translated-content リポジトリ

MDN ドキュメントのローカライズ版のリポジトリです。各国の言語が管理されています。

translated-content/
└─ files/
    ├── es/
    ├── fr/
    ├── ja/
    │    ├── conflicting/
    │    ├── games/
    │    ├── glossary/
    │    ├── learn/
    │    ├── mdn/
    │    ├── mozilla/
    │    ├── orphaned/
    │    ├── related/
    │    ├── web/
    │    └── webassembly/
    ├── ko/
    ├── pt-br/
    ├── ru/
    ├── zh-cn/
    └── zh-tw/

ディレクトリ構造は content リポジトリに類似しています。files/ja/ ディレクトリ下に、URL に対応するドキュメントファイルが存在しています。

例えば、上記の Baseline/Compatibility のページであれば、次のファイルパスが対応するドキュメントファイルです。

/translated-content/files/ja/glossary/baseline/compatibility/index.md

日本語版ドキュメントファイルの中身

---
title: Baseline (互換性)
slug: Glossary/Baseline/Compatibility
l10n:
  sourceCommit: d14b5a927958ec1ab9737f2f9fce0761a4c95c75
---

{{GlossarySidebar}}

**Baseline** （ベースライン）は、ブラウザー間で動作するウェブプラットフォームの機能を確認します。Baseline は、サイトの訪問者に互換性の問題を引き起こす可能性が低くなった時期を示すことで、その機能を使用するタイミングを決定するのに役立ちます。

...

ローカライズ版のドキュメントを管理する translated-content リポジトリでは、英語版と同様に当初は index.html ファイルでドキュメントを管理していました。2022 年 8 月頃に日本語を含むローカライズ版では index.md の Markdown 形式へ完全移行されました。

ローカライズ版では、英語版とは異なる Yaml Front Matter（メタデータ）を記述します。Remove duplicated frontmatter keys from localized content のトピックで説明されている通りですが、ローカライズのドキュメントのメタデータは、英語版のメタデータを継承します。そのため、重複するメタデータはローカライズ版には記述せず継承するようにし、またローカライズ版特有のメタデータを付与します。

title, slug は必須のメタデータであるため省略できません。l10n はローカライズ版専用のパラメータで、sourceCommit パラメータを値として持ちます。sourceCommit には、翻訳時に参照している英語版のドキュメントのコミットハッシュを記載します。これにより、いつのバージョンの英語版を翻訳しているのかを追跡できるようにしています。

l10n は Localization を表す Numeronym（ヌメロニム）の一種です。Numeronym とは数値ベースで単語を表す語のことで、数略語とも呼ばれます。Numeronym には i18n (Internationalization), l10n (Localization), a11y (Accessibility) のような間の文字数を数字に置き換える表記の他に、W3C (WWWC; World Wide Web Consortium) のように文字数を数字に置き換えるもの、P2P (Peer-to-Peer) のように発音を数字に置き換えるものも含まれます。

browser-compat-data リポジトリ

Browser Compat Data（BCD; ブラウザーの互換性テーブル）を管理しているリポジトリです。

caniuse.com でも表示されるデータです。caniuse.com には "caniuse" 情報と "MDN" 情報の 2 種類があります。この "MDN" 情報の方は BCD リポジトリの情報が使われています。

余談ですが、BCD テーブルの情報はしばしば間違っていることがあります。できる限り正しい情報を入力するようにはしているはずですが、必ずしも正しいとは限らないので、MDN の BCD テーブルの情報を過信しないようにしましょう。間違っているデータを見つけたら、このリポジトリの Issue で報告するか、GitHub 上で修正しプルリクエストを作成することができます。

BCD 管理ファイルの中身

/browser-compat-data/css/properties/text-wrap.json

例えば text-wrap プロパティに対する BCD テーブルは、以下のような JSON で管理されています。

...
"balance": {
  "__compat": {
    "description": "<code>balance</code>",
    "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/text-wrap#balance",
    "spec_url": "https://drafts.csswg.org/css-text-4/#valdef-text-wrap-balance",
    "support": {
      "chrome": {
        "version_added": "114"
      },
      "chrome_android": "mirror",
      "edge": "mirror",
      "firefox": {
        "version_added": "121"
      },
      "firefox_android": "mirror",
      "ie": {
        "version_added": false
      },
      "oculus": "mirror",
      "opera": "mirror",
      "opera_android": "mirror",
      "safari": {
        "version_added": false
      },
      "safari_ios": "mirror",
      "samsunginternet_android": "mirror",
      "webview_android": "mirror"
    },
    "status": {
      "experimental": false,
      "standard_track": true,
      "deprecated": false
    }
  }
},
...

interactive-examples リポジトリ

Interactive Examples は埋め込みデモコードの一種です。埋め込みデモコードについては、先日の記事「MDN の埋め込みデモコードが壊れているので修正するよ」で詳しく紹介しています。

管理されている実際のコードは HTML や CSS, JavaScript のコードです。

yari リポジトリ

yari リポジトリは MDN Web Docs のプラットフォーム自体を構成するためのプログラムを管理しているリポジトリです。例えばマクロコードの実装やサイドバーの実装などがあります。

mdn-community リポジトリ

mdn-community リポジトリは、主に情報交換をするための場です。英語版メンテナや各言語のコントリビューターと情報交換をすることができます。そのような人々に対して何か質問や意見をしたい場合は https://github.com/orgs/mdn/discussions からトピックを作成することができます。

mozilla-japan/translation リポジトリ

このリポジトリは日本 Mozilla コミュニティ向けに用意されたリポジトリで、日本語ローカライズに関する情報を扱うことができます。

特に、翻訳作業時にはこのリポジトリで Issue を作成します。実際の翻訳作業は translated-content リポジトリで行い、プルリクエストも translated-content リポジトリに作成しますが、Issue だけは mozilla-japan/translation リポジトリに作成することを推奨します。

Issue を translated-content リポジトリに作成しても良いのですが、translated-content リポジトリは他の国の作業も混じっているため、Issue が埋もれてしまいがちです。そのため、日本語コミュニティにクローズドでも差し支えない作業内容の報告等であれば mozilla-japan/translation リポジトリへ Issue を作成する方が都合が良いのです。

もちろん、他の国の人にも伝えたい作業内容を扱う場合には、意図的に translated-content リポジトリの Issue を作成して構いません。ただし、その場合は積極的に英語で記述するようにしましょう。そうでなければ、通常は mozilla-japan/translation リポジトリへの Issue および translated-content リポジトリへのプルリクエスト作成時には日本語で記述しても構いません。なぜなら、プルリクエストのレビュアーは日本のメンバーであって、他の国の読者を考慮する必要が通常はないからです。

より詳細な翻訳作業時のガイドラインについては https://mozilla-japan.github.io/mdn-translation-guide/ を参照してください。

さいごに

MDN のリポジトリ群を紹介してみました。MDN ページのログを追跡したりしたい場合には、上記の情報を参考にリポジトリを調査してみてください。

他にも、以下のようなツールを公開しています。

2023 年の MDN 翻訳 Advent Calendar をほとんど私が書いていますが、他の方の記事を読みたい場合は過去のアドベントカレンダーを参照してみてください。

おわり。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0