Update Content of MDN/Structures/Macros (#2173)

* Update MDN/Structures/Macros/Commonly-used_macros

* fix typo

* Fix typo

2 files changed, 190 insertions, 135 deletions

diff --git a/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html b/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html
index 15252fc83a..313dbd3a22 100644
--- a/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html
+++ b/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html
@@ -2,213 +2,268 @@
 title: 常用的宏
 slug: MDN/Structures/Macros/Commonly-used_macros
 tags:
-  - CSS
-  - 参考
-  - 宏
-  - 结构
+- CSS
+- 参考
+- 宏
+- 结构
 translation_of: MDN/Structures/Macros/Commonly-used_macros
 original_slug: MDN/Structures/Macros/Custom_macros
 ---
 <div>{{MDNSidebar}}</div>
 
-<p><span class="seoSummary">本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见<a href="/en-US/docs/MDN/Contribute/Content/Macros">使用宏</a>和<a href="/en-US/docs/MDN/Contribute/Editor/Links#Using_link_macros">使用链接宏</a>。</span>对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Other">其它宏</a>。这里也有一份 <a href="/en-US/docs/templates">MDN 上所有宏的完整列表</a>。</p>
+<p><span class="seoSummary">本页列举了一些 MDN 中的常用宏命令。对于使用这些宏的入门信息，请阅读<a href="/zh-CN/docs/MDN/Contribute/Content/Macros">使用宏</a>这篇文章。</span>还有一些不常用或只在特定内容中适用，以及一些不赞成使用的宏的信息，参见<a href="/zh-CN/docs/MDN/Contribute/Structures/Macros/Other">其它宏</a>。在我们的 GitHub Repo 中，可以找到<a href="https://github.com/mdn/yari/tree/master/kumascript/macros">MDN 上所有宏的完整列表</a>。</p>
 
-<p>对于适合你使用的样式，另见 <a href="/en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS 样式指南</a>。</p>
+<p>对于调整页面样式相关的宏，另见 <a href="/zh-CN/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS 样式指南</a>。</p>
 
-<h2 id="链接">链接</h2>
+<h2 id="Linking">链接</h2>
 
-<h3 id="创建一个单独的超链接">创建一个单独的超链接</h3>
+<p>为了简化一些常见超链接的创建工作——如指向站内的技术参考页面、术语库以及其他主题的链接——我们提供了丰富的宏来完成这些工作</p>
 
-<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的<strong>链接</strong>按钮创建链接。</p>
+<p>我们推荐使用宏来创建这些常见的链接，这样不但简洁，对翻译工作也很友好——使用宏创建的术语库和技术参考链接不需要翻译者再做处理，这些宏可提供正确的链接，使其符合当前页面的语言。</p>
 
-<ul>
- <li>{{TemplateLink("Glossary")}} 宏创建一个链接指向 MDN <a href="/en-US/docs/Glossary">术语汇编（glossary）</a>里的一个具体的术语词条。这个宏接受一个必须的和两个可选的参数：
-
-  <ol>
-   <li>术语的名称（比如 "HTML"）。</li>
-   <li>代替术语名称显示在文章中的文本（此项应当尽可能少地使用）。{{optional_inline}}</li>
-   <li>如果这个参数是明确的并且是非零的，一般用于术语汇编链接的自定义样式将不适用。{{optional_inline}}</li>
-  </ol>
+<h3 id="Glossayr_links">链接到术语库</h3>
 
-  <p>示例：</p>
+<p>正如{{TemplateLink("Glossary")}}这个宏的名字所示，它可用于创建指向 MDN 中<a
+    href="/zh-CN/docs/Glossary">术语库</a>内一个具体词条的链接。调用这个宏时，有一个必需的参数和一个可选参数。</p>
 
+<ol>
+  <li>术语的名字，比如“HTML”。
+    <ul>
+      <li><code>\{{Glossary("HTML")}}</code>会指向{{Glossary("HTML")}}。</li>
+    </ul>
+  </li>
+  <li>可选参数：使用参数中的文本内容，替代术语的名字显示在页面中。</li>
   <ul>
-   <li>\{{Glossary("HTML")}} 生成 {{Glossary("HTML")}}</li>
-   <li>\{{Glossary("CSS", "Cascading Style Sheets")}} 生成 {{Glossary("CSS", "Cascading Style Sheets")}}</li>
-   <li>\{{Glossary("HTML", "", 1)}} 生成 {{Glossary("HTML", "", 1)}}</li>
+    <li><code>\{{Glossary("CSS", "Cascading Style Sheets")}}</code>会指向{{Glossary("CSS", "Cascading Style Sheets")}}。
+    </li>
   </ul>
- </li>
-</ul>
+</ol>
 
-<h3 id="链接到参考文档页面">链接到参考文档页面</h3>
+<h3 id="Links_to_in-page_sections">链接到页内章节</h3>
 
-<p>有各种宏用来链接到 MDN 上特定参考区域里的页面。</p>
+<p>{{TemplateLink("anch")}} 可用于创建指向当前文章中其他小节的链接。它和 Glossary 有一个相同作用的可选参数可在翻译时使用。</p>
 
 <ul>
- <li>{{TemplateLink("cssxref")}} 链接到 <a href="/en-US/docs/CSS_Reference" title="en-US/docs/CSS_Reference">CSS 参考</a>里的一个页面。<br>
-  示例： <code>\{{cssxref("cursor")}}</code>，显示为：{{ cssxref("cursor") }} 。</li>
- <li>{{TemplateLink("domxref")}} 链接到 DOM 参考里的页面；如果你在结尾列入了圆括号，这个模板会像一个函数名那样显示这个链接。例如，<span class="plain"><span class="nowiki">\{{domxref("document.getElementsByName()")}}</span></span> 显示为 {{ domxref("document.getElementsByName()") }} <code>而 \{\{domxref("Node")\}\}</code> 显示为 {{ domxref("Node") }} 。</li>
- <li>{{TemplateLink("event")}} 链接到 DOM 事件参考，例如：\{{event("change")}} 显示为 {{event("change")}} 。</li>
- <li>{{TemplateLink("HTMLElement")}} 链接到 HTML 参考里的一个 HTML 元素。</li>
- <li>{{TemplateLink("htmlattrxref")}} 链接到一个 HTML 属性。如果你只指定属性名，它将是一个全局属性的描述。如果你指定一个属性名和一个元素名，它将是一个具体元素的一个属性名。例如，<code>\{\{htmlattrxref("lang")\}\} </code>将创建链接：{{htmlattrxref("lang")}} 。<code>\{\{htmlattrxref("type","input")\}\}</code> 将创建链接：{{htmlattrxref("type","input")}} 。</li>
- <li>{{TemplateLink("jsxref")}} 链接到 <a href="/en-US/docs/Web/JavaScript/Reference" title="en-US/docs/Web/JavaScript/Reference">JavaScript 参考</a>里的一个页面。</li>
- <li>{{TemplateLink("SVGAttr")}} 链接到一个特定的 SVG 属性。例如，<code>\{\{SVGAttr("d")\}\}</code> 创建这样的链接： {{SVGAttr("d")}} 。</li>
- <li>{{TemplateLink("SVGElement")}} 链接到 SVG 参考里的一个 SVG 元素。</li>
+  <li><code>\{{anch("Linking to pages in references","链接到 MDN 的参考文档页面")}}</code></li>
+  <li>
+    <p>实际效果：{{anch("Linking to pages in references","链接到 MDN 的参考文档页面")}}</p>
+  </li>
 </ul>
 
-<h3 id="链接到漏洞和互联网中继聊天（IRC）">链接到漏洞和互联网中继聊天（IRC）</h3>
+<h3 id="Linking_to_pages_in_references">链接到 MDN 的参考文档页面</h3>
+
+<p>下面列出的宏可链接到 MDN 站内不同技术领域的参考文档，如 Javascript,、CSS、HTML、elements、SVG 等。</p>
+
+<P>这些宏都很容易上手，大多数情况下只需一个参数——所涉及的 Web 组件的名字（如标签、对象、方法、属性等的名字）。在{{anch("Glossayrlinks","术语库")}}中提到的，可修改实际显示的文本的可选参数，也存在于下面大多数宏中。如果你想了解其他参数，表格中最左列的链接中可以查看相关宏的文档。</P>
+
+<table class="standard-table">
+  <thead>
+    <tr>
+      <th>宏</th>
+      <th>所归属的主题页面</th>
+      <th>示例</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{TemplateLink("CSSxRef")}}</td>
+      <td><a href="/zh-CN/docs/Web/CSS/Reference">CSS 参考文档</a> (/Web/CSS/Reference)</td>
+      <td><code>\{{CSSxRef("cursor")}}</code>会指向{{CSSxRef("cursor")}}.</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("DOMxRef")}}</td>
+      <td><a href="/zh-CN/docs/Web/API">DOM 参考文档</a> (/Web/API)</td>
+      <td><code>\{{DOMxRef("Document")}}</code>或<code>\{{DOMxRef("document")}}</code>都指向{{DOMxRef("Document")}}。<br>
+        <code>\{{DOMxRef("document.getElementsByName()")}}</code>会指向{{DOMxRef("document.getElementsByName()")}}<br>
+        <code>\{{DOMxRef("Node")}}</code>会指向{{DOMxRef("Node")}}. <br>
+        你可以使用第二个参数控制在页面上实际显示的文本：<code>\{{DOMxRef("document.getElementsByName()","getElementsByName()")}}</code>会生成{{DOMxRef("document.getElementsByName()","getElementsByName()")}}
+      </td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("HTMLElement")}}</code>
+      </td>
+      <td><a href="/zh-CN/docs/Web/HTML/Element">HTML 元素参考文档</a> (/Web/HTML/Element)</td>
+      <td><code>\{{HTMLElement("select")}}</code>会指向{{HTMLElement("select")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("HTMLAttrxRef")}}</td>
+      <td>如果只指明了属性的名字，链接会跳转到 <a href="/zh-CN/docs/Web/HTML/Global_attributes">HTML 全局属性</a>页面对应属性的位置。<br/>如果同时指明 HTML 元素和属性名，则会跳转到元素页面下对应属性的位置。</td>
+      <td>
+        <code>\{{HTMLAttrxRef("lang")}} </code>会指向{{HTMLAttrxRef("lang")}}.<br /><code>\{{HTMLAttrxRef("type","input")}}</code>生成的链接则会跳转到{{HTMLElement("input")}}元素页面下的{{HTMLAttrxRef("type","input")}}属性。
+      </td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("JSxRef")}}</td>
+      <td><a href="/zh-CN/docs/Web/JavaScript/Reference">JavaScript 参考文档</a>（/Web/JavaScript/Reference）.</td>
+      <td><code>\{{JSxRef("Promise")}}</code>会指向{{JSxRef("Promise")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("SVGAttr")}}</td>
+      <td><a href="/zh-CN/docs/Web/SVG/Attribute">SVG 属性参考</a> (/Web/SVG/Attribute).</td>
+      <td><code>\{{SVGAttr("d")}}</code>会指向{{SVGAttr("d")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("SVGElement")}}</td>
+      <td><a href="/zh-CN/docs/Web/SVG/Element">SVG 元素参考</a> (/Web/SVG/Element).</td>
+      <td><code>\{{SVGElement("view")}}</code>会指向{{SVGElement("view")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("HTTPHeader")}}</td>
+      <td><a href="/zh-CN/docs/Web/HTTP/Headers">HTTP 消息头</a> (/Web/HTTP/Headers).</td>
+      <td><code>\{{HTTPHeader("ACCEPT")}}</code>会指向{{HTTPHeader("ACCEPT")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("HTTPMethod")}}</td>
+      <td><a href="/zh-CN/docs/Web/HTTP/Methods">HTTP 请求方法</a> (/Web/HTTP/Methods).</td>
+      <td><code>\{{HTTPMethod("HEAD")}}</code>会指向{{HTTPMethod("HEAD")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("HTTPStatus")}}</td>
+      <td><a href="/zh-CN/docs/Web/HTTP/Status">HTTP 响应代码</a> (/Web/HTTP/Status)</td>
+      <td><code>\{{HTTPStatus("404")}}</code>会指向{{HTTPStatus("404")}}</td>
+    </tr>
+    <tr>
+      <td>{{TemplateLink("event")}}</td>
+      <td><a href="/zh-CN/docs/Web/Events">事件参考</a> (/Web/Events)</td>
+      <td>
+        <div class="notecard note">
+          <h4>注意</h4>
+          <p>因为事件关联在具体的元素下，这个宏不是特别有用。例如想指向 wheel 事件的页面，需要使用
+            <code>\{{DOMxRef("Document.wheel_event")}}</code>：{{DOMxRef("Document.wheel_event")}}
+          </p>
+        </div>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<h3 id="Linking_to_bugs">关联到某个 Bug</h3>
 
 <ul>
