qmk · ymzcdg · Feb 13, 2020 · Feb 14, 2020 · Feb 15, 2020 · Feb 16, 2020
diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md
@@ -4,7 +4,7 @@ This page attempts to explain the basic information you need to know to work wit
 
 ## Basic QMK Structure
 
-QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk_core` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
+QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk_core` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboards` folders.
 
 ### Userspace Structure
 

diff --git a/docs/newbs_building_firmware_configurator.md b/docs/newbs_building_firmware_configurator.md
@@ -9,13 +9,13 @@ Watch the [Video Tutorial](https://youtu.be/tx54jkRC9ZY)
 The QMK Configurator works best with Chrome/Firefox. 
 
 
-!> **Files from other tools such as KLE, or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool. **
+!> **Files from other tools such as KLE, or kbfirmware will not be compatible with QMK Configurator. Do not load them, do not import them. QMK Configurator is a DIFFERENT tool.**
 
 ## Selecting your keyboard
 
 Click the drop down box and select the keyboard you want to create a keymap for. 
 
-?> If your keyboard has several versions, make sure you select the correct one.** 
+?> **If your keyboard has several versions, make sure you select the correct one.** 
 
 I'll say that again because it's important
 

diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md
@@ -1,4 +1,4 @@
-* [完全菜鸟指南](zh-cn/newbs.md)
+* [菜鸟入门指南](zh-cn/newbs.md)
   * [入门](zh-cn/newbs_getting_started.md)
   * [构建你的第一个固件](zh-cn/newbs_building_firmware.md)
   * [刷新固件](zh-cn/newbs_flashing.md)
@@ -25,7 +25,7 @@
   * [一般问题](zh-cn/faq_general.md)
   * [构建/编译](zh-cn/faq_build.md)
   * [调试/故障排除](zh-cn/faq_debug.md)
-  * [布局](zh-cn/faq_keymap.md)
+  * [映射](zh-cn/faq_keymap.md)
   * [Zadig驱动安装](zh-cn/driver_installation_zadig.md)
 
 * 详细指南
@@ -34,7 +34,7 @@
   * [构建/编译指南](zh-cn/getting_started_make_guide.md)
   * [刷新固件](zh-cn/flashing.md)
   * [定制功能](zh-cn/custom_quantum_functions.md)
-  * [布局概述](zh-cn/keymap.md)
+  * [映射概述](zh-cn/keymap.md)
 
 * [硬件](zh-cn/hardware.md)
   * [兼容的单片机](zh-cn/compatible_microcontrollers.md)
@@ -128,5 +128,7 @@
   * [Midi工具库](zh-cn/internals_midi_util.md)
   * [发送函数](zh-cn/internals_send_functions.md)
   * [Sysex工具](zh-cn/internals_sysex_tools.md)
-<!--fromen:20200126-6:03AM(GMT+8)-->
-<!--cn:20200211-11:04AM(GMT+8)-->
+
+<!--源文件：https://raw.githubusercontent.com/qmk/qmk_firmware/d0d106cef75b4121374020fca633e8fc2628cef0/docs/_summary.md 
+    源提交哈希：d0d106cef75b4121374020fca633e8fc2628cef0-->
+<!--翻译时间:20200217-18:18(GMT+8)-->
diff --git a/docs/zh-cn/contributing.md b/docs/zh-cn/contributing.md
@@ -1,4 +1,4 @@
-# 如何做贡献
+# 为本工程做贡献
 
 👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍
 
@@ -23,7 +23,7 @@
 
 # 项目概况
 
-Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的。怎么说呢，都是我的一部分，两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的，尤其与AVR([LUFA](http://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](http://www.chibios.com))两小哥哥搭配，干活不累，嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念，但也有点不爽，因为您以前的经验可能没法用来帮助Q酱。
+Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的。怎么说呢，都是我的一部分，两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的，尤其与AVR([LUFA](http://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](http://www.chibios.com))两小哥哥搭配，干活不累，嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念， 不过您以前的经验可能没法用来帮助Q酱。
 
 <!-- 需要修正: 这里放些学习C语言的资源。另外感谢修正的小可爱。谢谢您了。-->
 
@@ -36,7 +36,7 @@ Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的
 您以前是否没为开源贡献过代码，而又想知道帮助Q酱是怎么一回事? 稍安勿躁，咱给您总结一下！
 
 0. 先注册一个 [GitHub](https://github.com) 账户。
-1. 做好一个你要贡献的布局，那就要 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。
+1. 做好一个你要贡献的映射，那就要 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。
 2. 把关联着问题的仓库分叉（fork）到你的仓库。这样你在`你的GitHub用户名/qmk_firmware`就有一个仓库备份啦。
 3. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git`这个命令把仓库同步到你的电脑中。
 4. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。
