From 6b15373d6124f034efd4655a3134f3d0d343ab60 Mon Sep 17 00:00:00 2001
From: Sean <me@sean.taipei>
Date: Tue, 26 Apr 2022 19:56:53 +0800
Subject: [PATCH] [zh] Fix the translation for "Advanced" (#33162)

* [zh] Sync Hugo shortcodes with upstream

* [zh] Fix the translation for "Advanced"
---
 content/zh/docs/contribute/advanced.md        |   2 +-
 .../contribute/style/hugo-shortcodes/index.md | 278 ++++++++++++++----
 2 files changed, 226 insertions(+), 54 deletions(-)

diff --git a/content/zh/docs/contribute/advanced.md b/content/zh/docs/contribute/advanced.md
index 5fe6df4098..ccbbd6b3a0 100644
--- a/content/zh/docs/contribute/advanced.md
+++ b/content/zh/docs/contribute/advanced.md
@@ -1,5 +1,5 @@
 ---
-title: 高级贡献
+title: 进阶贡献
 slug: advanced
 content_type: concept
 weight: 98
diff --git a/content/zh/docs/contribute/style/hugo-shortcodes/index.md b/content/zh/docs/contribute/style/hugo-shortcodes/index.md
index 02d3dfc015..ef853710f0 100644
--- a/content/zh/docs/contribute/style/hugo-shortcodes/index.md
+++ b/content/zh/docs/contribute/style/hugo-shortcodes/index.md
@@ -9,10 +9,14 @@ content_type: concept
 
 <!-- overview -->
 
-<!-- This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation. -->
+<!--
+This page explains the custom Hugo shortcodes that can be used in Kubernetes Markdown documentation.
+-->
 本页面将介绍 Hugo 自定义短代码，可以用于 Kubernetes Markdown 文档书写。
 
-<!-- Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes). -->
+<!--
+Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes).
+-->
 关于短代码的更多信息可参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。
 
 <!-- body -->
@@ -20,18 +24,18 @@ content_type: concept
 <!--
 ## Feature state
 
-In a Markdown page (.md file) on this site, you can add a shortcode to display
-version and state of the documented feature.
+In a Markdown page (`.md` file) on this site, you can add a shortcode to
+display version and state of the documented feature.
 -->
 ## 功能状态
 
-在本站的 Markdown 页面中，你可以加入短代码来展示所描述的功能特性的版本和状态。
+在本站的 Markdown 页面（`.md` 文件）中，你可以加入短代码来展示所描述的功能特性的版本和状态。
 
 <!--
 ### Feature state demo
 
-Below is a demo of the feature state snippet, which displays the feature as stable 
-in the latest Kubernetes version.
+Below is a demo of the feature state snippet, which displays the feature as
+stable in the latest Kubernetes version.
 -->
 ### 功能状态示例
 
@@ -41,12 +45,16 @@ in the latest Kubernetes version.
 {{</* feature-state state="stable" */>}}
 ```
 
-<!-- Renders to: -->
+<!--
+Renders to:
+-->
 会转换为：
 
 {{< feature-state state="stable" >}}
 
-<!-- The valid values for `state` are: -->
+<!--
+The valid values for `state` are:
+-->
 `state` 的可选值如下：
 
 * alpha
@@ -69,7 +77,9 @@ feature state version by passing the `for_k8s_version` shortcode parameter. For
 {{</* feature-state for_k8s_version="v1.10" state="beta" */>}}
 ```
 
-<!-- Renders to: -->
+<!--
+Renders to:
+-->
 会转换为：
 
 {{< feature-state for_k8s_version="v1.10" state="beta" >}}
