aboutsummaryrefslogtreecommitdiff
path: root/docs/zh-cn
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zh-cn')
-rw-r--r--docs/zh-cn/README.md31
-rw-r--r--docs/zh-cn/_summary.md133
-rw-r--r--docs/zh-cn/contributing.md205
-rw-r--r--docs/zh-cn/custom_quantum_functions.md490
-rw-r--r--docs/zh-cn/faq.md6
-rw-r--r--docs/zh-cn/faq_build.md122
-rw-r--r--docs/zh-cn/faq_debug.md136
-rw-r--r--docs/zh-cn/faq_general.md19
-rw-r--r--docs/zh-cn/faq_keymap.md151
-rw-r--r--docs/zh-cn/getting_started_getting_help.md15
-rw-r--r--docs/zh-cn/getting_started_github.md64
-rw-r--r--docs/zh-cn/getting_started_introduction.md54
-rw-r--r--docs/zh-cn/newbs.md23
-rw-r--r--docs/zh-cn/newbs_best_practices.md163
-rw-r--r--docs/zh-cn/newbs_building_firmware.md81
-rw-r--r--docs/zh-cn/newbs_flashing.md307
-rw-r--r--docs/zh-cn/newbs_getting_started.md102
-rw-r--r--docs/zh-cn/newbs_learn_more_resources.md15
-rw-r--r--docs/zh-cn/newbs_testing_debugging.md46
-rw-r--r--docs/zh-cn/reference_glossary.md167
20 files changed, 2330 insertions, 0 deletions
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
new file mode 100644
index 000000000..b42818d58
--- /dev/null
+++ b/docs/zh-cn/README.md
@@ -0,0 +1,31 @@
1# QMK机械键盘固件
2
3[![当前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
4[![异议](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
5[![文档状态](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
6[![GitHub贡献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
7[![GitHub分支](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
8
9## 什么是 QMK 固件?
10
11QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包括 QMK 固件, QMK 工具箱, qmk.fm网站, 和这些文档。QMK 固件是一个基于[tmk\_keyboard](https://github.com/tmk/tmk_keyboard)的键盘固件，它在爱特梅尔AVR微控制器实现一些有用的功能,确切地说, 是在 [OLKB product line](https://olkb.com), 在 [ErgoDox EZ](https://www.ergodox-ez.com) 键盘, 和 [Clueboard product line](https://clueboard.co/). 上。它被移植到使用ChibiOS的ARM芯片上. 它可以在飞线键盘或定制PCB键盘中发挥功能.
12
13## 如何得到它
14
15如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从GitHub获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls).
16
17此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`[email protected]:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`).
18
19## 如何编译
20
21在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令:
22
23 make planck/rev4:default
24
25这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下:
26
27 make preonic:default
28
29## 如何定制
30
31QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](https://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。
diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md
new file mode 100644
index 000000000..cedcfbd52
--- /dev/null
+++ b/docs/zh-cn/_summary.md
@@ -0,0 +1,133 @@
1* [完全菜鸟指南](zh-cn/newbs.md)
2 * [入门](zh-cn/newbs_getting_started.md)
3 * [构建你的第一个固件](zh-cn/newbs_building_firmware.md)
4 * [刷新固件](zh-cn/newbs_flashing.md)
5 * [测试和调试](zh-cn/newbs_testing_debugging.md)
6 * [Git最佳实践](zh-cn/newbs_git_best_practices.md)
7 * [使用你分叉(fork)的主分支(master)](zh-cn/newbs_git_using_your_master_branch.md)
8 * [解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md)
9 * [重新同步一个分支](zh-cn/newbs_git_resynchronize_a_branch.md)
10 * [学习资源](zh-cn/newbs_learn_more_resources.md)
11
12* [QMK基础](zh-cn/README.md)
13 * [QMK简介](zh-cn/getting_started_introduction.md)
14 * [QMK命令行工具](zh-cn/cli.md)
15 * [QMK命令行工具配置](zh-cn/cli_configuration.md)
16 * [向QMK贡献代码](zh-cn/contributing.md)
17 * [如何使用GitHub](zh-cn/getting_started_github.md)
18 * [获得帮助](zh-cn/getting_started_getting_help.md)
19
20* [非兼容性修改](zh-cn/breaking_changes.md)
21 * [我的PR已经被标记为非兼容性修改](zh-cn/breaking_changes_instructions.md)
22 * [2019年8月30日](zh-cn/ChangeLog/20190830.md)
23
24* [问题与解答](zh-cn/faq.md)
25 * [一般问题](zh-cn/faq_general.md)
26 * [构建/编译](zh-cn/faq_build.md)
27 * [调试/故障排除](zh-cn/faq_debug.md)
28 * [布局](zh-cn/faq_keymap.md)
29 * [Zadig驱动安装](zh-cn/driver_installation_zadig.md)
30
31* 详细指南
32 * [安装构建工具](zh-cn/getting_started_build_tools.md)
33 * [vagrant指南](zh-cn/getting_started_vagrant.md)
34 * [构建/编译指南](zh-cn/getting_started_make_guide.md)
35 * [刷新固件](zh-cn/flashing.md)
36 * [定制功能](zh-cn/custom_quantum_functions.md)
37 * [布局概述](zh-cn/keymap.md)
38
39* [硬件](zh-cn/hardware.md)
40 * [兼容的单片机](zh-cn/compatible_microcontrollers.md)
41 * [AVR处理器](zh-cn/hardware_avr.md)
42 * [驱动](zh-cn/hardware_drivers.md)
43
44* 参考
45 * [键盘指南](zh-cn/hardware_keyboard_guidelines.md)
46 * [配置选项](zh-cn/config_options.md)
47 * [键码](zh-cn/keycodes.md)
48 * [代码书写规范 - C](zh-cn/coding_conventions_c.md)
49 * [代码书写规范 - Python](zh-cn/coding_conventions_python.md)
50 * [文档书写规范](zh-cn/documentation_best_practices.md)
51 * [文档模板](zh-cn/documentation_templates.md)
52 * [术语表](zh-cn/reference_glossary.md)
53 * [单元测试](zh-cn/unit_testing.md)
54 * [实用函数](zh-cn/ref_functions.md)
55 * [配置器支持](zh-cn/reference_configurator_support.md)
56 * [info.json 格式](zh-cn/reference_info_json.md)
57 * [Python 命令行开发](zh-cn/cli_development.md)
58
59* [特性](zh-cn/features.md)
60 * [基本键码](zh-cn/keycodes_basic.md)
61 * [US ANSI控制码](zh-cn/keycodes_us_ansi_shifted.md)
62 * [量子键码](zh-cn/quantum_keycodes.md)
63 * [高级键码](zh-cn/feature_advanced_keycodes.md)
64 * [音频](zh-cn/feature_audio.md)
65 * [自动shift](zh-cn/feature_auto_shift.md)
66 * [背光](zh-cn/feature_backlight.md)
67 * [蓝牙](zh-cn/feature_bluetooth.md)
68 * [热改键](zh-cn/feature_bootmagic.md)
69 * [组合](zh-cn/feature_combo)
70 * [命令](zh-cn/feature_command.md)
71 * [消抖 API](zh-cn/feature_debounce_type.md)
72 * [拨动开关](zh-cn/feature_dip_switch.md)
73 * [动态宏指令](zh-cn/feature_dynamic_macros.md)
74 * [编码器](zh-cn/feature_encoders.md)
75 * [重音号Esc复合键](zh-cn/feature_grave_esc.md)
76 * [触摸反馈](zh-cn/feature_haptic_feedback.md)
77 * [HD44780 LCD控制器](zh-cn/feature_hd44780.md)
78 * [自锁键](zh-cn/feature_key_lock.md)
79 * [布局](zh-cn/feature_layouts.md)
80 * [前导键](zh-cn/feature_leader_key.md)
81 * [LED阵列](zh-cn/feature_led_matrix.md)
82 * [宏指令](zh-cn/feature_macros.md)
83 * [鼠标键](zh-cn/feature_mouse_keys.md)
84 * [OLED驱动](zh-cn/feature_oled_driver.md)
85 * [一键功能](zh-cn/one_shot_keys.md)
86 * [指针设备](zh-cn/feature_pointing_device.md)
87 * [PS/2鼠标](zh-cn/feature_ps2_mouse.md)
88 * [RGB灯光](zh-cn/feature_rgblight.md)
89 * [RGB矩阵](zh-cn/feature_rgb_matrix.md)
90 * [空格候补换挡](zh-cn/feature_space_cadet.md)
91 * [分体键盘](zh-cn/feature_split_keyboard.md)
92 * [速录机](zh-cn/feature_stenography.md)
93 * [换手](zh-cn/feature_swap_hands.md)
94 * [多击键](zh-cn/feature_tap_dance.md)
95 * [终端](zh-cn/feature_terminal.md)
96 * [热敏打印机](zh-cn/feature_thermal_printer.md)
97 * [Unicode](zh-cn/feature_unicode.md)
98 * [用户空间](zh-cn/feature_userspace.md)
99 * [速度键](zh-cn/feature_velocikey.md)
100
101* 制造和定制者指南
102 * [手工连线指南](zh-cn/hand_wire.md)
103 * [ISP刷新指南](zh-cn/isp_flashing_guide.md)
104 * [ARM调试指南](zh-cn/arm_debugging.md)
105 * [ADC设备](zh-cn/adc_driver.md)
106 * [I2C设备](zh-cn/i2c_driver.md)
107 * [SPI设备](zh-cn/spi_driver.md)
108 * [WS2812设备](zh-cn/ws2812_driver.md)
109 * [EEPROM设备](zh-cn/eeprom_driver.md)
110 * [GPIO控制](zh-cn/internals_gpio_control.md)
111 * [自定义键盘矩阵](zh-cn/custom_matrix.md)
112 * [Proton C转换](zh-cn/proton_c_conversion.md)
113
114* 深入了解
115 * [键盘工作原理](zh-cn/how_keyboards_work.md)
116 * [深入了解QMK](zh-cn/understanding_qmk.md)
117
118* 其他话题
119 * [使用Eclipse开发QMK](zh-cn/other_eclipse.md)
120 * [使用VSCode开发QMK](zh-cn/other_vscode.md)
121 * [支持](zh-cn/getting_started_getting_help.md)
122 * [翻译QMK文档](zh-cn/translating.md)
123
124* QMK 内构 (正在编写)
125 * [定义](zh-cn/internals_defines.md)
126 * [输入回调寄存器](zh-cn/internals_input_callback_reg.md)
127 * [Midi设备](zh-cn/internals_midi_device.md)
128 * [Midi设备配置过程](zh-cn/internals_midi_device_setup_process.md)
129 * [Midi工具库](zh-cn/internals_midi_util.md)
130 * [发送函数](zh-cn/internals_send_functions.md)
131 * [Sysex工具](zh-cn/internals_sysex_tools.md)
132<!--fromen:20200126-6:03AM(GMT+8)-->
133<!--cn:20200211-11:04AM(GMT+8)-->
diff --git a/docs/zh-cn/contributing.md b/docs/zh-cn/contributing.md
new file mode 100644
index 000000000..6424d330c
--- /dev/null
+++ b/docs/zh-cn/contributing.md
@@ -0,0 +1,205 @@
1# 如何做贡献
2
3👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍
4
5第三方的帮助让Q酱成长了许多呢，Q酱也从你们那学到了不少新东西。Q酱希望每一个想帮助我的人都能很方便的做出有用的贡献。在这里我给摩拳擦掌的你们写了一点引导，让你们的代码在不对我做重大改动的情况下都能成功的被采纳哦。
6
7* [项目概况](#项目概况)
8* [代码规范](#代码规范)
9* [一般教程](#一般教程)
10* [行为守则对于我来说有何意义?](#行为守则对于我来说有何意义?)
11
12## 这文章巨长无比不想读啊! 我就想问个问题而已!
13
14您要是想问关于Q酱的问题的话可以在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)随意问。
15
16请记住:
17
18* 维护Q酱的小可爱有的时候可能会有点忙，不能及时回答您的问题，耐心等等，他们都是很nice的人呀。
19* 维护Q酱的人都是很无私的善良的人。无论是贡献代码还是回答问题，都是义务的。有时见到他们努力回答各种问题，解决各种BUG，Q酱也是很心疼的。
20* 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答：
21 * https://opensource.com/life/16/10/how-ask-technical-questions
22 * http://www.catb.org/esr/faqs/smart-questions.html
23
24# 项目概况
25
26Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的。怎么说呢，都是我的一部分，两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的，尤其与AVR([LUFA](https://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](https://www.chibios.org))两小哥哥搭配，干活不累，嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念，但也有点不爽，因为您以前的经验可能没法用来帮助Q酱。
27
28<!-- 需要修正: 这里放些学习C语言的资源。另外感谢修正的小可爱。谢谢您了。-->
29
30# Q酱，我在哪能帮助你嘞?
31
32您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh).
33
34# Q酱，我如何帮助你?
35
36您以前是否没为开源贡献过代码，而又想知道帮助Q酱是怎么一回事? 稍安勿躁，咱给您总结一下！
37
380. 先注册一个 [GitHub](https://github.com) 账户。
391. 做好一个你要贡献的布局，那就要 [找一个你想解决的问题](https://github.com/qmk/qmk_firmware/issues)，或者 [找一个你想添加的特性](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)。
402. 把关联着问题的仓库分叉（fork）到你的仓库。这样你在`你的GitHub用户名/qmk_firmware`就有一个仓库备份啦。
413. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git`这个命令把仓库同步到你的电脑中。
424. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。
435. 使用`git checkout -b 此处写分支名字（别用汉字）`命令来创建一个分支（branch）用于开发。
446. 对要解决的问题或要添加的特性进行适当的更改。
457. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引（快照）里。
468. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。
479. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里（反正不是打篮球那个库里）。
4810. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。
4911. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟Q酱的中文也不是那么的溜，有可能会看不懂中文）。
5012. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想问维护的小可爱们的问题。你的your pull request有点小问题无伤大雅(本来也没有完美的代码嘛), 维护的小可爱们会竭尽全力帮您改进的！
5113. 维护人员审查代码可能需要一些时间。
5214. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。
5315. 预祝您合并成功！
54
55# 代码规范
56
57其实也没有什么特别严格的规范啦，但是俗话说的好：没有规矩，不成方圆。您可以看一下您的要改动的代码周围的画风，然后保持队形。如果你感觉周围都不知道是什么牛鬼蛇神的话就看看下面的建议：
58
59* 我们用肆(4)个空格来缩进(软件中也可以设置到Tab键)
60* 我们使用改良的1TBS(允许单行样式)
61 * 左大括号: 在开放性语句块那行的末尾
62 * 右大括号: 和开放性语句块第一个字母对齐
63 * Else If: 将右大括号放在行的开头，下一个左大括号放在同一行的结尾
64 * 可选大括号: 可选大括号是必选的
65 * 应该这样: if (condition) { return false; }
66 * 不应该这样: if (condition) return false;
67* 建议使用C语言风格的注释: `/* */`
68 * 把注释想象成一个描述特征的故事
69 * 充分使用注释来描述你为何这样修改
70 * 有些公认的东西就不要写到注释里面了
71 * 如果你不知道注释是否多余,看下面
72* 一般不要主动换行，主动换行的话每行不要超过76列
73* 要把 `#pragma once` 放到头文件的开始哦，抛弃老土的(`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)吧
74* 下面两种预处理命令都可以用: `#ifdef DEFINED` 还有 `#if defined(DEFINED)`
75 * 以上那句对处女座不是很友好哈，处女座的朋友们就别纠结了，直接 `#if defined(DEFINED)` 。
76 * 还有就是选好一种风格就一直用，一直用一直爽，不要朝三暮四, 除非你要变化到多重条件的 `#if`。
77 * `#` 和 `if`要挨在一起哦，再让本空格在中间冒充电灯泡本空格会生气的。
78 * 以下是缩进规则:
79 * 首先考虑可读性，强迫症的朋友们总想要保持代码的高一致性，这样可不好。
80 * 保证文件已有风格不变。如果代码本来就是杂糅风格，那就见机行事，让你的修改更有意义些。
81 * 其实你也可以在缩进的时候看看周围其他代码，然后范水模山，预处理命令可以有自己的缩进风格。
82
83可以参照下面:
84
85```c
86/* foo 的 Enums*/
87enum foo_state {
88 FOO_BAR,
89 FOO_BAZ,
90};
91
92/* 有返回值的情况 */
93int foo(void) {
94 if (some_condition) {
95 return FOO_BAR;
96 } else {
97 return -1;
98 }
99}
100```
101
102# Clang-format的自动格式化
103[Clang-format](https://clang.llvm.org/docs/ClangFormat.html) 是LLVM的一部分，可以帮你自动格式化代码。我们给你准备好了一个适用于以上规范的配置文件，会帮你调整缩进和换行，你只需要写好括号就好。有了它，你再也不用担心调整代码格式太耗时，没有时间陪伴自己（虚构）的另一半了。
104
105使用[LLVM 完整安装](https://llvm.org/builds/)可以在Windows上安装clang-format, Ubuntu用户要用`sudo apt install clang-format`。
106
107命令行的朋友们, 加上 `-style=file`选项就会自动在QMK的根目录寻找.clang-format配置文件了。
108
109VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。
110
111有些东西(比如LAYOUT宏) 会被clang-format打乱，所以那些文件就别用clang-format了,这里就教您一个小窍门，在`// clang-format off` 和 `//clang-format on`之间装上会被搞乱的代码就好了。
112
113# 一般教程
114
115你可以给Q酱的不同部分添砖加瓦，但也要用不同的方法严谨检查。不论你修改哪里最好还是看看下边。
116
117* 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。
118* 提交之前看一眼，`git diff --check`的空格一定要写对了
119* 确定你的代码能通过编译
120 * 布局: 确定`make keyboard:your_new_keymap` 不返回错误
121 * 键盘: 确定 `make keyboard:all` 不返回错误
122 * 核心代码: 确定 `make all` 不返回错误
123* 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如:
124
125```
126Adjust the fronzlebop for the kerpleplork
127
128The kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.
129
130Limited 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.
131```
132
133## 文档
134
135想帮助Q酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴，如果你是对的人[点这个](#Q酱，我在哪能帮助你嘞?)!
136
137文档呢，都静静的放在`qmk_firmware/docs` 目录里, 也或者您想为网页做贡献的话也是可以的哦。
138
139在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像`my_layers`或者`my_keycodes`来防止名字不一致的enums被当作特务枪毙:
140
141```c
142enum my_layers {
143 _FIRST_LAYER,
144 _SECOND_LAYER
145};
146
147enum my_keycodes {
148 FIRST_LAYER = SAFE_RANGE,
149 SECOND_LAYER
150};
151```
152
153## 布局
154
155大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则，这样可以让别人更好理解你的代码
156
157* 用 [模板](documentation_templates.md)写个`readme.md`。
158* 所有的布局PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧
159* 不要把新特性和布局一起PR。可以分别PR他们
160* 布局文件夹就不要放`Makefile`了，这个操作都过时啦
161* 更新文件头部的copyrights(看`%YOUR_NAME%`那)
162
163## 键盘
164
165QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md`会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。
166
167我们建议你按下面的来操作:
168
169* 用[模板](documentation_templates.md)写`readme.md`。
170* 提交数量尽量合理，不然我们可就要把你的PR给squash了。
171* 不要把新特性和新键盘一起PR。可以分别PR他们
172* 用父文件夹的名字命名 `.c`/`.h`文件, 比如`/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
173* 键盘文件夹就不要放`Makefile`了，这个操作都过时啦
174* 更新文件头部的copyrights(看`%YOUR_NAME%`那)
175
176## Quantum/TMK 核心
177
178在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前，一定要确保你的工作是有意义的。看看[了解QMK](understanding_qmk.md)你会对Q酱有更深的了解，这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以：
179
180* [在Discord交流](https://discord.gg/Uq7gcHh)
181* [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new)
182
183新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以，在实施重大返修之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。
184
185修复BUG或者开发新特性之前看看这个：
186
187* **默认不启用** - QMK运行的芯片多数内存有限，所以首要考虑的还应该是布局不要被破坏，于是特性默认是不启用的。你喜欢什么特性的话就打开它，如果你觉得有些特性应该默认开启或者你能帮助缩减代码，那就联系维护组吧。
188* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 我们的Travis系统会发现一切问题，但是自己编译一下可要比在线等快多了。
189* **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性，或者在不支持的平台自动禁用。
190* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。
191
192也可以看看以下建议：
193
194* 提交数量尽量合理，不然我们可就要把你的PR给squash了。
195* 不要把新特性、布局和键盘一起PR。可以分别PR他们。
196* 给你的特性写[单元测试](unit_testing.md)。
197* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，你就要先看看[代码规范](#代码规范)确认情况。
198
199## 重构
200
201为了保持QMK脉络清晰，Q酱打算深入规划重构一下自己，然后让合作者进行修改。如果你有重构的思路或建议[创建一个issue](https://github.com/qmk/qmk_firmware/issues), Q酱很乐意讨论一下怎么改进一下。
202
203# 行为守则对于我来说有何意义?
204
205我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人，无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者，我们将站在你这边，并按照行为准则对施暴者进行适当谴责。
diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md
new file mode 100644
index 000000000..1ae996e39
--- /dev/null
+++ b/docs/zh-cn/custom_quantum_functions.md
@@ -0,0 +1,490 @@
1# 如何定制你键盘的功能
2
3对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。
4
5本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
6
7## A Word on Core vs 键盘 vs 布局
8
9我们把qmk组织成一个层次结构：
10
11* Core (`_quantum`)
12 * Keyboard/Revision (`_kb`)
13 * Keymap (`_user`)
14
15下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。
16
17在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。
18<!-- 翻译问题：上面那句翻译的不太好-->
19# 自定义键码
20
21到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。
22
23## 定义一个新键码
24
25创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。
26
27
28这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。
29
30```c
31enum my_keycodes {
32 FOO = SAFE_RANGE,
33 BAR
34};
35```
36
37## 为键码的行为编程
38
39当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。
40
41当某个键按下或释放时这俩函数会被调用。
42
43### process_record_user()`函数示例实现
44
45这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。
46
47```c
48bool process_record_user(uint16_t keycode, keyrecord_t *record) {
49 switch (keycode) {
50 case FOO:
51 if (record->event.pressed) {
52 // 按下时做些什么
53 } else {
54 // 释放时做些什么
55 }
56 return false; // 跳过此键的所有进一步处理
57 case KC_ENTER:
58 // 当按下回车时播放音符
59 if (record->event.pressed) {
60 PLAY_SONG(tone_qwerty);
61 }
62 return true; // 让QMK触发回车按下/释放事件
63 default:
64 return true; // 正常处理其他键码
65 }
66}
67```
68
69### `process_record_*` 函数文档
70
71* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
72* 布局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
73
74`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。
75
76`record`参数含有实际按键的信息：
77
78```c
79keyrecord_t record {
80 keyevent_t event {
81 keypos_t key {
82 uint8_t col
83 uint8_t row
84 }
85 bool pressed
86 uint16_t time
87 }
88}
89```
90
91# LED控制
92
93qmk提供了读取HID规范包含的5个LED的方法。:
94
95* `USB_LED_NUM_LOCK`
96* `USB_LED_CAPS_LOCK`
97* `USB_LED_SCROLL_LOCK`
98* `USB_LED_COMPOSE`
99* `USB_LED_KANA`
100
101这五个常量对应于主机LED状态的位置位。
102有两种方法可以获得主机LED状态：
103
104* 通过执行 `led_set_user()`
105* 通过调用 `host_keyboard_leds()`
106
107## `led_set_user()`
108
109当5个LED中任何一个的状态需要改变时，此函数将被调用。此函数通过参数输入LED参数。
110使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这两个宏来检查LED状态。
111
112!> `host_keyboard_leds()`可能会在`led_set_user()`被调用前返回新值。
113
114### `led_set_user()`函数示例实现
115
116```c
117void led_set_user(uint8_t usb_led) {
118 if (IS_LED_ON(usb_led, USB_LED_NUM_LOCK)) {
119 writePinLow(B0);
120 } else {
121 writePinHigh(B0);
122 }
123 if (IS_LED_ON(usb_led, USB_LED_CAPS_LOCK)) {
124 writePinLow(B1);
125 } else {
126 writePinHigh(B1);
127 }
128 if (IS_LED_ON(usb_led, USB_LED_SCROLL_LOCK)) {
129 writePinLow(B2);
130 } else {
131 writePinHigh(B2);
132 }
133 if (IS_LED_ON(usb_led, USB_LED_COMPOSE)) {
134 writePinLow(B3);
135 } else {
136 writePinHigh(B3);
137 }
138 if (IS_LED_ON(usb_led, USB_LED_KANA)) {
139 writePinLow(B4);
140 } else {
141 writePinHigh(B4);
142 }
143}
144```
145
146### `led_set_*`函数文档
147
148* 键盘/修订: `void led_set_kb(uint8_t usb_led)`
149* 布局: `void led_set_user(uint8_t usb_led)`
150
151## `host_keyboard_leds()`
152
153调用这个函数会返回最后收到的LED状态。这个函数在`led_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码).
154为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。
155
156## 设置物理LED状态
157
158一些键盘实现了为设置物理LED的状态提供了方便的方法。
159
160### Ergodox Boards
161
162Ergodox实现了提供`ergodox_right_led_1`/`2`/`3_on`/`off()`来让每个LED开或关, 也可以用 `ergodox_right_led_on`/`off(uint8_t led)` 按索引打开或关闭他们。
163
164此外，还可以使用`ergodox_led_all_set(uint8_t n)`指定所有LED的亮度级别；针对每个LED用`ergodox_right_led_1`/`2`/`3_set(uint8_t n)`；使用索引的话用`ergodox_right_led_set(uint8_t led, uint8_t n)`。
165
166Ergodox boards 同时定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高亮度级别`LED_BRIGHTNESS_HI`(默认最高).
167
168# 键盘初始化代码
169
170键盘初始化过程有几个步骤。你是用那个函数取决于你想要做什么。
171
172有三个主要初始化函数，按调用顺序列出。
173
174* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。
175* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能尚未初始化。
176* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
177
178!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。
179
180## 键盘预初始化代码
181
182这代码极早运行，甚至都在USB初始化前运行。
183
184在这之后不久矩阵就被初始化了。
185
186对于大多数用户来说,这用不到，因为它主要是用于面向硬件的初始化。
187
188但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的).
189
190### `keyboard_pre_init_user()`函数示例实现
191
192本例中在键盘级别，设定 B0, B1, B2, B3, 和 B4 是LED引脚。
193
194```c
195void keyboard_pre_init_user(void) {
196 // 调用键盘预初始化代码
197
198 // 设置LED引脚为输出模式
199 setPinOutput(B0);
200 setPinOutput(B1);
201 setPinOutput(B2);
202 setPinOutput(B3);
203 setPinOutput(B4);
204}
205```
206
207### `keyboard_pre_init_*` 函数文档
208
209* 键盘/修订: `void keyboard_pre_init_kb(void)`
210* 布局: `void keyboard_pre_init_user(void)`
211
212## 矩阵初始化代码
213
214这将会在矩阵初始化时被调用，在某些硬件设置好后，但在一些功能被初始化前。
215
216这在你设置其他地方会用到的东西的时候会很有用，但与硬件无关，也不依赖于它的启动位置。
217
218
219### `matrix_init_*`函数文档
220
221* 键盘/修订: `void matrix_init_kb(void)`
222* 布局: `void matrix_init_user(void)`
223
224
225## 键盘后初始化代码
226
227这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。
228
229
230### `keyboard_post_init_user()`示例实现
231
232本示例在所有初始化完成后运行，配置RGB灯。
233
234```c
235void keyboard_post_init_user(void) {
236 // 调用后初始化代码
237 rgblight_enable_noeeprom(); // 使能Rgb，不保存设置
238 rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存
239 rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存
240}
241```
242
243### `keyboard_post_init_*` 函数文档
244
245* 键盘/修订: `void keyboard_post_init_kb(void)`
246* 布局: `void keyboard_post_init_user(void)`
247
248# 矩阵扫描代码
249
250可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。
251
252### `matrix_scan_*`示例实现
253
254这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
255
256### `matrix_scan_*` 函数文档
257
258* 键盘/修订: `void matrix_scan_kb(void)`
259* 布局: `void matrix_scan_user(void)`
260
261该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。
262
263你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。
264
265
266# 键盘 空闲/唤醒 代码
267
268如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。
269
270用两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在系统板空闲和唤醒时调用。
271
272
273### suspend_power_down_user()和suspend_wakeup_init_user()示例实现
274
275
276```c
277void suspend_power_down_user(void) {
278 // code will run multiple times while keyboard is suspended
279}
280
281void suspend_wakeup_init_user(void) {
282 // code will run on keyboard wakeup
283}
284```
285
286### 键盘 挂起/唤醒 函数文档
287
288* 键盘/修订: `void suspend_power_down_kb(void)` 和`void suspend_wakeup_init_user(void)`
289* 布局: `void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
290
291# 层改变代码
292
293每当层改变这个就运行代码。这对于层指示或自定义层处理很有用。
294
295### `layer_state_set_*` 示例实现
296
297本例使用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)使之与层对应
298
299```c
300layer_state_t layer_state_set_user(layer_state_t state) {
301 switch (biton32(state)) {
302 case _RAISE:
303 rgblight_setrgb (0x00, 0x00, 0xFF);
304 break;
305 case _LOWER:
306 rgblight_setrgb (0xFF, 0x00, 0x00);
307 break;
308 case _PLOVER:
309 rgblight_setrgb (0x00, 0xFF, 0x00);
310 break;
311 case _ADJUST:
312 rgblight_setrgb (0x7A, 0x00, 0xFF);
313 break;
314 default: // for any other layers, or the default layer
315 rgblight_setrgb (0x00, 0xFF, 0xFF);
316 break;
317 }
318 return state;
319}
320```
321### `layer_state_set_*` 函数文档
322
323* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
324* 布局: `layer_state_t layer_state_set_user(layer_state_t state)`
325
326
327该`状态`是活动层的bitmask, 详见[布局概述](keymap.md#布局的层状态)
328
329
330# 掉电保存配置 (EEPROM)
331
332这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。
333
334最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。
335
336记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。
337
338* 如果您不理解这个例子，那么您可能希望避免使用这个特性，因为它相当复杂。
339
340### 示例实现
341
342本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！
343
344
345在你的keymap.c文件中，将以下代码添加至顶部:
346```c
347typedef union {
348 uint32_t raw;
349 struct {
350 bool rgb_layer_change :1;
351 };
352} user_config_t;
353
354user_config_t user_config;
355```
356
357以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。
358
359 `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。
360
361首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样：
362```c
363void keyboard_post_init_user(void) {
364 // 调用布局级别的矩阵初始化
365
366 // 从EEPROM读用户配置
367 user_config.raw = eeconfig_read_user();
368
369 // 如使能，设置默认层
370 if (user_config.rgb_layer_change) {
371 rgblight_enable_noeeprom();
372 rgblight_sethsv_noeeprom_cyan();
373 rgblight_mode_noeeprom(1);
374 }
375}
376```
377以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。
378
379```c
380layer_state_t layer_state_set_user(layer_state_t state) {
381 switch (biton32(state)) {
382 case _RAISE:
383 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
384 break;
385 case _LOWER:
386 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
387 break;
388 case _PLOVER:
389 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
390 break;
391 case _ADJUST:
392 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
393 break;
394 default: // 针对其他层或默认层
395 if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
396 break;
397 }
398 return state;
399}
400```
401这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为：
402```c
403
404bool process_record_user(uint16_t keycode, keyrecord_t *record) {
405 switch (keycode) {
406 case FOO:
407 if (record->event.pressed) {
408 // 按下时做点什么
409 } else {
410 // 释放时做点什么
411 }
412 return false; // 跳过此键的进一步处理
413 case KC_ENTER:
414 // 在按下回车时播放音符
415 if (record->event.pressed) {
416 PLAY_SONG(tone_qwerty);
417 }
418 return true; // 让QMK产生回车按下/释放事件
419 case RGB_LYR: // 本句让underglow作为层指示，或正常使用。
420 if (record->event.pressed) {
421 user_config.rgb_layer_change ^= 1; // 切换状态
422 eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态
423 if (user_config.rgb_layer_change) { // 如果层状态被使能
424 layer_state_set(layer_state); // 那么立刻更新层颜色
425 }
426 }
427 return false;
428 case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参考)
429 if (record->event.pressed) { //本句失能层指示，假设你改变了这个…你要把它禁用
430 if (user_config.rgb_layer_change) { // 仅当使能时
431 user_config.rgb_layer_change = false; // 失能，然后
432 eeconfig_update_user(user_config.raw); // 向EEPROM写入设置
433 }
434 }
435 return true; break;
436 default:
437 return true; // 按其他键正常
438 }
439}
440```
441最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值
442
443```c
444void eeconfig_init_user(void) { // EEPROM正被重置
445 user_config.raw = 0;
446 user_config.rgb_layer_change = true; // 我们想要默认使能
447 eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值
448
449 // use the non noeeprom versions, 还要向EEPROM写入这些值
450 rgblight_enable(); // 默认使能RGB
451 rgblight_sethsv_cyan(); // 默认设置青色
452 rgblight_mode(1); // 默认设置长亮
453}
454```
455
456然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。
457
458### 'EECONFIG' 函数文档
459
460* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)`
461* 布局: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`和`void eeconfig_update_user(uint32_t val)`
462
463`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。
464
465# 自定义击键-长按临界值(TAPPING_TERM)
466默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。
467
468想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。
469
470
471## `get_tapping_term`示例实现
472
473想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代码:
474
475```c
476uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
477 switch (keycode) {
478 case SFT_T(KC_SPC):
479 return TAPPING_TERM + 1250;
480 case LT(1, KC_GRV):
481 return 130;
482 default:
483 return TAPPING_TERM;
484 }
485}
486```
487
488### `get_tapping_term` 函数文档
489
490不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。
diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md
new file mode 100644
index 000000000..3d0b65c6f
--- /dev/null
+++ b/docs/zh-cn/faq.md
@@ -0,0 +1,6 @@
1# 常见问题
2
3* [一般问题](faq_general.md)
4* [构建和编译QMK](faq_build.md)
5* [QMK调试和故障排除](faq_debug.md)
6* [布局问题](faq_keymap.md)
diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md
new file mode 100644
index 000000000..c4b6e64d8
--- /dev/null
+++ b/docs/zh-cn/faq_build.md
@@ -0,0 +1,122 @@
1# 关于构建的常见问题
2
3本页所写是QMK构建的常见问题.如果你还没有进行过编译,就看一下[构建环境搭建](getting_started_build_tools.md) 和 [make的说明](getting_started_make_guide.md).
4
5## 如果您不能在Linux上编程
6您需要适当的权限才能操作设备。对于Linux用户, 请参阅下方有关`udev`规则的说明。如果您对`udev`有问题，解决方法是用`sudo`命令。如果您不熟悉此命令，使用`man sudo`查看其手册或[看这个网页](https://linux.die.net/man/8/sudo).
7
8在你的主控是ATMega32u4时，以下是使用`sudo`命令的样例：
9
10 $ sudo dfu-programmer atmega32u4 erase --force
11 $ sudo dfu-programmer atmega32u4 flash your.hex
12 $ sudo dfu-programmer atmega32u4 reset
13
14或只用；
15
16 $ sudo make <keyboard>:<keymap>:dfu
17
18使用`sudo`运行`make`一般来说**不**推荐，如果可能，尽量使用前一种方法之一。
19
20### Linux `udev` 规则
21在Linux上，您需要适当的权限才能访问MCU。你也可以在刷新固件时使用 `sudo`，或把这些文件放到`/etc/udev/rules.d/`。
22
23**/etc/udev/rules.d/50-atmel-dfu.rules:**
24```
25# Atmel ATMega32U4
26SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
27# Atmel USBKEY AT90USB1287
28SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
29# Atmel ATMega32U2
30SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
31```
32
33**/etc/udev/rules.d/52-tmk-keyboard.rules:**
34```
35# tmk键盘产品 https://github.com/tmk/tmk_keyboard
36SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
37```
38**/etc/udev/rules.d/54-input-club-keyboard.rules:**
39
40```
41# Input Club keyboard bootloader
42SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
43```
44
45### 串行设备在Linux上检测不到bootloader模式
46确保您的内核对您的设备有相应的支持。 如果你的设备是 USB ACM, 比如Pro Micro (Atmega32u4)，就要加上`CONFIG_USB_ACM=y`. 其他设备可能需要`USB_SERIAL` 及其任何子选项。
47
48## DFU Bootloader的未知设备
49
50如果您在使用Windows来刷新键盘的时候碰到了问题，检查设备管理器。如果在键盘处于 "bootloader模式"时你看到 "未知设备"，说明你可能面临设备问题。
51
52重新运行MSYS2上的安装脚本或许会凑效（比如在MSYS2/WSL运行 `./util/qmk_install.sh`) 或者重新安装QMK工具箱也可能会解决你的问题。
53
54如果以上方法还是短针攻疽，那您可能需要使用[Zadig Utility](https://zadig.akeo.ie/)。下载此程序, 找到设备问题, 然后选择 `WinUSB`选项, 然后点击"Reinstall driver"。完成后再试试刷新你的键盘。倘若依然徒劳无功，那就尝试所有选项直到好用为止。
55
56?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。
57如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备)
58
59## USB VID 和 PID
60你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。
61
62大多数QMK主板使用`0xFEED`作为vendor ID。您应该查看其他键盘，以确保选择了唯一的Product ID。
63
64也要看看这个。
65https://github.com/tmk/tmk_keyboard/issues/150
66
67一也可以在下方链接购买一个唯一的VID:PID。不过个人使用似乎用不着这个。
68- https://www.obdev.at/products/vusb/license.html
69- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
70
71## AVR的BOOTLOADER_SIZE
72注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。
73
74```
75# Boot Section Size in *bytes*
76# Teensy halfKay 512
77# Teensy++ halfKay 2048
78# Atmel DFU loader 4096 (TMK Alt Controller)
79# LUFA bootloader 4096
80# USBaspLoader 2048
81OPT_DEFS += -DBOOTLOADER_SIZE=2048
82```
83
84## 在MacOS上 `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)`
85这是brew更新的问题，导致AVR GCC依赖的符号链接被损坏。
86
87解决方案是移除并重新安装所有受影响的模块。
88
89```
90brew rm avr-gcc
91brew rm dfu-programmer
92brew rm dfu-util
93brew rm gcc-arm-none-eabi
94brew rm avrdude
95brew install avr-gcc
96brew install dfu-programmer
97brew install dfu-util
98brew install gcc-arm-none-eabi
99brew install avrdude
100```
101
102### avr-gcc 8.1 和 LUFA
103
104如果你把avr-gcc升级到7以上你可能会遇到关于LUFA的问题。比如:
105
106`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
107
108那你就需要在brew中把avr-gcc回退到7。
109
110```
111brew uninstall --force avr-gcc
112brew install avr-gcc@8
113brew link --force avr-gcc@8
114```
115
116### 我刷新了我的键盘但是键盘不工作/按键没有注册 - 而且还是ARM的 (rev6 planck, clueboard 60, hs60v2, etc...) (Feb 2019)
117由于EEPROM在基于ARM的芯片上的工作原理，保存的设置可能不再有效。这会影响默认层，而且*或许*在某些情况下，会使键盘不好用，我们仍在调查这些情况。重置EEPROM将解决此问题。
118
119[Planck rev6键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) 是用于强制重置EEPROM的。刷入这个文件后，再次刷入正常固件，这会将键盘恢复到_正常_工作状态。
120[Preonic rev3键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
121
122如果以任何形式启用了bootmagic， 那么您还需要(看[Bootmagic文档](feature_bootmagic.md) 以及键盘信息，以了解如何执行此操作的详细信息).
diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md
new file mode 100644
index 000000000..4dba44c27
--- /dev/null
+++ b/docs/zh-cn/faq_debug.md
@@ -0,0 +1,136 @@
1# 调试的常见问题
2
3本篇详细介绍了人们在键盘故障排除时的各种常见问题。
4
5# 调试控制台
6
7## `hid_listen` 无法识别设备
8当设备的调试控制台未就绪时，您将看到如下内容：
9
10```
11Waiting for device:.........
12```
13
14插入设备后，*hid_listen*找到该设备，您将收到以下消息：
15
16```
17Waiting for new device:.........................
18Listening:
19```
20
21如果您无法获得这条“Listening:”消息，请尝试在[Makefile]中使用 `CONSOLE_ENABLE=yes`
22
23在Linux这样的操作系统上，你可能需要一些权限。
24- 使用`sudo hid_listen`
25
26## 控制台没有返回消息
27检查:
28- *hid_listen* 找到了你的设备。看前面。
29- 输入**Magic**+d打开调试。详见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands)。
30- 设置`debug_enable=true` ，一般存在于**matrix.c**的`matrix_init()`中。
31- 尝试使用'print'函数而不要用调试输出。详见**common/print.h**。
32- 断开其他有控制台功能的设备。 详见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97)。
33
34## Linux或UNIX这样的系统如何请求超级用户权限
35用'sudo'来执行*hid_listen*就有权限了。
36```
37$ sudo hid_listen
38```
39
40或者把一个文件放到规则文件夹来为TMK设备添加*udev规则*，不同系统的目录可能有所不同。
41
42文件: /etc/udev/rules.d/52-tmk-keyboard.rules(在Ubuntu系统的情况下)
43```
44# tmk keyboard products https://github.com/tmk/tmk_keyboard
45SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
46```
47
48***
49
50# 其他
51## 安全注意事项
52
53你应该不想要把你的键盘变成"砖头"吧，就是变成没法重写固件的那种。
54下面讲解一些参数来告诉你什么风险很大（其实也不是很大）。
55
56- 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。
57 按PCB上的RESET要拧开键盘底部。
58- 如果 tmk_core / common 里面的文件丢失键盘可能失灵。
59- .hex太大可能不太好; `make dfu` 会删除块，检验大小（咦?好像反了...）。
60 一但出错，刷新键盘失败的话就困在DFU出不去了。
61 - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672)
62
63```
64Linking: .build/planck_rev4_cbbrowne.elf [OK]
65Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
66
67Size after:
68 text data bss dec hex filename
69 0 22396 0 22396 577c planck_rev4_cbbrowne.hex
70```
71
72 - 上面那个文件大小是 22396/577ch，比28672/7000h小
73 - 当你有一个合适的.hex文件时，你就要重试加载那个了
74 - 您在键盘Makefile中的某些选项可能消耗额外内存；注意以下这几个
75 BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
76- DFU 工具/不/可以写入bootloader (unless you throw in extra fruit salad of options),
77 所以还是有点危险的
78- EEPROM大概有100000次循环寿命。不要总是频繁重写固件；EEPROM会玩坏的。
79## 全键无冲不好用
80首先你要在**Makefile**用如下命令编译固件`NKRO_ENABLE`。
81
82全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式，尤其是在BIOS中。
83
84
85## 指点杆需要复位电路(PS/2 鼠标支持)
86如果没有复位电路，由于硬件初始化不正确，您将得到不一致的结果。查看TPM754复位电路。
87
88- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
89- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
90
91
92## 矩阵不可读16以上的列
93当列超过16时[matrix.h]的`read_cols()`中，用`1UL<<16`而不要用`1<<16`。
94
95在C语言中`1` 是一个[int] 类型的[16 bit]值，在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型，比如`1UL`。
96
97https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
98
99## 特殊额外键不起作用(系统，音频控制键)
100你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。
101
102```
103EXTRAKEY_ENABLE = yes # 音频控制和系统控制
104```
105
106## 睡眠唤醒不好用
107
108在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。
109
110在主机睡眠时按下任何键都可以唤醒了。
111
112## 使用Arduino?
113
114**注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。
115
116- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
117- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
118
119Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。
120
121## USB 3 兼容性
122据传说有些人用USB3接口会有问题，用USB2的试试。
123
124
125## Mac 兼容性
126### OS X 10.11 和集线器
127https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
128
129
130## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题
131有人说他们的键盘在BIOS中，或许是恢复(睡眠和唤醒)后不工作.
132
133截止至目前，其根本原因未知，不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项，也试试其他的。
134
135https://github.com/tmk/tmk_keyboard/issues/266
136https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
diff --git a/docs/zh-cn/faq_general.md b/docs/zh-cn/faq_general.md
new file mode 100644
index 000000000..4949acb8c
--- /dev/null
+++ b/docs/zh-cn/faq_general.md
@@ -0,0 +1,19 @@
1# ��������
2
3## QMK��ʲô?
4
5[QMK](https://github.com/qmk), �����ӻ�е����(Quantum Mechanical Keyboard)����д����һȺ��Դ������Ϊ���Ƽ��̿����Ĺ��ߡ����Ǵ�[QMK�̼�](https://github.com/qmk/qmk_firmware)��ʼ������[TMK](https://github.com/tmk/tmk_keyboard)��ħ�ķֲ档
6
7### Ϊʲô������(Quantum)?
8
9<!-- ���޸� �����²ۣ��ĵ����߾�ȻҲ��֪��Ϊɶ������ -->
10
11## QMK��TMK��ʲô����?
12
13TMK�����[Jun Wako](https://github.com/tmk)��ƺ�ִ�С�QMKʼ��[Jack Humbert](https://github.com/jackhumbert)ΪPlanck���̴�����TMK�ֲ档һ��ʱ���Jack�ķֲ�ͺ�TMK��ȥ��Զ�ˣ�������2015�꣬Jack��������QMK��
14
15�Ӽ����۵�������QMK��TMK����һЩ�¹��ܶ��ɵġ�������QMK��չ�˿��õļ��룬ʹ�߼����ܽ�һ���ḻ���� `S()`, `LCTL()`, �� `MO()`��ȫ�������[����](keycodes.md).
16
17�ӹ��̵�������������TMK�Լ�ά�������йٷ�֧�ֵļ��̣�ֻ�к�Сһ��������֧�֡���������ά���Ѵ��ڷֲ��Ϊ�������̴����ķֲ档Ĭ��֧�ֺ��ٵļ��룬�����û�ͨ�����������˷������֡�QMK����ͨ�����й����ֿ�������ֺͼ��̣����ǻ�������з���������׼��PR����ͼ���ı�֤������ά����ͬʱQMKС��Ҳ���ڱ�Ҫʱ���������
18
19�����ַ����������ŵ��ȱ�㣬���Ҵ�����������ʱ��TMK��QMK֮������������
diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md
new file mode 100644
index 000000000..ff38f3889
--- /dev/null
+++ b/docs/zh-cn/faq_keymap.md
@@ -0,0 +1,151 @@
1# 布局常见问题
2
3本页本页包含人们经常遇到的关于布局的问题。如果你觉得没什么问题，请先看[布局概览](keymap.md)。
4
5## 我能用什么键码?
6看[键码](keycodes.md)你可以找到你能用的键码索引。可以的话这些链接可以连接到更广泛的文档。
7
8键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
9
10## 默认的键码什么样?
11
12世界上有三种标准键盘设计，分别是：ANSI, ISO, and JIS. 主要是北美用ANSI(译者注：中国很多键盘使用这个), 欧洲和非洲主要使用ISO，日本使用JIS。未提及的区域通常使用ANSI或ISO。与这些设计对应的键代码如下所示：
13
14<!-- 该图片的来源: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
15![键盘设计图](https://i.imgur.com/5wsh5wM.png)
16
17## 我有一些键变成了其他功能或者不工作了
18
19QMK有两个功能，Bootmagic和命令行，它允许您在运行中更改键盘的行为。该功能包括但不仅限于, 交换Ctrl/Caps，关闭界面，交换Alt/Gui，交换 Backspace/Backslash，禁用所有键，以及其他的行为改变。
20
21快速解决方法是插入键盘时按住`Space`+`Backspace`。该操作将重置已保存设置，让这些键回复初始功能。这招不好用的话参阅下方：
22
23* [Bootmagic](feature_bootmagic.md)
24* [命令](feature_command.md)
25
26## 菜单键不好用
27
28现在大多数键盘 `KC_RGUI`和`KC_RCTL`中间的键子叫做`KC_APP`。这是因为在这个键子发明之前相关标准里就已经有键叫做`MENU(菜单)`了，所以微软叫他`APP(应用)`键。
29
30## `KC_SYSREQ` 不工作
31使用抓屏的键码(`KC_PSCREEN`或`KC_PSCR`)而不用`KC_SYSREQ`。组合键'Alt + Print Screen'会被当作'System request'。
32
33见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)和
34* https://en.wikipedia.org/wiki/Magic_SysRq_key
35* https://en.wikipedia.org/wiki/System_request
36
37## 电源键不工作
38
39这有点让人困惑,QMK有两个"Power(电源)"键码: `KC_POWER` 在键盘/小键盘的HID使用页面中，`KC_SYSTEM_POWER` (或者叫`KC_PWR`)在用户页。
40
41前者只能被macOS识别，但是后者，即`KC_SLEP`和`KC_WAKE`三大主要操作系统全都支持，所以推荐使用这两个。Windows下这些键立即生效，macOS要长按直到弹出对话框。
42
43## 自动大小写锁定
44可以解决'the'问题(正常应为The)。我经常在输入'The'时不慎输入了'the'或者'THe'。自动大小写锁定可以修正此类问题。详见下方链接。
45https://github.com/tmk/tmk_keyboard/issues/67
46
47## 修改 键/层 卡住
48除非正确配置层切换，否则修改键或层可能会卡住。
49对于修改键和图层操作，必须把`KC_TRANS`放到目标层的相同位置，用于注销修改键或在释放事件时返回到上一层。
50* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
51* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
52* https://github.com/tmk/tmk_keyboard/issues/248
53
54
55## 机械自锁开关支持Mechanical Lock Switch Support
56
57本功能用于*机械自锁开关*比如[this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock)。你可以通过向`config.h`添加以下宏来使能该功能：
58
59```
60#define LOCKING_SUPPORT_ENABLE
61#define LOCKING_RESYNC_ENABLE
62```
63
64在使能该功能后，要在键盘中使用`KC_LCAP`, `KC_LNUM` 和 `KC_LSCR`这三个键码。
65
66远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。***
67
68## 输入ASCII之外的特殊字符比如Cédille 'Ç'
69
70请见[Unicode](feature_unicode.md)功能。
71
72## macOS上的`Fn`
73
74不像大多数FN键，苹果上那个有自己的键码...呃，基本上算吧。 他取缔了基本6键无冲HID报告的第六个键码 -- 所以苹果键盘其实是5键无冲的。
75
76技术上说QMK可以发送这个键。但是，这样做需要修改报告格式以添加FN键的状态。这还不是最糟糕的，你的键盘的VID和PID和真的苹果键盘不一样的话还不会被识别。
77QMK官方支持这个会被律师函的，所以就当我没说过。
78
79详见[issue#2179](https://github.com/qmk/qmk_firmware/issues/2179)。
80
81
82## Mac OSX的媒体控制键
83#### KC_MNXT 和 KC_MPRV 在Mac上不好用
84使用 `KC_MFFD`(`KC_MEDIA_FAST_FORWARD`) 和 `KC_MRWD`(`KC_MEDIA_REWIND`)，不要用 `KC_MNXT` 和 `KC_MPRV`.
85详见 https://github.com/tmk/tmk_keyboard/issues/195
86
87
88## Mac OSX中支持那些键?
89你可以从此源码中获知在OSX中支持哪些键码
90
91`usb_2_adb_keymap` 阵列映射 键盘/小键盘 页用于ADB扫描码(OSX内部键码).
92
93https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
94
95`IOHIDConsumer::dispatchConsumerEvent`会处理用户页面用法。
96<!--翻译问题：上面那两句翻译的不好-> handles Consumer page usages. -->
97https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
98
99
100## Mac OSX中的JIS键
101岛国特别键比如`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)`OSX是不是别的。You can use **Seil** to enable those keys, try following options.
102<!--翻译问题：以上“岛国特别键”没有任何地域歧视的意思 -->
103* 在电脑键盘上使能NFER键
104* 在电脑键盘上使能XFER键
105* 在电脑键盘上使能KATAKAN键
106
107https://pqrs.org/osx/karabiner/seil.html
108
109
110## RN-42蓝牙模块与Karabiner不能有效协同工作
111Karabiner - Mac OSX的改键软件 - 默认RN-42模块是不会被响应的。想要Karabiner和你的键盘协同工作你要使能此选项：
112https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
113
114此问题详见下方链接。
115https://github.com/tmk/tmk_keyboard/issues/213
116https://github.com/tekezo/Karabiner/issues/403
117
118
119## Esc 和 <code>&#96;</code> 双功能键
120
121请见[Grave Escape](feature_grave_esc.md)功能。
122
123## Mac OSX的弹出键
124`KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250
125似乎Windows10会忽略该键码，Linux/Xorg可以识别该键码但默认不映射。
126
127目前尚不清楚如何在真正的苹果键盘按出弹出键。HHKB使用`F20`用于弹出键(`Fn+f`)，该功能在MAC模式有效但不保证与苹果弹出键码相符。
128
129
130## `action_util.c`中的 `weak_mods`和`real_mods`是什么
131___待改善___
132
133real_mods 用于保存实际(物理)修改键的实际状态。
134weak_mods 用于保存虚拟或临时修改键，它将不会影响实际修改键。
135
136以按下左侧Shift键然后输入ACTION_MODS_KEY(LSHIFT, KC_A)为例，
137
138在weak_mods时，
139* (1) 按下不抬起左Shift: real_mods |= MOD_BIT(LSHIFT)
140* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT)
141* (3) 抬起 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
142real_mods 还是保持在修改状态。
143
144在没有weak_mods时，
145* (1) 按下不抬起左Shift: real_mods |= MOD_BIT(LSHIFT)
146* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT)
147* (3) 抬起 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
148此时real_mods失去‘实际左Shift’的状态。
149
150weak_mods和real_mods现已全部加入键盘数据包发送豪华套餐。
151https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
diff --git a/docs/zh-cn/getting_started_getting_help.md b/docs/zh-cn/getting_started_getting_help.md
new file mode 100644
index 000000000..8c0ebaa24
--- /dev/null
+++ b/docs/zh-cn/getting_started_getting_help.md
@@ -0,0 +1,15 @@
1# 获得帮助
2
3有很多方法来获得关于QMK的帮助.
4
5## 实时聊天
6
7你可以在我们的主要[Discord服务器](https://discord.gg/Uq7gcHh)找到QMK的开发者和用户。有很多讨论固件的不同频道, 工具箱(Toolbox), 硬件,配置工具(configurator).
8
9## OLKB Subreddit
10
11QMK的官方论坛是[/r/olkb](https://reddit.com/r/olkb) 在[reddit.com](https://reddit.com)上.
12
13## GitHub的Issue
14
15你可以在GitHub上 [提出issue](https://github.com/qmk/qmk_firmware/issues).当您的问题需要长期讨论或调试时，这尤其方便。
diff --git a/docs/zh-cn/getting_started_github.md b/docs/zh-cn/getting_started_github.md
new file mode 100644
index 000000000..b4e8e9fa5
--- /dev/null
+++ b/docs/zh-cn/getting_started_github.md
@@ -0,0 +1,64 @@
1# 如何在QMK中使用GitHub
2
3GitHub can be a little tricky to those that aren't familiar with it - this guide will walk through each step of forking, cloning, and submitting a pull request with QMK.
4
5?> 本教程假设您已安装GitHub，并且您喜欢使用命令行工作。
6
7首先 [GitHub上的QMK页面](https://github.com/qmk/qmk_firmware), 您能看到右上方有个按钮写着"Fork":
8
9![从GitHub上分叉](https://i.imgur.com/8Toomz4.jpg)
10
11如果你是某组织成员，你将需要选择分叉到哪个账户。一般情况下, 你是想要分叉到你的私人账户下。当你完成分叉 (有时需要等一会), 点击"Clone or Download" 按钮:
12
13!从GitHub下载](https://i.imgur.com/N1NYcSz.jpg)
14
15你要选择 "HTTPS", 然后选择链接复制:
16
17![HTTPS链接](https://i.imgur.com/eGO0ohO.jpg)
18
19然后，在命令行输入`git clone --recurse-submodules `，然后粘贴你的链接:
20
21```
22user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
23Cloning into 'qmk_firmware'...
24remote: Enumerating objects: 9, done.
25remote: Counting objects: 100% (9/9), done.
26remote: Compressing objects: 100% (5/5), done.
27remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
28Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
29Resolving deltas: 100% (119972/119972), done.
30...
31Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
32Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
33Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
34Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
35```
36
37现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出（pull）你的改变，像这样:
38
39```
40user@computer:~$ git add .
41user@computer:~$ git commit -m "adding my keymap"
42[master cccb1608] adding my keymap
43 1 file changed, 1 insertion(+)
44 create mode 100644 keyboards/planck/keymaps/mine/keymap.c
45user@computer:~$ git push
46Counting objects: 1, done.
47Delta compression using up to 4 threads.
48Compressing objects: 100% (1/1), done.
49Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done.
50Total 1 (delta 1), reused 0 (delta 0)
51remote: Resolving deltas: 100% (1/1), completed with 1 local objects.
52To https://github.com/whoeveryouare/qmk_firmware.git
53 + 20043e64...7da94ac5 master -> master
54```
55
56现在你的改动已经在你GitHub上的分支中了 - 如果你回到这 (`https://github.com/你的GitHub账户名/qmk_firmware`) ,你可以点击下方所示按钮创建 "New Pull Request":
57
58![新的 Pull Request](https://i.imgur.com/DxMHpJ8.jpg)
59
60现在你可以看到你所做的一切 - 如果看起来不错, 就可以点击 "Create Pull Request"定稿了:
61
62![创建Pull Request](https://i.imgur.com/Ojydlaj.jpg)
63
64提交后,我们会开跟你说你的改动,要求您进行更改, 并最终接受您的更改!感谢您为QMK做的贡献 :)
diff --git a/docs/zh-cn/getting_started_introduction.md b/docs/zh-cn/getting_started_introduction.md
new file mode 100644
index 000000000..b977b6339
--- /dev/null
+++ b/docs/zh-cn/getting_started_introduction.md
@@ -0,0 +1,54 @@
1# 介绍
2
3本页解释了使用QMK项目所需的基本信息。它假定您能熟练使用Unix shell，但您不熟悉C语言也不熟悉使用make编译。
4
5## 基本QMK结构
6
7QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk_core` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。
8
9### 用户空间结构
10
11在`users`文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。详见[用户空间特性](feature_userspace.md)
12
13### 键盘项目结构
14
15在`keyboards`文件夹和他的子文件夹`handwired`中就是各个键盘的项目了，比如`qmk_firmware/keyboards/clueboard`。内部结构与如下:
16
17* `keymaps/`: 可以构建的不同布局
18* `rules.mk`: 用来设置 "make" 命令默认选项的文件。别直接编辑这个文件,你应该使用具体某个布局的 `rules.mk`.
19* `config.h`: 用于设置默认编译选项的文件。别直接编辑这个文件, 你应该使用具体某个布局的 `config.h`.
20
21### 布局结构
22
23在各个布局的文件夹，你能找到以下文件。只有 `keymap.c` 是必要的, 如果其他文件找不到就会直接选择默认选项。
24
25* `config.h`: 配置布局的选项
26* `keymap.c`: 布局的全部代码, 必要文件
27* `rules.mk`: 使能的QMK特性
28* `readme.md`:介绍你的布局,告诉别人怎么使用，附上功能说明。请将图片上传到imgur等图床（译者注：imgur可能已被墙，为了方便国人访问，建议使用国内可以直接访问的图床）。
29
30# `config.h` 文件
31
32有三个重要的`config.h` 位置:
33
34* 键盘 (`/keyboards/<keyboard>/config.h`)
35* 用户空间 (`/users/<user>/config.h`)
36* 布局 (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
37
38构建系统按照上述顺序自动获取配置文件。如果要覆盖由上一个 `config.h` 所做的设置，您需要首先为要更改的设置包含一些样板代码。
39
40```
41#pragma once
42```
43
44要覆盖上一个 `config.h` 所做的设置，你要先 `#undef` 然后再 `#define` 这个设置.
45
46样板代码和设置看起来像这样：
47
48```
49#pragma once
50
51// 像下面那样覆盖设置（MY_SETTING指的是你要覆盖的设置项）!
52#undef MY_SETTING
53#define MY_SETTING 4
54```
diff --git a/docs/zh-cn/newbs.md b/docs/zh-cn/newbs.md
new file mode 100644
index 000000000..eca8c14e5
--- /dev/null
+++ b/docs/zh-cn/newbs.md
@@ -0,0 +1,23 @@
1# QMK菜鸟教程
2
3QMK是为你机械硬盘设计的的一个强大的开源固件。使用QMK可以很简单的让你的定制键盘变得强大。看完这篇文章，无论你是菜鸟还是大佬，都可以顺利的使用QMK来定制键盘。
4
5你是否为不知道你的键盘能不能运行QMK而苦恼? 如果你的机械键盘是你自己做的，那么这把键盘一般可以运行QMK。我们提供了[一大堆自制键盘](https://qmk.fm/keyboards/), 所以即便你的键盘不能运行QMK你也很容易能找到满足你需求的键盘。
6
7## 概览
8
9这个教程有7个主要部分：
10
11* [新手上路](newbs_getting_started.md)
12* [用命令行构建你的第一个固件](newbs_building_firmware.md)
13* [用在线界面构建你的第一个固件](newbs_building_firmware_configurator.md)
14* [刷新固件](newbs_flashing.md)
15* [测试和调试](newbs_testing_debugging.md)
16* [Git最佳实践](newbs_best_practices.md)
17* [其他学习资源](newbs_learn_more_resources.md)
18
19这份教程旨在帮助没有固件构建经验的人，也是根据该目的做出选择和建议。这些程序有很多替代方法，大部分替代我们都支持。如果你对完成一个任务有疑问，可以[向我们寻求帮助](getting_started_getting_help.md).
20
21## 其他资源
22
23* [Thomas Baart的 QMK基础博客](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 这是一个用户创建的博客，涵盖了为新手准备的使用QMK的基础知识。
diff --git a/docs/zh-cn/newbs_best_practices.md b/docs/zh-cn/newbs_best_practices.md
new file mode 100644
index 000000000..fa58dc75e
--- /dev/null
+++ b/docs/zh-cn/newbs_best_practices.md
@@ -0,0 +1,163 @@
1# 最佳实践
2
3## 或者说, "我应如何学会不再担心并开始爱上Git。"
4
5本文档旨在指导新手以最佳方式获得为QMK做出贡献的丝滑体验。我们将介绍为QMK做出贡献的过程，详细介绍使这项任务更容易的一些方法，然后我们将制造一些问题，来教你如何解决它们。
6
7本文假设了一些内容:
8
91. 一有个GitHub账户, 并[创建qmk_firmware仓库分叉](getting_started_github.md)到你的帐户.
102. 你已经[建立你的构建环境](newbs_getting_started.md?id=environment-setup).
11
12
13## 你分叉的主分支: 一直在上传，但不要提交
14
15十分推荐您在QMK开发过程中无论开发是否完成都要保持你的 `master` 分支更新，但是 ***一定不要*** 提交。相反，你应该在一个开发分叉中做出你所有修改并在开发时提交pull request。
16
17减少合并冲突的可能性 &mdash; 两个或多个用户同时编辑文件的同一部分的实例 &mdash; 保持 `master` 分支最新，并创建一个新的分支来开始新的开发。
18
19### 更新你的主分支
20
21保持你的 `master` 更新, 推荐你添加QMK Firmware仓库作为Git的远程仓库，想这么做的话, 你可以打开你的Git命令行接口然后输入:
22
23```
24git remote add upstream https://github.com/qmk/qmk_firmware.git
25```
26
27运行 `git remote -v`, 来确定这个仓库已经添加，以下是回显:
28
29```
30$ git remote -v
31origin https://github.com/<your_username>/qmk_firmware.git (fetch)
32origin https://github.com/<your_username>/qmk_firmware.git (push)
33upstream https://github.com/qmk/qmk_firmware.git (fetch)
34upstream https://github.com/qmk/qmk_firmware.git (push)
35```
36
37现在添加已完成，你可以用`git fetch upstream`来检查仓库的更新. 这会检索branches 和 tags &mdash; 统称为"refs" &mdash; 从QMK仓库, 也就是 `upstream`。我们可以比较我们的分叉和QMK的 `origin` 数据的不同。
38
39要更新你的分叉的主分支，请运行以下命令，在每行之后按Enter键:
40
41```
42git checkout master
43git fetch upstream
44git pull upstream master
45git push origin master
46```
47
48这回切换到你的`master` 分支, 检索你QMK仓库的refs, 下载当前QMK `master` 分支到你的电脑, 并上传到你的分叉.
49
50### 做改动
51
52你可以输入以下命令来创建一个新的分支来做改动:
53
54```
55git checkout -b dev_branch
56git push --set-upstream origin dev_branch
57```
58
59这回建立一个叫做 `dev_branch`的新分支, 检查一下, 然后想你的分叉保存分支. 使用 `--set-upstream` 参数来告诉git使用你的分叉并且当每次你对你的分支用`git push` 或 `git pull`时要使用`dev_branch`。 它仅需要在第一次push的时候使用；然后你就可以很安全的用 `git push` 或 `git pull`, 并不需要其他参数了。
60
61!> 使用 `git push`, 你可以用 `-u` 来代替 `--set-upstream` &mdash; `-u`是`--set-upstream`的简写。
62
63您可以将您的分支命名为您想要的任何名称，但建议将其命名为与您要进行的更改相关的内容。
64
65默认情况下 `git checkout -b` 在已经检出的分支上建立新的分支。您可以将新的分支建立在未检出的现有分支的基础上，方法是将现有分支的名称添加到命令：
66
67```
68git checkout -b dev_branch master
69```
70
71现在您已经有了一个开发分支，那么就打开您的文本编辑器并进行您需要做的任何更改。建议对您的分支进行许多小的提交；这样，任何引起问题的更改都可以在需要时更容易地跟踪和撤消。要进行更改，编辑并保存任何需要更新的文件，请将它们添加到Git的 *staging area* ，然后将它们提交到您的分支：
72
73```
74git add path/to/updated_file
75git commit -m "My commit message."
76```
77
78` git add`添加已更改到Git的*临时区域*也就是Git的“加载区域”的文件。其中包含使用 `git commit` 命令 *提交* 的并已经保存到仓库的更改。建议您使用描述性的提交消息，这样您就可以一目了然地知道更改了什么。
79
80!> 如果你修改了很多文件，但所有的文件都是同一个更改的一部分，你可以用 `git add .` 来添加当前目录中所有已更改的文件而不是单独添加每个文件.
81
82### 发布更改
83
84最后一步是将更改推送到您的分叉。 输入 `git push`来推送. 现在Git将`dev_branch`的当前状态发布到您的分叉。
85
86
87## 解决合并冲突
88
89有时，当您在某个分支中的工作需要很长时间才能完成时，其他人所做的更改与您在打开pull request时对该分支所做的更改相冲突。这称为*rebase* 即合并冲突，当多个人编辑同一文件的同一部分时会发生这种情况。
90
91### 重新调整您的更改
92
93*rebase*是Git的一种方法，它获取在某一点上应用的更改，撤销它们，然后将相同的更改应用到另一点。在合并冲突的情况下，您可以重新设置您的分支以获取在创建分支时和当前时间之间的那段时间所做的更改。
94
95运行以下命令来开始：
96
97```
98git fetch upstream
99git rev-list --left-right --count HEAD...upstream/master
100```
101
102 这里的`git rev-list` 命令返回当前分支和qmk的主分支之间不同的提交数。我们首先运行`git fetch`，以确保我们有代表upstream仓库的refs。 `git rev-list` 命令的回显有两个数字：
103
104```
105$ git rev-list --left-right --count HEAD...upstream/master
1067 35
107```
108
109第一个数字表示自创建以来当前分支的提交数, 第二个数字是自创建当前分支以来对 `upstream/master` 进行的提交数, 因此, 当前分支中未记录变动。
110
111既然知道当前分支和upstream仓库的当前状态，我们可以开始一个rebase操作：
112
113```
114git rebase upstream/master
115```
116
117这就是让Git撤销当前分支上的提交，然后根据QMK的主分支重新应用它们。
118
119```
120$ git rebase upstream/master
121First, rewinding head to replay your work on top of it...
122Applying: Commit #1
123Using index info to reconstruct a base tree...
124M conflicting_file_1.txt
125Falling back to patching base and 3-way merge...
126Auto-merging conflicting_file_1.txt
127CONFLICT (content): Merge conflict in conflicting_file_1.txt
128error: Failed to merge in the changes.
129hint: Use 'git am --show-current-patch' to see the failed patch
130Patch failed at 0001 Commit #1
131
132Resolve all conflicts manually, mark them as resolved with
133"git add/rm <conflicted_files>", then run "git rebase --continue".
134You can instead skip this commit: run "git rebase --skip".
135To abort and get back to the state before "git rebase", run "git rebase --abort".
136```
137
138这告诉我们有一个合并冲突，并给出带有冲突的文件的名称。在文本编辑器中打开冲突的文件，在该文件的某个位置，您会发现如下内容：
139
140```
141<<<<<<< HEAD
142<p>For help with any issues, email us at [email protected].</p>
143=======
144<p>Need help? Email [email protected].</p>
145>>>>>>> Commit #1
146```
147
148 `<<<<<<< HEAD`行标记合并冲突的开始, `>>>>>>> Commit #1` 行标记结束, 冲突选项被 `=======`分隔。`HEAD`那端的部分来自文件的qmk master版本，标记有commit消息的部分来自当前的分支持和提交。
149
150因为Git跟踪 *对文件的更改* 而不是直接跟踪文件的内容，所以如果Git在提交之前找不到文件中的文本，它将不知道如何编辑该文件。重新编辑文件将解决冲突。进行更改，然后保存文件。
151
152```
153<p>Need help? Email [email protected].</p>
154```
155
156现在运行:
157
158```
159git add conflicting_file_1.txt
160git rebase --continue
161```
162
163Git记录对冲突文件的更改，并继续应用来自我们的分支的提交，直到它到达末尾。
diff --git a/docs/zh-cn/newbs_building_firmware.md b/docs/zh-cn/newbs_building_firmware.md
new file mode 100644
index 000000000..fc43583c2
--- /dev/null
+++ b/docs/zh-cn/newbs_building_firmware.md
@@ -0,0 +1,81 @@
1# 构建第一个固件
2
3现在您已经建立了构建环境，就可以开始构建自定义固件了。对于本指南的这一部分，我们将在3个程序之间切换——文件管理器、文本编辑器和终端窗口。请保持所有3个程序打开，直到您完成并对键盘固件满意。
4
5如果您在按照指南第一部分的操作之后关闭并重新打开了终端窗口，请不要忘记输入“cd qmk_firmware”，来使您的终端位于正确的目录。
6
7## 导航到您的keymaps文件夹
8
9首先导航到键盘的 `keymaps` 文件夹.
10
11?> 如果您使用的是MacOS或Windows，可以使用以下命令轻松地打开keymaps文件夹。
12
13?> macOS:
14
15 open keyboards/<keyboard_folder>/keymaps
16
17?> Windows:
18
19 start .\\keyboards\\<keyboard_folder>\\keymaps
20
21## 创建`default` 布局副本
22
23打开`keymaps`文件夹后，您将需要创建`default`文件夹的副本。我们强烈建议您将文件夹命名为与GitHub用户名相同的名称，但您也可以使用任何您想使用的名称，只要它只包含小写字母、数字和下划线字符。
24
25要自动执行此过程，您还可以选择运行`new_keymap.sh`脚本。
26
27导航到`qmk_firmware/util` 目录然后输入以下命令：
28
29```
30./new_keymap.sh <keyboard path> <username>
31```
32
33例如，一个名字叫ymzcdg的用户要创建1up60hse的布局，他需要输入
34
35```
36./new_keymap.sh 1upkeyboards/1up60hse ymzcdg
37```
38
39## 在你最钟爱的文本编辑器中打开`keymap.c`
40
41打开你的`keymap.c`. 在这个文件中，您可以找到控制键盘行为的结构。 在你的`keymap.c` 的顶部有一些让布局更易读的define和enum。在靠下的位置你会找到一行和下面这句很像的:
42
43 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
44
45从这一行开始便是层列表。这行下面你会看到包括 `LAYOUT` 或 `KEYMAP`这两个词的几行, 从这些行开始就是层。在这一行下面是组成该特定层的键的列表。
46
47!> 编辑您的keymap文件时，注意不要添加或删除任何逗号。如果这样做，您将阻止您的固件编译，并且您可能不容易找出多余的或缺少的逗号在哪里。
48
49## 根据您的喜好自定义布局
50
51如何完成这一步骤完全取决于您。改变一直困扰着你的问题，或者完全重做所有的事情。如果您不需要全部图层，可以删除图层，或者将图层总数增加到32个。查看以下文档，了解可以在此处定义的内容:
52
53* [键码](keycodes.md)
54* [特性](features.md)
55* [问题与解答](faq.md)
56
57?> 当你明白布局是怎么工作时，您也要让每次改变尽可能小。一次改变很大在调试时找出问题会十分困难。
58
59## 构建你的固件
60
61完成对布局的更改后，您就要构建固件了。为此，请返回终端窗口并运行build命令:
62
63 make <my_keyboard>:<my_keymap>
64
65例如，如果您的keymap名为“xyverz”，并且您正在为rev5 planck构建一个keymap，那么您将使用此命令：
66
67 make planck/rev5:xyverz
68
69在编译过程中，你将看到屏幕上有很多输出，通知您正在编译哪些文件他应该以与下文类似的输出结束:
70
71```
72Linking: .build/planck_rev5_xyverz.elf [OK]
73Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
74Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
75Checking file size of planck_rev5_xyverz.hex [OK]
76 * File size is fine - 18392/28672
77```
78
79## 刷新你的固件
80
81请移步 [Flashing Firmware](newbs_flashing.md) 来继续。
diff --git a/docs/zh-cn/newbs_flashing.md b/docs/zh-cn/newbs_flashing.md
new file mode 100644
index 000000000..05a9eb55e
--- /dev/null
+++ b/docs/zh-cn/newbs_flashing.md
@@ -0,0 +1,307 @@
1# 刷新你的键盘
2
3现在您已经构建了一个自定义固件文件，那么您就需要刷新键盘了。
4
5## 用QMK工具箱刷新键盘
6
7刷新键盘的最简单方法是使用[QMK 工具箱](https://github.com/qmk/qmk_toolbox/releases).
8
9但是，QMK工具箱目前仅适用于Windows和MacOS。如果您使用的是Linux（或者只是希望从命令行刷新固件），则必须使用 [方法概述](newbs_flashing.md#flash-your-keyboard-from-the-command-line).
10
11### 将文件加载到QMK工具箱中
12
13首先打开QMK工具箱应用程序。您将要在访达或资源管理器中找到固件文件。您的键盘固件可能是两种格式之一`.hex`或`.bin`。qmk会尝试将键盘的相应文件复制到“qmk_firmware”根目录中。
14
15?> 如果您在Windows或MacOS上，可以使用以下命令轻松地在资源管理器或访达中打开当前固件文件夹。
16
17?> Windows:
18
19 start .
20
21?> macOS:
22
23 open .
24
25固件文件始终遵循此命名格式:
26
27 <keyboard_name>_<keymap_name>.{bin,hex}
28
29例如，使用 `default` 布局的 `plank/rev5` 将使用以下名字：
30
31 planck_rev5_default.hex
32
33找到固件文件后，将其拖到QMK工具箱中的“Local file”框中，或单击“Open”并导航到固件文件的存储位置。
34
35### 将键盘置于DFU（Bootloader）模式
36
37要刷新自定义固件，您必须将键盘置于特殊的刷新模式。在此模式下，您将无法键入或使用键盘。在写入固件时，不要拔下键盘插头或以其他方式中断刷新过程，这一点非常重要。
38
39不同的键盘有不同的方式进入这种特殊模式。如果您的键盘当前运行的是QMK或TMK，而您没有得到特定的指示，请按顺序尝试以下操作:
40
41* 按住两个shift键并按 `Pause`
42* 按住两个shift键并按 `B`
43* 拔下键盘插头, 同时按住空格键和 `B` , 插上键盘然后等一会再放开按键
44* 按下PCB底部的 `RESET` 物理键
45* 找到PCB上标记有 `BOOT0` 或 `RESET`的金属点, 在插入PCB的同时短接它们
46
47成功后，您将在QMK工具箱中看到类似以下内容的消息:
48
49```
50*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
51*** DFU device connected
52```
53
54### 刷新你的键盘
55
56单击QMK工具箱中的 `Flash` 按钮。您将看到类似以下内容的输出:
57
58```
59*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
60*** DFU device connected
61*** Attempting to flash, please don't remove device
62>>> dfu-programmer atmega32u4 erase --force
63 Erasing flash... Success
64 Checking memory from 0x0 to 0x6FFF... Empty.
65>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
66 Checking memory from 0x0 to 0x55FF... Empty.
67 0% 100% Programming 0x5600 bytes...
68 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
69 0% 100% Reading 0x7000 bytes...
70 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
71 Validating... Success
72 0x5600 bytes written into 0x7000 bytes memory (76.79%).
73>>> dfu-programmer atmega32u4 reset
74
75*** DFU device disconnected
76*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
77```
78
79## 使用命令行刷新键盘
80
81首先，您需要知道您的键盘使用的是哪个bootloader。通常是以下四个常见的bootloader。Pro-Micro 和 clones 使用 CATERINA, Teensy 使用 Halfkay, OLKB 键盘使用 QMK-DFU, 其他的atmega32u4芯片使用DFU。
82
83您可以在以下文章中了解更多关于bootloader[刷新指令和Bootloader信息](flashing.md)。
84
85如果您知道正在使用的bootloader是哪种，那么在编译固件时，可以向“make”命令里添加一些额外参数，以自动执行刷新过程。
86
87### DFU
88
89对于DFU引导加载程序，当您准备好编译和刷新固件时，打开终端窗口并运行构建命令:
90
91 make <my_keyboard>:<my_keymap>:dfu
92
93例如，如果您的布局名为“xyverz”，并且您正在为rev5 planck构建一个布局，那么您可以使用此命令：
94
95 make planck/rev5:xyverz:dfu
96
97编译完成后，应输出以下内容：
98
99```
100Linking: .build/planck_rev5_xyverz.elf [OK]
101Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
102Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
103Checking file size of planck_rev5_xyverz.hex
104 * File size is fine - 18574/28672
105 ```
106
107到了这个时候, 构建脚本将每隔5秒查找一次DFU。它将重复以下操作，直到找到设备或将其取消。
108
109 dfu-programmer: no device present.
110 Error: Bootloader not found. Trying again in 5s.
111
112一旦出现以上回显，您将需要重置控制器。然后，它应该显示与以下类似的输出：
113
114```
115*** Attempting to flash, please don't remove device
116>>> dfu-programmer atmega32u4 erase --force
117 Erasing flash... Success
118 Checking memory from 0x0 to 0x6FFF... Empty.
119>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
120 Checking memory from 0x0 to 0x55FF... Empty.
121 0% 100% Programming 0x5600 bytes...
122 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
123 0% 100% Reading 0x7000 bytes...
124 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
125 Validating... Success
126 0x5600 bytes written into 0x7000 bytes memory (76.79%).
127>>> dfu-programmer atmega32u4 reset
128```
129
130如果您对此有任何问题，您可能需要这样做：
131
132 sudo make <my_keyboard>:<my_keymap>:dfu
133
134#### DFU命令
135
136有许多DFU命令可用于将固件下载到DFU设备：
137
138* `:dfu` - 这是正常选项，等待DFU设备可用，然后刷新固件。这将每隔5秒检查一次，以查看是否出现了DFU设备。
139* `:dfu-ee` - 这将刷新一个`eep`文件，而不是普通的十六进制文件。这很不常见。
140* `:dfu-split-left` - 这将刷新正常固件，就像默认选项 (`:dfu`)一样. 但是，这也会刷新“左侧”EEPROM文件，用于分割键盘。 _这是基于Elite C的键盘的推荐选择。_
141* `:dfu-split-right` - 这将刷新正常固件，就像默认选项(`:dfu`). 但是，这也会刷新“右侧”EEPROM文件，用于分割键盘。 _这是基于Elite C的键盘的推荐选择。_
142
143
144### Caterina
145
146对于Arduino板以及其克隆版来说(比如SparkFun和ProMicro), 准备好编译和刷新固件后，打开终端窗口并运行构建命令:
147
148 make <my_keyboard>:<my_keymap>:avrdude
149
150比如, 你的布局叫"xyverz"你要创建一个rev2 Lets Split的布局,你要用以下命令:
151
152 make lets_split/rev2:xyverz:avrdude
153
154固件完成编译后，它将输出类似以下的内容:
155
156```
157Linking: .build/lets_split_rev2_xyverz.elf [OK]
158Creating load file for flashing: .build/lets_split_rev2_xyverz.hex [OK]
159Checking file size of lets_split_rev2_xyverz.hex [OK]
160 * File size is fine - 27938/28672
161Detecting USB port, reset your controller now..............
162```
163
164此时，复位，然后脚本将检测bootloader，然后刷新固件。输出应该像这样:
165
166```
167Detected controller on USB port at /dev/ttyS15
168
169Connecting to programmer: .
170Found programmer: Id = "CATERIN"; type = S
171 Software Version = 1.0; No Hardware Version given.
172Programmer supports auto addr increment.
173Programmer supports buffered memory access with buffersize=128 bytes.
174
175Programmer supports the following devices:
176 Device code: 0x44
177
178avrdude.exe: AVR device initialized and ready to accept instructions
179
180Reading | ################################################## | 100% 0.00s
181
182avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
183avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
184 To disable this feature, specify the -D option.
185avrdude.exe: erasing chip
186avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
187avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
188avrdude.exe: writing flash (27938 bytes):
189
190Writing | ################################################## | 100% 2.40s
191
192avrdude.exe: 27938 bytes of flash written
193avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
194avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
195avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
196avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
197avrdude.exe: reading on-chip flash data:
198
199Reading | ################################################## | 100% 0.43s
200
201avrdude.exe: verifying ...
202avrdude.exe: 27938 bytes of flash verified
203
204avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
205
206avrdude.exe done. Thank you.
207```
208如果您对此有任何问题，您可能需要这样做：
209
210 sudo make <my_keyboard>:<my_keymap>:avrdude
211
212
213此外，如果要刷新多个板，请使用以下命令：
214
215 make <keyboard>:<keymap>:avrdude-loop
216
217当你完成了刷新后，你需要按下ctrl+c或者其他正确的按键来让你的操作系统终止循环。
218
219
220## HalfKay
221
222对于PJRC设备（Teensy），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令:
223
224 make <my_keyboard>:<my_keymap>:teensy
225
226比如, 如果你的布局叫做"xyverz"你想创建Ergodox or Ergodox EZ的布局,你要使用以下命令:
227
228 make erdogox_ez:xyverz:teensy
229
230固件完成编译后，它将输出如下内容：
231
232```
233Linking: .build/ergodox_ez_xyverz.elf [OK]
234Creating load file for flashing: .build/ergodox_ez_xyverz.hex [OK]
235Checking file size of ergodox_ez_xyverz.hex [OK]
236 * File size is fine - 25584/32256
237 Teensy Loader, Command Line, Version 2.1
238Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
239Waiting for Teensy device...
240 (hint: press the reset button)
241 ```
242
243此时，复位键盘。完成后，您将看到如下输出：
244
245 ```
246 Found HalfKay Bootloader
247Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
248Programming............................................................................................................................................................................
249...................................................
250Booting
251```
252
253## STM32 (ARM)
254
255对于大多数ARM板（包括Proton C、Planck Rev 6和Preonic Rev 3），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令：
256
257 make <my_keyboard>:<my_keymap>:dfu-util
258
259例如，如果您的keymap被命名为“xyverz”，并且您正在为Planck Revision 6键盘构建一个布局，那么您需要使用以下命令，然后将键盘重新启动到bootloader（在完成编译之前）：
260
261 make planck/rev6:xyverz:dfu-util
262
263固件完成编译后，它将输出如下内容：
264
265```
266Linking: .build/planck_rev6_xyverz.elf [OK]
267Creating binary load file for flashing: .build/planck_rev6_xyverz.bin [OK]
268Creating load file for flashing: .build/planck_rev6_xyverz.hex [OK]
269
270Size after:
271 text data bss dec hex filename
272 0 41820 0 41820 a35c .build/planck_rev6_xyverz.hex
273
274Copying planck_rev6_xyverz.bin to qmk_firmware folder [OK]
275dfu-util 0.9
276
277Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
278Copyright 2010-2016 Tormod Volden and Stefan Schmidt
279This program is Free Software and has ABSOLUTELY NO WARRANTY
280Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
281
282Invalid DFU suffix signature
283A valid DFU suffix will be required in a future dfu-util release!!!
284Opening DFU capable USB device...
285ID 0483:df11
286Run-time device DFU version 011a
287Claiming USB DFU Interface...
288Setting Alternate Setting #0 ...
289Determining device status: state = dfuERROR, status = 10
290dfuERROR, clearing status
291Determining device status: state = dfuIDLE, status = 0
292dfuIDLE, continuing
293DFU mode device DFU version 011a
294Device returned transfer size 2048
295DfuSe interface name: "Internal Flash "
296Downloading to address = 0x08000000, size = 41824
297Download [=========================] 100% 41824 bytes
298Download done.
299File downloaded successfully
300Transitioning to dfuMANIFEST state
301```
302
303## 试一试吧!
304
305恭喜您! 您的自定义固件已经刷写到您的键盘
306
307试一试，确保一切按你想的方式进行。我们写了[测试和调试](newbs_testing_debugging.md)来完善新手引导。 因此，请前往那里了解如何排除自定义功能的故障。
diff --git a/docs/zh-cn/newbs_getting_started.md b/docs/zh-cn/newbs_getting_started.md
new file mode 100644
index 000000000..596ab78f7
--- /dev/null
+++ b/docs/zh-cn/newbs_getting_started.md
@@ -0,0 +1,102 @@
1# 介绍
2
3你的电脑键盘里面包含一个处理器, 这个处理器和你电脑里面的不太一样。这个处理器负责运行一些特殊的软件，这些软件可以监测按钮按下并将按钮处于按下还是释放状态的数据发送出去。QMK就是这样一种软件，即监测按钮被按下并发送这样的信息到作为主机的计算机上。当你创建了你的布局, 你也就创建了你的键盘运行的的可执行程序。
4
5QMK试图通过使简单的事情变得更简单，使使不可能成为可能来把大量的权力交给你。你不需要懂如何通过程序创建强大的布局——你只需要遵循简单的语法规则。
6
7# 新手上路
8
9在你能创建布局前,你要安装一些软件来建立你的开发环境。无论你想编译多少固件，这个操作都只需要进行一次。
10
11如果您更喜欢图形化界面, 请考虑使用在线工具[QMK配置器](https://config.qmk.fm)。 请参考 [使用在线GUI构建您的第一个固件](newbs_building_firmware_configurator.md)。
12
13
14## 下载软件
15
16### 文本编辑器
17
18你需要一个可以编辑 **纯文本** 文件的程序。在Windows上你可以用Notepad, 在Linux上使用gedit，这两个都是简单又实用的文本编辑工具。 在macOS上, 请小心使用 “文本编辑” 这个默认软件: 如果你不明确的选择_格式_菜单中的 _制作纯文本_ 的话文本将不会被保存为纯文本。
19
20你也可以下载并安装一个专用编辑器 [Sublime Text](https://www.sublimetext.com/) 或 [VS Code](https://code.visualstudio.com/)。 这大概是跨平台的最好方法了, 这些编辑器是专门为了编辑代码设计的。
21
22?>搞不清用哪种编辑器? Laurence Bradford 写了篇关于编辑器选择的文章 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/)。
23
24### QMK 工具箱
25
26QMK 工具箱 是一种可选的Windows和macOS下的图形化工具，它可以对你的定制键盘进行编程和调试。你可能会发现它就是你能简单的刷新你的键盘固件并查看调试信息的稀世珍宝。
27
28[在这里下载最新发布版本](https://github.com/qmk/qmk_toolbox/releases/latest)
29
30* Windows用户: `qmk_toolbox.exe` (绿色版) 或 `qmk_toolbox_install.exe` (安装版)
31* macOS用户: `QMK.Toolbox.app.zip` (绿色版) or `QMK.Toolbox.pkg` (安装版)
32
33## 建立你的环境
34
35我们为了使QMK环境变得更容易建立已竭尽所能。你只需要准备Linux 或 Unix 环境, 然后让QMK安装剩余部分。
36
37?> 如果你从未使用过Linux/Unix的命令行,有一些你需要学习的基础概念和命令，以下资料将教会您使用QMK环境的必要能力:<br>
38[必会Linux命令](https://www.guru99.com/must-know-linux-commands.html)<br>
39[一些基本的Unix命令](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
40
41### Windows
42
43你需要安装MSYS2和Git.
44
45* 按照以下安装说明进行操作[MSYS2 主页](https://www.msys2.org)。
46* 关闭所有打开的MSYS2终端并打开新的MSYS2 MinGW 64-bit终端。
47* 使用以下命令安装Git: `pacman -S git`。
48
49### macOS
50
51你需要安装Homebrew。按照以下说明进行操作 [Homebrew 主页](https://brew.sh)。
52
53在Homebrew安装完成后, 继续 _同步QMK工程_. 这一步你将会通过运行一个脚本安装其他包。
54
55### Linux
56
57你将需要安装Git.你很有可能已经安装,但若你尚未安装,可以使用以下命令进行安装:
58
59* Debian / Ubuntu / Devuan: `apt-get install git`
60* Fedora / Red Hat / CentOS: `yum install git`
61* Arch: `pacman -S git`
62
63?> 无论你使用哪种平台，Docker都可以是你的选择[点这里进一步了解](getting_started_build_tools.md#docker)
64
65## 同步QMK工程
66
67当你建立Linux/Unix环境后,你就已经可以下载QMK了.下载时我们可以用Git来 "clone" QMK仓库. 打开一个终端或MSYS2 MinGW 窗口，在阅读剩余的指南时请保持窗口打开。在窗口里面运行以下两句命令:
68
69```shell
70git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
71cd qmk_firmware
72```
73
74?> 如果您已经知道[如何使用GitHub](getting_started_github.md), 我们推荐您创建您自己的分支并克隆。 如果您不知道这是什么, 您完全可以忽略这句无关紧要的话。
75
76QMK附带一个脚本，可帮助您设置剩余的所需内容.您可以通过输入此命令来运行它:
77
78 util/qmk_install.sh
79
80## 测试你的开发环境
81
82现在你的QMK环境已经建立完毕, 你可以为你的键盘创建固件了。开始试着创建键盘的默认固件吧。 你需要使用以下格式的命令创建固件:
83
84 make <keyboard>:default
85
86比如, 制作一个Clueboard 66%的固件，需要用:
87
88 make clueboard/66/rev3:default
89
90当完成后你要看到一些回显，尾部如下:
91
92```
93Linking: .build/clueboard_66_rev3_default.elf [OK]
94Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]
95Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK]
96Checking file size of clueboard_66_rev3_default.hex [OK]
97 * The firmware size is fine - 26356/28672 (2316 bytes free)
98```
99
100# 创建你的布局
101
102现在你可以创建属于你自己的布局了! 请移步 [构建你的第一个固件](newbs_building_firmware.md)来继续。
diff --git a/docs/zh-cn/newbs_learn_more_resources.md b/docs/zh-cn/newbs_learn_more_resources.md
new file mode 100644
index 000000000..ccb4fa326
--- /dev/null
+++ b/docs/zh-cn/newbs_learn_more_resources.md
@@ -0,0 +1,15 @@
1# 学习资源
2
3这些资源旨在让QMK社区的新成员更了解新成员文档中提供的信息。
4
5Git 资源:
6
7* [很好的通用教程](https://www.codecademy.com/learn/learn-git)
8* [从例子中学习Git游戏](https://learngitbranching.js.org/)
9* [了解有关GitHub的更多信息的Git资源](getting_started_github.md)
10* [专门针对QMK的Git资源](contributing.md)
11
12
13命令行资源:
14
15* [超棒的命令行通用教程](https://www.codecademy.com/learn/learn-the-command-line)
diff --git a/docs/zh-cn/newbs_testing_debugging.md b/docs/zh-cn/newbs_testing_debugging.md
new file mode 100644
index 000000000..d88d9b6f2
--- /dev/null
+++ b/docs/zh-cn/newbs_testing_debugging.md
@@ -0,0 +1,46 @@
1# 测试和调试
2
3使用自定义固件刷新键盘后，您就可以测试它了。如果您幸运，一切都会完美运行，但如果没有，这份文件将帮助您找出问题所在。
4
5## 测试
6
7测试键盘通常非常简单。按下每一个键并确保它发送的是您期望的键。甚至有一些程序可以帮助您确保没有任何键失效。
8
9注意：这些程序不是由QMK提供或认可的。
10
11* [QMK Configurator](https://config.qmk.fm/#/test/) (网页版)
12* [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (仅Windows)
13* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (仅Mac)
14* [Keyboard Tester](https://www.keyboardtester.com) (网页版)
15* [Keyboard Checker](https://keyboardchecker.com) (网页版)
16
17## 使用QMK工具箱进行调试
18
19[QMK工具箱](https://github.com/qmk/qmk_toolbox) 将会在你的`rules.mk`中有`CONSOLE_ENABLE = yes`的时候显示你键盘发来的消息。 默认情况下，输出极为有限，不过您可以打开调试模式来增加输出信息量。使用你键盘布局中的`DEBUG`键码,使用 [命令](feature_command.md) 特性来使能调试模式, 或者向你的布局中添加以下代码。
20
21```c
22void keyboard_post_init_user(void) {
23 // Customise these values to desired behaviour
24 debug_enable=true;
25 debug_matrix=true;
26 //debug_keyboard=true;
27 //debug_mouse=true;
28}
29```
30
31<!-- 需要修改之处:这里要添加调试回显。 -->
32
33## 发送您自己的调试消息
34
35有时用[custom code](custom_quantum_functions.md)发送自定义调试信息很有用. 这么做很简单. 首先在你文件头部包含`print.h`:
36
37```c
38#include "print.h"
39```
40
41之后，您可以使用一些不同的打印功能:
42
43* `print("string")`: 打印简单字符串.
44* `uprintf("%s string", var)`: 打印格式化字符串
45* `dprint("string")`: 仅在调试模式使能时打印简单字符串
46* `dprintf("%s string", var)`: 仅在调试模式使能时打印格式化字符串
diff --git a/docs/zh-cn/reference_glossary.md b/docs/zh-cn/reference_glossary.md
new file mode 100644
index 000000000..06d363250
--- /dev/null
+++ b/docs/zh-cn/reference_glossary.md
@@ -0,0 +1,167 @@
1# QMK术语表
2
3## ARM
4多家公司生产的32位单片机系列，例如Atmel, Cypress, Kinetis, NXP, ST, 和 TI等公司。
5
6## AVR
7[Atmel](https://www.microchip.com/)公司的单片机系列。 AVR是TMK的初始支持平台。
8
9## AZERTY
10Français (法国)标准键盘布局。用键盘的前六个字母命名。
11
12## Backlight(背光)
13键盘上照明的通称。背光通常是一组LED灯，通过键帽或者按轴发光，但也不总是这样。
14
15## Bluetooth(蓝牙)
16一种短距离点对点无线协议。许多多无线键盘使用此协议。
17
18## Bootloader(引导加载程序)
19一种写到你单片机的保护区的特殊的程序，该程序可以使单片机升级自己的固件，通常是通过USB来升级。
20
21## Bootmagic(热改键)
22允许各种键盘行为动态变化的功能，如交换或禁用常用键。
23
24## C
25一种适用于系统代码的低级编程语言。大多数qmk代码是用C编写的。
26
27## Colemak
28一种流行的键盘布局。
29
30## Compile(编译)
31把人可读的代码转换成你的单片机可以运行的机器代码的过程。
32
33## Dvorak
34一个由August Dvorak博士在20世纪30年代创建的布局。Dvorak简化键盘(Dvorak Simplified Keyboard)的缩写。
35
36## Dynamic Macro(动态宏)
37一种记录在键盘上的宏，当键盘拔出或计算机重新启动时，宏将丢失。
38
39* [动态宏文档](feature_dynamic_macros.md)
40
41## Eclipse
42是一种受C语言开发者追捧的集成开发环境(IDE)。
43
44* [Eclipse安装说明](eclipse.md)
45
46## Firmware(固件)
47用来控制单片机的软件。
48
49## git
50命令行版本控制软件
51
52## GitHub
53负责大多数QMK项目的网站。它是Git、问题跟踪和其他帮助我们运行qmk的功能的集成平台。
54
55## ISP(在系统编程)
56在系统编程(In-system programming), 使用外部硬件和JTAG管脚对AVR芯片进行编程的一种方法。
57
58## hid_listen
59从键盘接收调试消息的接口。 您可以使用[QMK Flasher](https://github.com/qmk/qmk_flasher)或[PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)查看这些消息
60
61## Keycode(键码)
62表示特定键的2字节数据。`0x00`-`0xFF`用于[基本键码](keycodes_basic.md)而`0x100`-`0xFFFF`用于[量子键码](quantum_keycodes.md).
63
64## Key Down
65一个键按下尚未抬起时触发的事件。
66
67## Key Up
68一个键抬起时触发的事件。
69
70## Keymap(键映射)
71映射到物理键盘布局的一组键码，在按键和按键释放时进行处理。有时翻译为布局，意为软件上表示的布局，即映射。
72
73## Layer(层)
74为了让一个键实现多个功能的抽象结构。最高活动层有限。
75
76## Leader Key(前导键、设置菜单键)
77本功能允许您点击前导键，然后按顺序按1-3个键子来激活按键或其他量子功能。
78
79* [前导键文档](feature_leader_key.md)
80
81## LED
82发光二极管，键盘上最常用的指示灯装置。
83
84## Make
85用于编译所有源文件的软件包。可以使用`make`命令和其他参数来编译你的固件。
86
87## Matrix(矩阵)
88一种由列和行组成的接线模式，使单片机能够用较少的引脚检测按键。矩阵通常包含二极管，以达到全键无冲。
89
90## Macro(宏)
91本功能可以在敲击单个键后发送多个按键事件(hid报告)。
92
93* [宏文档](feature_macros.md)
94
95## MCU(单片机、微控制单元)
96微控制单元，键盘的处理器。
97
98## Modifier(修改键、修饰键、功能键)
99按住该键将会改变其他键的功能，修饰键包括 Ctrl, Alt, 和 Shift。
100
101## Mousekeys(鼠标键)
102本功能在您敲击键盘时会控制鼠标光标。
103
104* [鼠标键文档](feature_mouse_keys.md)
105
106## N-Key Rollover (NKRO、全键无冲)
107一种术语，适用于能够同时报告任意数量按键的键盘。
108
109## Oneshot Modifier(粘滞键)
110一种能让你的功能键一直保持按下，直到你按下其他键的功能。它叫做粘滞键或叫做粘连键，该功能由软件实现而非机械结构。
111
112## ProMicro
113一种低成本AVR开发板。这种板子很容易在购物网站找到(价格不到20RMB)，但是据说刷写pro micro有点令人抓狂。
114
115## Pull Request(拉请求、PR)
116向QMK请求提交代码。我们鼓励所有用户提交你们自己的键盘的代码。
117
118## QWERTY
119标准英文键盘，通常也用于其他语言，例如中文。是用键盘前6个字母命名的。
120
121## QWERTZ
122标准Deutsche(德语)键盘布局。使用前6个字母明名。
123
124## Rollover(允许翻转、无冲形式)
125该术语表示在一个键已按下时按下另一个键。形式包括2KRO(双键无冲),6KRO(6键无冲),和NKRO(全键无冲)，无冲表示可同时按下而不产生冲突的键的数量。
126
127## Scancode(扫描码)
128HID报告中的一个1字节的数字，表示一个键子。这些数字在下列文档中[HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)该文档发布于[USB-IF](https://www.usb.org/)。
129
130## Space Cadet键盘的shift键
131一种特使的shift设置，能让你通过敲击左或右shift一次或多次键入不同的括号。
132
133* [Space Cadet键盘文档](feature_space_cadet.md)
134
135## Tap(敲击、单击)
136按下并释放一个键。在某些情况下您需要区分键按下和键抬起，但是单击把两个事件都包括了。
137
138## Tap Dance(多击键)
139本功能允许向同一个键子分配多个键码，并根据按键次数区分。
140
141* [多击键文档](feature_tap_dance.md)
142
143## Teensy
144一种低成本AVR开发板<!--译者吐槽：我怎么感觉成本不低。好吧，我穷。 -->，通常用于手工连线键盘。这个teensy是有点小贵但是halfkay bootloader会让它刷写十分简单，所以也很常用。
145
146## Underlight(背光)
147用于照亮电路板底面的LED的总称。这些LED通常从印刷电路板的底部向键盘所在的表面发光。
148
149## Unicode
150在较大的计算机世界中，Unicode是一组编码方案，用于表示任何语言中的字符。 与qmk相关的是，它意味着使用各种操作系统方案来发送Unicode代码点，而不是扫描码。
151
152* [Unicode文档](feature_unicode.md)
153
154## Unit Testing(单元测试)
155针对qmk的自动运行测试框架。单元测试帮助我们确信我们的更改不会破坏任何东西。
156
157* [单元测试文档](unit_testing.md)
158
159## USB
160通用串行总线，键盘最常见的有线接口。
161
162## USB 主机 (或简易主机)
163USB诸暨市你的电脑，或者你的键盘所插的任何设备。
164
165# 并没有找到你想找到的术语?
166
167[建立一个issue](https://github.com/qmk/qmk_firmware/issues) ，想好你的问题，或许你所问的术语就会添加到这里。创建一个PR帮我们添加需要添加的术语当然坠吼了:)
generated by cgit v1.2.3 (git 2.25.1) at 2025-08-27 02:00:58 +0100