次のような方法を通して、どなたでもJekyllサイト翻訳プロジェクト（以下、「本プロジェクト」といいます）に貢献または参加することができます。
- 翻訳ドキュメント上の誤訳やタイプミスの指摘、またはより良い訳への改善提案(修正提案)
- 本家(jekyll/jekyll)のドキュメント追加・更新に追従する翻訳ドキュメントの追加・更新(本家への追従)
- 本プロジェクトの管理業務
以下では、これらの具体的な貢献方法を順に説明します。
翻訳ドキュメント上の誤訳やタイプミスを発見した場合または訳の改善提案をする場合は、次の方法を採ってください。
Issueの作成に際しては、問題箇所を明示し、修正案があればそれをコメントして下さい。できればEdit Requestのラベルを付けて下さい。問題箇所が複数ある場合、それらを一つのIssueにまとめて頂いて結構です。
余力があれば、修正案をPull Requestしてください(事前にIssueを立てなくても結構です)。Pull Requestの具体的な手順については後述します。
本プロジェクトでは、翻訳・修正が必要なファイルがある場合、基本的には、まずはプロジェクト管理者がIssueを立て、それに対する翻訳作業者からの修正Pull Requestを通してこれを消化をしていくというワークフローを採用しています。 Pull Requestの具体的な手順は次の項を参照して下さい。
ここでは、翻訳ドキュメントの追加・更新におけるワークフローを中心に説明します。修正提案をPull Requestで行う場合のワークフローについては、「1. 翻訳対象の選択と宣言」は読み飛ばして下さい。
Issue一覧から希望する翻訳案件を選びます。翻訳が必要とされている案件には、Original UpdatedまたはOriginal Createdというラベルが付いています。
前者は本家更新へ追従するべく既存翻訳ファイルの更新が必要なもの、後者は本家で新規に追加されたファイルに対応する新規翻訳が必要なものを指しています。
Issueには作業対象ファイル(および差分ファイル)へのリンクが貼ってあるので、リンク先で内容を確認して案件を決定してください。
翻訳案件が決まったら、そのIssueに自分が翻訳作業をする旨の宣言をコメントとして残してください(ex.「私が担当します！」)。これは同じ翻訳案件で作業が重複してしまうのを避けるために必要です。
次の手順でローカルに作業環境を構築します。
-
本プロジェクトをフォークして、自身のリポジトリにそのコピーを作ります。
-
フォークしたプロジェクトをローカルの作業環境にクローンします。
git clone [email protected]:/jekyllrb-ja.github.io.git
-
翻訳作業のためのトピックブランチを作成します。
ex. git checkout -b translate-usage
-
必要に応じて、
bundle installを実行し、ローカル環境にプロジェクト関連のgemをインストールします。
作成したトピックブランチで対象ファイルの作成、更新または修正を行って下さい。翻訳上の細かいルールについては、下記「翻訳上のルールについて」を参考にして下さい。 具体的な翻訳作業に当たり注意点が２点ほどあります。
-
本プロジェクトでは本家(jekyll/jekyll)の原文ファイルを管理することはしていません。 代わりに、各翻訳ファイルにおいて対応原文をそのセンテンスごとにHTMLコメントとして挿入することで、原文に対する翻訳文の追従状況を管理しています。 そのため、翻訳作業においては、翻訳の作成・修正に加えて、コメント化された原文の更新も同時に行う必要があります。 新規に翻訳ファイルを作成する場合には、原文のすべて(コードも含めて)をコメント化して挿入する作業が必要になります。本プロジェクトに含まれる
togglateというツールがこの作業を支援します。togglateの使い方については下記「togglateを使った翻訳ファイルの作成」を参照して下さい。 -
翻訳対象ファイルにYAML Front Matterがある場合は、ベースとなっている原文のリビジョンを特定する指定
base_revisionを、最後の項目として挿入しています。base_revision: 0fbdc6944041147c2d21b306751b078860b6603b[refs/heads/master]
この値はIssueでリンクされたdiffファイルの一行目にありますので、古い値をこれに置き換えてください（base_revisionキーが無い場合は挿入してください）。
本プロジェクトでは、翻訳ファイルの本家原文に対する追従状況をシステム的に監視するため、翻訳ファイル内の原文およびbase_revisionを参照しています。そのためこれらの情報が正しく更新されている必要があります。ご理解の程、よろしくお願い致します。
Pull Requestを送る前に、ローカル環境で翻訳ファイルが形式上正しく更新されているか確認する方法について説明します。翻訳ファイルの形式チェックは、最終的にプロジェクトの管理サイドでも行いますので、以下の作業は必須ではありません。 なお、この作業を実行するにはRuby(version2.0以上)および必要なgemが事前にインストールされている必要があります。
翻訳ファイルに挿入した原文が正しく更新されているかを、rakeタスクを使って確認できます。翻訳ファイルが_docsディレクトリ内のextras.mdである場合、プロジェクトのルートで以下を実行します。
rake verify_original_insertion[_docs/extras.md]
このコマンドにより、翻訳ファイルに挿入された原文と本家の対応ファイルの内容の一致が比較されます。翻訳ファイル内の原文が正しく更新されている場合は、次の出力が得られます。
no Diff on _docs/extras.md <-> _docs/extras.md [e57cd00:]
更新が正しくない場合はその差分が出力されますので、その差分が無くなるよう修正して下さい。なお、比較の対象になる本家側のリビジョンは、翻訳ファイルのYAML Front Matterにおけるbase_revisionが使われますが、他のrevisionとの比較を行いたい場合は、第２引数にそれを渡します。
rake verify_original_insertion[_docs/extras.md,master]
ローカル環境に本プロジェクトのサイトを立ち上げることで、翻訳ファイルがブラウザ上で正しく表示されるかを確認できます。以下のコマンドでサーバーが立ち上がります。
bundle exec jekyll serve
ブラウザからhttp://localhost:4000/へアクセスします。
翻訳作業が完了したらコミットし、そのトピックブランチをリモートリポジトリにプッシュしてください。
git add _docs/usage.md
git commit -m 'update translation of usage.md'
git push origin translate-usage
なお、ファイル更新のベースとなった差分ファイル(diff)は削除する必要はありません。
プッシュしたトピックブランチを本プロジェクトに取り込むPull Requestを送って下さい(対象ブランチはmasterです)。
Issueに基づいたPull Requestである場合は、そのdescriptionにfix #<issue番号>を入れて下さい(変更がマージされると自動でIssueがクローズされるようになります)。
本プロジェクトに参加したい方は、Issueにその旨をお知らせ下さい。
本プロジェクトにおける翻訳上のルールについては、まだ暫定的なものしかありませんが、以下を参考にして下さい。
- 文末はです・ます調で終わる
- 可能な限り原文の内容を維持する
- 原文に誤りがある場合(リンクミスなど)は、先に原文にPR送ってみる？
- 翻訳した文章は以下の理由により、適宜改行をはさむ 140文字程度が目安
- レビュー時に読みづらい
- 一行に複数個の指摘をつけるとどこのものか分かりづらい
以下を参考にしてください。
翻訳メモ · jekyllrb-ja/jekyllrb-ja.github.io Wiki
-
下記コマンドにて作業用ファイルを作成します。
togglate create -e=false ./diff/_docs/xxxxx.md > ./_docs/xxxxx.md -
YAML Front-matter部分がコメントアウトされてしまうので、ファイル冒頭にコピペします。
-
作業用ファイル内の[Translation here]部分に訳文を書いていきます。
ローカルで作業をする際の Tips については以下を参考にしてください。