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

あらすじ

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

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

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

現状

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

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

知見とか

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

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

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

意訳 or 直訳？

色々な人の意見をもとに「日本人が読みやすいように意訳していく」のが良いではという結論に至った
結局のところ翻訳した文書は誰が読むかを考えると、自分(日本人)だろう、という話が一番腑に落ちたので…以下、感銘を受けた記事など
なんという Python 率。「ドキュメント翻訳なんとか」でググると Python 界隈の方の活動がすごい引っかかるのはそれだけ盛んであるということなんだろうか(Ruby 方面へのアンテナの感度が低いだけとも思う)
~~直訳でもフツーに間違うから~~固い文より、読みやすい文の方がよいのではないか(誤訳しない努力はする)

原文はどうしよう？

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

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

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

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

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

更新の追従

更新の追従をするには

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

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

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

翻訳した元のリビジョン番号を特定

最新のリポジトリとマージ

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

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

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

Togglateでできること

原文に対して Togglate を使うと、すべての文章がコメントアウトされる
- 使用前

Hello!

使用後

こんにちは！

<!--original
Hello!
-->

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

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

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

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

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

原文チラ見したい問題

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

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

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

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

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

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

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

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

おまけ

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

良い傾向。

kk_Atakaの日記

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