fix: 翻译 API 文档

Author: Zhicheng WANG

src/cdk-experimental/menu/menu.md

@@ -89,7 +89,7 @@ You must wrap pop-up menus with an `ng-template` with the `cdkMenuPanel` directi
 variable which must be of type `cdkMenuPanel`. Further, the `cdkMenu` must also reference the
 `cdkMenuPanel`.
 
-你必须使用带有 `cdkMenuPanel` 指令的 `ng-template` 来包装弹出菜单，并且其引用变量必须是 `cdkMenuPanel` 类型的。此外， `cdkMenu` 也必须引用这个 `cdkMenuPanel` 。
+你必须使用带有 `cdkMenuPanel` 指令的 `ng-template` 来包装弹出菜单，并且其引用变量必须是 `cdkMenuPanel` 类型的。此外，`cdkMenu` 也必须引用这个 `cdkMenuPanel`。
 
 ```html
 <ng-template cdkMenuPanel #panel="cdkMenuPanel">
@@ -129,7 +129,7 @@ container element with the `cdkContextMenuTriggerFor`, which behaves like `cdkMe
 that it responds to the browser's native `contextmenu` event. Custom context menus appear next to
 the cursor, similarly to native context menus.
 
-当用户右键单击某个容器元素时，就会打开一个上下文菜单。`cdkContextMenuTriggerFor` 标记一个容器元素，它的行为类似于 `cdkMenuTriggerFor` ，不过它会响应浏览器的原生事件 `contextmenu`。自定义上下文菜单会出现在光标旁边，类似于原生的上下文菜单。
+当用户右键单击某个容器元素时，就会打开一个上下文菜单。`cdkContextMenuTriggerFor` 标记一个容器元素，它的行为类似于 `cdkMenuTriggerFor`，不过它会响应浏览器的原生事件 `contextmenu`。自定义上下文菜单会出现在光标旁边，类似于原生的上下文菜单。
 
 <!-- example({
   "example": "cdk-menu-context",

src/cdk/a11y/a11y.md

@@ -171,7 +171,7 @@ details.
 See [the W3C's WAI-ARIA](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live)
 for more information on aria-live regions.
 
-`LiveAnnouncer` 用于通过 `aria-live` 区域为屏幕阅读器用户播报信息。关于 `aria-live` 区域的详细信息，请参见 [W3C 的 WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) 。
+`LiveAnnouncer` 用于通过 `aria-live` 区域为屏幕阅读器用户播报信息。关于 `aria-live` 区域的详细信息，请参见 [W3C 的 WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live)。
 
 #### Example
 
@@ -204,7 +204,7 @@ monitor and an optional boolean flag `checkChildren`. Passing true for `checkChi
 defaults to `false` if not specified. The `monitor` method will return an Observable that emits the
 `FocusOrigin` whenever the focus state changes. The `FocusOrigin` will be one of the following:
 
-要监听某个元素的焦点变化，可以用 `monitor` 方法传入要监控的元素和一个可选的逻辑标志 `checkChildren`。给 `checkChildren` 传入 `true` 会告诉 `FocusMonitor` ：如果该元素的任何各级子元素有焦点，就认为该元素有焦点。如果没有指定，该选项默认为 `false` 。`monitor` 方法会返回一个可观察对象，当焦点状态改变时，该对象会发送一个 `FocusOrigin`。 `FocusOrigin` 是下列值之一：
+要监听某个元素的焦点变化，可以用 `monitor` 方法传入要监控的元素和一个可选的逻辑标志 `checkChildren`。给 `checkChildren` 传入 `true` 会告诉 `FocusMonitor` ：如果该元素的任何各级子元素有焦点，就认为该元素有焦点。如果没有指定，该选项默认为 `false`。`monitor` 方法会返回一个可观察对象，当焦点状态改变时，该对象会发送一个 `FocusOrigin`。`FocusOrigin` 是下列值之一：
 
 * `'mouse'` indicates the element was focused with the mouse
 
@@ -269,7 +269,7 @@ For convenience, the CDK also provides two directives that allow for easily moni
 the host element with `checkChildren` set to `true`. Each of these directives has an `@Output()`
 `cdkFocusChange` that will emit the new `FocusOrigin` whenever it changes.
 
-为了方便使用，CDK 还提供了两个指令，可以简单地监控某个元素。`cdkMonitorElementFocus` 相当于在 `checkChildren` 为 `false` 的宿主元素上调用 `monitor`。 `cdkMonitorSubtreeFocus` 相当于在 `checkChildren` 为 `true` 的宿主元素上调用 `monitor`。这两个指令都有一个 `@Output()` `cdkFocusChange`，每当它发生变化时都会通过该事件发出新的 `FocusOrigin`。
+为了方便使用，CDK 还提供了两个指令，可以简单地监控某个元素。`cdkMonitorElementFocus` 相当于在 `checkChildren` 为 `false` 的宿主元素上调用 `monitor`。`cdkMonitorSubtreeFocus` 相当于在 `checkChildren` 为 `true` 的宿主元素上调用 `monitor`。这两个指令都有一个 `@Output()` `cdkFocusChange`，每当它发生变化时都会通过该事件发出新的 `FocusOrigin`。
 
 <!-- example(focus-monitor-directives) -->
 
@@ -344,7 +344,7 @@ targets. The accepted values are `active` (default), `black-on-white`, and `whit
 values correspond to the supported values for the
 [`-ms-high-contrast` media query][ms-high-contrast].
 
-`$target` 参数允许你指定这些样式要用高对比度模式的哪个变体。接受的值是 `active` （默认），`black-on-white` 和 `white-on-black` 。这些值对应于 [`-ms-high-contrast` 媒体查询][ms-high-contrast] 所支持的值。
+`$target` 参数允许你指定这些样式要用高对比度模式的哪个变体。接受的值是 `active` （默认），`black-on-white` 和 `white-on-black`。这些值对应于 [`-ms-high-contrast` 媒体查询][ms-high-contrast] 所支持的值。
 
 The `$encapsulation` parameter affects how the emitted styles interact with style encapsulation.
 The supported values are `on`, `off`, and `any`. The default value is `any`, which works for any
@@ -353,7 +353,7 @@ the amount of CSS emitted by limiting the styles to components with encapsulatio
 disabled, respectively. The styles emitted for encapsulated components work for both Angular's
 emulated style encapsulation and for native Shadow DOM encapsulation.
 
-`$encapsulation` 参数会影响所生成的样式与样式封装的互动。支持的值是 `on`、`off` 和 `any` 。默认值为 `any`，它生成的两个选择器，可用于任何封装方案。指定为 `on` 或 `off`，可以将样式分别限制为启用或禁用样式封装，可以轻微减小生成的 CSS 的大小。这些为带封装的组件生成的样式，会作用于 Angular 的模拟（emulated）样式封装和原生（native） Shadow DOM 封装方式。
+`$encapsulation` 参数会影响所生成的样式与样式封装的互动。支持的值是 `on`、`off` 和 `any`。默认值为 `any`，它生成的两个选择器，可用于任何封装方案。指定为 `on` 或 `off`，可以将样式分别限制为启用或禁用样式封装，可以轻微减小生成的 CSS 的大小。这些为带封装的组件生成的样式，会作用于 Angular 的模拟（emulated）样式封装和原生（native） Shadow DOM 封装方式。
 
 [Windows 高对比度模式]: https://support.microsoft.com/en-us/windows/use-high-contrast-mode-in-windows-10-fedc744c-90ac-69df-aed5-c8a90125e696
 

src/cdk/a11y/fake-event-detection.ts

@@ -6,7 +6,12 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-/** Gets whether an event could be a faked `mousedown` event dispatched by a screen reader. */
+/**
+ * Gets whether an event could be a faked `mousedown` event dispatched by a screen reader.
+ *
+ * 获取某个事件是否可能是屏幕阅读器派发的伪 `mousedown` 事件。
+ *
+ */
 export function isFakeMousedownFromScreenReader(event: MouseEvent): boolean {
   // We can typically distinguish between these faked mousedown events and real mousedown events
   // using the "buttons" property. While real mousedowns will indicate the mouse button that was
@@ -15,7 +20,12 @@ export function isFakeMousedownFromScreenReader(event: MouseEvent): boolean {
   return event.buttons === 0;
 }
 
-/** Gets whether an event could be a faked `touchstart` event dispatched by a screen reader. */
+/**
+ * Gets whether an event could be a faked `touchstart` event dispatched by a screen reader.
+ *
+ * 获取某个事件是否可能是屏幕阅读器派发的伪 `touchstart` 事件。
+ *
+ */
 export function isFakeTouchstartFromScreenReader(event: TouchEvent): boolean {
   const touch: Touch | undefined = (event.touches && event.touches[0]) ||
                                    (event.changedTouches && event.changedTouches[0]);

src/cdk/a11y/focus-monitor/focus-monitor.ts

@@ -673,7 +673,7 @@ export class FocusMonitor implements OnDestroy {
    *
    * @param event The blur event.
    *
-   * 模糊事件。
+   * 失焦事件。
    *
    * @param element The monitored element.
    *

src/cdk/a11y/focus-trap/focus-trap.ts

@@ -36,6 +36,9 @@ import {InteractivityChecker} from '../interactivity-checker/interactivity-check
  * 此类当前使用相对简单的方法进行焦点捕获。它假定 tab 顺序与 DOM 顺序相同，但这不一定正确。和 `tabIndex > 0` 一样，flex `order` 和 Shadow DOM 之类的都可能导致两者未对齐。
  *
  * @deprecated Use `ConfigurableFocusTrap` instead.
+ *
+ * 请改用 `ConfigurableFocusTrap`。
+ *
  * @breaking-change 11.0.0
  */
 export class FocusTrap {
@@ -457,6 +460,9 @@ export class FocusTrap {
  * 允许轻松实例化焦点陷阱的工厂。
  *
  * @deprecated Use `ConfigurableFocusTrapFactory` instead.
+ *
+ * 请改用 `ConfigurableFocusTrapFactory`。
+ *
  * @breaking-change 11.0.0
  */
 @Injectable({providedIn: 'root'})
@@ -474,7 +480,7 @@ export class FocusTrapFactory {
   /**
    * Creates a focus-trapped region around the given element.
    *
-   * 在指定元素周围创建一个焦点捕获 zone 。
+   * 在指定元素周围创建一个焦点捕获 zone。
    *
    * @param element The element around which focus will be trapped.
    *

src/cdk/a11y/high-contrast-mode/high-contrast-mode-detector.ts

@@ -61,14 +61,17 @@ export const HIGH_CONTRAST_MODE_ACTIVE_CSS_CLASS = 'cdk-high-contrast-active';
  * Mode. This service does not detect high-contrast mode as added by the Chrome "High Contrast"
  * browser extension.
  *
- * 目前，IE、Edge 和 Firefox 支持此模式。 Chrome 浏览器不支持 Windows 高对比度模式。此服务无法检测到由 Chrome 的“高对比度” 扩展程序添加的高对比度模式。
+ * 目前，IE、Edge 和 Firefox 支持此模式。Chrome 浏览器不支持 Windows 高对比度模式。此服务无法检测到由 Chrome 的“高对比度” 扩展程序添加的高对比度模式。
  *
  */
 @Injectable({providedIn: 'root'})
 export class HighContrastModeDetector {
   /**
    * Figuring out the high contrast mode and adding the body classes can cause
    * some expensive layouts. This flag is used to ensure that we only do it once.
+   *
+   * 检测高对比度模式并添加 body 上的类可能会导致某些昂贵的布局工作。此标志用于确保我们仅执行一次。
+   *
    */
   private _hasCheckedHighContrastMode: boolean;
   private _document: Document;

src/cdk/a11y/interactivity-checker/interactivity-checker.ts

@@ -44,15 +44,15 @@ export class InteractivityChecker {
   /**
    * Gets whether an element is disabled.
    *
-   * 获取元素是否被禁用。
+   * 获取元素是否已禁用。
    *
    * @param element Element to be checked.
    *
    * 要检查的元素。
    *
    * @returns Whether the element is disabled.
    *
-   * 元素是否被禁用。
+   * 元素是否已禁用。
    *
    */
   isDisabled(element: HTMLElement): boolean {
@@ -240,7 +240,7 @@ function isNativeFormElement(element: Node) {
 /**
  * Gets whether an element is an `<input type="hidden">`.
  *
- * 获取元素是否为 `&lt;input type="hidden">` 。
+ * 获取元素是否为 `&lt;input type="hidden">`。
  *
  */
 function isHiddenInput(element: HTMLElement): boolean {

src/cdk/a11y/key-manager/focus-key-manager.ts

@@ -14,7 +14,7 @@ import {FocusOrigin} from '../focus-monitor/focus-monitor';
  * Each item must know how to focus itself, whether or not it is currently disabled
  * and be able to supply its label.
  *
- * 这是可获取焦点条目的接口（由 FocusKeyManager 使用）。每个条目都必须知道如何获取焦点，无论当前是否被禁用并能提供其标签。
+ * 这是可获取焦点条目的接口（由 FocusKeyManager 使用）。每个条目都必须知道如何获取焦点，无论当前是否已禁用并能提供其标签。
  *
  */
 export interface FocusableOption extends ListKeyManagerOption {

src/cdk/a11y/key-manager/list-key-manager.ts

@@ -34,7 +34,7 @@ export interface ListKeyManagerOption {
   /**
    * Whether the option is disabled.
    *
-   * 该选项是否被禁用。
+   * 该选项是否已禁用。
    *
    */
   disabled?: boolean;

src/cdk/a11y/live-announcer/live-announcer.md

@@ -4,7 +4,7 @@
 See [the W3C's WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live)
 for more information on aria-live regions.
 
-`LiveAnnouncer` 用于通过 `aria-live` 区域为屏幕阅读器用户播报信息。关于 `aria-live` 区域的详细信息，请参见 [W3C 的 WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) 。
+`LiveAnnouncer` 用于通过 `aria-live` 区域为屏幕阅读器用户播报信息。关于 `aria-live` 区域的详细信息，请参见 [W3C 的 WAI-ARIA](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live)。
 
 #### Methods
 

src/cdk/accordion/accordion-item.ts

@@ -135,7 +135,7 @@ export class CdkAccordionItem implements OnDestroy {
   /**
    * Whether the AccordionItem is disabled.
    *
-   * 此条目是否被禁用了。
+   * 此条目是否已禁用了。
    *
    */
   @Input()

src/cdk/clipboard/clipboard.md

@@ -43,7 +43,7 @@ the content. Directly calling `copy` may fail in this case, so you can pre-load
 the text that was buffered. Please note, if you call `beginCopy`, you must clean up the
 `PendingCopy` object by calling `destroy` on it after you are finished.
 
-但是，对于更长的文本，浏览器需要时间来填充一个临时 textarea 元素并复制内容。在这种情况下，直接调用 `copy` 可能会失败，所以你可以通过调用 `beginCopy` 来预加载该文本。这个方法会返回一个 `PendingCopy` 对象，它有一个 `copy` 方法来真正复制缓存的文本。请注意，如果你调用过 `beginCopy` ，就必须在完成后调用 `destroy` 来清理这个 `PendingCopy` 对象。
+但是，对于更长的文本，浏览器需要时间来填充一个临时 textarea 元素并复制内容。在这种情况下，直接调用 `copy` 可能会失败，所以你可以通过调用 `beginCopy` 来预加载该文本。这个方法会返回一个 `PendingCopy` 对象，它有一个 `copy` 方法来真正复制缓存的文本。请注意，如果你调用过 `beginCopy`，就必须在完成后调用 `destroy` 来清理这个 `PendingCopy` 对象。
 
 ```typescript
 class HeroProfile {

src/cdk/clipboard/copy-to-clipboard.ts

@@ -47,6 +47,9 @@ export const CDK_COPY_TO_CLIPBOARD_CONFIG =
 
 /**
  * @deprecated Use `CDK_COPY_TO_CLIPBOARD_CONFIG` instead.
+ *
+ * 请改用 `CDK_COPY_TO_CLIPBOARD_CONFIG`。
+ *
  * @breaking-change 13.0.0
  */
 export const CKD_COPY_TO_CLIPBOARD_CONFIG = CDK_COPY_TO_CLIPBOARD_CONFIG;

src/cdk/clipboard/pending-copy.ts

@@ -23,7 +23,7 @@
  * Destroy must be called when no longer in use, regardless of whether `copy` is
  * called.
  *
- * 无论是否调用 `copy` ，都必须在不再使用时调用其 Destroy。
+ * 无论是否调用 `copy`，都必须在不再使用时调用其 Destroy。
  *
  */
 export class PendingCopy {

src/cdk/collections/collection-viewer.ts

@@ -28,7 +28,7 @@ export interface CollectionViewer {
    * A stream that emits whenever the `CollectionViewer` starts looking at a new portion of the
    * data. The `start` index is inclusive, while the `end` is exclusive.
    *
-   * `CollectionViewer` 开始查看数据的新部分时就会发出的流。 包含 `start` 索引，而不包含 `end` 索引（左闭右开区间）。
+   * `CollectionViewer` 开始查看数据的新部分时就会发出的流。包含 `start` 索引，而不包含 `end` 索引（左闭右开区间）。
    *
    */
   viewChange: Observable<ListRange>;

src/cdk/drag-drop/directives/drag.ts

@@ -203,15 +203,27 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
   /**
    * Configures the place into which the preview of the item will be inserted. Can be configured
    * globally through `CDK_DROP_LIST`. Possible values:
+   *
+   * 配置项目预览的插入位置。可以通过 `CDK_DROP_LIST` 进行全局配置。可能的值有：
+   *
    * - `global` - Preview will be inserted at the bottom of the `<body>`. The advantage is that
-   * you don't have to worry about `overflow: hidden` or `z-index`, but the item won't retain
-   * its inherited styles.
+   *   you don't have to worry about `overflow: hidden` or `z-index`, but the item won't retain
+   *   its inherited styles.
+   *
+   *   `global` —— 预览将插入在 `<body>` 的底部。其优点是你不必担心 `overflow: hidden` 或 `z-index`，但项目不会保留它继承的样式。
+   *
    * - `parent` - Preview will be inserted into the parent of the drag item. The advantage is that
-   * inherited styles will be preserved, but it may be clipped by `overflow: hidden` or not be
-   * visible due to `z-index`. Furthermore, the preview is going to have an effect over selectors
-   * like `:nth-child` and some flexbox configurations.
+   *   inherited styles will be preserved, but it may be clipped by `overflow: hidden` or not be
+   *   visible due to `z-index`. Furthermore, the preview is going to have an effect over selectors
+   *   like `:nth-child` and some flexbox configurations.
+   *
+   *   `parent` —— 预览将插入到拖动项的父级中。优点是已继承的样式将被保留，但可能会被 `overflow: hidden` 裁剪，或由于 `z-index` 而变得不可见。此外，该预览将对选择器如 `:nth-child` 和一些 flexbox 配置产生影响。
+   *
    * - `ElementRef<HTMLElement> | HTMLElement` - Preview will be inserted into a specific element.
-   * Same advantages and disadvantages as `parent`.
+   *   Same advantages and disadvantages as `parent`.
+   *
+   *   `ElementRef<HTMLElement> | HTMLElement` 预览将插入到特定元素中。具有和 `parent` 一样的优点和缺点。
+   *
    */
   @Input('cdkDragPreviewContainer') previewContainer: PreviewContainer;
 
@@ -292,9 +304,19 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
       });
 
   constructor(
-      /** Element that the draggable is attached to. */
+      /**
+       * Element that the draggable is attached to.
+       *
+       * 此可拖动对象要附着到的元素。
+       *
+       */
       public element: ElementRef<HTMLElement>,
-      /** Droppable container that the draggable is a part of. */
+      /**
+       * Droppable container that the draggable is a part of.
+       *
+       * 此可拖动对象所属的可拖动容器。
+       *
+       */
       @Inject(CDK_DROP_LIST) @Optional() @SkipSelf() public dropContainer: CdkDropList,
       /**
        * @deprecated `_document` parameter no longer being used and will be removed.

src/cdk/drag-drop/directives/drop-list.ts

@@ -51,7 +51,7 @@ let _uniqueIdCounter = 0;
  * Internal compile-time-only representation of a `CdkDropList`.
  * Used to avoid circular import issues between the `CdkDropList` and the `CdkDrag`.
  *
- * `CdkDropList` 内部的仅编译时表示法。 用来解决 `CdkDropList` 和 `CdkDrag` 之间的循环导入问题。
+ * `CdkDropList` 内部的仅编译时表示法。用来解决 `CdkDropList` 和 `CdkDrag` 之间的循环导入问题。
  *
  * @docs-private
  */
@@ -281,7 +281,12 @@ export class CdkDropList<T = any> implements OnDestroy {
   private _unsortedItems = new Set<CdkDrag>();
 
   constructor(
-      /** Element that the drop list is attached to. */
+      /**
+       * Element that the drop list is attached to.
+       *
+       * 拖放列表要附着到的元素。
+       *
+       */
       public element: ElementRef<HTMLElement>, dragDrop: DragDrop,
       private _changeDetectorRef: ChangeDetectorRef,
       private _scrollDispatcher: ScrollDispatcher,