docs/guide-ja updated [ci skip] (#16821)

docs/guide-ja/security-best-practices.md

@@ -160,16 +160,26 @@ CSRF を回避する
 CSRF は、クロス・サイト・リクエスト・フォージェリ (cross-site request forgery) の略称です。
 多くのアプリケーションは、ユーザのブラウザから来るリクエストはユーザ自身によって発せられたものだと仮定しているけれども、その仮定は間違っているかもしれない ... というのが CSRF の考え方です。
 
-例えば、`an.example.com` というウェブ・サイトが `/logout` という URL を持っており、この URL を単純な GET でアクセスするとユーザをログアウトさせるようになっているとします。
-ユーザ自身によってこの URL がリクエストされる限りは何も問題はありませんが、ある日、悪い奴が、ユーザが頻繁に訪れるフォーラムに `<img src="http://an.example.com/logout">` というリンクを含むコンテントを何とかして投稿することに成功します。
+例えば、`an.example.com` というウェブ・サイトが `/logout` という URL を持っており、
+この URL を単純な GET でアクセスするとユーザをログアウトさせるようになっているとします。
+ユーザ自身によってこの URL がリクエストされる限りは何も問題はありませんが、ある日、悪い奴が、ユーザが頻繁に訪れるフォーラムに `<img src="http://an.example.com/logout">` というリンクを含むコンテントを何らかの方法で投稿します。
 ブラウザは画像のリクエストとページのリクエストの間に何ら区別を付けませんので、ユーザがそのような `img` タグを含むページを開くとブラウザはその URL に対して GET リクエストを送信します。
 そして、ユーザが `an.example.com` からログアウトされてしまうことになる訳です。
 
-これは基本的な考え方です。ユーザがログアウトされるぐらいは大したことではない、と言うことも出来るでしょう。しかし、悪い奴は、この考え方を使って、もっとひどいことをすることも出来ます。例えば、`http://an.example.com/purse/transfer?to=anotherUser&amount=2000` という URL を持つウェブ・サイトがあると考えて見てください。この URL に GET リクエストを使ってアクセスすると、権限を持つユーザア・カウントから `anotherUser` に $2000 が送金されるのです。私たちは、ブラウザは画像をロードするのに常に GET リクエストを使う、ということを知っていますから、この URL が POST リクエストだけを受け入れるようにコードを修正することは出来ます。しかし残念なことに、それで問題が解決する訳ではありません。攻撃者は `<img>` タグの代りに何らかの JavaScript コードを書いて、その URL に対する POST リクエストの送信を可能にすることが出来ます。
+これは CSRF 攻撃がどのように動作するかという基本的な考え方です。ユーザがログアウトされるぐらいは大したことではない、と言うことも出来るでしょう。
+しかしこれは例に過ぎません。この考え方を使って、支払いを開始させたり、データを変更したりというような、もっとひどいことをすることも出来ます。
+`http://an.example.com/purse/transfer?to=anotherUser&amount=2000` という URL を持つウェブ・サイトがあると考えて見てください。この URL に GET リクエストを使ってアクセスすると、権限を持つユーザ・アカウントから `anotherUser` に $2000 が送金されるのです。
+私たちは、ブラウザは画像をロードするのに常に GET リクエストを使う、ということを知っていますから、
+この URL が POST リクエストだけを受け入れるようにコードを修正することは出来ます。
+しかし残念なことに、それで問題が解決する訳ではありません。攻撃者は `<img>` タグの代りに何らかの JavaScript コードを書いて、
+その URL に対する POST リクエストの送信を可能にすることが出来ます。
+
+これを理由として、Yii は CSRF 攻撃を防御するための追加のメカニズムを適用します。
 
 CSRF を回避するためには、常に次のことを守らなければなりません。
 
 1. HTTP の規格、すなわち、GET はアプリケーションの状態を変更すべきではない、という規則に従うこと。
+   詳細は [RFC2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) を参照して下さい。
 2. Yii の CSRF 保護を有効にしておくこと。
 
 場合によっては、コントローラやアクションの単位で CSRF 検証を無効化する必要があることがあるでしょう。これは、そのプロパティを設定することによって達成することが出来ます。

docs/guide-ja/structure-applications.md

@@ -365,6 +365,7 @@ $width = \Yii::$app->params['thumbnail.size'][0];
 ]
 ```
 
+タイム・ゾーンを設定することの意味合いについては、[日付のフォーマッティングのセクション](output-formatting.md#time-zones) で詳細を参照して下さい。
 
 #### [[yii\base\Application::version|version]] <span id="version"></span>
 

docs/guide-ja/structure-widgets.md

@@ -86,6 +86,10 @@ use yii\helpers\Html;
 
 ## ウィジェットを作成する <span id="creating-widgets"></span>
 
+ウィジェットは必要に従って二つの異なる方法で作成することが出来ます。
+
+### 1: `widget()` メソッドを利用する
+
 ウィジェットを作成するためには、[[yii\base\Widget]] を拡張して、[[yii\base\Widget::init()]] および/または
 [[yii\base\Widget::run()]] メソッドをオーバーライドします。
 通常、`init()` メソッドはウィジェットのプロパティを初期化するコードを含むべきものであり、`run()` メソッドはウィジェットのレンダリング結果を生成するコードを含むべきものです。
@@ -128,6 +132,21 @@ use app\components\HelloWidget;
 <?= HelloWidget::widget(['message' => 'おはよう']) ?>
 ```
 
+
+ウィジェットが大きなかたまりのコンテントをレンダーする必要がある場合もあります。
+コンテントを `run()` の中に埋め込むことも出来ますが、もっと良い方法は、コンテントを [view](structure-views.md) に置き、
+[[yii\base\Widget::render()]] を呼んでレンダーする方法です。例えば、
+
+```php
+public function run()
+{
+    return $this->render('hello');
+}
+```
+
+### 2: `begin()` と `end()` のメソッドを利用する
+
+これは上記のものと少し異なるだけのものです。
 下記は `HelloWidget` の変種で、`begin()` と `end()` の間に包まれたコンテントを受け取り、
 それを HTML エンコードして表示するものです。
 
@@ -168,22 +187,17 @@ use app\components\HelloWidget;
 ?>
 <?php HelloWidget::begin(); ?>
 
-    ... タグを含みうるコンテント ...
+    一つまたはそれ以上の <strong>HTML</strong> <pre>タグ</pre> を含みうるサンプル・コンテント
+
+    このコンテントが大きくなりすぎる場合は、サブ・ビューを使います。
+
+    例えば、
+
+    <?php echo $this->render('viewfile'); // 注意: この render() メソッドは \yii\base\View クラスのもの。コードのこの部分はビュー・ファイルの中にあり、Widget クラス・ファイルの中にはない ?>
 
 <?php HelloWidget::end(); ?>
 ```
 
-場合によっては、ウィジェットが大きな固まりのコンテントを表示する必要があるかもしれません。
-コンテントを `run()` メソッドの中に埋め込むことも出来ますが、より良い方法は、コンテントを [ビュー](structure-views.md) の中に置いて、[[yii\base\Widget::render()]] を呼んでレンダリングすることです。
-例えば、
-
-```php
-public function run()
-{
-    return $this->render('hello');
-}
-```
-
 デフォルトでは、ウィジェット用のビューは `WidgetPath/views` ディレクトリの中のファイルに保存すべきものです。
 ここで `WidgetPath` はウィジェットのクラス・ファイルを含むディレクトリを指します。
 したがって、上記の例では、ウィジェット・クラスが `@app/components` に配置されていると仮定すると、`@app/components/views/hello.php` というビュー・ファイルがレンダリングされることになります。