-
Notifications
You must be signed in to change notification settings - Fork 13
Get started with translation of Mozilla documentations
これは、Google、Microsoft、Mozilla が共同でメンテナンスしている Web 開発者向けのドキュメントサイト、MDN Web Docs プロジェクトの開発ドキュメントを翻訳する作業ステップを簡単にまとめたものです。このページのオリジナルは、2015-03-25 に行われた MDN 翻訳ミートアップで、mar さんが解説してくれた内容を元に、catch さんが整理したものです（元ページ）。MDN の現状に合わせて、適宜更新を加えています。
ミートアップの翻訳ガイド経由でこのページにいらっしゃった方は「作業ステップ」の内容はすでに翻訳ガイドで説明済みかと思いますので、「作業上のヒント」や「FAQ」などのセクションを読むと役立つかもしれません。
MDN 日本語版では、Web 開発者向けドキュメントである MDN Web Docs の日本語訳を作成しています。
各ドキュメントは、英語ページは en-US、日本語ページは ja の階層に配置します。
(例)
原文 : https://developer.mozilla.org/en-US/Firefox
日本語: https://developer.mozilla.org/ja/Firefox
各ページのLANGUAGE(言語)アイコン(右上)でも、翻訳済みの言語が確認できます。
まだ未翻訳のドキュメントがあった場合、翻訳のリクエストと作業の進捗状況は、以下で確認できます。
- GitHub mozilla-japan/translation
- GitHub mozilla-japan/translation 翻訳リスト
- GitHub mozilla-japan/translation 翻訳Wiki
- [ja][すべての製品] L10N ダッシュボード | Mozilla サポート
タグ「editorial」の付いた要レビュー記事
開発者向けドキュメントサイト Mozilla Developer Network (MDN) のドキュメント翻訳状況は、Yari への移行に伴い、MDN 上には無くなりました。類似的なものとして、翻訳状況を調査するためのツールがいくつか存在します。
- translation-tracer：英語版と日本語版の全ファイルを比較し、翻訳されていないページや更新されていないページ、その他、特殊な状況にあるページを探すことができます。(関連 issue)
- Translation dashboard ：英語版と構造的に差異が多いページをフィルターで探すことができる Yari ローカルサーバーで使える機能。日本語版の場合、http://localhost:5042/ja/_translations
- MDN翻訳ステータス一覧表：正規表現フィルタに単語やディレクトリ名を入力し、ラジオボタンから ja / not ja などを選択することで、翻訳されているページ、まだ翻訳されていないページを絞り込むことができます。例：https://mdn.lavoscore.org/?filter=not-ja®ex_b=glossary （関連 issue）
詳細は、翻訳ミートアップで利用していたスライドを元にした翻訳ガイドを参考にしてください。
MDN Web Docs の内容は、GitHub で管理されています。(2020年の終わりごろまでは、一種の Wiki でした) 翻訳の反映も、GitHub の Pull Request を利用して行います。
GitHub のアカウントが必要ですので、持ってない方は取得してください。(https://github.com/)
上記の「原文ページと翻訳ページの URL 対応」や「翻訳リクエストとステータス」を参考に、作業するページを選びます。自分が得意／知識を持つジャンルや、興味を持つページから始めるのがオススメです。最初から長いページを選ぶと挫折してしまう場合もあるので、ペース配分に注意しましょう。
GitHub の mdn/translated-content/files/ja 以下から、対応するファイルを見つけます。 MDN の URL 階層と、GitHub リポジトリーの格納場所の階層とは一致しています。
まだ日本語ページがない場合、mdn/content/en-US 以下から、対応する原文のファイルを見つけます。
既存の訳に、軽微な変更（数文字の誤字訂正など）をする場合は、ブラウザーから直接 github の編集機能を使うのが簡単です。 （必要であればリンクをたどって）目的のファイルまで移動します。
それ以上の編集が必要な場合、新規の訳を追加する場合には、必要なツールをインストールした上で、ローカル環境構築作業をします。 このあたりの説明と ツールの 1 つ yarn へのリンクは、https://github.com/mdn/content#build-the-site にあります。
ローカルで編集するには、Git とテキストエディタがあれば十分ですが、yarn をインストールすることで、ローカルで MDN サイトのテスト実行ができる環境を構築できます。
ブラウザーから編集する場合は、GitHub の機能を使って、プルリクエストまで行えます。
ローカルで編集する場合は、テキストエディタを使ってください。fork したリポジトリーから新しいブランチを作るのがポイントです。
MDN 専用テンプレート（{・・・}）もあるので、そこはいじらないよう注意するといいでしょう。HTML タグの中の ID 属性も、修正しないでください。
とはいえ、英語文を日本語にするのが大事です。細かなタグや属性は、レビューで直してもらえる(こともある)。
GitHub の Pull Request を作成します。
GitHub の mdn/translated-contents ページから Pull Request を作成 (自動でレビュワーが設定される。レビュワーは自分から変えたりできない模様)
スラグとは、URL の中で一番右にある / 以下のフレーズで、システム的には格納場所のディレクトリー名です。従来は、言語ごとに編集することができましたが、Yari では原文に統一することになりました。
たとえば、ページ内のリンクが https://developer.mozilla.org/en-US/Firefox となっていたら、en-US/ の部分を ja/ に置換します。
このようにすると、日本語のページに飛ぶようになります (日本語ページがまだない場合は翻訳のお誘いが表示されます)。
※以前は en-US/ を削除するという方法もありましたが、この場合との違いについては、こちらを参照 してください。
ローカルでファイルを編集している場合、git log コマンドを使ってください。Git の GUI クライアントなども役立つかもしれません。
ブラウザーでの場合は GitHub の History ボタンからコミットログを参照することができます。
Yari （最初期を除いた時期）から markdown 形式のソースファイルを編集する方式に変更になったので、ソースを直接編集します。
MDN サイトの各ページの下部に「View the source on GitHub」というリンクがあるので、他のページのソースをウェブ上からすぐに参照したいときに便利です。
英語版を継承するため、日本語版では一切記載しないルールとなりました。詳細は、翻訳ガイドを参照してください。
PR が承認されてから、一定時間の後に編集結果が公開されます。MDN サーバー側で何かしら動いているはずですが、すぐに公開されるかはタイミング次第です。
公開ページでのフラグは無くなりました。Pull Request を Draft の状態にすることはできます。
一度にページの全部を翻訳しなくても構いません。タイトルと見出しだけとか、テキストを段落ごとに置き換えていくのでもいいです。
Ubuntu など Debian系の Linux では、yarn は yarnpkg パッケージに含まれています。 また、Node.js の 14.x が必要です。Debian リポジトリーのものが古い場合 ──buster 用の node.js は 10.x── は、Node.js 開発元の案内を参考に、新しいものをインストールしてください。これらを含めて、特記事項をこちらにまとめました。)
Debian 系の Linux では、yarn install コマンドの実行前に NODE_PATH の設定が必要なことがあるようです。
リポジトリーに配置する .env ファイルの CONTENT_TRANSLATED_ROOT の値ですが、ホームディレクトリーを $HOME、~ で指定するとエラーになるようです。
ルート(/) からのフルパス指定だと正常動作します。
2022/02/28 追記：以下の対応が不要になるようにマクロが改善されているようです (参考)。
※ページ中のセクション id を利用するマクロ (Page マクロ等) やセクション指定のリンクがうまく行かないときも同じ解決手順になります。
ライブサンプル (EmbedLiveSample) を使う場合、EmbedLiveSample マクロの引数が見出しの HTML 要素の id 属性値と一致する必要があります。Markdown 形式で見出しを記述した場合、id 属性の値は見出しそのものになります (見出しを日本語に翻訳した場合、日本語の id になる)。 EmbedLiveSample マクロの引数に日本語は使えないため、EmbedLiveSample マクロの引数に利用する見出しは、HTML で記述するようにしてください (# の数が そのまま hx の x に対応します)。
<!-- 原文 -->
## Examples
{{EmbedLiveSample("Examples")}}
<!-- 日本語訳 -->
<h2 id="Examples">例</h2>
{{EmbedLiveSample("Examples")}}Kuma システムまでにも同じようなバグがありましたが、Yari システムになった現在、name 属性の付与は不要です。
(参考) Kuma 時代の記事: https://qiita.com/sutara79/items/940948f9ba786cecd985#%E4%B8%8D%E5%85%B7%E5%90%88
- Slack の Mozilla Japan の translation チャンネル
- Mozilla 翻訳グループ – Google グループ
-
Mozilla 翻訳フォーラム(2022 年 1 月終了) - Twitter Mozilla 翻訳ハッシュタグ