docs/guide-ja updated [ci skip]

docs/guide-ja/concept-di-container.md

@@ -74,17 +74,44 @@ $container->get('Foo', [], [
 ### PHP コーラブル・インジェクション <span id="php-callable-injection"></span>
 
 この場合、コンテナは、登録された PHP のコーラブルを使用して、クラスの新しいインスタンスを構築します。
-コーラブルは、依存関係を解決し、新しく作成されたオブジェクトに適切に依存を注入する責務を負います。
+[[yii\di\Container::get()]] が呼ばれるたびに、対応するコーラブルが起動されます。
+このコーラブルが、依存関係を解決し、新しく作成されたオブジェクトに適切に依存を注入する役目を果たします。
 たとえば
 
 ```php
 $container->set('Foo', function () {
-    return new Foo(new Bar);
+    $foo = new Foo(new Bar);
+    // ... その他の初期化 ...
+    return $foo;
 });
 
 $foo = $container->get('Foo');
 ```
 
+新しいオブジェクトを構築するための複雑なロジックを隠蔽するために、PHP コーラブルを返すスタティックなクラスメソッドを使うことが出来ます。
+例えば、
+
+```php
+class FooBuilder
+{
+    public static function build()
+    {
+        return function () {
+            $foo = new Foo(new Bar);
+            // ... その他の初期化 ...
+            return $foo;
+       };
+    }
+}
+
+$container->set('Foo', FooBuilder::build());
+
+$foo = $container->get('Foo');
+```
+
+ご覧のように、PHP コーラブルが `FooBuilder::build()` メソッドによって返されています。
+このようにすれば、`Foo` クラスを構成しようとする人は、`Foo` がどのように構築されるかを気にする必要はもうなくなります。
+
 
 依存関係の登録 <span id="registering-dependencies"></span>
 --------------

docs/guide-ja/concept-service-locator.md

@@ -47,7 +47,7 @@ $locator->set('pageCache', new FileCache);
 
 ```php
 $cache = $locator->get('cache');
-// または代わりに
+// または代りに
 $cache = $locator->cache;
 ```
 
@@ -60,8 +60,8 @@ $cache = $locator->cache;
 
 サービスロケータは多くの場合、 [構成情報](concept-configurations.md) で作成されるため、
 [[yii\di\ServiceLocator::setComponents()|components]] という名前の書き込み可能プロパティが提供されています。
-これで一度に複数のコンポーネントを設定して登録することができます。次のコードはアプリケーションを構成する構成情報配列を示しており、
-"db" と "cache" と "search" コンポーネントの登録もしています:
+これで一度に複数のコンポーネントを設定して登録することができます。
+次のコードは、サービスロケータ (例えば [アプリケーション](structure-applications.md)) を "db"、"cache"、"search" コンポーネントとともに構成するための構成情報配列を示しています。
 
 ```php
 return [
@@ -75,36 +75,39 @@ return [
         ],
         'cache' => 'yii\caching\ApcCache',
         'search' => function () {
-            return new app\components\SolrService;
+            $solr = new app\components\SolrService('127.0.0.1');
+            // ... その他の初期化 ...
+            return $solr;
         },
     ],
 ];
 ```
 
-コンポーネントが複雑なものである場合に、構成の複雑さを隠蔽する追加のクラスを作成するのは良いアイデアです。
+上記において、"search" コンポーネントを構成する別の方法があります。
+`SolrService` のインスタンスを構築する PHP コールバックを直接に書く代りに、下記のように、そういうコールバックを返すスタティックなクラスメソッドを使うことが出来ます。
 
 ```php
-class FacebookSDK {
-    public static function service($config) {
-        return function() use $config {
-             // ここでオブジェクトを構築する
-             return $object;
+class SolrServiceBuilder
+{
+    public static function build($ip)
+    {
+        return function () use ($ip) {
+            $solr = new app\components\SolrService($ip);
+            // ... その他の初期化 ...
+            return $solr;
         };
     }
 }
-```
 
-これを次のように使うことが出来ます。
-
-```php
 return [
     // ...
     'components' => [
         // ...
-        'facebook' => FacebookSDK::service([
-            'secret' => 'theverysecret',
-            // ...
-        ]),
+        'search' => SolrServiceBuilder::build('127.0.0.1'),
     ],
 ];
 ```
+
+この方法は、Yii に属さないサードパーティのライブラリをカプセル化する Yii コンポーネントをリリースしようとする場合に、特に推奨される代替手法です。
+上で示されているようなスタティックなメソッドを使ってサードパーティのオブジェクトを構築する複雑なロジックを表現します。
+そうすれば、あなたのコンポーネントのユーザは、コンポーネントを構成するスタティックなメソッドを呼ぶ必要があるだけになります。

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

@@ -131,13 +131,21 @@ HtmlPurifier の処理は非常に重いので、キャッシュを追加する
 CSRF を回避する
 ---------------
 
-TBD: what's CSRF, how it works, intro
+CSRF とは、クロスサイトリクエストフォージェリ (cross-site request forgery) の略称です。
+多くのアプリケーションは、ユーザのブラウザから来るリクエストはユーザ自身によって発せられたものだと仮定しているけれども、その仮定は間違っているかもしれない ... というのが CSRF の考え方です。
 
-1. HTTP の規格に従うこと、すなわち、GET はアプリケーションの状態を変更すべきではない。
+例えば、`an.example.com` というウェブサイトが `/logout` という URL を持っており、この URL を単純な GET でアクセスするとユーザをログアウトさせるようになっているとします。
+ユーザ自身によってこの URL がリクエストされる限りは何も問題はありませんが、ある日、悪い連中が、ユーザが頻繁に訪れるフォーラムに `<img src="http://an.example.com/logout">` というリンクを含むコンテントを何とかして投稿します。
+ブラウザは画像のリクエストとページのリクエストの間に何ら区別を付けませんので、ユーザがそのような `img` タグを含むページを開くと `an.example.com` からログアウトされてしまうことになります。
+
+これは基本的な考え方です。ユーザがログアウトされるぐらいは大したことではない、と言うことも出来るでしょう。
+しかし、POST を送信することも、それほど難しくはありません。
+
+CSRF を回避するためには、次のことを守らなければなりません。
+
+1. HTTP の規格、すなわち、GET はアプリケーションの状態を変更すべきではない、という規則に従うこと。
 2. Yii の CSRF 保護を有効にしておくこと。
 
-TBD: how CSRF protection works
-
 
 ファイルの曝露を回避する
 ------------------------