2018年以降の記事はGitHub Pagesに移行しました

Jekyllドキュメントの日本語翻訳リポジトリ「jekyllrb.com.jp」を作成しました

あらすじ

Jekyll プロジェクトに対していろいろやった。

  1. Jekyll プロジェクトのリポジトリルートにある README.markdownCONTRIBUTING.markdown を日本語訳してプルリクした!
    • 人生初のプルリクエストをささげ、マージしてもらえた。やった!
    • いきなりカットインしてきた PR に対してすごく親身に対応してもらえた
  2. あわせて Jekyllドキュメントの日本語翻訳リポジトリ を作成した!

所感

今回のやり取りを通じて、ドキュメントに対して以下のような観点で考える力が足りないと感じた。

まだ明確な答えは出ていないので、これからドキュメントを育てつつ答えを探していきたい。

  1. 意訳 or 直訳?
    • 若干意味が通らない文章になってもいいから、出てくる単語を全て愚直に訳す?
    • 経験(実際にライブラリを使うと、「このコマンドはこう動くから、この文章ではこう言いたいのだろう」的なニュアンスはわかったりする)をもとに意訳する?
      • 前者だと文章がごちゃっとなりそうで、後者だと大事な表現を落としてしまう事が多そう
      • 他プロジェクトなどで翻訳された文章を読んでいると、前者が多いような気がする…
      • もちろんおそろしくカッコよくて読みやすい文章に訳せるならば、それに越したことはない
  2. 原文はどうしよう?
    • 原文(英語)の扱い
      • 残す?残さない?また、残す場合はコメントアウト
      • 文章を比較する場合や本家の更新に追従する場合、原文がないとわけわからなくならない? diff とかとるのに
    • 本家への追従の仕方
      • 本家のドキュメントにどうやってついていく?
  3. 誰が、どこで、どう管理するか?
    • Author と Committer が読めない(管理できない)ブツはどのように管理すべきなのか
      • 本家のリポジトリjp とか en みたいにディレクトリ切ってそこで管理していく
      • 翻訳したドキュメントは、その言語を取り扱える別の人が所有し、本家はそこをフォークしておく

この辺、他のプロジェクトではどうやっているんだろう。

プルリクに至るまでの思考と行動の流れ

以下、おまけ。

いかにして Jekyll にプルリクするに至ったかの経緯。

  1. 2014 年になったしなんかしたいな(うっすら)
  2. 今年は少しドキュメントの原文を読む機会を増やしてみようか
  3. 何読もう
  4. Ruby の Gem のドキュメントか何かが良いかな
  5. 1 年くらい Jekyll でブログ書くようにしてるし、いろいろ内部のことも知りたいし Jekyll のドキュメントを読んでみよう!
  1. 知らないオプションとか発見したいから configuration ページあたりから読んでみようか…
  2. 待てよ、せっかく読むんなら翻訳しながら読んでみる?
  3. 翻訳するんならコントリビュートしてみたいな
  4. 既にやってる人は……いないっぽい
  5. とって食われるわけではないはずなので、どうせなら投げてみよう!ダメならリジェクトされればいいか
  1. コントリビュートのやり方は CONTRIBUTING.markdown に書いてあったな…
  2. ならば CONTRIBUTING.markdown から翻訳しよう
  3. よくみたら同じ階層に README.markdown もあるからこれも併せて翻訳してみよう
  4. 牛歩で翻訳…
  1. 翻訳できた
  2. 自分で翻訳した CONTRIBUTING.markdown を読みながら Jekyll へのコントリビュートのやり方を確認
  3. 「文章の更新」については書いてるけど、新規文書の追加の仕方は書いてないな…
  4. ええいままよで、わからないことは質問してみよう Translated of README.markdown and CONTRIBUTING.markdown into Japanese. by gosyujin · Pull Request #2081 · jekyll/jekyll · GitHub
  5. マージされた!

日本語翻訳用リポジトリを作成するまでのやりとり(JekyllのPR上)

次に、 Jekyll ドキュメントの翻訳リポジトリを作るに至ったかの経緯。

上記のプルリクエスト が close された後もやりとりを…。

  • docs 下の翻訳もしたいが、どこにどういうファイル名で置けば良い?

  • 我々は日本語の読み書きができないから確認ができない
  • メンテナンス性も下がるから、できるだけ(オリジナル以外の)ドキュメントを管理したくない
  • @matheus が自分のリポジトリを作ってやってる から参考にしてみて」

とのこと。言ってることはごもっとも。どう管理するのが一番良いんだろう?

結局、翻訳サイトは(上記の jekyllrb.com.br も含めて) Jekyll 本家からフォークして参照するのが一番良いのではないかという意見もあり。

やるならリポジトリを作ってそこでやってみたらどうかと助言をいただく。

というわけで始動させてみました!よろしくお願いします!