[ruby-list:34095] Re: localized document

jihg です。

まったく見当違いかもしれないけど、不思議に思うことがあるので書いて見ま
す。

From: HIDAKA Takahiro [mailto:[e-mail]] 
Subject: [ruby-list:34093] Re: localized document


＞　ひだかです。
＞
＞　本題というかコメントの話ですが、ファイルを分割するとして、
＞
＞1. ソース(foo.rb)からコメントだけを抜き出して foo.rdoc.ja を作る。
＞2. foo.rdoc.ja に日本語のコメントを書くときは対訳形式で書く。もとのコ
メントは
＞   一切変更しないで残して、対訳部分は # 以外の別の記号をつける
＞
＞   例)
＞	# This library is...
＞	% このライブラリは...
＞	# This function is...
＞	% この関数は...
＞
＞3. RDoc では、両方のファイルを読んで、一致するコメントの対訳部分だけを
＞   置き換える。
＞4. 一致しないコメントがあれば警告を出力する
＞     - 翻訳もれや元ドキュメントの更新をチェックできる。
＞     - foo.rb → foo.rdoc.ja の同期スクリプトがいるかも。。
＞5. もともと日本語で書いていて、英語コメントをつけたいときのために、
＞   foo.rb(日本語) と foo.rdoc.en を用意すれば入れ替えることのできる
＞   ツールも用意する?


※言語と表記すると混乱を生みそうなので"言葉"と書きます。意味は同じです。

正しく解釈できてると思うけど、一応、僕の理解を。

◆作成者側
  1.僕は日本語しか分からないので、コメントは日本語で書きたい。
  2.で、作成者(僕）と利用者（誰か）の理解できる言葉が違うとき、利用者が
理解しやすいように、そっちの言葉のコメントも用意したい。
  3.そうするためにはどうしたらいいか？
  4.コメント部分を別ファイルに抜き出す。
  5.拡張子は、例えば英語なら、元ファイル名.rdoc.en
  6.ファイルは対訳形式で、行ごとに原文と訳文を併記する。
  7.ひとまとめにして配布する。

◆利用者側
  1.ファイルを RDoc に渡すときスイッチをつける。たとえば英語なら -en と
か。
   2.RDoc はファイル名.rdoc.en を探す。
  3.あればそれで置き換える。
  4.原文をキーにして訳文で置換する。
  5.一致するキーがないときは警告する。

で、思うんだけど、元のスクリプトのコメントを直接置き換えてみるのはどう？
ソースを読む人の助けになりそうなんだけど。

※問題は、パッチを提供する場合。ちょっと面倒。


＞このくらいやると使いやすくなるでしょうか。まだまるっきり妄想ですが。
＞でも、こんなに複雑なら、最初から一体化して書いたほうがましなのかな。

対応する言葉が多くなるとコメントが肥大化する。そうなると、英語に統一すれ
ばいいってはなしが出てくる。併記する必要ある？ って話。

「自前でファイルを用意すれば、対応してない言葉でもメニューなどの表示を変
えられます」

って、あるソフトの説明に書いてたんだけど、フォントを変えられなくて、悲し
い思いをしたことがあります。便利なんだけど、EU 圏のことしか考えてないっ
ていうのがねえ。

RDoc はフォントは考慮しないだろうから、こういうことができるし。一本化す
るより別ファイルにしたほうが、より多くの言葉に対応できていいんじゃな
い？。