ソースコード中のコメントは、英語の行を残して日本語を併記すべきなのか
Closed this issue · 3 comments
CONTIBUTING.md の「日本語のフォーマット」によると、ソースコード中の英語コメントは消さずに、日本語コメントを新しい行に書くように指定されています。また、これは mdbook-trancheck の仕様であるとも説明されています。おそらく、コード中の英語の行だけ（マークダウンの意味で）コメントアウトして日本語を併記する、ということができないからだと思います。
一方、これには別の解決策もあります。それは、コードブロック全体をコメントアウトして、それを丸々コピーし、英語コメント部分を日本語に書き換えるという方法です。これは、コメントが完全にローカライズされるという一方、Markdown コードの量が2倍になるという欠点はあるかもしれません。
後者でなく前者が採用されている理由は、後者に記載した欠点によるものでしょうか？
関連コメント（私は rust-lang-ja の別のリポジトリの翻訳中に第二の方法を取り、以下の指摘を受けました）： rust-lang-ja/edition-guide#53 (comment)
mdbook-transcheck の作者です。
もともとこのツールのコンセプトは「原文が継続的にアップデートされるときに、和訳の追従コストをできるだけ下げる」というものです。そのため訳す必要のない部分はできるだけ自動で更新できるように現在のルールにしています。
コードブロック全体を丸々コピーした場合のデメリットとしては、原文のコードブロックが更新されたときに、それを和訳側に反映するのは和訳者の作業になってしまい、見落としや反映ミスが発生することが考えられます。
もちろん和訳に協力していただける方がもっと増えて、細かいところまでチェックができるだけのリソースがあれば見栄えを優先することもできると思いますが、今のところは多少不格好でも少ないリソースで継続的に回せるようにした方がいいのかな、と思っています。
ご返答ありがとうございます。承知いたしました。