Merge pull request yiisoft#16011 from yiichina/doc

zh-CN doc translation

docs/guide-zh-CN/caching-fragment.md

@@ -1,7 +1,9 @@
 片段缓存
 ================
 
-片段缓存指的是缓存页面内容中的某个片段。例如，一个页面显示了逐年销售额的摘要表格，可以把表格缓存下来，以消除每次请求都要重新生成表格的耗时。片段缓存是基于[数据缓存](caching-data.md)实现的。
+片段缓存指的是缓存页面内容中的某个片段。例如，一个页面显示了逐年销售额的摘要表格，
+可以把表格缓存下来，以消除每次请求都要重新生成表格的耗时。
+片段缓存是基于[数据缓存](caching-data.md)实现的。
 
 在[视图](structure-views.md)中使用以下结构启用片段缓存：
 
@@ -14,18 +16,27 @@ if ($this->beginCache($id)) {
 }
 ```
 
-调用 [[yii\base\View::beginCache()|beginCache()]] 和 [[yii\base\View::endCache()|endcache()]] 方法包裹内容生成逻辑。如果缓存中存在该内容，[[yii\base\View::beginCache()|beginCache()]] 方法将渲染内容并返回 false，因此将跳过内容生成逻辑。否则，内容生成逻辑被执行，一直执行到 [[yii\base\View::endCache()|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` 标记。
+和[数据缓存](caching-data.md)一样，每个片段缓存也需要全局唯一的 `$id` 标记。
 
 
 ## 缓存选项 <span id="caching-options"></span>
 
-如果要为片段缓存指定额外配置项，请通过向 [[yii\base\View::beginCache()|beginCache()]] 方法第二个参数传递配置数组。在框架内部，该数组将被用来配置一个 [[yii\widget\FragmentCache]] 小部件用以实现片段缓存功能。
+如果要为片段缓存指定额外配置项，
+请通过向 [[yii\base\View::beginCache()|beginCache()]] 
+方法第二个参数传递配置数组。在框架内部，该数组将被用来配置一个 [[yii\widget\FragmentCache]] 
+小部件用以实现片段缓存功能。
 
 ### 过期时间（duration） <span id="duration"></span>
 
-或许片段缓存中最常用的一个配置选项就是 [[yii\widgets\FragmentCache::duration|duration]] 了。它指定了内容被缓存的秒数。以下代码缓存内容最多一小时：
+或许片段缓存中最常用的一个配置选项就是 [[yii\widgets\FragmentCache::duration|duration]] 了。
+它指定了内容被缓存的秒数。
+以下代码缓存内容最多一小时：
 
 ```php
 if ($this->beginCache($id, ['duration' => 3600])) {
@@ -36,14 +47,17 @@ if ($this->beginCache($id, ['duration' => 3600])) {
 }
 ```
 
-如果该选项未设置，则默认为 0，永不过期。
+If the option is not set, it will take the default value 60, which means the cached content will expire in 60 seconds.
 
 
 ### 依赖 <span id="dependencies"></span>
 
-和[[数据缓存]](caching-data.md)一样，片段缓存的内容一样可以设置缓存依赖。例如一段被缓存的文章，是否重新缓存取决于它是否被修改过。
+和[数据缓存](caching-data.md)一样，片段缓存的内容一样可以设置缓存依赖。
+例如一段被缓存的文章，是否重新缓存取决于它是否被修改过。
 
