CONTRIBUTING.md

κeenさんのコントリビューションガイドをベースとしたものです。

新たに翻訳する

• 翻訳開始時に draft でプルリクエストを上げる（タイトルとかで1行くらいコミットしておく）
  • それで排他制御の意味になる
  • また、進捗の可視化になったり、忙しくなって途中で止めた時に回収出来たりする
  • 完成したら draft を外して中の人にレビューをお願いする
• 基本的には1ファイル単位で翻訳/PRする（1ファイルが大きくて負担がきつい時は応相談）
• プルリクの指針、翻訳時の指針に従う
• プルリクを上げた直後にCIが走り、HTMLが自動生成される。またプルリクの元になるブランチへコミットした時もCIが走る。。

既存の翻訳を修正する

修正してプルリクエストを投げる。

• typoや軽い言い回しの修正などは気軽に投げると気軽にマージされる
• 訳語の修正などは最初の訳の時点で既に議論されている可能性があるためある程度チェックされる（チェックした旨とリンクがあるとレビューが速くなります）

プルリクの指針

• プルリクを上げた時点でライセンス条項に同意したものとする
  • 機械翻訳などライセンスに違反する訳をプルリクエストしてはならない
• コミットするファイルは翻訳文書だけで、生成されたHTMLファイルはコミットしない
• その文書に含まれる用語のglossaryも翻訳する
• 新たな組込み用語を訳した時は対訳表(TranslationTableEmbedded.md)も更新する
• 翻訳を終えた後に最低でも1度全体を眺めて推敲する

翻訳時の指針

書式類

• 英文をコメントアウトし、その直下に空行を1行挿入し、和訳を書く
  • コメントの直下に空行を入れずにMarkdown書式の文章を書くと、mdbookでは全てのMarkdownレンダリングが無効化されるため
• 1パラグラフ単位で翻訳する
• ただし、rustのコードブロック（バッククォート3つで始まる別行立てのもの）中のコメントについては行頭が# //になるようにして英文のコメントを含むコードをコメントアウトし、直下にコメントを翻訳したものを書く（See Issue #13）。
  • これは「rustの」コードブロックのみで、他のコードブロック、例えばtextなどでは#でコメントアウト出来ないので原文を削除して翻訳文書を書き入れる。
• クォート(')やダブルクォート(")は鉤括弧(「」)にする
• 句読点には、。を、感嘆符は全角のエクスクラメーションマーク(！)を、疑問符は全角のクエスチョンマーク(？)を用いる。
  • これらの記号の後にスペースは入れない（See Issue #82）。
• 括弧は全角の（と）を使用する。
  • ただし、「日本語(original English)」のように原語を示す場合に限り、半角の(と)を使用する（See Issue #82）。
• どんなに1行が長くなっても日本語の文の途中で改行しない。レンダリングで余計な空白が入ってしまう。句点(。)、最悪でも読点(、)の後で改行する。
• 訳注を入れる際はインラインなら（訳注: ...）のようにし、別行なら > 訳注: ... のように囲み形式にする

日本語

• 敬体を基本とする
• 用語の訳は対訳表および組込み対訳表に従う
• 用語や厳密な意味論を話してる部分以外はある程度は意訳でよい
• むしろ変に原文に忠実で、日本語として読みづらいよりも意味が伝わって日本語として分かりやすい方がいい。
  • ただし元の英文の意味と異なる場合（誤訳の場合）は修正が入る
• 継続用法の関係代名詞やコロン(:)、セミコロン(;)など日本語と対応取りづらい文は無理に1文に詰めず、2文に分けてもよい。 また、継続用法の関係代名詞でも限定修飾のように訳してもよい（日本語でどちらの意味にも読み取れるため。英語のテストでないので読み手の好意的解釈をあてにしてよい。）
• 英語だとit, thatなどの指示語が多用されるが日本語だと繰り返した方が自然なことが多いので無理に指示語を使わずに自然な方を使う
• 逆にyou, your, we, ourなどの英語の文法上仕方なく出てくる人称代名詞は日本語には訳さない方が自然なことが多いので無理に訳に出さない。 特に、一般論を語る時のyouは 訳してはならない 参考 【雑談】"あなた"と訳さない"you" ~ einzelzelle