@@ -54,61 +54,10 @@ Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的
 
 # 代码规范
 
-其实也没有什么特别严格的规范啦，但是俗话说的好：没有规矩，不成方圆。您可以看一下您的要改动的代码周围的画风，然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议：
-
-* 我们用肆(4)个空格来缩进(软件中也可以设置到Tab键)
-* 我们使用改良的1TBS(允许单行样式)
-  * 左大括号: 在开放性语句块那行的末尾
-  * 右大括号: 和开放性语句块第一个字母对齐
-  * Else If: 将右大括号放在行的开头，下一个左大括号放在同一行的结尾
-  * 可选大括号: 可选大括号是必选的
-    * 应该这样: if (condition) { return false; }
-    * 不应该这样: if (condition) return false;
-* 建议使用C语言风格的注释: `/* */`
-  * 把注释想象成一个描述特征的故事
-  * 充分使用注释来描述你为何这样修改
-  * 有些公认的东西就不要写到注释里面了
-  * 如果你不知道注释是否多余,看下面
-* 一般不要主动换行，主动换行的话每行不要超过76列
-* 要把 `#pragma once` 放到头文件的开始哦，抛弃老土的(`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)吧
-* 下面两种预处理命令都可以用: `#ifdef DEFINED` 还有 `#if defined(DEFINED)`
-  * 以上那句对处女座不是很友好哈，处女座的朋友们就别纠结了，直接 `#if defined(DEFINED)` 。
-  * 还有就是选好一种风格就一直用，一直用一直爽，不要朝三暮四, 除非你要变化到多重条件的 `#if`。
-  * `#` 和 `if`要挨在一起哦，再让本空格在中间冒充电灯泡本空格会生气的。
-  * 以下是缩进规则:
-    * 首先考虑可读性，强迫症的朋友们总想要保持代码的高一致性，这样可不好。
-    * 保证文件已有风格不变。如果代码本来就是杂糅风格，那就见机行事，让你的修改更有意义些。
-    * 其实你也可以在缩进的时候看看周围其他代码，然后范水模山，预处理命令可以有自己的缩进风格。
-
-可以参照下面:
+我们的大多数风格您都是能接受的，如果您会C或者Python的话我们的代码都会让您有家一样的感觉。
 
-```c
-/* foo 的 Enums*/
-enum foo_state {
-  FOO_BAR,
-  FOO_BAZ,
-};
-
-/* 有返回值的情况 */
-int foo(void) {
-  if (some_condition) {
-    return FOO_BAR;
-  } else {
-    return -1;
-  }
-}
-```
-
-# Clang-format的自动格式化
-[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) 是LLVM的一部分，可以帮你自动格式化代码。我们给你准备好了一个适用于以上规范的配置文件，会帮你调整缩进和换行，你只需要写好括号就好。有了它，你再也不用担心调整代码格式太耗时，没有时间陪伴自己（虚构）的另一半了。
-
-使用[LLVM 完整安装](http://llvm.org/builds/)可以在Windows上安装clang-format, Ubuntu用户要用`sudo apt install clang-format`。
-
-命令行的朋友们, 加上 `-style=file`选项就会自动在QMK的根目录寻找.clang-format配置文件了。
-
-VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。
-
-有些东西(比如LAYOUT宏) 会被clang-format打乱，所以那些文件就别用clang-format了,这里就教您一个小窍门，在`// clang-format off` 和 `//clang-format on`之间装上会被搞乱的代码就好了。
+* [代码规范 - C](zh-cn/coding_conventions_c.md)
+* [代码规范 - Python](zh-cn/coding_conventions_python.md)
 
 # 一般教程
 
@@ -117,7 +66,7 @@ VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独
 * 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。
 * 提交之前看一眼，`git diff --check`的空格一定要写对了
 * 确定你的代码能通过编译
-  * 布局: 确定`make keyboard:your_new_keymap` 不返回错误
+  * 映射: 确定`make keyboard:your_new_keymap` 不返回错误
   * 键盘: 确定 `make keyboard:all` 不返回错误
   * 核心代码: 确定 `make all` 不返回错误
 * 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如:
@@ -130,11 +79,13 @@ The kerpleplork was intermittently failing with error code 23. The root cause wa
 Limited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.
 ```
 
+!> **重点来了:** 如果您想为用户代码做漏洞修复或者改进，比如改进一下非默认的映射、用户空间或映射什么的，请务必标注你的PR中代码的原始提交者。有好些开发者小可爱就因为自己的代码在不知情的情况下被修改了，都急哭了，他们中还有很多是平常表现很坚强的大神哦。
+
 ## 文档
 
 想帮助Q酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴，如果你是对的人[点这个](#Q酱，我在哪能帮助你嘞?)!
 
-文档呢，都静静的放在`qmk_firmware/docs` 目录里, 也或者您想为网页做贡献的话也是可以的哦。
+文档呢，都静静的放在`qmk_firmware/docs` 目录里, 您如果习惯网页的话也是可以的哦，点击 https://docs.qmk.fm/ 页面下面的"Edit this page"就可以啦。
 
 在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像`my_layers`或者`my_keycodes`来防止名字不一致的enums被当作特务枪毙:
 
@@ -150,14 +101,26 @@ enum my_keycodes {
 };
 ```
 
-## 布局
+### 预览文档
+
+在做出PR之前，你可以先预览一下文档。如果你安装了开大环境的话，在 `qmk_firmware/` 文件夹下使用下列命令:
+
+    ./bin/qmk docs
+
+或者你安装了Python3的话使用:
 
-大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则，这样可以让别人更好理解你的代码
+    python3 -m http.server 8936
+
+然后访问 `http://localhost:8936/`.
+
+## 映射
+
+大多数QMK新手都从创建一个自己的映射开始。我们尽力保证映射规范宽松 (毕竟映射是个性的体现) 不过建议遵守以下准则，这样可以让别人更好理解你的代码
 
 * 用 [模板](documentation_templates.md)写个`readme.md`。
-* 所有的布局PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧
-* 不要把新特性和布局一起PR。可以分别PR他们
-* 布局文件夹就不要放`Makefile`了，这个操作都过时啦
+* 所有的映射PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧
+* 不要把新特性和映射一起PR。可以分别PR他们
+* 映射文件夹就不要放`Makefile`了，这个操作都过时啦
 * 更新文件头部的copyrights(看`%YOUR_NAME%`那)
 
 ## 键盘
@@ -175,7 +138,7 @@ QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制
 
 ## Quantum/TMK 核心
 
-在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前，一定要确保你的工作是有意义的。看看[了解QMK](understanding_qmk.md)你会对Q酱有更深的了解，这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以：
+在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前，一定要确保你的工作是有意义的。看看[了解QMK](zh-cn/understanding_qmk.md)你会对Q酱有更深的了解，这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以：
 
 * [在Discord交流](https://discord.gg/Uq7gcHh)
 * [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new)
@@ -184,16 +147,16 @@ QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制
 
 修复BUG或者开发新特性之前看看这个：
 
-* **默认不启用** - QMK运行的芯片多数内存有限，所以首要考虑的还应该是布局不要被破坏，于是特性默认是不启用的。你喜欢什么特性的话就打开它，如果你觉得有些特性应该默认开启或者你能帮助缩减代码，那就联系维护组吧。
+* **默认不启用** - QMK运行的芯片多数内存有限，所以首要考虑的还应该是映射不要被破坏，于是特性默认是不启用的。你喜欢什么特性的话就打开它，如果你觉得有些特性应该默认开启或者你能帮助缩减代码，那就联系维护组吧。
 * **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 我们的Travis系统会发现一切问题，但是自己编译一下可要比在线等快多了。
 * **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性，或者在不支持的平台自动禁用。
 * **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。
 
 也可以看看以下建议：
 
 * 提交数量尽量合理，不然我们可就要把你的PR给squash了。
-* 不要把新特性、布局和键盘一起PR。可以分别PR他们。
-* 给你的特性写[单元测试](unit_testing.md)。
+* 不要把新特性、映射和键盘一起PR。可以分别PR他们。
+* 给你的特性写[单元测试](zh-cn/unit_testing.md)。
 * 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，你就要先看看[代码规范](#代码规范)确认情况。
 
 ## 重构
@@ -203,3 +166,7 @@ QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制
 # 行为守则对于我来说有何意义?
 
 我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人，无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者，我们将站在你这边，并按照行为准则对施暴者进行适当谴责。
+
+<!--源文件：https://raw.githubusercontent.com/qmk/qmk_firmware/3c190f8927f8676febb5e247908d2bdfd574a54b/docs/contributing.md 
+    源提交哈希：3c190f8927f8676febb5e247908d2bdfd574a54b-->
+<!--翻译时间:20200217-18:20(GMT+8)-->