- <li>漏洞
-  <ul>
-   <li>通过使用下面的语法 {{TemplateLink("bug")}} 可以让你轻松地链接到 bugzilla.mozilla.org 上的一个漏洞（页面）：<code>\{\{Bug(123456)\}\}</code> 。这将显示：{{ Bug(123456) }} 。</li>
-   <li>{{TemplateLink("WebkitBug")}} 插入一条指向 WebKit 漏洞数据库中一个漏洞的链接。例如：<code>\{\{WebkitBug(31277)\}\}</code> 插入 {{ WebkitBug(31277) }} 。</li>
-  </ul>
- </li>
- <li>{{TemplateLink("IRCLink")}} 插入一条指向特定 IRC 频道的链接，它带有一个提示框标明它是做什么的以及它需要一个 IRC 客户端。</li>
+  <li>Bugs
+    <ul>
+      <li>通过编号，{{TemplateLink("bug")}}宏可以指向<a href="bugzilla.mozilla.org">bugzilla.mozilla.org</a>站内相应的 bug，<code>\{{Bug(123456)}}</code>会指向{{Bug(123456)}}.
+      </li>
+      <li>类似的，{{TemplateLink("WebkitBug")}}宏同样可以借助编号，指向 WebKit bug 库里对应的 bug。例如，<code>\{{WebkitBug(31277)}}</code>会指向{{WebkitBug(31277)}}.
+      </li>
+    </ul>
+  </li>
 </ul>
 
