cookbook - 组件相对路径 初译完毕

cookbook - 1 to 2 初译开始
其它微调

public/docs/ts/latest/cookbook/a1-a2-quick-reference.jade

@@ -5,9 +5,14 @@ a(id="top")
   This chapter provides a quick reference guide to some of the common Angular 1
   syntax and its equivalent in Angular 2.
 
+  在Angular 1和Anuglar 2之间，有很多不同的概念和语法。
+  本章提供了一个快速的参考指南，指出一些常用的Angular 1语法及其在Angular 2中的等价物。
+
 :marked
   **See the Angular 2 syntax in this [live example](/resources/live-examples/cb-a1-a2-quick-reference/ts/plnkr.html)**.
 
+  **可到[在线范例](/resources/live-examples/cb-a1-a2-quick-reference/ts/plnkr.html)中查看Angular 2语法**。
+
   ## Contents
   This chapter covers
   * [Template Basics](#template-basics) - binding and local variables

public/docs/ts/latest/cookbook/component-relative-paths.jade

@@ -3,50 +3,82 @@ include ../_util-fns
 :marked
   ## Write *Component-Relative* URLs to component templates and style files
 
+  ## 为组件模板和样式表文件写*相对于组件的*URL
+
   Our components often refer to external template and style files.
   We identify those files with a URL in the `templateUrl` and `styleUrls` properties of the `@Component` metadata
   as seen here:
 
+  我们的组件通常都是引用外部的模板和样式表文件。
+  我们在`@Component`的元数据中通过`templateUrl`和`styleUrls`属性来标识出它们的位置：
+
 +makeExample('cb-component-relative-paths/ts/app/some.component.ts','absolute-config')(format='.')
 :marked
   By default, we *must* specify the full path back to the application root.
   We call this an ***absolute path*** because it is *absolute* with respect to the application root.
 
+  默认情况下，我们*必须*指定一个到应用根目录的完整路径。
+  我们称之为***绝对路径***，因为如果以应用程序的根目录为基准来看，它就是*绝对路径*。
+
   There are two problems with an *absolute path*:
 
+  使用*绝对路径*有两个问题：
+
   1. We have to remember the full path back to the application root.
 
+  1. 我们不得不记住到应用程序根目录的完整路径。
+
   1. We have to update the URL when we move the component around in the application files structure.
 
+  1. 当我们在应用的文件结构中移动这个组件时，将不得不更新这个URL
+
   It would be much easier to write and maintain our application components if we could specify template and style locations
   *relative* to their component class file.
 
+  如果我们能用*相对*于组件类文件的路径来指定模板和样式表的位置，那么编写和维护组件就会变得容易得多。
+
   *We can!*
 
+  *没问题！*
+
 .alert.is-important
   :marked
     We can if we build our application as `commonjs` modules and load those modules
     with a suitable package loader such as `systemjs` or `webpack`.
     Learn why [below](#why-default).
 
+    如果我们把应用构建成`commonjs`模块，并用一个合适的包加载器（比如`systemjs`或`webpack`）加载那些模块，就可以了。
+    [在下方](#why-default)可以学到原理。
+
     The Angular 2 CLI uses these technologies and defaults to the
     *component-relative path* approach described here.
     CLI users can skip this chapter or read on to understand
     how it works.
 
+    Angular 2 CLI(命令行界面)使用这些技术，并默认采用这里所说的*组件相对路径*方法。
+    用CLI用户可以跳过本章，并且往后阅读来了解它是怎么工作的。
+
 .l-main-section
 :marked
   ## _Component-Relative_ Paths
+  ## _组件相对_路径
 
   Our goal is to specify template and style URLs *relative* to their component class files,
   hence the term ***component-relative path***.
 
+  我们的目标是指定*相对*于组件类的模板和样式表的URL，因此得名***组件相对路径***。
+
   The key to success is following a convention that puts related component files in well-known locations.
 
+  成功的关键是遵循一个约定：把相对组件的文件放进众所周知的位置。
+
   We recommend keeping component template and component-specific style files as *siblings* of their
   companion component class files.
   Here we see the three files for `SomeComponent` sitting next to each other in the `app` folder.
 
+  我们建议把组件的模板和组件特有的样式表文件作为组件类文件的“兄弟”。
+  这里我们看到在`app`目录下依次有`SomeComponent`的三个文件。
+
 .filetree
   .file app
     .children
@@ -58,26 +90,44 @@ include ../_util-fns
   We'll have more files and folders — and greater folder depth — as our application grows.
   We'll be fine as long as the component files travel together as the inseparable siblings they are.
 
+  当应用规模增长后，我们还会有更多的文件和目录以及更大的深度。
+  如果组件的所有文件总是像形影不离的兄弟那样共进退，那该多好啊！
+
   ### Set the *moduleId*
+  ### 设置*moduleId*
 
   Having adopted this file structure convention, we can specify locations of the template and style files
   relative to the component class file simply by setting the `moduleId` property of the `@Component` metadata like this
+
+  采用这种文件结构约定，我们可以为模板和样式表文件指定相对于组件类文件的位置 —— 只要简单的在`@Component`元数据中设置`moduleId`属性就可以了，就像这样：
+
 +makeExample('cb-component-relative-paths/ts/app/some.component.ts','module-id')(format='.')
 :marked
   We strip the `app/` base path from the `templateUrl` and `styleUrls`. The result looks like this:
+
+  我们从`templateUrl`和`styleUrls`中把基准路径`app/`去掉了。结果是这样的：
+
 +makeExample('cb-component-relative-paths/ts/app/some.component.ts','relative-config')(format='.')
 
 .alert.is-helpful
   :marked
     Webpack users may prefer [an alternative approach](#webpack) that uses `require`.
 
+    Webpack用户可能更喜欢[一个替代方案](#webpack)：使用`require`。
+
 .l-main-section
 :marked
   ## Source
 
+  ## 源码
+
   **We can see the [live example](/resources/live-examples/cb-component-relative-paths/ts/plnkr.html)**
   and download the source code from there
   or simply read the pertinent source here.
+
+  **我们可以参见[在线范例](/resources/live-examples/cb-component-relative-paths/ts/plnkr.html)**
+  并从中下载源码或只在这里阅读相关源码。
+
 +makeTabs(
   `cb-component-relative-paths/ts/app/some.component.ts,
   cb-component-relative-paths/ts/app/some.component.html,
@@ -90,51 +140,90 @@ a#why-default
 .l-main-section
 :marked
   ## Appendix: why *component-relative* is not the default
+  ## 附录：为什么*组件相对路径*不是默认方式
 
   A *component-relative* path is obviously superior to an *absolute* path.
   Why did Angular default to the *absolute* path?
   Why do *we* have to set the `moduleId`? Why can't Angular set it?
 
+  *组件相对路径*明显比*绝对路径*高级一点。
+  为什么Angular默认采用了*绝对路径*呢？
+  为什么*我们*不得不设置`moduleId`呢？Angular为什么不能自己设置它？
+
   First, let's look at what happens if we use a relative path and omit the `moduleId`.
 
+  首先，如果只使用相对路径而省略掉`moduleId`，我们来看看会发生什么。
+
+  `EXCEPTION: Failed to load some.component.html`
+
   `EXCEPTION: Failed to load some.component.html`
 
   Angular can't find the file so it throws an error.
 
+  Angular找不到这个文件，所以它抛出一个错误。
+
   Why can't Angular calculate the template and style URLs from the component file's location?
 
+  为什么Angular不能相对于组件类文件的路径来自动计算模板和样式表的URL呢？
+
   Because the location of the component can't be determined without the developer's help.
   Angular apps can be loaded in many ways: from individual files, from SystemJS packages, or
   from CommonJS packages, to name a few.
   We might generate modules in any of several formats.
   We might not be writing modular code at all!
 
+  因为如果没有开发人员的帮助，组件的位置是检测不到的。
+  Angular应用可能被用多种方式加载：SystemJS包、CommonJS包等等。
+  我们可能会用几种格式之一来生成模块。
+  我们甚至可能完全没有写成模块化代码。
+
   With this diversity of packaging and module load strategies,
   it's not possible for Angular to know with certainty where these files reside at runtime.
 
+  由于存在这么多打包和模块加载策略，所以Angular不可能知道在运行期这些文件的正确位置。
+
   The only location Angular can be sure of is the URL of the `index.html` home page, the application root.
   So by default it resolves template and style paths relative to the URL of `index.html`.
   That's why we previously wrote our file URLs with an `app/` base path prefix.
 
+  Angular能够确定的唯一的位置是首页`index.html`的URL，也就是应用的根目录。
+  所以，默认情况下，它只能计算相对于`index.html`的模板和样式表路径。
+  这就是为什么我们以前用`app/`基准路径的前缀来写文件的URL。
+
   But *if* we follow the recommended guidelines and we write modules in `commonjs` format
   and we use a module loader that *plays nice*,
   *then* we — the developers of the application —
   know that the semi-global `module.id` variable is available and contains
   the absolute URL of the component class module file.
 
+  但是，*如果*我们遵循了建议的指导原则，用`commonjs`格式编写模块，并使用一个*不错的*模块加载器，
+  那么我们这些应用开发人员就能知道存在一个可用的半全局变量`module.id`，并且其中包含着组件类模块文件的绝对URL。
+
   That knowledge enables us to tell Angular where the *component* file is
   by setting the `moduleId`:
+
+  这种认知让我们得以通过设置`moduleId`来告诉Angular*组件类*文件在哪里：
+
 +makeExample('cb-component-relative-paths/ts/app/some.component.ts','module-id')(format='.')
 
 a#webpack
 .l-main-section
 :marked
   ## Webpack: load templates and styles with *require*
+
+  ## Webpack: 使用*require*加载模板和样式表
+
   Webpack developers have an alternative to `moduleId`.
 
+  Webpack开发者有`moduleId`的另一个备选方案。
+
   They can load templates and styles at runtime by setting the component metadata `template` and `style` properties
   with `require` statements that reference *component-relative* URLS.
 
+  通过把组件元数据中的`template`和`style`属性设置为`require`语句，并引用一个*相对于组件的*URL，他们可以在运行期间加载模板和样式表。
+
 +makeExample('webpack/ts/src/app/app.component.ts')(format='.')
 :marked
   See the [Introduction to Webpack](../guide/webpack.html).
+
+  参见[Webpack简介](../guide/webpack.html)。