Skip to content

Get started with translation of Mozilla documentations

Jump to bottom Edit New page
Takeshi HAMASAKI edited this page Apr 17, 2021 · 32 revisions

MDN Web Docs ドキュメント翻訳の始め方

これは、Google、Microsoft、Mozilla が共同でメンテナンスしている Web 開発者向けのドキュメントサイト、MDN Web Docs プロジェクトの開発ドキュメントを翻訳する作業ステップを簡単にまとめたものです。このページのオリジナルは、2015-03-25に行われた MDN 翻訳ミートアップで、marさんが解説してくれた内容を元に、catchさんが整理したものです（元ページ）。MDN の現状に合わせて、適宜更新を加えています。

ミートアップのスライド経由でこのページにいらっしゃった方は「作業ステップ」の内容はすでにスライドで説明済みかと思いますので、「作業上のヒント」や「FAQ」 などのセクションを読むと役立つかもしれません。

翻訳対象

MDN 日本語版では、Web 開発者向けドキュメントである MDN Web Docs の日本語訳を作成しています。

原文ページと翻訳ページのURL対応

各ドキュメントは、英語ページは en-US、日本語ページは ja の階層に配置します。

(例)
原文　: https://developer.mozilla.org/en-US/Firefox
日本語: https://developer.mozilla.org/ja/Firefox

各ページのLANGUAGE(言語)アイコン(右上)でも、翻訳済みの言語が確認できます。

翻訳リクエストとステータス

まだ未翻訳のドキュメントがあった場合、翻訳のリクエストと作業の進捗状況は、以下で確認できます。

作業ステップ

MDN Web Docs の内容は、github で管理されています。（2020年の終わりごろまでは、一種の Wiki でした） 翻訳の反映も、github の Pull Request を利用して行います。

Step1. github のアカウントを作ってサインインする