-<h3 id="用于多页面指南的导航帮助">用于多页面指南的导航帮助</h3>
+<h3 id="Navigation_aids_for_multi-page_guides">多页面间的导航栏</h3>
 
-<p>{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。</p>
+<p>
+  {{TemplateLink("Previous")}}、{TemplateLink("Next")}}、{{TemplateLink("PreviousNext")}}、{{TemplateLink("PreviousMenuNext")}}这几个宏可以在页面中创建导航栏，帮助读者按照文章的先后顺序阅读。其中的参数需要填入目标页面在 MDN 中的位置，你可以在页面的网址中找到所需的信息。例如 <a href="/zh-CN/docs/Learn/JavaScript/Objects/Inheritance">JavaScript 中的继承</a>这个页面，链接地址为“https://developer.mozilla.org/zh-CN/docs/Learn/JavaScript/Objects/Inheritance”，那么它在 MDN 中的位置就可以用<code>Learn/JavaScript/Objects/Object_prototypes</code>描述。</p>
 
-<h2 id="代码示例">代码示例</h2>
+<h2 id="Code_samples">代码示例</h2>
 
-<h3 id="实样">实样</h3>
+<h3 id="Live_samples">动态示例</h3>
 
 <ul>
- <li>{{TemplateLink("EmbedLiveSample")}} 让你嵌入一个如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样（Live samples）</a>中描述的代码示例结果到页面上。</li>
- <li>{{TemplateLink("LiveSampleLink")}} 创建一个链接指向一个包含（当前）页面上如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样</a>中描述的代码示例结果。</li>
+  <li>{{TemplateLink("EmbedLiveSample")}} 可嵌入一个在<a href="/zh-CN/docs/MDN/Contribute/Structures/Live_samples">动态示例</a>中描述的代码示例，到当前页面上。</li>
+  <li>{{TemplateLink("LiveSampleLink")}} 创建一个页面链接，其中包含如<a href="/zh-CN/docs/MDN/Contribute/Structures/Live_samples">动态示例</a>中描述的示例的结果。</li>
+  <li>{{TemplateLink("EmbedGHLiveSample")}} 提供了一种新的动态示例编写和使用方式，你可以在<a href="/zh-CN/docs/MDN/Structures/Code_examples#github_live_samples">Github动态示例</a>中了解更多信息。</li>
 </ul>
 
