Chinese Translation of version 1.0.0

source/zh-CN/1.0.0/index.html.haml

@@ -1,7 +1,7 @@
 ---
-description: Keep a Changelog
+description: 如何维护更新日志
-title: Keep a Changelog
+title: 如何维护更新日志
-language: en
+language: zh-CN
 version: 1.0.0
 ---
 
@@ -18,8 +18,8 @@ version: 1.0.0
 
 .header
   .title
-    %h1 Keep a Changelog
+    %h1 如何维护更新日志
-    %h2 Don’t let your friends dump git logs into changelogs.
+    %h2 更新日志绝对不应该是git日志的堆砌物
 
   = link_to changelog do
     Version
@@ -30,248 +30,236 @@ version: 1.0.0
 .answers
   %h3#what
     %a.anchor{ href: "#what", aria_hidden: "true" }
-    What is a changelog?
+    更新日志是什么？
 
   %p
-    A changelog is a file which contains a curated, chronologically
+    更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表，
-    ordered list of notable changes for each version of a project.
+    以记录一个项目中所有版本的显著变动。
 
   %h3#why
     %a.anchor{ href: "#why", aria_hidden: "true" }
-    Why keep a changelog?
+    为何要提供更新日志？
 
   %p
-    To make it easier for users and contributors to see precisely what
+    为了让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动。
-    notable changes have been made between each release (or version) of
-    the project.
 
   %h3#who
     %a.anchor{ href: "#who", aria_hidden: "true" }
-    Who needs a changelog?
+    哪些人需要更新日志？
 
   %p
-    People do. Whether consumers or developers, the end users of
+    人人需要更新日志。无论是消费者还是开发者，软件的最终用户都关心软件所包含什么。
-    software are human beings who care about what's in the software. When
+    当软件有所变动时，大家希望知道改动是为何、以及如何进行的。
-    the software changes, people want to know why and how.
 
 .good-practices
   %h3#how
     %a.anchor{ href: "#how", aria_hidden: "true" }
-    How do I make a good changelog?
+    怎样制作高质量的更新日志？
 
   %h4#principles
     %a.anchor{ href: "#principles", aria_hidden: "true" }
-    Guiding Principles
+    指导原则
 
   %ul
     %li
-      Changelogs are <em>for humans</em>, not machines.
+      记住日志是写给<em>人</em>的，而非机器。
     %li
-      There should be an entry for every single version.
+      每个版本都应该有独立的入口。
     %li
-      The same types of changes should be grouped.
+      同类改动应该分组放置。
     %li
-      Versions and sections should be linkable.
+      版本与章节应该相互对应。
     %li
-      The latest version comes first.
+      新版本在前，旧版本在后。
     %li
-      The release date of each versions is displayed.
+      应包括每个版本的发布日期。
     %li
-      Mention whether you follow #{link_to "Semantic Versioning", semver}.
+      注明是否遵守#{link_to "语义化版本格式", semver}.
 
   %a.anchor{ href: "#types", aria_hidden: "true" }
-  %h4#types Types of changes
+  %h4#types 变动类型
 
   %ul
     %li
       %code Added
-      for new features.
+      新添加的功能。
     %li
       %code Changed
-      for changes in existing functionality.
+      对现有功能的变更。
     %li
       %code Deprecated
-      for soon-to-be removed features.
+      已经不建议使用，准备很快移除的功能。
     %li
       %code Removed
-      for now removed features.
+      已经移除的功能。
     %li
       %code Fixed
-      for any bug fixes.
+      对bug的修复
     %li
       %code Security
-      in case of vulnerabilities.
+      对安全的改进
 
 .effort
 
   %h3#effort
     %a.anchor{ href: "#effort", aria_hidden: "true" }
-    How can I reduce the effort required to maintain a changelog?
+    如何减少维护更新日志的精力？
 
   %p
-    Keep an <code>Unreleased</code> section at the top to track upcoming
+    在文档最上方提供 <code>Unreleased</code> 区块以记录即将发布的更新内容。
-    changes.
 
-  %p This serves two purposes:
+  %p 这样有两大意义：
 
   %ul
     %li
-      People can see what changes they might expect in upcoming releases
+      大家可以知道在未来版本中可能会有哪些变更
     %li
-      At release time, you can move the <code>Unreleased</code> section
+      在发布新版本时，可以直接将<code>Unreleased</code>区块中的内容移动至新发
-      changes into a new release version section.
+      布版本的描述区块就可以了
 
 .bad-practices
   %h3#bad-practices
     %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
-    Can changelogs be bad?
+    有很糟糕的更新日志吗？
-  %p Yes. Here are a few ways they can be less than useful.
+    
+  %p 当然有，下面就是一些糟糕的方式。
+  
   %h4#log-diffs
     %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
-    Commit log diffs
+    使用git日志
 
   %p
