Jekyllドキュメントを翻訳してなんとなくわかってきたもの

あらすじ

Jekyllドキュメントの翻訳リポジトリを作成して約3ヶ月くらいたちまして。

現状報告と、今までの知見のまとめを。

とりあえず自分の中でたまっているものを整理したいのでとりとめもなく書き出していくメソッド。

現状

Jekyll • シンプルで、ブログのような、静的サイト

  • 翻訳当時のリビジョンの Documentation 全翻訳が完了しました!(historyなど一部を除く)
    • 翻訳期間中、本家の更新に追従できていないのでこれから猛追モードに入ります
  • プロジェクトを Organization に昇格させました
    • jekyllrb-ja/jekyllrb-ja.github.io
    • もともとは.br版の翻訳をしている人のリポジトリをお手本にしていたので個人リポジトリで細々とやっていた
    • が、協力していただける方が増えたのもあり Org 化

知見とか

翻訳開始時に悩んでいた事は以下の3点。

それに対しての答えは、現時点で少しずつ見えてきた気がする。

少なくとも、今の自分の中で納得できる答えは見つけられた。

意訳 or 直訳?

原文はどうしよう?

  • これについては「更新の追従」で書く
  • Jekyllrb-jaでは「原文(英語)はコメントアウトで残す」方式を採用した

誰が、どこで、どう管理するか?

  • これに関しては、結局プロジェクトによりけりとしかいえないかな
  • プロジェクトの舵を取る人が「入れよう!」といったら入れればいいし、「分けよう!」といったら分ければよいと思う
    • 「分けよう!」はこのプロジェクト(jekyll)だし、「入れよう!」は progit とか sinatra かな

こんな感じなことが多いのかな〜。まあ、こんな綺麗に二分割はできないけどだいたいの方向性として。

  • 誰が:
    • 「入れよう」メインコミッターの人たち?
    • 「分けよう」翻訳したい人たち
  • どこで:
    • 「入れよう」本家リポジトリ内、あるいはメインコミッターの人が管理しているドキュメント用リポジトリ内
    • 「分けよう」翻訳したい人たちが作った翻訳用リポジトリ
  • どう管理:
    • 「入れよう」基本的に本家(メインコミッターの人)の方針に順守
    • 「分けよう」本家の方針を守りつつ独自(翻訳フローなど)にいける?

更新の追従

更新の追従をするには

本家のドキュメントの更新にどうやってついていくか…今後のモチベージョン(めんどくさくないこと、など)に関わってくるのでできるだけ簡単にしたい。

※ 一番最初の版に関しては、どこかターゲットとなる本家のリビジョンを決めておいて動かさない。あとはターゲットに対して「えいや」で翻訳&コミットしていけばなんとかなると思っている

例えば Sphinx ではリビジョンを覚えておいてそれとぶつける方式で、

  • 翻訳した元のリビジョン番号を特定
  • 最新のリポジトリとマージ

ProGit では本家とぴったりあわせる方式のようです。

  • 本家の更新1コミットにつき訳文更新1コミット

これを解決するために Jekyllrb-ja では @melborne さん謹製の Togglate - GitHub というツールを使わせていただく事に決めました。

Togglateでできること

  • 原文に対して Togglate を使うと、すべての文章がコメントアウトされる
    • 使用前 console Hello!
    • 使用後 ```console こんにちは!

```

こんな感じ <!--original --> でコメントアウトしているのが Togglate でコメントアウトした文章(=原文)。

この形式でコメントアウトする事で以下のようなことができる。

  • Togglateで <!--original --> 内の文章のみを抽出できる(=原文を再構築できる)
    • 「jekyllrb-jaドキュメント内の原文」を再構築することで、「本家の原文」との比較に使用できる(ややこしい)
  • Togglateで出力するjsをhtmlに追加すると「対応する日本語にマウスカーソルを当てると原文がポップアップする」ことができる
    • 後述する「原文チラ見したい問題」を解決できる

更新の追従をする際に、更新された箇所の日本語文とコメントアウトした原文両方を更新しなければならないのがちょいめんどうだけど、上記 2 点を解消できる点で有用だと思っている。あわせて日本語文と原文の更新も自動化できれば…。

…この辺はまだまだ試行錯誤なので、ちょっとうまくまとまらず。また進捗があったら改めてまとめる。

原文チラ見したい問題

また、別の問題として「日本語読んでいる途中で原文チラ見したい」というものも人によってはあるかも。

これが意外とめんどくさくて、

  • 日本語サイトをブラウザで開きつつ
  • 原文のサイトかリポジトリを開き
  • 対応するファイル or Webページを開き
  • 対応する文章を探し
  • 並べて比較してみる

という手順を踏む必要がある。

これをTogglateは、原文を <!--original --> でコメントアウトしておいて、ブラウザからポップアップすると表示できるようになっている。

そのため、上記のフローが

  • 気になるところにカーソルをあわせる

で済むようになる。こんな感じ。

img

おまけ

  • 他の人のプロジェクトに Issue を追加したりすることに抵抗が減った

良い傾向。

関連記事(この記事の初版より古い記事はリンクがグレーで表示されます)

  1. 2014/07/26 [Jekyll] [Translate] jekyllrb-ja キックオフを実施しました
  2. 2014/11/30 [Jekyll] kawasaki.rb #018 でJekyllドキュメント翻訳のLTをしてきた
  3. 2014/04/01 [Ruby] [Jekyll] [イベント] kawasaki.rb #010 で発表してきました #kwskrb
  4. 2014/03/13 [Jekyll] [GitHub] Jekyllドキュメントの日本語翻訳リポジトリ「jekyllrb.com.jp」を作成しました
  5. 2014/01/28 [Jekyll] [GitHub] [Ruby] Jekyllプロジェクトへpull requestを行う手順(したとは言っていない)
  6. 2015/08/06 [Jekyll] [Liquid] Jekyllで出力するタグをソートする 解決編
  7. 2015/03/14 [Jekyll] Jekyllがデフォルトでは外部から繋がらなくなってたよ
  8. 2013/11/25 [Jekyll] Jekyllのプラグイン作成で複数ファイルにまたがったタグをどう扱えばいいのかわからない話
  9. 2013/09/07 [Ruby] [Git] [Jekyll] Jekyllバージョンアップの際に思いのほか手こずった話 てっく煮さん製プラグインの更新に追従したい編
  10. 2013/08/07 [Ruby] [Jekyll] [Git] Jekyllバージョンアップの際に思いのほか手こずった話 Jekyll Bootstrapの更新に追従したい編
  11. 2013/05/27 [Jekyll] [Ruby] Jekyll@GitHub Pagesの運用形態を変えたのでAnalyticsの設定が効かなくなっていた
  12. 2013/05/23 [Jekyll] [Liquid] [Ruby] 記事の目次を出力するJekyllプラグインの改良
  13. 2013/05/21 [Jekyll] [Git] GitHub PagesでJekyllプラグインを使えるようにするには…
  14. 2013/04/11 [Ruby] [Jekyll] Jekyllのバージョンを 0.12.0 にあげた
  15. 2012/11/12 [Ruby] [Jekyll] はてなダイアリーのエントリをJekyllへ移行する