-<h3 id="附上的示例文件">附上的示例文件</h3>
+<h2 id="Sidebar_generation">添加侧边栏组</h2>
 
-<ul>
- <li>{{TemplateLink("Embed_text")}} 模板允许你嵌入一份附加的文本文件到你的文章主体部分中。这将有助于你让代码段既可下载又能显示在文章内容中。你可以为语法高亮选择地指定一种语言。如果你不指定一种（语言），该文本将无格式化嵌入。第一个参数是被嵌入附件的文件名；第二个（参数），如果支持的话，是用于语法高亮的语言，比如 "javascript", "svg" 或 "cpp" 。</li>
- <li>{{TemplateLink("EmbedSVG")}} 嵌入一个附带 XML 文件作为一张 SVG 图像到页面当中。指定附带的 SVG 文件的文件名。你可以和 {{TemplateLink("Embed_text")}} 一同使用来展示源码和相同文件的渲染输出。</li>
-</ul>
-
-<h2 id="侧边栏组">侧边栏组</h2>
-
-<p>There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。</p>
+<p>一些有海量子条目的主题，比如技术参考、指南、教程等，通常需要一个单独的主页面提供导航。对于这些主题中的页面，顶部的面包屑导航就显得比较简陋，下面这些模板，可以在页面的左侧，生成对应主题的侧边导航栏。</p>
 
 <ul>