-    Using commit log diffs as changelogs is a bad idea: they're full of
+    使用git日志作为更新日志是个非常糟糕的方式：git日志充满各种无意义的信息，
-    noise. Things like merge commits, commits with obscure titles,
+    如合并提交、语焉不详的提交标题、文档更新等。
-    documentation changes, etc.
 
   %p
-    The purpose of a commit is to document a step in the evolution of
+    提交的目的是记录源码的演化。
-    the source code. Some projects clean up commits, some don't.
+    一些项目会清理提交记录，一些则不会。
 
   %p
-    The purpose of a changelog entry is to document the noteworthy
+    更新日志的目的则是记录重要的变更以供最终受众阅读，而记录范围通常涵盖多次提交。
-    difference, often across multiple commits, to communicate them
-    clearly to end users.
     
   %h4#ignoring-deprecations
     %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
-    Ignoring Deprecations
+    无视即将弃用功能
+    
   %p
-    When people upgrade from one version to another, it should be
+    当从一个版本升级至另一个时，人们应清楚（尽管痛苦）的知道哪些部分将出现问题。
-    painfully clear when something will break. It should be possible to
+    应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后，
-    upgrade to a version that lists deprecations, remove what's
+    再升级至把那些弃用功能真正移除的版本。
-    deprecated, then upgrade to the version where the deprecations
+    
-    become removals.
   %p
-    If you do nothing else, list deprecations, removals, and any
+    即使其他什么都不做，也要在更新日志中列出derecations，removals以及其他重大变动。
-    breaking changes in your changelog.
+    
   %h4#confusing-dates
     %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
-    Confusing Dates
+    易混淆的日期格式
 
   %p
-    In the U.S., people put the month first (<code>06-02-2012</code> for
+    在美国，人们将月份写在日期的起始(<code>06-02-2012</code>对应2012年6月2日)，
-    June 2nd, 2012), while many people in the rest of the world write a
+    与此同时世界上其他地方的很多人将至写作<code>2 June 2012</code>，并拥有不同发音。
-    robotic-looking <code>2 June 2012</code>, yet pronounce it
+    <code>2012-06-02</code>从大到小的排列符合逻辑，并不与其他日期格式相混淆，而且还
-    differently. <code>2012-06-02</code> works logically from largest to
+    符合#{link_to "ISO标准", iso}。因此，推荐在更新日志中采用使用此种日期格式。
-    smallest, doesn't overlap in ambiguous ways with other date formats,
-    and is an #{link_to "ISO standard", iso}. Thus, it is the
-    recommended date format for changelogs.
 
   %aside
-    There’s more. Help me collect these antipatterns by
+    还有更多内容。请通过
-    = link_to "opening an issue", issues
+    = link_to "发布问题", issues
-    or a pull request.
+    或发布pull请求帮助我收集更多异常模式。
 
 .frequently-asked-questions
   %h3#frequently-asked-questions
     %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
-    Frequently Asked Questions
+    常见问题
+    
   %h4#standard
     %a.anchor{ href: "#standard", aria_hidden: "true" }
-    Is there a standard changelog format?
+    是否有一个标准化的更新日志格式？
 
   %p
-    Not really. There's the GNU changelog style guide, or the two-
+    并没有。虽然GNU提供了更新日志样式指引，以及那个仅有两段长的GNU NEWS文件“指南”，
-    paragraph-long GNU NEWS file "guideline". Both are inadequate or
+    但两者均远远不够。
-    insufficient.
 
   %p
-    This project aims to be
+    此项目意在提供一个
-    = link_to "a better changelog convention.", changelog
+    = link_to "更好的更新日志惯例", changelog
-    It comes from observing good practices in the open source
+    所有点子都来自于在开源社区中对优秀实例的观察与记录。
-    community and gathering them.
 
   %p
-    Healthy criticism, discussion and suggestions for improvements
+    对于所有建设性批评、讨论及建议，我们都非常
-    = link_to "are welcome.", issues
+    = link_to "欢迎。", issues
 
 
   %h4#filename
     %a.anchor{ href: "#filename", aria_hidden: "true" }
-    What should the changelog file be named?
+    更新日志文件应被如何命名？
 
   %p
-    Call it <code>CHANGELOG.md</code>. Some projects use
+    可以叫做<code>CHANGELOG.md</code>。 一些项目也使用
-    <code>HISTORY</code>, <code>NEWS</code> or <code>RELEASES</code>.
+    <code>HISTORY</code>、<code>NEWS</code>或<code>RELEASES</code>。
 
   %p
-    While it's easy to think that the name of your changelog file
+    当然，你可以认为更新日志的名字并不是什么要紧事，但是为什么要为难那些仅仅是
-    doesn't matter that much, why make it harder for your end users to
+    想看到都有哪些重大变更的最终用户呢？
-    consistently find notable changes?
 
   %h4#github-releases
     %a.anchor{ href: "#github-releases", aria_hidden: "true" }
-    What about GitHub Releases?
+    对于GitHub发布呢？
+    
   %p
