docs(API): 翻译完了 RouterModule

aio/content/translations/cn/api-plan.md

@@ -26,7 +26,7 @@
 [x] |core/ViewChild | 2,870 | 0.89
 [x] |core/Directive | 2,767 | 0.86
 [x] |router/Routes | 2,331 | 0.72
-[ ] |router/RouterModule | 2,227 | 0.69
+[x] |router/RouterModule | 2,227 | 0.69
 [x] |router/Route | 2,223 | 0.69
 [ ] |common/http/HttpClientModule | 2,167 | 0.67
 [ ] |core/ElementRef | 2,163 | 0.67

packages/router/src/router_module.ts

@@ -35,6 +35,7 @@ import {flatten} from './utils/collection';
  *
  * Contains a list of directives
  *
+ * 所含指令的列表
  *
  */
 const ROUTER_DIRECTIVES =
@@ -45,7 +46,7 @@ const ROUTER_DIRECTIVES =
  *
  * Is used in DI to configure the router.
  *
- *
+ * DI 用它来配置路由器。
  */
 export const ROUTER_CONFIGURATION = new InjectionToken<ExtraOptions>('ROUTER_CONFIGURATION');
 
@@ -86,16 +87,28 @@ export function routerNgProbeToken() {
  * Since the router deals with a global shared resource--location, we cannot have
  * more than one router service active.
  *
+ * RouterModule 可能会被多次导入：每个惰性加载的发布包都会导入一次。
+ * 但由于路由器要和全局共享的资源 - location 打交道，所以不能同时激活一个以上的 `Router` 服务。
+ *
  * That is why there are two ways to create the module: `RouterModule.forRoot` and
  * `RouterModule.forChild`.
  *
+ * 这就是需要两种方式来创建本模块的原因：`RouterModule.forRoot` 和 `RouterModule.forChild`。
+ *
  * * `forRoot` creates a module that contains all the directives, the given routes, and the router
  *   service itself.
+ *
+ *   `forRoot` 创建一个包含所有指令、指定的路由和 `Router` 服务本身的模块。
+ *
  * * `forChild` creates a module that contains all the directives and the given routes, but does not
  *   include the router service.
  *
+ *   `forChild` 会创建一个包含所有指令、指定的路由，但不含 `Router` 服务的模块。
+ *
  * When registered at the root, the module should be used as follows
  *
+ * 当注册在根模块时，该模块应该这样用：
+ *
  * ```
  * @NgModule({
  *   imports: [RouterModule.forRoot(ROUTES)]
@@ -105,6 +118,8 @@ export function routerNgProbeToken() {
  *
  * For submodules and lazy loaded submodules the module should be used as follows:
  *
+ * 对于子模块和惰性加载的子模块，该模块应该这样用：
+ *
  * ```
  * @NgModule({
  *   imports: [RouterModule.forChild(ROUTES)]
@@ -116,18 +131,26 @@ export function routerNgProbeToken() {
  *
  * Adds router directives and providers.
  *
+ * 添加路由器指令和服务提供商。
+ *
  * Managing state transitions is one of the hardest parts of building applications. This is
  * especially true on the web, where you also need to ensure that the state is reflected in the URL.
  * In addition, we often want to split applications into multiple bundles and load them on demand.
  * Doing this transparently is not trivial.
  *
+ * 在构建应用时，管理状态的转换是最难的任务之一。对 Web 来说尤其如此，你还要确保这个状态同时在 URL 中反映出来。
+ * 另外，我们通常会希望把应用拆分成多个发布包，并按需加载。要让这些工作透明化，可没那么简单。
+ *
  * The Angular router solves these problems. Using the router, you can declaratively specify
  * application states, manage state transitions while taking care of the URL, and load bundles on
  * demand.
  *
+ * Angular 的路由器解决了这些问题。使用路由器，你可以声明式的指定应用的状态、管理状态的转换，还可以处理好 URL，还可以按需加载发布包。
+ *
  * [Read this developer guide](https://angular.io/docs/ts/latest/guide/router.html) to get an
  * overview of how the router should be used.
  *
+ * [阅读开发指南](/guide/router) 以获得如何使用路由器的全景图。
  *
  */
 @NgModule({
@@ -143,17 +166,43 @@ export class RouterModule {
    * Creates a module with all the router providers and directives. It also optionally sets up an
    * application listener to perform an initial navigation.
    *
+   * 创建一个带有所有路由器服务提供商和指令的模块。它还可以（可选的）设置一个应用监听器，来执行首次导航。
+   *
    * Options (see `ExtraOptions`):
+   *
+   * 选项（参见 `ExtraOptions`）：
+   *
    * * `enableTracing` makes the router log all its internal events to the console.
+   *
+   *   `enableTracing` 让路由器把它所有的内部事件都记录到控制台中。
+   *
    * * `useHash` enables the location strategy that uses the URL fragment instead of the history
    * API.
+   *
+   *   `useHash` 修改位置策略（`LocationStrategy`），用 URL 片段（`#`）代替 `history` API。
+   *
    * * `initialNavigation` disables the initial navigation.
+   *
+   *   `initialNavigation` 禁用首次导航。
+   *
    * * `errorHandler` provides a custom error handler.
+   *
+   *   `errorHandler` 提供一个自定义的错误处理器。
+   *
    * * `preloadingStrategy` configures a preloading strategy (see `PreloadAllModules`).
+   *
+   *   `preloadingStrategy` 配置预加载策略（参见 `PreloadAllModules`）。
+   *
    * * `onSameUrlNavigation` configures how the router handles navigation to the current URL. See
    * `ExtraOptions` for more details.
+   *
+   *   `onSameUrlNavigation` 会配置路由器在导航到当前 URL 时该如何处理。欲知详情，参见 `ExtraOptions`。
+   *
    * * `paramsInheritanceStrategy` defines how the router merges params, data and resolved data
    * from parent to child routes.
+   *
+   *   `paramsInheritanceStrategy` 定义了路由器要如何把父路由的参数、数据和解析出的数据合并到子路由中。
+   *
    */
   static forRoot(routes: Routes, config?: ExtraOptions): ModuleWithProviders<RouterModule> {
     return {
@@ -192,6 +241,8 @@ export class RouterModule {
 
   /**
    * Creates a module with all the router directives and a provider registering routes.
+   *
+   * 创建一个具有所有路由器指令和一个用于注册路由的提供商。
    */
   static forChild(routes: Routes): ModuleWithProviders<RouterModule> {
     return {ngModule: RouterModule, providers: [provideRoutes(routes)]};
@@ -225,8 +276,12 @@ export function provideForRootGuard(router: Router): any {
  *
  * Registers routes.
  *
+ * 注册路由。
+ *
  * ### Example
  *
+ * ### 例子
+ *
  * ```
  * @NgModule({
  *   imports: [RouterModule.forChild(ROUTES)],
@@ -249,24 +304,47 @@ export function provideRoutes(routes: Routes): any {
  *
  * Represents an option to configure when the initial navigation is performed.
  *
+ * 一个选项，用于控制执行首次导航的时机。
+ *
  * * 'enabled' - the initial navigation starts before the root component is created.
  * The bootstrap is blocked until the initial navigation is complete.
+ *
+ *   'enabled' - 在根组件创建之前就开始首次导航。在首次导航完成之前，引导过程都会被阻塞。
+ *
  * * 'disabled' - the initial navigation is not performed. The location listener is set up before
  * the root component gets created.
+ *
+ *   'disabled' - 不执行首次导航。在根组件创建之前，就会挂接上位置变更监听器。
+ *
  * * 'legacy_enabled'- the initial navigation starts after the root component has been created.
  * The bootstrap is not blocked until the initial navigation is complete. @deprecated
+ *
+ *   'legacy_enabled' - 在根组件创建完之后开始首次导航。在首次导航之前不阻塞引导过程。@deprecated
+ *
  * * 'legacy_disabled'- the initial navigation is not performed. The location listener is set up
  * after @deprecated
  * the root component gets created.
+ *
+ *   'legacy_disabled' - 不执行首次导航。在根组件创建完之后设置路径监听器。@deprecated
+ *
  * * `true` - same as 'legacy_enabled'. @deprecated since v4
+ *
+ *   `true` - 同 'legacy_enabled'. @deprecated since v4
+ *
  * * `false` - same as 'legacy_disabled'. @deprecated since v4
  *
+ *   `false` - 同 'legacy_disabled'. @deprecated since v4
+ *
  * The 'enabled' option should be used for applications unless there is a reason to have
  * more control over when the router starts its initial navigation due to some complex
  * initialization logic. In this case, 'disabled' should be used.
  *
+ * 应用应该默认使用 'enabled'。如果在一些复杂的初始化逻辑中，需要在路由器开始首次导航之前进行更多的控制，则应该使用 'disabled'。
+ *
  * The 'legacy_enabled' and 'legacy_disabled' should not be used for new applications.
  *
+ * 新的应用中不应该再使用 'legacy_enabled' 和 'legacy_disabled'。
+ *
  * @experimental
  */
 export type InitialNavigation =
@@ -277,31 +355,42 @@ export type InitialNavigation =
  *
  * Represents options to configure the router.
  *
+ * 表示路由器的配置项。
  *
  */
 export interface ExtraOptions {
   /**
    * Makes the router log all its internal events to the console.
+   *
+   * 让路由器将其所有的内部事件都记录到控制台中。
    */
   enableTracing?: boolean;
 
   /**
    * Enables the location strategy that uses the URL fragment instead of the history API.
+   *
+   * 修改位置策略（`LocationStrategy`），用 URL 片段（`#`）代替 `history` API。
    */
   useHash?: boolean;
 
   /**
    * Disables the initial navigation.
+   *
+   * 禁用首次导航
    */
   initialNavigation?: InitialNavigation;
 
   /**
    * A custom error handler.
+   *
+   * 自定义的错误处理器。
    */
   errorHandler?: ErrorHandler;
 
   /**
    * Configures a preloading strategy. See `PreloadAllModules`.
+   *
+   * 配置预加载策略，参见 `PreloadAllModules`。
    */
   preloadingStrategy?: any;
 
@@ -310,22 +399,41 @@ export interface ExtraOptions {
    * By default, the router will ignore this navigation. However, this prevents features such
    * as a "refresh" button. Use this option to configure the behavior when navigating to the
    * current URL. Default is 'ignore'.
+   *
+   * 规定当路由器收到一个导航到当前 URL 的请求时该如何处理。
+   * 默认情况下，路由器会忽略本次导航。不过，这会阻止实现类似于"刷新"按钮的功能。
+   * 使用该选项可以控制导航到当前 URL 时的行为。默认为 'ignore'。
    */
   onSameUrlNavigation?: 'reload'|'ignore';
 
   /**
    * Configures if the scroll position needs to be restored when navigating back.
    *
+   * 配置是否需要在导航回来的时候恢复滚动位置。
+   *
    * * 'disabled'--does nothing (default).
+   *
+   *   'disabled' - 什么也不做（默认）。
+   *
    * * 'top'--set the scroll position to 0,0..
+   *
+   *   'top' - 把滚动位置设置为 0,0。
+   *
    * * 'enabled'--set the scroll position to the stored position. This option will be the default in
    * the future.
    *
+   *   'enabled' - 把滚动位置设置为以前保存的位置。将来这个选项会变成默认值。
+   *
    * When enabled, the router store store scroll positions when navigating forward, and will
    * restore the stored positions whe navigating back (popstate). When navigating forward,
    * the scroll position will be set to [0, 0], or to the anchor if one is provided.
    *
+   * 当启用时，路由器会在向前导航时保存滚动位置，导航回来（popstate）时则恢复所保存的位置。当向前导航时，滚动位置会设置为 [0, 0]，如果指定了锚点，则跳转到那个锚点。
+   *
    * You can implement custom scroll restoration behavior as follows.
+   *
+   * 你可以自定义滚动位置的恢复策略。
+   *
    * ```typescript
    * class AppModule {
    *  constructor(router: Router, viewportScroller: ViewportScroller, store: Store<AppState>) {
@@ -346,6 +454,8 @@ export interface ExtraOptions {
    *
    * You can also implement component-specific scrolling like this:
    *
+   * 你还可以像这样在组件级实现滚动位置恢复策略：
+   *
    * ```typescript
    * class ListComponent {
    *   list: any[];
@@ -367,20 +477,34 @@ export interface ExtraOptions {
   /**
    * Configures if the router should scroll to the element when the url has a fragment.
    *
+   * 配置当 url 中带有片段（`#`）时路由器是否滚动到那个元素。
+   *
    * * 'disabled'--does nothing (default).
+   *
+   *   'disabled' - 什么也不做（默认）。
+   *
    * * 'enabled'--scrolls to the element. This option will be the default in the future.
    *
+   *   'enabled' - 滚动到该元素。将来该选项会变为默认值。
+   *
    * Anchor scrolling does not happen on 'popstate'. Instead, we restore the position
    * that we stored or scroll to the top.
+   *
+   * 在 'popstate' 时，不会自动滚动到锚点，而是恢复应用中保存的滚动位置，或滚动到顶部。
    */
   anchorScrolling?: 'disabled'|'enabled';
 
   /**
    * Configures the scroll offset the router will use when scrolling to an element.
    *
+   * 配置当滚动到一个元素时，路由器使用的滚动偏移。
+   *
    * When given a tuple with two numbers, the router will always use the numbers.
    * When given a function, the router will invoke the function every time it restores scroll
    * position.
+   *
+   * 当给出两个数字时，路由器总会使用它们。
+   * 当给出一个函数时，路由器每当要恢复滚动位置时，都会调用该函数。
    */
   scrollOffset?: [number, number]|(() => [number, number]);
 
@@ -388,9 +512,16 @@ export interface ExtraOptions {
    * Defines how the router merges params, data and resolved data from parent to child
    * routes. Available options are:
    *
+   * 定义路由器如何把父路由的参数、数据和解析出的数据合并到子路由。有效的选项包括：
+   *
    * - `'emptyOnly'`, the default, only inherits parent params for path-less or component-less
    *   routes.
+   *
+   *   `'emptyOnly'`，默认值，只从无路径或无组件的路由中继承父路由的参数。
+   *
    * - `'always'`, enables unconditional inheritance of parent params.
+   *
+   *   `'always'`，无条件继承父路由的参数。
    */
   paramsInheritanceStrategy?: 'emptyOnly'|'always';
 
@@ -399,9 +530,20 @@ export interface ExtraOptions {
    * invalid character sequences. The default implementation is to redirect to the root url dropping
    * any path or param info. This function passes three parameters:
    *
+   * 一个自定义的 URI 格式无效错误的处理器。每当 encodeURI 包含无效字符序列时，就会调用该处理器。默认的实现是跳转到根路径，抛弃任何路径和参数信息。该函数传入三个参数：
+   *
    * - `'URIError'` - Error thrown when parsing a bad URL
+   *
+   *   `'URIError'` - 当传入错误的 URL 时抛出的错误
+   *
    * - `'UrlSerializer'` - UrlSerializer that’s configured with the router.
+   *
+   *   `'UrlSerializer'` - 路由器所配置的 UrlSerializer。
+   *
    * - `'url'` -  The malformed URL that caused the URIError
+   *
+   *   `'url'` - 导致 URIError 的格式无效的 URL
+   *
    * */
   malformedUriErrorHandler?:
       (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree;
@@ -413,8 +555,17 @@ export interface ExtraOptions {
    * URL early so if navigation fails, you can show an error message with the URL that failed.
    * Available options are:
    *
+   * 定义路由器要何时更新浏览器的 URL。默认行为是在每次成功的导航之后更新。
+   * 不过，有些应用会更愿意在导航开始时就更新。最常见的情况是尽早更新 URL，这样当导航失败时，你就可以在出错的 URL 上显示一条错误信息了。
+   * 可用的选项包括：
+   *
    * - `'deferred'`, the default, updates the browser URL after navigation has finished.
+   *
+   *   `'deferred'`，默认值，在导航完毕后更新浏览器 URL。
+   *
    * - `'eager'`, updates browser URL at the beginning of navigation.
+   *
+   *   `'eager'`，在导航开始时更新浏览器的 URL。
    */
   urlUpdateStrategy?: 'deferred'|'eager';
 
@@ -422,6 +573,8 @@ export interface ExtraOptions {
    * Enables a bug fix that corrects relative link resolution in components with empty paths.
    * Example:
    *
+   * 启用 BUG 补丁，纠正空路径组件的相对链接解析问题。
+   *
    * ```
    * const routes = [
    *   {
@@ -437,14 +590,20 @@ export interface ExtraOptions {
    *
    * From the `ContainerComponent`, this will not work:
    *
+   * 在 `ContainerComponent` 中不能这样用：
+   *
    * `<a [routerLink]="['./a']">Link to A</a>`
    *
    * However, this will work:
    *
+   * 不过，可以这样用：
+   *
    * `<a [routerLink]="['../a']">Link to A</a>`
    *
    * In other words, you're required to use `../` rather than `./`. The current default in v6
    * is `legacy`, and this option will be removed in v7 to default to the corrected behavior.
+   *
+   * 换句话说，要使用 `../` 而不是 `./`。目前 v6 版本的默认值是 `legacy`，到 v7 就会移除该选项，以纠正此行为。
    */
   relativeLinkResolution?: 'legacy'|'corrected';
 }
@@ -509,13 +668,21 @@ export function rootRoute(router: Router): ActivatedRoute {
 /**
  * To initialize the router properly we need to do in two steps:
  *
+ * 要正确初始化路由器，我们需要完成两个步骤：
+ *
  * We need to start the navigation in a APP_INITIALIZER to block the bootstrap if
  * a resolver or a guards executes asynchronously. Second, we need to actually run
  * activation in a BOOTSTRAP_LISTENER. We utilize the afterPreactivation
  * hook provided by the router to do that.
  *
+ * 为了让解析器或路由守卫能异步执行，我们需要在 APP_INITIALIZER 中开始导航，以便阻塞引导过程。
+ * 其次，我们要在 BOOTSTRAP_LISTENER 中实际运行激活逻辑。
+ * 我们利用路由器提供的 `afterPreactivation`（预激活完成后） 钩子来做到这一点。
+ *
  * The router navigation starts, reaches the point when preactivation is done, and then
  * pauses. It waits for the hook to be resolved. We then resolve it only in a bootstrap listener.
+ *
+ * 路由器开始导航，当预激活（`preactivation`）完成之后，就到达了这个时间点，并等待。它会一直等到这个钩子被解析之后才会继续。以后我们就只会在引导过程监听器中解析它了。
  */
 @Injectable()
 export class RouterInitializer {
@@ -607,6 +774,8 @@ export function getBootstrapListener(r: RouterInitializer) {
 /**
  * A token for the router initializer that will be called after the app is bootstrapped.
  *
+ * 一个代表路由器初始化器的令牌，应用引导完毕后就会调用它。
+ *
  * @experimental
  */
 export const ROUTER_INITIALIZER =