- <li>{{TemplateLink("CSSRef")}} 生成 CSS 参考页面的侧边栏。</li>
- <li>{{TemplateLink("HTMLRef")}} 生成 HTML 参考页面的侧边栏。</li>
- <li>{{TemplateLink("APIRef")}} 生成 Web API 参考页面的侧边栏。</li>
+  <li>{{TemplateLink("CSSRef")}} 生成 CSS 参考页面的侧边栏。</li>
+  <li>{{TemplateLink("HTMLRef")}} 生成 HTML 参考页面的侧边栏。</li>
+  <li>{{TemplateLink("APIRef")}} 生成 Web API 参考页面的侧边栏。</li>
 </ul>
 
-<p>（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）</p>
-
-<h2 id="通用格式化">通用格式化</h2>
+<h2 id="General-purpose_formatting">通用的文章格式化工具</h2>
 
-<h3 id="API_文档的行内指示器">API 文档的行内指示器</h3>
+<h3 id="Inline_indicators_for_API_documentation">API 文档的行内指示器</h3>
 
-<p>{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。</p>
+<p>{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常可以用来描述一个对象的属性是只读的或一个函数的参数是可省略的。
+</p>
 
-<p>用法: <code>\{{optional_inline()}}</code> 或 <code>\{{ReadOnlyInline()}} 。</code>示例：</p>
+<p>用法: <code>\{{optional_inline}}</code> 或 <code>\{{ReadOnlyInline}} 。</code>示例：</p>
 
 <dl>
- <dt><code>isCustomObject</code> {{ReadOnlyInline()}}</dt>
- <dd>如果为真，指示该对象是一个自定义对象。</dd>
- <dt>parameterX {{ optional_inline() }}</dt>
- <dd>Blah blah blah...</dd>
+  <dt><code>isCustomObject</code> {{ReadOnlyInline}}</dt>
+  <dd>如果此项值为 <code>true</code>，表明该对象是一个自定义对象。</dd>
+  <dt>某项参数{{optional_inline}}</dt>
+  <dd>参数描述</dd>
 </dl>
 
-<h2 id="状态和兼容性指示器">状态和兼容性指示器</h2>
+<h2 id="Status_and_compatibility_indicators">状态和兼容性指示器</h2>
 
-<h3 id="没有附加参数的行内指示器">没有附加参数的行内指示器</h3>
+<h3 id="Inline_indicators_with_no_additional_parameters">无需参数的行内指示器</h3>
 
-<h4 id="非标准的">非标准的</h4>
+<h4 id="Non-standard">非标准</h4>
 
-<p>{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。</p>
+<p>{{TemplateLink("non-standard_inline")}} 指示当前 API 还没有被标准化，也没有进入标准化议程。</p>
 
-<h5 id="语法"><strong>语法</strong></h5>
+<h5 id="Syntax"><strong>语法</strong></h5>
 
 <p><code>\{{non-standard_inline}}</code></p>
 
-<h5 id="示例">示例</h5>
+<h5 id="Examples">示例</h5>
 
 <ul>
- <li>图标：{{non-standard_inline}}</li>
+  <li>图标：{{non-standard_inline}}</li>
 </ul>
 
-<h4 id="实验性的">实验性的</h4>
+<h4 id="Experimental">实验性的</h4>
 
-<p>{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。</p>
+<p>{{TemplateLink("experimental_inline")}} 指示当前 API 没有被广泛支持，且将来可能会有所修改。</p>
 
-<h5 id="语法_2">语法</h5>
+<h5 id="Syntax_2">语法</h5>
 
 <p><code>\{{experimental_inline}}</code></p>
 
-<h5 id="示例_2"><code>示例</code></h5>
+<h5 id="Examples_2"><code>示例</code></h5>
 
 <ul>
- <li>图标：{{experimental_inline}}</li>
+  <li>图标：{{experimental_inline}}</li>
 </ul>
 
-<h3 id="提供明确技术的指示器">提供明确技术的指示器</h3>
-
-<p>在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。</p>
+<h3 id="Inline_indicators_that_support_specifying_the_technology">代表明确技术参考的行内指示器</h3>
 
-<h4 id="不赞成的">不赞成的</h4>
+<h4 id="Deprecated">不赞成的</h4>
 
-<p>{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。<strong>注意：</strong>“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。</p>
+<p>{{TemplateLink("deprecated_inline")}}会插入一个带有“不赞成”的行内指示器，即{{Deprecated_Inline}}。这表示不鼓励使用该 API ，或其已经被移除。</p>
 
-<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p>
+<h5 id="Syntax_3">语法</h5>
 
-<h5 id="语法_3">语法</h5>
+<p><code>\{{deprecated_inline}}</code>></p>
 
-<p><code>\{{deprecated_inline}}</code> <code>或 \{{deprecated_inline("gecko5")}}</code></p>
-
-<h5 id="示例_3">示例</h5>
+<h5 id="Examples_3">示例</h5>
 
 <ul>
- <li>图标：{{deprecated_inline}}</li>
- <li>徽标：{{deprecated_inline("gecko5")}}</li>
+  <li>图标：{{deprecated_inline}}</li>
 </ul>
 
-<h4 id="已废弃的">已废弃的</h4>
-
-<p>{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。</p>
+<h3 id="Page_or_section_header_indicators">页面或章节头部的指示器</h3>
 
-<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p>
+<p>下列指示器的含义，类似于上述的内联指示器。这些组件应直接放置在技术参考页面的标题（或面包屑导航栏）下，也可以用于标记页面上的某个小节。</p>
 
-<h5 id="语法_4">语法</h5>
+<ul>
+  <li>{{TemplateLink("non-standard_header")}}语法：<code>\{{Non-standard_header()}}</code> {{ Non-standard_header}}</li>
 
-<p><code>\{{obsolete_inline}}</code> 或<code> \{{obsolete_inline("js1.8.5")}}</code></p>
+  <li>{{TemplateLink("SeeCompatTable")}} 对于一些介绍<a href="/zh-CN/docs/MDN/Guidelines/Conventions_definitions#experimental">实验性功能</a>的内容，应当在这些内容前放置此指示器。语法：<code>\{{SeeCompatTable}}</code> {{SeeCompatTable()}}</li>
 
-<h5 id="示例_4">示例</h5>
+  <li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li>
 
-<ul>
- <li>图标：{{obsolete_inline}}</li>
- <li>徽标：{{obsolete_inline("js1.8.5")}}</li>
+  <li>{{TemplateLink("secureContext_header")}}: <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li>
 </ul>
 
-<h3 id="模板徽标">模板徽标</h3>
+<h3 id="Indicating_that_a_feature_is_available_in_web_workers">指示一个功能在 web workers 中可用</h3>
 
-<p>这些宏大多数被用于 <a href="/en-US/docs/WebAPI">WebAPI</a> 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。</p>
+<p> {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在<a href="/zh-CN/docs/Web/API/Web_Workers_API">Web worker</a>上下文中可用。它还有一个可选参数，当带有<code>notservice</code>时，表示该功能在 web worker 中可用但在 servcie worker 中不可用。</p>
 
-<h3 id="页面或区域标头指示">页面或区域标头指示</h3>
+<h5 id="Syntax_4">语法</h5>
 
-<p>这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。</p>
-
-<ul>
- <li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_header()}}</code> {{ Non-standard_header() }}</li>
- <li>{{TemplateLink("SeeCompatTable")}} 应该被放置在介绍实验性功能或兼容性的区域。 示例: <code>\{{SeeCompatTable()}}</code> {{ SeeCompatTable() }}</li>
- <li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li>
- <li>{{TemplateLink("deprecated_header")}} 搭配变量: <code>\{{deprecated_header("gecko5")}}</code> {{ Deprecated_header("gecko5") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li>
- <li>{{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header()}}</code> {{ Obsolete_header() }}</li>
- <li>{{TemplateLink("obsolete_header")}} 搭配变量: <code>\{{obsolete_header("gecko30")}}</code> {{ Obsolete_header("gecko30") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li>
- <li>{{TemplateLink("secureContext_header")}}: <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li>
-</ul>
+<p>\{{AvailableInWorkers}}
+  \{{AvailableInWorkers("notservice")}}</p>
 
-<h3 id="指示一个功能在Web_workers中可用">指示一个功能在Web workers中可用</h3>
+<h5 id="Examples_5">Examples</h5>
 
-<p> {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在<a href="/en-US/docs/Web/API/Web_Workers_API">Web worker</a> 上下文中可用。</p>
-
-<ol>
-</ol>
-
-<ol>
-</ol>
+<div>{{AvailableInWorkers}}
+  {{AvailableInWorkers("notservice")}}
+</div>
diff --git a/files/zh-cn/mdn/structures/macros/index.html b/files/zh-cn/mdn/structures/macros/index.html
index 4227374bac..67cd0470bd 100644
--- a/files/zh-cn/mdn/structures/macros/index.html
+++ b/files/zh-cn/mdn/structures/macros/index.html
@@ -11,17 +11,17 @@ translation_of: MDN/Structures/Macros
 ---
 <div>{{MDNSidebar}}</div>
 
-<p><span class="seoSummary">为了自动化执行某些工作，<a href="/zh-CN/docs/MDN/Yari">Yari</a> 平台提供了一个强大的宏系统——<a href="/zh-CN/docs/MDN/Tools/KumaScript">KumaScript</a>。本文提供了一些相关信息，方便你在参与编辑 MDN 时，使用这些宏。</span></p>
+<p><span class="seoSummary">为了自动化执行某些工作，<a href="/zh-CN/docs/MDN/Yari">Yari</a> 平台提供了一个强大的宏系统——<a href="/zh-CN/docs/MDN/Tools/KumaScript">KumaScript</a>。本文提供了一些相关信息，方便你在参与编辑 MDN 时使用这些宏。</span></p>
 
-<p>本文只是简要介绍了 KumaScript，<a href="/zh-CN/docs/MDN/Kuma/KumaScript_guide" title="/zh-CN/docs/MDN/Kuma/KumaScript_guide">KumaScript 指南</a>提供了更深入的内容，帮助你使用和掌握它。</p>
+<p>本文只是简要介绍了相关内容，<a href="/zh-CN/docs/MDN/Tools/KumaScript">KumaScript 指南</a>提供了更深入的内容。</p>
 
 <h2 id="How_macros_are_implemented">宏是如何实现的</h2>
 
-<p>MDN 使用宏是基于运行于服务器上的 JavaScript 代码实现的，并由 <a href="http://nodejs.org/">Node.js</a> 解释执行。在此之上，已经实现了一个丰富的工具库，让宏可以与这个平台及其中的内容进行互动。</p>
+<p>MDN 使用的宏基于运行于服务器上的 JavaScript 代码来实现，并由 <a href="http://nodejs.org/">Node.js</a> 解释执行。在此之上，已经实现了一个丰富的工具库，让宏可以与这个平台以及其中的内容进行交互。</p>
 
 <h2 id="Using_a_macro_in_content">在文章中使用宏</h2>
 
-<p>要实际使用宏，只需将对宏的调用和可能需要的参数写在一对双括号中，如下：</p>
+<p>要在文章中实际使用宏，只需将对宏的调用和可能需要的参数写在一对双括号中，如下：</p>
 
 <pre class="notranslate">\{{macroname(parameter-list)}}</pre>
 
@@ -30,13 +30,13 @@ translation_of: MDN/Structures/Macros
 <ul>
  <li>宏的名称区分大小写，但一些常见的大小写错误也可以在执行时被纠正。比如将某个名称中含有大写的宏，全部使用小写字母，或者将某些名字以小写开头的宏大写。</li>
  <li>参数以逗号分隔。</li>
- <li>如果没有参数，括号可以省略：<code>\{{macroname()}}</code> 和 <code>\{{macroname}}</code> 的效果是。</li>
- <li>数字参数可以是引号，也可以不是。这取决于您（但是，像版本号这类可能被识别成小数的参数，则包含在引号中）</li>
+ <li>如果没有参数，括号可以省略：<code>\{{macroname()}}</code> 和 <code>\{{macroname}}</code> 的作用是相同的。</li>
+ <li>数字参数是否放在引号中，一般没有区别。但是，像版本号（如1.2.3）这类可能被识别成小数的参数，则需包含在引号中。</li>
  <li>如果遇到错误，请先仔细检查代码。如果仍然无法弄清楚发生了什么，请参阅<a href="/zh-CN/docs/MDN/Tools/KumaScript/Troubleshooting">排查 KumaScript 中的错误</a>以获取帮助。</li>
 </ul>
 
-<p>宏的几乎所有执行结果都会被缓存，以便被重用来加快执行速度。这意味着宏仅在输入发生变化时才实际运行，包括调用时的参数以及环境值（例如这个宏被调用时所在的路径）。</p>
+<p>宏的几乎所有执行结果都会被缓存，以便被重用并加快执行速度。这意味着宏仅在输入发生变化时才实际运行，包括调用时的参数以及环境值（例如调用这个宏的文章所在的路径）。</p>
 
-<p>宏既可以用来做一些简单的工作，比如插入更大的文本块或从MDN的另一部分交换内容一样简单，也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。</p>
+<p>宏既可以用来做一些简单的工作，比如插入更大的文本块或用 MDN 的替换文章中的内容。也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。</p>
 
-<p>您可以在<a href="/zh-CN/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">常用的宏</a>页面看到一些我们最常用到的宏，还可以在我们 Github 的仓库中，浏览<a href="https://github.com/mdn/yari/tree/master/kumascript/macros">所有可用的宏</a>。大多数宏顶部的注释中，都有内置的文档帮助你了解它的作用。</p>
+<p>你可以在<a href="/zh-CN/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">常用的宏</a>页面看到一些我们最常用到的宏，还可以在我们 Github 的仓库中，浏览<a href="https://github.com/mdn/yari/tree/master/kumascript/macros">所有可用的宏</a>。大多数宏顶部的注释中，都有内置的文档帮助你了解它的作用。</p>