-    It's a great initiative. #{link_to "Releases", ghr} can be used to
+    这是个非常好的倡议。#{link_to "Releases", ghr}可通过手动添加发布日志或将带
-    turn simple git tags (for example a tag named <code>v1.0.0</code>)
+    有注释的git标签信息抓取后转换的方式，将简单的git标签（如一个叫<code>v1.0.0</code>的标签）
-    into rich release notes by manually adding release notes or it can
+    转换为信息丰富的发布日志。
-    pull annotated git tag messages and turn them into notes.
+
   %p
-    GitHub Releases create a non-portable changelog that can only be
+    GitHub发布会创建一个非便携、仅可在GitHub环境下显示的更新日志。尽管会花费更
-    displayed to users within the context of GitHub. It's possible to
+    多时间，但将之处理成更新日志格式是完全可能的。
-    make them look very much like the Keep a Changelog format, but it
+
-    tends to be a bit more involved.
   %p
-    The current version of GitHub releases is also arguably not very
+    现行版本的GitHub发布不像哪些典型的大写文件(<code>README</code>, 
-    discoverable by end-users, unlike the typical uppercase files
+    <code>CONTRIBUTING</code>, etc.)，仍可以认为是不利于最终用户探索的。
-    (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Another
+    另一个小问题则是界面并不提供不同版本间commit日志的链接。
-    minor issue is that the interface doesn't currently offer links to
+
-    commit logs between each release.
   %h4#automatic
     %a.anchor{ href: "#automatic", aria_hidden: "true" }
-    Can changelogs be automatically parsed?
+    更新日志可以被自动识别吗？
 
   %p
-    It’s difficult, because people follow wildly different formats and
+    非常困难，因为有各种不同的文件格式和命名。
-    file names.
+    
 
   %p
-    #{link_to "Vandamme", vandamme} is a Ruby gem created by the
+    #{link_to "Vandamme", vandamme} 是一个Ruby程序，由
-    #{link_to "Gemnasium", gemnasium} team and which parses many (but
+    #{link_to "Gemnasium", gemnasium} 团队制作，可以解析多种
-    not all) open source project changelogs.
+    （但绝对不是全部）开源库的更新日志。
 
 
   %h4#yanked
     %a.anchor{ href: "#yanked", aria_hidden: "true" }
-    What about yanked releases?
+    那些后来撤下的版本怎么办？
     
   %p
-    Yanked releases are versions that had to be pulled because of a
+    因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。
-    serious bug or security issue. Often these versions don't even
+    这些版本一般不出现在更新日志里，但建议他们出现。
-    appear in change logs. They should. This is how you should display
+    显示方式应该是：
-    them:
 
   %p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
 
   %p
-    The <code>[YANKED]</code> tag is loud for a reason. It's important
+    <code>[YANKED]</code> 的标签应该非常醒目。
-    for people to notice it. Since it's surrounded by brackets it's also
+    人们应该非常容易就可以注意到他。
-    easier to parse programmatically.
+    并且被方括号所包围也使其更易被程序识别。
 
 
   %h4#rewrite
     %a.anchor{ href: "#rewrite", aria_hidden: "true" }
-    Should you ever rewrite a changelog?
+    是否可以重写更新日志？
 
   %p
-    Sure. There are always good reasons to improve a changelog. I
+    当然可以。总会有多种多样的原因需要我们去改进更新日志。
-    regularly open pull requests to add missing releases to open source
+    对于那些有着未维护更新日志的开源项目，我会定期打开pull请求以加入缺失的发布信息。
-    projects with unmaintained changelogs.
 
   %p
+    另外，很有可能你发现自己忘记记录一个重大功能更新。这种情况下显然你应该去重写更新日志。
     It's also possible you may discover that you forgot to address a
     breaking change in the notes for a version. It's obviously important
     for you to update your changelog in this case.
@@ -279,22 +267,19 @@ version: 1.0.0
 
   %h4#contribute
     %a.anchor{ href: "#contribute", aria_hidden: "true" }
-    How can I contribute?
+    如何贡献？
 
   %p
-    This document is not the <strong>truth</strong>; it’s my carefully
+    本文档并非<strong>真理</strong>。而是我深思熟虑后的建议，以及我收集的信息与典例。
-    considered opinion, along with information and examples I gathered.
 
   %p
-    This is because I want our community to reach a consensus. I believe
+    我希望我们的社区可以对此达成一直。我相信讨论的过程与最终结果一样重要。
-    the discussion is as important as the end result.
 
   %p
-    So please <strong>#{link_to "pitch in", gh}</strong>.
+    所以欢迎<strong>#{link_to "贡献", gh}</strong>.
 
 .press
-  %h3 Conversations
+  %h3 访谈
   %p
-    I went on #{link_to "The Changelog podcast", thechangelog}
+    我在#{link_to "更新日志播客", thechangelog}上讲述了为何维护者与贡献者应关心更新日志，
-    to talk about why maintainers and contributors should care about changelogs,
+    以及支持我进行此项目的诸多因素。
-    and also about the motivations behind this project.