@@ -78,10 +88,10 @@ feature state version by passing the `for_k8s_version` shortcode parameter. For
 ## Glossary
 There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`.
 
-You can reference glossary terms with an inclusion that will automatically
-update and replace content with the relevant links from [our
-glossary](/docs/reference/glossary/). When the glossary term is moused-over,
-the glossary entry displays a tooltip. The glossary term also displays as a link.
+You can reference glossary terms with an inclusion that automatically updates
+and replaces content with the relevant links from [our glossary](/docs/reference/glossary/).
+When the glossary term is moused-over, the glossary entry displays a tooltip.
+The glossary term also displays as a link.
 
 As well as inclusions with tooltips, you can reuse the definitions from the glossary in
 page content.
@@ -96,21 +106,24 @@ page content.
 
 除了包含工具提示外，你还可以重用页面内容中词汇表中的定义。
 <!--
-The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary), with a content file for each glossary term.
+The raw data for glossary terms is stored at
+[the glossary directory](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary),
+with a content file for each glossary term.
 -->
 
-词汇术语的原始数据保存在 [https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary)，每个内容文件对应相应的术语解释。
+词汇术语的原始数据保存在[词汇目录](https://github.com/kubernetes/website/tree/main/content/en/docs/reference/glossary)，
+每个内容文件对应相应的术语解释。
 
 <!--
 ### Glossary demo
 
-For example, the following include within the Markdown will render to
+For example, the following include within the Markdown renders to
 {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
 -->
 ### 词汇演示
 
-例如，下面的代码在 Markdown 中将会转换为 `{{< glossary_tooltip text="cluster" term_id="cluster" >}}`，
-然后在提示框中显示。
+例如下面的代码在 Markdown 中将会转换为
+{{< glossary_tooltip text="cluster" term_id="cluster" >}}，然后在提示框中显示。
 
 ```
 {{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
@@ -146,10 +159,68 @@ which renders as:
 呈现为： 
 {{< glossary_definition term_id="cluster" length="all" >}}
 
+<!--
+## Links to API Reference
+-->
+## 链接至 API 参考 {#links-to-api-reference}
+
+<!--
+You can link to a page of the Kubernetes API reference using the
+`api-reference` shortcode, for example to the
+{{< api-reference page="workload-resources/pod-v1" >}} reference:
+-->
+你可以使用 `api-reference` 短代码链接到 Kubernetes API 参考页面，例如
+Pod
+{{< api-reference page="workload-resources/pod-v1" >}} 参考文件：
+
+```
+{{</* api-reference page="workload-resources/pod-v1" */>}}
+```
+
+<!--
+The content of the `page` parameter is the suffix of the URL of the API reference page.
+-->
+本语句中 `page` 参数的内容是 API 参考页面的 URL 后缀。
+
+
+<!--
+You can link to a specific place into a page by specifying an `anchor`
+parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
+reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
+section of the page:
+-->
+你可以通过指定 `anchor` 参数链接到页面中的特定位置，例如到
+{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} 参考，或页面的
+{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
+部分。
+
+```
+{{</* api-reference page="workload-resources/pod-v1" anchor="PodSpec" */>}}
+{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" */>}}
+```
+
+
+<!--
+You can change the text of the link by specifying a `text` parameter, for
+example by linking to the
+{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}}
+section of the page:
+-->
+你可以通过指定 `text` 参数来更改链接的文本，例如通过链接到页面的
+{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量">}}
+部分：
+
+```
+{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量" */>}}
+```
+
+
 <!--
 ## Table captions
 
-You can make tables more accessible to screen readers by adding a table caption. To add a [caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
+You can make tables more accessible to screen readers by adding a table caption. To add a
+[caption](https://www.w3schools.com/tags/tag_caption.asp) to a table,
+enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
 
 {{< note >}}
 Table captions are visible to screen readers but invisible when viewed in standard HTML.
@@ -205,7 +276,8 @@ Parameter | Description | Default
 {{< /table >}}
 
 <!--
-If you inspect the HTML for the table, you should see this element immediately after the opening `<table>` element:
+If you inspect the HTML for the table, you should see this element immediately
+after the opening `<table>` element:
 
 ```html
 <caption style="display: none;">Configuration parameters</caption>
@@ -235,8 +307,17 @@ The `tabs` shortcode takes these parameters:
 
 <!--
 * `name`: The name as shown on the tab.
-* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
-* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`.
+* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo
+  what code language to use for highlighting.
+* `include`: The file to include in the tab. If the tab lives in a Hugo
+  [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles),
+  the file -- which can be any MIME type supported by Hugo -- is looked up in the bundle itself.
+  If not, the content page that needs to be included is looked up relative to the current page.
+  Note that with the `include`, you do not have any shortcode inner content and must use the
+  self-closing syntax. For example,
+  `{{</* tab name="Content File #1" include="example1" /*/>}}`. The language needs to be specified
+  under `codelang` or the language is taken based on the file name.
+  Non-content files are code-highlighted by default.
 -->
 * `name`： 标签页上显示的名字。
 * `codelang`: 如果要在 `tab` 短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。
@@ -245,10 +326,12 @@ The `tabs` shortcode takes these parameters:
   Hugo 会在包内查找文件（可以是 Hugo 所支持的任何 MIME 类型文件）。
   否则，Hugo 会在当前路径的相对路径下查找所要包含的内容页面。
   注意，在 `include` 页面中不能包含短代码内容，必须要使用自结束（self-closing）语法。
-  非内容文件将会被代码高亮。
+  例如 `{{</* tab name="Content File #1" include="example1" /*/>}}`。
   如果没有在 `codelang` 进行声明的话，Hugo 会根据文件名推测所用的语言。
+  默认情况下，非内容文件将会被代码高亮。
 <!--
-* If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
+* If your inner content is markdown, you must use the `%`-delimiter to surround the tab.
+  For example, `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
 * You can combine the variations mentioned above inside a tab set.
 -->
 * 如果内部内容是 Markdown，你必须要使用 `%` 分隔符来包装标签页。
@@ -282,7 +365,9 @@ println "This is tab 2."
 {{< /tabs */>}}
 ```
 
-<!-- Will be rendered as: -->
+<!--
+Renders to:
+-->
 会转换为：
 
 {{< tabs name="tab_with_code" >}}
@@ -294,41 +379,51 @@ println "This is tab 2."
 {{< /tab >}}
 {{< /tabs >}}
 
-<!-- ### Tabs demo: Inline Markdown and HTML -->
+<!--
+### Tabs demo: Inline Markdown and HTML
+-->
 ### 标签页演示：内联 Markdown 和 HTML
 
 ```go-html-template
 {{</* tabs name="tab_with_md" >}}
 {{% tab name="Markdown" %}}
-这是 **一些 markdown 。**
-{{< note >}}它甚至可以包含短代码。{{< /note >}}
+这是 **一些 markdown。**
+{{< note >}}
+它甚至可以包含短代码。
+{{< /note >}}
 {{% /tab %}}
 {{< tab name="HTML" >}}
 <div>
 	<h3>纯 HTML</h3>
-	<p>这是一些 <i>纯</i> HTML 。</p>
+	<p>这是一些 <i>纯</i> HTML。</p>
 </div>
 {{< /tab >}}
 {{< /tabs */>}}
 ```
 
-<!-- Will be rendered as: -->
+<!--
+Renders to:
+-->
 会转换为：
 
 {{< tabs name="tab_with_md" >}}
 {{% tab name="Markdown" %}}
-这是 **一些 markdown 。**
-{{< note >}}它甚至可以包含短代码。{{< /note >}}
+这是 **一些 markdown。**
+{{< note >}}
+它甚至可以包含短代码。
+{{< /note >}}
 {{% /tab %}}
 {{< tab name="HTML" >}}
 <div>
 	<h3>纯 HTML</h3>
-	<p>这是一些 <i>纯</i> HTML 。</p>
+	<p>这是一些 <i>纯</i> HTML。</p>
 </div>
 {{< /tab >}}
 {{< /tabs >}}
 
-<!-- ### Tabs demo: File include -->
+<!--
+### Tabs demo: File include
+-->
 ### 标签页演示：文件嵌套
 
 ```go-text-template
@@ -339,7 +434,9 @@ println "This is tab 2."
 {{< /tabs */>}}
 ```
 
-<!-- Will be rendered as: -->
+<!--
+Renders to:
+-->
 会转换为：
 
 {{< tabs name="tab_with_file_include" >}}
@@ -348,6 +445,78 @@ println "This is tab 2."
 {{< tab name="JSON File" include="podtemplate.json" />}}
 {{< /tabs >}}
 
+<!--
+## Third party content marker
+-->
+## 第三方内容标记  {#third-party-content-marker}
+
+<!--
+Running Kubernetes requires third-party software. For example: you
+usually need to add a
+[DNS server](/docs/tasks/administer-cluster/dns-custom-nameservers/#introduction)
+to your cluster so that name resolution works.
+-->
+运行 Kubernetes 需要第三方软件。例如：你通常需要将
+[DNS 服务器](/zh/docs/tasks/administer-cluster/dns-custom-nameservers/#introduction)
+添加到集群中，以便名称解析工作。
+
+<!--
+When we link to third-party software, or otherwise mention it,
+we follow the [content guide](/docs/contribute/style/content-guide/)
+and we also mark those third party items.
+-->
+当我们链接到第三方软件或以其他方式提及它时，我们会遵循[内容指南](/zh/docs/contribute/style/content-guide/)
+并标记这些第三方项目。
+
+<!--
+Using these shortcodes adds a disclaimer to any documentation page
+that uses them.
+-->
+使用这些短代码会向使用它们的任何文档页面添加免责声明。
+
+<!--
+### Lists {#third-party-content-list}
+-->
+### 列表  {#third-party-content-list}
+
+<!--
+For a list of several third-party items, add:
+-->
+对于有关几个第三方项目的列表，请添加：
+```
+{{%/* thirdparty-content */%}}
+```
+<!--
+just below the heading for the section that includes all items.
+-->
+在包含所有项目的段落标题正下方。
+
+<!--
+### Items {#third-party-content-item}
+-->
+### 项目  {#third-party-content-item}
+
+<!--
+If you have a list where most of the items refer to in-project
+software (for example: Kubernetes itself, and the separate
+[Descheduler](https://github.com/kubernetes-sigs/descheduler)
+component), then there is a different form to use.
+-->
+如果你有一个列表，其中大多数项目引用项目内软件（例如：Kubernetes 本身，以及单独的
+[Descheduler](https://github.com/kubernetes-sigs/descheduler)
+组件），那么可以使用不同的形式。
+
+<!--
+Add the shortcode:
+
+before the item, or just below the heading for the specific item.
+-->
+在项目之前，或在特定项目的段落下方添加此短代码：
+```
+{{%/* thirdparty-content single="true" */%}}
+```
+
+
 <!--
 ## Version strings
 
@@ -364,9 +533,10 @@ The two most commonly used version parameters are `latest` and `version`.
 <!--
 ### `{{</* param "version" */>}}`
 
-The `{{</* param "version" */>}}` shortcode generates the value of the current version of
-the Kubernetes documentation from the `version` site parameter. The `param` shortcode accepts
-the name of one site parameter, in this case: `version`.
+The `{{</* param "version" */>}}` shortcode generates the value of the current
+version of the Kubernetes documentation from the `version` site parameter. The
+`param` shortcode accepts the name of one site parameter, in this case:
+`version`.
 -->
 ### `{{</* param "version" */>}}`
 
@@ -375,10 +545,11 @@ the name of one site parameter, in this case: `version`.
 
 <!--
 {{< note >}}
-In previously released documentation, `latest` and `version` parameter values are not equivalent.
-After a new version is released, `latest` is incremented and the value of `version` for the
-documentation set remains unchanged. For example, a previously released version of the
-documentation displays `version` as `v1.19` and `latest` as `v1.20`.
+In previously released documentation, `latest` and `version` parameter values
+are not equivalent.  After a new version is released, `latest` is incremented
+and the value of `version` for the documentation set remains unchanged. For
+example, a previously released version of the documentation displays `version`
+as `v1.19` and `latest` as `v1.20`.
 {{< /note >}}
 -->
 {{< note >}}
@@ -415,7 +586,8 @@ Renders to:
 <!--
 ### `{{</* latest-semver */>}}`
 
-The `{{</* latest-semver */>}}` shortcode generates the value of `latest` without the "v" prefix.
+The `{{</* latest-semver */>}}` shortcode generates the value of `latest`
+without the "v" prefix.
 
 Renders to:
 -->
@@ -432,7 +604,7 @@ Renders to:
 
 The `{{</* version-check */>}}` shortcode checks if the `min-kubernetes-server-version`
 page parameter is present and then uses this value to compare to `version`.
- 
+
 Renders to:
 -->
 ### `{{</* version-check */>}}`
@@ -447,9 +619,9 @@ Renders to:
 <!--
 ### `{{</* latest-release-notes */>}}`
 
-The `{{</* latest-release-notes */>}}` shortcode generates a version string from `latest` and removes
-the "v" prefix. The shortcode prints a new URL for the release note CHANGELOG page with the modified
-version string.
+The `{{</* latest-release-notes */>}}` shortcode generates a version string
+from `latest` and removes the "v" prefix. The shortcode prints a new URL for
+the release note CHANGELOG page with the modified version string.
 
 Renders to:
 -->
@@ -466,14 +638,14 @@ Renders to:
 
 <!--
 * Learn about [Hugo](https://gohugo.io/).
-* Learn about [writing a new topic](/docs/home/contribute/style/write-new-topic/).
-* Learn about [page content types](/docs/home/contribute/style/page-content-types/).
-* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).
+* Learn about [writing a new topic](/docs/contribute/style/write-new-topic/).
+* Learn about [page content types](/docs/contribute/style/page-content-types/).
+* Learn about [opening a pull request](/docs/contribute/new-content/open-a-pr/).
 * Learn about [advanced contributing](/docs/contribute/advanced/).
 -->
 
-* 了解[Hugo](https://gohugo.io/)。
+* 了解 [Hugo](https://gohugo.io/)。
 * 了解[撰写新的话题](/zh/docs/contribute/style/write-new-topic/)。
 * 了解[使用页面内容类型](/zh/docs/contribute/style/page-content-types/)。
 * 了解[发起 PR](/zh/docs/contribute/new-content/open-a-pr/)。
-* 了解[高级贡献](/zh/docs/contribute/advanced/)。
+* 了解[进阶贡献](/zh/docs/contribute/advanced/)。