diff options
| author | t7yang <t7yang@gmail.com> | 2021-05-03 01:26:21 +0800 |
|---|---|---|
| committer | Irvin <irvinfly@gmail.com> | 2021-05-03 16:32:38 +0800 |
| commit | 01d82319d26f908e24379d8c04acd8c99e498a2c (patch) | |
| tree | e66d4a91349b4a887fa863d4fe1c1d3e54727f10 /files/zh-tw | |
| parent | e148780fff69e6e2db636ab6f13d2fcdff7f8766 (diff) | |
| download | translated-content-01d82319d26f908e24379d8c04acd8c99e498a2c.tar.gz translated-content-01d82319d26f908e24379d8c04acd8c99e498a2c.tar.bz2 translated-content-01d82319d26f908e24379d8c04acd8c99e498a2c.zip | |
Update /mdn/guidelines/writing_style_guide, zh-TW
Diffstat (limited to 'files/zh-tw')
| -rw-r--r-- | files/zh-tw/mdn/guidelines/writing_style_guide/index.html | 691 |
1 files changed, 372 insertions, 319 deletions
diff --git a/files/zh-tw/mdn/guidelines/writing_style_guide/index.html b/files/zh-tw/mdn/guidelines/writing_style_guide/index.html index c9ee99400a..cc90ee9ab4 100644 --- a/files/zh-tw/mdn/guidelines/writing_style_guide/index.html +++ b/files/zh-tw/mdn/guidelines/writing_style_guide/index.html @@ -1,181 +1,316 @@ --- -title: MDN 風格指南 +title: 寫作風格指南 slug: MDN/Guidelines/Writing_style_guide -translation_of: MDN/Guidelines/Writing_style_guide +tags: + - 文件 + - 指南 + - 指導方針 + - MDN Web 文件 + - MDN 風格指南 + - 風格指南 + - 寫作風格指南 + - Documentation + - Guide + - Guidelines + - MDN + - MDN Meta + - MDN Web Docs + - MDN style guide + - Style guide + - Writing style guide --- <div>{{MDNSidebar}}</div> -<p><span class="seoSummary">為了讓文檔更加組織化、標準化而易於閱讀，MDN 風格指南描述了文本的組織方式、拼寫和格式等問題。</span>這些規則只是指導方針而非強制規定。與格式相比，我們對內容更感興趣，因此在你做貢獻之前，大可不必因為沒有學習本指南而感到驚訝或沮喪，只管放手去做便是。勤勞的志願者們會編輯你的工作以符合本指南。</p> +<p><span class="seoSummary">為了讓文件更加組織化、標準化而易於閱讀，MDN 風格指南描述了文件的組織方式、拼寫、格式等問題。</span>這些規則只是指導方針而非強制規定。與格式相比，我們對內容更感興趣，因此不用覺得在開始貢獻之前有被迫要學習這些指南的壓力。若之後有其他支援者修改了你的內容以便讓它符合這些指南，你也不需要因此而感到沮喪或驚訝。</p> -<p>如果你在尋找頁面應當如何結構化的具體方式，參見 <a href="/zh-CN/docs/MDN/Contribute/Content/Layout" style="line-height: 1.5;">MDN 頁面配置指南</a>。</p> +<p>在語言方面，本指南主要適用於英語文件，其它語言可擁有（且歡迎建立）自己的風格指南。它們會以當地語系團隊頁面的子頁面發佈。</p> -<p>在語言方面，本指南主要適用於英語文檔，其它語言可擁有（且歡迎創建）自己的風格指南。它們應作為當地語系化團隊頁面的子頁面發佈。</p> - -<p>有關 MDN 以外網站內容的風格標準，請參考 <a href="http://www.mozilla.org/zh-CN/styleguide/" title="http://www.mozilla.org/en-US/styleguide/">Mozilla 風格指南</a>。</p> - -<h2 id="Page_name_and_heading_capitalization" name="Page_name_and_heading_capitalization">基礎</h2> +<h2 id="Basics">基礎</h2> <p>維持整份文件的一致性是各大文件發表風格指南的基礎。以下段落將會列出這些基礎概念來協助您。</p> -<h3 id="頁面標題">頁面標題</h3> +<h3 id="Page_titles">頁面標題</h3> -<p>頁面標題會展示於搜索結果中，也可用於在頂部的麵包屑導航列中的層次結構以建構頁面。頁面標題可以與頁面“縮略名”不同。縮略名會出現在“<em><locale>/docs/”後，是頁面URL的一部分。</em></p> +<p>頁面標題會展示於搜索結果，也可用於在頂部的麵包屑導覽列中的層次結構以建構頁面。網頁標題（既顯示在頁面頂端及搜尋結果）也會因頁面的「路徑」而異，這些路徑就是組成頁面網址的一部分—— 「<code><var><locale></var>/docs/</code>」 。</p> -<h4 id="標題與頁首的大小寫">標題與頁首的大小寫</h4> +<h4 id="Title_and_heading_capitalization">標題與頁首的大小寫</h4> -<p>頁面標題與章節標題應使用一般句子的大小寫形式（只大寫句首字母和專有名詞）， 而非新聞式標題。</p> +<p>頁面標題與章節標題應使用一般句子的大小寫形式（只對句首字母和專有名詞大寫），而非新聞式標題：</p> <ul> - <li><span class="correct"><strong>正確</strong></span>：“A new method for creating JavaScript rollovers”</li> - <li><span class="incorrect"><strong>錯誤</strong></span>：“A New Method for Creating JavaScript Rollovers”</li> -</ul> + <li><span class="correct"><strong>正確</strong></span>：“A new method for creating JavaScript rollovers”</li> + <li><span class="incorrect"><strong>錯誤</strong></span>：“A New Method for Creating JavaScript Rollovers”</li> + </ul> -<p>有些舊的頁面編寫於本樣式規則定版之前。若你願意，可隨時更新它們。我們會逐漸完善它們。</p> + <p>有些舊的頁面編寫於本樣式規則定版之前。若你願意，可隨時更新它們。我們會逐漸完善它們。</p> -<h4 id="選擇標題與簡述">選擇標題與簡述</h4> +<h4 id="Choosing_titles_and_slugs">選擇標題與路徑</h4> -<p>頁面縮略名應保持簡短；當創建新的層級時， 該層次的縮略名通常應只由一兩個單詞組成。</p> +<p>頁面路徑應保持簡短。當建立新的層級時，該層級的路徑應只由一兩個單詞組成。</p> <p>至於頁面標題，只要在合理範圍內，長度可以隨意，不過它應當是描述性的。</p> -<h4 id="創建新子樹">創建新子樹</h4> +<h4 id="Creating_new_subtrees">建立新的子目錄</h4> -<p>當你需要添加關於某個主題或主題範圍的文章時，一般可以創建一個登陸頁面，然後為這些文章分別添加子頁面。登陸頁面應當以一兩段對該主題或技術的描述開頭，接著提供一個子頁面的清單，並對每個子頁面做簡短的描述。你可以用一些我們創建的巨集來將頁面自動插入到該清單中。</p> +<p>當你需要加入關於某個主題或主題範圍的文章時，一般可以建立一個目錄頁面，然後為這些文章分別加入子頁面。目錄頁面應當以一兩段對該主題或技術的描述開頭，接著提供一個子頁面的清單，並對每個子頁面做簡短的描述。你可以用一些我們建立的巨集來將頁面自動插入到該清單中。</p> <p>以 <a href="/zh-TW/docs/Web/JavaScript">JavaScript</a> 指南為例，它的結構如下：</p> <ul> - <li><a href="/zh-TW/docs/Web/JavaScript/Guide" title="JavaScript/Guide">JavaScript/指南</a> - 主內容表頁面</li> + <li><a href="/zh-TW/docs/Web/JavaScript/Guide" title="JavaScript/Guide">JavaScript/指南</a> ——主內容表頁面</li> <li><a href="/zh-TW/docs/Web/JavaScript/Guide/JavaScript_Overview" title="JavaScript/Guide/JavaScript_Overview">JavaScript/指南/JavaScript 概述</a></li> <li><a href="/zh-TW/docs/JavaScript/Guide/Functions" title="JavaScript/Guide/Functions">JavaScript/指南/函數</a></li> <li><a href="/zh-TW/docs/JavaScript/Guide/Details_of_the_Object_Model" title="JavaScript/Guide/Details_of_the_Object_Model">JavaScript/指南/物件模型細節</a></li> </ul> -<p>請儘量避免將你的文章放在頂層，不然會拖慢網站的下載速度，降低網站導航和搜索的效率。</p> +<p>請儘量避免將你的文章放在頂層，不然會拖慢網站的下載速度，降低網站導覽和搜索的效率。</p> + +<h3 id="General_article_content_guidelines">一般文章內容指導方針</h3> + +<p>任何文件的篇幅都應該適可而止。如果你侃侃而談或提供過多的細節，文章會變得乏味且鮮少被閱讀。文章內容涵蓋恰當的篇幅有許多好處，其中就包含：讓讀者找到他們真正想要的資訊、提供搜尋引擎足夠好的素材以便用於分析及評價文章的內容。</p> + +<p>本文只針對前者（提供讀者需要的資訊）進行說明。對於如何確保文章恰當的被搜尋引擎分類及評價，請移步到 <a href="/zh-TW/docs/MDN/Contribute/Howto/Write_for_SEO">MDN 如何針對 SEO 進行寫作</a>。</p> + +<p>寫作的目標是要讓讀者取得所有必要資訊的同時又不會陷入太多的細節中。以下是這個主題的相關建議。</p> + +<h4 id="Consider_your_audience">考量讀者想要的</h4> + +<p>要知道這些僅僅只是建議。某些建議並非適用於任何場景。時時刻刻考量讀者想要什麼。譬如，有關網路技術的進階文章就不需要講述太多有關網路基礎的觀念。</p> + +<h4 id="Provide_a_useful_summary">提供有用的概述</h4> + +<p>如果文章可能涵蓋讀者有興趣的內容，確保文章的概述——開頭的段落或是第一個標題後的段落——能夠提供讀者足夠的資訊。</p> + +<p>對於指南或是教學類型的內容，概述應該要能夠涵蓋讀者須知的主題且他們應先具備的知識；若有需要。同時也必須提到哪些已經被文件化或經討論的技術或 API 並以連結的方式提供相關的資訊，也別忘了給予文章內容中有幫助的提示。</p> + +<h5 id="Example_Too_short!">範例：過於簡短！</h5> + +<p>這個範例就過於簡短。它缺乏太多資訊了，譬如，所謂的「 stroke 」 文字到底是什麼意思、文字又會被繪製在哪裡等。</p> + +<div class="example-bad"> +<p><strong><code>CanvasRenderingContext2D.strokeText()</code></strong> draws a string.</p> +</div> + +<h5 id="Example_Too_long!">範例：過於冗長！</h5> + +<p>更新後的概述反而有過於冗長的問題。涵蓋了太多的資訊了，而且用來描述其他方法以及屬性的篇幅過於龐大。</p> + +<p>反之，概述應該著重在 <code>strokeText()</code> 方法本身，在輔以適當的參考指南作為其他細節的補充</p> + +<div class="example-bad"> +<p>When called, the Canvas 2D API method <strong><code>CanvasRenderingContext2D.strokeText()</code></strong> strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.</p> + +<p>The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.</p> + +<p>The placement of the text relative to the specified coordinates are determined by the context's <code>textAlign</code>, <code>textBaseline</code>, and <code>direction</code> properties. <code>textAlign</code> controls the placement of the string relative to the X coordinate specified; if the value is <code>"center"</code>, then the string is drawn starting at <code>x - (stringWidth / 2)</code>, placing the specified X-coordinate in the middle of the string. If the value is <code>"left"</code>, the string is drawn starting at the specified value of <code>x</code>. And if <code>textAlign</code> is <code>"right"</code>, the text is drawn such that it ends at the specified X-coordinate.</p> + +<p>(etc etc etc...)</p> + +<p>You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.</p> + +<p>You can call the <strong><code>fillText()</code></strong> method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.</p> +</div> + +<h5 id="Example_Much_better!">範例：恰到好處！</h5> + +<p>下列是一個針對 <code>strokeText()</code> 方法更好的概述。</p> + +<div class="example-good"> +<p>The {{domxref("CanvasRenderingContext2D")}} method <code><strong>strokeText()</strong></code>, part of the <a href="/zh-TW/docs/Web/API/Canvas_API">Canvas 2D API</a>, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.</p> + +<p>For more details and further examples, see {{SectionOnPage("/zh-TW/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, <a href="/zh-TW/docs/Web/API/Canvas_API/Tutorial/Drawing_text">Drawing text</a>.</p> +</div> + +<h4 id="Include_all_relevant_examples">涵蓋所有相關的範例</h4> + +<p>使用範例來進一步闡明每一個使用到的參數以及任何可能出現的少數邊際案例是非常重要的。使用範例來展示常見問題以及可能引發問題的情況及他們的解決方式。</p> + +<p>一般而言會期待多數的頁面都可以包含一到多個範例，最好有超過一個範例。</p> + +<p>每一個範例須有前導的文字用於說明該範例所為何事以及讀者在閱讀及試驗該範例前的須知事項。</p> + +<h5 id="Code_Examples">程式碼範例</h5> + +<p>每一段程式碼都應具有其如何運作的說明。大型段落的程式碼應切割成更小的部分以便於進行個別的描述。</p> + +<p>每一段程式碼之後的文字應解釋所有相關資訊並控制好描述細節的程度：</p> + +<ul> + <li>如果程式碼相對簡單且並直接使用到任何已經建檔的 API ，那簡略的對其說明它是什麼以及為何在此即可。</li> + <li>如果程式碼過於艱深、使用到已經建檔的 API 、有技術上的創新，則需要提供更細緻的說明。</li> +</ul> + +<p>當加入<a href="/zh-TW/docs/MDN/Structures/Live_samples">實際範例</a>時，所有位於範例區域內的 {{HTMLElement("pre")}} 區塊會在執行範例前串聯起來，這便於讓你把 HTML 、 CSS 、 JavaScript 分開來處理，並讓它們擁有自己的描述、標題等。這使得程式碼的建檔變得更強大且更彈性。</p> + +<h4 id="Overly-short_articles_are_hard_to_find">過於簡短的文章很難被找到</h4> + +<p>如果文章的篇幅過於簡短，那可能搜尋引擎無法對其合理的索引（甚至根本無法索引）。根據經驗，文章的本體應最少有 250-300 字的篇幅。不用特別對文章內容充數，把這個原則當作最低的目標要求就足夠了。</p> -<h3 id="Sections.2C_Paragraphs.2C_Newlines" name="Sections.2C_Paragraphs.2C_Newlines">章節、段落與換行</h3> +<h3 id="Headings">標題</h3> -<p>請按照遞增順序使用標題級別：首先是 {{HTMLElement("h2")}}，其次是{{HTMLElement("h3")}}，接著是 {{HTMLElement("h4")}}，不要跳過級別。H2 是允許的最高級別，因為 H1 要留給頁面標題。若你需要超過四、五個級別的標題，請考慮將該文章拆分為幾篇更小的文章並創建登陸頁面，然後用巨集 {{TemplateLink("Next")}}、{{TemplateLink("Previous")}} 和 {{TemplateLink("PreviousNext")}} 將他們連結起來。</p> +<p>當開啟新的章節段落務必要加上標題。標題的層級以遞減的方式排序： {{HTMLElement("h2")}} 再來是 {{HTMLElement("h3")}} 再來是 {{HTMLElement("h4")}} ，不要跳過任何一個層級。</p> -<p>在你鍵盤上的 Enter (或 return) 鍵會開一個新的段落。如果希望插入新的一行中間沒有空白，就同時按下 Shift 和 Enter 鍵。</p> +<p>因為 H1 已經被保留作為頁面的標題使用，因此 H2 是章節段落可使用的最高層級標題。如果使用到超過三或四個等級的標題，請考慮把文章重新劃分成數個篇幅更短的文章並提供一個目錄頁面。</p> -<p>Don't create single subsections -- you don't subdivide a topic into one. It's either two subheadings or more or none at all. </p> +<h4 id="Heading_dos_and_donts">標題的為與不為</h4> -<p>Don't have bumping heads, which are headings followed immediately by headings. Aside from looking horrible, it's helpful to readers if every heading has at least a brief intro after it to introduce the subsections beneath.</p> +<ul> + <li><strong>不要建立單獨的子章節。</strong>不要把一個主題拆成單獨的子主題。請用兩個或以上的子標題或乾脆都不要有。</li> + <li><strong>不要對標題使用樣式及 classes 。</strong>這當然也包含了不要用 {{HTMLElement("code")}} 元素。因此請不要把標題寫成「使用 <code>SuperAmazingThing</code> 介面」，而是寫成「使用 SuperAmazingThing 介面」這樣就好。</li> + <li><strong>避免在標題內使用巨集</strong>（除了某些特別用於標題的巨集）。</li> + <li><strong>不要建立「頭碰頭」標題。</strong>一個標題緊接著一個子標題中間沒有任何的內容看起來會很突兀也會讓讀者因為看不到外側章節開頭有任何的說明而感到困惑。</li> + + <h3 id="Lists">清單</h3> -<h3 id="Text_Formatting" name="Text_Formatting">文本格式與樣式</h3> +<p>清單應在所有頁面中具備一致的格式及結構。個別的清單項目應使用適合的標點符號，無論使用何種清單格式。然而，根據你所建立的清單類型，你可能需要根據下列的說明進行調整。</p> -<p>請使用“樣式”下拉清單來為選中的內容應用預定義的樣式。</p> +<h4 id="Bulleted_lists">無序清單</h4> -<div class="note"><strong>注意： </strong>“注意” 樣式用於重要的注意事項，就像這樣。</div> +<p>無序清單應用於群聚相關的簡扼資訊。每個項目應循著類似的句子結構。無序清單中的子句及句子應包含標準的標點符號。無序清單中的每個句子的結尾都應出現句號，即便是項目的最後一句，就好比段落一樣。</p> -<div class="warning"><strong>警告：</strong>同樣，“警告”樣式用於創建警告框，就像這樣。</div> +<p>一個正確結構的無序清單範例：</p> -<p>除非有明確指令，否則<strong>請勿</strong>使用 HTML 的 <code>style</code> 屬性來手動更改內容的風格。如果你無法使用預先定義的 class 來達成目的，就將他丟到 <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">Matrix</a> 以尋求協助。</p> +<div class="example-good"> +<p>在此範例中，必須包含：</p> -<h3 id="範例程式的樣式與格式">範例程式的樣式與格式</h3> +<ul> + <li>一個條件，以及一些簡短的說明。</li> + <li>一個類似的條件，以及一些簡短的說明。</li> + <li>再一個條件，以及更深入的說明。</li> +</ul> +</div> -<h4 id="縮排與換行">縮排與換行</h4> +<p>注意看，相同的句子結構在項目重複出現。在此範例中，每個項目闡述一個條件並在逗號後緊隨著簡短的說明，而每一個項目都以句號作為結尾。</p> -<p>所有的程式碼範例，一個縮排使用兩個空白鍵。程式碼縮排要整潔、左大括號（ { ）和開展一段區域的宣稱同行。例如：</p> +<h4 id="Numbered_lists">有序清單</h4> -<pre class="brush: js notranslate">if (condition) { - /* handle the condition */ +<p>有序清單主要用於列舉一段操作指南的步驟。因為操作指南可能很複雜，清楚地說明是首要任務，特別是每個項目的文字長度可能都不短。如同無序清單，請使用標準的標點符號。</p> + +<p>一個正確結構的有序清單：</p> + +<div class="example-good"> +<p>想要正確地結構有序清單，必須做到：</p> + +<ol> + <li>以標題或簡短的段落起頭，接著進入操作指南的部分。在開始進行操作指南前提供使用者相關的脈絡是非常重要的。</li> + <li>開始建立操作指南，每一個步驟的項目都應有它自己的序號。操作指南可能會延伸出不少東西，所以重點把它寫得清楚且使用正確的標點符號。</li> + <li>在完成操作指南後，接續著有序清單給予結語或說明有哪些在完成操作指南後應期待出現的結果。</li> +</ol> + +<p>這是最後結語的範例。上述就是簡短的有序清單，說明如何如何建立一個具備正確格式的有序清單操作指南。</p> +</div> + +<p>注意看，有序清單的每個項目讀起來都像是一個簡短的段落。那是因為有序清單通常是用於說明操作指南的目的，或是帶領讀者走過一步步的程序，也請確保每一個項目都著重在：一個序號項目說明一個步驟。</p> + +<h3 id="Text_formatting_and_styles">文字的格式及樣式</h3> + +<p>使用<strong>「格式化樣式］</strong>的下拉清單來對選取內容套用預定義的樣式。</p> + +<div class="note notecard"><strong>「備註區塊」</strong>樣式是用於標示重要的備註，就好比這樣。</div> + +<div class="warning">類似地，<strong>「警告區塊」</strong>樣式用於建立警告區塊，就好比這樣。</div> + +<p>除非有特別地指示，否則<em>不要</em>使用 HTML <code>style</code> 屬性來手動套用樣式。如果碰到無法使用預定義地 class ，請在 <a href="https://discourse.mozilla.org/c/mdn">MDN 討論論壇</a>尋求協助。</p> + +<h3 id="Code_sample_style_and_formatting">程式碼範例的樣式與格式</h3> + +<div class="note notecard"> +<p><strong>注意</strong>：此章節說明透過樣式／格式來影響程式碼如何在 MDN 文章中顯示。如果你需要撰寫程式碼例子的實際指導方針，請參閱<a href="/zh-TW/docs/MDN/Guidelines/Code_guidelines">程式碼範例指導方針</a></p> +</div> + +<h4 id="Tabs_and_line_breaks">Tabs 以及換行</h4> + +<p>在所有程式碼範例中使用兩個半形空格作為 tab 。把左側括號「 <code>{</code> 」字元放在陳述式的同一行作為開啟區塊的方式進行縮排會讓程式碼更清楚。譬如：</p> + +<pre class="brush: js">if (條件) { + /* 處理成立的條件 */ } else { - /* handle the "else" case */ + /* 處理「 else 」的情況 */ } </pre> -<p>一行不能長到要橫向滾動才能閱讀，應當於自然斷點處換行。例如：</p> +<p>不應水平延伸該行的內容使得其太長以至於在閱讀時需要水平方向捲動。反之，應以自然的方式進行斷行。一些範例：</p> -<pre class="brush: js notranslate">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION +<pre class="brush: js">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION || class.YET_ANOTHER_CONDITION ) { - /* something */ + /* 某些內容 */ } var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"] .createInstance(Components.interfaces.nsIToolkitProfileService); </pre> -<h4 id="行內程式碼樣式">行內程式碼樣式</h4> - -<p>按下 Code 按鈕（標示為一對尖括號 <> ）套用到函式、變數、以及方法名稱的行內程式碼（這用到了 {{HTMLElement("code")}} 元素），例如 <code class="js plain">frenchText()</code> 函式。</p> - -<p>方法名稱要跟著一對小括號：<code>doSomethingUseful()</code>，這能讓該方法與其他程式碼術語做出辨別。</p> +<h4 id="Inline_code_formatting">行內程式碼的格式</h4> -<h4 id="語法高亮">語法高亮</h4> +<p>使用 {{HTMLElement("code")}} 來標示函數名稱、變數名稱、方法名稱。譬如：「 <code>frenchText()</code> 函數」。</p> -<p><img alt='Screenshot of the "syntax highlighting" menu.' src="https://mdn.mozillademos.org/files/7857/syntax-highlighting-menu.png" style="border-style: solid; border-width: 1px; float: right; height: 315px; margin: 2px 4px; width: 183px;">Entire lines (or multiple lines) of code should be formatted using syntax highlighting rather than the {{HTMLElement("code")}} element. Click the "pre" button in the toolbar to create the preformatted content box in which you'll then write your code. Then, with the text entry cursor inside the code box, select the appropriate language from the language list button to the right of the "pre" button, as seen in the screenshot to the right. The following example shows text with JavaScript formatting:</p> +<p><strong>方法名稱必須緊隨一對小括號。</strong>譬如， <code>doSomethingUseful()</code> 。小括號有助於區別方法及其他程式碼術語。</p> -<div class="line number2 index1 alt1"> -<pre class="brush: js notranslate">for (var i = 0, j = 9; i <= 9; i++, j--) - document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);</pre> -</div> - -<p>If no appropriate transformation is available, use the <code>pre</code> tag without specifying a language ("No Highlight" in the language menu).</p> +<h4 id="Syntax_highlighting">語法上色</h4> -<pre class="notranslate">x = 42;</pre> +<p>一行或多行的程式碼應使用<a href="/zh-TW/docs/MDN/Guidelines/CSS_style_guide#code_syntax_highlighting">語法上色</a>的方式格式化而不是用 {{HTMLElement("code")}} 元素。</p> -<h4 id="HTML_元素風格參考">HTML 元素風格參考</h4> +<h4 id="Styling_mentions_of_HTML_elements">對提及的 HTML 元素使用不同的樣式</h4> -<p>There are various specific rules to follow when writing about HTML elements, in order to consistently describe the various components of elements, and to ensure that they're properly linked to detailed documentation.</p> +<p>HTML 元素在撰寫時有它們特殊的規則。這些規則可以對元素及其元件提供一致的描述。同時也可以保證連結到正確的詳細文件。</p> <dl> - <dt>元素名</dt> - <dd>請使用 {{TemplateLink("HTMLElement")}} macro，它可以導向該元素的網頁連結。例如說，寫 \{{HTMLElement("title")}} 就會產生 {{HTMLElement("title")}}。如果不想要有連結，<strong>使用尖括號把名字包起來</strong> ，然後套用 Code (inline) 樣式（例如 <code><title></code>）。</dd> - <dt>屬性名</dt> - <dd>請使用 <strong>粗體</strong></dd> + <dt>元素名稱</dt> + <dd>使用 {{TemplateLink("HTMLElement")}} 巨集，這會建立連向該元素頁面的連結。譬如，撰寫 \{{HTMLElement("title")}} 會產生 "{{HTMLElement("title")}}" 。如果不想要建立連結，<strong>就把元素名稱置於角括號中</strong>並使用「行內程式碼樣式」（舉例， <code><title></code> ）。</dd> + <dt>屬性名稱</dt> + <dd>使用「行內程式碼」樣式讓它以<code>程式碼字型</code>顯示。此外，當屬性在解釋其為何的相關說明或其在文章中首次出現時要把它們加上<strong><em>粗體</em></strong>。</dd> <dt>屬性定義</dt> - <dd>針對 definition term，請使用 {{TemplateLink("htmlattrdef")}} macro（例如 <span class="nowiki">\{{htmlattrdef("type")}}</span>）so that it can be linked to from other pages, then use the {{TemplateLink("htmlattrxref")}} macro (e.g., <span class="nowiki">\{{htmlattrxref("attr","element")}}</span>) to reference attribute definitions.</dd> + <dd>對定義的術語使用 {{TemplateLink("htmlattrdef")}} 巨集（舉例， \{{htmlattrdef("type")}} ） ，以便它們可以用 {{TemplateLink("htmlattrxref")}} 巨集（舉例， \{{htmlattrxref("type","element")}} ）的方式被其他頁面連結來參照屬性定義。</dd> <dt>屬性值</dt> - <dd>Use "Code (inline)" style, and do not use quotation marks around strings, unless needed by the syntax of a code sample. E.g.: When the <strong>type</strong> attribute of an <code><input></code> element is set to <code>email</code> or <code>tel</code> ...</dd> - <dt>Labeling attributes</dt> - <dd>Use labels like {{HTMLVersionInline(5)}} thoughtfully. For example, use them next to the bold attribute name but not for every occurrence in your body text.</dd> + <dd>使用「行內程式碼」樣式來套用 <code><code></code> 屬性值，而且不要使用引述標示環繞字串值，除非程式碼範例有此需要。</dd> + <dd><strong>譬如：</strong>「當 <code><input></code> 的 <code>type</code> 屬性被設定為 <code>email</code> 或 <code>tel</code> ……」</dd> </dl> -<h3 id="Latin_abbreviations" name="Latin_abbreviations">拉丁語縮寫</h3> +<h3 id="Latin_abbreviations">拉丁文縮寫</h3> -<h4 id="In_notes_and_parentheses" name="In_notes_and_parentheses">在注記與括弧中</h4> +<h4 id="In_notes_and_parentheses">在備註與括弧中</h4> <ul> - <li>常見的拉丁縮寫（etc.、i.e.、e.g.）可以在括號表達、或注記內使用。這些縮寫都要用半形句點（.）。 + <li>常見的拉丁縮寫（ etc. 、 i.e. 、 e.g. ）可以在括號表達、或備註內使用。這些縮寫都要用半形句號（.）並緊隨著逗號或其他恰當的標點符號。 <ul> - <li><span class="correct"><strong>正確</strong></span>：Web browsers (e.g. Firefox) can be used ...</li> - <li><span class="incorrect"><strong>錯誤</strong></span>：Web browsers e.g. Firefox can be used ...</li> - <li><span class="incorrect"><strong>錯誤</strong></span>：Web browsers, e.g. Firefox, can be used ...</li> - <li><span class="incorrect"><strong>錯誤</strong></span>：Web browsers, (eg: Firefox) can be used ...</li> + <li><span class="correct"><strong>正確</strong></span>：Web browsers (e.g., Firefox) can be used ...</li> + <li><span class="incorrect"><strong>不正確</strong></span>：Web browsers e.g. Firefox can be used ...</li> + <li><span class="incorrect"><strong>不正確</strong></span>：Web browsers, e.g. Firefox, can be used ...</li> + <li><span class="incorrect"><strong>不正確</strong></span>：Web browsers, (eg: Firefox) can be used ...</li> </ul> </li> </ul> -<h4 id="In_running_text" name="In_running_text">在行文中</h4> +<h4 id="In_running_text">在行文中</h4> <ul> - <li>在普通行文中（也就是注記與括號以外的文字）請使用與該縮寫相等的文字表達。 + <li>在普通行文中（也就是備註與括號以外的文字）請使用與該縮寫相等的文字表達。 <ul> <li><span class="correct"><strong>正確</strong></span>: ... web browsers, and so on.</li> - <li><span class="incorrect"><strong>錯誤</strong></span>: ... web browsers, etc.</li> + <li><span class="incorrect"><strong>不正確</strong></span>: ... web browsers, etc.</li> <li><span class="correct"><strong>正確</strong></span>: Web browsers such as Firefox can be used ...</li> - <li><span class="incorrect"><strong>錯誤</strong></span>: Web browsers e.g. Firefox can be used ...</li> + <li><span class="incorrect"><strong>不正確</strong></span>: Web browsers e.g. Firefox can be used ...</li> </ul> </li> </ul> -<h4 id="Meanings_and_English_equivalents_of_Latin_abbreviations" name="Meanings_and_English_equivalents_of_Latin_abbreviations">與拉丁文意義相同的中/英文</h4> +<h4 id="Meanings_and_English_equivalents_of_Latin_abbreviations">與拉丁文意義相同的中／英文（譯註：中文解釋取自劍橋大學線上辭典）</h4> -<table class="fullwidth-table"> - <tbody> +<table class="standard-table"> + <thead> <tr> - <th>縮寫</th> - <th>拉丁文</th> - <th>英文</th> - <th>中文</th> + <th scope="col">縮寫</th> + <th scope="col">拉丁文</th> + <th scope="col">英文</th> + <th scope="col">中文</th> </tr> + </thead> + <tbody> <tr> <td>cf.</td> <td><em>confer</em></td> <td>compare</td> - <td>對比，比較</td> + <td>參照、比較</td> </tr> <tr> <td>e.g.</td> @@ -187,381 +322,299 @@ var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-ser <td>et al.</td> <td><em>et alii</em></td> <td>and others</td> - <td>什麼的，以及其他</td> + <td>以及其他人、等人、等等</td> </tr> <tr> <td>etc.</td> <td><em>et cetera</em></td> <td>and so forth, and so on</td> - <td>等等，諸如此類</td> + <td>以及諸如此類、以及其他、等等</td> </tr> <tr> <td>i.e.</td> <td><em>id est</em></td> <td>that is, in other words</td> - <td>即，換言之</td> + <td>也就是、即</td> </tr> <tr> <td>N.B.</td> <td><em>nota bene</em></td> <td>note well</td> - <td>注意</td> + <td>注意、留心（用於提醒讀者留意重要資訊）</td> </tr> <tr> <td>P.S.</td> <td><em>post scriptum</em></td> <td>postscript</td> - <td>注，附言</td> + <td>附言、補充說明</td> </tr> </tbody> </table> -<div class="note"> -<p><strong>注意：</strong>永遠考慮使用拉丁語縮寫的收益。有些縮寫很少用到、多數讀者並不明白其意義，或常常與其他縮寫搞混。如果你要用，也請確定<strong>你</strong>用對了，像常見的錯誤是把「e.g.」與「i.e.」搞混。</p> -</div> +<div class="note notecard"> +<p><strong>備註</strong>：總是想清楚使用拉丁文縮寫是否真的有效益。某些縮寫甚少使用，讀者根本不明白其意義，而某些甚至會跟其他縮寫產生混淆。</p> -<h3 id="Acronyms_and_abbreviations" name="Acronyms_and_abbreviations">縮寫與簡稱</h3> - -<h4 id="Capitalization_and_periods" name="Capitalization_and_periods">大小寫與點號</h4> - -<p>所有的縮寫與簡稱都要大寫、並把半形句點刪除，就算是「US」與「UN」之類的組織也一樣。</p> +<p>若你選擇使用這些縮寫，請確保<em>你</em>能夠正確地使用它們。例如，常見的錯誤是把「 e.g. 」和「 i.e. 」搞混。</p> +</div> -<ul> - <li><span class="correct"><strong>正確</strong></span>：XUL</li> - <li><span class="incorrect"><strong>錯誤</strong></span>：X.U.L.</li> - <li><span class="incorrect"><strong>錯誤</strong></span>：Xul</li> -</ul> +<h3 id="Acronyms_and_abbreviations">簡稱與縮寫</h3> -<h4 id="Expansion" name="Expansion">全名</h4> +<h4 id="Capitalization_and_periods">大小寫與句號</h4> -<p>On the first mention of a term on a page, expand acronyms likely to be unfamiliar to users. When in doubt, expand it, or, better, link it to the article or <a href="/en-US/docs/Glossary">glossary</a> entry describing the technology.</p> +<p>所有的縮寫與簡稱都要大寫、並把半形句號刪除，就算是「 US 」與「 UN 」之類的組織也一樣。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: "XUL (XML User Interface Language) is Mozilla's XML-based language..."</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: "XUL is Mozilla's XML-based language..."</li> + <li><span class="correct"><strong>正確</strong></span>： XUL</li> + <li><span class="incorrect"><strong>不正確</strong></span>： X.U.L. ； Xul</li> </ul> -<h4 id="Plurals_of_acronyms_and_abbreviations" name="Plurals_of_acronyms_and_abbreviations">縮寫與簡寫的複數形式</h4> +<h4 id="Expansion">Expansion</h4> -<p>For plurals of acronyms or abbreviations, add <em>s</em>. Don't use an apostrophe. Ever. Please.</p> +<p>當在頁面中首次提及某個術語時，最好把那些使用者不熟悉的縮寫展開。如果不確定是否有必要，那就展開吧——如果可以連結到它的文章或是<a href="/zh-TW/docs/Glossary">術語表</a>中的條目來說明此技術更好。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: CD-ROMs</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: CD-ROM's</li> + <li><span class="correct"><strong>正確</strong></span>:「XUL （ XML User Interface Language ）是 Mozilla 的類 XML 語言……」</li> + <li><span class="incorrect"><strong>不正確</strong></span>:「XUL 是 Mozilla 的類 XML 語言……」</li> </ul> -<h3 id="Contractions" name="Contractions">大小寫</h3> - -<p>Use standard English capitalization rules in body text, and capitalize "World Wide Web" and "Web".</p> - -<p>Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "Enter" not "ENTER."</p> - -<h3 id="Contractions" name="Contractions">縮寫</h3> - -<p>Use contractions (e.g. "don't", "can't", "shouldn't") if you prefer. We're not that formal!</p> +<h4 id="Plurals_of_acronyms_and_abbreviations">簡寫與縮寫的複數形式</h4> -<h3 id="Pluralization" name="Pluralization">複數形式</h3> +<p>簡寫與縮寫的複數形式要加上 <em>s</em> 。（譯註：中文沒有複數概念所以不需要）</p> -<p>Use English-style plurals, not the Latin- or Greek-influenced forms.</p> +<p>不要加上撇號。真的不要。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: syllabuses, octopuses</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: syllabi, octopi</li> + <li><span class="correct"><strong>正確</strong></span>： CD-ROMs</li> + <li><span class="incorrect"><strong>不正確</strong></span>： CD-ROM's</li> </ul> -<h3 id="Hyphenation" name="Hyphenation">連字號</h3> +<h4 id="Versus_vs._and_v.">「 Versus 」、「 vs. 」、「 v. 」</h4> -<p>Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.</p> +<p>偏好使用縮短的「 vs. 」。</p> <ul> - <li><font color="green"><strong>Correct</strong></font>: email, re-elect, co-op</li> - <li><font color="red"><strong>Incorrect</strong></font>: e-mail, reelect, coop</li> + <li><span class="correct"><strong>正確</strong></span>： this vs. that</li> + <li><span class="incorrect"><strong>不正確</strong></span>： this v. that</li> + <li><span class="incorrect"><strong>不正確</strong></span>： this versus that</li> </ul> -<h3 id="性別中立的用語">性別中立的用語</h3> - -<p>It is a good idea to use gender-neutral language in any kind of writing where gender is irrelevant to the subject matter, to make the text as inclusive as possible. So for example, if you are talking about the actions of a specific man, usage of he/his would be fine, but if the subject is a person of either gender, he/his isn't really appropriate.<br> - <br> - Let's take the following example:</p> - -<blockquote> -<p>A confirmation dialog appears, asking the user if he allows the web page to make use of his web cam.</p> -</blockquote> - -<blockquote> -<p>A confirmation dialog appears, asking the user if she allows the web page to make use of her web cam.</p> -</blockquote> +<h3 id="Capitalization">大小寫</h3> -<p>Both versions in this case are gender-specific. This could be fixed by using gender-neutral pronouns:</p> +<p>在主體文字中使用標準的英文大寫規則以及大寫化「 World Wide Web 」。用小寫的「 web 」（單獨使用或作為修飾）以及「 internet 」是可以接受的。</p> -<blockquote> -<p>A confirmation dialog appears, asking the user if they allow the web page to make use of their web cam.</p> -</blockquote> +<div class="notecard note"> +<p><strong>備註</strong>：這項指導方針跟之前的版本有所不同，所以你可能會發現在 MDN 中有多處出現「 Web ］跟「 Internet 」。</p> -<div class="note"> -<p><strong>Note:</strong> MDN allows the use of this very common syntax (which is controversial among usage authorities), in order to make up for the lack of a neutral gender in English. The use of the third-person plural as a neutral gender pronoun (that is, using "they," them", "their," and "theirs") is an accepted practice, commonly known as "<a href="http://en.wikipedia.org/wiki/Singular_they">singular 'they.'</a>"</p> +<p>當你在編輯其他變更的時候你可以順手把它也改了，但不需要特別為了改變這些大寫而編輯文章。</p> </div> -<p>You can use both genders:</p> +<p>鍵盤按鍵應使用句子式的大寫而不是全大寫化。譬如，「 <kbd>Enter</kbd> 」而不是「 <kbd>ENTER</kbd> 」。唯一例外是你可以用「 <kbd>ESC</kbd> 」來作為「 <kbd>Escape</kbd> 」的縮寫。</p> -<blockquote> -<p>A confirmation dialog appears, asking the user if he or she allows the web page to make use of his/her web cam.</p> -</blockquote> - -<p>making the users plural:</p> - -<blockquote> -<p>A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.</p> -</blockquote> - -<p>The best solution, of course, is to rewrite and eliminate the pronouns completely:</p> - -<blockquote> -<p>A confirmation dialog appears, requesting the user's permission for web cam access.</p> -</blockquote> - -<blockquote> -<p>A confirmation dialog box appears, which asks the user for permission to use the web cam.</p> -</blockquote> - -<p>The last way of dealing with the problem is arguably better, as it is not only grammatically more correct but removes some of the complexity associated with dealing with genders across different languages that may have wildly varying gender rules. This can make translation easier, both for readers reading English, then translating it into their own language as they read, and for localizers translating articles into their own language.</p> - -<h3 id="Numbers_and_numerals" name="Numbers_and_numerals">數字與數詞</h3> - -<h4 id="日期">日期</h4> - -<p>For dates (not including dates in code samples) use the format "January 1, 1990".</p> +<p>特定的詞彙都應首字大寫（譬如包含大寫字母的商標）或以人物姓名作為詞彙的術語（除非出現在程式碼中且程式碼的語法要求以小寫書寫）。一些範例：</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: February 24, 2006</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: February 24th, 2006; 24 February, 2006; 24/02/2006</li> + <li>Boolean （源自英國數學家和邏輯學家 {{interwiki("wikipedia", "George Boole")}} ）</li> + <li>JavaScript （甲骨文公司的商標，總是作為商標來書寫）</li> + <li>Python 、 TypeScript 、 Django 、 其他程式語言和框架名稱</li> </ul> -<p>Alternately, you can use the YYYY/MM/DD format.</p> +<h3 id="Contractions">縮略形式</h3> -<ul> - <li><span class="correct"><strong>Correct</strong></span>: 2006/02/24</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: 02/24/2006; 24/02/2006; 02/24/06</li> -</ul> +<p>我們的書寫風格比較隨意，所以，如果喜歡的話就放心的用縮略形式吧（例如，「 don't 」、「 can't 」、「 shouldn't 」）。</p> -<h4 id="Decades" name="Decades">年代</h4> +<h3 id="Pluralization">複數形式</h3> -<p>For decades, use the format "1990s". Don't use an apostrophe.</p> +<p>使用英文式的複數，而非拉丁文或希臘文的格式。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: 1990s</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: 1990's</li> + <li><span class="correct"><strong>正確</strong></span>： syllabuses 、 octopuses</li> + <li><span class="incorrect"><strong>不正確</strong></span>： syllabi 、 octopi</li> </ul> -<h4 id="Plurals_of_numerals" name="Plurals_of_numerals">數詞的複數</h4> +<h3 id="Hyphenation">連字號</h3> -<p>For plurals of numerals add <em>"s"</em>. Don't use an apostrophe.</p> +<p>當前綴的最後一個字母是元音且與字根的第一個字母相同時，應使用連字號串聯。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: 486s</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: 486's</li> + <li><span class="correct"><strong>正確</strong></span>： email 、 re-elect 、 co-op</li> + <li><span class="incorrect"><strong>不正確</strong></span>： e-mail 、 reelect 、 coop</li> </ul> -<h4 id="Commas" name="Commas">逗號</h4> +<h3 id="Gender-neutral_language">性別中立語言</h3> -<p>In running text, use commas only in five-digit and larger numbers.</p> +<p>為了讓文字更有包容性，最好用性別中立的語言來進行寫作讓主題與性別脫鉤。例如，如果敘述某個跟男性有關的動作使用「 he 」或「 his 」是妥當的；但若主題涉及不同性別則使用「 he 」或「 his 」就不恰當。<br> + <br> + 來看看下列的範例（譯註：中文的「他」等代名詞無關性別，本身既是中性的，無須多此一舉，下列範例保留原文）：</p> -<ul> - <li><span class="correct"><strong>Correct</strong></span>: 4000; 54,000</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: 4,000; 54000</li> -</ul> +<p><em>A confirmation dialog appears, asking the user if he allows the Web page to make use of his Web cam.</em></p> -<h3 id="Punctuation" name="Punctuation">標點符號</h3> +<p><em>A confirmation dialog appears, asking the user if she allows the Web page to make use of her Web cam.</em></p> -<h4 id="Serial_comma" name="Serial_comma">連續逗號</h4> +<p>上述兩個版本皆有性別取向，可以以性別中立的代名詞取而代之：</p> -<p><strong>Use the serial comma</strong>. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.</p> +<p><em>A confirmation dialog appears, asking the user if they allow the Web page to make use of their Web cam.</em></p> -<ul> - <li><span class="correct"><strong>Correct</strong></span>: I will travel on trains, planes, and automobiles.</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: I will travel on trains, planes and automobiles.</li> -</ul> +<div class="note notecard"> +<p><strong>備註：</strong>： MDN 允許使用這種非常常見的語法（在使用正當性上存在爭議）來彌補英文中缺乏性別中性的詞彙。</p> -<div class="note"> -<p><strong>Note:</strong> This is in contrast to the <a href="http://www.mozilla.org/en-US/styleguide/" title="http://www.mozilla.org/en-US/styleguide/">One Mozilla style guide</a>, which specifies that the serial comma is not to be used. MDN is an exception to this rule.</p> +<p>使用複數第三人稱做為性別中立的代名詞是被接受的慣例，常被當作「<a href="https://en.wikipedia.org/wiki/Singular_they">單數的『他們』</a>」。</p> </div> -<h3 id="Spelling" name="Spelling">拼字</h3> +<p>複數化使用者（譯註：中文並無複數概念，下列範例保留原文）</p> -<p>For words with variant spellings, always use the first entry at <a href="http://www.answers.com/library/Dictionary">Answers.com</a>. Do not use variant spellings.</p> +<p><em>A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.</em></p> -<ul> - <li><span class="correct"><strong>Correct</strong></span>: localize, honor</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: localise, honour</li> -</ul> +<p>The best solution, of course, is to rewrite and eliminate the pronouns:</p> -<h3 id="術語">術語</h3> +<p><em>A confirmation dialog appears, requesting the user's permission for web cam access.</em></p> -<h4 id="棄用_vs._過時">棄用 vs. 過時</h4> +<p><em>A confirmation dialog box appears, which asks the user for permission to use the web cam.</em></p> -<p>It's important to be clear on the difference between the terms <strong>obsolete</strong> and <strong>deprecated</strong>.</p> +<p>最後一個例子可以說更妥善的處理了這個問題。不只在文法上更正確，還消除了某些跨語言時會碰到不同性別規則的難題。這個解法使得讀者和譯者在面對翻譯時更加輕鬆。</p> -<dl> - <dt>棄用：</dt> - <dd>On MDN, the term <strong>obsolete</strong> marks an API or technology that is not only no longer recommended, but also no longer implemented in the browser. For Mozilla-specific technologies, the API is no longer implemented in Mozilla code; for Web standard technology, the API or feature is no longer supported by current, commonly-used browsers.</dd> - <dt>過時：</dt> - <dd>On MDN, the term <strong>deprecated</strong> marks an API or technology that is no longer recommended, but is still implemented and may still work. These technologies will in theory eventually become <em>obsolete</em> and be removed, so you should stop using them. For Mozilla-specific technologies, the API is still supported in Mozilla code; for Web standard technology, the API or feature has been removed or replaced in a recent version of the defining standard.</dd> -</dl> +<h3 id="Numbers_and_numerals">數字和數字符號</h3> -<h4 id="HTML_元素">HTML 元素</h4> +<p>譯註：下列格式及範例仍採用英文格式作為忠實傳達原文說明如何書寫英文的相關知識。</p> -<p>Use "elements" to refer to HTML and XML elements, rather than "tags". In addition, they should almost always be wrapped in "<>", and should be in the {{HTMLElement("code")}} style. Also, at least the first time you reference a given element in a section should use the {{TemplateLink("HTMLElement")}} macro, to create a link to the documentation for the element (unless you're writing within that element's reference document page).</p> +<h4 id="Dates">日期</h4> + +<p>日期格式使用「 January 1, 1990 」（不包含程式碼範例中的日期）。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: the {{HTMLElement("span")}} element</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: the span tag</li> + <li><span class="correct"><strong>正確</strong></span>： February 24, 2006</li> + <li><span class="incorrect"><strong>不正確</strong></span>： February 24th, 2006; 24 February, 2006; 24/02/2006</li> </ul> -<h4 id="使用者介面動作">使用者介面動作</h4> - -<p>In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label and type.</p> +<p>作為替代，也可以使用 YYYY/MM/DD 格式。</p> <ul> - <li><span class="correct"><strong>Correct</strong></span>: Click the Edit button.</li> - <li><span class="incorrect"><strong>Incorrect</strong></span>: Click Edit.</li> + <li><span class="correct"><strong>正確</strong></span>： 2006/02/24</li> + <li><span class="incorrect"><strong>不正確</strong></span>： 02/24/2006; 24/02/2006; 02/24/06</li> </ul> -<h3 id="語態">語態</h3> +<h4 id="Decades">年代</h4> -<p>While the active voice is generally preferred, the passive voice is also acceptable, given the informal feel of our content. Try to be consistent, though.</p> +<p>年代使用「 1990s 」。不要用撇號。</p> -<h2 id="Wiki_語法與用處">Wiki 語法與用處</h2> - -<h3 id="外部連結">外部連結</h3> - -<p>To automatically create a link to a Bugzilla bug, use this template:</p> - -<pre class="notranslate">\{{Bug(322603)}} -</pre> +<ul> + <li><span class="correct"><strong>正確</strong></span>： 1990s</li> + <li><span class="incorrect"><strong>不正確</strong></span>： 1990's</li> +</ul> -<p>This results in:</p> +<h4 id="Plurals_of_numerals">數字的複數</h4> -<p>{{Bug(322603)}}</p> +<p>複數數字加上「 s 」不要用撇號。</p> -<p>For WebKit bugs, you can use this template:</p> +<ul> + <li><span class="correct"><strong>正確</strong></span>： 486s</li> + <li><span class="incorrect"><strong>不正確</strong></span>： 486's</li> +</ul> -<pre class="notranslate">\{{Webkitbug("322603")}} -</pre> +<h4 id="Commas">逗號</h4> -<p>This results in:</p> +<p>在行文中使用逗號的條件是五個字元或以上的大數。</p> -<p>{{Webkitbug("322603")}}</p> +<ul> + <li><span class="correct"><strong>正確</strong></span>： 4000; 54,000</li> + <li><span class="incorrect"><strong>不正確</strong></span>： 4,000; 54000</li> +</ul> -<h3 id="頁面標籤">頁面標籤</h3> +<h3 id="Punctuation">標點符號</h3> -<p>Tags provide meta information about a page and/or indicate that a page has specific improvements needed to its content. Every page in the wiki should have tags. You can find details on tagging in our <a href="/en-US/docs/MDN/Contribute/Howto/Tag">How to properly tag pages</a> guide.</p> +<p>譯註：下列格式及範例仍採用英文格式作為忠實傳達原文說明如何書寫英文的相關知識。</p> -<p>The tagging interface lives at the bottom of a page while you're in edit mode, and looks something like this:</p> +<h4 id="Serial_comma">連續逗號</h4> -<p><img alt="Screenshot of the UX for adding and removing tags on MDN" src="https://mdn.mozillademos.org/files/7859/tag-interface.png" style="border-style: solid; border-width: 1px; height: 167px; width: 863px;"></p> +<p><strong>須使用連續逗號（譯註：中文為頓號）</strong>。連續逗號（ serial/Oxford comma ）是指在連續出現三個或以上的項目時須使用的逗號。</p> -<p>To add a tag, click in the edit box at the end of the tag list and type the tag name you wish to add. Tags will autocomplete as you type. Press enter (or return) to submit the new tag. Each article may have as many tags as needed. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.</p> +<ul> + <li><span class="correct"><strong>正確</strong></span>： I will travel on trains, planes, and automobiles.</li> + <li><span class="incorrect"><strong>不正確</strong></span>： I will travel on trains, planes and automobiles.</li> +</ul> -<p>To remove a tag, simply click the little "X" icon in the tag.</p> +<h4 id="Apostrophes_and_quotation_marks">撇號和引用標示</h4> -<h4 id="標記需要加工的頁面">標記需要加工的頁面</h4> +<p>譯註：下列格式及範例仍採用英文格式作為忠實傳達原文說明如何書寫英文的相關知識。</p> -<p>In addition to using tags to track information about the documentation's quality and content, we also use them to mark articles as needing specific types of work.</p> +<p><strong>不使用「彎」引號（ curly quote ）和引用標示。</strong>在 MDN 我們只用直引號及撇號。</p> -<h4 id="標記棄用的頁面">標記棄用的頁面</h4> +<p>這樣做有幾個原因。</p> -<p>Use the following tags for pages that are not current:</p> +<ol> + <li>我們必須做出選擇並保持一致的風格。</li> + <li>如果彎引號或撇號被寫入程式碼片段中——即便是行內——讀者都有可能把它們複製貼上到其他地方並期待可以正常運作（事實上不行）。</li> +</ol> <ul> - <li><em>Junk</em>: Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.</li> - <li><em>Obsolete</em>: Use for content that is technically superceded, but still valid in context. For example an HTML element that is obsolete in HTML5 is still valid in HTML 4.01. You can also use the <span class="nowiki">{{TemplateLink("obsolete_header")}}</span> macro to put a prominent banner on the topic.</li> - <li><em>Archive</em>: Use for content that is technically superceded and no longer useful. If possible, add a note to the topic referring readers to a more current topic. For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the <em>NeedsUpdate</em> tag, and add an explanation on the Talk page.) Pages with the Archive tag are eventually moved from the main content of MDN to the <a href="/en-US/docs/Archive">Archive</a> section.</li> + <li><span class="correct"><strong>正確</strong></span>： Please don't use "curly quotes."</li> + <li><span class="incorrect"><strong>不正確</strong></span>： Please don’t use “curly quotes.”</li> </ul> -<h3 id="SEO_摘要">SEO 摘要</h3> +<h3 id="Spelling">拼寫</h3> -<p>The SEO summary is a very short summary of the page. It will be reported as a summary of the article to robots crawling the site, and will then appear in search results for the page. It is also used by macros that automate the construction of landing pages inside MDN itself.</p> +<p>譯註：下列格式及範例仍採用英文格式作為忠實傳達原文說明如何書寫英文的相關知識。</p> -<p>By default, the first pagragraph of the page is used as the SEO summary. However you can override this behavior by marking a section with the <a href="/en-US/docs/Project:MDN/Contributing/Editor_guide/Editing#Formatting_styles">"SEO summary" style in the WYSIWYG editor</a>.</p> +<p>須用美式英文拼寫。</p> -<h3 id="導航頁面">導航頁面</h3> +<p>一般上使用 <a href="https://www.dictionary.com/">Dictionary.com</a> 上的第一個條目，除非該條目被列為異體字或主要用於非美國的英語。例如，如果檢視「 <a href="https://www.dictionary.com/browse/behaviour">behaviour</a> 」，會發現在「 Chiefly British 」之後緊跟著一個連向美國標準格式的連結「 <a href="https://dictionary.reference.com/browse/behavior">behavior</a> 」。不要用異體字。</p> -<p><strong>Landing pages</strong> are pages at the root of a topic area of the site, such as the main <a href="/en-US/docs/CSS" title="CSS">CSS</a> or <a href="/en-US/docs/HTML" title="HTML">HTML</a> pages. They have a standard format that consists of three areas:</p> +<ul> + <li><span class="correct"><strong>正確</strong></span>： localize, behavior</li> + <li><span class="incorrect"><strong>不正確</strong></span>： localise, behaviour</li> +</ul> -<ol> - <li>A brief (typically one paragraph) overview of what the technology is and what it's used for. See {{anch("Writing a landing page overview")}} for tips.</li> - <li>A two-column list of links with appropriate headings. See {{anch("Creating a page link list")}} for guidelines.</li> - <li>An <strong>optional</strong> "Browser compatibility" section at the bottom of the page.</li> -</ol> +<h3 id="Terminology">術語</h3> -<h4 id="創建頁面連結清單">創建頁面連結清單</h4> +<h4 id="HTML_elements">HTML 元素</h4> -<p>The link list section of an MDN landing page consists of two columns. These are created using the following HTML:</p> +<p>使用「元素」（ elements ）來指稱 HTML 和 XML 元素，而非「標籤」（ tags ）。此外，還需要把它們用「 <> 」包裹並以 {{HTMLElement("code")}} 樣式呈現。</p> -<pre class="brush: html notranslate"><div class="row topicpage-table"> - <div class="section"> - ... left column contents ... - </div> - <div class="section"> - ... right column contents ... - </div> -</div></pre> +<p>當第一次在章節中參照了某個元素，應使用 {{TemplateLink("HTMLElement")}} 巨集來建立指向該元素的文件（除非就在撰寫該元素的參考文件）。</p> -<p>The left-hand column should be a list of articles, with an <code><h2></code> header at the top of the left column explaining that it's a list of articles about the topic (for example "Documentation and tutorials about foo"); this header should use the CSS class "Documentation". Below that is a <code><dl></code> list of articles, with each article's link in a <code><dt></code> block and a brief one-or-two sentence summary of the article in the corresponding <code><dd></code> block.</p> +<ul> + <li><span class="correct"><strong>正確</strong></span>： {{HTMLElement("span")}} 元素</li> + <li><span class="incorrect"><strong>不正確</strong></span>： span 標籤</li> +</ul> -<p>The right-hand column should contain one or more of the following sections, in order:</p> +<h4 id="Parameters_vs._arguments">參數或引數</h4> -<dl> - <dt>從社群尋求協助</dt> - <dd>This should provide information on Matrix rooms and mailing lists available about the topic. The heading should use the class "Community".</dd> - <dt>工具</dt> - <dd>A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".</dd> - <dt>相關主題</dt> - <dd>A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".</dd> -</dl> - -<p><strong><<<finish this once we finalize the landing page standards>>></strong></p> +<p>MDN 偏好使用<strong>參數</strong>。為了保持一致性，請盡可能避免使用「引數」。</p> -<h2 id="插入、使用圖片">插入、使用圖片</h2> +<h4 id="User_interface_actions">使用者介面動作</h4> -<p>It's sometimes helpful to provide an image in an article you create or modify, especially if the article is very technical. To include an image:</p> +<p>在連續的操作指南中，使用祈使語氣進行描述使用者介面動作。透過它的標籤及類別指明使用者介面的元素。</p> -<ol> - <li>Attach the desired image file to the article (at the bottom of every article in edit mode)</li> - <li>Create an image in the WYSIWYG editor</li> - <li>In the WYSIWYG editor in the drop-down list listing attachments, select the newly created attachment which is your image</li> - <li>Press OK.</li> -</ol> +<ul> + <li><span class="correct"><strong>正確</strong></span>：點選編輯按鈕。</li> + <li><span class="incorrect"><strong>不正確</strong></span>：點選編輯。</li> +</ul> -<h2 id="其它參考">其它參考</h2> +<h3 id="Voice">語態</h3> -<h3 id="Preferred_style_guides" name="Preferred_style_guides">首選風格指南</h3> +<p>主動語態更受到青睞，但被動語態也可以接受，這讓內容看起來不會太過嚴肅。但請盡量保持一致的風格。</p> -<p>If you have questions about usage and style not covered here, we recommend referring to the <a href="http://www.economist.com/research/StyleGuide/">Economist style guide</a> or, failing that, the <a href="http://www.amazon.com/gp/product/0226104036/">Chicago Manual of Style</a>.</p> +<h2 id="Other_references">其他參考</h2> -<h3 id="Preferred_dictionary" name="Preferred_dictionary">首選詞典</h3> +<h3 id="Preferred_style_guides">偏好的風格指南</h3> -<p>For questions of spelling, please refer to <a href="http://www.answers.com/library/Dictionary">Answers.com</a>. The spell-checker for this site uses American English. Please do not use variant spellings (e.g., use <em>honor</em> rather than <em>honour</em>).</p> +<p>如果對本文未涵蓋的用法及風格有疑問，建議可以參考<a href="https://docs.microsoft.com/zh-tw/style-guide/welcome/">微軟寫作風格指南</a>——或<a href="https://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206">芝加哥風格手冊</a>。<a href="https://faculty.cascadia.edu/cma/HIST148/cmscrib.pdf">非官方的芝加哥風格手冊</a>可以透過線上取得。</p> -<p>We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please send them to the <a href="/en-US/docs/Project:Community" title="Project:en/Community">MDC mailing list</a> or <a href="/User:Sheppy" title="User:Sheppy">project lead</a> so we know what should be added.</p> +<h3 id="Preferred_dictionary">Preferred dictionary</h3> -<h3 id="MDC-specific" name="MDC-specific">MDN 特定資訊</h3> +<p>拼寫的問題請參考 <a href="https://www.dictionary.com/">Dictionary.com</a> 。本站的拼寫檢查使用美式英文。請不要使用異體拼寫（例如，使用 <em>color</em> 而不是 <em>colour</em> ）。</p> -<ul> - <li><a href="/en-US/docs/Project:Custom_CSS_Classes" title="Project:en/Custom_CSS_Classes">Custom CSS classes</a> defined for all MDC pages.</li> - <li><a href="/en-US/docs/Project:Custom_Templates" title="Project:en/Custom_Templates">Custom templates</a> created for use on MDC, with explanations.</li> -</ul> +<p>我們會隨時擴充指南的內容，如果因本文件尚未涵蓋的內容而找不到特定的問題，請把問題發布到 <a href="https://discourse.mozilla.org/c/mdn">MDN discussion forum</a> 好讓我們知道應該加入這些內容。</p> -<h3 id="Other_resources" name="Other_resources">語言、文法和拼字</h3> +<h3 id="Language_grammar_spelling">語言、文法、拼寫</h3> -<p>If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.</p> +<p>如果對增進寫作及編輯技巧有興趣的話，可以根據下列清單中找到對你有幫助的資源。</p> <ul> - <li><a href="http://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">On Writing Well</a>, by William Zinsser (Amazon link)</li> - <li><a href="http://www.amazon.com/Style-Basics-Clarity-Grace-4th/dp/0205830765/" title="http://www.amazon.com/Style-Lessons-Clarity-Grace-Edition/dp/0321898680">Style: The Basics of Clarity and Grace</a>, by Joseph Williams and Gregory Colomb (Amazon link)</li> - <li><a href="http://www.bartleby.com/64/">American Heritage Book of English Usage</a></li> - <li><a href="http://www.wsu.edu/~brians/errors/">Common Errors in English</a></li> - <li><a href="http://www-personal.umich.edu/~jlawler/aue.html">English Grammar FAQ</a> (alt.usage.english)</li> - <li><a href="http://www.angryflower.com/bobsqu.gif">Bob's quick guide to the apostrophe, you idiots</a> (funny)</li> - <li><a href="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2" title="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster's Concise Dictionary of English Usage</a> (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.</li> + <li><a href="https://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">On Writing Well</a>, by William Zinsser (Amazon link)</li> + <li><a href="https://www.amazon.com/Style-Basics-Clarity-Grace-4th/dp/0205830765/">Style: The Basics of Clarity and Grace</a>, by Joseph Williams and Gregory Colomb (Amazon link)</li> + <li><a href="https://brians.wsu.edu/common-errors-in-english-usage/">Common Errors in English</a></li> + <li><a href="https://www-personal.umich.edu/~jlawler/aue.html">English Grammar FAQ</a> (alt.usage.english)</li> + <li><a href="https://www.angryflower.com/bobsqu.gif">Bob's quick guide to the apostrophe, you idiots</a> (funny)</li> + <li><a href="https://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster's Concise Dictionary of English Usage</a> (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.</li> + <li><a href="https://english.stackexchange.com/">English Language and Usage StackExchange</a>: Question and answer site for English language usage.</li> </ul> |