Merge pull request #19 from fengyh/master

翻译： security-authorization.md
9 years ago · 96793faef3
2 changed files with 726 additions and 205 deletions
--- a/docs/guide-zh-CN/security-authorization.md
+++ b/docs/guide-zh-CN/security-authorization.md
@ -0,0 +1,521 @@
+授权
+=============
+
+授权是指验证用户是否允许做某件事的过程。Yii提供两种授权方法：
+存取控制过滤器（ACF）和基于角色的存取控制（RBAC）。
+
+
+## 存取控制过滤器 <span id="access-control-filter"></span>
+
+存取控制过滤器（ACF）是一种通过 [[yii\filters\AccessControl]] 类来实现的简单授权方法，
+非常适用于仅需要简单的存取控制的应用。正如其名称所指，ACF 是一个种行动（action）过滤器
+[filter](structure-filters.md)，可在控制器或者模块中使用。当一个用户请求一个 action 时，
+ACF会检查 [[yii\filters\AccessControl::rules|access rules]] 列表，判断该用户是否允许执
+行所请求的action。（译者注： `action` 在本文中视情况翻译为`行动`、`操作`、`方法`等）
+
+下述代码展示如何在 `site` 控制器中使用 ACF：
+
+```php
+use yii\web\Controller;
+use yii\filters\AccessControl;
+
+class SiteController extends Controller
+{
+    public function behaviors()
+    {
+        return [
+            'access' => [
+                'class' => AccessControl::className(),
+                'only' => ['login', 'logout', 'signup'],
+                'rules' => [
+                    [
+                        'allow' => true,
+                        'actions' => ['login', 'signup'],
+                        'roles' => ['?'],
+                    ],
+                    [
+                        'allow' => true,
+                        'actions' => ['logout'],
+                        'roles' => ['@'],
+                    ],
+                ],
+            ],
+        ];
+    }
+    // ...
+}
+```
+
+上面的代码中 ACF 以行为 (behavior) 的形式附加到 `site` 控制器。
+这就是很典型的使用行动过滤器的方法。 `only` 选项指明 ACF 应当只
+对 `login`， `logout` 和 `signup` 方法起作用。所有其它的 `site` 
+控制器中的方法不受存取控制的限制。 `rules` 选项列出了 [[yii\filters\AccessRule|存取规则 (access rules)]]，解读如下：
+
+- 允许所有访客（还未经认证的用户）执行 `login` 和 `signup` 操作。 
+  `roles` 选项包含的问号 `?` 是一个特殊的标识，代表”访客用户”。
+- 允许已认证用户执行 `logout` 操作。`@`是另一个特殊标识，
+  代表”已认证用户”。
+
+ACF 自顶向下逐一检查存取规则，直到找到一个与当前
+欲执行的操作相符的规则。 然后该匹配规则中的 `allow` 
+选项的值用于判定该用户是否获得授权。如果没有找到匹配的规则，
+意味着该用户没有获得授权。（译者注： `only` 中没有列出的操作，将无条件获得授权）
+
+当 ACF 判定一个用户没有获得执行当前操作的授权时，它的默认处理是：
+
+* 如果该用户是访客，将调用 [[yii\web\User::loginRequired()]] 将用户的浏览器重定向到登录页面。
+* 如果该用户是已认证用户，将抛出一个 [[yii\web\ForbiddenHttpException]] 异常。
+
+你可以通过配置 [[yii\filters\AccessControl::denyCallback]] 属性定制该行为：
+
+```php
+[
+    'class' => AccessControl::className(),
+    ...
+    'denyCallback' => function ($rule, $action) {
+        throw new \Exception('You are not allowed to access this page');
+    }
+]
+```
+
+[[yii\filters\AccessRule|Access rules]] 支持很多的选项。下列是所支持选项的总览。
+你可以派生 [[yii\filters\AccessRule]] 来创建自定义的存取规则类。
+
+ * [[yii\filters\AccessRule::allow|allow]]： 指定该规则是 "允许" 还是 "拒绝" 。（译者注：true是允许，false是拒绝）
+
+ * [[yii\filters\AccessRule::actions|actions]]：指定该规则用于匹配哪些操作。
+   它的值应该是操作方法的ID数组。匹配比较是大小写敏感的。如果该选项为空，或者不使用该选项，
+   意味着当前规则适用于所有的操作。
+
+ * [[yii\filters\AccessRule::controllers|controllers]]：指定该规则用于匹配哪些控制器。
+   它的值应为控制器ID数组。匹配比较是大小写敏感的。如果该选项为空，或者不使用该选项，
+   则意味着当前规则适用于所有的操作。（译者注：这个选项一般是在控制器的自定义父类中使用才有意义）
+
+ * [[yii\filters\AccessRule::roles|roles]]：指定该规则用于匹配哪些用户角色。
+   系统自带两个特殊的角色，通过 [[yii\web\User::isGuest]] 来判断：
+
+     - `?`： 用于匹配访客用户 （未经认证）
+     - `@`： 用于匹配已认证用户
+
+   使用其他角色名时，将触发调用 [[yii\web\User::can()]]，这时要求 RBAC 的支持 （在下一节中阐述）。
+   如果该选项为空或者不使用该选项，意味着该规则适用于所有角色。
+
+ * [[yii\filters\AccessRule::ips|ips]]：指定该规则用于匹配哪些 [[yii\web\Request::userIP|客户端IP地址]] 。
+   IP 地址可在其末尾包含通配符 `*` 以匹配一批前缀相同的IP地址。
+   例如，`192.168.*` 匹配所有 `192.168.` 段的IP地址。
+   如果该选项为空或者不使用该选项，意味着该规则适用于所有角色。
+
+ * [[yii\filters\AccessRule::verbs|verbs]]：指定该规则用于匹配哪种请求方法（例如`GET`，`POST`）。
+   这里的匹配大小写不敏感。
+
+ * [[yii\filters\AccessRule::matchCallback|matchCallback]]：指定一个PHP回调函数用于
+   判定该规则是否满足条件。（译者注：此处的回调函数是匿名函数）
+
+ * [[yii\filters\AccessRule::denyCallback|denyCallback]]: 指定一个PHP回调函数，
+   当这个规则不满足条件时该函数会被调用。（译者注：此处的回调函数是匿名函数）
+
+以下例子展示了如何使用 `matchCallback` 选项，
+可使你设计任意的访问权限检查逻辑：
+
+```php
+use yii\filters\AccessControl;
+
+class SiteController extends Controller
+{
+    public function behaviors()
+    {
+        return [
+            'access' => [
+                'class' => AccessControl::className(),
+                'only' => ['special-callback'],
+                'rules' => [
+                    [
+                        'actions' => ['special-callback'],
+                        'allow' => true,
+                        'matchCallback' => function ($rule, $action) {
+                            return date('d-m') === '31-10';
+                        }
+                    ],
+                ],
+            ],
+        ];
+    }
+
+    // 匹配的回调函数被调用了！这个页面只有每年的10月31号能访问（译者注：原文在这里说该方法是回调函数不确切，读者不要和 `matchCallback` 的值即匿名的回调函数混淆理解）。
+    public function actionSpecialCallback()
+    {
+        return $this->render('happy-halloween');
+    }
+}
+```
+
+
+## 基于角色的存取控制 （RBAC） <span id="rbac"></span>
+
+基于角色的存取控制 （RBAC） 提供了一个简单而强大的集中式存取控制机制。
+详细的关于 RBAC 和诸多传统的存取控制方案对比的详情，请参阅
+[Wikipedia](http://en.wikipedia.org/wiki/Role-based_access_control)。
+
+Yii 实现了通用的分层的 RBAC，遵循的模型是 [NIST RBAC model](http://csrc.nist.gov/rbac/sandhu-ferraiolo-kuhn-00.pdf).
+它通过 [[yii\rbac\ManagerInterface|authManager]] [application component](structure-application-components.md) 提供 RBAC 功能。
+
+使用 RBAC 涉及到两部分工作。第一部分是建立授权数据，
+而第二部分是使用这些授权数据在需要的地方执行检查。
+
+为方便后面的讲述，这里先介绍一些 RBAC 的基本概念。
+
+
+### 基本概念 <span id="basic-concepts"></span>
+
+角色是 *权限* 的集合 （例如：建贴、改贴）。一个角色
+可以指派给一个或者多个用户。要检查某用户是否有一个特定的权限，
+系统会检查该包含该权限的角色是否指派给了该用户。
+
+可以用一个规则 *rule* 与一个角色或者权限关联。一个规则用一段代码代表，
+规则的执行是在检查一个用户是否满足这个角色或者权限时进行的。例如，"改帖" 的权限
+可以使用一个检查该用户是否是帖子的创建者的规则。权限检查中，如果该用户
+不是帖子创建者，那么他（她）将被认为不具有 "改帖"的权限。
+
+角色和权限都可以按层次组织。特定情况下，一个角色可能由其他角色或权限构成，
+而权限又由其他的权限构成。Yii 实现了所谓的 *局部顺序* 的层次结构，包含更多的特定的 *树* 的层次。
+一个角色可以包含一个权限，反之则不行。（译者注：可理解为角色在上方，权限在下方，从上到下如果碰到权限那么再往下不能出现角色）
+
+
+### 配置 RBAC <span id="configuring-rbac"></span>
+
+在开始定义授权数据和执行存取检查之前，需要先配置应用组件 [[yii\base\Application::authManager|authManager]] 。 
+Yii 提供了两套授权管理器： [[yii\rbac\PhpManager]] 
+和 [[yii\rbac\DbManager]]。前者使用 PHP 脚本存放授权数据，
+而后者使用数据库存放授权数据。 如果你的应用不要求大量的动态角色和权限管理，
+你可以考虑使用前者。
+
+
+#### 使用 `PhpManager` <span id="using-php-manager"></span>
+
+以下代码展示使用 [[yii\rbac\PhpManager]] 时如何在应用配置文件中配置 `authManager`：
+
+```php
+return [
+    // ...
+    'components' => [
+        'authManager' => [
+            'class' => 'yii\rbac\PhpManager',
+        ],
+        // ...
+    ],
+];
+```
+
+现在可以通过 `\Yii::$app->authManager` 访问 `authManager` 。
+
+[[yii\rbac\PhpManager]] 默认将 RBAC 数据保存在 `@app/rbac` 目录下的文件中。
+如果权限层次数据在运行时会被修改，需确保WEB服务器进程对该目录和其中的文件有写权限。
+
+
+#### 使用 `DbManager` <span id="using-db-manager"></span>
+
+以下代码展示使用 [[yii\rbac\DbManager]] 时如何在应用配置文件中配置 `authManager`：
+
+```php
+return [
+    // ...
+    'components' => [
+        'authManager' => [
+            'class' => 'yii\rbac\DbManager',
+        ],
+        // ...
+    ],
+];
+```
+
+`DbManager` 使用4个数据库表存放它的数据：
+
+- [[yii\rbac\DbManager::$itemTable|itemTable]]： 该表存放授权条目（译者注：即角色和权限）。默认表名为 "auth_item" 。
+- [[yii\rbac\DbManager::$itemChildTable|itemChildTable]]： 该表存放授权条目的层次关系。默认表名为 "auth_item_child"。
+- [[yii\rbac\DbManager::$assignmentTable|assignmentTable]]： 该表存放授权条目对用户的指派情况。默认表名为 "auth_assignment"。
+- [[yii\rbac\DbManager::$ruleTable|ruleTable]]： 该表存放规则。默认表名为 "auth_rule"。
+
+继续之前，你需要在数据库中创建这些表。你可以使用存放在 `@yii/rbac/migrations` 目录中的数据库迁移文件来做这件事（译者注：根据本人经验，最好是将授权数据初始化命令也写到这个 RBAC 数据库迁移文件中）：
+
+`yii migrate --migrationPath=@yii/rbac/migrations`
+
+现在可以通过 `\Yii::$app->authManager` 访问 `authManager` 。
+
+
+### 建立授权数据 <span id="generating-rbac-data"></span>
+
+所有授权数据相关的任务如下：
+
+- 定义角色和权限；
+- 建立角色和权限的关系；
+- 定义规则；
+- 将规则与角色和权限作关联；
+- 指派角色给用户。
+
+根据授权的弹性需求，上述任务可用不同的方法完成。
+
+如果你的权限层次结构不会发生改变，而且你的用户数是恒定的，你可以通过 `authManager` 
+提供的 API 创建一个 [控制台命令](tutorial-console.md#create-command) 一次性初始化授权数据：
+
+```php
+<?php
+namespace app\commands;
+
+use Yii;
+use yii\console\Controller;
+
+class RbacController extends Controller
+{
+    public function actionInit()
+    {
+        $auth = Yii::$app->authManager;
+
+        // 添加 "createPost" 权限
+        $createPost = $auth->createPermission('createPost');
+        $createPost->description = 'Create a post';
+        $auth->add($createPost);
+
+        // 添加 "updatePost" 权限
+        $updatePost = $auth->createPermission('updatePost');
+        $updatePost->description = 'Update post';
+        $auth->add($updatePost);
+
+        // 添加 "author" 角色并赋予 "createPost" 权限
+        $author = $auth->createRole('author');
+        $auth->add($author);
+        $auth->addChild($author, $createPost);
+
+        // 添加 "admin" 角色并赋予 "updatePost" 
+		// 和 "author" 权限
+        $admin = $auth->createRole('admin');
+        $auth->add($admin);
+        $auth->addChild($admin, $updatePost);
+        $auth->addChild($admin, $author);
+
+        // 为用户指派角色。其中 1 和 2 是由 IdentityInterface::getId() 返回的id （译者注：user表的id）
+        // 通常在你的 User 模型中实现这个函数。
+        $auth->assign($author, 2);
+        $auth->assign($admin, 1);
+    }
+}
+```
+
+在用 `yii rbac/init` 执行了这个命令后，我们将得到下图所示的层次结构：
+
+![Simple RBAC hierarchy](images/rbac-hierarchy-1.png "简单的 RBAC 层次结构示意图")
+
+作者可创建新贴，管理员可编辑帖子以及所有作者可做的事情。
+
+如果你的应用允许用户注册，你需要在注册时给新用户指派一次角色。例如，
+在高级项目模板中，要让所有注册用户成为作者，你需要如下例所示修改
+`frontend\models\SignupForm::signup()` 方法：
+
+```php
+public function signup()
+{
+    if ($this->validate()) {
+        $user = new User();
+        $user->username = $this->username;
+        $user->email = $this->email;
+        $user->setPassword($this->password);
+        $user->generateAuthKey();
+        $user->save(false);
+
+        // 要添加以下三行代码：
+        $auth = Yii::$app->authManager;
+        $authorRole = $auth->getRole('author');
+        $auth->assign($authorRole, $user->getId());
+
+        return $user;
+    }
+
+    return null;
+}
+```
+
+对于有动态更改授权数据的复杂存取控制需求的，你可能需要使用 `authManager` 
+提供的 API 的开发用户界面（例如：管理面板）。
+
+
+### 使用规则 (Rules) <span id="using-rules"></span>
+
+如前所述，规则给角色和权限增加额外的约束条件。规则是 [[yii\rbac\Rule]] 的派生类。
+它需要实现 [[yii\rbac\Rule::execute()|execute()]] 方法。在之前我们创建的层次结构中，作者不能编辑自己的帖子，我们来修正这个问题。
+首先我们需要一个规则来认证当前用户是帖子的作者：
+
+```php
+namespace app\rbac;
+
+use yii\rbac\Rule;
+
+/**
+ * 检查 authorID 是否和通过参数传进来的 user 参数相符
+ */
+class AuthorRule extends Rule
+{
+    public $name = 'isAuthor';
+
+    /**
+     * @param string|integer $user 用户 ID.
+     * @param Item $item 该规则相关的角色或者权限
+     * @param array $params 传给 ManagerInterface::checkAccess() 的参数
+     * @return boolean 代表该规则相关的角色或者权限是否被允许
+     */
+    public function execute($user, $item, $params)
+    {
+        return isset($params['post']) ? $params['post']->createdBy == $user : false;
+    }
+}
+```
+
+上述规则检查 `post` 是否是 `$user` 创建的。我们还要在之前的命令中
+创建一个特别的权限 `updateOwnPost` ：
+
+```php
+$auth = Yii::$app->authManager;
+
+// 添加规则
+$rule = new \app\rbac\AuthorRule;
+$auth->add($rule);
+
+// 添加 "updateOwnPost" 权限并与规则关联
+$updateOwnPost = $auth->createPermission('updateOwnPost');
+$updateOwnPost->description = 'Update own post';
+$updateOwnPost->ruleName = $rule->name;
+$auth->add($updateOwnPost);
+
+// "updateOwnPost" 权限将由 "updatePost" 权限使用
+$auth->addChild($updateOwnPost, $updatePost);
+
+// 允许 "author" 更新自己的帖子
+$auth->addChild($author, $updateOwnPost);
+```
+
+现在我们得到如下层次结构:
+
+![RBAC hierarchy with a rule](images/rbac-hierarchy-2.png "有一个规则的 RBAC 层次结构")
+
+
+### 存取检查 <span id="access-check"></span>
+
+授权数据准备好后，存取检查简单到只需要一个方法调用 [[yii\rbac\ManagerInterface::checkAccess()]]。
+因为大多数存取检查都是针对当前用户而言，为方便起见， Yii 提供了一个快捷方法
+[[yii\web\User::can()]]，可以如下例所示来使用：
+
+```php
+if (\Yii::$app->user->can('createPost')) {
+    // 建贴
+}
+```
+
+如果当前用户是 `ID=1` 的 Jane ，我们从图中的 `createPost` 开始，并试图到达 `Jane` 。 （译者注：参照图中红色路线所示的建贴授权流程）
+
+![Access check](images/rbac-access-check-1.png "Access check")
+
+为了检查某用户是否能更新帖子，我们需要传递一个额外的参数，该参数是 `AuthorRule` 要用的：
+
+```php
+if (\Yii::$app->user->can('updatePost', ['post' => $post])) {
+    // 更新帖子
+}
+```
+
+下图所示为当前用户是 John 时所发生的事情：
+
+
+![Access check](images/rbac-access-check-2.png "存取权限检查")
+
+我们从图中的 `updatePost` 开始，经过 `updateOwnPost`。为通过检查，`Authorrule` 
+规则的 `execute()` 方法应当返回 `true` 。该方法从 `can()` 方法调用接收到 `$params` 参数，
+因此它的值是 `['post' => $post]` 。如果一切顺利，我们会达到指派给 John 的 `author` 角色。
+
+对于 Jane 来说则更简单，因为她是管理员：
+
+![Access check](images/rbac-access-check-3.png "Access check")
+
+
+### 使用默认角色 <span id="using-default-roles"></span>
+
+所谓默认角色就是 *隐式* 地指派给 *所有* 用户的角色。不需要调用 
+[[yii\rbac\ManagerInterface::assign()]] 方法做显示指派，并且授权数据中不包含指派信息。
+
+默认角色通常与一个规则关联，用以检查该角色是否符合被检查的用户。
+
+默认角色常常用于已经确立了一些角色的指派关系的应用（译者注：指派关系指的是应用业务逻辑层面，
+并非指授权数据的结构）。比如，一个应用的 user 表中有一个 `group` 字段，代表用户属于哪个特权组。
+如果每个特权组可以映射到 RBAC 的角色，你就可以采用默认角色自动地为每个用户指派一个 RBAC 角色。
+让我们用一个例子展示如何做到这一点。
+
+假设在 user 表中，你有一个 `group` 字段，用 1 代表管理员组，用 2 表示作者组。
+你规划两个 RBAC 角色 `admin` 和 `author` 分别对应这两个组的权限。
+你可以这样设置 RBAC 数据，
+
+
+```php
+namespace app\rbac;
+
+use Yii;
+use yii\rbac\Rule;
+
+/**
+ * 检查是否匹配用户的组
+ */
+class UserGroupRule extends Rule
+{
+    public $name = 'userGroup';
+
+    public function execute($user, $item, $params)
+    {
+        if (!Yii::$app->user->isGuest) {
+            $group = Yii::$app->user->identity->group;
+            if ($item->name === 'admin') {
+                return $group == 1;
+            } elseif ($item->name === 'author') {
+                return $group == 1 || $group == 2;
+            }
+        }
+        return false;
+    }
+}
+
+$auth = Yii::$app->authManager;
+
+$rule = new \app\rbac\UserGroupRule;
+$auth->add($rule);
+
+$author = $auth->createRole('author');
+$author->ruleName = $rule->name;
+$auth->add($author);
+// ... 添加$author角色的子项部分代码 ... （译者注：省略部分参照之前的控制台命令）
+
+$admin = $auth->createRole('admin');
+$admin->ruleName = $rule->name;
+$auth->add($admin);
+$auth->addChild($admin, $author);
+// ... 添加$admin角色的子项部分代码 ... （译者注：省略部分参照之前的控制台命令）
+```
+
+注意，在上述代码中，因为 "author" 作为 "admin" 的子角色，当你实现这个规则的 `execute()` 方法时， 
+你也需要遵从这个层次结构。这就是为何当角色名为 "author" 的情况下（译者注：`$item->name`就是角色名）， 
+`execute()` 方法在组为 1 或者 2 时均要返回 true 
+（意思是用户属于 "admin" 或者 "author" 组 ）。
+
+接下来，在配置 `authManager` 时指定 [[yii\rbac\BaseManager::$defaultRoles]] 选项（译者注：在应用配置文件中的组件部分配置）：
+
+```php
+return [
+    // ...
+    'components' => [
+        'authManager' => [
+            'class' => 'yii\rbac\PhpManager',
+            'defaultRoles' => ['admin', 'author'],
+        ],
+        // ...
+    ],
+];
+```
+
+现在如果你执行一个存取权限检查， 判定该规则时， `admin` 和 `author` 
+两个角色都将会检查。如果规则返回 true ，意思是角色符合当前用户。基于上述规则
+的实现，意味着如果某用户的 `group` 值为 1 ， `admin` 角色将赋予该用户，
+如果 `group` 值是 2 则将赋予 `author` 角色。
--- a/docs/guide-zh-CN/structure-extensions.md
+++ b/docs/guide-zh-CN/structure-extensions.md
@ -1,36 +1,36 @@
-Extensions
+扩展
 ==========

-Extensions are redistributable software packages specifically designed to be used in Yii applications and provide
-ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar
-at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can
-use extensions to accelerate your development process. You can also package your code as extensions to share with
-other people your great work.
+扩展是专门设计的在 Yii 应用中随时可拿来使用的，
+并可重发布的软件包。例如， [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug)
+扩展在你的应用的每个页面底部添加一个方便用于调试的工具栏，
+帮助你简单地抓取页面生成的情况。
+你可以使用扩展来加速你的开发过程。

-> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages
-  that can be used without Yii, we will refer to them using the term "package" or "library".
+> 信息：本文中我们使用的术语 "扩展" 特指 Yii 软件包。而用术语
+  "软件包" 和 "库" 指代非 Yii 专用的通常意义上的软件包。


-## Using Extensions <span id="using-extensions"></span>
+## 使用扩展 <span id="using-extensions"></span>

-To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/)
-packages which can be installed by taking the following two simple steps:
+要使用扩展，你要先安装它。大多数扩展以 [Composer](https://getcomposer.org/) 软件包的形式发布，
+这样的扩展可采取下述两个步骤来安装：

-1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install.
-2. run `composer install` to install the specified extensions.
+1. 修改你的应用的 `composer.json` 文件，指明你要安装的是哪个扩展 （Composer 软件包）。
+2. 运行 `composer install` 来安装指定的扩展。

-Note that you may need to install [Composer](https://getcomposer.org/) if you do not have it.
+注意如果你还没有安装 [Composer](https://getcomposer.org/) ，你需要先安装。

-By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository
-for open source Composer packages. You can look for extensions on Packagist. You may also
-[create your own repository](https://getcomposer.org/doc/05-repositories.md#repository) and configure Composer
-to use it. This is useful if you are developing closed open extensions and want to share within your projects.
+默认情况，Composer安装的是在 [Packagist](https://packagist.org/) 中
+注册的软件包 - 最大的开源 Composer 代码库。你可以在 Packageist 中查找扩展。
+你也可以 [创建你自己的代码库](https://getcomposer.org/doc/05-repositories.md#repository) 然后配置 Composer 来使用它。
+如果是在开发私有的扩展，并且想只在你的其他工程中共享时，这样做是很有用的。

-Extensions installed by Composer are stored in the `BasePath/vendor` directory, where `BasePath` refers to the
-application's [base path](structure-applications.md#basePath).  Because Composer is a dependency manager, when
-it installs a package, it will also install all its dependent packages.
+通过 Composer 安装的扩展会存放在 `BasePath/vendor` 目录下，这里的 `BasePath` 
+指你的应用的 [base path](structure-applications.md#basePath)。因为 Composer 还是一个依赖管理器，当它安装一个包时，
+也将安装这个包所依赖的所有软件包。

-For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following:
+例如想安装 `yiisoft/yii2-imagine` 扩展，可按如下示例修改你的 `composer.json` 文件：

 ```json
 {
@ -44,42 +44,42 @@ For example, to install the `yiisoft/yii2-imagine` extension, modify your `compo
 }
 ```

-After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should
-also see another directory `imagine/imagine` which contains the installed dependent package.
+安装完成后，你应该能在 `BasePath/vendor` 目录下见到 `yiisoft/yii2-imagine` 目录。你也应该
+见到另一个 `imagine/imagine` 目录，在其中安装了所依赖的包。

-> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All
-  core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz`
-  varies for different extensions.
+> 信息： `yiisoft/yii2-imagine` 是 Yii 由开发团队维护一个核心扩展，
+  所有核心扩展均由 [Packagist](https://packagist.org/) 集中管理，命名为
+  `yiisoft/yii2-xyz`，其中的 `xyz`， 不同扩展有不同名称。

-Now you can use the installed extensions like they are part of your application. The following example shows
-how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension:
+现在你可以使用安装好的扩展了，好比是应用的一部分。如下示例展示了如何使用 `yiisoft/yii2-imagine` 扩展
+提供的 `yii\imagine\Image` 类：

 ```php
 use Yii;
 use yii\imagine\Image;

-// generate a thumbnail image
+// 生成一个缩略图
 Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
    ->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
 ```

-> Info: Extension classes are autoloaded by the [Yii class autoloader](concept-autoloading.md).
+> 信息： 扩展类由 [Yii class autoloader](concept-autoloading.md) 自动加载。


-### Installing Extensions Manually <span id="installing-extensions-manually"></span>
+### 手动安装扩展 <span id="installing-extensions-manually"></span>

-In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer.
-To do so, you should
+在极少情况下，你可能需要手动安装一部分或者全部扩展，而不是依赖 Composer。
+想做到这一点，你应当：

-1. download the extension archive files and unpack them in the `vendor` directory.
-2. install the class autoloaders provided by the extensions, if any.
-3. download and install all dependent extensions as instructed.
+1. 下载扩展压缩文件，解压到 `vendor` 目录。
+2. 如果有，则安装扩展提供的自动加载器。
+3. 按指导说明下载和安装所有依赖的扩展。

-If an extension does not have a class autoloader but follows the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/),
-you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to
-declare a [root alias](concept-aliases.md#defining-aliases) for the extension root directory. For example,
-assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes
-are under the `myext` namespace, then you can include the following code in your application configuration:
+如果扩展没有提供类的自动加载器，但也遵循了 [PSR-4 standard](http://www.php-fig.org/psr/psr-4/) 
+标准，那么你可以使用 Yii 提供的类自动加载器来加载扩展类。
+你需要做的仅仅是为扩展的根目录声明一个 [root alias](concept-aliases.md#defining-aliases)。
+例如，假设在 `vendor/mycompany/myext` 目录中安装了一个扩展，并且扩展类的命名空间为 `myext` ，
+那么你可以在应用配置文件中包含如下代码：

 ```php
 [
@ -90,29 +90,29 @@ are under the `myext` namespace, then you can include the following code in your
 ```


-## Creating Extensions <span id="creating-extensions"></span>
+## 创建扩展 <span id="creating-extensions"></span>

-You may consider creating an extension when you feel the need to share with other people your great code.
-An extension can contain any code you like, such as a helper class, a widget, a module, etc.
+在你需要将你的杰作分享给其他人的时候，你可能会考虑创建一个扩展。
+扩展可包括任何你喜欢的代码，例如助手类、挂件、模块，等等。

-It is recommended that you create an extension in terms of a [Composer package](https://getcomposer.org/) so that
-it can be more easily installed and used by other users, liked described in the last subsection.
+建议你按照 [Composer package](https://getcomposer.org/) 的条款创建扩展，以便其他人更容易安装和使用。
+就像上面的章节讲述的那样。

-Below are the basic steps you may follow to create an extension as a Composer package.
+以下是将扩展创建为一个 Composer 软件包的需遵循的基本步骤。

-1. Create a project for your extension and host it on a VCS repository, such as [github.com](https://github.com).
-   The development and maintenance work about the extension should be done on this repository.
-2. Under the root directory of the project, create a file named `composer.json` as required by Composer. Please
-   refer to the next subsection for more details.
-3. Register your extension with a Composer repository, such as [Packagist](https://packagist.org/), so that
-   other users can find and install your extension using Composer.
+1. 为你的扩展建一个工程，并将它存放在版本控制代码库中，例如 [github.com](https://github.com) 。
+   扩展的开发和维护都应该在这个代码库中进行。
+2. 在工程的根目录下，建一个 Composer 所需的名为 `composer.json` 的文件。
+   详情请参考后面的章节。  
+3. 在一个 Composer 代码库中注册你的扩展，比如在 [Packagist](https://packagist.org/) 中，以便其他
+   用户能找到以及用 Composer 安装你的扩展。


 ### `composer.json` <span id="composer-json"></span>

-Each Composer package must have a `composer.json` file in its root directory. The file contains the metadata about
-the package. You may find complete specification about this file in the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup).
-The following example shows the `composer.json` file for the `yiisoft/yii2-imagine` extension:
+每个 Composer 软件包在根目录都必须有一个 `composer.json` 文件。该文件包含软件包的元数据。
+你可以在 [Composer手册](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup) 中找到完整关于该文件的规格。
+以下例子展示了 `yiisoft/yii2-imagine` 扩展的 `composer.json` 文件。

 ```json
 {
@ -155,39 +155,39 @@ The following example shows the `composer.json` file for the `yiisoft/yii2-imagi
 ```


-#### Package Name <span id="package-name"></span>
+#### 包名 <span id="package-name"></span>

-Each Composer package should have a package name which uniquely identifies the package among all others.
-The format of package names is `vendorName/projectName`. For example, in the package name `yiisoft/yii2-imagine`,
-the vendor name and the project name are `yiisoft` and `yii2-imagine`, respectively.
+每个 Composer 软件包都应当有一个唯一的包名以便能从其他的软件包中识别出来。
+包名的格式为 `vendorName/projectName` 。例如在包名 `yiisoft/yii2-imagine` 中，vendor 名和 project 名分别是
+ `yiisoft` 和 `yii2-imagine` 。

-Do NOT use `yiisoft` as vendor name as it is reserved for use by the Yii core code.
+不要用 `yiisoft` 作为你的 vendor 名，由于它被 Yii 的核心代码预留使用了。

-We recommend you prefix `yii2-` to the project name for packages representing Yii 2 extensions, for example,
-`myname/yii2-mywidget`. This will allow users to more easily tell whether a package is a Yii 2 extension.
+我们推荐你用 `yii2-` 作为你的包名的前缀，表示它是 Yii 2 的扩展，例如，`myname/yii2-mywidget`。
+这更便于用户辨别是否是 Yii 2 的扩展。


-#### Package Type <span id="package-type"></span>
+#### 包类型 <span id="package-type"></span>

-It is important that you specify the package type of your extension as `yii2-extension` so that the package can
-be recognized as a Yii extension when being installed.
+将你的扩展指明为 `yii2-extension` 类型很重要，以便安装的时候
+能被识别出是一个 Yii 扩展。

-When a user runs `composer install` to install an extension, the file `vendor/yiisoft/extensions.php`
-will be automatically updated to include the information about the new extension. From this file, Yii applications
-can know which extensions are installed (the information can be accessed via [[yii\base\Application::extensions]].
+当用户运行 `composer install` 安装一个扩展时， `vendor/yiisoft/extensions.php` 
+文件会被自动更新使之包含新扩展的信息。从该文件中， Yii 应用程序就能知道安装了
+哪些扩展 (这些信息可通过 [[yii\base\Application::extensions]] 访问)。


-#### Dependencies <span id="dependencies"></span>
+#### 依赖 <span id="dependencies"></span>

-Your extension depends on Yii (of course). So you should list it (`yiisoft/yii2`) in the `require` entry in `composer.json`.
-If your extension also depends on other extensions or third-party libraries, you should list them as well.
-Make sure you also list appropriate version constraints (e.g. `1.*`, `@stable`) for each dependent package. Use stable
-dependencies when your extension is released in a stable version.
+你的扩展依赖于 Yii （理所当然）。因此你应当在 `composer.json` 文件中列出它
+(`yiisoft/yii2`)。如果你的扩展还依赖其他的扩展或者是第三方库，你也要一并列出来。
+确定你也为每一个依赖的包列出了适当的版本约束条件 (比如 `1.*`, `@stable`) 。
+当你发布一个稳定版本时，你所依赖的包也应当使用稳定版本。

-Most JavaScript/CSS packages are managed using [Bower](http://bower.io/) and/or [NPM](https://www.npmjs.org/),
-instead of Composer. Yii uses the [Composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin)
-to enable managing these kinds of packages through Composer. If your extension depends on a Bower package, you can
-simply list the dependency in `composer.json` like the following:
+大多数 JavaScript/CSS 包是用 [Bower](http://bower.io/) 来管理的，而非 Composer。你可使用 
+[Composer asset 插件](https://github.com/francoispluchino/composer-asset-plugin) 使之可以
+通过 Composer 来管理这类包。如果你的扩展依赖 Bower 软件包，你可以如下例所示那样简单地
+在 `composer.json` 文件的依赖中列出它。

 ```json
 {
@ -198,19 +198,19 @@ simply list the dependency in `composer.json` like the following:
 }
 ```

-The above code states that the extension depends on the `jquery` Bower package. In general, you can use
-`bower-asset/PackageName` to refer to a Bower package in `composer.json`, and use `npm-asset/PackageName`
-to refer to a NPM package. When Composer installs a Bower or NPM package, by default the package content will be
-installed under the `@vendor/bower/PackageName` and `@vendor/npm/Packages` directories, respectively.
-These two directories can also be referred to using the shorter aliases `@bower/PackageName` and `@npm/PackageName`.
+上述代码表明该扩展依赖于 `jquery` Bower 包。一般来说，你可以在 `composer.json` 
+中用 `bower-asset/PackageName` 指定 Bower 包，用 `npm-asset/PackageName` 指定 NPM 包。
+当 Compower 安装 Bower 和 NPM 软件包时，包的内容默认会分别安装到 `@vendor/bower/PackageName`
+和 `@vendor/npm/Packages` 下。这两个目录还可以分别用 `@bower/PackageName` 
+和 `@npm/PackageName` 别名指向。

-For more details about asset management, please refer to the [Assets](structure-assets.md#bower-npm-assets) section.
+关于 asset 管理的详细情况，请参照 [Assets](structure-assets.md#bower-npm-assets) 章节。


-#### Class Autoloading <span id="class-autoloading"></span>
+#### 类的自动加载 <span id="class-autoloading"></span>

-In order for your classes to be autoloaded by the Yii class autoloader or the Composer class autoloader,
-you should specify the `autoload` entry in the `composer.json` file, like shown below:
+为使你的类能够被 Yii 的类自动加载器或者 Composer 的类自动加载器自动加载，你应当在
+ `composer.json` 中指定 `autoload` 条目，如下所示：

 ```json
 {
@ -224,41 +224,41 @@ you should specify the `autoload` entry in the `composer.json` file, like shown
 }
 ```

-You may list one or multiple root namespaces and their corresponding file paths.
+你可以列出一个或者多个根命名空间和它们的文件目录。

-When the extension is installed in an application, Yii will create for each listed root namespace
-an [alias](concept-aliases.md#extension-aliases) that refers to the directory corresponding to the namespace.
-For example, the above `autoload` declaration will correspond to an alias named `@yii/imagine`.
+当扩展安装到应用中后，Yii 将为每个所列出根命名空间创建一个
+[别名](concept-aliases.md#extension-aliases) 指向命名空间对应的目录。
+例如，上述的 `autoload` 条目声明将对应于别名 `@yii/imagine`。


-### Recommended Practices <span id="recommended-practices"></span>
+### 推荐的做法 <span id="recommended-practices"></span>

-Because extensions are meant to be used by other people, you often need to take extra development effort. Below
-we introduce some common and recommended practices in creating high quality extensions.
+扩展意味着会被其他人使用，你在开发中通常需要额外的付出。
+下面我们介绍一些通用的及推荐的做法，以创建高品质的扩展。


-#### Namespaces <span id="namespaces"></span>
+#### 命名空间 <span id="namespaces"></span>

-To avoid name collisions and make the classes in your extension autoloadable, you should use namespaces and
-name the classes in your extension by following the [PSR-4 standard](http://www.php-fig.org/psr/psr-4/) or
-[PSR-0 standard](http://www.php-fig.org/psr/psr-0/).
+为避免冲突以及使你的扩展中的类能被自动加载，你的类应当使用命名空间，
+并使类的命名符合 [PSR-4 standard](http://www.php-fig.org/psr/psr-4/) 或者
+[PSR-0 standard](http://www.php-fig.org/psr/psr-0/) 标准。

-You class namespaces should start with `vendorName\extensionName`, where `extensionName` is similar to the project name
-in the package name except that it should not contain the `yii2-` prefix. For example, for the `yiisoft/yii2-imagine`
-extension, we use `yii\imagine` as the namespace its classes.
+你的类的命名空间应以 `vendorName\extensionName` 起始，其中 `extensionName` 
+和项目名相同，除了它没有 `yii2-` 前缀外。例如，对 `yiisoft/yii2-imagine` 扩展
+来说，我们用 `yii\imagine` 作为它的类的命名空间。

-Do not use `yii`, `yii2` or `yiisoft` as vendor name. These names are reserved for use by the Yii core code.
+不要使用 `yii`、`yii2` 或者 `yiisoft` 作为你的 vendor 名。这些名称已由 Yii 内核代码预留使用了。


-#### Bootstrapping Classes <span id="bootstrapping-classes"></span>
+#### 类的自举引导 <span id="bootstrapping-classes"></span>

-Sometimes, you may want your extension to execute some code during the [bootstrapping process](runtime-bootstrapping.md)
-stage of an application. For example, your extension may want to respond to the application's `beginRequest` event
-to adjust some environment settings. While you can instruct users of the extension to explicitly attach your event
-handler in the extension to the `beginRequest` event, a better way is to do this automatically.
+有时候，你可能想让你的扩展在应用的 [自举过程](runtime-bootstrapping.md) 中执行一些代码。
+例如，你的扩展可能想响应应用的 `beginRequest` 事件，做一些环境的设置工作。
+虽然你可以指导扩展的使用者显式地将你的扩展中的事件句柄附加（绑定）到 `beginRequest` 事件，
+但是更好的方法是自动完成。

-To achieve this goal, you can create a so-called *bootstrapping class* by implementing [[yii\base\BootstrapInterface]].
-For example,
+为实现该目标，你可以创建一个所谓 *bootstrapping class* （自举类）实现 [[yii\base\BootstrapInterface]] 接口。
+例如，

 ```php
 namespace myname\mywidget;
@ -277,7 +277,7 @@ class MyBootstrapClass implements BootstrapInterface
 }
 ```

-You then list this class in the `composer.json` file of your extension like follows,
+然后你将这个类在 `composer.json` 文件中列出来，如下所示，

 ```json
 {
@ -289,147 +289,147 @@ You then list this class in the `composer.json` file of your extension like foll
 }
 ```

-When the extension is installed in an application, Yii will automatically instantiate the bootstrapping class
-and call its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method during the bootstrapping process for
-every request.
+当这个扩展安装到应用后，Yii 将在每一个请求的自举过程中
+自动实例化自举类并调用其 [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] 
+方法。


-#### Working with Databases <span id="working-with-databases"></span>
+#### 操作数据库 <span id="working-with-databases"></span>

-Your extension may need to access databases. Do not assume that the applications that use your extension will always
-use `Yii::$db` as the DB connection. Instead, you should declare a `db` property for the classes that require DB access.
-The property will allow users of your extension to customize which DB connection they would like your extension to use.
-As an example, you may refer to the [[yii\caching\DbCache]] class and see how it declares and uses the `db` property.
+你的扩展可能要存取数据库。不要假设使用你的扩展的应用总是用 
+`Yii::$db` 作为数据库连接。你应当在需要访问数据库的类中申明一个 `db` 属性。
+这个属性允许你的扩展的用户可定制你的扩展使用哪个 DB 连接。例如，
+你可以参考 [[yii\caching\DbCache]] 类看一下它是如何申明和使用 `db` 属性的。

-If your extension needs to create specific DB tables or make changes to DB schema, you should
+如果你的扩展需要创建特定的数据库表，或者修改数据库结构，你应当

- provide [migrations](db-migrations.md) to manipulate DB schema, rather than using plain SQL files;
- try to make the migrations applicable to different DBMS;
- avoid using [Active Record](db-active-record.md) in the migrations.
+- 提供 [数据迁移](db-migrations.md) 来操作数据库的结构修改，而不是使用SQL文本文件；
+- 尽量使迁移文件适用于不同的 DBMS；
+- 在迁移文件中避免使用 [Active Record](db-active-record.md)。


-#### Using Assets <span id="using-assets"></span>
+#### 使用 Assets <span id="using-assets"></span>

-If your extension is a widget or a module, chances are that it may require some [assets](structure-assets.md) to work.
-For example, a module may display some pages which contain images, JavaScript, and CSS. Because the files of an
-extension are all under the same directory which is not Web accessible when installed in an application, you have
-two choices to make the asset files directly accessible via Web:
+如果你的扩展是挂件或者模块类型，它有可能需要使用一些 [assets](structure-assets.md) 。
+例如，一个模块可能要显示一些包含图片，JavaScript 和 CSS 的页面。因为扩展的文件
+都是放在同一个目录之下，安装之后 Web 无法读取，你有两个选择使得这些 asset 文件目录
+可以通过 Web 读取：

- ask users of the extension to manually copy the asset files to a specific Web-accessible folder;
- declare an [asset bundle](structure-assets.md) and rely on the asset publishing mechanism to automatically
-  copy the files listed in the asset bundle to a Web-accessible folder.
+- 让扩展的用户手动将这些 asset 文件拷贝到特定的 Web 可以读取的文件夹；
+- 申明一个 [asset bundle](structure-assets.md) 并依靠 asset 发布机制自动将这些文件（asset bundle 中列出的文件）
+  拷贝到 Web 可读的文件夹。

-We recommend you use the second approach so that your extension can be more easily used by other people.
-Please refer to the [Assets](structure-assets.md) section for more details about how to work with assets in general.
+我们推荐你使用第二种方法，以便其他人能更容易使用你的扩展。
+更详细的关于如何处理 assets ，请参照 [Assets](structure-assets.md) 章节。


-#### Internationalization and Localization <span id="i18n-l10n"></span>
+#### 国际化和本地化 <span id="i18n-l10n"></span>

-Your extension may be used by applications supporting different languages! Therefore, if your extension displays
-content to end users, you should try to [internationalize and localize](tutorial-i18n.md) it. In particular,
+你的扩展可能会在支持不同语言的应用中使用！因此，如果你的扩展要显示内容给终端用户，
+你应当试着实现 [国际化和本地化](tutorial-i18n.md)，特别地，

- If the extension displays messages intended for end users, the messages should be wrapped into `Yii::t()`
-  so that they can be translated. Messages meant for developers (such as internal exception messages) do not need
-  to be translated.
- If the extension displays numbers, dates, etc., they should be formatted using [[yii\i18n\Formatter]] with
-  appropriate formatting rules.
+- 如果扩展为终端用户显示信息，这些信息应该用 `Yii::t()` 
+  包装起来，以便可以进行翻译。
+  只给开发者参考的信息（如内部异常信息）不需要做翻译。
+- 如果扩展显示数字、日期等，你应该用 [[yii\i18n\Formatter]] 
+  中适当的格式化规则做格式化处理。

-For more details, please refer to the [Internationalization](tutorial-i18n.md) section.
+更详细的信息，请参照 [Internationalization](tutorial-i18n.md) 章节。


-#### Testing <span id="testing"></span>
+#### 测试 <span id="testing"></span>

-You want your extension to run flawlessly without bringing problems to other people. To reach this goal, you should
-test your extension before releasing it to public.
+你一定想让你的扩展可以无暇地运行而不会给其他人带来问题和麻烦。为达到这个目的，
+你应当在公开发布前做测试。

-It is recommended that you create various test cases to cover your extension code rather than relying on manual tests.
-Each time before you release a new version of your extension, you may simply run these test cases to make sure
-everything is in good shape. Yii provides testing support, which can help you to more easily write unit tests,
-acceptance tests and functionality tests. For more details, please refer to the [Testing](test-overview.md) section.
+推荐你创建测试用例，做全面覆盖的测试你的扩展，而不只是依赖于手动测试。
+每次发布新版本前，你只要简单地运行这些测试用例确保一切完好。
+Yii 提供了测试支持，使你更容易写单元测试、验收测试和功能测试。
+详情请参照 [Testing](test-overview.md) 章节。


-#### Versioning <span id="versioning"></span>
+#### 版本控制 <span id="versioning"></span>

-You should give each release of your extension a version number (e.g. `1.0.1`). We recommend you follow the
-[semantic versioning](http://semver.org) practice when determining what version numbers should be used.
+你应该为每一个扩展定一个版本号（如 `1.0.1`）。我们推荐你命名版本号时参照
+[semantic versioning](http://semver.org) 决定用什么样的版本号。


-#### Releasing <span id="releasing"></span>
+#### 发布 <span id="releasing"></span>

-To let other people know your extension, you need to release it to public.
+为使其他人知道你的扩展，你应该公开发布。

-If it is the first time you release an extension, you should register it on a Composer repository, such as
-[Packagist](https://packagist.org/). After that, all you need to do is simply creating a release tag (e.g. `v1.0.1`)
-on the VCS repository of your extension and notify the Composer repository about the new release. People will
-then be able to find the new release, and install or update the extension through the Composer repository.
+如果你首次发布一个扩展，你应该在 Composer 代码库中注册它，例如
+[Packagist](https://packagist.org/)。之后，你所需要做的仅仅是在
+版本管理库中创建一个 tag （如`v1.0.1`），然后通知 Composer 代码库。
+其他人就能查找到这个新的发布了，并可通过 Composer 代码库安装和更新该扩展。

-In the releases of your extension, besides code files you should also consider including the following to
-help other people learn about and use your extension:
+在发布你的扩展时，除了代码文件，你还应该考虑包含如下内容
+帮助其他人了解和使用你的扩展：

-* A readme file in the package root directory: it describes what your extension does and how to install and use it.
-  We recommend you write it in [Markdown](http://daringfireball.net/projects/markdown/) format and name the file
-  as `readme.md`.
-* A changelog file in the package root directory: it lists what changes are made in each release. The file
-  may be written in Markdown format and named as `changelog.md`.
-* An upgrade file in the package root directory: it gives the instructions on how to upgrade from older releases
-  of the extension. The file may be written in Markdown format and named as `upgrade.md`.
-* Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be
-  fully covered in the readme file.
-* API documentation: your code should be well documented to allow other people more easily read and understand it.
-  You may refer to the [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php)
-  to learn how to document your code.
+* 根目录下的 readme 文件：它描述你的扩展是干什么的以及如何安装和使用。
+  我们推荐你用 [Markdown](http://daringfireball.net/projects/markdown/) 的格式
+  来写并将文件命名为 `readme.md`。
+* 根目录下的修改日志文件：它列举每个版本的发布做了哪些更改。该文件可以用 Markdown 根式
+  编写并命名为 `changelog.md`。
+* 根目录下的升级文件：它给出如何从其他就版本升级该扩展的指导。该文件可以用 Markdown 根式
+  编写并命名为 `changelog.md`。
+* 入门指南、演示代码、截屏图示等：如果你的扩展提供了许多功能，在 readme 文件中不能完整
+  描述时，就要用到这些文件。
+* API 文档：你的代码应当做好文档，让其他人更容易阅读和理解。
+  你可以参照 [Object class file](https://github.com/yiisoft/yii2/blob/master/framework/base/Object.php)
+  学习如何为你的代码做文档。

-> Info: Your code comments can be written in Markdown format. The `yiisoft/yii2-apidoc` extension provides a tool
-  for you to generate pretty API documentation based on your code comments.
+> 信息：你的代码注释可以写成 Markdown 格式。`yiisoft/yii2-apidoc` 扩展为你提供了一个从你的
+  代码注释生成漂亮的 API 文档。

-> Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to
-  the [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style).
+> 信息：虽然不做要求，我们还是建议你的扩展遵循某个编码规范。
+  你可以参照 [core framework code style](https://github.com/yiisoft/yii2/wiki/Core-framework-code-style)。


-## Core Extensions <span id="core-extensions"></span>
+## 核心扩展 <span id="core-extensions"></span>

-Yii provides the following core extensions that are developed and maintained by the Yii developer team. They are all
-registered on [Packagist](https://packagist.org/) and can be easily installed as described in the
-[Using Extensions](#using-extensions) subsection.
+Yii 提供了下列核心扩展，由 Yii 开发团队开发和维护。这些扩展全都在
+[Packagist](https://packagist.org/) 中注册，并像 [Using Extensions](#using-extensions) 章节描述
+的那样容易安装。

 - [yiisoft/yii2-apidoc](https://github.com/yiisoft/yii2-apidoc):
-  provides an extensible and high-performance API documentation generator. It is also used to generate the core
-  framework API documentation.
+  提供了一个可扩展的、高效的 API 文档生成器。核心框架的 API 
+  文档也是用它生成的。
 - [yiisoft/yii2-authclient](https://github.com/yiisoft/yii2-authclient):
-  provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client.
+  提供了一套常用的认证客户端，例如 Facebook OAuth2 客户端、GitHub OAuth2 客户端。
 - [yiisoft/yii2-bootstrap](https://github.com/yiisoft/yii2-bootstrap):
-  provides a set of widgets that encapsulate the [Bootstrap](http://getbootstrap.com/) components and plugins.
+  提供了一套挂件，封装了 [Bootstrap](http://getbootstrap.com/) 的组件和插件。
 - [yiisoft/yii2-codeception](https://github.com/yiisoft/yii2-codeception):
-  provides testing support based on [Codeception](http://codeception.com/).
+  提供了基于 [Codeception](http://codeception.com/) 的测试支持。
 - [yiisoft/yii2-debug](https://github.com/yiisoft/yii2-debug):
-  provides debugging support for Yii applications. When this extension is used, a debugger toolbar will appear
-  at the bottom of every page. The extension also provides a set of standalone pages to display more detailed
-  debug information.
+  提供了对 Yii 应用的调试支持。当使用该扩展是，
+  在每个页面的底部将显示一个调试工具条。
+  该扩展还提供了一个独立的页面，以显示更详细的调试信息。
 - [yiisoft/yii2-elasticsearch](https://github.com/yiisoft/yii2-elasticsearch):
-  provides the support for using [Elasticsearch](http://www.elasticsearch.org/). It includes basic querying/search
-  support and also implements the [Active Record](db-active-record.md) pattern that allows you to store active records
-  in Elasticsearch.
+  提供对 [Elasticsearch](http://www.elasticsearch.org/) 的使用支持。它包含基本的查询/搜索支持，
+  并实现了 [Active Record](db-active-record.md) 模式让你可以将活动记录
+  存储在 Elasticsearch 中。
 - [yiisoft/yii2-faker](https://github.com/yiisoft/yii2-faker):
-  provides the support for using [Faker](https://github.com/fzaninotto/Faker) to generate fake data for you.
+  提供了使用 [Faker](https://github.com/fzaninotto/Faker) 的支持，为你生成模拟数据。
 - [yiisoft/yii2-gii](https://github.com/yiisoft/yii2-gii):
-  provides a Web-based code generator that is highly extensible and can be used to quickly generate models,
-  forms, modules, CRUD, etc.
+  提供了一个基于页面的代码生成器，具有高可扩展性，并能用来快速生成模型、
+  表单、模块、CRUD等。
 - [yiisoft/yii2-imagine](https://github.com/yiisoft/yii2-imagine):
-  provides commonly used image manipulation functions based on [Imagine](http://imagine.readthedocs.org/).
+  提供了基于 [Imagine](http://imagine.readthedocs.org/) 的常用图像处理功能。
 - [yiisoft/yii2-jui](https://github.com/yiisoft/yii2-jui):
-  provides a set of widgets that encapsulate the [JQuery UI](http://jqueryui.com/) interactions and widgets.
+  提供了一套封装 [JQuery UI](http://jqueryui.com/) 的挂件以及它们的交互。
 - [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb):
-  provides the support for using [MongoDB](http://www.mongodb.org/). It includes features such as basic query,
-  Active Record, migrations, caching, code generation, etc.
+  提供了对 [MongoDB](http://www.mongodb.org/) 的使用支持。它包含基本
+  的查询、活动记录、数据迁移、缓存、代码生成等特性。
 - [yiisoft/yii2-redis](https://github.com/yiisoft/yii2-redis):
-  provides the support for using [redis](http://redis.io/). It includes features such as basic query,
-  Active Record, caching, etc.
+  提供了对 [redis](http://redis.io/) 的使用支持。它包含基本的
+  查询、活动记录、缓存等特性。
 - [yiisoft/yii2-smarty](https://github.com/yiisoft/yii2-smarty):
-  provides a template engine based on [Smarty](http://www.smarty.net/).
+  提供了一个基于 [Smarty](http://www.smarty.net/) 的模板引擎。
 - [yiisoft/yii2-sphinx](https://github.com/yiisoft/yii2-sphinx):
-  provides the support for using [Sphinx](http://sphinxsearch.com). It includes features such as basic query,
-  Active Record, code generation, etc.
+  提供了对 [Sphinx](http://sphinxsearch.com) 的使用支持。它包含基本的
+  查询、活动记录、代码生成等特性。
 - [yiisoft/yii2-swiftmailer](https://github.com/yiisoft/yii2-swiftmailer):
-  provides email sending features based on [swiftmailer](http://swiftmailer.org/).
+  提供了基于 [swiftmailer](http://swiftmailer.org/) 的邮件发送功能。
 - [yiisoft/yii2-twig](https://github.com/yiisoft/yii2-twig):
-  provides a template engine based on [Twig](http://twig.sensiolabs.org/).
+  提供了一个基于 [Twig](http://twig.sensiolabs.org/) 的模板引擎。