-通过设置 [[yii\widgets\FragmentCache::dependency|dependency]] 选项来指定依赖，该选项的值可以是一个 [[yii\caching\Dependency]] 类的派生类，也可以是创建缓存对象的配置数组。以下代码指定了一个片段缓存，它依赖于 `update_at` 字段是否被更改过的。
+通过设置 [[yii\widgets\FragmentCache::dependency|dependency]] 选项来指定依赖，
+该选项的值可以是一个 [[yii\caching\Dependency]] 类的派生类，也可以是创建缓存对象的配置数组。
+以下代码指定了一个片段缓存，它依赖于 `update_at` 字段是否被更改过的。
 
 ```php
 $dependency = [
@@ -62,9 +76,13 @@ if ($this->beginCache($id, ['dependency' => $dependency])) {
 
 ### 变化 <span id="variations"></span>
 
-缓存的内容可能需要根据一些参数的更改而变化。例如一个 Web 应用支持多语言，同一段视图代码也许需要生成多个语言的内容。因此可以设置缓存根据应用当前语言而变化。
+缓存的内容可能需要根据一些参数的更改而变化。
+例如一个 Web 应用支持多语言，同一段视图代码也许需要生成多个语言的内容。
+因此可以设置缓存根据应用当前语言而变化。
 
-通过设置 [[yii\widgets\FragmentCache::variations|variations]] 选项来指定变化，该选项的值应该是一个标量，每个标量代表不同的变化系数。例如设置缓存根据当前语言而变化可以用以下代码：
+通过设置 [[yii\widgets\FragmentCache::variations|variations]] 选项来指定变化，
+该选项的值应该是一个标量，每个标量代表不同的变化系数。
+例如设置缓存根据当前语言而变化可以用以下代码：
 
 ```php
 if ($this->beginCache($id, ['variations' => [Yii::$app->language]])) {
@@ -78,7 +96,10 @@ if ($this->beginCache($id, ['variations' => [Yii::$app->language]])) {
 
 ### 开关 <span id="toggling-caching"></span>
 
-有时你可能只想在特定条件下开启片段缓存。例如，一个显示表单的页面，可能只需要在初次请求时缓存表单（通过 GET 请求）。随后请求所显示（通过 POST 请求）的表单不该使用缓存，因为此时表单中可能包含用户输入内容。鉴于此种情况，可以使用 [[yii\widgets\FragmentCache::enabled|enabled]] 选项来指定缓存开关，如下所示：
+有时你可能只想在特定条件下开启片段缓存。例如，一个显示表单的页面，可能只需要在初次请求时缓存表单（通过 GET 请求）。
+随后请求所显示（通过 POST 请求）的表单不该使用缓存，因为此时表单中可能包含用户输入内容。
+鉴于此种情况，可以使用 [[yii\widgets\FragmentCache::enabled|enabled]] 选项来指定缓存开关，
+如下所示：
 
 ```php
 if ($this->beginCache($id, ['enabled' => Yii::$app->request->isGet])) {
@@ -92,7 +113,9 @@ if ($this->beginCache($id, ['enabled' => Yii::$app->request->isGet])) {
 
 ## 缓存嵌套 <span id="nested-caching"></span>
 
-片段缓存可以被嵌套使用。一个片段缓存可以被另一个包裹。例如，评论被缓存在里层，同时整个评论的片段又被缓存在外层的文章中。以下代码展示了片段缓存的嵌套使用：
+片段缓存可以被嵌套使用。一个片段缓存可以被另一个包裹。
+例如，评论被缓存在里层，同时整个评论的片段又被缓存在外层的文章中。
+以下代码展示了片段缓存的嵌套使用：
 
 ```php
 if ($this->beginCache($id1)) {
@@ -112,18 +135,28 @@ if ($this->beginCache($id1)) {
 }
 ```
 
-可以为嵌套的缓存设置不同的配置项。例如，内层缓存和外层缓存使用不同的过期时间。甚至当外层缓存的数据过期失效了，内层缓存仍然可能提供有效的片段缓存数据。但是，反之则不然。如果外层片段缓存没有过期而被视为有效，此时即使内层片段缓存已经失效，它也将继续提供同样的缓存副本。因此，你必须谨慎处理缓存嵌套中的过期时间和依赖，否则外层的片段很有可能返回的是不符合你预期的失效数据。
-
+可以为嵌套的缓存设置不同的配置项。例如，内层缓存和外层缓存使用不同的过期时间。
+甚至当外层缓存的数据过期失效了，内层缓存仍然可能提供有效的片段缓存数据。
+但是，反之则不然。如果外层片段缓存没有过期而被视为有效，
+此时即使内层片段缓存已经失效，它也将继续提供同样的缓存副本。
+因此，你必须谨慎处理缓存嵌套中的过期时间和依赖，
+否则外层的片段很有可能返回的是不符合你预期的失效数据。
 > 译注：外层的失效时间应该短于内层，外层的依赖条件应该低于内层，以确保最小的片段，返回的是最新的数据。
 
-
 ## 动态内容 <span id="dynamic-content"></span>
 
-使用片段缓存时，可能会遇到一大段较为静态的内容中有少许动态内容的情况。例如，一个显示着菜单栏和当前用户名的页面头部。还有一种可能是缓存的内容可能包含每次请求都需要执行的 PHP 代码（例如注册资源包的代码）。这两个问题都可以使用**动态内容**功能解决。
+使用片段缓存时，可能会遇到一大段较为静态的内容中有少许动态内容的情况。
+例如，一个显示着菜单栏和当前用户名的页面头部。
+还有一种可能是缓存的内容可能包含每次请求
+都需要执行的 PHP 代码（例如注册资源包的代码）。
+这两个问题都可以使用**动态内容**功能解决。
 
-动态内容的意思是这部分输出的内容不该被缓存，即便是它被包裹在片段缓存中。为了使内容保持动态，每次请求都执行 PHP 代码生成，即使这些代码已经被缓存了。
+动态内容的意思是这部分输出的内容不该被缓存，即便是它被包裹在片段缓存中。
+为了使内容保持动态，每次请求都执行 PHP 代码生成，
+即使这些代码已经被缓存了。
 
-可以在片段缓存中调用 [[yii\base\View::renderDynamic()]] 去插入动态内容，如下所示：
+可以在片段缓存中调用 [[yii\base\View::renderDynamic()]] 去插入动态内容，
+如下所示：
 
 ```php
 if ($this->beginCache($id1)) {
@@ -138,4 +171,7 @@ if ($this->beginCache($id1)) {
 }
 ```
 
-[[yii\base\View::renderDynamic()|renderDynamic()]] 方法接受一段 PHP 代码作为参数。代码的返回值被看作是动态内容。这段代码将在每次请求时都执行，无论其外层的片段缓存是否被存储。
+[[yii\base\View::renderDynamic()|renderDynamic()]] 方法接受一段 PHP 代码作为参数。
+代码的返回值被看作是动态内容。这段代码将在每次请求时都执行，
+无论其外层的片段缓存是否被存储。
+

docs/guide-zh-CN/caching-http.md

@@ -1,9 +1,12 @@
 HTTP 缓存
 ============
 
-除了前面章节讲到的服务器端缓存外， Web 应用还可以利用客户端缓存去节省相同页面内容的生成和传输时间。
+除了前面章节讲到的服务器端缓存外， Web 应用还可以利用客户端缓存
+去节省相同页面内容的生成和传输时间。
 
-通过配置 [[yii\filters\HttpCache]] 过滤器，控制器操作渲染的内容就能缓存在客户端。[[yii\filters\HttpCache|HttpCache]] 过滤器仅对 `GET` 和 `HEAD` 请求生效，它能为这些请求设置三种与缓存有关的 HTTP 头。
+通过配置 [[yii\filters\HttpCache]] 过滤器，控制器操作渲染的内容就能缓存在客户端。
+[[yii\filters\HttpCache|HttpCache]] 过滤器仅对 `GET` 和 `HEAD` 请求生效，
+它能为这些请求设置三种与缓存有关的 HTTP 头。
 
 * [[yii\filters\HttpCache::lastModified|Last-Modified]]
 * [[yii\filters\HttpCache::etagSeed|Etag]]
@@ -14,11 +17,13 @@ HTTP 缓存
 
 `Last-Modified` 头使用时间戳标明页面自上次客户端缓存后是否被修改过。
 
-通过配置 [[yii\filters\HttpCache::lastModified]] 属性向客户端发送 `Last-Modified` 头。该属性的值应该为 PHP callable 类型，返回的是页面修改时的 Unix 时间戳。该 callable 的参数和返回值应该如下：
+通过配置 [[yii\filters\HttpCache::lastModified]] 属性向客户端发送 `Last-Modified` 头。
+该属性的值应该为 PHP callable 类型，返回的是页面修改时的 Unix 时间戳。
+该 callable 的参数和返回值应该如下：
 
 ```php
 /**
- * @param Action $action 当前处理的操作对象
+ * @param Action $action 当前处理的动作对象
  * @param array $params “params” 属性的值
  * @return int 页面修改时的 Unix 时间戳
  */
@@ -43,18 +48,27 @@ public function behaviors()
 }
 ```
 
-上述代码表明 HTTP 缓存只在 `index` 操作时启用。它会基于页面最后修改时间生成一个 `Last-Modified` HTTP 头。当浏览器第一次访问 `index` 页时，服务器将会生成页面并发送至客户端浏览器。之后客户端浏览器在页面没被修改期间访问该页，服务器将不会重新生成页面，浏览器会使用之前客户端缓存下来的内容。因此服务端渲染和内容传输都将省去。
+上述代码表明 HTTP 缓存只在 `index` 操作时启用。
+它会基于页面最后修改时间生成一个 `Last-Modified` HTTP 头。
+当浏览器第一次访问 `index` 页时，服务器将会生成页面并发送至客户端浏览器。
+之后客户端浏览器在页面没被修改期间访问该页，
+服务器将不会重新生成页面，浏览器会使用之前客户端缓存下来的内容。
+因此服务端渲染和内容传输都将省去。
 
 
 ## `ETag` 头 <span id="etag"></span>
 
-“Entity Tag”（实体标签，简称 ETag）使用一个哈希值表示页面内容。如果页面被修改过，哈希值也会随之改变。通过对比客户端的哈希值和服务器端生成的哈希值，浏览器就能判断页面是否被修改过，进而决定是否应该重新传输内容。
+“Entity Tag”（实体标签，简称 ETag）使用一个哈希值表示页面内容。如果页面被修改过，
+哈希值也会随之改变。通过对比客户端的哈希值和服务器端生成的哈希值，
+浏览器就能判断页面是否被修改过，进而决定是否应该重新传输内容。
 
-通过配置 [[yii\filters\HttpCache::etagSeed]] 属性向客户端发送 `ETag` 头。该属性的值应该为 PHP callable 类型，返回的是一段种子字符用来生成 ETag 哈希值。该 callable 的参数和返回值应该如下：
+通过配置 [[yii\filters\HttpCache::etagSeed]] 属性向客户端发送 `ETag` 头。
+该属性的值应该为 PHP callable 类型，返回的是一段种子字符用来生成 ETag 哈希值。
+该 callable 的参数和返回值应该如下：
 
 ```php
 /**
- * @param Action $action 当前处理的操作对象
+ * @param Action $action 当前处理的动作对象
  * @param array $params “params” 属性的值
  * @return string 一段种子字符用来生成 ETag 哈希值
  */
@@ -79,31 +93,51 @@ public function behaviors()
 }
 ```
 
-上述代码表明 HTTP 缓存只在 `view` 操作时启用。它会基于用户请求的标题和内容生成一个 `ETag` HTTP 头。当浏览器第一次访问 `view` 页时，服务器将会生成页面并发送至客户端浏览器。之后客户端浏览器标题和内容没被修改在期间访问该页，服务器将不会重新生成页面，浏览器会使用之前客户端缓存下来的内容。因此服务端渲染和内容传输都将省去。
+上述代码表明 HTTP 缓存只在 `view` 操作时启用。
+它会基于用户请求的标题和内容生成一个 `ETag` HTTP 头。
+当浏览器第一次访问 `view` 页时，服务器将会生成页面并发送至客户端浏览器。
+之后客户端浏览器标题和内容没被修改在期间访问该页，服务器将不会重新生成页面，
+浏览器会使用之前客户端缓存下来的内容。
+因此服务端渲染和内容传输都将省去。
 
-ETag 相比 `Last-Modified` 能实现更复杂和更精确的缓存策略。例如，当站点切换到另一个主题时可以使 ETag 失效。
+ETag 相比 `Last-Modified` 能实现更复杂和更精确的缓存策略。
+例如，当站点切换到另一个主题时可以使 ETag 失效。
 
-复杂的 Etag 生成种子可能会违背使用 `HttpCache` 的初衷而引起不必要的性能开销，因为响应每一次请求都需要重新计算 Etag。请试着找出一个最简单的表达式去触发 Etag 失效。
-
-
-> Note: 为了遵循 [RFC 7232（HTTP 1.1 协议）](http://tools.ietf.org/html/rfc7232#section-2.4)，如果同时配置了 `ETag` 和 `Last-Modified` 头，`HttpCache` 将会同时发送它们。并且如果客户端同时发送 `If-None-Match` 头和 `If-Modified-Since` 头，则只有前者会被接受。
+复杂的 Etag 生成种子可能会违背使用 `HttpCache` 的初衷而引起不必要的性能开销，
+因为响应每一次请求都需要重新计算 Etag。
+请试着找出一个最简单的表达式去触发 Etag 失效。
 
+> 注意：为了遵循 [RFC 7232（HTTP 1.1 协议）](http://tools.ietf.org/html/rfc7232#section-2.4)，
+如果同时配置了 `ETag` 和 `Last-Modified` 头，`HttpCache` 将会同时发送它们。
+并且如果客户端同时发送 `If-None-Match` 头和 `If-Modified-Since` 头，
+则只有前者会被接受。
 
 
 ## `Cache-Control` 头 <span id="cache-control"></span>
 
-`Cache-Control` 头指定了页面的常规缓存策略。可以通过配置 [[yii\filters\HttpCache::cacheControlHeader]] 属性发送相应的头信息。默认发送以下头：
+`Cache-Control` 头指定了页面的常规缓存策略。
+可以通过配置 [[yii\filters\HttpCache::cacheControlHeader]] 
+属性发送相应的头信息。默认发送以下头：
 
 ```
 Cache-Control: public, max-age=3600
 ```
 
 ## 会话缓存限制器 <span id="session-cache-limiter"></span>
 
-当页面使 session 时，PHP 将会按照 PHP.INI 中所设置的 `session.cache_limiter` 值自动发送一些缓存相关的 HTTP 头。这些 HTTP 头有可能会干扰你原本设置的 `HttpCache` 或让其失效。为了避免此问题，默认情况下 `HttpCache` 禁止自动发送这些头。想改变这一行为，可以配置 [[yii\filters\HttpCache::sessionCacheLimiter]] 属性。该属性接受一个字符串值，包括 `public`，`private`，`private_no_expire`，和 `nocache`。请参考 PHP 手册中的[缓存限制器](http://www.php.net/manual/en/function.session-cache-limiter.php)了解这些值的含义。
+当页面使 session 时，PHP 将会按照 PHP.INI 
+中所设置的 `session.cache_limiter` 值自动发送一些缓存相关的 HTTP 头。
+这些 HTTP 头有可能会干扰你原本设置的 `HttpCache` 或让其失效。
+为了避免此问题，默认情况下 `HttpCache` 禁止自动发送这些头。
+想改变这一行为，可以配置 [[yii\filters\HttpCache::sessionCacheLimiter]] 属性。
+该属性接受一个字符串值，包括 `public`，`private`，`private_no_expire`，和 `nocache`。
+请参考 PHP 手册中的[缓存限制器](http://www.php.net/manual/en/function.session-cache-limiter.php)
+了解这些值的含义。
 
 
 ## SEO 影响 <span id="seo-implications"></span>
 
-搜索引擎趋向于遵循站点的缓存头。因为一些爬虫的抓取频率有限制，启用缓存头可以可以减少重复请求数量，增加爬虫抓取效率（译者：大意如此，但搜索引擎的排名规则不了解，好的缓存策略应该是可以为用户体验加分的）。
+搜索引擎趋向于遵循站点的缓存头。因为一些爬虫的抓取频率有限制，
+启用缓存头可以可以减少重复请求数量，增加爬虫抓取效率
+（译者：大意如此，但搜索引擎的排名规则不了解，好的缓存策略应该是可以为用户体验加分的）。