GitHub のアカウントが必要ですので、持ってない方は取得してください。 (https://github.com/)

GitHub のアカウントをすでに持っている人はそのアカウントを使えます。 サインインしてください。

なお、MDNそのもの にも github のアカウントでサインインできます。（貢献者としてのプロファイルを登録できます。以前は、編集のために MDN へのサインインが必須でした。）

Step2. 翻訳するページを選ぶ

上記の「原文ページと翻訳ページのURL対応」や「翻訳リクエストとステータス」を参考に、作業するページを選びます。自分が得意／知識を持つジャンルや、興味を持つページから始めるのがオススメです。最初から長いページを選ぶと挫折してしまう場合もあるので、ペース配分に注意しましょう。

github の mdn/translated-content/files/ja 以下から、対応するファイルを見つけます。 MDN の URL 階層と、github リポジトリの格納場所の階層とは一致しています。

まだ日本語ページがない場合、mdn/content/en-US 以下から、対応する原文のファイルを見つけます。 → mdn/translated-content 側に追加する手順が必要 (ToDo)

Step pre-3. ページの編集準備　（ToDo 要編集）

既存の訳に、軽微な変更（数文字の誤字訂正など）をする場合は、ブラウザーから直接 github の編集機能を使うのが簡単です。 （必要であればリンクをたどって）目的のファイルまで移動します。

それ以上の編集が必要な場合、新規の訳を追加する場合には、必要なツールをインストールした上で、下記にあるような準備作業をします。 このあたりの説明と ツールの1つ yarn へのリンクは、 https://github.com/mdn/content#setup にあります。 （Debian系の Linux では、 yarn は yarnpkg パッケージに含まれています。 また、Node.js の 14.x が必要なので、Debianリポジトリのものが古い場合 ──buster 用の node.js は 10.x── は、Node.js 開発元の案内を参考に、新しいものをインストールしてください。）

yarn のインストールが済んだら、以下の手順で、ローカルでMDNサイトのテスト実行ができる環境を構築します。

- GitHubブラウザ上でmdn/contentリポジトリをforkする。
- Githubブラウザ上でmdn/translated-contentリポジトリをforkする。
- forkしたレポジトリをローカルへ`git clone`する。 （mdn/content が約300MB、 mdn/translated-contentが約650MBです。 2021年4月時点）
- クローンしたcontentレポジトリへ移動して`yarn install`を実行する。 （Debian系の Linux では、 `yarnpkg install` コマンドの実行前に NODE_PATH の設定が必要なことがある。）
- ローカルのcontentレポジトリに`.env`ファイルを追加してtranslated-contentリポジトリ内のfilesディレクトリを環境変数CONTENT_TRANSLATED_ROOTに設定する。
- yarn startを実行する。
- ブラウザでlocalhost:5000へアクセスする。
	- ローカルでMDN Web Docsのテスト環境が動作する。
	- localhost:5000/ja/<ページ>で日本語ページを確認できる。

ローカルでMDNのサイトをテスト実行できるようになりました。

Step3. ページの編集　（ToDo 要編集）

あとはtranslated-content/files以下の目的のファイルを更新、テスト実行して正常動作と見た目を確認、OKならfork元へプルリクエストを出すということですね。
forkからのpull requestの流れはなんとなく以下のサイトを確認中です。
http://kik.xii.jp/archives/179contentリポジトリに配置する`.env`ファイルのCONTENT_TRANSLATED_ROOTの値ですが、ホームディレクトリを$HOME、~で指定するとエラーでした。
ルート(/)からのフルパス指定だと正常動作しました。

Step4. 実際に翻訳する （ToDo 要編集）

http://localhost:5000/ja　にアクセスして翻訳/修正したいページまで行く

該当するファイルをエディタで開くか、ページ上部のOpen in your editor でエディタを開くか Quick-edit で編集する（と、localhostに反映されるので確認する）
forkしたリポジトリの作業ブランチにコミット->pushする

基本的に HTML で記述されています。

（ToDo このあたりは Yari でも該当？） MDN 専用テンプレート（{・・・}）もあるので、そこはいじらないよう注意するといいでしょう。HTML タグの中の ID 属性も、修正しないでください。

とはいえ、英語文を日本語にするのが大事です。細かなタグや属性は、レビューで直してもらえる(こともある)。

Step5. レビューを依頼する(必須　以前は任意でした)

Github の Pull Request を作成します。

Githubのmdn/translated-contents ページからPullRequestを生成（自動でレビュワーが設定される。レビュワーは自分から変えたりできない模様）

作業上のヒント

URL スラグ：原文のままにする

スラグとは、URLの中で一番右にある / 以下のフレーズで、システム的には格納場所のディレクトリ名です。従来は、言語ごとに編集することができましたが、Yari では原文に統一することになりました。

リンクの修正

たとえば、ページ内のリンクが https://developer.mozilla.org/en-US/Firefox となっていたら、en-US/ の部分を ja/ に置換します。

このようにすると、日本語のページに飛ぶようになります（日本語ページがまだない場合は翻訳のお誘いが表示されます）。 ※以前は en-US/ を削除するという方法もありましたが、この場合との違いについては、こちらを参照してください。

作業履歴の確認（ToDo github による方法に書き換え？）

“編集”ボタンの右の歯車のアイコンをクリックすると、詳細メニューが開きます。

ここで”履歴”を選択すると、そのページの編集履歴を見ることができます。

ソースの表示（ToDo github による方法に書き換え？基本HTMLを直接編集する方法しかない？）

「ソースの表示」ボタンをクリックすると、Wikiのソースを表示して、直接編集できるようになります。

ソースを直接編集する場合は、タグの閉じ忘れに注意してください。閉じ忘れは自動補完されますが、不完全な場合があるため、構造的によろしくない感じになってしまうことがあります。

ページ内容のタグ（ToDo github による方法に書き換え、タグの扱いはリポジトリの中でどうなっている？）

ページの末尾に、ページの種類ごとにタグを付与することができます。とりあえず、英語ページと同じタグを割り当てるといいでしょう。

タグが複数ある場合は、カンマで区切ります。

たとえ記事が英語版の翻訳であったとしても、すべてのページに少なくともひとつのタグが付ける必要があります。

検索結果のフィルタリングや貢献者同士の規約として使われているタグは翻訳されるべきではありません。より詳しいルールや使い方などは、How to properly tag pages をご参照ください。なお、既存のタグで記事の中身を表せない場合には、新たなタグを自由に作ることができます。

編集結果の公開

PRが承認されてから、（ToDo 定期的な cron による更新？？）編集結果が公開されます。

編集状態のフラグ

以下のフラグで、読者にページの状態を伝えることができます。

  • Localizationフラグ：作業中

Reviewフラグは、次のものがあります。

始める前に、とりあえず保存すると、他の人が編集できないようにロックされる。※編集状態フラグを立てても、編集ロックされる仕様はありません。

気にせず翻訳を始めるのが吉です。

翻訳のスピード

一度にページの全部を翻訳しなくても構いません。タイトルと見出しだけとか、テキストを段落ごとに置き換えていくのでもいいです。

FAQ

MDN のバグもしくは制限　（ToDo これは yari でも継続して存在する？）

ライブサンプル機能を使ったサンプルコードでは id 属性値がテキストコンテンツで置き換えられてしまう

※ページ中のセクション id を利用するマクロ（Page マクロ等）やセクション指定のリンクがうまく行かないときも同じ解決手順になります。

ライブサンプル (EmbedLiveSample) を使う場合、要素の中のテキストコンテンツと EmbedLiveSample ライブサンプルの引数が一致する必要があります。また、id 属性には何を付けていても保存時にテキストコンテンツの値で上書きされてしまいます。

これは、name 属性をつけることで防げます。

<!-- 原文 -->
<h2 id="Examples">Examples</h2> <!-- ライブサンプルに使われる見出し -->
{{EmbedLiveSample("Examples")}}

<!-- 日本語訳 -->
<h2 id="Examples" name="Examples">例</h2> <!-- 必ず name 属性を追加する -->
{{EmbedLiveSample("Examples")}}

詳しくはこちらの記事をご覧下さい: https://qiita.com/sutara79/items/940948f9ba786cecd985#%E4%B8%8D%E5%85%B7%E5%90%88

関連情報

作業用コミュニティ

資料集

MDNのドキュメント作成/翻訳資料

Add a custom footer

MDN 翻訳の始め方
SUMO の翻訳ガイド
翻訳リクエスト
MDN 日本語版レビューについて

翻訳 Google Groups
Medium について

L10N ガイドライン
表記ガイドライン
Mozilla 用語集
Firefox OS 用語集

Mozilla Japan コミュニティポータル
著作権とライセンスについて

Clone this wiki locally