Yii 2 のドキュメントとその日本語翻訳はいくつかのレポジトリに分散して格納されています。 この yiijan organization においては、それらのレポジトリを本家からフォークしてホストしています。
- フレームワーク本体
- yii2
- フレームワークのメッセージ ... framework/messages/ja/yii.php
- ユーザ・ガイド ... docs/guide-ja/*
- 開発者ガイド ... docs/internals-ja/*
- yii2
- アプリケーション・テンプレート
- 公式エクステンション
この yii2-ja レポジトリは、これらの日本語翻訳全体に関わる問題を扱います。
翻訳作業については、原則として、次のワーク・フローを想定しています。
まずは、yiijan organization に参加してください。 オーナーの誰かにリクエストしてくだされば、invitation を送ります。 資格を求めたりも、義務を課したりもしませんので、お気軽にご参加下さい。
対象となるレポジトリのフォークをあなたの開発環境にクローンします。 このとき、選択肢として、あなた自身のフォークを github 上に作成してそれをクローンする方法と、yiijan のフォークをクローンする方法があります。
git clone [email protected]:YOUR-GITHUB-USERNAME/yii2.git
または、
git clone [email protected]:yiijan/yii2.git
どちらの場合も、本家のレポジトリと yiijan のレポジトリをリモートとして追加する必要があります。
- あなた自身のフォークを作成してクローンする場合
- 本家のレポジトリを "upstream" という名前でリモートとして追加する
- yiijan のレポジトリを "yiijan" という名前でリモートとして追加する
- yiijan のフォークをクローンする場合
- 本家のレポジトリを "upstream" という名前でリモートとして追加する
- yiijan のレポジトリは "origin" という名前で既にリモートとして追加されている
どちらの方法によっても構いません。
yiijan のフォークを使う場合は、ここまでの準備を clone-yiijan-repos で行うことができます。
ひとまとまりの比較的大きな作業をするときは、新規 issue で作業の開始を宣言します。 ただし、タイポの修正など、小さな作業については、issue を立てる必要はありません。
git fetch upstream
これは非常に重要です。 なぜなら、master ブランチを使うと、そのレポジトリからは一つ以上のプル・リクエストを送信することが出来なくなるからです。
独立した修正や変更は、各々、それ自身のブランチに入れるべきです。 ブランチの名前は説明的なものにしてください。 例えば、
git checkout upstream/master
git checkout -b docs-ja-xyz-translation
作成した新しいブランチで翻訳の作業をします。
以下のコマンドを使って、コミットしたいファイルや変更をステージング・エリアに追加します。
git add path/to/my/file.md
説明的なコミット・メッセージを付けて修正をコミットしてください。
このとき、余計な自動テストをスキップするために、コミット・メッセージに [ci skip] を含めることが推奨されます。
git commit -m "docs-ja-xyz.md typo fixed [ci skip]"
git pull upstream master
このステップは、プル・リクエストを出す前にあなたのブランチが最新のコードを持っていることを確実にするためのものです。 こうすると、Yii 開発チームが確実にワン・クリックであなたの変更をマージすることが出来るようになります。
git push origin docs-ja-xyz-translation
または
git push yiijan docs-ja-xyz-translation
上記の 2. の段階で設定したリモートの名称に従って、作業したブランチを yiijan にプッシュしてください。
github の yiijan のレポジトリに入って、本家に対して "Pull Request" を発行します。
ドキュメントの日本語翻訳に限定されている限り、プル・リクエストが却下される可能性はまずありません。
あなたのプルリクエストが受け入れられた後、あなたが作業してきたブランチをローカルおよび yiijan のレポジトリから削除することが出来ます。
git checkout master
git branch -D docs-ja-zyz-translation
git push origin --delete docs-ja-zyz-translation
本家に直接のプル・リクエストをすることは、あなたの権利です。 誰もそれを制止する権利を持ちません。 また、何でもかんでも、一緒にやらなければならない訳でもないでしょう。 あなたの好きなやり方で yii プロジェクトに参画して下さい。
yiijan では、片仮名のテクニカル・タームにおいて "・" (中黒) をデリミタとしています。 例えば、
- application component : アプリケーション・コンポーネント
- active record model class : アクティブ・レコード・モデル・クラス
また、語末の長音記号 "ー" は原則として省略しています。 例えば、
- web server : ウェブ・サーバ
- html helper : html ヘルパ
翻訳作業上、原文と訳文を比較しなければならない事がよくあります。 例えば、原文において修正や追加があった場合に、訳文の該当場所を探し出すことが必要になります。
このため、パラグラフ単位で訳文の行数を原文の行数と同じになるように調整して、 原文と訳文の突き合わせが楽に出来るようにしています。
以下のスクリプトを作業の補助として使用することが出来ます。
(各ツールにはシェル・スクリプト・バージョンと Windows *.bat ファイル・バージョンがあります)
GitHub の yiijan グループから、repo-list.txt に列挙されたレポジトリをクローンします。
そのとき同時に、upstream に yiisoft 本家のレポジトリを指定します。
特定のレポジトリについて、翻訳の追加や更新が必要な文書(またはその個所)を抽出します。
対象とするレポジトリの名前を引数として与えてください。例えば、
./check-docs yii2-gii
ただし、対象となるレポジトリは、この yii2-ja レポジトリを格納するディレクトリの兄弟ディレクトリにある必要があります。
結果は、translation-check ディレクトリに <repo-name>.html 例えば yii2-gii.html として格納されます。
このスクリプトは、内部的に、yii/build/build translation コマンドを使用しています。 詳細については、翻訳ワークフロー を参照してください。
情報: チェック結果の html ファイルは、内容が前回と変化していない場合は、タイムスタンプが変化しません。
情報:
yii2レポジトリに対しては、開発者用内部文書の翻訳も追加でチェックします。結果の html ファイルはinternals.htmlです。
repo-list.txt に列挙されたレポジトリ全てについて、check-docs を実行します。
yii2 レポジトリのソースから、翻訳の対象となるメッセージを抽出して、yii2/framework/messages/ja/yii2.php ファイルを更新します。
config-ja.php を構成情報として参照します。
このバッチ・ファイルは、内部的に、message/extract コマンドを使用しています。 詳細については、翻訳ワークフロー を参照してください。
特定のレポジトリについて、ローカルおよび origin の master ブランチを upstream の master ブランチで更新します。
そして、同時に、そのレポジトリに対して check-docs スクリプトを実行します。
対象とするレポジトリの名前を引数として与えてください。例えば、
update-repo.bat yii2-gii
ただし、対象となるレポジトリは、この yii2-ja レポジトリを格納するディレクトリの兄弟ディレクトリにある必要があります。
repo-list.txt に列挙されたレポジトリ全てについて、update-repo を実行します。
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent