CONTRIBUTING.ja.md

貢献

本書で何かしら改善になるものを見付けたらPRやイシューを開いてください。

フィードバックに感謝します。

章のテキストを編集する

テキストの変更をローカルで見てみるには、mdbookをインストールし、以下のコマンドをリポジトリのルートで走らせます。

mdbook serve -o

readmeファイルへの変更毎に描画されたwebページが自動的に再読み込みされます。

日本語訳について

生成された日本語訳のドキュメントはtext-ja/*にあります。

以降は貢献者と維持管理者を対象とする内容です。

貢献者へ

日本語訳を改善するパッチを歓迎します。 翻訳内容そのものはもちろん、後述の自動検証の整備について改善の余地があります。 改善に協力される際は以降の内容に注意してください。

必要なものはpo4a、POファイルを編集するテキストエディタ、Node.jsです。 またNode.jsに関しては、npm iとすることにより、使用する依存関係をインストールしておきます。 なお、GNU Guixで作業されている方はguix shellとすれば環境が整います。

po4aは日本語訳の管理用に採用しています。 そのため翻訳の変更についてはpo/ja.poファイルを編集してください。 生成物（Markdownファイル）をそのまま編集してはなりません。 npm run translateとすれば翻訳が更新されます。 なお、po4aはバージョンによってMarkdownの字句解析が異なる場合があります。 translate/.po4a-versionに記載されているものと可能な限り近いバージョンを使用してください。

翻訳の際にはtranslation/terms.txtに挙げた簡単な用語集のメモが役に立つかもしれません。 追加や変更の提案をいただいても構いません。

生成物に対しての自動的な検証を幾つか導入しています。 npm run lintで検証します。

翻訳文はtextlintを使います。 npm run lint:textで検証します。 いくつかの規則は.textlintrc.jsonで無効にしています。 例えばpreset-jtf-style/1.1.3.箇条書きは、コードブロックを含む場合に文末の句読点を揃えることが難しいため無効にしています。 npx textlint --fix <ファイルパス>で生成物に対する自動修正を行います。 ただし修正されるのは生成物なので、POファイルの対応箇所に反映する必要があります。

生成物のMarkdownはmarkdownlintを使います。 npm run lint:mdで検証します。 こちらも幾つかの規則を無効にしていますが、原文でも無効にしているもの以外は可能な限り有効にできるようにしたいと考えています。

対応いただいた翻訳の編集内容について、著作権表示と利用許諾をご確認ください。 POファイルを編集した場合、著作権表示の追加ないし年度の更新をお願いします。 また、いただいたパッチの利用許諾は原文のものに準ずるものとします。 翻訳を作成する際に機械翻訳を援用しても構いませんが、生成された翻訳の権利関係に注意してください。

コミットメッセージは原文のリポジトリで採用されている形式に沿います。 特に翻訳に関するコミットタイトルは[ translate ] ...として原文の変更と区別します。 作業ブランチを切って細かくコミットし、パッチの作成時にgit rebaseで意味のある単位に整理することをお勧めします。

[ translate ] Some descriptive commit title

* [ some ] smaller change

* [ other ] smaller change

上記が守られていないパッチについてはこちらでコミット内容を変更することがあります。

維持管理者へ

本日本語訳は、比較的容易に原文の変更へ追従できるような仕組みが整備されています。 以下の手順により最新版へ更新します。 なお、3、4番目の過程をする時間の余裕がない場合は、1、2までしておいてjaブランチにプッシュしておけば大丈夫です。 原文に更新のあった箇所は英語に戻ってしまいますが、不正確な内容が含まれない状態を保てます。 別の人が3、4番目の過程で翻訳の追従をすることに期待しましょう。

1. 原文のリポジトリのmasterブランチをjaブランチにマージする。
2. POファイルおよび翻訳生成物を更新する。
3. POファイルを編集し、未翻訳の箇所、ファジー項目の解決を行う。
4. 翻訳生成物を更新する。

まず、原文のリポジトリのmasterブランチをjaブランチにマージします。 本リポジトリのmasterブランチは原文のリポジトリのmasterブランチと同一です。 そのため、以下の過程を経るとよいでしょう。

1. 原文のリポジトリのmasterブランチを本リポジトリのmasterブランチにプルする。
2. 本リポジトリのmasterブランチを本リポジトリのjaブランチにマージする。

jaブランチへのマージの際に競合が発生する可能性があります。 translationディレクトリ以下はmasterブランチにない想定なので、原則translationディレクトリ外での発生が見込まれます。 よしなに更新しましょう。 競合の発生が顕著な場合はtranslationディレクトリ外のファイルもtranslationファイル内に移動できないか検討します。 なお、以前は原文のリポジトリのmasterブランチをjaブランチにマージする工程でリベースするようにしていました。 リベースの方がコミット履歴がすっきりするのですが、既にクローンしたリポジトリからプルしたときに問題が起こりやすくなります。 またリポジトリがクローンされる機会が増えているようなので、マージするようにしました。

次にPOファイルおよび翻訳生成物を更新します。 これはnpm run translateとするだけです。 これにより自動的に対応するPOファイルと翻訳生成物が更新されます。 翻訳生成物については、原文で更新があった箇所は英語に戻ります。 そのため最新の内容でない日本語が翻訳生成物に残り続けるということがありません。

更にPOファイルを編集し、未翻訳の箇所、ファジー項目の解決を行います。 POファイルにおいてfuzzyの印が付いているところと未翻訳の項目の翻訳を行います。 前者については既存の翻訳から似ていそうなものを雛形として自動的に挿入してくれることがあります。 そちらを参考に翻訳しましょう。

最後に翻訳生成物を更新します。 これもnpm run translateとするだけです。

詳細はpo4aのドキュメントも参照してください。