Merge pull request #6241 from softark/docs-internals-ja-2014-11-25

docs/internals-ja/core-code-style.md

@@ -2,7 +2,7 @@ Yii2 繧ｳ繧｢繝輔Ξ繝ｼ繝繝ｯ繝ｼ繧ｯ縺ｮ繧ｳ繝ｼ繝峨せ繧ｿ繧､繝ｫ
 =======================================
 
 下記のコードスタイルが Yii 2.x コアと公式エクステンションの開発に用いられています。
-コアに対してプルリクエストをしたいときは、これを使用することを考慮してください。
+コアに対してコードをプルリクエストをしたいときは、これを使用することを考慮してください。
 私たちは、あなたが自分のアプリケーションにこのコードスタイルを使うことを強制するものではありません。
 あなたにとってより良いコードスタイルを自由に選んでください。
 
@@ -22,7 +22,7 @@ Yii2 繧ｳ繧｢繝輔Ξ繝ｼ繝繝ｯ繝ｼ繧ｯ縺ｮ繧ｳ繝ｼ繝峨せ繧ｿ繧､繝ｫ
 - クラス内の定数はアンダースコアで区切られた大文字だけで宣言されなければならない。
 - メソッド名は `camelCase` で宣言されなければならない。
 - プロパティ名は `camelCase` で宣言されなければならない。
-- プロパティ名は private である場合はアンダースコアで開始しなければならない。
+- プロパティ名は private である場合はアンダースコアで始まらなければならない。
 - `else if` ではなく常に `elseif` を使用すること。
 
 2. ファイル
@@ -30,9 +30,9 @@ Yii2 繧ｳ繧｢繝輔Ξ繝ｼ繝繝ｯ繝ｼ繧ｯ縺ｮ繧ｳ繝ｼ繝峨せ繧ｿ繧､繝ｫ
 
 ### 2.1. PHP タグ
 
-- PHP コードは `<?php ?>` または `<?=` タグを使わなければなりません。他のタグ、例えば `<?` は使ってはなりません。
+- PHP コードは `<?php ?>` または `<?=` タグを使わなければなりません。他のタグの変種、例えば `<?` を使ってはなりません。
 - ファイルが PHP コードのみを含む場合は、末尾の `?>` を含むべきではありません。
-- 各行の末尾に空白を追加しないこと。
+- 各行の末尾に空白を追加してはいけません。
 - PHP コードを含む全てのファイルの名前は `.php` という拡張子で終るべきです。
 
 ### 2.2. 文字エンコーディング
@@ -51,26 +51,26 @@ PHP 繧ｳ繝ｼ繝峨 BOM 辟｡縺励 UTF-8 縺ｮ縺ｿ繧剃ｽｿ繧上↑縺代ｌ縺ｰ縺ｪ繧翫∪縺帙ｓ
 
 - クラスは `CamelCase` で命名されなければなりません。
 - 中括弧は常にクラス名の下の行に書かれるべきです。
-- 全てのクラスは PHPDoc に従ったドキュメンテーションブロックを持たなければなりません。
+- 全てのクラスは PHPDoc に従ったドキュメントブロックを持たなければなりません。
 - クラス内のすべてのコードは単一のタブによってインデントされなければなりません。
-- 単一の PHP ファイルにはクラスが一つだけあるべきです。
+- 一つの PHP ファイルにはクラスが一つだけあるべきです。
 - 全てのクラスは名前空間に属すべきです。
-- クラス名はファイル名と一致すべきです。クラスの名前空間はディレクトリ構造と一致すべきです。
+- クラス名はファイル名と合致すべきです。クラスの名前空間はディレクトリ構造と合致すべきです。
 
 ```php
 /**
- * ドキュメンテーション
+ * ドキュメント
  */
 class MyClass extends \yii\Object implements MyInterface
 {
-    // code
+    // コード
 }
 ```
 
 ### 4.1. 定数
 
 クラスの定数はアンダースコアで区切られた大文字だけで宣言されなければなりません。
-例えば:
+例えば、
 
 ```php
 <?php
@@ -82,17 +82,17 @@ class Foo
 ```
 ### 4.2. プロパティ
 
