Merge pull request #5946 from jamband/add-docs-ja

docs/guide-ja/caching-fragment.md

+フラグメントキャッシュ
+================
+
+フラグメントキャッシュは、ウェブページの断片をキャッシュすることを言います。例えば、ページ内の表に年間販売の概要が表示されている場合、リクエスト毎にこの表を生成するのにかかる時間を削減するために、キャッシュにこの表を格納することができます。フラグメントキャッシュは [データキャッシュ](caching-data.md) 上に構築されています。
+
+フラグメントキャッシュを使用するには [ビュー](structure-views.md) で以下の構文を使用します:
+
+```php
+if ($this->beginCache($id)) {
+
+    // ... ここに生成するコンテンツを書く ...
+
+    $this->endCache();
+}
+```
+
+つまり [[yii\base\View::beginCache()|beginCache()]] と [[yii\base\View::endCache()|endCache()]] をペアにして囲み、その中にコンテンツ生成ロジックを書いていきます。コンテンツがキャッシュ内で見つかった場合、キャッシュされたコンテンツをレンダリングし [[yii\base\View::beginCache()|beginCache()]] は false を返します。結果として、コンテンツ生成ロジックはスキップされます。それ以外の場合はコンテンツ生成ロジックが呼ばれ、そして [[yii\base\View::endCache()|endCache()]] が呼ばれたとき生成されたコンテンツがキャプチャされ、キャッシュに格納されます。
+
+[データキャッシュ](caching-data.md) と同様に、キャッシュされたコンテンツを識別するためにユニークな `$id` が必要になります。
+
+
+## キャッシュのオプション <a name="caching-options"></a>
+
+[[yii\base\View::beginCache()|beginCache()]] メソッドの 2 番目のパラメータを配列にすることで、フラグメントキャッシュに関する追加のオプションを指定することもできます。裏で、この配列のオプションは実際にフラグメントキャッシュ機能を実装している [[yii\widgets\FragmentCache]] ウィジェットを構成するために使用されます。
+
+### 持続時間 <a name="duration"></a>
+
+
+おそらくフラグメントキャッシュで通常よく使われるであろうオプションは [[yii\widgets\FragmentCache::duration|duration]] でしょう。このオプションにはコンテンツがどれだけの時間キャッシュ内において有効であるかを指定します。以下のコードは最大で 1 時間コンテンツの断片をキャッシュします:
+
+```php
+if ($this->beginCache($id, ['duration' => 3600])) {
+
+    // ... ここに生成するコンテンツを書く ...
+
+    $this->endCache();
+}
+```
+
+オプションがセットされていない場合は、デフォルトである 60 が使われ、つまり有効期限が 60 秒間のキャッシュされたコンテンツを意味します。
+
+
+### 依存関係 <a name="dependencies"></a>
+
+[データキャッシュ](caching-data.md#cache-dependencies) と同様に、キャッシュされたコンテンツの断片は依存関係を持つことができます。例えば、表示されている投稿の内容は、投稿が変更されたか否かに依存する、といった具合です。
+
+依存関係を指定するには [[yii\widgets\FragmentCache::dependency|dependency]] オプションに [[yii\caching\Dependency]] オブジェクトを指定するか、または依存関係オブジェクトを作成するための配列構成を指定します。以下のコードはコンテンツの断片が `updated_at` カラムの値の変化に依存していることを指定しています:
+
+```php
+$dependency = [
+    'class' => 'yii\caching\DbDependency',
+    'sql' => 'SELECT MAX(updated_at) FROM post',
+];
+
+if ($this->beginCache($id, ['dependency' => $dependency])) {
+
+    // ... ここに生成するコンテンツを書く ...
+
+    $this->endCache();
+}
+```
+
+
+### バリエーション <a name="variations"></a>
+
+キャッシュされたコンテンツはいくつかのパラメータによって変化させることもできます。例えば、複数の言語をサポートしているウェブアプリケーションに対して、ビューコードの同じ部分を、異なる言語で生成することができます。現在のアプリケーションの言語に応じて、キャッシュされたコンテンツに変更を加えるといったことが可能になります。
+
+キャッシュのバリエーションを指定するには [[yii\widgets\FragmentCache::variations|variations]] オプションに配列で、それぞれが特定のバリエーションの要素を表すスカラー値をセットします。例えば、言語によってキャッシュされたコンテンツを変化させるには、以下のコードを使うことができます:
+
+```php
+if ($this->beginCache($id, ['variations' => [Yii::$app->language]])) {
+
+    // ... ここに生成するコンテンツを書く ...
+
+    $this->endCache();
+}
+```
+
+
+### トグルキャッシュ <a name="toggling-caching"></a>
+
+また、ある条件が満たされた場合にのみフラグメントキャッシュを有効にすることもできます。たとえば、フォームが表示されているページに対して、最初の (GET リクエストによる) リクエストの場合だけはキャッシュしたいと思いますが、その後の (POST リクエストによる) フォームの表示では、フォームにユーザ入力が含まれている可能性があるため、キャッシュをすべきではありません。これを行うには、以下のように [[yii\widgets\FragmentCache::enabled|enabled]] オプションをセットします:
+
+```php
+if ($this->beginCache($id, ['enabled' => Yii::$app->request->isGet])) {
+
+    // ... ここに生成するコンテンツを書く ...
+
+    $this->endCache();
+}
+```
+
+
+## キャッシュのネスト <a name="nested-caching"></a>
+
+フラグメントキャッシュはネストすることができます。つまり、キャッシュされる断片を、より大きなキャッシュされる断片で囲むことができます。例えば、コメントが内側のフラグメントキャッシュ内にキャッシュされ、それらが外側のフラグメントキャッシュに記事内容と一緒にキャッシュされます。以下のコードは 2 つのフラグメントキャッシュをどのようにネストできるかを示したものです:
+
+```php
+if ($this->beginCache($id1)) {
+
+    // ...コンテンツ生成ロジック...
+
+    if ($this->beginCache($id2, $options2)) {
+
+        // ...コンテンツ生成ロジック...
+
+        $this->endCache();
+    }
+
+    // ...コンテンツ生成ロジック...
+
+    $this->endCache();
+}
+```
+
+ネストされたキャッシュには、異なるキャッシュオプションを設定することができます。 たとえば、上記の例における内側のキャッシュと外側のキャッシュに対して、異なる持続期間の値を設定する事が可能です。 これによって、外側のキャッシュでキャッシュされたデータが無効になった場合でも、内側のキャッシュが有効な内側の断片を提供することが可能になります。 しかし、その逆は真ではありません。 外側のキャッシュが有効であると判断された場合には、内側のキャッシュが無効になった後でも、外側のキャッシュが古くなったコンテンツのコピーを提供し続けます。 ネストされたキャッシュの持続時間や依存関係の設定を間違うと、無効になった内側のキャッシュデータが外側のキャッシュに残り続けることになるので、注意が必要です。
+
+
+## ダイナミックコンテンツ <a name="dynamic-content"></a>
+
+フラグメントキャッシュを使用する際、出力全体が比較的静的で、一ヶ所ないし数ヶ所だけが例外的に動的であるというような状況に遭遇します。例えば、ページ上部にはメインメニューバーと現在のユーザの名前とが一緒に表示される場合があります。他には、リクエスト毎に実行しなければいけない PHP のコードが含まれている場合(例えば、アセットバンドルを登録するためのコード)などです。この両方の問題は、いわゆる *ダイナミックコンテンツ* 機能によって解決することができます。
+
+ダイナミックコンテンツは、それがフラグメントキャッシュの中に含まれていても、キャッシュすべきではない出力の部分を意味します。コンテンツを常に動的にするためには、外側のコンテンツがキャッシュから提供されている場合でも、すべてのリクエストに対して、いくつかのPHP コードを実行することにより生成しなければいけません。
+
+以下のように、ダイナミックコンテンツを目的の場所に挿入するには、キャッシュされた断片内で [[yii\base\View::renderDynamic()]] を呼び出します。
+
+```php
+if ($this->beginCache($id1)) {
+
+    // ...コンテンツ生成ロジック...
+
+    echo $this->renderDynamic('return Yii::$app->user->identity->name;');
+
+    // ...コンテンツ生成ロジック...
+
+    $this->endCache();
+}
+```
+
+[[yii\base\View::renderDynamic()|renderDynamic()]] メソッドはパラメータとして PHP コードの一部を使用します。PHP コードの戻り値は、ダイナミックコンテンツとして扱われます。同じ PHP コードはすべてのリクエストに対して実行されますが、囲まれている断片がキャッシュから提供されているか否かは問いません。

docs/guide-ja/caching-http.md

+HTTP キャッシュ
+============
+
+前の節で説明したサーバーサイドのキャッシュに加えて、ウェブアプリケーションは、同じページコンテンツを生成し送信する時間を節約するために、クライアントサイドでもキャッシュを利用することができます。
+
+クライアントサイドのキャッシュを使用するには、レンダリング結果をキャッシュできるように、コントローラアクションのフィルタとして [[yii\filters\HttpCache]] を設定します。[[yii\filters\HttpCache]] は `GET` と `HEAD` リクエストに対してのみ動作し、また、それらのリクエストは 3 種類のキャッシュ関連の HTTP ヘッダを扱うことができます:
+
+* [[yii\filters\HttpCache::lastModified|Last-Modified]]
+* [[yii\filters\HttpCache::etagSeed|Etag]]
+* [[yii\filters\HttpCache::cacheControlHeader|Cache-Control]]
+
+
+## `Last-Modified` ヘッダ <a name="last-modified"></a>
+
+`Last-Modified` ヘッダは、クライアントがそれをキャッシュする時から、ページが変更されたかどうかを示すために、タイムスタンプを使用しています。
+
+`Last-Modified` ヘッダの送信を有効にするには [[yii\filters\HttpCache::lastModified]] プロパティを、ページの変更時間に関する UNIX タイムスタンプを返す PHP の callable 型で、以下のようなシグネチャで構成していきます。
+
+```php
+/**
+ * @param Action $action 現在扱っているアクションオブジェクト
+ * @param array $params "params" プロパティの値
+ * @return integer ページの更新時刻を表す UNIX タイムスタンプ
+ */
+function ($action, $params)
+```
+
+以下は `Last-Modified` ヘッダを使用する例です:
+
+```php
+public function behaviors()
+{
+    return [
+        [
+            'class' => 'yii\filters\HttpCache',
+            'only' => ['index'],
+            'lastModified' => function ($action, $params) {
+                $q = new \yii\db\Query();
+                return $q->from('post')->max('updated_at');
+            },
+        ],
+    ];
+}
+```
+
+上記のコードは `index` アクションでのみ HTTP キャッシュを有効にしている状態です。投稿の最終更新時刻に基づいて `Last-Modified` を生成する必要があります。ブラウザが初めて `index` ページにアクセスすると、ページはサーバ上で生成されブラウザに送信されます。もしブラウザが再度同じページにアクセスし、その期間中に投稿に変更がない場合は、ブラウザはクライアントサイドにキャッシュしたものを使用するので、サーバはページを再生成することはありません。その結果、サーバサイドのレンダリング処理とページコンテンツの送信は両方ともスキップされます。
+
+
+## `ETag` ヘッダ <a name="etag"></a>
+
+"Entity Tag" (略して `ETag`) ヘッダはページコンテンツを表すためにハッシュを使用します。ページが変更された場合ハッシュも同様に変更されます。サーバサイドで生成されたハッシュとクライアントサイドで保持しているハッシュを比較することによって、ページが変更されたかどうか、また再送信するべきかどうかを決定します。
+
+`ETag` ヘッダの送信を有効にするには [[yii\filters\HttpCache::etagSeed]] プロパティを設定します。プロパティは ETag のハッシュを生成するためのシードを返す PHP の callable 型で、以下のようなシグネチャで構成していきます。
+
+```php
+/**
+ * @param Action $action 現在扱っているアクションオブジェクト
+ * @param array $params "params" プロパティの値
+ * @return string ETag のハッシュを生成するためのシードとして使用する文字列
+ */
+function ($action, $params)
+```
+
+以下は `ETag` ヘッダを使用している例です:
+
+```php
+public function behaviors()
+{
+    return [
+        [
+            'class' => 'yii\filters\HttpCache',
+            'only' => ['view'],
+            'etagSeed' => function ($action, $params) {
+                $post = $this->findModel(\Yii::$app->request->get('id'));
+                return serialize([$post->title, $post->content]);
+            },
+        ],
+    ];
+}
+```
+
+上記のコードは `view` アクションでのみ HTTP キャッシュを有効にしている状態です。リクエストされた投稿のタイトルとコンテンツに基づいて HTTP の `Etag` ヘッダを生成しています。ブラウザが初めて `view` ページにアクセスするときに、ページがサーバ上で生成されブラウザに送信されます。ブラウザが再度同じページにアクセスし、投稿のタイトルやコンテンツに変更がない場合には、サーバはページを再生成せず、ブラウザはクライアントサイトにキャッシュしたものを使用します。その結果、サーバサイドのレンダリング処理とページコンテンツ送信の両方ともスキップされます。
+
+ETag は `Last-Modified` ヘッダよりも複雑かつ、より正確なキャッシング方式を可能にします。例えば、サイトが別のテーマに切り替わった場合には ETag を無効化する、といったことができます。
+
+ETag はリクエスト毎に再評価する必要があるため、負荷の高いもの生成すると `HttpCache` の本来の目的を損なって不必要なオーバーヘッドが生じる場合があるので、ページのコンテンツが変更されたときにキャッシュを無効化するための式は単純なものを指定するようにして下さい。
+
+> 注意: [RFC 7232](http://tools.ietf.org/html/rfc7232#section-2.4) に準拠して `Etag` と `Last-Modified` ヘッダの両方を設定した場合、`HttpCache` はその両方とも送信します。また、もし `If-None-Match` ヘッダと `If-Modified-Since` ヘッダの両方を送信した場合は前者のみが尊重されます。
+
+## `Cache-Control` ヘッダ <a name="cache-control"></a>
+
+`Cache-Control` ヘッダはページのための一般的なキャッシュポリシーを指定します。ヘッダ値に [[yii\filters\HttpCache::cacheControlHeader]] プロパティを設定することで、それを送ることができます。デフォルトでは、以下のヘッダーが送信されます:
+
+```
+Cache-Control: public, max-age=3600
+```
+
+## セッションキャッシュリミッタ<a name="session-cache-limiter"></a>
+
+ページでセッションを使用している場合、PHP はいくつかのキャッシュ関連の HTTP ヘッダ(PHP の設定ファイル内で指定されている session.cache_limiter など)を自動的に送信します。これらのヘッダは `HttpCache` で妨害したり、必要なキャッシュを無効にしたりできます。この動作を変更したい場合は [[yii\filters\HttpCache::sessionCacheLimiter]] プロパティを設定します。プロパティには `public`、`private`、`private_no_expire`、そして `nocache` などの文字列の値を使用することができます。これらの値についての説明は [session_cache_limiter()](http://www.php.net/manual/ja/function.session-cache-limiter.php) を参照してください。
+
+
+## SEO への影響 <a name="seo-implications"></a>
+
+検索エンジンのボットはキャッシュヘッダを尊重する傾向があります。 クローラの中には、一定期間内に処理するドメインごとのページ数に制限を持っているものもあるため、キャッシュヘッダを導入して、処理の必要があるページ数を減らしてやると、サイトのインデックスの作成を促進できるかも知れません。

docs/guide-ja/caching-overview.md

+キャッシュ
+=======
+
+ウェブアプリケーションのパフォーマンスを向上させるための簡単で効果的な方法としてキャッシュというものがあります。比較的静的なデータをキャッシュに格納し、必要に応じてキャッシュからそれらを取得することによって、アプリケーションは一からデータを生成するのに必要な時間を節約することができます。
+
+キャッシュはさまざまなレベルのものを、アプリケーション内のさまざまな場所で使用することができます。例えばサーバサイドでの低いレベルでは、データベースから取得した最新の記事情報リストのような基本的なデータを格納するために使用したり、高いレベルでは、レンダリング結果の一部分、最新の記事であったり、またウェブページ全体を格納するためなどにも使用できます。クライアントサイドでは、ブラウザのキャッシュに最近訪れたことのあるページの内容を格納するために HTTP キャッシュを使用することもできます。
+
+Yii では以下のリストに挙げられているキャッシュ機構をサポートしています:
+
+* [データキャッシュ](caching-data.md)
+* [フラグメントキャッシュ](caching-fragment.md)
+* [ページキャッシュ](caching-page.md)
+* [HTTP キャッシュ](caching-http.md)

docs/guide-ja/caching-page.md

+ページキャッシュ
+============
+
+ページキャッシュはサーバサイドでページ全体のコンテンツをキャッシュすることを言います。あとで、同じページに再度リクエストがあった場合、その内容を一から再び生成させるのではなく、キャッシュから提供するようにします。
+
+ページキャッシュは [[yii\filters\PageCache]]、 [アクションフィルタ](structure-filters.md) によってサポートされています。これは、コントローラクラスで以下のように使用することができます：
+
+```php
+public function behaviors()
+{
+    return [
+        [
+            'class' => 'yii\filters\PageCache',
+            'only' => ['index'],
+            'duration' => 60,
+            'variations' => [
+                \Yii::$app->language,
+            ],
+            'dependency' => [
+                'class' => 'yii\caching\DbDependency',
+                'sql' => 'SELECT COUNT(*) FROM post',
+            ],
+        ],
+    ];
+}
+```
+
+上記のコードは、ページキャッシュが `index` アクションのみで使用され、そのページのコンテンツは最大 60 秒間キャッシュし、現在のアプリケーションの言語によって変化し、投稿の総数に変化があった場合キャッシュされたページが無効になる、ということを示しています。
+
+見てわかるように、ページキャッシュは [フラグメントキャッシュ](caching-fragment.md) ととてもよく似ています。それらは両方とも `duration`、`dependencies`、`variations`、そして `enabled` などのオプションをサポートしています。主な違いとしては、ページキャッシュは [アクションフィルタ](structure-filters.md) として、フラグメントキャッシュは [ウィジェット](structure-widgets.md) として実装されているということです。
+
+また、ページキャッシュと一緒に [ダイナミックコンテンツ](caching-fragment.md#dynamic-content) だけでなく [フラグメントキャッシュ](caching-fragment.md) も使用することができます。

docs/internals/translation-teams.md

@@ -39,6 +39,7 @@ Japanese
 -------
 
 - Nobuo Kihara 木原伸夫, [@softark](https://github.com/softark), softark@gmail.com
+- Tomoki Morita, [@jamband](https://github.com/jamband), tmsongbooks215@gmail.com
 
 Russian
 -------