-- Public なクラスメンバーを宣言するときは `public` キーワードを明示的に指定します。
+- Public なクラスメンバを宣言するときは `public` キーワードを明示的に指定します。
 - Public および protected な変数はクラスの冒頭で、すべてのメソッドの宣言に先立って宣言されるべきです。
   Private な変数もまたクラスの冒頭で宣言されるべきですが、
-  変数がクラスのメソッドのごく一部分にのみ関係する場合は、変数を扱う一群のメソッドの直前に追加してもかまいません。
+  変数がクラスのメソッドのごく一部分にのみ関係する場合は、変数を扱う一群のメソッドの直前に追加しても構いません。
 - クラスにおけるプロパティの宣言の順序は public から始まり、protected、private と続くべきです。
 - より読みやすいように、プロパティの宣言は空行を挟まずに続け、プロパティ宣言とメソッド宣言のブロック間には2行の空行を挟むべきです。
 - Private 変数は `$_varName` のように名付けるべきです。
-- Public なクラスメンバーとスタンドアロンな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。
+- Public なクラスメンバとスタンドアロンな変数は、先頭を小文字にした `$camelCase` で名付けるべきです。
 - 説明的な名前を使うこと。`$i` や `$j` のような変数は使わないようにしましょう。
 
-例えば:
+例えば、
 
 ```php
 <?php
@@ -109,17 +109,17 @@ class Foo
 - 関数およびメソッドは、先頭を小文字にした `camelCase` で名付けるべきです。
 Functions and methods should be named using `camelCase` with first letter lowercase.
 - 名前は、関数の目的を示す自己説明的なものであるべきです。
-- クラスのメソッドは常に `private`、`protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。
+- クラスのメソッドは常に修飾子 `private`、`protected` または `public` を使って、可視性を宣言すべきです。`var` は許可されません。
 - 関数の開始の中括弧は関数宣言の次の行に置くべきです。
 
 ~~~
 /**
- * ドキュメンテーション
+ * ドキュメント
  */
 class Foo
 {
     /**
-     * ドキュメンテーション
+     * ドキュメント
      */
     public function bar()
     {
@@ -154,7 +154,7 @@ $config = [
 ];
 ```
 
-既存の変数の型を変えることは悪い慣行であるとみなされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。
+既存の変数の型を変えることは悪い慣行であると見なされます。本当に必要でない限り、そのようなコードを書かないように努めましょう。
 
 
 ```php
@@ -167,13 +167,13 @@ public function save(Transaction $transaction, $argument2 = 100)
 
 ### 5.2 文字列
 
-- 変数およびシングルクォーツを含まない文字列には、シングルクォーツを使います。
+- 文字列が変数および一重引用符を含まない場合は、一重引用符を使います。
 
 ```php
 $str = 'Like this.';
 ```
 
-- 文字列がシングルクォーツを含む場合は、余分なエスケープを避けるためにダブルクォーツを使ってもかまいません。
+- 文字列が一重引用符を含む場合は、余計なエスケープを避けるために二重引用符を使ってもかまいません。
 
 #### 変数置換
 
@@ -206,7 +206,7 @@ $sql = "SELECT *"
 
 ### 5.3 配列
 
-配列には、開発者は PHP 5.4 の短縮構文を使用しています。
+配列には、私たちは PHP 5.4 の短縮構文を使用しています。
 
 #### 添え字配列
 
@@ -218,7 +218,7 @@ $sql = "SELECT *"
 $arr = [3, 14, 15, 'Yii', 'Framework'];
 ```
 
-一つの行に多すぎる要素がある場合は:
+一つの行には多過ぎるほど要素がたくさんある場合は:
 
 ```php
 $arr = [
@@ -243,9 +243,9 @@ $config = [
 
 - 制御文の条件は括弧の前と後に一つの空白を持たなければなりません。
 - 括弧の中の演算子は空白によって区切られるべきです。
-- 開始の括弧は同じ行に置きます。
-- 終了の括弧は新しい行に置きます。
-- 単一行の文に対しても、常に括弧を使用します。
+- 開始の中括弧は同じ行に置きます。
+- 終了の中括弧は新しい行に置きます。
+- 単一行の文に対しても、常に中括弧を使用します。
 
 ```php
 if ($event === null) {
@@ -263,7 +263,7 @@ if (!$model && null === $event)
 
 #### switch
 
-switch には下記の書式を使用します:
+switch には下記の書式を使用します。
 
 ```php
 switch ($this->phpType) {
@@ -297,7 +297,7 @@ doIt('a', [
 
 ### 5.6 無名関数 (lambda) の宣言
 
-`function`/`use` トークンと開始括弧の間の空白に注意:
+`function`/`use` トークンと開始括弧の間の空白に注意してください。
 
 ```php
 // 良い
@@ -308,7 +308,7 @@ $sum = array_reduce($numbers, function ($r, $x) use ($n) {
     return $r;
 });
 
-// bad
+// 悪い
 $n = 100;
 $mul = array_reduce($numbers, function($r, $x) use($n) {
     $this->doMagic();
@@ -317,21 +317,21 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
 });
 ```
 
-ドキュメンテーション
---------------------
+ドキュメント
+------------
 
-- ドキュメンテーションの文法については [phpDoc](http://phpdoc.org/) を参照してください。
-- ドキュメンテーションの無いコードは許容されません。
+- ドキュメントの文法については [phpDoc](http://phpdoc.org/) を参照してください。
+- ドキュメントの無いコードは許容されません。
 - 全てのクラスファイルは、ファイルレベルの doc ブロックを各ファイルの先頭に持ち、
   クラスレベルの doc ブロックを各クラスの直前に持たなければなりません。
-- メソッドが何も返さないときは `@return` を使う必要はありません。
+- メソッドが実際に何も返さないときは `@return` を使う必要はありません。
 - `yii\base\Object` から派生するクラスのすべての仮想プロパティは、クラスの doc ブロックで `@property` タグでドキュメントされます。
   これらの注釈は、`build` ディレクトリで `./build php-doc` コマンドを走らせることにより、
   対応する getter や setter の `@return` や `@param` タグから自動的に生成されます。
-  getter や setter によって導入されるプロパティに対してドキュメンテーションのメッセージを
-  明示的に与えるために `@property` タグを追加することが出来ます。
-  これは `@return` において記述されているのとは違う説明を与えたい場合に有用です。
-  例えば:
+  getter や setter に `@property` タグを追加することによって、
+  これらのメソッドによって導入されるプロパティに対してドキュメントのメッセージを明示的に与えることが出来ます。
+  これは `@return` で記述されているのとは違う説明を与えたい場合に有用です。
+  下記が一例です。
 
   ```php
     <?php
@@ -341,15 +341,14 @@ $mul = array_reduce($numbers, function($r, $x) use($n) {
      * @property array 全ての属性に対するエラーの配列。エラーが無い場合は空の配列が返される。
      * 結果は二次元の配列である。詳細な説明は [[getErrors()]] を参照。
      * @return array 全ての属性または特定の属性に対するエラー。エラーが無い場合は空の配列が返される。
-     * 全ての属性に対する配列を返す場合、結果は、下記のように、二次元の配列である:
+     * 全ての属性に対するエラーを返す場合、結果は、下記のような二次元の配列になる。
      * ...
      */
     public function getErrors($attribute = null)
   ```
 
->Note|注意: これ以降、読みやすさを考慮してドキュメンテーションの内容を日本語に翻訳していますが、
-コアコードや公式エクステンションに対して寄稿する場合は、当然ながら、コメントは英語だけを
-使わなければなりません。
+>Note|注意: ここでは読みやすさを考慮してドキュメントの内容を日本語に翻訳していますが、
+コアコードや公式エクステンションに対して寄稿する場合は、当然ながら、コメントには英語だけを使う必要があるでしよう。
 
 #### ファイル
 
@@ -407,14 +406,14 @@ public function getEventHandlers($name)
 
 上記の例に見られるように、phpDoc コメントの書式設定には markdown を使っています。
 
-ドキュメンテーションの中でクラス、メソッド、プロパティをクロスリンクするために使う追加の文法があります:
+ドキュメントの中でクラス、メソッド、プロパティをクロスリンクするために使える追加の文法があります。
 
 - `'[[canSetProperty]] ` は、同じクラス内の `canSetProperty` メソッドまたはプロパティへのクロスリンクを生成します。
 - `'[[Component::canSetProperty]]` は、同じ名前空間内の `Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。
 - `'[[yii\base\Component::canSetProperty]]` は、`yii\base` 名前空間の`Component` クラスの `canSetProperty` メソッドへのクロスリンクを生成します。
 - `'[[Component]]` は、同じ名前空間内の `Component` クラスへのクロスリンクを生成します。ここでも、クラス名に名前空間を追加することが可能です。
 
-上記のリンクにクラス名やメソッド名以外のラベルを付けるために、次の例で示されている書式を使うことが出来ます:
+上記のリンクにクラス名やメソッド名以外のラベルを付けるためには、次の例で示されている文法を使うことが出来ます。
 
 ```
 ... [[header|ヘッダセル]] に表示されているように
@@ -422,7 +421,7 @@ public function getEventHandlers($name)
 
 `|` の前の部分がメソッド、プロパティ、クラスへの参照であり、`|` の後ろの部分がリンクのラベルです。
 
-下記の書式を使って公式ガイドにリンクすることも可能です:
+下記の文法を使ってガイドにリンクすることも可能です:
 
 ```markdown
 [ガイドへのリンク](guide:file-name.md)
@@ -440,11 +439,11 @@ public function getEventHandlers($name)
 
 ### `=== []` 対 `empty()`
 
-かの名時は `empty()` を使います。
+可能な場合は `empty()` を使います。
 
 ### 複数の return ポイント
 
-条件のネストが込み入ってきた場合は、早期の return を使います。メソッドが短いものである場合は、特に問題にしません。
+条件の入れ子が込み入ってきた場合は、早期の return を使います。メソッドが短いものである場合は、特に問題にしません。
 
 ### `self` 対 `static`
 
@@ -456,7 +455,8 @@ public function getEventHandlers($name)
 
 ### 「何かをするな」を示す値
 
-コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。`null`、`''`、または `[]` は、そのような値として受け取られるべきではありません。
+コンポーネントに対して「何かをしない」という設定を許可するプロパティは `false` の値を受け入れるべきです。
+`null`、`''`、または `[]` がそういう値であると見なされるべきではありません。
 
 ### ディレクトリ/名前空間の名前
 

docs/internals-ja/git-workflow.md

@@ -2,8 +2,9 @@ Yii 2 蟇ｨｿ閠縺溘ａ縺ｮ Git 繝ｯ繝ｼ繧ｯ繝輔Ο繝ｼ
 =====================================
 
 Yii の開発に寄稿したい、ですって? すばらしい! けれども、あなたの修正案が速やかに採用されるチャンスを増やすためには、
-どうか以下のステップを踏むようにしてください (最初の二つのステップは最初に寄稿するときにだけ必要になります)。
-あなたが git と github については初めてだという場合は、最初に [github help](http://help.github.com/) や [try git](https://try.github.com) を精査したり、[git internal data model](http://nfarina.com/post/9868516270/git-is-simpler) についていくらか学習したりする必要があるかもしれません。
+以下のステップを踏むようにしてください (最初の二つのステップは最初に寄稿するときにだけ必要になります)。
+あなたが git と github については初めてだという場合は、最初に [github help](http://help.github.com/) や [try git](https://try.github.com) を精査したり、
+[git internal data model](http://nfarina.com/post/9868516270/git-is-simpler) についていくらか学習したりする必要があるかもしれません。
 
 ### 1. github で Yii リポジトリを [Fork](http://help.github.com/fork-a-repo/) し、あなたのフォークをあなたの開発環境にクローンする
 
@@ -16,7 +17,7 @@ Linux 縺ｫ縺翫＞縺ｦ縲；itHub 縺ｧ GIT 繧定ｨｭ螳壹☆繧九縺ｫ蝠城｡後′逕溘§縺溘ｊ縲
 
 ### 2. メインの Yii リポジトリを "upstream" という名前でリモートとして追加する
 
-Yii をクローンしたディレクトリ、すなわち "yii2" に入って、以下のコマンドを打ち込みます:
+Yii をクローンしたディレクトリ、通常は "yii2" に入ります。そして、以下のコマンドを打ち込みます:
 
 ```
 git remote add upstream git://github.com/yiisoft/yii2.git
@@ -24,13 +25,13 @@ git remote add upstream git://github.com/yiisoft/yii2.git
 
 ### 3. あなたが取り組んでいる問題が、修正するために著しい努力を要求するものである場合は、それに対する課題(issue)が作成されていることを確認する
 
-全ての新機能とバグ修正は、議論とドキュメンテーションのための単一の参照ポイントを提供するために、それに結びつく課題を持つべきです。
+全ての新機能とバグ修正は、議論とドキュメントのための単一の参照ポイントを提供するために、それに結びつく課題を持つべきです。
 数分間時間を取って、既存の課題リストに目を通し、あなたが寄稿しようとしている問題に合致するものが無いかどうか調べてください。
 もし課題リストにすでに挙っているのを見つけた場合は、その課題にコメントを残して、あなたがその項目について取り組もうとしていることを示してください。
 あなたが取り組もうとしている問題に合致する既存の課題が見つからなかった場合は、新しい課題を作成してください。単純な修正であれば、直接にプルリクエストをしてください。
 こうすることで、開発チームはあなたの提案をレビューし、将来にわたって適切なフィードバックを提供することが可能になります。
 
-> 小さな変更や、ドキュメンテーションの問題、または単純な修正については、課題を作成する必要はありません。それらについては、プルリクエストだけで十分です。
+> 小さな変更や、ドキュメントの問題、または単純な修正については、課題を作成する必要はありません。それらについては、プルリクエストだけで十分です。
 
 ### 4. メインの Yii ブランチから最新のコードをフェッチする
 
@@ -38,7 +39,7 @@ git remote add upstream git://github.com/yiisoft/yii2.git
 git fetch upstream
 ```
 
-すべての新しい寄稿において、最新のコードに対して作業することを確実にするために、この作業から開始すべきです。
+最新のコードに対して作業することを保証するために、すべての新しい寄稿においてこのステップから作業を開始すべきです。
 
 ### 5. 現在の Yii のマスターブランチに基いて、あなたの寄稿のための新しいブランチを作成する
 
@@ -47,14 +48,14 @@ git fetch upstream
 独立したバグ修正や変更は、各々、それ自身のブランチに入れるべきです。
 ブランチの名前は説明的なものにし、あなたのコードが関係する課題の番号で始まるようにしてください。
 特定の課題を修正するものでない場合は、番号を省略してください。
-例えば:
+例えば、
 
 ```
 git checkout upstream/master
 git checkout -b 999-name-of-your-branch-goes-here
 ```
 
-### 6. 魔法を使ってあなたのコードを書く
+### 6. あなたの魔法を使って、あなたのコードを書く
 
 動くことを確認してくださいね :)
 
@@ -65,21 +66,21 @@ git checkout -b 999-name-of-your-branch-goes-here
 
 CHANGELOG ファイルを編集して、あなたの修正を追加します。
 新しい行は、ファイル冒頭の "Work in progress" 見出しの下に挿入してください。
-チェンジログの行は、下記のどちらかのように書いてください:
+チェンジログの行は、下記のどちらかのように書いてください。
 
 ```
 Bug #999: バグ修正の内容説明 (あなたの名前)
 Enh #999: 機能拡張の内容説明 (あなたの名前)
 ```
 
-`#999` は `Bug` または `Enh` が示している課題番号です。
-チェンジログはタイプ(`Bug`, `Enh`)によってグループ化し、課題番号順に並べます。
+`#999` は `Bug` または `Enh` が参照している課題番号です。
+チェンジログは、タイプ (`Bug`, `Enh`) によってグループ化し、課題番号順に並べます。
 
-非常に小さな修正、すなわち、タイポやドキュメンテーションの修正については、CHANGELOG を更新する必要はありません。
+非常に小さな修正、すなわち、タイポやドキュメントの修正については、CHANGELOG を更新する必要はありません。
 
 ### 8. 修正をコミットする
 
-以下のコマンドを使って、コミットしたいファイルや変更を [staging area](http://gitref.org/basic/#add) に追加します:
+以下のコマンドを使って、コミットしたいファイルや変更を [staging area](http://gitref.org/basic/#add) に追加します。
 
 ```
 git add path/to/my/file.php
@@ -87,14 +88,14 @@ git add path/to/my/file.php
 
 `-p` オプションを使って、コミットに含める変更を選択することも出来ます。
 
-説明的なコミットメッセージをいれて修正をコミットしてください。
-github があなたのコミットを自動的にチケットとリンクするように、`#XXX` という書式でチケット番号に言及することを忘れないでください:
+説明的なコミットメッセージを付けて修正をコミットしてください。
+github があなたのコミットを自動的にチケットとリンクするように、必ず `#XXX` でチケット番号に言及してください。
 
 ```
-git commit -m "A brief description of this change which fixes #42"
+git commit -m "#42 を解決する変更の短い説明をここに入れる"
 ```
 
-### 9. 最新の Yii コードを upstream からあなたのブランチに pull する
+### 9. 最新の Yii コードを upstream からあなたのブランチにプルする
 
 ```
 git pull upstream master
@@ -104,7 +105,7 @@ git pull upstream master
 もし何かマージ衝突がある場合は、ここでそれを修正してから再度変更をコミットすべきです。
 こうすると、Yii 開発チームがワンクリックであなたの変更をマージすることが確実に出来るようになります。
 
-### 10. 衝突をすべて解消したら、あなたのコードを github にプッシュする
+### 10. 衝突をすべて解決したら、あなたのコードを github にプッシュする
 
 ```
 git push -u origin 999-name-of-your-branch-goes-here
@@ -118,11 +119,11 @@ git push -u origin 999-name-of-your-branch-goes-here
 github 上のあなたのリポジトリに入って、"Pull Request" をクリックし、右側にあるブランチを選び、コメントボックスにもう少し詳細を記述します。
 プルリクエストを課題とリンクさせるために、プルコメントのどこかに `#999` という書式で課題番号を記載します。
 
-> 各プルリクエストは単一の課題を解決すべきものであることに注意してください。
+> 全てのプルリクエストはそれぞれ一つの課題を解決すべきものであることに注意してください。
 
 ### 12. 誰かがあなたのコードをレビューする
 
-誰かがあなたのコードをレビューします。あなたは修正を求められるかも知れません。その場合は、ステップ #6 に戻ってください 
+誰かがあなたのコードをレビューします。あなたは修正を求められるかも知れません。その場合は、ステップ #6 に戻ってください
 (現在のプルリクエストが open である限りは、別の新しいプルリクエストをする必要はありません)。
 あなたのコードが受け入れられた場合は、コードはメインブランチにマージされて、次回の Yii のリリースの一部となります。
 受け入れられなくても、落胆しないでください。
@@ -143,16 +144,16 @@ git push origin --delete 999-name-of-your-branch-goes-here
 
 退行 (regression) を早期に発見するために、github 上の Yii コードベースへのマージは、すべて [Travis CI](http://travis-ci.org) に取り上げられて、自動化されたテストにかけられます。
 コアチームとしては、このサービスに過大な負担をかけたくないために、
-以下の場合にはマージの説明に [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) が含まれるようにします。
-すなわち、プルリクエストが:
+以下の場合にはマージの説明に [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) が含まれるようにしてください。
+すなわち、プルリクエストが、
 
 * javascript、css または画像ファイルだけに影響する場合
-* ドキュメンテーションを更新する場合
-* 固定の文字列だけを修正する(例えば、翻訳をアップデートする)場合
+* ドキュメントを更新する場合
+* 固定の文字列だけを修正する (例えば、翻訳をアップデートする) 場合
 
 がそうです。
 
-このようにすることによって、そもそもテストによってカバーされない変更に対しては、最初から travis がテストランを開始しないようにしています。
+このようにすることによって、そもそもテストによってカバーされない変更に対しては、travis がテストランを開始しないようにすることが出来ます。
 
 ### コマンド概要 (上級の寄稿者向け)
 

docs/internals-ja/report-an-issue.md

 課題を報告する
 ==============
 
-あなたが報告する課題(issue)がより迅速に解決されるように、課題を作成するときには下記のガイドラインに従って下さい:
+あなたが報告する課題 (issue) がより迅速に解決されるように、課題を作成するときには下記のガイドラインに従って下さい。
 
-* PHP と Yii のバージョン、オペレーティングシステムとウェブサーバのタイプ、および、ブラウザのタイプとバージョンについて、情報を提供してください;
+* PHP と Yii のバージョン、オペレーティングシステムとウェブサーバのタイプ、および、ブラウザのタイプとバージョンについて、情報を提供してください。
 * 出来れば、**完全な**エラーのコールスタックを提供して下さい。問題を説明するスクリーンショットは大いに歓迎されます。
 * 問題を再現する手順を記述して下さい。問題を再現するコードを提供してくださるならば、なお一層良いでしょう。
 

docs/internals-ja/translation-workflow.md

@@ -2,40 +2,40 @@
 ================
 
 Yii は国際的なアプリケーションと開発者にとって役に立つように、数多くの言語に翻訳されています。
-貢献が大いに歓迎される主な領域はドキュメンテーションとフレームワークメッセージです。
+貢献が大いに歓迎される主な領域はドキュメントとフレームワークメッセージです。
 
 フレームワークメッセージ
 ------------------------
 
-フレームワークは二種類のメッセージを持っています: 一つは開発者向けの例外メッセージで、これは決して翻訳されません。
+フレームワークは二種類のメッセージを持っています。一つは開発者向けの例外メッセージで、これは決して翻訳されません。
 もう一つはエンドユーザーが実際に目にする検証エラーのようなメッセージです。
 
 メッセージの翻訳を開始するためには:
 
 1. `framework/messages/config.php` をチェックして、あなたの言語が `languages` のリストに挙っていることを確認してください。
-   もし挙っていなければ、あなたの言語をそこに追加します(リストをアルファベット順に保つことを忘れないでください)。
+   もし挙っていなければ、あなたの言語をそこに追加します (リストをアルファベット順に保つことを忘れないでください)。
    言語コードの形式は、例えば `ru` や `zh-CN` のように、[IETF言語タグ](http://ja.wikipedia.org/wiki/IETF%E8%A8%80%E8%AA%9E%E3%82%BF%E3%82%B0) に従うべきです。
 2. `framework` に入って、`yii message/extract messages/config.php` を走らせます。
 3. `framework/messages/your_language/yii.php` のメッセージを翻訳します。ファイルは必ず UTF-8 エンコーディングを使って保存してください。
-4. [プルリクエスト](https://github.com/yiisoft/yii2/blob/master/docs/internals/git-workflow.md)をします。
+4. [プルリクエスト](https://github.com/yiisoft/yii2/blob/master/docs/internals/git-workflow.md) をします。
 
 あなたの翻訳を最新状態に保つために、`yii message/extract messages/config.php` を再び走らせることが出来ます。
-これによって、変更のなかった箇所には触れることなく、自動的にメッセージを再抽出することが出来ます。
+このコマンドは、変更のなかった箇所には触れることなく、自動的にメッセージを再抽出してくれます。
 
 翻訳ファイルの中で、配列の各要素は、メッセージ(キー)と翻訳(値)をあらわします。
-値が空白の場合は、メッセージは翻訳されないものと見なされます。
+値が空文字列の場合は、メッセージは翻訳されないものと見なされます。
 翻訳が不要になったメッセージは、翻訳が一組の '@@' マークで囲まれます。
 メッセージ文字列は複数形書式とともに使うことが出来ます。
 詳細はガイドの [国際化](../guide-ja/tutorial-i18n.md) の節を参照してください。
 
-ドキュメンテーション
---------------------
+ドキュメント
+------------
 
-ドキュメンテーションの翻訳は `docs/<original>-<language>` の下に置きます。
+ドキュメントの翻訳は `docs/<original>-<language>` の下に置きます。
 ここで `<original>` は、`guide` や `internals` などの元の文書の名前であり、`<language>` は文書の翻訳先の言語コードです。
 例えば、ロシア語のガイドの翻訳は `docs/guide-ru` です。
 
-初期の仕事が完了した後は、最新の翻訳以後に変更された元の文書の箇所を取得するために、`build` ディレクトリにある専用のコマンドを使うことが出来ます:
+初期の仕事が完了した後は、最新の翻訳以後に変更されたソース文書の箇所を取得するために、`build` ディレクトリにある専用のコマンドを使うことが出来ます。
 
 ```
 php build translation "../docs/guide" "../docs/guide-ru" "Russian guide translation report" > report_guide_ru.html

docs/internals-ja/versions.md

@@ -12,7 +12,7 @@ Yii バージョン規約
 * 不安無しのアップグレードを保証するために、100% 後方互換でなければならない。唯一の例外はセキュリティ問題で、その場合は後方互換性が破られることもある。
 * リリースのサイクルは1～2ヶ月程度。
 * プレリリース (alpha, beta, RC) は不要。
-* 常にマスターブランチにマージバックされるべき (少なくとも週に一回は手作業で)。
+* 定期的に (少なくとも週に一回は手作業で) マスターブランチにマージバックされるべき。
 
 
 ## マイナーリリース `2.X.0`
@@ -23,7 +23,7 @@ Yii バージョン規約
 * `UPGRADE-2.X.md` ファイルに記録される非後方互換な変更を含みうる。
 * リリースのサイクルは6～8ヶ月程度。
 * プレリリースが必要: `2.X.0-alpha`, `2.X.0-beta`, `2.X.0-rc`
-* 大きなニュースのリリースとマーケティングの試みを要求する。
+* 大きなニュースリリースとマーケティング努力を必要とする。
 
 
 ## メジャーリリース `X.0.0`

docs/internals-ja/view-code-style.md

+Yii2 ビューのコードスタイル
+===========================
+
+下記のコードスタイルが Yii 2.x コアと公式エクステンションのビューファイルに用いられています。
+私たちは、あなたが自分のアプリケーションにこのコードスタイルを使うことを強制するものではありません。
+あなたにとってより良いコードスタイルを自由に選んでください。
+
+
+```php
+<?php
+// 冒頭の PHP タグは全てのテンプレートファイルで不可欠。冒頭のタグに続く空行も同じく必須。
+
+// コントローラから渡される入力変数をここで説明。
+/* @var $this yii\base\View */
+/* @var $form yii\widgets\ActiveForm */
+/* @var $posts app\models\Post[] */
+/* @var $contactMessage app\models\ContactMessage */
+// 下の空行は必要。
+
+// 名前空間に属するクラスの宣言。
+use yii\helpers\Html;
+use yii\widgets\ActiveForm;
+// 下の空行は必要。
+
+// コンテキストのプロパティを設定したり、コンテキストのセッターを呼んだり、その他のことをする。
+$this->title = 'Posts';
+?>
+<!-- foreach、for などには、独立した PHP ブロックを使う方が良い -->
+<?php foreach ($posts as $post): ?>
+    <!-- インデントのレベルに注目 -->
+    <h2><?= Html::encode($post['title']) ?></h2>
+    <p><?= Html::encode($post['shortDescription']) ?></p>
+<!-- 複数の PHP ブロックが使われる場合にそなえて、`}` ではなく、`endforeach;`、`endfor;`、`endif;` などを使う -->
+<?php endforeach; ?>
+
+<!-- ウィジェットの宣言は複数のコード行に分かれても良いし、分かれなくても良い -->
+<?php $form = ActiveForm::begin([
+    'options' => ['id' => 'contact-message-form'],
+    'fieldConfig' => ['inputOptions' => ['class' => 'common-input']],
+]); ?>
+    <!-- インデントのレベルに注目 -->
+    <?= $form->field($contactMessage, 'name')->textInput() ?>
+    <?= $form->field($contactMessage, 'email')->textInput() ?>
+    <?= $form->field($contactMessage, 'subject')->textInput() ?>
+    <?= $form->field($contactMessage, 'body')->textArea(['rows' => 6]) ?>
+
+    <div class="form-actions">
+        <?= Html::submitButton('Submit', ['class' => 'common-button']) ?>
+    </div>
+<!-- ウィジェットの終了の呼び出しは、独立した PHP タグを持つべき -->
+<?php ActiveForm::end(); ?>
+<!-- 末尾の改行文字は必須 -->
+
+```