aboutsummaryrefslogtreecommitdiff
path: root/docs/zh-cn
diff options
context:
space:
mode:
Diffstat (limited to 'docs/zh-cn')
-rw-r--r--docs/zh-cn/README.md45
-rw-r--r--docs/zh-cn/_summary.md322
-rw-r--r--docs/zh-cn/api_docs.md73
-rw-r--r--docs/zh-cn/api_overview.md20
-rw-r--r--docs/zh-cn/cli.md43
-rw-r--r--docs/zh-cn/cli_commands.md503
-rw-r--r--docs/zh-cn/cli_configuration.md126
-rw-r--r--docs/zh-cn/cli_tab_complete.md32
-rw-r--r--docs/zh-cn/configurator_architecture.md66
-rw-r--r--docs/zh-cn/configurator_default_keymaps.md198
-rw-r--r--docs/zh-cn/configurator_step_by_step.md63
-rw-r--r--docs/zh-cn/configurator_troubleshooting.md31
-rw-r--r--docs/zh-cn/contributing.md188
-rw-r--r--docs/zh-cn/custom_quantum_functions.md367
-rw-r--r--docs/zh-cn/driver_installation_zadig.md102
-rw-r--r--docs/zh-cn/easy_maker.md37
-rw-r--r--docs/zh-cn/faq.md6
-rw-r--r--docs/zh-cn/faq_build.md127
-rw-r--r--docs/zh-cn/faq_debug.md188
-rw-r--r--docs/zh-cn/faq_general.md59
-rw-r--r--docs/zh-cn/faq_keymap.md172
-rw-r--r--docs/zh-cn/faq_misc.md108
-rw-r--r--docs/zh-cn/feature_grave_esc.md39
-rw-r--r--docs/zh-cn/feature_space_cadet.md70
-rw-r--r--docs/zh-cn/flashing.md329
-rw-r--r--docs/zh-cn/flashing_bootloadhid.md75
-rw-r--r--docs/zh-cn/getting_started_docker.md59
-rw-r--r--docs/zh-cn/getting_started_getting_help.md15
-rw-r--r--docs/zh-cn/getting_started_github.md7
-rw-r--r--docs/zh-cn/getting_started_introduction.md9
-rw-r--r--docs/zh-cn/getting_started_vagrant.md61
-rw-r--r--docs/zh-cn/keymap.md209
-rw-r--r--docs/zh-cn/mod_tap.md143
-rw-r--r--docs/zh-cn/newbs.md36
-rw-r--r--docs/zh-cn/newbs_best_practices.md163
-rw-r--r--docs/zh-cn/newbs_building_firmware.md87
-rw-r--r--docs/zh-cn/newbs_building_firmware_configurator.md18
-rw-r--r--docs/zh-cn/newbs_flashing.md317
-rw-r--r--docs/zh-cn/newbs_getting_started.md210
-rw-r--r--docs/zh-cn/newbs_learn_more_resources.md36
-rw-r--r--docs/zh-cn/newbs_testing_debugging.md46
-rw-r--r--docs/zh-cn/reference_configurator_support.md200
-rw-r--r--docs/zh-cn/reference_glossary.md81
-rw-r--r--docs/zh-cn/support.md22
-rw-r--r--docs/zh-cn/syllabus.md77
-rw-r--r--docs/zh-cn/translating.md60
-rw-r--r--docs/zh-cn/zh_cn_doc_status.sh35
47 files changed, 3932 insertions, 1348 deletions
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
index b42818d58..93dfbf1ee 100644
--- a/docs/zh-cn/README.md
+++ b/docs/zh-cn/README.md
@@ -1,31 +1,42 @@
1# QMK机械键盘固件 1# Quantum Mechanical Keyboard固件
2 2
3[![当前版本](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags) 3<!---
4[![异议](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh) 4 original document: 0.15.12:docs/README.md
5[![文档状态](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm) 5 git diff 0.15.12 HEAD -- docs/README.md | cat
6[![GitHub贡献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) 6-->
7[![GitHub分支](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
8 7
9## 什么是 QMK 固件? 8## 什么是 QMK 固件?
10 9
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键盘中发挥功能. 10QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的用于开发计算机输入设备的开源软件。社区专注像键盘，鼠标，MIDI设备的各种电子输入设备。社区内的核心小组成员维护[QMK固件](https://github.com/qmk/qmk_firmware)，[QMK配置器](https://config.qmk.fm)（QMK Configurator），[QMK工具箱](https://github.com/qmk/qmk_toolbox)（QMK Toolbox），[qmk.fm](https://qmk.fm)，并与各位社区成员维护这份文档。
12 11
13## 如何到它 12## 如何
14 13
15如果你打算贡献布局, 键盘, 或者其他QMK特性, 一下是最简单的方法：[从GitHub获得repo分支](https://github.com/qmk/qmk_firmware#fork-destination-box), 并克隆你的repo到本地进行编辑，推送，然后从你的分支打开 [Pull Request](https://github.com/qmk/qmk_firmware/pulls). 14<div class="flex-container">
16 15
17此外, 你也可以直接下载 ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), 或者从git克隆 (`git@github.com:qmk/qmk_firmware.git`), 或 https (`https://github.com/qmk/qmk_firmware.git`). 16?> **基础方式** [QMK配置器](zh-cn/newbs_building_firmware_configurator.md) <br>
17用户友好的图形界面工具，无需具备编程知识基础。
18 18
19## 如何编译 19?> **进阶方式** [基于源代码](zh-cn/newbs.md) <br>
20功能更强大，但门槛较高。
20 21
21在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令: 22</div>
22 23
23 make planck/rev4:default 24## 个性化定制
24 25
25这将建立 `planck`的`rev4` 修订版本并使用 `default`布局。并非所有键盘都有修订版本 (也叫做子项目或文件夹)，在此情况下，修订版本可以省略，如下: 26QMK提供了很多功能，对应着很多可供浏览的配套文档。大部分功能都是通过修改[键映射](zh-cn/keymap.md)及[键码](zh-cn/keycodes.md)实现的。
26 27
27 make preonic:default 28## 需要帮助？
28 29
29## 如何 30请查阅[求帮助页面](zh-cn/support.md)以了解何获QMK使用方法助。
30 31
31QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](https://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。 32## 回馈社区
33
34有多种回馈社区的方法，最简单的方法是开始使用QMK并向你的朋友们推荐它。
35
36* 可以在我们的论坛及聊天室进行互助：
37 * [/r/olkb](https://www.reddit.com/r/olkb/)
38 * [Discord服务器](https://discord.gg/Uq7gcHh)
39* 点击页面下方的“Edit This Page”，可以对文档提供贡献。
40* [将这份文档翻译为你的语言](zh-cn/translating.md)
41* [上报bug](https://github.com/qmk/qmk_firmware/issues/new/choose)
42* [发起Pull Request](zh-cn/contributing.md)
diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md
index cedcfbd52..8a710a9ec 100644
--- a/docs/zh-cn/_summary.md
+++ b/docs/zh-cn/_summary.md
@@ -1,133 +1,193 @@
1* [完全菜鸟指南](zh-cn/newbs.md) 1<!--for translators, see first: zh-cn/reference_glossary.md#terms-of-zh-cn-translate -->
2* 新手教程
3 * [介绍](zh-cn/newbs.md)
2 * [入门](zh-cn/newbs_getting_started.md) 4 * [入门](zh-cn/newbs_getting_started.md)
3 * [构建你的第一个固件](zh-cn/newbs_building_firmware.md) 5 * [构建第一个固件](zh-cn/newbs_building_firmware.md)
4 * [刷新固件](zh-cn/newbs_flashing.md) 6 * [刷写固件](zh-cn/newbs_flashing.md)
5 * [测试和调试](zh-cn/newbs_testing_debugging.md) 7 * [寻求帮助](zh-cn/support.md)
6 * [Git最佳实践](zh-cn/newbs_git_best_practices.md) 8 * [其它资源](zh-cn/newbs_learn_more_resources.md)
7 * [使用你分叉(fork)的主分支(master)](zh-cn/newbs_git_using_your_master_branch.md) 9 * [QMK大纲](zh-cn/syllabus.md)
8 * [解决合并冲突](zh-cn/newbs_git_resolving_merge_conflicts.md) 10
9 * [重新同步一个分支](zh-cn/newbs_git_resynchronize_a_branch.md) 11* FAQ
10 * [学习资源](zh-cn/newbs_learn_more_resources.md) 12 * [常规FAQ](zh-cn/faq_general.md)
11 13 * [构建/编译QMK](zh-cn/faq_build.md)
12* [QMK基础](zh-cn/README.md) 14 * [QMK问题排查](zh-cn/faq_misc.md)
13 * [QMK简介](zh-cn/getting_started_introduction.md) 15 * [调试QMK](zh-cn/faq_debug.md)
14 * [QMK命令行工具](zh-cn/cli.md) 16 * [键映射FAQ](zh-cn/faq_keymap.md)
15 * [QMK命令行工具配置](zh-cn/cli_configuration.md) 17 * [充分利用AVR的存储空间](zh-cn/squeezing_avr.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) 18 * [术语表](zh-cn/reference_glossary.md)
53 * [单元测试](zh-cn/unit_testing.md) 19
54 * [实用函数](zh-cn/ref_functions.md) 20* 配置器(Configurator)
55 * [配置器支持](zh-cn/reference_configurator_support.md) 21 * [总览](zh-cn/newbs_building_firmware_configurator.md)
56 * [info.json 格式](zh-cn/reference_info_json.md) 22 * [入门](zh-cn/configurator_step_by_step.md)
57 * [Python 命令行开发](zh-cn/cli_development.md) 23 * [问题排查](zh-cn/configurator_troubleshooting.md)
58 24 * [框架](zh-cn/configurator_architecture.md)
59* [特性](zh-cn/features.md) 25 * QMK API
60 * [基本键码](zh-cn/keycodes_basic.md) 26 * [总览](zh-cn/api_overview.md)
61 * [US ANSI控制码](zh-cn/keycodes_us_ansi_shifted.md) 27 * [API文档](zh-cn/api_docs.md)
62 * [量子键码](zh-cn/quantum_keycodes.md) 28 * [键盘支持](zh-cn/reference_configurator_support.md)
63 * [高级键码](zh-cn/feature_advanced_keycodes.md) 29 * [添加默认键映射](zh-cn/configurator_default_keymaps.md)
64 * [音频](zh-cn/feature_audio.md) 30
65 * [自动shift](zh-cn/feature_auto_shift.md) 31* CLI
66 * [背光](zh-cn/feature_backlight.md) 32 * [总览](zh-cn/cli.md)
67 * [蓝牙](zh-cn/feature_bluetooth.md) 33 * [配置](zh-cn/cli_configuration.md)
68 * [热改键](zh-cn/feature_bootmagic.md) 34 * [命令](zh-cn/cli_commands.md)
69 * [组合](zh-cn/feature_combo) 35 * [Tab补全](zh-cn/cli_tab_complete.md)
70 * [命令](zh-cn/feature_command.md) 36
71 * [消抖 API](zh-cn/feature_debounce_type.md) 37* 使用QMK
72 * [拨动开关](zh-cn/feature_dip_switch.md) 38 * 导览
73 * [动态宏指令](zh-cn/feature_dynamic_macros.md) 39 * [功能定制](zh-cn/custom_quantum_functions.md)
74 * [编码器](zh-cn/feature_encoders.md) 40 * [利用Zadig安装驱动](zh-cn/driver_installation_zadig.md)
75 * [重音号Esc复合键](zh-cn/feature_grave_esc.md) 41 * [极简式制作](zh-cn/easy_maker.md)
76 * [触摸反馈](zh-cn/feature_haptic_feedback.md) 42 * [键映射总览](zh-cn/keymap.md)
77 * [HD44780 LCD控制器](zh-cn/feature_hd44780.md) 43 * 开发环境
78 * [自锁键](zh-cn/feature_key_lock.md) 44 * [Docker指南](zh-cn/getting_started_docker.md)
79 * [布局](zh-cn/feature_layouts.md) 45 * [Vagrant指南](zh-cn/getting_started_vagrant.md)
80 * [前导键](zh-cn/feature_leader_key.md) 46 * 刷写(Flashing)
81 * [LED阵列](zh-cn/feature_led_matrix.md) 47 * [刷写](zh-cn/flashing.md)
82 * [宏指令](zh-cn/feature_macros.md) 48 * [刷写ATmega32A (ps2avrgb)](zh-cn/flashing_bootloadhid.md)
83 * [鼠标键](zh-cn/feature_mouse_keys.md) 49 * IDE
84 * [OLED驱动](zh-cn/feature_oled_driver.md) 50 * [在Eclipse中使用QMK](zh-cn/other_eclipse.md)
85 * [一键功能](zh-cn/one_shot_keys.md) 51 * [在VSCode中使用QMK](zh-cn/other_vscode.md)
86 * [指针设备](zh-cn/feature_pointing_device.md) 52 * Git最佳实践
87 * [PS/2鼠标](zh-cn/feature_ps2_mouse.md) 53 * [介绍](zh-cn/newbs_git_best_practices.md)
88 * [RGB灯光](zh-cn/feature_rgblight.md) 54 * [你自己的副本](zh-cn/newbs_git_using_your_master_branch.md)
89 * [RGB矩阵](zh-cn/feature_rgb_matrix.md) 55 * [冲突合并](zh-cn/newbs_git_resolving_merge_conflicts.md)
90 * [空格候补换挡](zh-cn/feature_space_cadet.md) 56 * [基于你的分支修复](zh-cn/newbs_git_resynchronize_a_branch.md)
91 * [分体键盘](zh-cn/feature_split_keyboard.md) 57 * 键盘组装
92 * [速录机](zh-cn/feature_stenography.md) 58 * [飞线指南](zh-cn/hand_wire.md)
93 * [换手](zh-cn/feature_swap_hands.md) 59 * [ISP刷写指南](zh-cn/isp_flashing_guide.md)
94 * [多击键](zh-cn/feature_tap_dance.md) 60
95 * [终端](zh-cn/feature_terminal.md) 61 * 键码入门
96 * [热敏打印机](zh-cn/feature_thermal_printer.md) 62 * [键码汇总](zh-cn/keycodes.md)
97 * [Unicode](zh-cn/feature_unicode.md) 63 * [基础键码](zh-cn/keycodes_basic.md)
98 * [用户空间](zh-cn/feature_userspace.md) 64 * [语言特定的键码](zh-cn/reference_keymap_extras.md)
99 * [速度键](zh-cn/feature_velocikey.md) 65 * [修饰键](zh-cn/feature_advanced_keycodes.md)
100 66 * [原子键码](zh-cn/quantum_keycodes.md)
101* 制造和定制者指南 67 * [Magic键码](zh-cn/keycodes_magic.md)
102 * [手工连线指南](zh-cn/hand_wire.md) 68
103 * [ISP刷新指南](zh-cn/isp_flashing_guide.md) 69 * 键码进阶
104 * [ARM调试指南](zh-cn/arm_debugging.md) 70 * [指令](zh-cn/feature_command.md)
105 * [ADC设备](zh-cn/adc_driver.md) 71 * [动态宏](zh-cn/feature_dynamic_macros.md)
106 * [I2C设备](zh-cn/i2c_driver.md) 72 * [Grave Escape](zh-cn/feature_grave_esc.md)
107 * [SPI设备](zh-cn/spi_driver.md) 73 * [前导键](zh-cn/feature_leader_key.md)
108 * [WS2812设备](zh-cn/ws2812_driver.md) 74 * [Mod-Tap](zh-cn/mod_tap.md)
109 * [EEPROM设备](zh-cn/eeprom_driver.md) 75 * [宏](zh-cn/feature_macros.md)
110 * [GPIO控制](zh-cn/internals_gpio_control.md) 76 * [鼠标键](zh-cn/feature_mouse_keys.md)
111 * [自定义键盘矩阵](zh-cn/custom_matrix.md) 77 * [Space Cadet Shift](zh-cn/feature_space_cadet.md)
112 * [Proton C转换](zh-cn/proton_c_conversion.md) 78 * [US ANSI上档键值](zh-cn/keycodes_us_ansi_shifted.md)
113 79
114* 深入了解 80 * 软件特性
115 * [键盘工作原理](zh-cn/how_keyboards_work.md) 81 * [自动Shift](zh-cn/feature_auto_shift.md)
116 * [深入了解QMK](zh-cn/understanding_qmk.md) 82 * [组合键](zh-cn/feature_combo.md)
117 83 * [防抖API](zh-cn/feature_debounce_type.md)
118* 其他话题 84 * [按键锁定](zh-cn/feature_key_lock.md)
119 * [使用Eclipse开发QMK](zh-cn/other_eclipse.md) 85 * [按键重定义](zh-cn/feature_key_overrides.md)
120 * [使用VSCode开发QMK](zh-cn/other_vscode.md) 86 * [层](zh-cn/feature_layers.md)
121 * [支持](zh-cn/getting_started_getting_help.md) 87 * [粘滞键](zh-cn/one_shot_keys.md)
122 * [翻译QMK文档](zh-cn/translating.md) 88 * [光标设备](zh-cn/feature_pointing_device.md)
123 89 * [原生HID](zh-cn/feature_rawhid.md)
124* QMK 内构 (正在编写) 90 * [Sequencer](zh-cn/feature_sequencer.md)
125 * [定义](zh-cn/internals_defines.md) 91 * [换手](zh-cn/feature_swap_hands.md)
126 * [输入回调寄存器](zh-cn/internals_input_callback_reg.md) 92 * [一键多用](zh-cn/feature_tap_dance.md)
127 * [Midi设备](zh-cn/internals_midi_device.md) 93 * [点按配置](zh-cn/tap_hold.md)
128 * [Midi设备配置过程](zh-cn/internals_midi_device_setup_process.md) 94 * [终端](zh-cn/feature_terminal.md)
129 * [Midi工具库](zh-cn/internals_midi_util.md) 95 * [Unicode](zh-cn/feature_unicode.md)
130 * [发送函数](zh-cn/internals_send_functions.md) 96 * [用户空间](zh-cn/feature_userspace.md)
131 * [Sysex工具](zh-cn/internals_sysex_tools.md) 97 * [WPM计算](zh-cn/feature_wpm.md)
132<!--fromen:20200126-6:03AM(GMT+8)--> 98
133<!--cn:20200211-11:04AM(GMT+8)--> 99 * 硬件特性
100 * 显示
101 * [HD44780 LCD控制器](zh-cn/feature_hd44780.md)
102 * [ST7565 LCD驱动](zh-cn/feature_st7565.md)
103 * [OLED驱动](zh-cn/feature_oled_driver.md)
104 * 灯效
105 * [背光](zh-cn/feature_backlight.md)
106 * [LED矩阵](zh-cn/feature_led_matrix.md)
107 * [RGB灯光](zh-cn/feature_rgblight.md)
108 * [RGB矩阵](zh-cn/feature_rgb_matrix.md)
109 * [音频](zh-cn/feature_audio.md)
110 * [蓝牙](zh-cn/feature_bluetooth.md)
111 * [Bootmagic Lite](zh-cn/feature_bootmagic.md)
112 * [自定义矩阵](zh-cn/custom_matrix.md)
113 * [Digitizer](zh-cn/feature_digitizer.md)
114 * [拨动开关（DIP Switch）](zh-cn/feature_dip_switch.md)
115 * [编码器（旋钮）](zh-cn/feature_encoders.md)
116 * [触摸反馈](zh-cn/feature_haptic_feedback.md)
117 * [摇杆](zh-cn/feature_joystick.md)
118 * [LED指示](zh-cn/feature_led_indicators.md)
119 * [MIDI](zh-cn/feature_midi.md)
120 * [Proton C转换](zh-cn/proton_c_conversion.md)
121 * [PS/2鼠标](zh-cn/feature_ps2_mouse.md)
122 * [分体式键盘](zh-cn/feature_split_keyboard.md)
123 * [速记](zh-cn/feature_stenography.md)
124 * [热敏打印机](zh-cn/feature_thermal_printer.md)
125 * [Velocikey](zh-cn/feature_velocikey.md)
126
127* QMK开发
128 * [PR Checklist](zh-cn/pr_checklist.md)
129 * 打破兼容的改动
130 * [总览](zh-cn/breaking_changes.md)
131 * [我的PR已打上标记](zh-cn/breaking_changes_instructions.md)
132 * [近期的变更日志(Changelog)](zh-cn/ChangeLog/20210529.md "QMK v0.13.0 - 2021 May 29")
133 * [更早期的不兼容改动](zh-cn/breaking_changes_history.md)
134
135 * C语言开发
136 * [ARM调试指引](zh-cn/arm_debugging.md)
137 * [AVR处理器](zh-cn/hardware_avr.md)
138 * [C编码规范](zh-cn/coding_conventions_c.md)
139 * [兼容的微处理器](zh-cn/compatible_microcontrollers.md)
140 * [驱动](zh-cn/hardware_drivers.md)
141 * [ADC驱动](zh-cn/adc_driver.md)
142 * [Audio驱动](zh-cn/audio_driver.md)
143 * [I2C驱动](zh-cn/i2c_driver.md)
144 * [SPI驱动](zh-cn/spi_driver.md)
145 * [WS2812驱动](zh-cn/ws2812_driver.md)
146 * [EEPROM驱动](zh-cn/eeprom_driver.md)
147 * [串口驱动](zh-cn/serial_driver.md)
148 * [UART驱动](zh-cn/uart_driver.md)
149 * [操控GPIO](zh-cn/internals_gpio_control.md)
150 * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md)
151
152 * Python开发
153 * [编码规范](zh-cn/coding_conventions_python.md)
154 * [QMK CLI开发](zh-cn/cli_development.md)
155
156 * 配置器开发
157 * QMK API
158 * [开发环境](zh-cn/api_development_environment.md)
159 * [架构总览](zh-cn/api_development_overview.md)
160
161 * 硬件平台开发
162 * Arm/ChibiOS
163 * [选择MCU](zh-cn/platformdev_selecting_arm_mcu.md)
164 * [启动引导](zh-cn/platformdev_chibios_earlyinit.md)
165
166 * QMK参考信息
167 * [参与到QMK](zh-cn/contributing.md)
168 * [翻译QMK文档](zh-cn/translating.md)<!--but should we translate this? currently keep it fallback-->
169 * [配置](zh-cn/config_options.md)
170 * [数据驱动配置](zh-cn/data_driven_config.md)
171 * [Make指引](zh-cn/getting_started_make_guide.md)
172 * [编写文档的最佳实践](zh-cn/documentation_best_practices.md)
173 * [文档模板](zh-cn/documentation_templates.md)
174 * [贡献配列到社区](zh-cn/feature_layouts.md)
175 * [单元测试](zh-cn/unit_testing.md)
176 * [常用函数](zh-cn/ref_functions.md)
177 * [info.json参考资料](zh-cn/reference_info_json.md)
178
179 * 深入了解
180 * [键盘工作原理](zh-cn/how_keyboards_work.md)
181 * [键盘矩阵原理](zh-cn/how_a_matrix_works.md)
182 * [了解QMK](zh-cn/understanding_qmk.md)
183
184 * QMK内部细节 (编辑中)
185 * [定义](zh-cn/internals_defines.md)
186 * [输入回调的注册](zh-cn/internals_input_callback_reg.md)
187 * [Midi设备](zh-cn/internals_midi_device.md)
188 * [Midi设备驱动流程](zh-cn/internals_midi_device_setup_process.md)
189 * [Midi辅助功能](zh-cn/internals_midi_util.md)
190 * [发送函数](zh-cn/internals_send_functions.md)
191 * [Sysex工具](zh-cn/internals_sysex_tools.md)
192
193<!--fromen:20211014-12:00(GMT+8) commit 04cf161aa01fd433b5dae69d9fd31569ed5dca59-->
diff --git a/docs/zh-cn/api_docs.md b/docs/zh-cn/api_docs.md
new file mode 100644
index 000000000..a2df9ec20
--- /dev/null
+++ b/docs/zh-cn/api_docs.md
@@ -0,0 +1,73 @@
1# QMK API
2
3<!---
4 original document: 0.15.12:docs/api_docs.md
5 git diff 0.15.12 HEAD -- docs/api_docs.md | cat
6-->
7
8本章节详述了QMK API的使用方法，若您是应用开发者，使用这套API可以实现[QMK](https://qmk.fm)键盘固件的编译支持。
9
10## 总览
11
12本服务提供了一套用于编译自定义键映射的异步API，通过POST方式发送JSON参数到API，定期检查执行状态，待固件编译完成后，即可下载生成的固件文件和固件的源文件（如果需要的话）。
13
14#### 荷载JSON参数示例：
15
16```json
17{
18 "keyboard": "clueboard/66/rev2",
19 "keymap": "my_awesome_keymap",
20 "layout": "LAYOUT_all",
21 "layers": [
22 ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
23 ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
24 ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
25 ]
26}
27```
28
29如上可见，荷载参数里有用于生成固件文件的所有键盘信息。每一个层定义都包含了与键盘 `LAYOUT` 宏定义一致的QMK键码列表数据，若该键盘有多个支持的 `LAYOUT` 宏定义，也可以指定使用的是哪一个。
30
31## 提交一个编译job
32
33若要将键映射配置编译成固件文件，仅需将JSON参数通过POST发送至 `/v1/compile` 节点。下面的示例中我们假设JSON荷载参数已存放在 `json_data` 文件中。
34
35```
36$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" https://api.qmk.fm/v1/compile
37{
38 "enqueued": true,
39 "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
40}
41```
42
43## 检查状态
44
45键映射配置提交后，可以简单地通过 HTTP GET 请求来查询job状态：
46
47```
48$ curl https://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
49{
50 "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
51 "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
52 "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
53 "status": "running",
54 "result": null
55}
56```
57
58这份信息告诉我们编译job已经提交到队列中且正在执行。job的状态有5种：
59
60* **failed（失败）**: 编译服务出现问题。
61* **finished（完成）**: 编译已完成，`result` 字段中保存了编译结果。
62* **queued（排队中）**: 键映射job在等待可用的编译服务器。
63* **running（执行中）**: 编译进行中，应当很快就会结束。
64* **unknown（未知）**: 出现了较严重的错误，请给我们[提交一个bug](https://github.com/qmk/qmk_compiler/issues).
65
66## 确认编译产出
67
68编译job完成后请查看 `result` 字段，该字段下保存了如下信息项的哈希表数据：
69
70* `firmware_binary_url`: 用于刷写的固件文件URL列表
71* `firmware_keymap_url`: `keymap.c` 文件URL列表
72* `firmware_source_url`: 完整的固件源代码URL列表
73* `output`: 编译job的stdout及stderr输出信息，所有错误信息都会在这里。
diff --git a/docs/zh-cn/api_overview.md b/docs/zh-cn/api_overview.md
new file mode 100644
index 000000000..a07cfb742
--- /dev/null
+++ b/docs/zh-cn/api_overview.md
@@ -0,0 +1,20 @@
1# QMK API
2
3<!---
4 original document: 0.15.12:docs/api_overview.md
5 git diff 0.15.12 HEAD -- docs/api_overview.md | cat
6-->
7
8QMK API提供了一套可用于Web及GUI工具可用的异步API，用于实现将任何[QMK](https://qmk.fm/)支持的键盘的键映射方案进行编译。已有的键映射模板支持所有的QMK键码并且不需要额外的C代码需求。键盘的维护团队可以提供新的模板来启用更多功能的支持。
9
10## App开发者
11
12若您是一位意愿将这套API引入您的程序中的移动端App开发者，请参阅[API使用指引](zh-cn/api_docs.md)。
13
14## 键盘维护团队
15
16若您希望强化您维护的键盘方案在QMK编译API中的支持，请参阅[键盘支持](zh-cn/reference_configurator_support.md)。
17
18## 后端开发者
19
20若您对这套API系统本身感兴趣，请参阅[开发环境](zh-cn/api_development_environment.md)搭建环境并继续深入探索[架构总览](zh-cn/api_development_overview.md)。
diff --git a/docs/zh-cn/cli.md b/docs/zh-cn/cli.md
new file mode 100644
index 000000000..22c2db92c
--- /dev/null
+++ b/docs/zh-cn/cli.md
@@ -0,0 +1,43 @@
1# QMK CLI :id=qmk-cli
2
3<!---
4 original document: 0.15.12:docs/cli.md
5 git diff 0.15.12 HEAD -- docs/cli.md | cat
6-->
7
8## 总览 :id=overview
9
10QMK CLI可以让构建QMK键盘的过程更轻松一些，我们已提供的一批指令可用于简化及流式化地处理一些常见工作，如获取并编译QMK固件，创建新的键映射等。
11
12### 依赖项 :id=requirements
13
14QMK依赖Python 3.6或更高版本。我们已经尽力缩减依赖项，但在[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt)中的依赖项是需安装的包。在安装QMK CLI时这些依赖项也会自动完成安装。
15
16### 通过 Homebrew 安装(macOS 及部分 Linux) :id=install-using-homebrew
17
18若已安装[Homebrew](https://brew.sh)，可以按如下方法安装QMK:
19
20```
21brew install qmk/qmk/qmk
22export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径
23qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境
24```
25
26### 通过 pip 安装 :id=install-using-easy_install-or-pip
27
28未在以上列出的操作系统可以手动安装QMK。首先确认已安装Python 3.6（或更高版本）及 pip，然后通过如下指令安装QMK：
29
30```
31python3 -m pip install qmk
32export QMK_HOME='~/qmk_firmware' # 可选，指定 `qmk_firmware` 的路径
33qmk setup # 拉取 `qmk/qmk_firmware` 并选择性地配置构建环境
34```
35
36### 其它操作系统的安装包 :id=packaging-for-other-operating-systems
37
38我们正在寻求可以制作维护更多操作系统下可用的 `qmk` 安装包的开发者，若您愿意为您的操作系统制作安装包，请遵循如下指引：
39
40* 当该系统下的最佳实践与本指引冲突时，请遵循系统的最佳实践方案
41 * 但请在注释中列明此处违反这份指引的原因
42* 在 virtualenv 下安装
43* 指引用户去设置 `QMK_HOME` 环境变量，使得固件源文件拉取路径不再是默认的 `~/qmk_firmware`
diff --git a/docs/zh-cn/cli_commands.md b/docs/zh-cn/cli_commands.md
new file mode 100644
index 000000000..08d1cc7e7
--- /dev/null
+++ b/docs/zh-cn/cli_commands.md
@@ -0,0 +1,503 @@
1# QMK CLI 命令
2
3<!---
4 original document: 0.15.12:docs/cli_commands.md
5 git diff 0.15.12 HEAD -- docs/cli_commands.md | cat
6-->
7
8# 用户命令
9
10## `qmk compile`
11
12该命令用于在指定目录下编译固件，可用于构建<https://config.qmk.fm>导出的JSON数据，代码库中的键映射，或是当前目录下的键盘。
13
14该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
15
16**用于配置器导出的数据时**：
17
18```
19qmk compile [-c] <configuratorExport.json>
20```
21
22**用于键映射时**：
23
24```
25qmk compile [-c] [-e <var>=<value>] [-j <num_jobs>] -kb <keyboard_name> -km <keymap_name>
26```
27
28**在键盘目录下时**：
29
30须在存在默认键映射的键盘目录下执行，或是在键盘的键映射子目录下，否则须指定参数 `--keymap <keymap_name>`
31```
32qmk compile
33```
34
35**构建所有支持该键映射的键盘时**：
36
37```
38qmk compile -kb all -km <keymap_name>
39```
40
41**示例**：
42```
43$ qmk config compile.keymap=default
44$ cd ~/qmk_firmware/keyboards/planck/rev6
45$ qmk compile
46Ψ Compiling keymap with make planck/rev6:default
47...
48```
49指定键映射参数时
50
51```
52$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
53$ qmk compile -km 66_iso
54Ψ Compiling keymap with make clueboard/66/rev4:66_iso
55...
56```
57位于键盘目录下时
58
59```
60$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
61$ qmk compile
62Ψ Compiling keymap with make make gh60/satan:colemak
63...
64```
65
66**在配列目录下时**：
67
68必须是在 `qmk_firmware/layouts/` 下的键映射目录下。
69```
70qmk compile -kb <keyboard_name>
71```
72
73**示例**：
74```
75$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
76$ qmk compile -kb dz60
77Ψ Compiling keymap with make dz60:mechmerlin-ansi
78...
79```
80
81**并行编译**：
82
83在编译时添加 `-j`/`--parallel` 开关可能有助于加快编译速度。
84```
85qmk compile -j <num_jobs> -kb <keyboard_name>
86```
87`num_jobs` 用于指定并行的job上限，将其设置为0可以实现无限制的并行编译。
88```
89qmk compile -j 0 -kb <keyboard_name>
90```
91
92## `qmk flash` :id=qmk-flash
93
94该命令与 `qmk compile` 类似，但额外地可以指定bootloader。bootloader参数是可选的，默认会指定为 `:flash`。可通过 `-bl <bootloader>` 来指定bootloader。请查阅[刷写固件](zh-cn/flashing.md)指引以深入了解可用的bootloader信息。
95
96该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
97
98**用于配置器导出的数据时**：
99
100```
101qmk flash [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>] <configuratorExport.json>
102```
103
104**用于键映射时**：
105
106```
107qmk flash -kb <keyboard_name> -km <keymap_name> [-bl <bootloader>] [-c] [-e <var>=<value>] [-j <num_jobs>]
108```
109
110**列出所有bootloader**
111
112```
113qmk flash -b
114```
115
116## `qmk config`
117
118该命令用于配置QMK功能，完整的 `qmk config` 文档参见[CLI配置](zh-cn/cli_configuration.md)。
119
120**使用方法**：
121
122```
123qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
124```
125
126## `qmk cd`
127
128该命令会启动一个新的 shell 会话并定位到 `qmk_firmware` 所在目录。
129
130须留意如果你已经位于 `QMK_HOME` 下的某个位置（比如 `keyboards/` 目录中），该指令不会生效。
131
132若要退回到原来的 shell 会话，只需要执行 `exit`。
133
134**使用方法**:
135
136```
137qmk cd
138```
139
140## `qmk console`
141
142该命令用于连接键盘终端并展示调试信息。仅当键盘固件通过 `CONSOLE_ENABLE=yes` 编译时有效。
143
144**用法**：
145
146```
147qmk console [-d <pid>:<vid>[:<index>]] [-l] [-n] [-t] [-w <seconds>]
148```
149
150**示例**：
151
152连接到所有可用的键盘并输出终端信息：
153
154```
155qmk console
156```
157
158列出所有设备：
159
160```
161qmk console -l
162```
163
164仅输出 clueboard/66/rev3 键盘的信息:
165
166```
167qmk console -d C1ED:2370
168```
169
170仅输出第二把 clueboard/66/rev3 键盘的信息:
171
172```
173qmk console -d C1ED:2370:2
174```
175
176输出时间戳及VID:PID以替代键盘名：
177
178```
179qmk console -n -t
180```
181
182屏蔽bootloader的消息：
183
184```
185qmk console --no-bootloaders
186```
187
188## `qmk doctor`
189
190该命令用以检查你的开发环境并对发现的潜在的构建及刷写问题进行提醒，如果您乐意，它也可以修复其中大部分问题。
191
192**用法**：
193
194```
195qmk doctor [-y] [-n]
196```
197
198**示例**：
199
200检查开发环境中的问题并提示是否修复：
201
202 qmk doctor
203
204检查开发环境中的问题并自动进行修复：
205
206 qmk doctor -y
207
208检查开发环境中的问题，仅生成报告：
209
210 qmk doctor -n
211
212## `qmk format-json`
213
214将JSON文件格式化为（尽量）便于阅读的形式。会自动分辨JSON结构类型（info.json还是keymap.json），必要时也可以通过 `--format` 指定。
215
216**用法**：
217
218```
219qmk format-json [-f FORMAT] <json_file>
220```
221
222## `qmk info`
223
224展示QMK中的键盘及键映射信息，该命令用来获取键盘信息，输出配列，展示底层按键矩阵，及格式化地输出键映射JSON数据。
225
226**用法**：
227
228```
229qmk info [-f FORMAT] [-m] [-l] [-km KEYMAP] [-kb KEYBOARD]
230```
231
232该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
233
234**示例**：
235
236输出键盘的基础信息：
237
238 qmk info -kb planck/rev5
239
240输出键盘的矩阵信息：
241
242 qmk info -kb ergodox_ez -m
243
244输出键盘的键映射JSON数据：
245
246 qmk info -kb clueboard/california -km default
247
248## `qmk json2c`
249
250从QMK配置器导出的数据中生成 keymap.c 文件
251Creates a keymap.c from a QMK Configurator export.
252
253**用法**：
254
255```
256qmk json2c [-o OUTPUT] filename
257```
258
259## `qmk c2json`
260
261从 keymap.c 文件中生成 keymap.json
262**注意：** 解析C代码文件并不容易，该命令有可能无法对你的键映射文件生效，不使用C预处理代码有时可以解决问题。
263
264**用法**：
265
266```
267qmk c2json -km KEYMAP -kb KEYBOARD [-q] [--no-cpp] [-o OUTPUT] filename
268```
269
270## `qmk lint`
271
272检查键盘及键映射数据并提示出常见错误与问题，以及不符合模板规范的地方。
273
274**用法**：
275
276```
277qmk lint [-km KEYMAP] [-kb KEYBOARD] [--strict]
278```
279
280该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
281
282**示例**：
283
284基本的lint检查：
285
286 qmk lint -kb rominronin/katana60/rev2
287
288## `qmk list-keyboards`
289
290该命令可以列出 `qmk_firmware` 中所有的键盘
291
292**用法**：
293
294```
295qmk list-keyboards
296```
297
298## `qmk list-keymaps`
299
300该命令可以列出指定键盘（及指定版本）下的所有键映射。
301
302该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
303
304**用法**：
305
306```
307qmk list-keymaps -kb planck/ez
308```
309
310## `qmk new-keyboard`
311
312该命令可基于现有模板创建出新的键盘定义。
313
314对于未给出的参数，会提示你输入，若未传入 `-u` 参数且 .gitconfig 中设置了 `user.name`，则会提示你使用该值作为默认用户名。
315
316**用法**：
317
318```
319qmk new-keyboard [-kb KEYBOARD] [-t {avr,ps2avrgb}] -u USERNAME
320```
321
322## `qmk new-keymap`
323
324该命令可基于键盘已有的默认键映射创建新的键映射。
325
326该命令会尝试感知目录路径，当你在键盘或键映射目录下执行时，KEYBOARD及KEYMAP参数将被自动填入。
327
328**用法**：
329
330```
331qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
332```
333
334## `qmk clean`
335
336该命令会清理 `.build` 目录，若传入 `--all` 开关，在 `qmk_firmware` 下的所有.hex及.bin文件也会一并删除。
337
338**用法**：
339
340```
341qmk clean [-a]
342```
343
344---
345
346# 面向开发者的命令
347
348## `qmk format-text`
349
350该命令会重新格式化并统一文件的换行符。
351
352代码库下所有的文件须使用Unix换行符（LF）。
353若你在**Windows**下进行开发，必须确保文件中的换行符是正确的，才能让你的PR被允许合入。
354
355```
356qmk format-text
357```
358
359## `qmk format-c`
360
361该命令会使用clang-format来格式化C代码。
362
363不带参数地执行该命令以用来格式化核心代码相关的改动，默认会通过 `git diff` 来检查 `origin/master`， 可以通过 `-b <分支名>` 来改变检查的分支。
364
365带着 `-a` 开关执行命令会格式化所有的核心代码，也可以在命令行中传入文件名来指定格式化某个文件。
366
367**用以处理指定文件时**：
368
369```
370qmk format-c [file1] [file2] [...] [fileN]
371```
372
373**用以处理所有的核心代码时**：
374
375```
376qmk format-c -a
377```
378
379**用以处理 origin/master 下的所有改动时**：
380
381```
382qmk format-c
383```
384
385**用以处理指定分支下的所有改动时**：
386
387```
388qmk format-c -b branch_name
389```
390
391## `qmk generate-compilation-database`
392
393**用法**:
394
395```
396qmk generate-compilation-database [-kb KEYBOARD] [-km KEYMAP]
397```
398
399创建新 `compile_commands.json` 文件。
400
401你的IDE/编辑器是否使用了“编程语言本地服务器”（language server）且 _总是_ 无法找到全部的包含文件（include files）？是不是很讨厌红色的波浪线？想不想让你的编辑器看得懂 `#include QMK_KEYBOARD_H`？你需要的是一个[编译数据库](https://clang.llvm.org/docs/JSONCompilationDatabase.html)！而 QMK 可以帮助你构建出一个。
402
403该命令需要知道你在构建的是哪个键盘及键映射，它使用与 `qmk compile` 命令一样的选项：参数、当前目录以及配置文件。
404
405**示例：**
406
407```
408$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
409$ qmk generate-compilation-database
410Ψ Making clean
411Ψ Gathering build instructions from make -n gh60/satan:colemak
412Ψ Found 50 compile commands
413Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
414```
415
416现在可以打开你的开发环境并享受没有波浪线的日子了。
417
418## `qmk docs`
419
420该命令会在本地启动一个HTTP服务，从而你可以浏览及改进文档，默认端口号为8936，使用 `-b`/`--browser` 开关可以让该命令自动通过默认浏览器打开链接地址。
421
422**用法**：
423
424```
425qmk docs [-b] [-p PORT]
426```
427
428## `qmk generate-docs`
429
430该命令可以在本地生成QMK文档，用以文档的常规浏览使用，或进行文档改进工作。可以使用类似[serve](https://www.npmjs.com/package/serve)这样的工具来浏览生成的文档文件。
431
432**用法**：
433
434```
435qmk generate-docs
436```
437
438## `qmk generate-rgb-breathe-table`
439
440该命令可以生成用于[RGB灯光](zh-cn/feature_rgblight.md)的呼吸效果的查询表（LUT）头文件。将该文件命名为 `rgblight_breathe_table.h` 并放入键盘或键映射目录下，可以覆盖替换 `quantum/rgblight/` 下的默认LUT。
441
442**用法**：
443
444```
445qmk generate-rgb-breathe-table [-q] [-o OUTPUT] [-m MAX] [-c CENTER]
446```
447
448## `qmk kle2json`
449
450该命令可以将KLE原始数据转换成QMK配置器的JSON数据，可接受的输入可以是文件绝对路径，或当前目录下的文件名。若 `info.json` 文件存在，默认不会进行覆盖，通过指定 `-f` 或 `--force` 开关可以允许覆盖。
451
452**用法**：
453
454```
455qmk kle2json [-f] <filename>
456```
457
458**示例**：
459
460```
461$ qmk kle2json kle.txt
462☒ File info.json already exists, use -f or --force to overwrite.
463```
464
465```
466$ qmk kle2json -f kle.txt -f
467Ψ Wrote out to info.json
468```
469
470## `qmk format-python`
471
472该命令可以对 `qmk_firmware` 下的python代码进行格式化。
473
474**用法**：
475
476```
477qmk format-python
478```
479
480## `qmk pytest`
481
482该命令会执行python测试框架，在你更改了python代码后，应确保该命令可以成功执行。
483
484**用法**：
485
486```
487qmk pytest
488```
489
490**示例**:
491
492执行全部的测试套件：
493
494 qmk pytest
495
496执行指定的测试用例组：
497
498 qmk pytest -t qmk.tests.test_cli_commands
499
500执行单个测试用例：
501
502 qmk pytest -t qmk.tests.test_cli_commands.test_c2json
503 qmk pytest -t qmk.tests.test_qmk_path
diff --git a/docs/zh-cn/cli_configuration.md b/docs/zh-cn/cli_configuration.md
new file mode 100644
index 000000000..d3bca4a33
--- /dev/null
+++ b/docs/zh-cn/cli_configuration.md
@@ -0,0 +1,126 @@
1# QMK CLI 配置
2
3<!---
4 original document: 0.15.12:docs/cli_configuration.md
5 git diff 0.15.12 HEAD -- docs/cli_configuration.md | cat
6-->
7
8本文详述了 `qmk config` 功能及作用。
9
10# 介绍
11
12QMK CLI的配置系统是一套键/值（key/value）数据系统，每个键由一个子指令和一个参数名组成，通过点号（英文句号）分隔。这使得配置项可以简单直接地映射到命令行参数上。
13
14## 简单示例
15
16作为一个示例，对于指令 `qmk compile --keyboard clueboard/66/rev4 --keymap default`
17
18其存在两个命令行参数，可以通过如下方式从配置中读取：
19
20* `compile.keyboard`
21* `compile.keymap`
22
23可以这样设置：
24
25```
26$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
27compile.keyboard: None -> clueboard/66/rev4
28compile.keymap: None -> default
29Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
30```
31
32现在每次执行 `qmk compile` 时都不需要指定键盘及键映射参数了。
33
34## 设置用户级的默认配置
35
36当你需要在多个命令中使用一致的配置项时，比如很多命令都需要的 `--keyboard` 参数，相比于每次执行命令都去指定该参数值，你可以直接设置用户级的配置值，即可将该配置用于所有的命令。
37
38示例：
39
40```
41$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
42user.keyboard: None -> clueboard/66/rev4
43user.keymap: None -> default
44Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
45```
46
47# CLI文档 (`qmk config`)
48
49`qmk config` 命令可以管理配置数据。当不带额外参数执行时，会输出所有已有配置。存在参数时这些参数将被视为配置项参数，其格式须满足如下形式且无空格分隔：
50
51 <subcommand|general|default>[.<key>][=<value>]
52
53## 设置配置值
54
55在配置项的键后加 = 号进行值的设置，配置项的键必须是 `<section>.<key>` 的完整形式。
56
57举例：
58
59```
60$ qmk config default.keymap=default
61default.keymap: None -> default
62Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
63```
64
65## 读取配置值
66
67可以读取整个配置文件、单独配置键或是一整个配置系列，也可以同时指定读取多个配置项。
68
69### 全量配置读取示例
70
71 qmk config
72
73### 单系列配置读取示例
74
75 qmk config compile
76
77### 单配置项读取示例
78
79 qmk config compile.keyboard
80
81### 多配置项读取示例
82
83 qmk config user compile.keyboard compile.keymap
84
85## 删除配置值
86
87将配置值设置为 `None` 即可删除该配置值。
88
89示例：
90
91```
92$ qmk config default.keymap=None
93default.keymap: default -> None
94Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
95```
96
97## 批量操作
98
99一个指令中可以合并执行多个读写操作，将依序进行执行输出：
100
101```
102$ qmk config compile default.keymap=default compile.keymap=None
103compile.keymap=skully
104compile.keyboard=clueboard/66_hotswap/gen1
105default.keymap: None -> default
106compile.keymap: skully -> None
107Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
108```
109
110# 用户配置相关的配置项
111
112| 配置项 | 默认值 | 描述 |
113|-------|-------|------|
114| user.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） |
115| user.keymap | None | 键盘名称（举例：`default`） |
116| user.name | None | 用户的Github用户名 |
117
118# 所有配置项
119
120| 配置项 | 默认值 | 描述 |
121|-------|-------|------|
122| compile.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） |
123| compile.keymap | None | 键盘名称（举例：`default`） |
124| hello.name | None | 执行时展示的欢迎信息 |
125| new_keyboard.keyboard | None | 键盘路径（举例：`clueboard/66/rev4`） |
126| new_keyboard.keymap | None | 键盘名称（举例：`default`） |
diff --git a/docs/zh-cn/cli_tab_complete.md b/docs/zh-cn/cli_tab_complete.md
new file mode 100644
index 000000000..7a16e9766
--- /dev/null
+++ b/docs/zh-cn/cli_tab_complete.md
@@ -0,0 +1,32 @@
1# QMK Tab补全
2
3<!---
4 original document: 0.15.12:docs/cli_tab_complete.md
5 git diff 0.15.12 HEAD -- docs/cli_tab_complete.md | cat
6-->
7
8在使用Bash 4.2及更高版本、Zsh或FiSH时，可以启用QMK CLI的Tab补全功能，可以实现对 `qmk` 参数中的开关、键盘、文件等参数的自动补全。
9
10## 设置
11
12有以下几种启用Tab补全的方法。
13
14### 仅当前用户生效
15
16将以下内容添加到文件 `.profile` 或 `.bashrc` 的末尾:
17
18 source ~/qmk_firmware/util/qmk_tab_complete.sh
19
20若你的 `qmk_firmware` 存放在其它路径，以上路径也需要调整。
21
22### 系统级的符号关联
23
24若想让所有本地用户都可以实现Tab补全，可以按如下方法添加符号连接到 `qmk_tab_complete.sh` 脚本：
25
26 `ln -s ~/qmk_firmware/util/qmk_tab_complete.sh /etc/profile.d/qmk_tab_complete.sh`
27
28### 系统级的脚本拷贝
29
30有时符号连接的方案无效，可以改用拷贝文件到指定位置的方案。但须留意该Tab补全脚本可能会不定时更新，你需要定期重新拷贝一次该脚本。
31
32 cp util/qmk_tab_complete.sh /etc/profile.d
diff --git a/docs/zh-cn/configurator_architecture.md b/docs/zh-cn/configurator_architecture.md
new file mode 100644
index 000000000..386ebd689
--- /dev/null
+++ b/docs/zh-cn/configurator_architecture.md
@@ -0,0 +1,66 @@
1# QMK配置器框架
2
3<!---
4 original document: 0.15.12:docs/configurator_architecture.md
5 git diff 0.15.12 HEAD -- docs/configurator_architecture.md | cat
6-->
7
8本章节提供了QMK配置器前端技术框架信息，若你对QMK配置器前端工程本身感兴趣，可以从[QMK配置器](https://github.com/qmk/qmk_configurator)代码库开始。
9
10# 总览
11
12![QMK配置器技术框架图](./../configurator_diagram.svg)
13
14# 详述
15
16QMK配置器基于[单页面框架](https://en.wikipedia.org/wiki/Single-page_application)实现，供使用者创建兼容QMK键盘的自定义键映射方案。键映射方案可以导出为JSON格式的数据，也可以编译出可通过[QMK工具箱](https://github.com/qmk/qmk_toolbox)刷写到键盘中的固件文件。
17
18配置器从“键盘元数据仓库（Keyboard Metadata store）”获取键盘元数据，编译请求通过QMK API提交，编译产出放在S3兼容的数据仓库[Digital Ocean空间](https://www.digitalocean.com/products/spaces/)中。
19
20## 配置器前端
21
22地址：<https://config.qmk.fm>
23
24[配置器前端](https://config.qmk.fm)会编译并产出一些静态文件并通过Github Pages托管，每当[QMK配置器 `master`](https://github.com/qmk/qmk_configurator)分支收到推送的提交时都会触发。可以通过[QMK配置器 actions页面](https://github.com/qmk/qmk_configurator/actions/workflows/build.yml)查看这些job的状态。
25
26## 键盘元数据
27
28地址：<https://keyboards.qmk.fm>
29
30每当[qmk_firmware](https://github.com/qmk/qmk_firmware)仓库中的键盘定义变化时，会生成JSON格式的键盘元数据，并上传到指定空间用于配置器生成每种键盘的UI展现。可以在[QMK固件 actions页面](https://github.com/qmk/qmk_firmware/actions/workflows/api.yml)查看相关job的状态。如果你是QMK开发团队成员（Collaborator），可以使用 `workflow_dispatch` 事件触发器来手动执行该job。
31
32## QMK API
33
34地址：<http://api.qmk.fm>
35
36QMK API接受 `keymap.json` 文件输入并进行编译，这和你在 `qmk compile` 和 `qmk flash` 中使用的文件一样。当 `keymap.json` 文件被提交后，浏览器中的页面将定时查看job状态（每2秒一次，有时更久一些）直到job完成。最终产出的JSON描述信息里包含了键映射方案的源文件，及编译出的二进制的可下载链接地址。
37
38为遵循GPL协议，QMK API会确保源文件及编译产出总是同时提供的。
39
40API有3种非异常的回应状态-
41
421. 编译job排队中
432. 编译job执行中
443. 编译job已完成
45
46### 编译job排队中
47
48此状态表明[QMK编译器](#QMK编译器)节点还未选中该job，在配置器页面此时会显示“等待一个可用的烤炉（Waiting for an oven）”。
49
50### 编译job执行中
51
52此状态说明编译job已经在执行中，配置器页面会显示为“烤制中”(Baking)。
53
54### 编译job已完成
55
56此状态说明编译job已经执行完毕，输出的JSON格式的状态信息里有源文件及编译产出的二进制文件的下载链接项。
57
58## Redis/RQ
59
60QMK API通过Redis队列分发job到可用的[QMK编译器](#QMK编译器)节点。接收到的 `keymap.json` 文件先送到RQ队列，而 `qmk_compiler` 节点则从中拉取执行。
61
62## QMK编译器
63
64[QMK编译器](https://github.com/qmk/qmk_compiler)负责执行 `keymap.json` 文件的实际编译工作。它的工作逻辑是先拉取有请求的 `qmk_firmware` 分支代码，执行 `qmk compile keymap.json`，最后上传源文件及二进制产出到Digital Ocean空间中。
65
66当用户需要下载源代码/二进制文件时，API会给出重定向后的已鉴权地址链接。
diff --git a/docs/zh-cn/configurator_default_keymaps.md b/docs/zh-cn/configurator_default_keymaps.md
new file mode 100644
index 000000000..135029b7e
--- /dev/null
+++ b/docs/zh-cn/configurator_default_keymaps.md
@@ -0,0 +1,198 @@
1# 向QMK配置器中添加默认键映射 :id=adding-default-keymaps
2
3<!---
4 original document: 0.15.12:docs/configurator_default_keymaps.md
5 git diff 0.15.12 HEAD -- docs/configurator_default_keymaps.md | cat
6-->
7
8本章节描述了如何向QMK配置器中添加一款键盘的默认键映射
9
10
11## 技术信息 :id=technical-information
12
13QMK配置器使用JSON作为键映射的本地文件格式。我们尽力确保其行为与在 `qmk_firmware` 中 执行 `make <keyboard>:default` 时一致。
14
15该目录下的键映射需要定义四个键值对：
16
17* `keyboard` (字符串)
18 * 键盘名称，与执行 `make` 进行编译时使用的一致（如 `make 1upkeyboards/1up60rgb:default`）。
19* `keymap` (字符串)
20 * 应设置为 `default`.
21* `layout` (字符串)
22 * 默认键映射应使用的配列宏定义。
23* `layers` (数组)
24 * 键映射数据。此键下的每行元素对应一个层定义，层定义中包含该层的键码组成信息。
25
26额外地，大部分键映射中还有一个 `commit` 项，该项并不是QMK配置器后端服务API所需，而是用于告知配置器维护者这份JSON键映射数据来源于代码库中的哪个版本的键映射。该值为 `qmk_firmware` 代码库中最后一次修改键盘默认 `keymap.c` 文件提交的commit的SHA标记。该SHA值的获取方式是拉取[`qmk/qmk_firmware` 库的 `master`分支](https://github.com/qmk/qmk_firmware/tree/master/)后，执行 `git log -1 --pretty=oneline -- keyboards/<keyboard>/keymaps/default/keymap.c`（若键盘有什么问题且存在 `keymap.json` 文件，则用之作为替代），执行结果应类似于：
27
28```
29f14629ed1cd7c7ec9089604d64f29a99981558e8 Remove/migrate action_get_macro()s from default keymaps (#5625)
30```
31
32本例中，`f14629ed1cd7c7ec9089604d64f29a99981558e8` 即应为 `commit` 的值。
33
34
35## 示例 :id=example
36
37若某人想添加H87a Hineybush键盘的默认键映射方案，应到 `qmk_firmware` 下H87a的默认键映射下执行上述 `git log` 命令：
38
39```
40user ~/qmk_firmware (master)
41$ git log -1 --pretty=oneline master -- keyboards/hineybush/h87a/keymaps/default/keymap.c
42ef8878fba5d3786e3f9c66436da63a560cd36ac9 Hineybush h87a lock indicators (#8237)
43```
44
45在我们获取了commit哈希值后，还需要键映射定义（为加强可读性进行了编辑处理）：
46
47```c
48...
49#include QMK_KEYBOARD_H
50
51const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
52
53 [0] = LAYOUT_all(
54 KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SLCK, KC_PAUS,
55 KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP,
56 KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN,
57 KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT,
58 KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_TRNS, KC_UP,
59 KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT),
60
61 [1] = LAYOUT_all(
62 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RGB_TOG, RGB_MOD, RGB_HUD, RGB_HUI, RGB_SAD, RGB_SAI, RGB_VAD, RGB_VAI, BL_TOGG, BL_DEC, BL_INC,
63 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_VOLU,
64 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, RESET, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_MPLY, KC_MNXT, KC_VOLD,
65 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
66 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS,
67 KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS),
68
69};
70```
71
72默认键映射使用了 `LAYOUT_all` 宏，最后其会成为 `layout` 项的值。编译为QMK配置器的JSON键映射数据后，输出文件应为：
73
74```json
75{
76 "keyboard": "hineybush/h87a",
77 "keymap": "default",
78 "commit": "ef8878fba5d3786e3f9c66436da63a560cd36ac9",
79 "layout": "LAYOUT_all",
80 "layers": [
81 [
82 "KC_ESC", "KC_F1", "KC_F2", "KC_F3", "KC_F4", "KC_F5", "KC_F6", "KC_F7", "KC_F8", "KC_F9", "KC_F10", "KC_F11", "KC_F12", "KC_PSCR", "KC_SLCK", "KC_PAUS",
83 "KC_GRV", "KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0", "KC_MINS", "KC_EQL", "KC_BSPC", "KC_BSPC", "KC_INS", "KC_HOME", "KC_PGUP",
84 "KC_TAB", "KC_Q", "KC_W", "KC_E", "KC_R", "KC_T", "KC_Y", "KC_U", "KC_I", "KC_O", "KC_P", "KC_LBRC", "KC_RBRC", "KC_BSLS", "KC_DEL", "KC_END", "KC_PGDN",
85 "KC_CAPS", "KC_A", "KC_S", "KC_D", "KC_F", "KC_G", "KC_H", "KC_J", "KC_K", "KC_L", "KC_SCLN", "KC_QUOT", "KC_NUHS", "KC_ENT",
86 "KC_LSFT", "KC_NUBS", "KC_Z", "KC_X", "KC_C", "KC_V", "KC_B", "KC_N", "KC_M", "KC_COMM", "KC_DOT", "KC_SLSH", "KC_RSFT", "KC_TRNS", "KC_UP",
87 "KC_LCTL", "KC_LGUI", "KC_LALT", "KC_SPC", "KC_RALT", "MO(1)", "KC_RGUI", "KC_RCTL", "KC_LEFT", "KC_DOWN", "KC_RGHT"
88 ],
89 [
90 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RGB_TOG", "RGB_MOD", "RGB_HUD", "RGB_HUI", "RGB_SAD", "RGB_SAI", "RGB_VAD", "RGB_VAI", "BL_TOGG", "BL_DEC", "BL_INC",
91 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_VOLU",
92 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "RESET", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_MPLY", "KC_MNXT", "KC_VOLD",
93 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
94 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS",
95 "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS", "KC_TRNS"
96 ]
97 ]
98}
99```
100
101`layers` 数组中的空白区域不影响键映射功能，仅为了方便阅读。
102
103
104## 附加说明 :id=caveats
105
106### 层定义只能通过序号进行引用 :id=layer-references
107
108QMK中常见的一种做法是通过一系列 `#define` 或 `enum` 类型声明来对层定义进行命名：
109
110```c
111enum layer_names {
112 _BASE,
113 _MEDIA,
114 _FN
115};
116```
117
118对于C代码来讲可行，但对于配置器来讲，你*必须*使用层序号 - 上例中的`MO(_FN)` 应使用 `MO(2)`。
119
120### 不支持任何形式的定制化代码 :id=custom-code
121
122需要在 keymap.c 文件中添加函数代码的功能，如Tap Dance或是Unicode，都*完全*无法在配置器中构建。即便是在 `qmk_firmware` 代码库中在键盘定义中设置了 `TAP_DANCE_ENABLE = yes`，也只会导致*任何*固件构建在配置器中行不通。这是由API及JSON格式的键映射数据同时造成的限制。
123
124### 对自定义键码的不完全支持 :id=custom-keycodes
125
126仅有一个方案可以支持自定义键码：若自定义键码的逻辑实现是在 qmk_firmware 下的键盘定义中完成的，而非在键映射中，那么这个键码*可以*在配置器中使用且*可以*编译运行。（因此，）相对于在 `keymap.c` 中使用如下代码段：
127
128```c
129enum custom_keycodes {
130 MACRO_1 = SAFE_RANGE,
131 MACRO_2,
132 MACRO_3
133};
134...
135bool process_record_user(uint16_t keycode, keyrecord_t *record) {
136 switch(keycode) {
137 case MACRO_1:
138 if (record->event.pressed) {
139 SEND_STRING("This is macro #1.");
140 }
141 return false;
142 case MACRO_2:
143 if (record->event.pressed) {
144 SEND_STRING("This is macro #2.");
145 }
146 return false;
147 case MACRO_3:
148 if (record->event.pressed) {
149 SEND_STRING("This is macro #3.");
150 }
151 return false;
152 }
153 return true;
154};
155```
156
157... 请将键码的 `enum` 定义块添加到键盘的头文件（`<keyboard.h>`）中，例如（留意 `enum` 在这里命名为 `keyboard_keycodes`）：
158
159```c
160enum keyboard_keycodes {
161 MACRO_1 = SAFE_RANGE,
162 MACRO_2,
163 MACRO_3,
164 NEW_SAFE_RANGE // 重要!
165};
166```
167
168... 之后在 `<keyboard>.c` 中的 `process_record_kb()` 代码逻辑应为：
169
170```c
171bool process_record_kb(uint16_t keycode, keyrecord_t *record) {
172 switch(keycode) {
173 case MACRO_1:
174 if (record->event.pressed) {
175 SEND_STRING("This is macro #1.");
176 }
177 return false;
178 case MACRO_2:
179 if (record->event.pressed) {
180 SEND_STRING("This is macro #2.");
181 }
182 return false;
183 case MACRO_3:
184 if (record->event.pressed) {
185 SEND_STRING("This is macro #3.");
186 }
187 return false;
188 }
189 return process_record_user(keycode, record);
190};
191```
192
193注意最后的 `process_record_user()` 调用，若用户需要添加自定义键码到键映射中，须使用 `NEW_SAFE_RANGE` 替代 `SAFE_RANGE`，而其定义来自于上面键盘层定义中。
194
195
196## 更多资料 :id=additional-reading
197
198为了让QMK配置器支持你的键盘，你的键盘定义必须存在于 `qmk_firmware` 代码库的 `master` 分支中。相关操作指引，请参见[在QMK配置器中支持你的键盘](zh-cn/reference_configurator_support.md).
diff --git a/docs/zh-cn/configurator_step_by_step.md b/docs/zh-cn/configurator_step_by_step.md
new file mode 100644
index 000000000..bbfb71d5a
--- /dev/null
+++ b/docs/zh-cn/configurator_step_by_step.md
@@ -0,0 +1,63 @@
1# QMK 配置器: 入门
2
3<!---
4 original document: 0.15.12:docs/configurator_step_by_step.md
5 git diff 0.15.12 HEAD -- docs/configurator_step_by_step.md | cat
6-->
7
8本章节描述了如何使用QMK配置器构建出固件文件的过程。
9
10## 第一步：选择键盘
11
12从下拉列表中选择一款用于创建键映射的键盘。
13
14?> 当键盘有多个版本可选择时，请确保选择正确。
15
16因为很重要，这里我再次说一遍：
17
18!> **请选择正确的版本！**
19
20如果你的键盘声称是基于QMK的但未在列表中，可能是开发者还未提交给我们，或者提交还未被合并进来。若在[Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard)中没有找到请求支持该键盘的issue，请到[QMK固件](https://github.com/qmk/qmk_firmware/issues)提交一个issue。也有一些基于QMK的键盘是由制造商自己的GitHub账号在维护着，请也确认一下。 <!-- FIXME(skullydazed): This feels too wordy and I'm not sure we want to encourage these kinds of issues. Also, should we prompt them to bug the manufacutrer? -->
21
22## 第二部：选择键盘配列
23
24选择最适合你要创建的键映射的配列，一些键盘的配列不完整或有问题，后续会逐渐支持。
25
26!> 有时会遇到没有特别适合的配列的情况，请选择 `LAYOUT_all`。
27
28## 第三步：命名你的键映射
29
30如何起名完全取决于你。
31
32?> 如果编译时遇到了问题，可能是因为QMK固件代码库中已经有了同名项，可以尝试改一下名字。
33
34## 第四步：设计你的键映射
35
36以下三种方法可以添加键码：
37
381. 拖拽
392. 点击布局上的空白项，再点击所需的键码
403. 点击布局上的空白项, 再点击你物理键盘上的按键
41
42?> 鼠标在键上悬停时会有一个键码值的提示出现，详细描述信息请参见:
43
44* [基础键码资料](zh-cn/keycodes_basic.md)
45* [进阶键码资料](zh-cn/feature_advanced_keycodes.md)
46
47!> 如果你选择的配列与物理实机有出入，请将不需要的按键留空。如果不清楚应该用哪个键，例如，你只需要一个退格键，但 `LAYOUT_all` 中有两个退格键，须将两个键都放上一样的键码。
48
49## 第五步：保存键映射留待后续修订
50
51当你调整完毕键映射方案，或打算以后继续编辑，点击 `导出Keymap JSON文件（Download this QMK Keymap JSON File）` 按钮，当前键映射方案将保存到你的计算机中，之后可以点击 `导入Keymap JSON文件(Upload a QMK Keymap JSON File)` 按钮导入后继续编辑。
52
53!> **注意：** 导出的.json文件与 kbfirmware.com 和其它工具软件生成的并不兼容，如果你将导出的数据放到那些工具中，或尝试导入那些工具生成的.json文件，是不可行的。
54
55## 第六步：编译固件
56
57点击绿色的 `编译（Compile）` 按钮。
58
59编译完成后，可以点击绿色的 `固件（Download Firmware）` 下载固件文件。
60
61## 下一步：刷写到键盘中
62
63参见[刷写固件](zh-cn/newbs_flashing.md).
diff --git a/docs/zh-cn/configurator_troubleshooting.md b/docs/zh-cn/configurator_troubleshooting.md
new file mode 100644
index 000000000..a48ad1dd7
--- /dev/null
+++ b/docs/zh-cn/configurator_troubleshooting.md
@@ -0,0 +1,31 @@
1# 配置器问题排查
2
3<!---
4 original document: 0.15.12:docs/configurator_troubleshooting.md
5 git diff 0.15.12 HEAD -- docs/configurator_troubleshooting.md | cat
6-->
7
8## 我的 .json 文件不可用
9
10如果该 .json 文件确实是QMK配置器中导出的，恭喜你遇到bug了，请在[QMK配置器](https://github.com/qmk/qmk_configurator/issues)库中提交一个issue。
11
12如果不是……那么页面顶部加大加粗的提示让你不要使用其它 .json 文件，你是怎么错过的？
13
14## 我的配列中有好多空格键，我应该怎么处理？
15
16如果你是说有三个空格键栏，最好的做法是都放上空格键。这个处理方案也适用于退格键和Shift键。
17
18## 用于...的键码是什么？
19
20参见：
21
22* [基础键码资料](zh-cn/keycodes_basic.md)
23* [进阶键码资料](zh-cn/feature_advanced_keycodes.md)
24
25## 无法编译
26
27请检查键映射中所有的层，确保没有随机（random）键。
28
29## Bug及其它问题
30
31我们很乐意倾听你的需求及bug报告，请到[QMK配置器](https://github.com/qmk/qmk_configurator/issues)代码库中提交吧。
diff --git a/docs/zh-cn/contributing.md b/docs/zh-cn/contributing.md
index 6424d330c..03d3ea916 100644
--- a/docs/zh-cn/contributing.md
+++ b/docs/zh-cn/contributing.md
@@ -1,123 +1,78 @@
1# 如何做贡献 1# 如何做贡献
2 2
3<!---
4 original document: 0.15.12:docs/contributing.md
5 git diff 0.15.12 HEAD -- docs/contributing.md | cat
6-->
7
3👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍 8👍🎉 首先感谢各位百忙之中抽空阅读本文档，并为我们无私奉献。给您点赞啦！ 🎉👍
4 9
5第三方的帮助让Q酱成长了许多呢，Q酱也从你们那学到了不少新东西。Q酱希望每一个想帮助我的人都能很方便的做出有用的贡献。在这里我给摩拳擦掌的你们写了一点引导，让你们的代码在不对我做重大改动的情况下都能成功的被采纳哦。 10第三方的帮助让QMK获得了成长与进步。我们希望提供一套对贡献者和维护者都感到简便实用的PR（pull request）及贡献流程，因此我们整理出了一些准则，以免你的PR在被接纳前需要大改一番。
6 11
7* [项目概况](#项目概况) 12* [项目概况](#project-overview)
8* [代码规范](#代码规范) 13* [代码规范](#coding-conventions)
9* [一般教程](#一般教程) 14* [一般教程](#general-guidelines)
10* [行为守则对于我来说有何意义?](#行为守则对于我来说有何意义?) 15* [行为守则对于我来说有何意义？](#what-does-the-code-of-conduct-mean-for-me)
11 16
12## 这文章巨长无比不想读啊! 我就想问个问题而已! 17## 这文章巨长无比不想读啊! 我就想问个问题而已!
13 18
14您要是想问关于Q酱的问题的话可以在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)随意问。 19您要是有关于QMK的问题，请在[OLKB Subreddit](https://reddit.com/r/olkb)或者是[Discord](https://discord.gg/Uq7gcHh)上进行提问。
15 20
16请记住: 21请记住:
17 22
18* 维护Q酱的小可爱有的时候可能会有点忙，不能及时回答您的问题，耐心等等，他们都是很nice的人呀。 23* 你的问题也许要过几个小时才会有人回复，请耐心一些。
19* 维护Q酱的人都是很无私的善良的人。无论是贡献代码还是回答问题，都是义务的。有时见到他们努力回答各种问题，解决各种BUG，Q酱也是很心疼的。 24* 参与到QMK中的成员都是在无偿地贡献着自己的时间和精力，我们没有受雇于开发QMK或是专职回答你的疑问。
20* 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答： 25* 您可以看看下面的教程，可以让您的问题浅显易懂，更容易回答：
21 * https://opensource.com/life/16/10/how-ask-technical-questions 26 * https://opensource.com/life/16/10/how-ask-technical-questions
22 * http://www.catb.org/esr/faqs/smart-questions.html 27 * http://www.catb.org/esr/faqs/smart-questions.html
23 28
24# 项目概况 29# 项目概况 :id=project-overview
25 30
26Q酱很大一部分是用C语言组成的，不过有一小部分特性是C++的。怎么说呢，都是我的一部分，两个我都爱。Q酱一般是在键盘上的嵌入式处理器那里工作的，尤其与AVR([LUFA](https://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](https://www.chibios.org))两小哥哥搭配，干活不累，嘻嘻。如果您精通Arduino的话您会发现很多熟悉的概念，但也有点不爽，因为您以前的经验可能没法用来帮助Q酱。 31QMK很大一部分是C语言编写的，小部分特性是C++的。QMK的设计目标是在键盘上的嵌入式处理器中工作，如AVR([LUFA](https://www.fourwalledcubicle.com/LUFA.php))和ARM ([ChibiOS](https://www.chibios.org))。如果您对Arduino很熟悉的话，会发现优缺点也基本是相似的。但无论你之前是否有Arduino使用经验，都不会影响你参与到QMK贡献中来。
27 32
28<!-- 需要修正: 这里放些学习C语言的资源。外感谢正的小可爱。谢。--> 33<!-- FIXME: 这里应当放些C语言的。 -->
29 34
30# Q酱，我哪能帮助你嘞? 35# 我哪里求助？
31 36
32您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh). 37您要是有问题的话可以 [提出一个issue](https://github.com/qmk/qmk_firmware/issues) 或 [在Discord上交流一下](https://discord.gg/Uq7gcHh).
33 38
34# Q酱，我如你? 39# 我怎样才贡献？
35 40
36您以前是否没为开源贡献过代码，而又想知道帮助Q酱是怎么一回事? 稍安勿躁，咱给您总结一下！ 41您以前是否没有参与贡献过开源社区，而又想知道如何对QMK提供帮助？这里有一份快速指引！
42*译注：对于没有基本编程经验的人，请谨慎考虑这套操作流程，可参考，照着做很容易出问题，社区的语言障碍也会阻碍你对这些步骤的细节进行咨询*
37 43
380. 先注册一个 [GitHub](https://github.com) 账户。 440. 先注册一个 [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)。 451. 完整整理出来你要贡献的键映射，或是 [找一个你想解决的问题](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`就有一个仓库备份啦。 462. 把关联着问题的仓库fork到你的仓库。这样在`你的GitHub用户名/qmk_firmware` 下就有一个副本啦。
413. 使用 `git clone https://github.com/此处添GitHub用户名/此处添仓库名.git`这个命令把仓库同步到你的电脑中。 473. 使用 `git clone https://github.com/你的GitHub用户名/仓库名.git` 命令把仓库同步到你的电脑中。
424. 您要是想开发一个新特性的话可以先创建一个issue和Q酱的维护者讨论一下您要做什么。 484. 您要是想开发一个新特性的话可以先创建一个issue和QMK的维护者讨论一下您要做什么。
435. 使用`git checkout -b 此处写分支名字（别用汉字）`命令来创建一个分支（branch）用于开发。 495. 使用 `git checkout -b 此处写分支名字（别用汉字）` 命令来创建一个新分支（branch）用于开发。
446. 对要解决的问题或要添加的特性进行适当的更改。 506. 对要解决的问题或要添加的特性进行适当的更改。
457. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引（快照）里。 517. 使用 `git add 把改变的文件的目录写这里` 可以添加改变的文件内容到git用于管理工程状态的索引（快照）里。
468. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。 528. 使用 `git commit -m "这里写修改的相关信息"` 来描述你做出了什么修改。
479. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里（反正不是打篮球那个库里）。 539. 使用 `git push origin 此处写分支名字`来把你的更改同步到GitHub库里（反正不是打篮球那个库里）。
4810. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。 5410. 提交一个[QMK 固件的pull request](https://github.com/qmk/qmk_firmware/pull/new/master)。
4911. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟Q酱的中文也不是那么的溜，有可能会看不懂中文）。 5511. 给你的pull request拟一个标题，包括简短的描述和问题或错误代码。比如, 你可以起一个这样的"Added more log outputting to resolve #4352"（最好用英语，毕竟QMK的维护团队成员都是英语语系，有可能会看不懂中文）。
5012. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想问维护的小可爱们的问题。你的your pull request有点小问题无伤大雅(本来也没有完美的代码嘛), 维护的小可爱们会竭尽全力帮您改进的！ 5612. 在描述（description）里面写你做了哪些更改，你的代码里还存在什么问题, 或者你想对QMK维护着询问的问题。你的pull request有点小问题无伤大雅（没有完美的pull request）, QMK维护团队会尽力帮您改进的！
5113. 维护人员审查代码可能需要一些时间。 5713. 维护人员审查代码可能需要一些时间。
5214. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。 5814. 维护人员会通知您要更改什么地方，然后您就按照建议改一改。
5315. 预祝您合并成功！ 5915. 你的pull request合并成功了，恭喜！
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 60
107命行朋友们, 上 `-style=file`选项就会动在QMK根目录寻找.clang-format配置文件了。 61# 范 :id=coding-conventions
108 62
109VSCode用户, 标准的 C/C++ 插件就支持clang-format, 或者可以用[独立扩展](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)也行。 63我们的编码风格很容易掌握，如果你有C语言或Python编码经验，跟随我们的编码风格不会有什么困难。
110 64
111有些东西(比如LAYOUT宏) 会被clang-format打乱，所以那些文件就别用clang-format了,这里就教您一个小窍门，在`// clang-format off` 和 `//clang-format on`之间装上会被搞乱的代码就好了。 65* [编码规范 - C](zh-cn/coding_conventions_c.md)
66* [编码规范 - Python](zh-cn/coding_conventions_python.md)
112 67
113# 一般程 68# 基准 :id=general-guidelines
114 69
115你可以给Q酱的不同部分添砖加瓦，但也要用不同的方法严谨检查。不论你修改哪里最好还是看看下边。 70在QMK中存在多种类型的修改需求，因此也会有审查严格性上的差异。请在做出任何修改时留意，你的改动隶属于什么类型。
116 71
117* 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。 72* 将PR（pull request）分成一个个的逻辑单元。 比如，不要一次将两个新特性PR出去。要添加的特性排好队，一个一个来。
118* 提交之前看，`git diff --check`空定要对 73* 提交之前 `git diff --check` 以下查要提交的格
119* 确定你的代码能通过编译 74* 确定你的代码能通过编译
120 * 局: 确定`make keyboard:your_new_keymap` 不返回错误 75 * 键映: 确定`make keyboard:your_new_keymap` 不返回错误
121 * 键盘: 确定 `make keyboard:all` 不返回错误 76 * 键盘: 确定 `make keyboard:all` 不返回错误
122 * 核心代码: 确定 `make all` 不返回错误 77 * 核心代码: 确定 `make all` 不返回错误
123* 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如: 78* 提交的信息尽量明确。第一行写点简短介绍(每行不多于70个英文字母), 第二行空着,第三行和后面就要写些必要的细节了。最好用英文写，比如:
@@ -130,13 +85,15 @@ The kerpleplork was intermittently failing with error code 23. The root cause wa
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. 85Limited 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``` 86```
132 87
88!> **特别留意：** 若你要对其它QMK使用者提交的代码进行功能修改或尝试修复bug，例如非默认的键映射、用户空间和配列部分，须在PR中标记出代码的原始提交者。很多QMK使用者都会对自己提交的代码在不知晓的情况下产生了改动感到困惑和沮丧，无论他的Git及Github经验丰富与否。
89
133## 文档 90## 文档
134 91
135想帮助Q酱当然是先看文档最简单了。找到这个文档哪里错了然后改正它对于你来说超级简单! 我们也对有写文档能力的人求贤若渴，如果你是对的人[点这个](#Q酱，我在哪能帮助你嘞?)! 92对文档进行修正是最简单的参与贡献的一个办法，找到错误放置的文档或是修复不完备的部分很容易！我们也急需能修订文档的贡献者参与进来，所以如果你具备这样的能力但不清楚如何开始，请[看这里](#我怎样才能做出贡献？)！
136 93
137文档呢，都静静的放在`qmk_firmware/docs` 目录里, 也或者您想为网页做贡献的话也是可以的哦。 94文档位于 `qmk_firmware/docs` 目录下，如果你习惯于在web页面中完成工作目标，可以在 https://docs.qmk.fm/ 各文档页面下方点击“Edit this page”在线进行编辑。
138 95
139在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 把enums的名字都改成像`my_layers`或者`my_keycodes`来防止名字不一致的enums被当作特务枪毙: 96在文档中附代码案例时, 先观察文档其他地方的命名规范。比如, 将enum类型的定义命名为 `my_layers` 或 `my_keycodes` 的形式可以保持前后一致性：
140 97
141```c 98```c
142enum my_layers { 99enum my_layers {
@@ -150,56 +107,69 @@ enum my_keycodes {
150}; 107};
151``` 108```
152 109
153## 布局 110### 预览文档 :id=previewing-the-documentation
154 111
155大多数QMK新手都从创建一个自己的布局开始。我们尽力保证布局规范宽松 (毕竟布局是个性的体现) 不过建议遵守以下准则，这样可以让别人更好理解你的代码 112在发起pull request前，请通过文档预览来检查你的本地更改。可以在 `qmk_firmware/` 目录下执行以下命令来配置文档开发环境：
156 113
157* 用 [模板](documentation_templates.md)写个`readme.md`。 114 qmk docs
158* 所有的布局PR都会被squash, 如果你想知道你的提交是怎么被squash的那你就自己来吧 115
159* 不要把新特性和布局一起PR。可以分别PR他们 116或者，如果你有安装Python 3，可以尝试：
160* 布局文件夹就不要放`Makefile`了，这个操作都过时啦 117
161* 更新文件头部的copyrights(看`%YOUR_NAME%`那) 118 python3 -m http.server 8936 --directory docs
119
120然后在本地浏览器打开 `http://localhost:8936/`.
121
122## 键映射
123
124大多数QMK新手都从创建一个自己的键映射
125开始。我们尽力保证键映射规范宽松 (毕竟键映射体现的是个人喜好) 不过我们仍要求须遵守以下准则，以便他人更好地发现并理解你的键映射代码。
126
127* 使用这份 [模板](zh-cn/documentation_templates.md) 写一份 `readme.md`。
128* 所有的键映射PR都会被压缩处理（squashed，参见[Github文档](https://docs.github.com/cn/github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges)），如果你对commit被压缩很介意，请自行处理
129* 不要把新特性和键映射放在一个PR中。先提交新特性，再通过PR提交键映射
130* 键映射文件夹中不要提交 `Makefile` 文件（已不再使用）
131* 更新头文件中的copyrights信息(看 `%YOUR_NAME%` 部分)
162 132
163## 键盘 133## 键盘
164 134
165QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md`会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。 135QMK的最终归宿是键盘。有些键盘是社区维护的，有一些是制作这些键盘的人维护的。`readme.md` 会告诉你是谁维护了这个键盘，如果你对某个键盘有疑问，可以 [创建一个Issue](https://github.com/qmk/qmk_firmware/issues) 来问一问维护者。
166 136
167我们建议你按下面的来操作: 137我们建议你按下面的来操作:
168 138
169* 用[模板](documentation_templates.md)写`readme.md`。 139* 基于[模板](zh-cn/documentation_templates.md)编写 `readme.md`。
170* 交量尽量合理，不然我们就把你的PR给squash。 140* commit数量尽量合理，则你的PR可能被我们压缩。
171* 不要把新特性和新键盘一起PR。别PR 141* 不要把新特性和新键盘定放在个PR中。新特性，通过PR提键盘定
172* 用父文件夹的名字命名 `.c`/`.h`文件, 比如`/keyboards/<kb1>/<kb2>/<kb2>.[ch]` 142* 用最近一的文件夹的名字命名 `.c`/`.h` 文件, 比如 `/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
173* 键盘文件夹就不要放`Makefile`了，这个操作都过时啦 143* 键盘文件夹就不要放`Makefile`了，这个操作都过时啦
174* 更新文件头部的copyrights(看`%YOUR_NAME%`那) 144* 更新文件头部的copyrights(看`%YOUR_NAME%`那)
175 145
176## Quantum/TMK 核心 146## Quantum/TMK 核心
177 147
178在您废寝忘食地开发Q酱新特性或者帮Q酱驱虫之前，一定要确保你的工作是有意义的。看看[了解QMK](understanding_qmk.md)你会对Q酱有更深的了解，这个文档将带你领略QMK的程序流程。现在你应该和维护团对谈谈来了解实现你想法的最佳方法了。一下渠道都可以： 148在你投入大量精力到新功能开发中之前，请先确保使用了最佳的实现方案。通过阅读[了解QMK](zh-cn/understanding_qmk.md)可以获得对QMK的基本认知，这个文档将带你领略QMK的程序流程，然后你可以和维护团队探讨一下实现你想法的最佳方法的思路，以下渠道都可以：
179 149
180* [在Discord交流](https://discord.gg/Uq7gcHh) 150* [在Discord流](https://discord.gg/Uq7gcHh)
181* [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new) 151* [建立一个Issue](https://github.com/qmk/qmk_firmware/issues/new)
182 152
183新特性和BUG的修复影响所有键盘。开发组也在翻修QMK。所以，在实施重大返修之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。 153新特性和BUG的修复影响所有键盘，开发组也在翻修QMK。所以，在实施重大改动之前一定要讨论一下。如果你在没有事先与维护团队沟通的情况下提交了一个PR，而且你的选择与维护团队的计划方向不符，那你可能要面临大改了。
184 154
185修复BUG或者开发新特性之前看看这个： 155修复BUG或者开发新特性之前看看这个：
186 156
187* **默认不启用** - QMK运行的芯片多数内存有限，所以首要考虑的还应该是布局不要被破坏，于是特性默认是不启用的。你喜欢什么特性的话就打开它，如果你觉得有些特性应该默认开启或者你能帮助缩减代码，那就联系维护组吧。 157* **默认不启用** - QMK运行的芯片多数内存有限，首要考虑的应是已有的键映射不要被破坏，因此你的功能应当是“可以**启用**”的，而不是“可以禁用”的。如果你觉得该特性应该默认开启或者你能帮助缩减代码，请先和我们沟通一下。
188* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 我们的Travis系统会发现一切问题，但是自己编译一下可要比在线等快多了。 158* **提交之前在本地编译** - 这个简直就是家喻户晓了，但是也确实需要编译啊！ 在你发起PR前，请确保任何改动都通过了编译验证。
189* **注意版本和芯片平台** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。试着写一个能AVR和ARM两个平台运行的特性，或者在不支持的平台自动禁用。 159* **注意版本和芯片平台兼容性** - 有那么几个键盘有支持不同配置甚至是不同芯片的版本。请确保你开发的特性同时支持AVR和ARM两个平台，或者在不支持的平台自动禁用。
190* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。 160* **解释你的新特性** - 在`docs/`写个文档, 你可以创建新文档或者写到现有文档中。如果你不把它记录下来，其他人就无法从你的努力中获益。
191 161
192也可以看看以下建议： 162也可以看看以下建议：
193 163
194* 交量尽量合理，不然我们就把你的PR给squash。 164* commit数量尽量合理，则你的PR可能被我们压缩。
195* 不要把新、和键盘一起PR。PR他们。 165* 不要把新键定新键映键改动放在一个PR中。键改。
196* 给你的特性写[单元测试](unit_testing.md)。 166* 给你的特性编写[单元测试](zh-cn/unit_testing.md)。
197* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，你就要先看看[代码规范](#代码规范)确认情况。 167* 你编辑的文件风格要一致，如果风格不明确或者是混搭风的，请先阅读上方的[代码规范](#coding-conventions)。
198 168
199## 重构 169## 重构
200 170
201为了保持QMK脉络清晰，Q酱打算深入规划重构一下自己，然后让合作者进行修改。如果你有重构的思路或建议[创建一个issue](https://github.com/qmk/qmk_firmware/issues), Q酱很乐意讨论一下怎么改进一下。 171为了保持QMK脉络清晰，QMK的深度重构工作已在规划中，并会通过合作者进行相应的修改。如果你有重构的思路或建议请[创建一个issue](https://github.com/qmk/qmk_firmware/issues), 我们很乐意讨论一下QMK可以如何改进。
202 172
203# 行为守则对于我来说有何意义? 173# 行为守则对于我来说有何意义？ :id=what-does-the-code-of-conduct-mean-for-me
204 174
205我们的[行为守则](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) 是说明您有责任尊重和礼貌地对待项目中的每个人，无论他们的身份如何。 如果你是我们行为准则所描述的不当行为的受害者，我们将站在你这边，并按照行为准则对施暴者进行适当谴责。 175我们的[行为守则](https://qmk.fm/coc/) 指出您有责任尊重并礼貌地对待项目中的每个人，无论他们的身份如何。如果你是我们行为守则所描述的不当行为的受害者，我们将站在你这边，尽最大努力对施暴者进行谴责。
diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md
index 1ae996e39..29c508905 100644
--- a/docs/zh-cn/custom_quantum_functions.md
+++ b/docs/zh-cn/custom_quantum_functions.md
@@ -1,31 +1,35 @@
1# 如何定制你键盘的功能 1# 如何定制化键盘功能
2 2
3对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。 3<!---
4 original document: 0.15.12:docs/custom_quantum_functions.md
5 git diff 0.15.12 HEAD -- docs/custom_quantum_functions.md | cat
6-->
4 7
5本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。 8对于很多人来说对客制化键盘的诉求不只是向电脑输入按下的键。你肯定想实现比简单按键和宏更复杂的功能。QMK支持基于注入点的代码注入，功能重写，另外还可以自定义键盘在不同情况下的行为。
6 9
7## A Word on Core vs 键盘 vs 布局 10本页不要求任何额外的QMK知识基础，但阅读[理解QMK](zh-cn/understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
8 11
9我们把qmk组织成一个层次结构： 12## 核心/键盘/键映射的概念 :id=a-word-on-core-vs-keyboards-vs-keymap
13
14QMK基于如下层级组成：
10 15
11* Core (`_quantum`) 16* Core (`_quantum`)
12 * Keyboard/Revision (`_kb`) 17 * Keyboard/Revision (`_kb`)
13 * Keymap (`_user`) 18 * Keymap (`_user`)
14 19
15下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。 20该文后续部分所提及的函数在定义时皆可添加 `_kb()` 或 `_user()` 后缀，我们建议在键盘及其子版本中使用 `_kb()` 后缀，而在键映射中使用 `_user()` 后缀。
16 21
17在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。 22在键盘及其子版本中定义函数时，一个重要的点是在 `_kb()` 函数执行任何逻辑前，应先调用 `_user()` 函数，否则这些键映射中的函数将没有机会被执行。
18<!-- 翻译问题：上面那句翻译的不太好-->
19# 自定义键码 23# 自定义键码
20 24
21到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。 25到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。
22 26
23## 定义一个新键码 27## 定义一个新键码
24 28
25创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。 29创建键码的第一步，是先定义其枚举值，也就是给键码起个名字并分配一个唯一值。QMK没有直接限制最大可用的键码值，而是提供了一个 `SAFE_RANGE` 宏。你可以在定义枚举时用 `SAFE_RANGE` 来保证你取得了唯一的键码值。
26 30
27 31
28这有枚举两个键码的例子。把这块加到`keymap.c`的话你就在布局中能用`FOO`和`BAR`了。 32这有定义两个键码的枚举值的例子。添加以下代码块至 `keymap.c` 后你就可以在布局中使用 `FOO` 和 `BAR` 了。
29 33
30```c 34```c
31enum my_keycodes { 35enum my_keycodes {
@@ -34,15 +38,15 @@ enum my_keycodes {
34}; 38};
35``` 39```
36 40
37## 键码的行为编程 41## 编程设计的键码的行为 :id=programming-the-behavior-of-any-keycode
38 42
39当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。 43当你覆盖一个已存在按键的行为时，或是给新按键设计功能时，请使用 `process_record_kb()` 和 `process_record_user()` 函数。QMK会在响应并处理按键事件前调用这些函数，如果这些函数返回值为 `true`，QMK将继续用常规的方式处理键码，这样可以很方便的扩展键码的功能而不需要替换代码实现。如果函数返回`false` QMK会跳过常规的键处理逻辑，需要发送的按键按下或抬起事件则需交由你负责完成。
40 44
41当某键按下或释时这俩函会用。 45意按键在按下或起时，次都会调用这些函数。
42 46
43### process_record_user()`示例实现 47### process_record_user()` 示例
44 48
45这个例子做了两个事。自定义了一个叫做`FOO`的键码的行为，并补充了在按下回车时播放音符。 49这个例子做了两个事。自定义了一个叫做 `FOO` 的键码的行为，并提供了在按下回车时播放音符的功能。
46 50
47```c 51```c
48bool process_record_user(uint16_t keycode, keyrecord_t *record) { 52bool process_record_user(uint16_t keycode, keyrecord_t *record) {
@@ -51,7 +55,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
51 if (record->event.pressed) { 55 if (record->event.pressed) {
52 // 按下时做些什么 56 // 按下时做些什么
53 } else { 57 } else {
54 // 释时做些什么 58 // 起时做些什么
55 } 59 }
56 return false; // 跳过此键的所有进一步处理 60 return false; // 跳过此键的所有进一步处理
57 case KC_ENTER: 61 case KC_ENTER:
@@ -59,21 +63,21 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
59 if (record->event.pressed) { 63 if (record->event.pressed) {
60 PLAY_SONG(tone_qwerty); 64 PLAY_SONG(tone_qwerty);
61 } 65 }
62 return true; // 让QMK触回车按下/释事件 66 return true; // 让QMK车按下/起事件
63 default: 67 default:
64 return true; // 正常理其他键码 68 return true; // 正常他键码
65 } 69 }
66} 70}
67``` 71```
68 72
69### `process_record_*` 文档 73### `process_record_*` 示例
70 74
71* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)` 75* 键盘/各子版本：`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
72* 局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)` 76* 键映：`bool process_record_user(uint16_t keycode, keyrecord_t *record)`
73 77
74`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。 78`keycode` 参数为键映射中形如 `MO(1)`，`KC_L` 等定义的键值项。 应使用 `switch...case` 代码块来处理这些事件。
75 79
76`record`参数含有实际按键的信息： 80`record` 参数含有按键的真实状态信息：
77 81
78```c 82```c
79keyrecord_t record { 83keyrecord_t record {
@@ -88,108 +92,31 @@ keyrecord_t record {
88} 92}
89``` 93```
90 94
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# 键盘初始化代码 95# 键盘初始化代码
169 96
170键盘初始化过程有几个步骤你是那个数取你想要么。 97键盘初始化过程须经过几个步骤，你目的决定你需要注哪函数。
171 98
172有三个主要初始化函数，按调用顺序列出。 99有三个主要初始化函数，按调用顺序列出。
173 100
174* `keyboard_pre_init_*` - 会在大多数其他东西运行前运行。适用于哪些需要提前运行的硬件初始化。 101* `keyboard_pre_init_*` - 会在大多数其他功能运行前执行。适用于那些需要尽早执行的硬件初始化工作。
175* `matrix_init_*` - 在固件启动过程中间被调用。此时硬件已初始化，功能未初始化。 102* `matrix_init_*` - 在固件启动过程中被调用。此时硬件已初始化，但部能还不用。
176* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。 103* `keyboard_post_init_*` - 在固件启动过程的最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
177 104
178!> 对于大多数人来说`keyboard_post_init_user`是你想要调用的函数。例如, 此时你可以设置RGB灯发光。 105!> 对于大多数人来说 `keyboard_post_init_user` 是你想要关注的函数。例如, 你可以在这里启动RGB背光灯。
179 106
180## 键盘预初始化代码 107## 键盘预初始化代码
181 108
182这代码早运行，甚至都在USB前运行。 109这部分代码行的常早，甚至是在USB通信能之前。
183 110
184在这之后不久矩阵被始化了。 111在这之后不久即会完成矩阵的初始化。
185 112
186对于大多数用户来说,这用不，因为它主要是用于面向硬件的初始化。 113对于大多数用户来说不在此处进行修改，因为它主要用于硬件初始化。
187 114
188但如果你有硬件初始化的话放在这里再好不过了(比如初始化LED引脚一类的). 115但如果你有硬件须初始化的话放在这里再好不过了（比如初始化LED引脚）.
189 116
190### `keyboard_pre_init_user()`示例实现 117### `keyboard_pre_init_user()` 示例
191 118
192本例中在键盘级，设 B0, B1, B2, B3, 和 B4 是LED引脚。 119本例中，在键盘 B0, B1, B2, B3, 和 B4 引脚设置为LED引脚。
193 120
194```c 121```c
195void keyboard_pre_init_user(void) { 122void keyboard_pre_init_user(void) {
@@ -206,95 +133,110 @@ void keyboard_pre_init_user(void) {
206 133
207### `keyboard_pre_init_*` 函数文档 134### `keyboard_pre_init_*` 函数文档
208 135
209* 键盘/修订: `void keyboard_pre_init_kb(void)` 136* 键盘/各子版本：`void keyboard_pre_init_kb(void)`
210* 局: `void keyboard_pre_init_user(void)` 137* 键映：`void keyboard_pre_init_user(void)`
211 138
212## 矩阵初始化代码 139## 矩阵初始化代码
213 140
214这会矩阵初始化时被调用，在硬件设置，但在一些功能被初始化前。 141在矩阵初始化后被调用。时部分硬件已设置，但一些功能未完始化。
215 142
216这你设置地方会用到西的时很有用，硬件无关，的置。 143此用来设一与硬件无关，对始没有殊要求。
217 144
218 145
219### `matrix_init_*`函数文档 146### `matrix_init_*` 函数文档
220 147
221* 键盘/修订: `void matrix_init_kb(void)` 148* 键盘/各子版本：`void matrix_init_kb(void)`
222* 局: `void matrix_init_user(void)` 149* 键映：`void matrix_init_user(void)`
223 150
151### 低级矩阵函数的重写 :id=low-level-matrix-overrides
224 152
225## 键盘后初始化代码 153* GPIO引脚初始化：`void matrix_init_pins(void)`
154 * 此处须完成低级行列引脚的初始化。默认实现中，这里会参考可选的键盘设置项 `ROW2COL`，`COL2ROW` 及 `DIRECT_PINS` 来初始化所有 `MATRIX_ROW_PINS` 及 `MATRIX_COL_PINS` 中定义的GPIO引脚的输入/输出状态。当键盘设计者重写该函数后，QMK本身不会进行任何引脚的初始化，只会听从重写的函数的实现逻辑。
155* `COL2ROW`-从行中读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
156* `ROW2COL`-从列中读: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)`
157* `DIRECT_PINS`-直读: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)`
158 * 以上三个函数须参考矩阵类别，从底层矩阵的相关引脚状态中获取输入信息，并且应该只需要实现三者之一。默认情况下，在遍历 `MATRIX_ROW_PINS` and `MATRIX_COL_PINS` 时，会根据是否设置了 `ROW2COL`，`COL2ROW` 或 `DIRECT_PINS` 来配置输入输出方式。当键盘设计者重写该函数后，QMK本身不会进行任何矩阵GPIO引脚状态的变更，只会听从重写的函数的实现逻辑。
226 159
227这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。 160## 键盘后初始化代码
228 161
162这是键盘初始化过程中的最后一个任务。此时您可以配置并调整某些特性，因为此时这些特性已初始化完毕。
229 163
230### `keyboard_post_init_user()`示例实现 164### `keyboard_post_init_user()` 实现示例
231 165
232本示例在所有初始化完成后运行，配置RGB灯。 166本示例在所有初始化完成后运行，配置RGB背光。
233 167
234```c 168```c
235void keyboard_post_init_user(void) { 169void keyboard_post_init_user(void) {
236 // 调用后初始化代码 170 // 调用后初始化代码
237 rgblight_enable_noeeprom(); // 使能Rgb，不保存设置 171 rgblight_enable_noeeprom(); // 使能Rgb，不保存设置
238 rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)不保存 172 rgblight_sethsv_noeeprom(180, 255, 255); // 将颜色设置到蓝绿色(青色)，不保存设置
239 rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式不保存 173 rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 设置快速呼吸模式，不保存设置
240} 174}
241``` 175```
242 176
243### `keyboard_post_init_*` 函数文档 177### `keyboard_post_init_*` 函数文档
244 178
245* 键盘/修订: `void keyboard_post_init_kb(void)` 179* 键盘/各子版本：`void keyboard_post_init_kb(void)`
246* 布局: `void keyboard_post_init_user(void)` 180* 布局: `void keyboard_post_init_user(void)`
247 181
248# 矩阵扫描代码 182# 矩阵扫描码
249 183
250可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。 184应尽量使用 `process_record_*()` 实现所需的键盘自定义以及事件监听，以确保这些代码不会对键盘性能产生负面的影响。然而，在极少数情况下需要在矩阵扫描中添加监听，此时需要极端留意这些函数代码的性能表现，因为这些函数每秒可能被执行十数次。
251 185
252### `matrix_scan_*`示例实现 186### `matrix_scan_*` 实现示例
253 187
254这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh). 188这个例子被故意省略了。在监听处理这样一个对性能及其敏感的部分之前，您应该足够了解qmk的内部结构，才可以在没有示例的情况下编写。如果你需要帮助，请[新建一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
255 189
256### `matrix_scan_*` 函数文档 190### `matrix_scan_*` 函数文档
257 191
258* 键盘/修订: `void matrix_scan_kb(void)` 192* 键盘/各子版本：`void matrix_scan_kb(void)`
259* 布局: `void matrix_scan_user(void)` 193* 布局: `void matrix_scan_user(void)`
260 194
261该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。 195该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。
262 196
263你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。 197在需要自定义矩阵扫描代码时可以使用该函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户没有输入时你也想定期运行的功能。
198
199# Keyboard housekeeping
200
201* 键盘/各子版本：`void housekeeping_task_kb(void)`
202* 键映射：`void housekeeping_task_user(void)`
203
204该函数在所有QMK处理工作完毕后，下一轮开始执行前被执行。可以放心地假设此时QMK已对最新的矩阵扫描结果完成了所有的处理工作 -- 更新层状态，发送USB事件，更新LED状态，刷新显示屏。
264 205
206与 `matrix_scan_*` 类似，这些函数会频繁调用直至MCU处理能力上限。为了确保键盘的响应能力，建议在这些函数中尽量做最少的事情，在你确实需要在这里实现特别的功能时，可能会影响到其它功能的表现。
265 207
266# 键盘 空闲/唤醒 代码 208# 键盘 空闲/唤醒 代码
267 209
268如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。 210在主控板支持情况下，暂停大部分功能可以实现“空闲”状态，例如RGB灯光和背光。既可以节省电量消耗，也可能增强键盘的表现。
269 211
270两个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, 分别在统板空闲和唤醒时调用。 212这两个函数控制: `suspend_power_down_*` 和 `suspend_wakeup_init_*`，分别在空闲和唤醒时用。
271 213
272 214
273### suspend_power_down_user()和suspend_wakeup_init_user()例实现 215### suspend_power_down_user() 和 suspend_wakeup_init_user() 实现示例
274 216
275 217
276```c 218```c
277void suspend_power_down_user(void) { 219void suspend_power_down_user(void) {
278 // code will run multiple times while keyboard is suspended 220 // 当键盘挂起时会被多次调用的代码
279} 221}
280 222
281void suspend_wakeup_init_user(void) { 223void suspend_wakeup_init_user(void) {
282 // code will run on keyboard wakeup 224 // 键盘唤醒时被调用的代码
283} 225}
284``` 226```
285 227
286### 键盘 挂起/唤醒 函数文档 228### 键盘 挂起/唤醒 函数文档
287 229
288* 键盘/修订: `void suspend_power_down_kb(void)` 和`void suspend_wakeup_init_user(void)` 230* 键盘/各子版本：`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)` 231* 键映：`void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
290 232
291# 层改代码 233# 层换代码 :id=layer-change-code
292 234
293每当层改这个行代码。这于层或自定义层处理有用。 235每当层生换时执行，用于感知层换件，或自定义层处理逻。
294 236
295### `layer_state_set_*` 示例实现 237### `layer_state_set_*` 实现示例
296 238
297本例用了Planck键盘示范了如何设置 [RGB背光灯](feature_rgblight.md)与层应 239本例，通Planck键盘示范了如何将[RGB背光灯](zh-cn/feature_rgblight.md)设与层步。
298 240
299```c 241```c
300layer_state_t layer_state_set_user(layer_state_t state) { 242layer_state_t layer_state_set_user(layer_state_t state) {
@@ -311,36 +253,41 @@ layer_state_t layer_state_set_user(layer_state_t state) {
311 case _ADJUST: 253 case _ADJUST:
312 rgblight_setrgb (0x7A, 0x00, 0xFF); 254 rgblight_setrgb (0x7A, 0x00, 0xFF);
313 break; 255 break;
314 default: // for any other layers, or the default layer 256 default: // 默认层及其它层
315 rgblight_setrgb (0x00, 0xFF, 0xFF); 257 rgblight_setrgb (0x00, 0xFF, 0xFF);
316 break; 258 break;
317 } 259 }
318 return state; 260 return state;
319} 261}
320``` 262```
263
264可以通过 `IS_LAYER_ON_STATE(state, layer)` 和 `IS_LAYER_OFF_STATE(state, layer)` 宏来确认常规层的状态。
265
266如果不在 `layer_state_set_*` 函数中，可以通过 `IS_LAYER_ON(layer)` 和 `IS_LAYER_OFF(layer)` 宏来确认全局的层状态。
267
321### `layer_state_set_*` 函数文档 268### `layer_state_set_*` 函数文档
322 269
323* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)` 270* 键盘/各子版本：`uint32_t layer_state_set_kb(uint32_t state)`
324* 布局: `layer_state_t layer_state_set_user(layer_state_t state)` 271* 布局: `layer_state_t layer_state_set_user(layer_state_t state)`
325 272
326 273
327该`状`的bitmask, 详见[局概述](keymap.md#布局的层状态) 274处的 `state` 为当前活跃层的位掩码, 详见[键映概述](zh-cn/keymap.md#keymap-layer-status)
328 275
329 276
330# 掉电保存配置 (EEPROM) 277# 配置的持久存储（EEPROM）
331 278
332这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。 279该功能可以让键盘的配置持久存储下来。这些配置存储在控制器的EEPROM中，即便掉电后依旧可以留存下来。可以通过 `eeconfig_read_kb` 和 `eeconfig_read_user` 来读取，通过 `eeconfig_update_kb` and `eeconfig_update_user` 来进行保存。该功能常用于保存一些开关状态（比如rgb层指示灯）。此外，可以通过 `eeconfig_init_kb` 和 `eeconfig_init_user` 来设置EEPROM的默认配置值。
333 280
334最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。 281复杂的地方是，有很多方法可以存储和访问EEPROM数据，并且没有哪种方法是“正确”的。但是，每个功能只有一个双字(四字节)空间可用。
335 282
336记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。 283记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有这些配置信息会写到EEPROM中。如果你写入过于频繁，你的MCU寿命将会急速减少。
337 284
338* 如果您不理解这个例子，那么您可能望避使用这个特性，因为它相当复杂。 285* 如果您不理解这个例子，那么您可以使用这个特性，因为它相当复杂。
339 286
340### 示例实现 287### 实现示例
341
342本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！
343 288
289本例讲解了如何添加并读写设置项。本例使用用户键映射来实现。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多前述的函数来工作！
290（译注：该示例由于英文行文，可能会觉得看得稀里糊涂。实现的功能很简单，即开启了层指示功能（RGB_LYR）时，rgb背光灯会展示当前层的特定颜色用以指示层状态，而触发任何改变rgb背光颜色的键码时，rgb背光灯将回归普通的背光灯角色，不再作为层指示器）
344 291
345在你的keymap.c文件中，将以下代码添加至顶部: 292在你的keymap.c文件中，将以下代码添加至顶部:
346```c 293```c
@@ -354,14 +301,14 @@ typedef union {
354user_config_t user_config; 301user_config_t user_config;
355``` 302```
356 303
357以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。 304以上代码建立了一个32位的结构体，用于在内存及EEPROM中存储配置项。此时不再需要再单独声明变量，因为都已经在该结构体中定义了。须记住 `bool`（布尔）值占用1位，`uint8_t` 占用8位，`uint16_t` 占用16位。你可以混合搭配使用，但改变这些顺序会因为错误的读写而招致问题。
358 305
359 `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。 306我们在 `layer_state_set_*` 函数中会使用 `rgb_layer_change`。通过 `keyboard_post_init_user` 和 `process_record_user` 来配置所需的一切。
360 307
361首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样： 308在编写 `keyboard_post_init_user` 时，你需要使用 `eeconfig_read_user()` 来计算并填充你刚刚创建的结构体。然后即可以使用结构体数据来控制键映射中的功能。就像这样：
362```c 309```c
363void keyboard_post_init_user(void) { 310void keyboard_post_init_user(void) {
364 // 调用局级别的矩阵初始化 311 // 调用键映级别的矩阵初始化
365 312
366 // 从EEPROM读用户配置 313 // 从EEPROM读用户配置
367 user_config.raw = eeconfig_read_user(); 314 user_config.raw = eeconfig_read_user();
@@ -374,7 +321,7 @@ void keyboard_post_init_user(void) {
374 } 321 }
375} 322}
376``` 323```
377以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 324以上函数会在读EEPROM配置后立即设置默认层的RGB颜色。"raw"值将被转换为上述创建的实际使用的"union"结构体。
378 325
379```c 326```c
380layer_state_t layer_state_set_user(layer_state_t state) { 327layer_state_t layer_state_set_user(layer_state_t state) {
@@ -398,7 +345,7 @@ layer_state_t layer_state_set_user(layer_state_t state) {
398 return state; 345 return state;
399} 346}
400``` 347```
401这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为： 348这样仅在相关值使能时才会改变RGB背光灯。若要配置该值, 为 `process_record_user` 创建一个新键码 `RGB_LYR`。此时我们想实现的是，如果触发了常规的RGB码，以上示例中的逻辑都将不生效，形如：
402```c 349```c
403 350
404bool process_record_user(uint16_t keycode, keyrecord_t *record) { 351bool process_record_user(uint16_t keycode, keyrecord_t *record) {
@@ -407,7 +354,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
407 if (record->event.pressed) { 354 if (record->event.pressed) {
408 // 按下时做点什么 355 // 按下时做点什么
409 } else { 356 } else {
410 // 释时做点什么 357 // 起时做点什么
411 } 358 }
412 return false; // 跳过此键的进一步处理 359 return false; // 跳过此键的进一步处理
413 case KC_ENTER: 360 case KC_ENTER:
@@ -415,76 +362,116 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
415 if (record->event.pressed) { 362 if (record->event.pressed) {
416 PLAY_SONG(tone_qwerty); 363 PLAY_SONG(tone_qwerty);
417 } 364 }
418 return true; // 让QMK产生回车按下/释事件 365 return true; // 让QMK产生回车按下/起事件
419 case RGB_LYR: // underglow作为层指示，或正常使用 366 case RGB_LYR: // 这允许光灯作为层指示，或正常用
420 if (record->event.pressed) { 367 if (record->event.pressed) {
421 user_config.rgb_layer_change ^= 1; // 切换状态 368 user_config.rgb_layer_change ^= 1; // 切换状态
422 eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态 369 eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态
423 if (user_config.rgb_layer_change) { // 如果层态被使能 370 if (user_config.rgb_layer_change) { // 如果层指使能
424 layer_state_set(layer_state); // 那么立刻更新层颜色 371 layer_state_set(layer_state); // 那么立刻更新层颜色
425 } 372 }
426 } 373 }
427 return false; 374 return false;
428 case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参) 375 case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (参考 quantum_keycodes.h, 400 处)
429 if (record->event.pressed) { //本句失能层指示，假设你了个…你要把它禁用 376 if (record->event.pressed) { // 本句失能层指示功能，假设你现在要调该…你要把它禁用
430 if (user_config.rgb_layer_change) { // 仅当使能时 377 if (user_config.rgb_layer_change) { // 仅当使能时
431 user_config.rgb_layer_change = false; // 失能，然后 378 user_config.rgb_layer_change = false; // 失能，然后
432 eeconfig_update_user(user_config.raw); // 向EEPROM写入设置 379 eeconfig_update_user(user_config.raw); // 向EEPROM写入设置
433 } 380 }
434 } 381 }
435 return true; break; 382 return true; break;
436 default: 383 default:
437 return true; // 按其他键正常 384 return true; // 其他键码正常处理
438 } 385 }
439} 386}
440``` 387```
441最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值 388最后，须添加 `eeconfig_init_user` 函数，从而当EEPROM重置时，可以指定默认值, 甚至自定义操作。若想强制重置EEPROM，请用 `EEP_RST` 键码或[Bootmagic](zh-cn/feature_bootmagic.md) 功能。比如，在你想重置RGB层指示配置，并保存默认值时。
442 389
443```c 390```c
444void eeconfig_init_user(void) { // EEPROM正被重置 391void eeconfig_init_user(void) { // EEPROM被重置
445 user_config.raw = 0; 392 user_config.raw = 0;
446 user_config.rgb_layer_change = true; // 我们想要默认使能 393 user_config.rgb_layer_change = true; // 我们想要默认使能
447 eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值 394 eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值
448 395
449 // use the non noeeprom versions, 还要EEPROM写入这些 396 // 通过使用非'noeeprom'版本的数，可以时写入这些配置EEPROM中
450 rgblight_enable(); // 默认使能RGB 397 rgblight_enable(); // 默认使能RGB
451 rgblight_sethsv_cyan(); // 默认设置青色 398 rgblight_sethsv_cyan(); // 默认设置青色
452 rgblight_mode(1); // 默认设置长亮 399 rgblight_mode(1); // 默认设置长亮
453} 400}
454``` 401```
455 402
456然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。 403一切已就绪，RGB层指示将在需要时生效。这个设置会持久存储，即便是拔下键盘。如果你使用其他RGB码，层指示将失效，从而可以停留在期望的模式及颜色下。
457 404
458### 'EECONFIG' 函数文档 405### 'EECONFIG' 函数文档
459 406
460* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)` 407* 键盘/各子版本：`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)` 408* 键映射：`void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` 和 `void eeconfig_update_user(uint32_t val)`
462 409
463`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。 410`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会从EEPROM返回一个32位(双字)的值。
464 411
465# 自定义击键-长按临界值(TAPPING_TERM) 412### 定时执行 :id=deferred-execution
466默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。
467
468想使能这个功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。
469 413
414QMK支持在特定时间间隔后执行回调，以代替手动的计时器管理。
470 415
471## `get_tapping_term`示例实 416#### 时函数
472 417
473要修基于键`TAPPING TERM`,要`keymap.c`件如下代码: 418的 _定时回调函数_ 用的签，如下：
474 419
475```c 420```c
476uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { 421uint32_t my_callback(uint32_t trigger_time, void *cb_arg) {
477 switch (keycode) { 422 /* 处理了一些工作 */
478 case SFT_T(KC_SPC): 423 bool repeat = my_deferred_functionality();
479 return TAPPING_TERM + 1250; 424 return repeat ? 500 : 0;
480 case LT(1, KC_GRV):
481 return 130;
482 default:
483 return TAPPING_TERM;
484 }
485} 425}
486``` 426```
487 427
488### `get_tapping_term` 函数文档 428第一个参数 `trigger_time` 为预期的执行时间，如果因为其它事情造成了延迟未能在准确的时间点执行，可以利用这个参数“追赶”或者跳过这次间隔，取决于你的目的是什么。
429
430第二个参数 `cb_arg` 为下述的 `defer_exec()` 传入的参数，由此可以获取调用时的状态信息。
431
432返回值为该函数下一次期望被回调的时间间隔毫秒数 -- 若返回 `0` 则会自动被注销掉。上例中，通过执行假想的 `my_deferred_functionality()` 函数来决策回调是否继续下去 -- 若是，则给出一个 `500` 毫秒的延迟计划，否则，返回 `0` 来告知定时处理后台任务该计划已执行完毕。
433
434?> 须留意返回的延时时间是相对原定的触发时间点的，而不是回调执行完的时间点。这样可以防止偶发的执行延迟影响稳定的定时事件计划。
435
436#### 注册定时回调
437
438在定义好回调后，通过如下API进行定时回调注册：
439
440```c
441deferred_token my_token = defer_exec(1500, my_callback, NULL);
442```
443
444第一个参数为执行 `my_callback` 的毫秒时间延迟 -- 上例中为 `1500` 毫秒，即 1.5 秒。
445
446第三个参数为回调执行时传入的 `cb_arg` 参数。须确保该值在回调时依旧有效 -- 局部函数内的变量会在回调执行前就被释放掉因此不能用。如果并不需要这个参数，可以传入 `NULL`。
447
448返回值 `deferred_token` 可被用于在回调执行前取消该定时计划。如果该函数调用失败，会返回 `INVALID_DEFERRED_TOKEN`，一般错误原因是延时值被设置为 `0` 或回调函数参数为 `NULL`，还有一种可能是已有过量的回调在等待被处理 -- 可以按照下述方法修改这个阈值。
449
450#### 延长定时回调时间
451
452由 `defer_exec()` 返回的 `deferred_token` 可以用来修改回调执行所需等待的时延值：
453```c
454// 重新调整 my_token 后续的执行计划为当前时间起800ms后
455extend_deferred_exec(my_token, 800);
456```
457
458#### 取消定时回调
459
460由 `defer_exec()` 返回的 `deferred_token` 可以用来取消掉后续的执行计划：
461```c
462// 取消 my_token 的后续回调
463cancel_deferred_exec(my_token);
464```
465
466一旦 token 被取消了，即视为不再可用。重新使用该 token 是不支持的。
467
468#### 定时回调的限制
469
470可安排的定时回调计划数量是有限的，由 `MAX_DEFERRED_EXECUTORS` 定义的值确定。
471
472如果定时回调注册失败了，可以在对应的键盘或键映射下的 `config.h` 文件中修改该值，比如将默认的 8 改为 16：
473
474```c
475#define MAX_DEFERRED_EXECUTORS 16
476```
489 477
490不像这篇的其他功能,这个不需要quantum或者键盘级别的函数，只要用户级函数即可。
diff --git a/docs/zh-cn/driver_installation_zadig.md b/docs/zh-cn/driver_installation_zadig.md
new file mode 100644
index 000000000..db9bb9a3f
--- /dev/null
+++ b/docs/zh-cn/driver_installation_zadig.md
@@ -0,0 +1,102 @@
1# 利用Zadig安装Bootloader驱动
2
3<!---
4 original document: 0.15.12:docs/driver_installation_zadig.md
5 git diff 0.15.12 HEAD -- docs/driver_installation_zadig.md | cat
6-->
7
8QMK在主机侧会展现为一台HID键盘设备，因此不需要额外的驱动。但若要在Windows下刷写键盘固件，重置主控板时出现的bootloader设备则通常需要一些驱动程序。
9
10已知的特例有两个：常见于Pro Micro的Caterina bootloader，以及PJRC Teensys上的HalfKay bootloader, 会同时提供一个串行端口设备及一个HID设备，因此不需要额外的驱动。
11
12这里我们推荐使用[Zadig](https://zadig.akeo.ie/)工具软件。若你在MSYS2中配置了开发环境，`qmk_install.sh` 脚本已经替你安装了相关驱动。
13
14## 安装
15
16将键盘重置为bootloader模式，点击 `RESET` 键码（可能在别的层中），或按一下通常在主控板背面上的重置开关，如果你的键盘上没有前两者，尝试在按住Esc键或空格+`B`键时插上键盘（更多信息参见[Bootmagic](zh-cn/feature_bootmagic.md)）。有些键盘使用[指令](zh-cn/feature_command.md)功能来代替Bootmagic，这种情况下，可以在键盘插入状态下点击 左Shift+右Shift+`B` 或 左Shift+右Shift+Esc组合键来进入bootloader模式。
17也有一些键盘需要特别的操作才能进入bootloader状态。例如，[Bootmagic](zh-cn/feature_bootmagic.md)键（默认为：Esc键）在其它键上，比如左Control；或是指令组合键（默认为：左Shift+右Shift）为其它组合，如左Control+右Control。当不确定的时候，可以查阅一下主控板的README文件。
18
19若要将USBaspLoader设备置为bootloader模式，请在按住 `BOOT` 按钮时点击 `RESET` 按钮，或是在按住 `BOOT` 按钮时插入USB线缆。
20
21Zadig可以自动检测到bootloader设备，但有时你需要在 **Options（选项） → List All Devices（列出所有设备）** 的下拉列表中选择正确的设备。
22
23!> 如果Zadig中列出的一个或多个设备为 `HidUsb` 驱动的，那么你的键盘应该没有进入bootloader模式，此时箭头会标记成橙色并会询问你确认是否要修改系统驱动，此时**不要**允许该操作。
24
25如果箭头呈现绿色，选择所需的驱动，点击**Install Driver（安装驱动）**。如何选择正确的驱动进行安装请参见[已知驱动列表](#list-of-known-bootloaders)。
26
27![在Zadig中安装了正确的bootloader驱动](https://i.imgur.com/b8VgXzx.png)
28
29最后，重新拔插一次键盘，确认驱动可以正常加载。如果你在使用QMK工具箱进行刷写，记得也重启一下，因为有时它不会检测到驱动的变化。
30
31## 从错误的驱动安装中恢复
32
33如果你发现键盘无法输入了，应当是因为错误地替换了键盘本身的驱动，而不是bootloader的驱动，你的键盘没有进入bootloader模式就进行安装时就会遇到这个问题。在Zadig中很容易看出这个问题 - 正常的键盘在其所有的接口上都应该有 `HidUsb` 驱动：
34
35![在Zadig中的一个正常的键盘](https://i.imgur.com/Hx0E5kC.png)
36
37打开Device Manager（设备管理器），选择**View（查看） → Devices by container（依类型排序设备）**，并定位到你键盘名所在的节点。
38
39![在设备管理器中安装了错误的驱动的主控板](https://i.imgur.com/o7WLvBl.png)
40
41在这些节点上右键，选择**Uninstall device（卸载）**。如果出现了**Delete the driver software for this device（同时卸载该设备驱动文件）**也请勾选上。
42
43![设备卸载确认对话框，选中了“删除驱动文件”](https://i.imgur.com/aEs2RuA.png)
44
45点击 **Action（操作） → Scan for hardware changes（扫描检测硬件改动）**。此时，键盘应该恢复可用状态了。再确认一下Zadig中键盘是否在使用 `HidUsb` 驱动，如果是，键盘即完全恢复可用状态了，如果不是，重复这一步直到Zadig中报告了正确的驱动。
46
47?> 在这一步有时需要重启电脑，以便Windows可以选用新驱动文件。
48
49## 卸载
50
51卸载bootloadeer设备要比安装过程复杂一些。
52
53打开设备管理器，选择**查看 → 依类型排序设备**，并找到bootloader设备，寻找USB VID和PID与Zadig的[该表格](#list-of-known-bootloaders)中一致的项。
54
55在设备属性的详细信息tab中，找到 `Inf name（INF名称）` 值，通常该值类似于 `oemXX.inf`：
56
57![设备属性中的INF名称值](https://i.imgur.com/Bu4mk9m.png)
58
59之后使用管理员权限打开一个命令行窗口（在开始菜单处输出 `cmd` 并点击Ctrl+Shift+回车）。执行 `pnputil /enum-drivers` 并找到 `INF名称` 与 `Published Name（发布名称）` 一致的项：
60
61![对pnputil输出中匹配驱动项进行高亮展示](https://i.imgur.com/3RrSjzW.png)
62
63执行 `pnputil /delete-driver oemXX.inf /uninstall`，之后该驱动会被删除，相关设备也不再使用该驱动，但设备是不会被移除的。
64
65与上一节相似，本流程也可能需要执行多次，因为一个设备可能会有多个可用的驱动。
66
67!> **警告：** 操作过程中*务必非常小心*！以免不小心卸载掉其它关键驱动。如果你对操作不是很确定，多次检查 `/enum-drivers`的输出信息，也可以考虑执行 `/delete-driver` 时不添加 `/uninstall` 开关\。
68
69## 已知驱动列表 :id=list-of-known-bootloaders
70
71该表列出了已知的bootloader设备及其USB VID（厂商ID）和PID（产品ID），以及可用于QMK刷写固件的驱动。留意usbser及HidUsb驱动是随Windows附带的，无法通过Zadig安装 - 如果你的设备驱动不符，请参照上节来卸载这些驱动。
72
73此处列出的设备名应与Zadig中的一致，但不一定与设备管理器及QMK工具箱展示的一致。
74
75|Bootloader |设备名 |VID/PID |驱动 |
76|--------------|------------------------------|--------------|-------|
77|`atmel-dfu` |ATmega16u2 DFU |`03EB:2FEF` |libusb0|
78|`atmel-dfu` |ATmega32U2 DFU |`03EB:2FF0` |libusb0|
79|`atmel-dfu` |ATm16U4 DFU V1.0.2 |`03EB:2FF3` |libusb0|
80|`atmel-dfu` |ATm32U4DFU |`03EB:2FF4` |libusb0|
81|`atmel-dfu` |*none* (AT90USB64) |`03EB:2FF9` |libusb0|
82|`atmel-dfu` |AT90USB128 DFU |`03EB:2FFB` |libusb0|
83|`qmk-dfu` |(键盘名) Bootloader |同`atmel-dfu` |libusb0|
84|`halfkay` |*none* |`16C0:0478` |HidUsb |
85|`caterina` |Pro Micro 3.3V |`1B4F:9203` |usbser |
86|`caterina` |Pro Micro 5V |`1B4F:9205` |usbser |
87|`caterina` |LilyPadUSB |`1B4F:9207` |usbser |
88|`caterina` |Pololu A-Star 32U4 Bootloader |`1FFB:0101` |usbser |
89|`caterina` |Arduino Leonardo |`2341:0036` |usbser |
90|`caterina` |Arduino Micro |`2341:0037` |usbser |
91|`caterina` |Adafruit Feather 32u4 |`239A:000C` |usbser |
92|`caterina` |Adafruit ItsyBitsy 32u4 3V |`239A:000D` |usbser |
93|`caterina` |Adafruit ItsyBitsy 32u4 5V |`239A:000E` |usbser |
94|`caterina` |Arduino Leonardo |`2A03:0036` |usbser |
95|`caterina` |Arduino Micro |`2A03:0037` |usbser |
96|`bootloadhid` |HIDBoot |`16C0:05DF` |HidUsb |
97|`usbasploader`|USBasp |`16C0:05DC` |libusbK|
98|`apm32-dfu` |APM32 DFU ISP Mode |`314B:0106` |WinUSB |
99|`stm32-dfu` |STM32 BOOTLOADER |`0483:DF11` |WinUSB |
100|`kiibohd` |Kiibohd DFU Bootloader |`1C11:B007` |WinUSB |
101|`stm32duino` |Maple 003 |`1EAF:0003` |WinUSB |
102|`qmk-hid` |(键盘名) Bootloader |`03EB:2067` |HidUsb |
diff --git a/docs/zh-cn/easy_maker.md b/docs/zh-cn/easy_maker.md
new file mode 100644
index 000000000..420c77d3a
--- /dev/null
+++ b/docs/zh-cn/easy_maker.md
@@ -0,0 +1,37 @@
1# 极简式制作 - 通过配置器进行一次性的工程构建
2
3<!---
4 original document: 0.15.12:docs/easy_maker.md
5 git diff 0.15.12 HEAD -- docs/easy_maker.md | cat
6-->
7
8你是否需要一种极简的控制器编程方案，类似Proton C或Teensy 2.0，以进行一次性的工程构建？QMK提供了极简制作器，通过QMK配置器可以在几分钟内制作一个固件。
9
10有几种极简制作器，取决于你需要什么样的：
11
12* [引脚直连](https://config.qmk.fm/#/?filter=ez_maker/direct) - 将每个开关独立直连到一个引脚
13* 引脚直连 + 背光 (即将可用) - 类似引脚直连，单独加一个引脚连接到[背光](zh-cn/feature_backlight.md)控制器上
14* 引脚直连 + 小键盘锁 (即将可用) - 类似引脚直连，单独加一个引脚连接到Numlock LED上
15* 引脚直连 + 大写锁 (即将可用) - 类似引脚直连， 单独加一个引脚连接到Capslock LED上
16* 引脚直连 + 编码器 (即将可用) - 类似引脚直连， 再加两个引脚用于连接一个旋钮编码器
17
18## 快速指引
19
20最简单的情况是使用一个引脚直连的主控板，将每个引脚连接到一个开关，另一端再接地即可，从以下键盘列表中可以选择一款支持的MCU：
21
22* <https://config.qmk.fm/#/?filter=ez_maker/direct>
23
24更多信息请参见[引脚直连](#direct-pin)一节。
25
26# 引脚直连 :id=direct-pin
27
28与其名字表意相同，它的原理是一个引脚连接一个开关，每个开关的另一端接地（VSS或GND），不需要额外的部件，通常MCU内部自带上拉电阻，因此可以感知开关动作。
29
30
31这里有一个示意图，展示了如何将一个按钮连接到ProMicro的A3引脚上：
32
33![该示意图中的ProMicro的A3引脚导出一根线，连接到了开关的左边，另一根线从开关右边引出并接地。](https://i.imgur.com/JcDhZll.png)
34
35在开关连接到各自的引脚后，在键盘下拉列表中选择所使用的MCU，将键码指定到对应的引脚上即可构建出固件。以下链接仅展示支持引脚直连的极简式制作：
36
37* <https://config.qmk.fm/#/?filter=ez_maker/direct>
diff --git a/docs/zh-cn/faq.md b/docs/zh-cn/faq.md
deleted file mode 100644
index 3d0b65c6f..000000000
--- a/docs/zh-cn/faq.md
+++ /dev/null
@@ -1,6 +0,0 @@
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
index c4b6e64d8..84cd3c6a4 100644
--- a/docs/zh-cn/faq_build.md
+++ b/docs/zh-cn/faq_build.md
@@ -1,122 +1,73 @@
1# 于构的常问题 1# 被问的编问题
2 2
3本页所写是QMK构建的常见问题.如果你还没有进行过编译,就看一下[构建环境搭建](getting_started_build_tools.md) 和 [make的说明](getting_started_make_guide.md). 3<!---
4 original document: 0.15.12:docs/faq_build.md
5 git diff 0.15.12 HEAD -- docs/faq_build.md | cat
6-->
4 7
5## 如果您不能在Linux上编程 8本页涉及所有编译QMK的问题，如果你还没有试过，请先阅读[编译环境配置](zh-cn/getting_started_build_tools.md)及[Make指引](zh-cn/getting_started_make_guide.md)。
6您需要适当的权限才能操作设备。对于Linux用户, 请参阅下方有关`udev`规则的说明。如果您对`udev`有问题，解决方法是用`sudo`命令。如果您不熟悉此命令，使用`man sudo`查看其手册或[看这个网页](https://linux.die.net/man/8/sudo).
7 9
8在你的主控是ATMega32u4时，以下是使用`sudo`命令的样例： 10## 无法在Linux下编程
11操作设备需要足够的权限，对于Linux用户，请参阅下方有关 `udev` 的规则说明。如果你对 `udev` 有困惑，可以先试试 `sudo` 命令，如果你对这个命令不熟悉，可以通过 `man sudo` 或 [这个web页面](https://linux.die.net/man/8/sudo)进行了解。
12
13一个使用 `sudo` 的示例，这里假设你的控制器是ATMega32u4:
9 14
10 $ sudo dfu-programmer atmega32u4 erase --force 15 $ sudo dfu-programmer atmega32u4 erase --force
11 $ sudo dfu-programmer atmega32u4 flash your.hex 16 $ sudo dfu-programmer atmega32u4 flash your.hex
12 $ sudo dfu-programmer atmega32u4 reset 17 $ sudo dfu-programmer atmega32u4 reset
13 18
14或只用； 19或者只是:
15 20
16 $ sudo make <keyboard>:<keymap>:dfu 21 $ sudo make <keyboard>:<keymap>:flash
17 22
18用`sudo``make`般来说**不**推荐，能，尽量使用前之一。 23请意， `sudo` 来执行 `make` 常***不是***一个主，请尽量考虑使用面办法。
19 24
20### Linux `udev` 规则 25### Linux `udev` 规则 :id=linux-udev-rules
21在Linux上，您需要适当的权限才能访问MCU。你也可以在刷新固件时使用 `sudo`，或把这些文件放到`/etc/udev/rules.d/`。
22 26
23**/etc/udev/rules.d/50-atmel-dfu.rules:** 27在linux下，需要足够的权限才能读写bootloader设备，可以使用 `sudo` 来刷写固件（不推荐），也可以将[这个文件](https://github.com/qmk/qmk_firmware/tree/master/util/udev/50-qmk.rules) 放到 `/etc/udev/rules.d/` 目录下。
24``` 28
25# Atmel ATMega32U4 29放好后，执行：
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 30
33**/etc/udev/rules.d/52-tmk-keyboard.rules:**
34``` 31```
35# tmk键盘产品 https://github.com/tmk/tmk_keyboard 32sudo udevadm control --reload-rules
36SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666" 33sudo udevadm trigger
37``` 34```
38**/etc/udev/rules.d/54-input-club-keyboard.rules:** 35
36**注意：**在旧版ModeManager（<1.12）中，过滤功能仅在严格模式（strict mode）下可用，可以调整一下配置：
39 37
40``` 38```
41# Input Club keyboard bootloader 39printf '[Service]\nExecStart=\nExecStart=/usr/sbin/ModemManager --filter-policy=default' | sudo tee /etc/systemd/system/ModemManager.service.d/policy.conf
42SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666" 40sudo systemctl daemon-reload
41sudo systemctl restart ModemManager
43``` 42```
44 43
45### 串行设备在Linux上检测不到bootloader模式 44### 在Linux下无法检测到bootloader模式下的串口设备
46确保您的内核对您的设备有相应的支持。 如果你的设备是 USB ACM, 比如Pro Micro (Atmega32u4)，就要加上`CONFIG_USB_ACM=y`. 其他设备可能需要`USB_SERIAL` 及其任何子选项。 45确认一下你的内核版本是否已配置为支持该设备。如果你的设备使用USB ACM，如Pro Micro（Atmega32u4），确认内核 配置中包含 `CONFIG_USB_ACM=y`，其它类型的设备可能需要 `USB_SERIAL` 及相关子配置的支持。
47
48## DFU Bootloader的未知设备
49 46
50如果您在使用Windows来刷新键盘的时候碰到了问题，检查设备管理器。如果在键盘处于 "bootloader模式"时你看到 "未知设备"，说明你可能面临设备问题。 47## DFU Bootloader显示为未知设备
51 48
52重新运行MSYS2上的安装脚本或许会凑效（比如在MSYS2/WSL运行 `./util/qmk_install.sh`) 或者重新安装QMK工具箱也可能会解决你的问题。 49在Windows下刷写键盘固件时很常见的一个问题。主要原因是安装了错误的驱动，或者压根没有装驱动。
53 50
54如果以上方法还是短针攻疽，那您可能需要使用[Zadig Utility](https://zadig.akeo.ie/)。下载此程序, 找到设备问题, 然后选择 `WinUSB`选项, 然后点击"Reinstall driver"。完成后再试试刷新你的键盘。倘若依然徒劳无功，那就尝试所有选项直到好用为止。 51要修复这个问题，可以尝试重新执行QMK安装脚本(位于MSYS2或WSL中的 `qmk_firmware` 目录下的 `./util/qmk_install.sh`)或重新安装QMK工具箱。此外，也可以尝试下载安装[QMK驱动安装包 `qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer)来修复。
55 52
56?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。 53如果问题依旧，可能是需要下载安装Zadig，具体请参考[通过Zadig安装bootloader驱动](zh-cn/driver_installation_zadig.md)。
57如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备)
58 54
59## USB VID 和 PID 55## USB VID 和 PID
60你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。 56通过编辑 `config.h` 你可以自由指定ID，随便选一个看起来不常用的ID一般不会有什么问题，冲突的概率很低。
61 57
62大数QMK主板用`0xFEED`作为vendor ID您查看其他键盘，以保选一Product ID。 58大部QMK设备选用 `0xFEED` 作为VID，PID前先看一下其它键盘决。
63 59
64也看看这个。 60同时阅个issue：
65https://github.com/tmk/tmk_keyboard/issues/150 61https://github.com/tmk/tmk_keyboard/issues/150
66 62
67也可以在下方链接购买一个唯一的VID:PID。个人使用乎用着个。 63可以在地址购买唯一的VID:PID，我得个人使用情况没有要。
68- https://www.obdev.at/products/vusb/license.html 64- 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 65- https://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
70 66
71## AVR的BOOTLOADER_SIZE 67### 在我刷写完键盘后就没响应了/点了没动静了 -- 设备是arm的（rev6 planck, clueboard 60, hs60v2等）(2019年2月)
72注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。 68因为ARM平台下EEPROM特殊的工作模式，已保存的配置可能会失效。主要影响的是默认层，有概率在特定情况下会导致键盘不可用，我们还没有搞明白原因。这个问题可以在重置EEPROM后恢复。
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 69
119[Planck rev6键盘重置EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) 是用于强制重置EEPROM的。刷入这个文件后，再次刷入正常固件，这会将键盘恢复到_正常_工作状态。 70[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) 71[Preonic rev3 上重置 EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
121 72
122如果以任何形式启用了bootmagic， 那么您还需要(看[Bootmagic文档](feature_bootmagic.md) 以及键盘信息，以了解如何执行此操作的详细信息). 73也可以考虑使用bootmagic，只要它可以用。（参见[Bootmagic文档](zh-cn/feature_bootmagic.md)并结合键盘情况来了解如何操作）
diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md
index 4dba44c27..63d688ed9 100644
--- a/docs/zh-cn/faq_debug.md
+++ b/docs/zh-cn/faq_debug.md
@@ -1,136 +1,136 @@
1# 调试的常见问题 1# 调试 FAQ
2 2
3本篇详细介绍了人们在键盘故障排除时的各种常见问题。 3<!---
4 original document: 0.15.12:docs/faq_debug.md
5 git diff 0.15.12 HEAD -- docs/faq_debug.md | cat
6-->
4 7
5# 8此页面细介绍了人们对键盘障除的种见问题。
6 9
7## `hid_listen` 无法识别设备 10## 调试 :id=debugging
8当设备的调试控制台未就绪时，您将看到如下内容：
9 11
10``` 12如果你在 `rules.mk` 中配置了 `CONSOLE_ENABLE = yes`，你的键盘将会输出调试信息。默认情况下输出很有限，可以启用调试模式来增加调试输出的丰富度。使用你的键映射方案中的 `DEBUG` 键码，或使用[指令](zh-cn/feature_command.md)功能来启动调试模式，或者将下面这段代码放到你的键映射中：
11Waiting for device:.........
12```
13
14插入设备后，*hid_listen*找到该设备，您将收到以下消息：
15 13
16``` 14```c
17Waiting for new device:......................... 15void keyboard_post_init_user(void) {
18Listening: 16 // 通过调整这些值可以改变其表现
17 debug_enable=true;
18 debug_matrix=true;
19 //debug_keyboard=true;
20 //debug_mouse=true;
21}
19``` 22```
20 23
21如果您无法得这条“Listening:”消息，请试[Makefile]中使用 `CONSOLE_ENABLE=yes` 24## 试具
22 25
23在Linux这样的操作系统上，你可能需要一些权限。 26有多种可用于调试的工具。
24- 使用`sudo hid_listen`
25 27
26## 控制台没有返回消息 28### 使用QMK工具箱调试
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 29
34## Linux或UNIX这样的系统如何请求超级用户权限 30在兼容的平台上，[QMK工具箱](https://github.com/qmk/qmk_toolbox)可以展示你的键盘的调试输出。
35用'sudo'来执行*hid_listen*就有权限了。
36```
37$ sudo hid_listen
38```
39 31
40或者把个文件到规则文件夹来为TMK备添加*udev则*不同系统的目录可有所不同。 32### QMK CLI 试
41 33
42文件: /etc/udev/rules.d/52-tmk-keyboard.rules(在Ubuntu系统的情况下) 34倾向于在终端进行调试？使用 [QMK CLI 命令行](zh-cn/cli_commands.md#qmk-console)可以展示键盘输出的调试信息。
43```
44# tmk keyboard products https://github.com/tmk/tmk_keyboard
45SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
46```
47 35
48*** 36### 使用hid_listen调试
49 37
50# 其他 38更喜欢使用终端的方案？PJRC提供的[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)也可以用来展示调试信息，已有Windows、Linux及MacOS下预编译好的可执行文件。
51## 安全注意事项
52 39
53你应该不想要把你的键盘变成"砖头"吧，就是变成没法重写固件的那种。 40## 发送自定义调试信息 :id=debug-api
54下面讲解一些参数来告诉你什么风险很大（其实也不是很大）。
55 41
56- 假如你键盘表面没有设计重置键"RESET", 那你要进入bootloader的话就要按PCB上的RESET了。 42有时在[自定义代码](zh-cn/custom_quantum_functions.md)中输出调试信息非常有用，要做到这个功能也很简单，在代码文件头部包含 `print.h` 文件：
57 按PCB上的RESET要拧开键盘底部。
58- 如果 tmk_core / common 里面的文件丢失键盘可能失灵。
59- .hex太大可能不太好; `make dfu` 会删除块，检验大小（咦?好像反了...）。
60 一但出错，刷新键盘失败的话就困在DFU出不去了。
61 - 所以, 要知道大小限制。 Planck键盘上.hex文件最大大小是 is 7000h (十进制是28672)
62 43
44```c
45#include "print.h"
63``` 46```
64Linking: .build/planck_rev4_cbbrowne.elf [OK]
65Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
66 47
67Size after: 48然后可以使用以下输出函数：
68 text data bss dec hex filename
69 0 22396 0 22396 577c planck_rev4_cbbrowne.hex
70```
71 49
72 - 上面那个文件大小是 22396/577ch，比28672/7000h小 50* `print("string")`: 字符串输出
73 - 当你有一个合适的.hex文件时，你就要重试加载那个了 51* `uprintf("%s string", var)`: 格式化字符串输出
74 - 您在键盘Makefile中的某些选项可能消耗额外内存；注意以下这几个 52* `dprint("string")` 仅调试模式下，字符串输出
75 BOOTMAGIC_ENABLE, MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE 53* `dprintf("%s string", var)`: 仅调试模式下，格式化字符串输出
76- DFU 工具/不/可以写入bootloader (unless you throw in extra fruit salad of options),
77 所以还是有点危险的
78- EEPROM大概有100000次循环寿命。不要总是频繁重写固件；EEPROM会玩坏的。
79## 全键无冲不好用
80首先你要在**Makefile**用如下命令编译固件`NKRO_ENABLE`。
81 54
82全键无冲还不好用的话试着用`Magic` **N** 命令(默认是`LShift+RShift+N`)。这个命令会在**全键无冲**和**六键无冲**之间临时切换。有些情况**全键无冲**不好用你就需要使用**六键无冲**模式，尤其是在BIOS中。 55## 调试示例
83 56
57以下列出了一些实际出现过的调试范例，更多资料参见[调试/定位QMK问题](zh-cn/faq_debug.md)。
84 58
85## 指点杆需要复位电路(PS/2 鼠标支持) 59### 当前按下的键的矩阵坐标是什么？
86如果没有复位电路，由于硬件初始化不正确，您将得到不一致的结果。查看TPM754复位电路。
87 60
88- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447 61在移植或尝试诊断PCB问题时，确认按下的键被正确扫描到是很有用的排查步骤。要启用该场景的日志输出，请在 `keymap.c` 中添加：
89- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
90 62
63```c
64bool process_record_user(uint16_t keycode, keyrecord_t *record) {
65 // If console is enabled, it will print the matrix position and status of each key pressed
66#ifdef CONSOLE_ENABLE
67 uprintf("KL: kc: 0x%04X, col: %u, row: %u, pressed: %b, time: %u, interrupt: %b, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);
68#endif
69 return true;
70}
71```
91 72
92## 矩阵不可读16以上的列 73输出示例
93当列超过16时[matrix.h]的`read_cols()`中，用`1UL<<16`而不要用`1<<16`。 74```text
94 75Waiting for device:.......
95在C语言中`1` 是一个[int] 类型的[16 bit]值，在AVR中你不能左移大于15次。如果你使用`1<<16`的话会得到意外的零。你要用 [unsigned long]类型，比如`1UL`。 76Listening:
77KL: kc: 169, col: 0, row: 0, pressed: 1
78KL: kc: 169, col: 0, row: 0, pressed: 0
79KL: kc: 174, col: 1, row: 0, pressed: 1
80KL: kc: 174, col: 1, row: 0, pressed: 0
81KL: kc: 172, col: 2, row: 0, pressed: 1
82KL: kc: 172, col: 2, row: 0, pressed: 0
83```
96 84
97https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279 85### 扫描到一个键码需要多久？
98 86
99## 特殊额外键不起作用(系统，音频控制键) 87调试性能问题时，知晓开关矩阵的扫描频率是很有用的排查步骤。要启用该场景的日志输出，请在 `config.h` 中添加：
100你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。
101 88
89```c
90#define DEBUG_MATRIX_SCAN_RATE
102``` 91```
103EXTRAKEY_ENABLE = yes # 音频控制和系统控制
104```
105
106## 睡眠唤醒不好用
107
108在Windows查看设备管理器中该键盘设备属性中电源管理选项卡中的`允许此设备唤醒计算机(O)`是否勾选。同时看一眼BIOS设置。
109 92
110在主机睡眠时按下任何键都可以唤醒了。 93输出示例
94```text
95 > matrix scan frequency: 315
96 > matrix scan frequency: 313
97 > matrix scan frequency: 316
98 > matrix scan frequency: 316
99 > matrix scan frequency: 316
100 > matrix scan frequency: 316
101```
111 102
112## 使用Arduino? 103## `hid_listen` 无法识别到设备
113 104
114**注意Arduino的针脚名字和主控芯片的不一样。** 比如, Arduino的`D0`并不是`PD0`。自己用原理图捋一下电路。 105如果设备没有就绪，在命令行下调试会看到如下输出：
115 106
116- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf 107```
117- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf 108Waiting for device:.........
109```
118 110
119Arduino Leonardo和micro使用**ATMega32U4**，芯片TMK，Arduino的bootloader问题。 111设备入后*hid_listen*设备，会有下：
120 112
121## USB 3 兼容性 113```
122据传说有些人用USB3接口会有问题，用USB2的试试。 114Waiting for new device:.........................
115Listening:
116```
123 117
118若无法出现'Listening:'消息，尝试在[Makefile]中添加 `CONSOLE_ENABLE=yes`
124 119
125## Mac 兼容性 120在类Linux系统下，访问设备可能需要一定权限，尝试使用 `sudo hid_listen`。
126### OS X 10.11 和集线器
127https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
128 121
122此外，很多Linux发行版可以通过创建如下内容的文件 `/etc/udev/rules.d/70-hid-listen.rules` 来避免通过root权限执行hid_listen：
129 123
130## 对于BIOS (UEFI)/恢复(睡眠和唤醒)/重新启动 有问题 124```
131有人说他们的键盘在BIOS中，或许是恢复(睡眠和唤醒)后不工作. 125SUBSYSTEM=="hidraw", ATTRS{idVendor}=="abcd", ATTRS{idProduct}=="def1", TAG+="uaccess", RUN{builtin}+="uaccess"
126```
132 127
133截止至目前，其根本原因未知，不排除与某些构建选项有关。试着在Makefile中失能`CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE`这样的选项，也试试其他的。 128使用设备的真实VID和PID替换上面的abcd和def1，留意必须全小写。其中 `RUN{builtin}+="uaccess"` 仅在较老的发行版中需要使用。
134 129
135https://github.com/tmk/tmk_keyboard/issues/266 130## 命令行无法成功输出消息
136https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778 131请检查:
132- *hid_listen*确实找到了设备，如前文所述。
133- 通过**Magic**+d命令启用调试模式，参见[Magic Commands](https://github.com/tmk/tmk_keyboard#magic-commands).
134- 配置`debug_enable=true`. 参见[调试](#debugging)
135- 尝试用 `print` 替代 `dprint`， 参见**common/print.h**.
136- 拔出其它可能影响命令行的设备，参见[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97).
diff --git a/docs/zh-cn/faq_general.md b/docs/zh-cn/faq_general.md
index 4949acb8c..cc8ef3d19 100644
--- a/docs/zh-cn/faq_general.md
+++ b/docs/zh-cn/faq_general.md
@@ -1,19 +1,58 @@
1# 1# 常见问题FAQ）
2 2
3## QMKʲô? 3<!---
4 original document: 0.15.12:docs/faq_general.md
5 git diff 0.15.12 HEAD -- docs/faq_general.md | cat
6-->
4 7
5[QMK](https://github.com/qmk), ӻе(Quantum Mechanical Keyboard)дһȺԴΪƼ̿ĹߡǴ[QMK̼](https://github.com/qmk/qmk_firmware)ʼ[TMK](https://github.com/tmk/tmk_keyboard)ħķֲ档 8## QMK是什么?
6 9
7### Ϊʲô(Quantum)? 10[QMK](https://github.com/qmk), 是量子机械键盘（Quantum Mechanical Keyboard）的缩写, 是制作自定义键盘工具的人组成的组织。 一切始于[QMK固件](https://github.com/qmk/qmk_firmware)项目, 可以认为是[TMK](https://github.com/tmk/tmk_keyboard)的改进版本.
8 11
9<!-- ²ۣĵ߾ҲΪɶ --> 12## 知道开始搞！
10 13
11## QMKTMKʲ? 14这样的话议从[新手指引](zh-cn/newbs.md)开始。那里有你需要的高量的入门信息。
12 15
13TMK[Jun Wako](https://github.com/tmk)ƺִСQMKʼ[Jack Humbert](https://github.com/jackhumbert)ΪPlanck̴TMKֲ档һʱJackķֲͺTMKȥԶˣ2015꣬JackQMK 16如果还是搞不懂的话，直接跳到[QMK配置器](https://config.qmk.fm)吧，你核心需要的东西都在那里。
14 17
15Ӽ۵QMKTMKһЩ¹ܶɵġQMKչ˿õļ룬ʹ߼ܽһḻ `S()`, `LCTL()`, `MO()`ȫ[](keycodes.md). 18## 我的固件如何刷写到硬件上？
16 19
17ӹ̵TMKԼάйٷֵ֧ļֻ̣кСһ֧֡άѴڷֲΪ̴ķֲ档Ĭֺ֧ٵļ룬ûͨ˷֡QMKͨйֺֿͼ̣ǻз׼PRͼı֤άͬʱQMKСҲڱҪʱ 20先参考[编译/刷写固件FAQ](zh-cn/faq_build.md)，里面有充足的资料，常见的问题也给出了足够多的解决办法。
18 21
19ַŵȱ㣬ҴʱTMKQMK֮ 22## 我的问题这里找不到相关信息怎么办？
23
24没有关系，请到[GitHub上发issue](https://github.com/qmk/qmk_firmware/issues)看看是否有人遇到了相同的问题（留意一定是相同的问题，而不是相似的）。
25
26如果还是找不到解决办法，请[新建issue](https://github.com/qmk/qmk_firmware/issues/new)！
27
28## 我好像找到了bug？
29
30那么新建一个[issue](https://github.com/qmk/qmk_firmware/issues/new)吧，如果你还知道怎么修，带着修复方案发个Pull Request吧。
31
32## 但是 `git` 和 `GitHub` 我实在是玩不转！
33
34别担心，这里有很好的[入门指引](zh-cn/newbs_git_best_practices.md)可以教你怎么轻松快乐地使用 `git` 和GitHub进行开发。
35
36更多的 `git` 和GitHub知识，参考[这里](zh-cn/newbs_learn_more_resources.md)。
37
38## 我可以添加一个支持的键盘
39
40太棒啦！请发Pull Request吧，在代码审阅后，我们会合并进去！
41
42### 我可以打上 `QMK` 的标吗?
43
44很好啊！我们甚至乐意帮你这么做！
45
46我们有[一整页](https://qmk.fm/powered/)的资料旨在帮你在页面和键盘上打上QMK的标，里面有QMK官方提供的所有支援（信息及图片）。
47
48如果你有任何疑问，可以发issue或通过[Discord](https://discord.gg/Uq7gcHh)联系我们。
49
50## QMK和TMK区别是什么？
51
52TMK原先是由[Jun Wako](https://github.com/tmk)设计实现的，QMK来源于[Jack Humbert](https://github.com/jackhumbert)的Planck的TMK fork。一段时间后，Jack的这个fork与TMK渐行渐远，到2015年时，Jack决定将这份fork重命名为QMK。
53
54技术上讲QMK等同于基于TMK增加了一些新功能，最显著的是在扩充了可用键码后，实现了很多诸如 `S()`, `LCTL()` 及 `MO()` 这样的高级功能，所有这些键码可以参见[键码](zh-cn/keycodes.md)页。
55
56从工程项目及社区维护角度来看，TMK维护了一份官方支持的键盘及很少量的社区贡献，社区中各自维护着各自的fork，且因为默认键映射很少，TMK的使用者基本不会共享键映射。QMK通过统一的集约式仓库（repo）管理来鼓励分享键盘及键映射，任何符合质量基线的pull request都会被采纳，因此绝大部分贡献都来源于社区，QMK小组会在必要时提供支援。
57
58两种模式各有利弊，并且TMK和QMK之间也会有合乎理法的代码交流。
diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md
index ff38f3889..f67412971 100644
--- a/docs/zh-cn/faq_keymap.md
+++ b/docs/zh-cn/faq_keymap.md
@@ -1,151 +1,157 @@
1# 布局常见 1# 射FAQ
2 2
3本页本页包含人们经常遇到的关于布局的问题。如果你觉得没什么问题，请先看[布局概览](keymap.md)。 3<!---
4 original document: 0.15.12:docs/faq_keymap.md
5 git diff 0.15.12 HEAD -- docs/faq_keymap.md | cat
6-->
4 7
5## 我能用什么键码? 8本页包含人们经常遇到的关于键映射的问题，如果你还没阅读过[键映射概览](zh-cn/keymap.md)，请先阅读一下。
6看[键码](keycodes.md)你可以找到你能用的键码索引。可以的话这些链接可以连接到更广泛的文档。
7 9
8键码实际上定义在[common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h). 10## 我能使用的键码有哪些?
11所有可用键码收录在[键码](zh-cn/keycodes.md)页，在有更详尽的文档时，我们会更新这个链接。
9 12
10## 认的码样? 13所有键码实际定在[quantum/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/keycode.h).
11 14
12世界上有三种标准键盘设计，分别是：ANSI, ISO, and JIS. 主要是北美用ANSI(译者注：中国很多键盘使用这个), 欧洲和非洲主要使用ISO，日本使用JIS。未提及的区域通常使用ANSI或ISO。与这些设计对应的键代码如下所示： 15## 默认键码是什么?
13 16
14<!-- 该图片的来源: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a --> 17广为使用的键盘配列有三种——ANSI，ISO及JIS。北美主要使用ANSI，欧洲及非洲主要使用ISO，日本主要使用JIS，其它区域多为ANSI或ISO。这三种配列的键码可查阅：
15![键盘设计图](https://i.imgur.com/5wsh5wM.png)
16 18
17## 我有一些键变成了其他功能或者不工作了 19<!-- Source for this image: https://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
20![键盘配列示意图](https://i.imgur.com/5wsh5wM.png)
18 21
19QMK有两个功能，Bootmagic和命令行，它允许您在运行中更改键盘的行为。该功能包括但不仅限于, 交换Ctrl/Caps，关闭界面，交换Alt/Gui，交换 Backspace/Backslash，禁用所有键，以及其他的行为改变。 22## 如何对复杂的键码指定自定义的名称？
20 23
21快速解决方法是插入键盘时按住`Space`+`Backspace`。该操作将重置已保存设置，让这些键回复初始功能。这招不好用的话参阅下方： 24使用更容易理解的自定义的名字去指代一些键码有时很实用，通常我们使用 `#define` 来实现：
22 25
23* [Bootmagic](feature_bootmagic.md) 26```c
24* [命令](feature_command.md) 27#define FN_CAPS LT(_FL, KC_CAPSLOCK)
28#define ALT_TAB LALT(KC_TAB)
29```
30
31这样键映射代码中就可以使用 `FN_CAPS` 和 `ALT_TAB` 了，可读性好得多。
32
33## 一些按键发生了交换，或是不能用了
34
35QMK有两个功能系列，Bootmagic及指令，都可以让键盘随时变得灵活多变，功能包含但不限于交换Ctrl/Caps、锁定Gui键、交换Alt/Gui、交换Backspace/Backslash、禁用所有按键等。
25 36
26## 菜单键不好用 37快速恢复的办法是插入键盘时按住空格+`Backspace`键，这样会重置键盘内存储的设置信息，键盘就会恢复常态。如果问题依旧存在，请参考：
27 38
28现在大多数键盘 `KC_RGUI`和`KC_RCTL`中间的键子叫做`KC_APP`。这是因为在这个键子发明之前相关标准里就已经有键叫做`MENU(菜单)`了，所以微软叫他`APP(应用)`键。 39* [Bootmagic](zh-cn/feature_bootmagic.md)
40* [指令](zh-cn/feature_command.md)
29 41
30## `KC_SYSREQ` 不工作 42## 菜单键（Menu）不可用
31使用抓屏的键码(`KC_PSCREEN`或`KC_PSCR`)而不用`KC_SYSREQ`。组合键'Alt + Print Screen'会被当作'System request'。
32 43
33见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)和 44现代键盘上，位于 `KC_RGUI` 及 `KC_RCTL` 间的按键实际上叫做 `KC_APP`。原因是该键被发明时，相关标准中已经有了 `菜单（MENU）` 键，因此微软将该键命名为 `APP` 键。
45
46## `KC_SYSREQ` 不可用
47请使用截图键码（`KC_PSCREEN` 及 `KC_PSCR`）替代 `KC_SYSREQ`，组合键’Alt + Print Screen‘实际上会被识别为’System request‘。
48
49具体参见[issue #168](https://github.com/tmk/tmk_keyboard/issues/168)以及
34* https://en.wikipedia.org/wiki/Magic_SysRq_key 50* https://en.wikipedia.org/wiki/Magic_SysRq_key
35* https://en.wikipedia.org/wiki/System_request 51* https://en.wikipedia.org/wiki/System_request
36 52
37## 电源键不工作 53## 电源键不工作
38 54
39这有点让人困惑,QMK有两个"Power(电源)"键码: `KC_POWER` 在键盘/小键盘的HID使用页面中，`KC_SYSTEM_POWER` (或者叫`KC_PWR`)在用户页。 55QMK有两个容易让人迷惑的“电源键”键码：HID键盘页的 `KC_POWER`，及用户页的 `KC_SYSTEM_POWER`（或 `KC_PWR`）。
40 56
41前者只能被macOS识别，但是后者，即`KC_SLEP`和`KC_WAKE`三大主要操作系统全都支持，所以推荐使用这两个。Windows下这些键立即生效，macOS要长按直到弹出对话框。 57前者只有macOS支持，后者连同 `KC_SLEP` 及 `KC_WAKE` 在所有主流操作系统上都支持，因此使用后者是推荐的做法。在Windows下，按下按键即刻就会生效，而macOS下必须按住直到系统弹出一个对话框。
42 58
43## 自写 59## 修
44可以解决'the'问题(正常应为The)。我经常在输入'The'时不慎输入了'the'或者'THe'。自动大小写锁定可以修正此类问题。详见下方链接。 60用来解决我自己的’the‘麻烦，我总是会将’The‘错输入为’the‘或’THe‘，单发Shift键缓解了我的这个麻烦。
45https://github.com/tmk/tmk_keyboard/issues/67 61https://github.com/tmk/tmk_keyboard/issues/67
46 62
47## 修改 键/层 卡住 63## 修饰键/层 卡住了
48除非正确配置层切换，否则修改键或层可能会卡住。 64层切换功能只有在正确配置的情况下，才不会出现卡住修饰键和层的问题。
49对于修改键和图层操作，必须把`KC_TRANS`放到目标层的相同位置，用于注销修改键或在释放事件时返回到上一层。 65对于修饰键和层切换操作来讲，必须确保 `KC_TRANS` 在切换到目标layer时正确置位，才能让修饰键正确释放。或者在释放动作中确保返回到了之前的层。
66
50* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching 67* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
51* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604 68* https://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
52* https://github.com/tmk/tmk_keyboard/issues/248 69* https://github.com/tmk/tmk_keyboard/issues/248
53 70
54 71
55## 机械自锁开关支持Mechanical Lock Switch Support 72## 机械锁关支持
56 73
57本功能用于*机械自锁开关*比如[this Alps one](https://deskthority.net/wiki/Alps_SKCL_Lock)。你可以通过向`config.h`添加以下宏来使能该功能： 74该功能支持形如[Alps这款](https://deskthority.net/wiki/Alps_SKCL_Lock)的*机械锁定式开关*，启用该功能须在 `config.h` 中添加如下定义：
58 75
59``` 76```
60#define LOCKING_SUPPORT_ENABLE 77#define LOCKING_SUPPORT_ENABLE
61#define LOCKING_RESYNC_ENABLE 78#define LOCKING_RESYNC_ENABLE
62``` 79```
63 80
64使功能后，要在键中使用`KC_LCAP`, `KC_LNUM` 和 `KC_LSCR`这三个键码。 81该功能后，在你的键射中须改用 `KC_LCAP`，`KC_LNUM` 和 `KC_LSCR`。
65 82
66远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。*** 83旧式复古风（vintage style）键盘偶尔能见到锁定式开关，但在现代键盘中见不到了。***因此你基本不会需要这个功能的，直接使用 `KC_CAPS`，`KC_NLCK` 和 `KC_SLCK` 就好***
67 84
68## 输入ASCII之的特殊符比如Cédille 'Ç' 85## 输入形如法语中软音'Ç'这样的非ASCII字符
69 86
70[Unicode](feature_unicode.md)功能。 87参见[Unicode](zh-cn/feature_unicode.md)功能.
71 88
72## macOS的`Fn` 89## macOS系统的 `Fn`
73 90
74不像大多数FN键，苹果上那个有自己的键码...呃，基本上算吧。 他取缔了基本6键无冲HID报告的第六个键码 -- 所以苹果键盘其实是5键无冲的。 91和其它键盘不同，Apple键盘上的Fn有自己的键码...在某种程度上。其占用了基础6KRO HID事件上报中的第六个键码 —— 因此Apple键盘实际上只是5KRO（5键无冲）的。
75 92
76技术上说QMK可以发送这个键。但是，这样做需要修改报告格式以添加FN键的状态。这还不是最糟糕的，你的键盘的VID和PID和真的苹果键盘不一样的话还不会被识别。 93技术上讲QMK确实能发送这种键码，但这么做需要修改上报事件中Fn键状态的格式。更麻烦的是，只有你的键盘的VID及PID与Apple键盘一致时才会生效。QMK对此提供官方支持可能会有法律风险，换句话说，我们不太可能去这么做的。
77QMK官方支持这个会被律师函的，所以就当我没说过。
78 94
79见[issue#2179](https://github.com/qmk/qmk_firmware/issues/2179)。 95具体信息参见[这个issue](https://github.com/qmk/qmk_firmware/issues/2179)。
80 96
97## Mac OSX下支持的键有哪些？
98你可以通过查阅以下代码确认OSX下支持的键码。
81 99
82## Mac OSX的媒体控制键 100`usb_2_adb_keymap` 数组实现了从 Keyboard/Keypad 页到 ADB 扫描码（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 101
93https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c 102https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
94 103
95`IOHIDConsumer::dispatchConsumerEvent`会处理用户页法。 104以及 `IOHIDConsumer::dispatchConsumerEvent` 负责处理用户页分。
96<!--翻译问题：上面那两句翻译的不好-> handles Consumer page usages. --> 105
97https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp 106https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
98 107
99 108
100## Mac OSX中的JIS键 109## Mac OSX下的JIS键
101岛国特别键比如`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)`OSX是不是别的。You can use **Seil** to enable those keys, try following options. 110日语体系的JIS键盘有些特殊键码：`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` 在OSX下无法被识别，可以尝试通过以下配置借助 **Seil** 来启用这些键。
102<!--翻译问题：以上“岛国特别键”没有任何地域歧视的意思 -->
103* 在电脑键盘上使能NFER键
104* 在电脑键盘上使能XFER键
105* 在电脑键盘上使能KATAKAN键
106 111
107https://pqrs.org/osx/karabiner/seil.html 112* 在PC键盘中启用NFER键
113* 在PC键盘中启用XFER键
114* 在PC键盘中启用KATAKANA键
108 115
116https://pqrs.org/osx/karabiner/seil.html
109 117
110## RN-42蓝牙模块与Karabiner不能有效协同工作
111Karabiner - Mac OSX的改键软件 - 默认RN-42模块是不会被响应的。想要Karabiner和你的键盘协同工作你要使能此选项：
112https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
113 118
114此问题详见下方链接。 119## RN-42蓝牙模块与Karabiner的兼容性问题
120Karabiner - Mac OSX系统下的键映射工具 - 默认会忽略RN-42模块的输入事件。须在Karabiner开启相关选项来支持你的键盘。
121https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559230
122这个问题的其它详细信息参见
115https://github.com/tmk/tmk_keyboard/issues/213 123https://github.com/tmk/tmk_keyboard/issues/213
116https://github.com/tekezo/Karabiner/issues/403 124https://github.com/tekezo/Karabiner/issues/403
117 125
118 126
119## Esc 和 <code>&#96;</code> 双功能键 127## Esc和<code>&#96;</code>位于同一个键位
120
121请见[Grave Escape](feature_grave_esc.md)功能。
122 128
123## Mac OSX的弹出键 129参见[Grave Escape](zh-cn/feature_grave_esc.md)功能.
124`KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250
125似乎Windows10会忽略该键码，Linux/Xorg可以识别该键码但默认不映射。
126 130
127目前尚不清楚如何在真正的苹果键盘按出弹出键。HHKB使用`F20`用于弹出键(`Fn+f`)，该功能在MAC模式有效但不保证与苹果弹出键码相符。 131## Mac OSX下的弹出功能
132`KC_EJCT` 在OSX下可用。 https://github.com/tmk/tmk_keyboard/issues/250
133Windows 10应该是忽略了这个键码，Linux/Xorg能识别到，但默认没有映射处理。
128 134
135目前尚不清楚Apple键盘上弹出键到底是啥，HHKB在Mac模式下使用 `F20` 来作为弹出键（`Fn+f`），但应该和Apple的弹出键码不是一回事儿。
129 136
130## `action_util.c`中的 `weak_mods`和`real_mods`是什么 137## 在 `action_util.c` 中的 `weak_mods` 和 `real_mods` 是什么东西？
131___待改善___ 138___待的内容___
132 139
133real_mods 用于保存实际(物理)修改键的实际状态。 140real_mods保存的是现实的/物理上的修饰键状态，而weak_mods保存的是虚拟的或临时的修饰键状态，且不应该影响到真实的修饰键的状态。
134weak_mods 用于保存虚拟或临时修改键，它将不会影响实际修改键。
135 141
136按左侧Shift键然输入ACTION_MODS_KEY(LSHIFT, KC_A)为例， 142如你按了物理键盘的左shift键，输入了 ACTION_MODS_KEY(LSHIFT, KC_A)，
137 143
138在weak_mods时， 144在weak_mods下,
139* (1) 按不抬起左Shift: real_mods |= MOD_BIT(LSHIFT) 145* (1) 按左shift: real_mods |= MOD_BIT(LSHIFT)
140* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods |= MOD_BIT(LSHIFT) 146* (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) 147* (3) 开 ACTION_MODS_KEY(LSHIFT, KC_A): weak_mods &= ~MOD_BIT(LSHIFT)
142real_mods 还是保持在修状态。 148real_mods然留着修饰态值。
143 149
144在没有weak_mods时， 150非weak_mods时,
145* (1) 按不抬起左Shift: real_mods |= MOD_BIT(LSHIFT) 151* (1) 按左shift: real_mods |= MOD_BIT(LSHIFT)
146* (2) 按 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods |= MOD_BIT(LSHIFT) 152* (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) 153* (3) 开 ACTION_MODS_KEY(LSHIFT, KC_A): real_mods &= ~MOD_BIT(LSHIFT)
148real_mods失去‘实左Shift’的状态。 154这时real_mods失去了‘物理左shift’的状态值。
149 155
150weak_mods和real_mods现已全部加入键盘据包发华套餐。 156在键盘事件发送时，weak_mods会与real_mods或。
151https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57 157https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
diff --git a/docs/zh-cn/faq_misc.md b/docs/zh-cn/faq_misc.md
new file mode 100644
index 000000000..d01caba3b
--- /dev/null
+++ b/docs/zh-cn/faq_misc.md
@@ -0,0 +1,108 @@
1# 其它 FAQ
2
3<!---
4 original document: 0.15.12:docs/faq_misc.md
5 git diff 0.15.12 HEAD -- docs/faq_misc.md | cat
6-->
7
8## 怎么对键盘进行测试？ :id=testing
9
10测试键盘就简单直接，把每个按键按一遍后确认发送的是正确的就行。也可以使用[QMK配置器](https://config.qmk.fm/#/test/)的测试模式检查键盘，即便这键盘没有运行着QMK。
11
12## 安全措施
13
14你应该不想见到键盘变砖，变得不能再刷写固件。这里给出了一些非常危险（或相反不太危险）的因素。
15
16- 如果你的键盘没有RESET键，在你需要进入DFU模式时，不得不需要用螺丝刀打开后盖去按PCB上的RESET键。
17- 把 tmk_core/common 下的文件搞乱的话，容易导致键盘无法使用
18- .hex文件太大的话也会引起问题。`make dfu` 会先擦除存储块，再检查固件大小（哎呀，顺序错了），此时发现错误进而导致刷写失败，键盘停留在DFU模式下。
19 - 因此，请留意.hex文件尺寸有大小限制，例如在Planck上是十六进制7000（十进制的28672）
20
21```
22Linking: .build/planck_rev4_cbbrowne.elf [OK]
23Creating load file for Flash: .build/planck_rev4_cbbrowne.hex [OK]
24
25Size after:
26 text data bss dec hex filename
27 0 22396 0 22396 577c planck_rev4_cbbrowne.hex
28```
29
30 - 上面的文件大小是22396/577ch, 小于28672/7000h
31 - 任何合适的其它.hex文件，都可以尝试加载
32 - 在键盘的Makefile中你添加的一些配置也会额外占用空间，在使用BOOTMAGIC_ENABLE,
33 MOUSEKEY_ENABLE, EXTRAKEY_ENABLE, CONSOLE_ENABLE, API_SYSEX_ENABLE
34 时请留意
35- DFU工具/不会/允许bootloader被覆写（除非你往DFU工具上塞自己的东西），这个风险不大。
36- EEPROM的写循环一般是 100000（100k）次，不应不停地持续重复地刷写固件，不然很快就烧毁了。
37
38## NKRO 不好使
39首先请确保在编译固件时有在**Makefile**中启用 `NKRO_ENABLE`
40
41如果依旧不行，尝试一下 `Magic` **N** 指令（默认是左Shift+右Shift+N），这个指令可以让键盘在**NKRO**和**6KRO**模式间临时切换。有的场景下**NKRO**无法工作必须切换到**6KRO**模式，比如在BIOS中操作时。
42
43如果你的固件编译时指定了 `BOOTMAGIC_ENABLE` ，则需要使用 `BootMagic`**N** 指令（默认是空格+N）。这个配置保存在EEPROM中，断电也会留存。
44
45https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
46
47
48## 轨迹球需要复位电路 (PS/2鼠标支持)
49缺失复位电路的情况下，由于不正确的硬件初始化，可能会导致设备不稳定，具体请参阅TPM754的电路原理图：
50
51- https://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
52- https://www.mikrocontroller.net/attachment/52583/tpm754.pdf
53
54
55## 无法读到大于16的矩阵列
56当列数大于16时，在 [matrix.h] 中的 `read_cols()` 中请用 `1UL<<16` 替代 `1<<16`。
57
58在C语言中，对于AVR上的 `1`，会被视作一种[16位]的[整形(int)]类型，因此无法左移超过15位。因此 `1<<16` 的计算结果会错误地变成0。解决办法就是将类型改为[无符号长整形(unsigned long)]类型的 `1UL`。
59
60https://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
61
62## 有些额外的按键不好使（系统，音频控制键）
63在QMK的 `rules.mk` 中须定义 `EXTRAKEY_ENABLE`
64
65```
66EXTRAKEY_ENABLE = yes # 音频及系统控制
67```
68
69## 无法从休眠唤醒
70
71在Windows的**电源管理**的**设备管理**中，检查 `允许该设备唤醒计算机` 选项，同时检查一下BIOS中的相关设置，任意一个按键都应该能将计算机从休眠状态唤醒。
72
73## 在使用Arduino?
74
75**注意Arduino的引脚编号与芯片的引脚编号是不同的**。例如，Arduino的 `D0` 引脚并不是 `PD0`，请对照其电路图检查电路。
76
77- https://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
78- https://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
79
80Arduino Leonardo 以及 micro 使用的是**ATMega32U4**因此可以用TMK，但bootloader可能会是个麻烦的问题。
81
82## 启用JTAG
83
84默认情况下，键盘启动后JTAG调试接口就被禁用了。支持JTAG的MCU出场时会带着 `JTAGEN` 保险丝，而键盘因为需要这部分MCU的引脚去控制开关矩阵、LED等功能。
85
86如果你希望启用JTAG，在 `config.h` 中添加定义：
87
88```c
89#define NO_JTAG_DISABLE
90```
91
92## USB 3兼容性问题
93将设备从USB 3.x端口改插到USB 2.0端口能解决一些问题。
94
95
96## Mac相关兼容性问题
97### OS X 10.11 和 Hub
98参见: https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
99
100
101## BIOS (UEFI) 配置/恢复 (休眠 & 唤醒)/电源循环
102有人反馈过他们的键盘在BIOS下或是从休眠状态唤醒后会不可用。
103
104目前这个问题的原因还不清楚，但一些编译选项应该和这个问题有关，你可以在Makefile中禁用 `CONSOLE_ENABLE`, `NKRO_ENABLE`, `SLEEP_LED_ENABLE` 或其他的试一试。
105
106更多信息：
107- https://github.com/tmk/tmk_keyboard/issues/266
108- https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
diff --git a/docs/zh-cn/feature_grave_esc.md b/docs/zh-cn/feature_grave_esc.md
new file mode 100644
index 000000000..f57dabeaf
--- /dev/null
+++ b/docs/zh-cn/feature_grave_esc.md
@@ -0,0 +1,39 @@
1# Grave Escape
2
3<!---
4 original document: 0.15.12:docs/feature_grave_esc.md
5 git diff 0.15.12 HEAD -- docs/feature_grave_esc.md | cat
6-->
7
8*译注：Grave键即标准键盘中Tab键上方的 <code>&#96;</code> 键，该符号用于英法语等西语体系，辅助调整发音，中文中没有对应概念；Escape即Esc键*
9
10若你使用60%或其它没有Fn键配列的键盘，会留意到没有独立的Escape键。Grave Escape功能可以让Grave键(<code>&#96;</code>及`~`)与Escape共享一个按键
11
12## 使用方法
13
14在配列中使用 `KC_GESC` 替换 `KC_GRAVE` （一般都在`1`键左边）。默认点击会输出 `KC_ESC`，按下Shift或GUI键时，点击会输出 `KC_GRV`
15
16## 操作系统视角
17
18假如翠花按下GESC键，系统接收到的是KC_ESC字符。若翠花按住Shift再按下GESC，将输出 `~` 或是反引号。若翠花按住GUI/CMD/Win键，将仅输出<code>&#96;</code>字符
19
20## 键码
21
22|键 |别名 |描述 |
23|---------|-----------|------------------------------------------------------------------|
24|`KC_GESC`|`GRAVE_ESC`|单击输出Escape, 按住Shift或GUI时输出<code>&#96;</code> |
25
26### 须留意
27
28在macOS上 Command+<code>&#96;</code>默认行为是“移动焦点到下一个窗口”，因此不会输出反引号。另外，即便在键盘配置中更改过快捷键，终端程序(Terminal)也通常会将这个操作视为循环切换窗口
29
30## 配置
31
32有几种键组合可以变更这种行为，如Windows下的Control+Shift+Escape、macOS下的Command+Option+Escape。若要调整，可以在 `config.h` 中通过 `#define` 配置
33
34|定义 |描述 |
35|--------------------------|-----------------------------------------|
36|`GRAVE_ESC_ALT_OVERRIDE` |按住Alt时输出Escape |
37|`GRAVE_ESC_CTRL_OVERRIDE` |按住Control时输出Escape |
38|`GRAVE_ESC_GUI_OVERRIDE` |按住GUI时输出Escape |
39|`GRAVE_ESC_SHIFT_OVERRIDE`|按住Shift时输出Escape |
diff --git a/docs/zh-cn/feature_space_cadet.md b/docs/zh-cn/feature_space_cadet.md
new file mode 100644
index 000000000..e3dab9c72
--- /dev/null
+++ b/docs/zh-cn/feature_space_cadet.md
@@ -0,0 +1,70 @@
1# Space Cadet: The Future, Built In
2<!-- Deliberately not translated, leave it to a suitable translation -->
3
4<!---
5 original document: 0.15.12:docs/feature_space_cadet.md
6 git diff 0.15.12 HEAD -- docs/feature_space_cadet.md | cat
7-->
8
9*译注：Space Cadet来源于(在西方早期程序员中)著名的键盘Space Cadet Keyboard，具体信息参见下面的链接或[维基百科](https://en.wikipedia.org/wiki/Space-cadet_keyboard)*
10
11Steve Losh 在 [Space Cadet Shift](https://stevelosh.com/blog/2012/10/a-modern-space-cadet/) 详细地描述了该功能. 简而言之，点击左Shift时，会输出左括号；点击右Shift时，会输出右括号。如果按住Shift键，常规的Shift将正常工作。这功能实际上和听起来的一样爽，更爽的是现在连Control和Alt也支持！
12
13## 使用指南
14
15首先，在你的配列中完成以下任一项：
16- 替换左Shift为 `KC_LSPO`（左Shift，左括号），替换右Shift为 `KC_RSPC`（右Shift，右括号）。
17- 替换左Control为 `KC_LCPO`（左Control，左括号），替换右Control为 `KC_RCPC`（右Control，右括号）。
18- 替换左Alt为 `KC_LAPO`（左Alt，左括号），替换右Alt为 `KC_RAPC`（右Alt，右括号）。
19- 替换任意一个Shift为 `KC_SFTENT`（右Shift，回车）。
20
21## 键码
22
23|键码 |描述 |
24|-----------|-----------------------------|
25|`KC_LSPO` |按住时左Shift，点击时 `(` |
26|`KC_RSPC` |按住时右Shift，点击时 `)` |
27|`KC_LCPO` |按住时左Control，点击时 `(` |
28|`KC_RCPC` |按住时右Control，点击时 `)` |
29|`KC_LAPO` |按住时左Alt，点击时 `(` |
30|`KC_RAPC` |按住时右Alt，点击时 `)` |
31|`KC_SFTENT`|按住时右Shift，点击时回车 |
32
33## 须留意
34
35同时按下两边的Shift键时会与Space Cadet功能冲突。请参见[指令功能](zh-cn/feature_command.md)以了解如何解决，也可以在 `rules.mk` 中禁用指令：
36
37```make
38COMMAND_ENABLE = no
39```
40
41## 配置
42
43默认情况下Space Cadet假设键盘布局为US ANSI，如果你的布局使用不同的括号符，可以在 `config.h` 中重定义。可以修改修饰键点击时发送的字符，亦或阻止修饰键工作。这个新的配置项依次绑定了三个键码：按住或组合其它键使用时的修饰键；点击时发送的修饰键点击（`Tap Modifier`）（在 `KC_TRNS` 中没有修饰键时）；最后是点击时发送的键码。请记住，例如'KC_RSFT'按住时点击 `KC_KSPO` 及 `KC_TRNS` 时，修饰键依旧会对键码生效，即属于修饰键点击。
44
45|定义 |默认值 |描述 |
46|----------------|-------------------------------|----------------------------------------------------------------|
47|`LSPO_KEYS` |`KC_LSFT, LSPO_MOD, LSPO_KEY` |按住时发送`KC_LSFT`，点击时发送 `LSPO_MOD` 及 `LSPO_KEY` 定义的键码. |
48|`RSPC_KEYS` |`KC_RSFT, RSPC_MOD, RSPC_KEY` |按住时发送`KC_RSFT`，点击时发送 `RSPC_MOD` 及 `RSPC_KEY` 定义的键码. |
49|`LCPO_KEYS` |`KC_LCTL, KC_LSFT, KC_9` |按住时发送`KC_LCTL`，点击时发送 `KC_LSFT` 及 `KC_9`. |
50|`RCPC_KEYS` |`KC_RCTL, KC_RSFT, KC_0` |按住时发送`KC_RCTL`，点击时发送 `KC_RSFT` 及 `KC_0`. |
51|`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |按住时发送`KC_LALT`，点击时发送 `KC_LSFT` 及 `KC_9`. |
52|`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |按住时发送`KC_RALT`，点击时发送 `KC_RSFT` 及 `KC_0`. |
53|`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |按住时发送`KC_RSFT`，点击时发送 `SFTENT_KEY`. |
54|`SPACE_CADET_MODIFIER_CARRYOVER` |*未定义* |在尝试触发其它修饰键的修饰键点击前，暂存目前的修饰键。这在尝试触发Space Cadet前频繁发生修饰键提前松开时会有用。(译注[^1]) |
55
56
57## 过时的配置项
58
59以下是一些内部用于向后兼容的定义，目前仍可以使用，但上面的定义适用性要强得多。例如，若你点击 `KC_LSPO` 时不想按住修饰键，在旧定义中只有一个办法，使用 `DISABLE_SPACE_CADET_MODIFIER`。但现在可以定义为：`#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`，效果是在按住按键时触发左Shift，点击则发送 `KC_9`。
60
61|定义 |默认值 |描述 |
62|------------------------------|-------------|-------------------------------------|
63|`LSPO_KEY` |`KC_9` |点击左Shift时发送的键码 |
64|`RSPC_KEY` |`KC_0` |点击右Shift时发送的键码 |
65|`LSPO_MOD` |`KC_LSFT` |应用在 `LSPO_KEY` 上的修饰键 |
66|`RSPC_MOD` |`KC_RSFT` |应用在 `RSPC_KEY` 上的修饰键 |
67|`SFTENT_KEY` |`KC_ENT` |点击Shift时发送的键码 |
68|`DISABLE_SPACE_CADET_MODIFIER`|*未定义* |定义时将阻止修饰键应用在Space Cadet上 |
69
70[^1]这句实在是绕，不能确保翻译到位，请参考英文文档
diff --git a/docs/zh-cn/flashing.md b/docs/zh-cn/flashing.md
new file mode 100644
index 000000000..da3ceefc3
--- /dev/null
+++ b/docs/zh-cn/flashing.md
@@ -0,0 +1,329 @@
1# 刷写指引及Bootloader资料
2
3<!---
4 original document: 0.15.12:docs/flashing.md
5 git diff 0.15.12 HEAD -- docs/flashing.md | cat
6-->
7
8用于键盘的bootloader有很多种，几乎每一种都在使用私有的刷写协议及工具。幸运的是，形如[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)这样的工程目标就是尽量支持这些工具，本文会探讨各种bootloader的差异，以及可用的刷写方案。
9
10针对基于AVR的键盘，QMK会自动检查所要刷写的 `.hex` 文件大小是否与在 `rules.mk` 中设置的 `BOOTLOADER` 值所匹配，同时会输出字节大小信息（及最大限制）。
11
12同时也可以使用CLI工具刷写键盘，执行：
13```
14$ qmk flash -kb <keyboard> -km <keymap>
15```
16更多信息参见文档[`qmk flash`](zh-cn/cli_commands.md#qmk-flash)。
17
18## Atmel DFU
19
20Atmel系列的DFU bootloader默认配备在所有USB AVR系列上（16/32U4RC除外），广泛用于一些PCB上具备私有集成电路模块（IC）的键盘上（老款OLKB、Clueboards等）。有些使用的是LUFA实现的DFU bootloader，或是QMK的分支版本（新款OLKB），后者对硬件功能进行了扩充加强。
21
22为保证对DFU bootloader的兼容性，请确保在 `rules.mk` 中存在如下部分内容（可选的值还有 `lufa-dfu` 或 `qmk-dfu`）：
23
24```make
25# 选择Bootloader
26BOOTLOADER = atmel-dfu
27```
28
29兼容的刷写工具：
30
31* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
32* [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / QMK中将构建目标设为 `:dfu`（推荐的命令行工具）
33
34刷写过程：
35
361. 使用如下任一方式进入bootloader模式：
37 * 点击 `RESET` 键码
38 * 如果PCB上有 `RESET` 键，点击之
39 * 快速短接一下RST到GND
402. 等待操作系统识别到设备
413. 清空flash存储数据（如果使用QMK工具箱或CLI的 `make`会自动进行）
424. 将.hex文件刷写进去
435. 重置设备进入应用模式（如上，会自动进行）
44
45### QMK DFU
46
47QMK维护了[一个LUFA DFU bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/DFU)，其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。若要启用该功能，将以下定义添加到 `config.h`：
48
49```c
50#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW
51#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW
52// 可选:
53//#define QMK_LED E6
54//#define QMK_SPEAKER C6
55```
56目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。
57
58制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。
59
60要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。
61
62### `make` 构建目标
63
64* `:dfu`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。
65* `:dfu-split-left` 和 `:dfu-split-right`: 同 `:dfu` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Elite-C的分体式键盘这是理想的方法。
66
67## Caterina
68
69Arduino及其仿制板使用[Caterina bootloader](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina)或某种变体（使用Pro Micro或其仿制芯片、Pololu A-Star等构建的所有键盘），并基于虚拟串口使用AVR109协议进行通信。
70
71为确保对Caterina bootloader的兼容性，请添加如下代码块至 `rules.mk`：
72
73```make
74# 选择Bootloader
75BOOTLOADER = caterina
76```
77
78兼容的刷写工具：
79
80* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具）
81* [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `avr109` 编程器 / `:avrdude` 构建目标 （推荐的命令行工具）
82* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
83
84刷写过程：
85
861. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写；一些型号需要你在750ms内重置两次）：
87 * 点击 `RESET` 键码
88 * 如果PCB上有 `RESET` 键，点击之
89 * 快速短接一下RST到GND
902. 等待操作系统识别到设备
913. 将.hex文件刷写进去
924. 等待设备自动重置
93
94### `make` 构建目标
95
96* `:avrdude`: 每5秒检测一次直到发现可用的Caterina设备（通过检测新COM端口），然后进行固件刷写。
97* `:avrdude-loop`: 同 `:avrdude` 一样刷写固件，但会在一个设备刷写完后再次尝试刷写。主要用于批量刷写设备。按 Ctrl+C 以终止循环检测。
98* `:avrdude-split-left` 和 `:avrdude-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Pro Micro的分体式键盘这是理想的方法。
99
100## HalfKay
101
102HalfKay是一款由PJRC开发的超精简的bootloader，且呈现为HID设备（因此不需要额外的驱动），在所有的Teensys，即"the 2.0"，上已经预刷写过。该bootloader目前是闭源的，因此一旦覆写（即通过ISP刷入其它bootloader）掉，就无法复原了。
103
104为确保对Halfkay bootloader的兼容性，请添加如下代码块至 `rules.mk`：
105
106```make
107# 选择Bootloader
108BOOTLOADER = halfkay
109```
110
111兼容的刷写工具：
112
113* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
114* [Teensy Loader Command Line](https://www.pjrc.com/teensy/loader_cli.html) / QMK中将构建目标设为 `:teensy`（推荐的命令行工具）
115* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
116
117刷写过程：
118
1191. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）：
120 * 点击 `RESET` 键码
121 * 如果Teensy上或PCB上有 `RESET` 键，点击之
122 * 快速短接一下RST到GND
1232. 等待操作系统识别到设备
1243. 将.hex文件刷写进去
1254. 重置设备进入应用模式（可能会自动进行）
126
127## USBasploader
128
129USBasploader是一款来源于[Objective Development](https://www.obdev.at/products/vusb/usbasploader.html)的bootloader。它通过模拟出一个USBasp ISP编程器来运行V-USB以用于一些形如ATmega328P这样的“非USB AVR芯片”。
130
131为确保对USBasploader bootloader的兼容性，请添加如下代码块至 `rules.mk`：
132
133```make
134# 选择Bootloader
135BOOTLOADER = usbasploader
136```
137
138兼容的刷写工具：
139
140* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
141* [avrdude](https://www.nongnu.org/avrdude/) QMK中须基于 `usbasp` 编程器 / `:usbasp` 构建目标（推荐的命令行工具）
142* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
143
144刷写过程：
145
1461. 使用如下任一方式进入bootloader模式：
147 * 点击 `RESET` 键码
148 * 在按住 `BOOT` 按钮时，快速点击一下PCB上的 `RESET`
1492. 等待操作系统识别到设备
1503. 将.hex文件刷写进去
1514. 点击PCB上的 `RESET` 按钮或将RST短接至GND一下。
152
153## BootloadHID
154
155BootloadHID是一款用于AVR微控制器的bootloader，其呈现为HID输入设备，和HalkKay很像，因此在Windows下也无需安装驱动。
156
157为确保对bootloadHID bootloader的兼容性，请添加如下代码块至 `rules.mk`：
158
159```make
160# 选择Bootloader
161BOOTLOADER = bootloadhid
162```
163
164兼容的刷写工具：
165
166* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
167* [bootloadHID CLI](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK中将构建目标设为 `:bootloadhid`（推荐的命令行工具）
168* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash)
169
170
171刷写过程：
172
1731. 使用如下任一方式进入bootloader模式：
174 * 点击 `RESET` 键码
175 * 在按住“盐键”（salt key）时插入键盘 - 在PS2AVRGB板上，通常在MCU的A0及B0引脚上有这个按键，否则请查看键盘的使用说明。
1762. 等待操作系统识别到设备
1773. 将.hex文件刷写进去
1784. 重置设备到应用模式（可能会自动进行）
179
180### QMK HID
181
182QMK维护了[一个LUFA HID bootloader的分支版本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID)，通过USB HID节点设备进行刷写，工作模式类似于PJRC的Teensy Loader刷写器以及HalfKay bootloader。其可以进行一次矩阵扫描来退出bootloader进入应用模式，同时会让LED闪烁或蜂鸣器响一声。
183
184为确保对QMK HID bootloader的兼容性，请添加如下代码块至 `rules.mk`：
185
186```make
187# 选择Bootloader
188BOOTLOADER = qmk-hid
189```
190
191要启用额外的功能支持，请添加如下定义至 `config.h`：
192
193```c
194#define QMK_ESC_OUTPUT F1 // COL pin if COL2ROW
195#define QMK_ESC_INPUT D5 // ROW pin if COL2ROW
196// 可选:
197//#define QMK_LED E6
198//#define QMK_SPEAKER C6
199```
200
201目前来讲不推荐将 `QMK_ESC` 键设置成与[Bootmagic Lite](zh-cn/feature_bootmagic.md)同一个键，否则按下该键时只会让MCU在bootloader模式上反复进出。
202
203制造商及型号字符串自动从 `config.h` 中获取，并会在型号后追加 " Bootloader"。
204
205要生成该bootloader，需指定 `bootloader` 构建目标，即 `make planck/rev4:default:bootloader`。要生成可部署到正式产品的.hex文件（同时包含QMK及bootloader），使用 `production` 构建目标，即 `make planck/rev4:default:production`。
206
207兼容的刷写工具：
208
209* TBD
210 * 目前只能选择使用该 [Python脚本](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp_python), 或从LUFA仓库中构建[`hid_bootloader_cli`](https://github.com/qmk/lufa/tree/master/Bootloaders/HID/HostLoaderApp)。Homebrew也许（即将）能直接支持（通过 `brew install qmk/qmk/hid_bootloader_cli`）。
211
212刷写过程：
213
2141. 使用如下任一方式进入bootloader模式：
215 * 点击 `RESET` 键码
216 * 如果PCB上有 `RESET` 键，点击之
217 * 快速短接一下RST到GND
2182. 等待操作系统识别到设备
2194. 将.hex文件刷写进去
2205. 重置设备进入应用模式（可能会自动进行）
221
222### `make` 构建目标
223
224* `:qmk-hid`: 每5秒检测一次直到发现可用的DFU设备，然后进行固件刷写。
225
226## STM32/APM32 DFU
227
228所有的STM32及APM32 MCU系列，除F103型号外（参见[STM32duino小节](#stm32duino)）都在出场时预装了bootloader且无法修改或删除。
229
230为确保对STM32-DFU bootloader的兼容性，请添加如下代码块至 `rules.mk`（可选替代项为 `apm32-dfu`）：
231
232```make
233# 选择Bootloader
234BOOTLOADER = stm32-dfu
235```
236
237兼容的刷写工具：
238
239* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具）
240* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具）
241
242刷写过程：
243
2441. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）：
245 * 点击 `RESET` 键码（对STM32F042设备可能无效）
246 * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开
247 * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。
2482. 等待操作系统识别到设备
2493. 将.bin文件刷写进去
2504. 重置设备进入应用模式（可能会自动进行）
251
252### `make` 构建目标
253
254* `:dfu-util`: 每5秒检测一次直到发现可用的STM32 bootloader设备，然后进行固件刷写。
255* `:dfu-util-split-left` 和 `:dfu-util-split-right`: 同 `:avrdude` 一样会刷写固件，但额外地会设置手性设置到EEPROM中，对于基于Proton-C的分体式键盘这是理想的方法。
256* `:st-link-cli`: 通过ST-Link CLI工具集而非dfu-util进行刷写，需要有ST-Link电子狗。
257* `:st-flash`: 通过[STLink工具](https://github.com/stlink-org/stlink)内的 `st-flash` 工具而非dfu-util进行刷写，需要有ST-Link电子狗。
258
259## STM32duino :id=stm32duino
260
261该bootloader几乎是STM32F103板专用，该型号出厂不带USB DFU bootloader。其源代码及预编译好的二进制文件[在这里](https://github.com/rogerclarkmelbourne/STM32duino-bootloader)。
262
263为确保对STM32duino bootloader的兼容性，请添加如下代码块至 `rules.mk`：
264
265```make
266# 选择Bootloader
267BOOTLOADER = stm32duino
268```
269
270兼容的刷写工具：
271
272* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases) （推荐的图形化工具）
273* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具）
274
275刷写过程：
276
2771. 使用如下任一方式进入bootloader模式（进入该模式后只有7秒时间可以刷写）：
278 * 点击 `RESET` 键码（对STM32F042设备可能无效）
279 * 如果有重置电路，点击PCB上的 `RESET` 键；有些主控板上可能会有一个开关需要先打开
280 * 否则，你需要将 `BOOT0` 接线到VCC（通过 `BOOT0` 按钮或跳线），短接 `RESET` 至GND（通过 `RESET` 按钮或条线），然后断开 `BOOT0` 的接线。
2812. 等待操作系统识别到设备
2823. 将.bin文件刷写进去
2834. 重置设备进入应用模式（可能会自动进行）
284
285## Kiibohd DFU
286
287Input Club出品的键盘使用NXP Kinetis微控制器而非STM32，并使用了独有的[自制bootloader](https://github.com/kiibohd/controller/tree/master/Bootloader)，然而处理器 及协议上两者大部分是一致的。
288
289在 `rules.mk` 中该bootloader的设置项为 `kiibohd`，但既然该bootloader仅用在Input Club主控板上，就不必要设置到键映射或是用户级<!--译：不清楚这里的“user level”是个啥……-->了。
290
291兼容的刷写工具：
292
293* [QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)（推荐的图形化工具）
294* [dfu-util](https://dfu-util.sourceforge.net/) / QMK中将构建目标设为 `:dfu-util`（推荐的命令行工具）
295
296刷写过程：
297
2981. 使用如下任一方式进入bootloader模式：
299 * 点击 `RESET` 键码（有可能只能进入到“安全”bootloader模式，参见[这里](https://github.com/qmk/qmk_firmware/issues/6112)）
300 * 如果PCB上有 `RESET` 键，点击之
3012. 等待操作系统识别到设备
3023. 将.bin文件刷写进去
3034. 重置设备进入应用模式（可能会自动进行）
304
305## tinyuf2
306
307键盘可以考虑支持tinyuf2 bootloader，目前唯一支持的设备是F401/F411 blackpill。
308
309在 `rules.mk` 中该bootloader的设置项为 `tinyuf2`，也可指定到键映射及用户级中。
310
311为确保对tinyuf2 bootloader的兼容性，请添加如下代码块至 `rules.mk`：
312
313```make
314# 选择Bootloader
315BOOTLOADER = tinyuf2
316```
317
318兼容的刷写工具：
319
320* 任何具备文件拷贝能力的程序，如 _macOS Finder_ 或 _Windows Explorer_ *。
321
322刷写过程：
323
3241. 使用如下任一方式进入bootloader模式：
325 * 点击 `RESET` 键码
326 * 双击PCB上的 `nRST` 键
3272. 等待操作系统识别到设备
3283. 将.uf2文件拷贝到新出现的USB存储设备上
3294. 等待设备恢复可用状态
diff --git a/docs/zh-cn/flashing_bootloadhid.md b/docs/zh-cn/flashing_bootloadhid.md
new file mode 100644
index 000000000..70139c1e1
--- /dev/null
+++ b/docs/zh-cn/flashing_bootloadhid.md
@@ -0,0 +1,75 @@
1# BootloadHID刷写指引及资料
2
3<!---
4 original document: 0.15.12:docs/flashing_bootloadhid.md
5 git diff 0.15.12 HEAD -- docs/flashing_bootloadhid.md | cat
6-->
7
8ps2avr(GB)基于一片ATmega32A微控制器及特殊的bootloader，无法使用常规的QMK方法进行刷写。
9
10常规刷写过程：
11
121. 使用如下任一方式进入bootloader模式：
13 * 点击 `RESET` 键码（一些设备上不管用）
14 * 在按住“盐键”（salt key）时插入键盘（该键一般会在键盘使用说明上写明）
152. 等待操作系统识别到设备
163. 将.hex文件刷写进去
174. 重置设备到应用模式（可能会自动进行）
18
19## 用于bootloadHID刷写的构建目标
20
21?> 使用QMK安装脚本，具体[参见这里](zh-cn/newbs_getting_started.md)，所需的bootloadHID工具应自动被安装上。
22
23若希望通过命令行进行刷写，通过如下命令指定 `:bootloadhid` 构建目标：
24
25 make <keyboard>:<keymap>:bootloadhid
26
27## 基于图形化界面的刷写方法
28
29### Windows
301. 下载[HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash)
312. 重置键盘
323. 确认VID为 `16c0` 且PID为 `05df`
334. 点击 `查找设备（Find Device）` 并确认目标键盘可见
345. 点击 `打开.hex文件（Open .hex File）` 并定位到你创建的.hex文件
356. 点击 `刷写设备（Flash Device）` 并等待刷写完毕
36
37## 在命令行中进行刷写
38
391. 重置键盘
402. 通过输入 `bootloadHID -r` 并追加 `.hex` 文件的路径进行主控板的刷写
41
42### Windows系统上手动安装
43针对MSYS2:
441. 下载BootloadHID固件包：https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz
452. 使用合适的工具解压，如7-Zip
463. 将解压出的 `commandline/bootloadHID.exe` 拷贝至MSYS目录下，一般是 `C:\msys64\usr\bin`
47
48针对Windows本地环境刷写，`bootloadHID.exe` 可以直接在非MSYS2环境下执行。
49
50### Linux系统上手动安装
511. 安装libusb开发依赖项：
52 ```bash
53 # 该操作具体取决于系统 - Debian下可以这样
54 sudo apt-get install libusb-dev
55 ```
562. 下载BootloadHID固件包：
57 ```
58 wget https://www.obdev.at/downloads/vusb/bootloadHID.2012-12-08.tar.gz -O - | tar -xz -C /tmp
59 ```
603. 构建bootloadHID可执行程序：
61 ```
62 cd /tmp/bootloadHID.2012-12-08/commandline/
63 make
64 sudo cp bootloadHID /usr/local/bin
65 ```
66
67### MacOS系统上手动安装
681. 执行以下命令安装Homebrew：
69 ```
70 /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
71 ```
722. 安装以下包：
73 ```
74 brew install --HEAD https://raw.githubusercontent.com/robertgzr/homebrew-tap/master/bootloadhid.rb
75 ```
diff --git a/docs/zh-cn/getting_started_docker.md b/docs/zh-cn/getting_started_docker.md
new file mode 100644
index 000000000..038f17f9a
--- /dev/null
+++ b/docs/zh-cn/getting_started_docker.md
@@ -0,0 +1,59 @@
1# Docker快速上手指引
2
3<!---
4 original document: 0.15.12:docs/getting_started_docker.md
5 git diff 0.15.12 HEAD -- docs/getting_started_docker.md | cat
6-->
7
8本工程包含了一套Docker工作流，可以方便地在不更改你主系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与其他人以及QMK开发者的一致。当你需要其他人协助你排查遇到的问题时会方便很多。
9
10## 需求
11
12核心需求是一个已安装的可用的 `docker` 或 `podman`。
13* [Docker CE](https://docs.docker.com/install/#supported-platforms)
14* [Podman](https://podman.io/getting-started/installation)
15
16## 用法
17
18拉取QMK仓库到本地（包括所有的子模块）：
19
20```bash
21git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
22cd qmk_firmware
23```
24
25执行以下命令构建键映射：
26```bash
27util/docker_build.sh <keyboard>:<keymap>
28# 例: util/docker_build.sh planck/rev6:default
29```
30
31如上可以构建所需的键盘/键映射，可用于刷写的 `.hex` 及 `.bin` 输出文件存放在QMK目录下。如果省略了 `:keymap` 参数，所有的键映射都会被编译。留意编译参数格式与 `make` 构建时的一致。
32
33同时也支持直接从Docker中编译和刷写，只需要指定 `target`：
34
35```bash
36util/docker_build.sh keyboard:keymap:target
37# 例: util/docker_build.sh planck/rev6:default:flash
38```
39
40可以不带参数地执行该脚本，其会依次要求你输入这些参数，也许你会觉得这样更好用：
41
42```bash
43util/docker_build.sh
44# 从输入中读取参数 (留空则构建所有的键盘/键映射)
45```
46
47可以通过设置环境变量 `RUNTIME` 为想使用的容器运行时的名称或路径来指定运行时，默认其会检测并自动选取docker或podman，相比于podman会更倾向于用docker。
48
49```bash
50RUNTIME="podman" util/docker_build.sh keyboard:keymap:target
51```
52
53## FAQ
54
55### 为什么我无法在我的Windows/macOS下刷写固件
56
57在Windows及macOS上，需要有[Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/)运行着，配置过程很繁琐，因此我们没有做推荐。请考虑使用[QMK工具箱](https://github.com/qmk/qmk_toolbox)。
58
59!> Windows下需要启用[Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v)才能运行Docker，这也意味着它无法运行在没有Hyper-V的Windows版本下，如Windows 7，Windows 8及**Windows 10家庭版**。
diff --git a/docs/zh-cn/getting_started_getting_help.md b/docs/zh-cn/getting_started_getting_help.md
deleted file mode 100644
index 8c0ebaa24..000000000
--- a/docs/zh-cn/getting_started_getting_help.md
+++ /dev/null
@@ -1,15 +0,0 @@
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
index b4e8e9fa5..2a5ec8ca4 100644
--- a/docs/zh-cn/getting_started_github.md
+++ b/docs/zh-cn/getting_started_github.md
@@ -1,6 +1,11 @@
1# 如何在QMK中使用GitHub 1# 如何在QMK中使用GitHub
2 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. 3<!---
4 original document: 0.15.12:docs/getting_started_github.md
5 git diff 0.15.12 HEAD -- docs/getting_started_github.md | cat
6-->
7
8对不熟悉 GitHub 的人来说，使用GitHub 可能会有些难度。此教程会教您 fork 和 clone QMK，以及向 QMK 提交 pull request 。
4 9
5?> 本教程假设您已安装GitHub，并且您喜欢使用命令行工作。 10?> 本教程假设您已安装GitHub，并且您喜欢使用命令行工作。
6 11
diff --git a/docs/zh-cn/getting_started_introduction.md b/docs/zh-cn/getting_started_introduction.md
index b977b6339..82d50355e 100644
--- a/docs/zh-cn/getting_started_introduction.md
+++ b/docs/zh-cn/getting_started_introduction.md
@@ -1,5 +1,10 @@
1# 介绍 1# 介绍
2 2
3<!---
4 original document: 0.15.12:docs/getting_started_introduction.md
5 git diff 0.15.12 HEAD -- docs/getting_started_introduction.md | cat
6-->
7
3本页解释了使用QMK项目所需的基本信息。它假定您能熟练使用Unix shell，但您不熟悉C语言也不熟悉使用make编译。 8本页解释了使用QMK项目所需的基本信息。它假定您能熟练使用Unix shell，但您不熟悉C语言也不熟悉使用make编译。
4 9
5## 基本QMK结构 10## 基本QMK结构
@@ -8,7 +13,7 @@ QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk
8 13
9### 用户空间结构 14### 用户空间结构
10 15
11在`users`文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。详见[用户空间特性](feature_userspace.md) 16在`users`文件夹里面的目录是每个用户的目录。这个文件夹里面放的是用户们在不同键盘都能用到的代码。详见[用户空间特性](zh-cn/feature_userspace.md)
12 17
13### 键盘项目结构 18### 键盘项目结构
14 19
@@ -25,7 +30,7 @@ QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk
25* `config.h`: 配置布局的选项 30* `config.h`: 配置布局的选项
26* `keymap.c`: 布局的全部代码, 必要文件 31* `keymap.c`: 布局的全部代码, 必要文件
27* `rules.mk`: 使能的QMK特性 32* `rules.mk`: 使能的QMK特性
28* `readme.md`:介绍你的布局,告诉别人怎么使用，附上功能说明。请将图片上传到imgur等图床（译者注：imgur可能已被墙，为了方便国人访问，建议使用国内可以直接访问的图床）。 33* `readme.md`:介绍你的布局,告诉别人怎么使用，附上功能说明。请将图片上传到imgur等图床（译注：imgur可能已被墙，为了方便国人访问，建议使用国内可以直接访问的图床）。
29 34
30# `config.h` 文件 35# `config.h` 文件
31 36
diff --git a/docs/zh-cn/getting_started_vagrant.md b/docs/zh-cn/getting_started_vagrant.md
new file mode 100644
index 000000000..5e5de4455
--- /dev/null
+++ b/docs/zh-cn/getting_started_vagrant.md
@@ -0,0 +1,61 @@
1# Vagrant快速上手指引
2
3<!---
4 original document: 0.15.12:docs/getting_started_vagrant.md
5 git diff 0.15.12 HEAD -- docs/getting_started_vagrant.md | cat
6-->
7
8本工程包含一份 `Vagrantfile`，可以方便地在不更改你系统环境情况下完成新固件文件的构建工作。这同时也保证了在你拉取该工程代码后的编译环境与也使用Vagrantfile的其它人的一致。当你需要其他人协助你排查遇到的问题时会方便很多。
9
10## 需求
11
12本工程中的 `Vagrantfile` 需要安装[Vagrant](https://www.vagrantup.com/)以及可用的虚拟机服务：
13
14* [VirtualBox](https://www.virtualbox.org/) (5.0.12及以后版本)
15 * 卖点是'最适用于Vagrant的平台'
16* [VMware Workstation](https://www.vmware.com/products/workstation) 及 [Vagrant VMware插件](https://www.vagrantup.com/vmware)
17 * （付费购买的）VMware插件需要在经过正版授权的VMware Workstation/Fusion上运行
18* [Docker](https://www.docker.com/)
19
20安装了Vagrant之后，在安装合适的虚拟机服务后可能需要重启机器。拉取本工程后在工程目录下执行 'vagrant up' 将启动一个包含了所有本工程所需工具的构建环境（虚拟机或是容器）。最后会有一个vagrant启动提示告知你一切正常就绪，否则你也可以参考一下下面的构建文档。
21
22## 刷写固件
23
24比较“简单”的方案是在你的宿主系统上借助以下工具刷写固件：
25
26* [QMK工具箱](https://github.com/qmk/qmk_toolbox) (推荐)
27* [Teensy Loader](https://www.pjrc.com/teensy/loader.html)
28
29如果你希望通过命令行进行编程工作，可以在Vagrantfile中取消掉['modifyvm']的注释以允许USB直通到Linux环境，既可以使用dfu-util/dfu-programmer之类的命令行工具进行编程工作，或是安装Teensy的命令行版本。
30
31## Vagrantfile概览
32开发环境被配置为运行QMK Docker镜像 `qmkfm/qmk_cli`，不仅让各系统下的功能预期一致，也是我们CI环境的镜像。
33
34## FAQ
35
36### 为什么我的VirtualBox环境会有问题？
37VirtualBox 5的某些版本与工程中Vagrantfile中指定的VirtualBox扩展存在兼容问题。如果你遇到了/vagrant挂载不成功的问题，请升级VirtualBox至5.0.12或更高版本。**或者，可以尝试执行如下命令：**
38
39```console
40vagrant plugin install vagrant-vbguest
41```
42
43### 如何移除一个现有环境？
44不再需要这个环境了是吗？在本工程目录下的任何位置，执行：
45
46```console
47vagrant destroy
48```
49
50### 如果我是想直接用Docker呢？
51想在不使用虚拟机技术的情况下也能使用Vagrant工作流？Vagrangfile已配置为允许绕过运行虚拟机，直接运行容器。通过如下方式执行命令可以强制使用Docker来启动环境：
52```console
53vagrant up --provider=docker
54```
55
56### 如何访问虚拟机环境而非Docker容器？
57通过如下方法跳过 `vagrant` 的用户初始化过程以在QMK构建镜像中直接执行：
58
59```console
60vagrant ssh -c 'sudo -i'
61```
diff --git a/docs/zh-cn/keymap.md b/docs/zh-cn/keymap.md
new file mode 100644
index 000000000..b4433ed49
--- /dev/null
+++ b/docs/zh-cn/keymap.md
@@ -0,0 +1,209 @@
1# 键映射总览
2
3<!---
4 original document: 0.15.12:docs/keymap.md
5 git diff 0.15.12 HEAD -- docs/keymap.md | cat
6-->
7
8QMK键映射定义在C源文件中，其数据结构上是一个容纳了数组的数组。外层数组容纳了各个层，内层各数组则为层内的键列表。基本所有键盘都通过定义 `LAYOUT()` 宏来创建该两级数组。
9
10
11## 键映射与配列 :id=keymap-and-layers
12在QMK中, **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** 容纳了多个 **层**， 每个**层**下包含了由**16位**的**动作码**所组成的键映射信息。 最多可以定义**32个层**。
13
14对于常规键的定义，其**动作码**的高8位皆为0，低8位保存了USB HID中使用的各个键对应的**键码**。
15
16不同的层可以同时生效，层的编号从0至31，编号越高的层优先级越高。
17（译注：由于是ascii图，掺杂中文会导致排版错乱，各翻译标注在图下方。下同）
18
19 Keymap: 32 Layers Layer: action code matrix
20 ----------------- ---------------------
21 stack of layers array_of_action_code[row][column]
22 ____________ precedence _______________________
23 / / | high / ESC / F1 / F2 / F3 ....
24 31 /___________// | /-----/-----/-----/-----
25 30 /___________// | / TAB / Q / W / E ....
26 29 /___________/ | /-----/-----/-----/-----
27 : _:_:_:_:_:__ | : /LCtrl/ A / S / D ....
28 : / : : : : : / | : / : : : :
29 2 /___________// | 2 `--------------------------
30 1 /___________// | 1 `--------------------------
31 0 /___________/ V low 0 `--------------------------
32翻译：
33
34|原文 |译文 |
35|--------------------------|-------------|
36|Keymap: 32 Layers | 键映射：32个层|
37|stack of layers | 层堆栈 |
38|precedence | 优先级 |
39|high/low | 高/低 |
40|layer: action code matrix | 层：动作码矩阵|
41|row/column | 行/列 |
42
43有时，键映射中存储的动作码在一些文档中也被称作键码，主要是由TMK沿袭而来的习惯。
44
45### 键映射的层状态 :id=keymap-layer-status
46
47键映射的层状态由两个32位参数决定：
48
49* **`default_layer_state`** 指向一个总是可用的键映射层（0-31）（即默认层）。
50* **`layer_state`** 每一位标记对应层的启用/停用状态。
51
52通常键映射中的'0'层为 `default_layer（默认层）`，其它层在启动时会被固件置为停用状态，不过这些可以通过 `config.h` 进行配置。当你换了一个按键布局时可用于更改 `default_layer`，比如从Qwerty布局切换到了Colemak布局。
53
54 Initial state of Keymap Change base layout
55 ----------------------- ------------------
56
57 31 31
58 30 30
59 29 29
60 : :
61 : : ____________
62 2 ____________ 2 / /
63 1 / / ,->1 /___________/
64 ,->0 /___________/ | 0
65 | |
66 `--- default_layer = 0 `--- default_layer = 1
67 layer_state = 0x00000001 layer_state = 0x00000002
68翻译：
69
70|原文 |译文 |
71|-----------------------|-------------|
72|Initial state of Keymap| 键映射原始状态|
73|Change base layout | 更改了基础层 |
74
75另外，可以通过修改 `layer_state` 做到其他层对基础层的覆盖，以实现诸如导航键、功能键（F1-F12）、多媒体键等特殊动作。
76
77 Overlay feature layer
78 --------------------- bit|status
79 ____________ ---+------
80 31 / / 31 | 0
81 30 /___________// -----> 30 | 1
82 29 /___________/ -----> 29 | 1
83 : : | :
84 : ____________ : | :
85 2 / / 2 | 0
86 ,->1 /___________/ -----> 1 | 1
87 | 0 0 | 0
88 | +
89 `--- default_layer = 1 |
90 layer_state = 0x60000002 <-'
91
92
93
94### 层优先级及穿透
95须记住**层堆栈中更高的层有着更高的优先级**。固件会从最高的活跃层开始向下找键码，一旦固件在活跃层上找到了一个非 `KC_TRNS`（穿透）键码，就会停止查找，再往下的层级不会被查看。
96
97 ____________
98 / / <--- 较高的层
99 / KC_TRNS //
100 /___________// <--- 较低的层 (KC_A)
101 /___________/
102
103 这个场景中，较高层级中的非穿透键是可用的，如果定义为 `KC_TRNS`（及同等效果的），较低层级的键码 `KC_A` 将被采纳。
104
105**注意：** 在层中定义合法的穿透键的方法有：
106* `KC_TRANSPARENT`
107* `KC_TRNS`（别名）
108* `_______`（别名）
109
110这些键码允许在搜索非穿透键码时可以穿透当前层下落到更低层去。
111
112## `keymap.c` 文件解析
113
114本例中我们将深入到[Clueboard 66%的一款旧版的默认键映射](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/keyboards/clueboard/keymaps/default/keymap.c)方案中去。将该文件在另一个浏览器窗口中打开，以便对照本文进行同步阅览。
115
116在一个 `keymap.c` 文件中会有三个你可能会关心的部分：
117
118* [预定义](#definitions)
119* [层/键映射数据结构](#layers-and-keymaps)
120* [自定义函数](#custom-functions)，若有的话
121
122### 预定义
123
124文件头部可以看到：
125
126 #include QMK_KEYBOARD_H
127
128 // Helpful defines
129 // 译：便捷性的宏定义
130 #define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
131
132 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
133 * You can use _______ in place for KC_TRNS (transparent) *
134 * Or you can use XXXXXXX for KC_NO (NOOP) *
135 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
136 // 译：可以用 _______ 替代 KC_TRNS（穿透），用 XXXXXXX 替代 KC_NO (空操作)
137
138 // Each layer gets a name for readability.
139 // The underscores don't mean anything - you can
140 // have a layer called STUFF or any other name.
141 // Layer names don't all need to be of the same
142 // length, and you can also skip them entirely
143 // and just use numbers.
144 // 译：每一层为了便于识别可以起一个名字，下划线没有实际意义 - 叫STUFF之类的也行的，
145 // 译：层名不需要都一样长，甚至不定义这些直接用层号也是可以的
146 #define _BL 0
147 #define _FL 1
148 #define _CL 2
149
150以上是一些便于编写键映射及自定义函数时可用的预定义，`GRAVE_MODS` 后续会用在自定义函数中，之后的 `_BL`, `_FL` 及 `_CL` 便于我们在代码中引用这些层。
151
152注：在一些更早的键映射文件中，你可能会发现一些形如 `_______` 或 `XXXXXXX` 的定义，这些可以分别代替 `KC_TRNS` 及 `KC_NO`，这样可以更清楚地分辨出各层中定义了哪些键的键值。现在这些定义是不需要的，因为我们默认已经提供了这些定义。
153
154### 层和键映射
155
156这个文件中最主要的部分是 `keymaps[]` 定义，这里须列出你的层以及层中的内容。这一部分应该以如下定义起始：
157
158 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
159
160之后是一个LAYOUT()宏组成的列表，一个LAYOUT()下定义了一个层中的键列表，一般你需要至少一个“基础层”（如QWERTY、Dvorak或Colemak），之后是在其之上的多个“功能”层。受限于对层的处理顺序，较低的层无法覆盖在较高的层上。
161
162QMK在 `keymaps[][MATRIX_ROWS][MATRIX_COLS]` 中保存着16位的动作码（有些时候也被称作键码），对于与常规键一致的键码，其高字节为0，低字节为USB HID 键盘所使用的键码值。
163
164> QMK的前身TMK中使用 `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` 来存储8位的键码，一些键码被保留用于引用执行 `fn_actions[]` 数组中的特定功能。
165
166#### 基础层
167
168以下示例是Clueboard的基础层定义：
169
170 /* Keymap _BL: Base Layer (Default Layer)
171 */
172 [_BL] = LAYOUT(
173 F(0), KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_GRV, KC_BSPC, KC_PGUP, \
174 KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_PGDN, \
175 KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \
176 KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RO, KC_RSFT, KC_UP, \
177 KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN, KC_SPC,KC_SPC, KC_HENK, KC_RALT, KC_RCTL, MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT),
178
179这里有一些值得留意的地方：
180
181* 站在C语言源代码的角度看，这只是一个数组，但我们掺杂了大量括号使得每个键可以在视觉上与物理设备对齐。
182* 常规的键盘扫描码以KC_起始，而那些“特殊”键则不是。
183* 最左上的键可以触发自定义函数0（`F(0)`）
184* "Fn"键定义为 `MO(_FL)`，当按住该键时会切换到 `_FL` 层。
185
186#### 功能覆盖层
187
188对于功能层，从代码角度讲与基础层没有任何区别。但在概念上讲，应该将其作为覆盖层而非替代层来定义。对大部分人来讲这个区别不重要，但当你构建越来越复杂的层结构时，其重要性会越来越凸显。
189
190 [_FL] = LAYOUT(
191 KC_GRV, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, _______, KC_DEL, BL_STEP, \
192 _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS, _______, _______, _______, _______, \
193 _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \
194 _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \
195 _______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END),
196
197这里值得留意的有：
198
199* 我们使用 `_______` 定义来替代 `KC_TRNS`， 以便凸显在该层中有变化的那些键。
200* 对于这一层来讲，如果点击的是一个 `_______` 键，实际生效的将是其下的活跃层中的键。
201
202# 核心细节
203
204在阅读完本节后，你应该掌握了构建自己的键映射的基础能力，更多的资料请参见：
205
206* [键码](zh-cn/keycodes.md)
207* [键映射FAQ](zh-cn/faq_keymap.md)
208
209我们仍在优化这份文档，如果你有更好的优化建议，请[提交一份issue](https://github.com/qmk/qmk_firmware/issues/new)！
diff --git a/docs/zh-cn/mod_tap.md b/docs/zh-cn/mod_tap.md
new file mode 100644
index 000000000..5bf18a152
--- /dev/null
+++ b/docs/zh-cn/mod_tap.md
@@ -0,0 +1,143 @@
1# Mod-Tap
2
3<!---
4 original document: 0.15.12:docs/mod_tap.md
5 git diff 0.15.12 HEAD -- docs/mod_tap.md | cat
6-->
7
8Mod-Tap键 `MT(mod, kc)` 在按住时功能为修饰键，在点击时则是常规键码。举例来讲，可以设计出一个按键，当点击时发送Escape，按下时则作为Control或Shift
9
10修饰键码及`OSM()`将会被缀以`MOD_`前缀，而非`KC_`
11
12|修饰键码 |描述 |
13|----------|------------------------------------------|
14|`MOD_LCTL`|左Control |
15|`MOD_LSFT`|左Shift |
16|`MOD_LALT`|左Alt |
17|`MOD_LGUI`|左GUI (Windows/Command/Meta键) |
18|`MOD_RCTL`|右Control |
19|`MOD_RSFT`|右Shift |
20|`MOD_RALT`|右Alt (AltGr) |
21|`MOD_RGUI`|右GUI (Windows/Command/Meta键) |
22|`MOD_HYPR`|Hyper (左Control, Shift, Alt 及 GUI同时按下)|
23|`MOD_MEH` |Meh (左Control, Shift, 及 Alt同时按下) |
24
25可以通过逻辑或进行组合：
26
27```c
28MT(MOD_LCTL | MOD_LSFT, KC_ESC)
29```
30
31此时按住该键将触发左Control及左Shift，点击将发送Escape。
32
33为了方便配列，QMK已包含一些常见的Mod-Tap：
34
35|键 |别名 |描述 |
36|------------|-----------------------------------------------------------------|---------------------------------------------|
37|`LCTL_T(kc)`|`CTL_T(kc)` |按住时为左Control，点击时为 `kc` |
38|`LSFT_T(kc)`|`SFT_T(kc)` |按住时为左Shift，点击时为 `kc` |
39|`LALT_T(kc)`|`LOPT_T(kc)`, `ALT_T(kc)`, `OPT_T(kc)` |按住时为左Alt，点击时为 `kc` |
40|`LGUI_T(kc)`|`LCMD_T(kc)`, `LWIN_T(kc)`, `GUI_T(kc)`, `CMD_T(kc)`, `WIN_T(kc)`|按住时为左GUI，点击时为 `kc` |
41|`RCTL_T(kc)`| |按住时为右 Control，点击时为 `kc` |
42|`RSFT_T(kc)`| |按住时为右 Shift，点击时为 `kc` |
43|`RALT_T(kc)`|`ROPT_T(kc)`, `ALGR_T(kc)` |按住时为右 Alt，点击时为 `kc` |
44|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |按住时为右 GUI，点击时为 `kc` |
45|`LSG_T(kc)` |`SGUI_T(kc)`, `SCMD_T(kc)`, `SWIN_T(kc)` |按住时为左Shift及GUI，点击时为 `kc` |
46|`LAG_T(kc)` | |按住时为左Alt及GUI，点击时为 `kc` |
47|`RSG_T(kc)` | |按住时为右 Shift及GUI，点击时为 `kc` |
48|`RAG_T(kc)` | |按住时为右 Alt及GUI，点击时为 `kc` |
49|`LCA_T(kc)` | |按住时为左Control及Alt，点击时为 `kc` |
50|`LSA_T(kc)` | |按住时为左Shift及Alt，点击时为 `kc` |
51|`RSA_T(kc)` |`SAGR_T(kc)` |按住时为右 Shift及右 Alt (AltGr)，点击时为 `kc` |
52|`RCS_T(kc)` | |按住时为右 Control及右 Shift，点击时为 `kc` |
53|`LCAG_T(kc)`| |按住时为左Control，Alt及GUI，点击时为 `kc` |
54|`RCAG_T(kc)`| |按住时为右 Control，Alt及GUI，点击时为 `kc` |
55|`C_S_T(kc)` | |按住时为左Control及Shift，点击时为 `kc` |
56|`MEH_T(kc)` | |按住时为左Control，Shift及Alt，点击时为 `kc` |
57|`HYPR_T(kc)`|`ALL_T(kc)` |按住时为左Control，Shift，Alt及GUI，点击时为 `kc` - 更多[参见这里](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
58
59## 注意
60
61目前 `MT()` 的 `kc`参数限制在[基础键码集](zh-cn/keycodes_basic.md)中，因此不能使用 `LCTL()`，`KC_TILD` 及其它大于 `0xFF` 的键码。原因是，QMK使用16位的键码，其中3位是功能标记，1位标记左右修饰键，4位存储修饰键码，仅剩8位存储键码。当一次Mod-Tap触发时，只要有一个右修饰键被激发，其它的修饰键也都被视为右修饰键，因此无法混搭形如左Control+右Shift的形式，会被视为右Control+右Shift
62
63若展开讲就比较复杂了。迁移到32位的键码可以很大程度解决这个问题，但同时会招致配列矩阵大小翻倍，也可能会有其它未知问题。若是想用修饰键配合按键，可以考虑使用[Tap Dance/多击键](zh-cn/feature_tap_dance.md#example-5-using-tap-dance-for-advanced-mod-tap-and-layer-tap-keys)
64
65在使用Windows远程桌面时你可能会发现有些问题，这是因为远程桌面对键码响应过快。若要修复，可以打开远程桌面的“配置”，在“本地资源”页中的键盘属性，调整为“本地计算器”，此时功能即可恢复正常。另一个办法是加大[`TAP_CODE_DELAY`](zh-cn/config_options.md#behaviors-that-can-be-configured)。
66
67## 截获Mod-Taps
68
69### 改变点击功能
70
71若要在Mod-Tap中突破基础键码的限制，可以在 `process_record_user` 中实现。如，上档键码 `KC_DQUO` 无法与 `MT()` 共用，因为它实际上是 `LSFT(KC_QUOT)` 的别名，`KC_DQUO` 上的修饰键码会被 `MT()` 覆盖。但可以使用如下代码截获点击，手动发送 `KC_DQUO`：
72
73```c
74bool process_record_user(uint16_t keycode, keyrecord_t *record) {
75 switch (keycode) {
76 case LCTL_T(KC_DQUO):
77 if (record->tap.count && record->event.pressed) {
78 tap_code16(KC_DQUO); // 点击时发送 KC_DQUO
79 return false; // 通过返回false阻止对该键的其它处理
80 }
81 break;
82 }
83 return true;
84}
85```
86
87### 改变按住功能
88
89类似地，同样可以使用这段自定义代码改变按住功能。下面的例子会在 `LT(0, kc)` （layer-tap键无实际意义，因为layer 0默认被激活）按住时对X，C和V键附加剪切，复制和粘贴功能：
90
91```c
92bool process_record_user(uint16_t keycode, keyrecord_t *record) {
93 switch (keycode) {
94 case LT(0,KC_X):
95 if (record->tap.count && record->event.pressed) {
96 return true; // 返回true来发送常规键码
97 } else if (record->event.pressed) {
98 tap_code16(C(KC_X)); // 截获按住功能来发送Ctrl-X
99 }
100 return false;
101 case LT(0,KC_C):
102 if (record->tap.count && record->event.pressed) {
103 return true; // 返回true来发送常规键码
104 } else if (record->event.pressed) {
105 tap_code16(C(KC_C)); // 截获按住功能来发送Ctrl-C
106 }
107 return false;
108 case LT(0,KC_V):
109 if (record->tap.count && record->event.pressed) {
110 return true; // 返回true来发送常规键码
111 } else if (record->event.pressed) {
112 tap_code16(C(KC_V)); // 截获按住功能来发送Ctrl-V
113 }
114 return false;
115 }
116 return true;
117}
118```
119
120在数字及字母键上使用Mod-Tap时推荐启用 `IGNORE_MOD_TAP_INTERRUPT`，以避免在快速按下下一个键时保持功能优先级。参见[忽略Mod Tap中断](zh-cn/tap_hold.md#ignore-mod-tap-interrupt)。
121
122### 同时改变点击和按住功能
123
124最后一个例子通过 `LT(0,KC_NO)` 实现了点击复制，按住粘贴的功能：
125
126```c
127bool process_record_user(uint16_t keycode, keyrecord_t *record) {
128 switch (keycode) {
129 case LT(0,KC_NO):
130 if (record->tap.count && record->event.pressed) {
131 tap_code16(C(KC_C)); // 截获点击来发送Ctrl-C
132 } else if (record->event.pressed) {
133 tap_code16(C(KC_V)); // 截获按住功能来发送Ctrl-V
134 }
135 return false;
136 }
137 return true;
138}
139```
140
141## 其它信息
142
143在[点按配置](zh-cn/tap_hold.md)中描述了影响Mod-Tap行为的标记。
diff --git a/docs/zh-cn/newbs.md b/docs/zh-cn/newbs.md
index eca8c14e5..3be462621 100644
--- a/docs/zh-cn/newbs.md
+++ b/docs/zh-cn/newbs.md
@@ -1,23 +1,29 @@
1# QMK菜教程 1# QMK入教程
2 2
3QMK是为你机械硬盘设计的的一个强大的开源固件。使用QMK可以很简单的让你的定制键盘变得强大。看完这篇文章，无论你是菜鸟还是大佬，都可以顺利的使用QMK来定制键盘。 3<!---
4 original document: 0.15.12:docs/newbs.md
5 git diff 0.15.12 HEAD -- docs/newbs.md | cat
6-->
4 7
5你是否为不知道你的键盘能不能运行QMK而苦恼? 如果你的机械键盘是你自己做的，那么这把键盘一般可以运行QMK。我们提供了[一大堆自制键盘](https://qmk.fm/keyboards/), 所以即便你的键盘不能运行QMK你也很容易能找到满足你需求的键盘。 8就像计算机一样，每把键盘里也有一个处理器，它的职责是在你点击键盘时，检测到这个动作并反馈给计算机。QMK固件即是为了这个目的而设计的一种"软件"，负责检测点击，反馈给电脑。当你构建出一个自定义键映射时，就是在创建一个新的键盘"软件"。
6 9
7## 概览 10QMK的愿景是提供强有力的功能，让不可能的事情变得可能，简单的事情依旧简单。即便是不会编程也可以创建强大的键映射方案。
8 11
9这个教程有7个主要部分： 12想知道你的键盘是否能运行QMK？如果这个键盘是你自己组建的，那么很可能是可以的。我们[已经支持很多键盘](https://qmk.fm/keyboards/)，所以即便你的键盘不能运行QMK，你也很容易能买到满足要求的键盘。
10 13
11* [新手上路](newbs_getting_started.md) 14?> **这份指南适合于我吗？**<br>
12* [用命令行构建你的第一个固件](newbs_building_firmware.md) 15编程对你是个困难的话，可以看看我们的[在线GUI页面](zh-cn/newbs_building_firmware_configurator.md)。</div>
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 16
19这份教程旨在帮助没有固件构建经验的人，也是根据该目的做出选择和建议。这些程序有很多替代方法，大部分替代我们都支持。如果你对完成一个任务有疑问，可以[向我们寻求帮助](getting_started_getting_help.md). 17## 总览
20 18
21## 其他资源 19这份指南适用于想通过源代码编译出键盘固件的需求。对于程序员，全过程都会感觉很熟悉。教程主要分3部分：
22 20
23* [Thomas Baart的 QMK基础博客](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 这是一个用户创建的博客，涵盖了为新手准备的使用QMK的基础知识。 211. [环境配置](zh-cn/newbs_getting_started.md)
222. [构建第一个固件](zh-cn/newbs_building_firmware.md)
233. [刷写固件](zh-cn/newbs_flashing.md)
24
25该指南的目的是帮助那些从未编译过软件的人，很多取舍及建议都是基于这个考量。完成一个目标可能有多种方案，我们尽量都去支持，如果你搞不明白你的目标如何实现，可以[向我们寻求帮助](zh-cn/support.md)。
26
27## 更多资料
28
29这份指南之外，也有一些其它能帮助你学习QMK的资料。我们归纳整理在[大纲](zh-cn/syllabus.md)页面和[学习资料](zh-cn/newbs_learn_more_resources.md)页面
diff --git a/docs/zh-cn/newbs_best_practices.md b/docs/zh-cn/newbs_best_practices.md
deleted file mode 100644
index fa58dc75e..000000000
--- a/docs/zh-cn/newbs_best_practices.md
+++ /dev/null
@@ -1,163 +0,0 @@
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 support@webhost.us.</p>
143=======
144<p>Need help? Email support@webhost.us.</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 support@webhost.us.</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
index fc43583c2..681c7ba8f 100644
--- a/docs/zh-cn/newbs_building_firmware.md
+++ b/docs/zh-cn/newbs_building_firmware.md
@@ -1,81 +1,68 @@
1# 构建第一个固件 1# 构建第一个固件
2 2
3现在您已经建立了构建环境，就可以开始构建自定义固件了。对于本指南的这一部分，我们将在3个程序之间切换——文件管理器、文本编辑器和终端窗口。请保持所有3个程序打开，直到您完成并对键盘固件满意。 3<!---
4 original document: 0.15.12:docs/newbs_building_firmware.md
5 git diff 0.15.12 HEAD -- docs/newbs_building_firmware.md | cat
6-->
4 7
5如果您在按照指南第一部分的操作之后关闭并重新打开了终端窗口，请不要忘记输入“cd qmk_firmware”，来使您的终端位于正确的目录。 8现在您已经准备好了构建环境，就可以开始构建自定义固件了。在这节指南中，我们将在3个程序中开展工作——文件管理器、文本编辑器和终端。在做出心满意足的固件前，请不要关闭它们。
9## 新建键映射
6 10
7## 导航到您的keymaps文件夹 11也许你会考虑从默认键映射复制一份来开始，如果你遵循编译环境配置指南到了最后，那么使用QMK命令行可以简单地做到：
8 12
9首先导航到键盘的 `keymaps` 文件夹. 13 qmk new-keymap
10 14
11?> 如果您MacOS或Windows，可以使用以下命令轻打keymaps文件夹。 15如果的境有那样配置，者你有多个键盘要做，可以键盘
12 16
13?> macOS: 17 qmk new-keymap -kb <keyboard_name>
14 18
15 open keyboards/<keyboard_folder>/keymaps 19检查命令行输出，应该类似于：
16 20
17?> Windows: 21 Ψ <github_username> keymap directory created in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>
18 22
19 start .\\keyboards\\<keyboard_folder>\\keymaps 23上面就是创建出的新 `keymap.c` 文件的路径。
20 24
21## `default` 布局副本 25## 使用趁手的编辑打 `keymap.c`
22 26
23打开`keymaps`文件夹后，您将需要创建`default`文件夹的副本。我们强烈建议您将文件夹命名为与GitHub用户名相同的名称，但您也可以使用任何您想使用的名称，只要它只包含小写字母、数字和下划线字符。 27在编辑器中打开 `keymap.c`，可以看到控制键盘所有功能的关键结构。`keymap.c` 文件头部的一些define和enum定义能让代码容易阅读一些，继续往下会找到这么一行：
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 28
43 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { 29 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
44 30
45从这一行开始便是层列表。这行下面你会看到包括 `LAYOUT` 或 `KEYMAP`这两个词的几行, 从这些行开始就是层。在这一行下面是组成该特定层的键的列表。 31这行是所有层定义的起点，往下能看到有 `LAYOUT` 的行，都是一个层定义的起始，其下方为该层的组成定义。
46 32
47!> 编辑您的keymap文件时，注意不要添加或删除任何逗号。如果这样做，您将阻止您的固件编译，并且您可能不容易找出多余的或缺少的逗号在哪里。 33!> 编辑时请非常留意不要错误增加/删除了逗号分隔符，否则很可能无法编译固件，且很难排查是哪里的逗号不对。
48 34
49## 据您喜好义 35## 个人喜好计级
50 36
51如何完成这一步骤完全取决于您。改变一直困扰着你的问题，或者完全重做所有的事情。如果您不需要全部图层，可以删除图层，或者将图层总数增加到32个。查看以下文档，了解可以在此处定义的内容: 37这一步的目标完全取决于你，既可以去修复一个你不爽的问题，也可以完全重写一个新的。你可以删除不需要的层，或是增加层到32个的上限，QMK功能丰富，可以在左边的导航栏中寻找“使用QMK”一节，浏览完整的功能信息，也可以看看这些比较简单的：
52 38
53* [键码](keycodes.md) 39* [基础键码](zh-cn/keycodes_basic.md)
54* [特性](features.md) 40* [量子键码](zh-cn/quantum_keycodes.md)
55* [问题与解答](faq.md) 41* [Grave/Escape](zh-cn/feature_grave_esc.md)
42* [鼠标键](zh-cn/feature_mouse_keys.md)
56 43
57?> 当你明白布局是怎么工作时，您也要让每次改变尽可能小。一次改变很大在调试时找出问题会十分困难。 44?> 你大概理解了键映射如何工作的话，留心尽量少去做改动，改动越多出了问题越难排查。
58 45
59## 构建你的固件 46## 构建固件 :id=build-your-firmware
60 47
61成后，您就构件了。为此，请返回终端窗口并build命令: 48对键映完修改后，编译固件了。回到终端中用编命令：
62 49
63 make <my_keyboard>:<my_keymap> 50 qmk compile
64 51
65例如，如果您的keymap名为“xyverz”，并且您正在为rev5 planck构建一个keymap，那么您将使用此命令： 52如果没有完整地配置环境，或你有多个目标键盘，可以指定键盘及键映射：
66 53
67 make planck/rev5:xyverz 54 qmk compile -kb <keyboard> -km <keymap>
68 55
69在编译过程中，你将看到屏幕上有很多输出，通知您正在编译哪些文件他应该以与下文类似的输出结束: 56编译完成后，会输出详尽的编译产出文件信息，其末尾应该看起来像这样：
70 57
71``` 58```
72Linking: .build/planck_rev5_xyverz.elf [OK] 59Linking: .build/planck_rev5_default.elf [OK]
73Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] 60Creating load file for flashing: .build/planck_rev5_default.hex [OK]
74Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK] 61Copying planck_rev5_default.hex to qmk_firmware folder [OK]
75Checking file size of planck_rev5_xyverz.hex [OK] 62Checking file size of planck_rev5_default.hex [OK]
76 * File size is fine - 18392/28672 63 * The firmware size is fine - 27312/28672 (95%, 1360 bytes free)
77``` 64```
78 65
79## 刷新你的固件 66## 刷件
80 67
81步 [Flashing Firmware](newbs_flashing.md) 来。 68参阅[写固](zh-cn/newbs_flashing.md)了如何将固件写入键控。
diff --git a/docs/zh-cn/newbs_building_firmware_configurator.md b/docs/zh-cn/newbs_building_firmware_configurator.md
new file mode 100644
index 000000000..c4cd11431
--- /dev/null
+++ b/docs/zh-cn/newbs_building_firmware_configurator.md
@@ -0,0 +1,18 @@
1# QMK配置器
2
3<!---
4 original document: 0.15.12:docs/newbs_building_firmware_configurator.md
5 git diff 0.15.12 HEAD -- docs/newbs_building_firmware_configurator.md | cat
6-->
7
8[![QMK配置器截图](https://i.imgur.com/anw9cOL.png)](https://config.qmk.fm/)
9
10[QMK配置器](https://config.qmk.fm)是一个可用于生成`.hex`和`.bin`格式的QMK固件文件的在线交互页面。
11
12这里有[视频教程](https://www.youtube.com/watch?v=-imgglzDMdY). 很多人给我们反馈该视频包含了足够多的知识可以用来开始编写自己的键盘程序。
13
14QMK配置器在Chrome及Firefox中工作良好。
15
16!> **来自于第三方工具的文件数据无法保证与QMK兼容，如Keyboard Layout Editor(KLE)或kbfirmware，请不要加载或导入这些文件。QMK配置器是一个独立的工具。**
17
18更多信息请参见[QMK配置器: 入门](zh-cn/configurator_step_by_step.md)。
diff --git a/docs/zh-cn/newbs_flashing.md b/docs/zh-cn/newbs_flashing.md
index 05a9eb55e..9ffb79279 100644
--- a/docs/zh-cn/newbs_flashing.md
+++ b/docs/zh-cn/newbs_flashing.md
@@ -1,307 +1,124 @@
1# 刷新你的键盘 1# 刷写键盘固件
2 2
3现在您已经构建了一个自定义固件文件，那么您就需要刷新键盘了。 3<!---
4 original document: 0.15.12:docs/newbs_flashing.md
5 git diff 0.15.12 HEAD -- docs/newbs_flashing.md | cat
6-->
4 7
5## QMK箱刷键盘 8自义的固件文件构建出，以写键盘中了。
6 9
7键盘的最简单方是使用[QMK 工具箱](https://github.com/qmk/qmk_toolbox/releases). 10## 键盘调DFU（Bootloader）模式
8 11
9但是，QMK工具箱目前仅适用于Windows和MacOS。如果您使用的是Linux（或者只是希望从命令行刷新固件），则必须使用 [方法概述](newbs_flashing.md#flash-your-keyboard-from-the-command-line). 12在你将自定义固件刷写到键盘前，键盘必须处于特有的刷写模式下。此时，键盘会处于不会响应点击等常规操作的状态，并且一定留意不要打断刷写工作，刷写固件过程中不可以把键盘拔下来。
10 13
11### 将文件加载到QMK工具箱中 14不同的键盘进入刷写模式的方法都是不同的，如果你的键盘运行的是QMK、TMK或PS2AVRGB(Bootmapper客户端)且没有写明特别的操作说明的话，可以依次尝试以下操作：
12 15
13首先打开QMK工具箱应用程序。您将要在访达或资源管理器中找到固件文件。您的键盘固件可能是两种格式之一`.hex`或`.bin`。qmk会尝试将键盘的相应文件复制到“qmk_firmware”根目录中。 16* 按住两边的Shift键，点击Pause
17* 按住两边的Shift键，点击B
18* 拔出键盘，同时按住“空格”键及B键，再插上键盘，等两秒后松开
19* 拔出键盘，按住键盘左上或左下的按键（一般来讲是Escape或左Control），在插上键盘
20* 按重置按键（Reset），一般在PCB背面
21* 在PCB上寻找导出的 `RESET` 和 `GND` 引脚，在插电的情况下短接一下
14 22
15?> 如果您在Windows或MacOS上，可以使用以下命令轻松地在资源管理器或访达中打开当前固件文件夹。 23如果上面的方法没有用，且键盘主板上的芯片是 `STM32` 系列，情况要复杂一些。通常在[Discord](https://discord.gg/Uq7gcHh)上寻求帮助是最好的办法，并且很可能需要你提供一些键盘主板的照片 —— 所以如果你能提前准备好，我们沟通起来会快得多。
16 24
17?> Windows: 25如果没有遇到什么问题，你会在QMK工具箱的输出信息里找到类似下面的黄色文字的信息：
18 26
19 start . 27```
20 28*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
21?> macOS: 29```
22
23 open .
24
25固件文件始终遵循此命名格式:
26 30
27 <keyboard_name>_<keymap_name>.{bin,hex} 31已进入bootloader状态的设备也可以在设备管理器、系统信息或 `lsusb` 中看到。
28 32
29如，用 `default` `plank/rev5` 用下名字： 33## 使用QMK固
30 34
31 planck_rev5_default.hex 35使用[QMK工具箱](https://github.com/qmk/qmk_toolbox/releases)刷写固件是最简单的方案。
32 36
33找到固件文件后，将其拖到QMK工具箱中的“Local file”框中，或单击“Open”并导航到固件文件的存储位置。 37然而该工具箱仅支持Windows及macOS，如果你在使用Linux环境（或是希望用命令行刷写固件），请参阅[在命令行中刷写固件](#使用命令行刷写固件)一节。
34 38
35### 键盘DFUBootloader）模 39### 件QMK具箱
36 40
37要刷新自定义固件，您必须将键盘置于特殊的刷新模式。在此模式下，您将无法键入或使用键盘。在写入固件时，不要拔下键盘插头或以其他方式中断刷新过程，这一点非常重要。 41打开QMK工具箱，在Finder或文件管理器中找到固件文件。键盘固件文件名后缀通常是 `.hex` 或 `.bin`，QMK工具箱会尝试将正确的文件拷贝到qmk根目录 `qmk_firmware` 中。
38 42
39不同的键盘有不同的方式进入这种特殊模式。如果您的键盘当前运行的是QMK或TMK，而您没有得到特定的指示，请按顺序尝试以下操作: 43在Windows或macOS上，使用下面的指令可以快速打开当前目录。
40 44
41* 按住两个shift键并按 `Pause` 45<!-- tabs:start -->
42* 按住两个shift键并按 `B`
43* 拔下键盘插头, 同时按住空格键和 `B` , 插上键盘然后等一会再放开按键
44* 按下PCB底部的 `RESET` 物理键
45* 找到PCB上标记有 `BOOT0` 或 `RESET`的金属点, 在插入PCB的同时短接它们
46 46
47成功后，您将在QMK工具箱中看到类似以下内容的消息: 47#### ** Windows **
48 48
49``` 49```
50*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 50start .
51*** DFU device connected
52``` 51```
53 52
54### 刷新你的键盘 53#### ** macOS **
55
56单击QMK工具箱中的 `Flash` 按钮。您将看到类似以下内容的输出:
57 54
58``` 55```
59*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390 56open .
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``` 57```
78 58
79## 使用命令行刷新键盘 59<!-- tabs:end -->
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 60
87### DFU 61固件文件的文件名格式为：
88 62
89对于DFU引导加载程序，当您准备好编译和刷新固件时，打开终端窗口并运行构建命令: 63```
90 64<keyboard_name>_<keymap_name>.{bin,hex}
91 make <my_keyboard>:<my_keymap>:dfu 65<键盘名>_<键映射名>.{bin,hex}
92 66```
93例如，如果您的布局名为“xyverz”，并且您正在为rev5 planck构建一个布局，那么您可以使用此命令：
94
95 make planck/rev5:xyverz:dfu
96 67
97编译成后，应输下容： 68例， `planck/rev5` 的 `default` 键映对的是：
98 69
99``` 70```
100Linking: .build/planck_rev5_xyverz.elf [OK] 71planck_rev5_default.hex
101Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK] 72```
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 73
107到这候, 脚本将隔5秒找一次DFU。它将下作，直到设备。 74找到，其QMK具箱的"Local file"，或点“Open”位至固件。
108 75
109 dfu-programmer: no device present. 76### 刷写到键盘
110 Error: Bootloader not found. Trying again in 5s.
111 77
112一旦现上显，您将需要重控然后，它应该显示以类似的输出： 78点击QMK箱的`Flash`，将下输出信息：
113 79
114``` 80```
81*** DFU device connected: Atmel Corp. ATmega32U4 (03EB:2FF4:0000)
115*** Attempting to flash, please don't remove device 82*** Attempting to flash, please don't remove device
116>>> dfu-programmer atmega32u4 erase --force 83>>> dfu-programmer.exe atmega32u4 erase --force
117 Erasing flash... Success 84 Erasing flash... Success
118 Checking memory from 0x0 to 0x6FFF... Empty. 85 Checking memory from 0x0 to 0x6FFF... Empty.
119>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex 86>>> dfu-programmer.exe atmega32u4 flash "D:\Git\qmk_firmware\gh60_satan_default.hex"
120 Checking memory from 0x0 to 0x55FF... Empty. 87 Checking memory from 0x0 to 0x3F7F... Empty.
121 0% 100% Programming 0x5600 bytes... 88 0% 100% Programming 0x3F80 bytes...
122 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 89 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
123 0% 100% Reading 0x7000 bytes... 90 0% 100% Reading 0x7000 bytes...
124 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success 91 [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>] Success
125 Validating... Success 92 Validating... Success
126 0x5600 bytes written into 0x7000 bytes memory (76.79%). 93 0x3F80 bytes written into 0x7000 bytes memory (56.70%).
127>>> dfu-programmer atmega32u4 reset 94>>> dfu-programmer.exe atmega32u4 reset
128``` 95
129 96*** DFU device disconnected: Atmel Corp: ATmega32U4 (03EB:2FF4:0000)
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``` 97```
208如果您对此有任何问题，您可能需要这样做：
209
210 sudo make <my_keyboard>:<my_keymap>:avrdude
211
212 98
213此外，如果要刷新多板，请用以下命令： 99## 使用命令行刷写固件
214 100
215 make <keyboard>:<keymap>:avrdude-loop 101现在已经没有以前那样繁琐了，在编译固件后需要刷写时，打开终端输入如下刷写指令：
216 102
217当你完成了刷新后，你需要按下ctrl+c或者其他正确的按键来让你的操作系统终止循环。 103 qmk flash
218 104
105如果未通过命令行工具配置过键盘/键映射名，或有多个目标键盘，可以指定目标键盘和键映射：
219 106
220## HalfKay 107 qmk flash -kb <键盘名> -km <键映射名>
221 108
222对于PJRC设备（Teensy），当您准备好编译和刷新固件时，打开终端窗口并运行构建命令: 109QMK将核查键盘配置，并尝试使用合适的bootloader进行刷写。也就是说，你不用关注应该使用什么bootloader，这些重活儿让qmk指令去承担就好。
223 110
224 make <my_keyboard>:<my_keymap>:teensy 111但是，先决条件是键盘配置中已经设置了bootloader，如果未配置，或你的键盘板子不支持配置的刷写方式，你会看到这些错误信息：
225 112
226比如, 如果你的布局叫做"xyverz"你想创建Ergodox or Ergodox EZ的布局,你要使用以下命令: 113 WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
227 114
228 make erdogox_ez:xyverz:teensy 115此时，只能退回到需要指定bootloader的方法，具体参见[刷写固件](zh-cn/flashing.md)指引。
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 116
253## STM32 (ARM) 117## 上手试试键盘吧！
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 118
303## 试吧! 119恭喜你，你的定固件成功刷写到键盘了，快去试试吧！
304 120
305恭喜您! 您的自定义固件已经刷写到您的键盘 121运气不差的话一切都会是正常工作的，如果不幸遇到了些问题，有一些参考方案可以帮助你排查问题原因。
122键盘测试就简单直接了，依次按一下各按键，检查它是不是发送了正确的输入。可以使用[QMK配置器](https://config.qmk.fm/#/test/)中的测试模式进行测试，即便你的键盘并不运行QMK。
306 123
307试一试，确保一切按你想的方式进行。我们写了[测试和调试](newbs_testing_debugging.md)来完善新手引导。 因此，请前往那里了解如何排除自定义功能的故障。 124还是不行吗？参阅一下FAQ或[通过Discord和我们聊聊](https://discord.gg/Uq7gcHh)吧。
diff --git a/docs/zh-cn/newbs_getting_started.md b/docs/zh-cn/newbs_getting_started.md
index 596ab78f7..7ca9871aa 100644
--- a/docs/zh-cn/newbs_getting_started.md
+++ b/docs/zh-cn/newbs_getting_started.md
@@ -1,93 +1,183 @@
1# 介 1# 置环境
2 2
3你的电脑键盘里面包含一个处理器, 这个处理器和你电脑里面的不太一样。这个处理器负责运行一些特殊的软件，这些软件可以监测按钮按下并将按钮处于按下还是释放状态的数据发送出去。QMK就是这样一种软件，即监测按钮被按下并发送这样的信息到作为主机的计算机上。当你创建了你的布局, 你也就创建了你的键盘运行的的可执行程序。 3<!---
4 original document: 0.15.12:docs/newbs_getting_started.md
5 git diff 0.15.12 HEAD -- docs/newbs_getting_started.md | cat
6-->
4 7
5QMK试图通过使简单的事情变得更简单，使使不可能成为可能来把大量的权力交给你。你不需要懂如何通过程序创建强大的布局——你只需要遵循简单的语法规则。 8构建键映射前，有一些必须安装配置的构建工具，但无论你要编译多少个固件，这一步只需要做一次。
6 9
7# 新手上 10## 1. 必备具
8 11
9在你能创建布局前,你要安装一些软件来建立你的开发环境。无论你想编译多少固件，这个操作都只需要进行一次。 12首先需要确保一些基本的软件配备。
10 13
11如果您更喜欢图形化界面, 请考虑使用在线工具[QMK配置器](https://config.qmk.fm)。 请参考 [使用在线GUI构建您的第一个固件](newbs_building_firmware_configurator.md)。 14* [文本编辑器](zh-cn/newbs_learn_more_resources.md#text-editor-resources)
15 * 你需要至少一个能编辑常规文本的软件。系统自带的编辑器通常不会如实保存（会做一些额外的处理，如回车），所以选择编辑器时需要留意。
16* [QMK工具箱(可选)](https://github.com/qmk/qmk_toolbox)
17 * 在Windows及macOS上可用的图形程序，用于编辑及调试你的键盘
12 18
19?> 如果你没有Linux/Unix命令行使用经验，有些基本概念需要先学习一下。[这些资料](zh-cn/newbs_learn_more_resources.md#command-line-resources)是个使用QMK很好的参考。
13 20
14## 下载软 21## 2. 准备构环境 :id=set-up-your-environment
15 22
16### 23已尽力让QMK易于配置了你只备好Linux或Unix环境，剩的交给QMK来安装。
17 24
18你需要一个可以编辑 **纯文本** 文件的程序。在Windows上你可以用Notepad, 在Linux上使用gedit，这两个都是简单又实用的文本编辑工具。 在macOS上, 请小心使用 “文本编辑” 这个默认软件: 如果你不明确的选择_格式_菜单中的 _制作纯文本_ 的话文本将不会被保存为纯文本。 25<!-- tabs:start -->
19 26
20你也可以下载并安装一个专用编辑器 [Sublime Text](https://www.sublimetext.com/) 或 [VS Code](https://code.visualstudio.com/)。 这大概是跨平台的最好方法了, 这些编辑器是专门为了编辑代码设计的。 27### ** Windows **
21 28
22?>搞不清用哪种编辑器? Laurence Bradford 写了篇关于编辑器选择的文章 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/)。 29QMK有维护一套基于MSYS2的软件包，所有命令行程序和依赖都是齐备的。通过 `QMK MSYS` 快捷命令可以快速启动开发环境。
23 30
24### QMK 工具箱 31#### 依赖项
25 32
26QMK 工具箱 是一种可选的Windows和macOS下的图形化工具，它可以对你的定制键盘进行编程和调试。你可能会发现它就是你能简单的刷新你的键盘固件并查看调试信息的稀世珍宝。 33需安装[QMK MSYS](https://msys.qmk.fm/)，最新版在[这里](https://github.com/qmk/qmk_distro_msys/releases/latest)。
27 34
28[下载最新](https://github.com/qmk/qmk_toolbox/releases/latest) 35此，如想安装MSYS2环境，下面给了体骤。
29 36
30* Windows用户: `qmk_toolbox.exe` (绿色版) 或 `qmk_toolbox_install.exe` (安装版) 37<details>
31* macOS用户: `QMK.Toolbox.app.zip` (绿色版) or `QMK.Toolbox.pkg` (安装版) 38 <summary>自行安装</summary>
32 39
33## 建境 40?> 决定 `QMK MSYS`，跳过此节.
34 41
35我们为了使QMK环境变得更容易建立已竭尽所能。你只需要准备Linux 或 Unix 环境, 然后让QMK安装剩余部分。 42#### 依赖项
36 43
37?> 如果你从未使用过Linux/Unix的命令行,有一些你需要学习的基础概念和命令，以下资料将教会您使用QMK环境的必要能力:<br> 44遵循 https://www.msys2.org 上的指引，安装MSYS2、Git和Python。
38[必会Linux命令](https://www.guru99.com/must-know-linux-commands.html)<br>
39[一些基本的Unix命令](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
40 45
41### Windows 46在MSYS2安装完毕后，关闭所有的MSYS终端，启动新的MinGW 64-bit终端。
42 47
43你需要安装MSYS2和Git. 48!> **注意:** MinGW 64-bit 终端*不同于*安装包最后打开的MSYS终端，窗口标题应当是紫色的"MINGW64"而不是"MSYS"。具体的差异可以[参考这里](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems)。
44 49
45* 按照以下安装说明进行操作[MSYS2 主页](https://www.msys2.org)。 50执行如下命令：
46* 关闭所有打开的MSYS2终端并打开新的MSYS2 MinGW 64-bit终端。
47* 使用以下命令安装Git: `pacman -S git`。
48 51
49### macOS 52 pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip
50 53
51你需要安装Homebrew。按照以下说明进行操作 [Homebrew 主页](https://brew.sh)。 54#### 安装
52 55
53Homebrew装完成后, 继续 _同步QMK程_. 这一步将通运一个脚本装其他包。 56安装QMK行程:
54 57
55### Linux 58 python3 -m pip install qmk
56 59
57你将需要安装Git.你很有可能已经安装,但若你尚未安装,可以使用以下命令进行安装: 60</details>
58 61
59* Debian / Ubuntu / Devuan: `apt-get install git` 62### ** macOS **
60* Fedora / Red Hat / CentOS: `yum install git`
61* Arch: `pacman -S git`
62 63
63?> 无论你使用哪种平台，Docker都可以是你的选择[点这里进一步了解](getting_started_build_tools.md#docker) 64QMK维护了一套Homebrew tap和formula以用于自动安装命令行程序及依赖项。
64 65
65## 同步QMK工程 66#### 依赖项
66 67
67当你建立Linux/Unix环境后,你就已经可以下载QMK了.下载时我们可以用Git来 "clone" QMK仓库. 打开一个终端或MSYS2 MinGW 窗口，在阅读剩余的指南时请保持窗口打开。在窗口里面运行以下两句命令: 68须先安装Homebrew，可以参考 https://brew.sh
68 69
69```shell 70#### 安装
70git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git 71
71cd qmk_firmware 72安装QMK命令行程序：
72``` 73
74 brew install qmk/qmk/qmk
75
76### ** Linux/WSL **
77
78?> **WSL用户注意**: 默认情况下，QMK仓库会被clone到home目录下，如果想指定其它目录，务必留意要放在WSL文件系统中（即，非 `/mnt` 目录下），否则文件读写会[非常慢](https://github.com/microsoft/WSL/issues/4197).
79
80#### 依赖项
81
82须安装Git及Python，通常你肯定已经有了，如果确实没有，请使用下面的方法尝试安装：
83
84* Debian / Ubuntu / Devuan: `sudo apt install -y git python3-pip`
85* Fedora / Red Hat / CentOS: `sudo yum -y install git python3-pip`
86* Arch / Manjaro: `sudo pacman --needed --noconfirm -S git python-pip libffi`
87* Void: `sudo xbps-install -y git python3-pip`
88* Solus: `sudo eopkg -y install git python3`
89* Sabayon: `sudo equo install dev-vcs/git dev-python/pip`
90* Gentoo: `sudo emerge dev-vcs/git dev-python/pip`
91
92#### 安装
93
94安装QMK命令行程序：
95
96 python3 -m pip install --user qmk
97
98#### 社区提供的包
99
100有一些社区成员提供的包，可能版本会有落后或是功能不全的问题，如果你遇到了什么问题，请联系维护它的社区成员。
101
102Arch系环境下可以使用官方源安装命令行程序（在写这份文档时，有些依赖项被标记为可选的，其实不是）：
103
104 sudo pacman -S qmk
105
106也可以尝试AUR的 `qmk-git`：
107
108 yay -S qmk-git
109
110### ** FreeBSD **
111
112#### 安装
113
114使用FreeBSD包安装QMK命令行程序：
115
116 pkg install -g "py*-qmk"
117
118请遵循安装后输出的指引操作进行配置（使用 `pkg info -Dg "py*-qmk"` 可以显示这份指引）。
119
120<!-- tabs:end -->
121
122## 3. 执行QMK配置 :id=set-up-qmk
123*译注：由于setup过程中需要从github clone依赖项，请先确保科学上网*
124
125<!-- tabs:start -->
73 126
74?> 如果您已经知道[如何使用GitHub](getting_started_github.md), 我们推荐您创建您自己的分支并克隆。 如果您不知道这是什么, 您完全可以忽略这句无关紧要的话。 127### ** Windows **
75 128
76QMK附一个脚本，可帮助设置余的所需内容.您可以通输入此命令来运它: 129安装QMK，行：
77 130
78 util/qmk_install.sh 131 qmk setup
79 132
80## 试你的环 133通常有的询问 `y` 行了。
81 134
82现在你的QMK环境已经建立完毕, 你可以为你的键盘创建固件了。开始试着创建键盘的默认固件吧。 你需要使用以下格式的命令创建固件: 135### ** macOS **
83 136
84 make <keyboard>:default 137安装QMK后，执行：
85 138
86比如, 制作一个Clueboard 66%的固件，需要用: 139 qmk setup
87 140
88 make clueboard/66/rev3:default 141通常所有的询问回复 `y` 就行了。
89 142
90当完成后你要看到一些回显，尾部如下: 143### ** Linux/WSL **
144
145安装QMK后，执行：
146
147 qmk setup
148
149通常所有的询问回复 `y` 就行了。
150
151?>**Debian及Ubuntu系环境须留意**:
152也许你会遇到 `bash: qmk: command not found` 错误，主要是因为Debian上的Bash 4.4版本引入的一个[bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155)，`$HOME/.local/bin` 被从PATH环境变量中删除了，后续版本中这个问题已被修复。
153然而Ubuntu很挫地再次引入了这个bug[且没有修复](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562)。
154不过修复也很容易，在当前账户中执行：`echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc`
155
156### ** FreeBSD **
157
158安装QMK后，执行：
159
160 qmk setup
161
162通常所有的询问回复 `y` 就行了。
163
164<!-- tabs:end -->
165
166?> QMK的home目录可以在安装时通过 `qmk setup -H <path>` 来指定，安装后也可以通过[命令行程序来配置](zh-cn/cli_configuration.md?id=single-key-example)`user.qmk_home`变量，可以通过 `qmk setup --help` 查看所有可用配置。
167
168?> 若你熟悉GitHub，[推荐阅读这份指引](zh-cn/getting_started_github.md)通过 `qmk setup <github_username>/qmk_firmware` 来clone你自己的fork。如果你看不懂这一段啥意思，忽略就是了。
169
170## 4. 测试你的构建环境
171
172QMK构建环境搭建完成，可以尝试构建一个键盘固件。使用以下指令格式，先试试编译默认提供的键映射：
173
174 qmk compile -kb <keyboard> -km default
175
176例如，要构建一个Clueboard 66%，就这样执行：
177
178 qmk compile -kb clueboard/66/rev3 -km default
179
180你应当能看到像这样的输出信息：
91 181
92``` 182```
93Linking: .build/clueboard_66_rev3_default.elf [OK] 183Linking: .build/clueboard_66_rev3_default.elf [OK]
@@ -97,6 +187,22 @@ Checking file size of clueboard_66_rev3_default.hex
97 * The firmware size is fine - 26356/28672 (2316 bytes free) 187 * The firmware size is fine - 26356/28672 (2316 bytes free)
98``` 188```
99 189
100# 创建你的布局 190## 5. 配置你的构建环境 (可选的)
191
192通过对默认配置的简单调整，QMK用起来会更有趣一些，我们来试试！
193
194大部分QMK新手手头只有一把键盘，可以通过 `qmk config` 命令将它设置为默认键盘，例如你想将 `clueboard/66/rev4` 设置为默认，可以这样：
195
196 qmk config user.keyboard=clueboard/66/rev4
197
198也可以调整默认的键映射名称。社区上大家常用自己的GitHub用户名，这也是我们推荐的做法。
199
200 qmk config user.keymap=<github_username>
201
202完成后，这些配置就不用管了，编译键盘固件就可以直接这样执行：
203
204 qmk compile
205
206# 制作你自己的键映射
101 207
102现在你可以创建属于你自己的布局了! 请移步 [构建你的第一个固件](newbs_building_firmware.md)来继续。 208万事俱备啦！请继续阅读[构建第一个固件](zh-cn/newbs_building_firmware.md).
diff --git a/docs/zh-cn/newbs_learn_more_resources.md b/docs/zh-cn/newbs_learn_more_resources.md
index ccb4fa326..20fed1f35 100644
--- a/docs/zh-cn/newbs_learn_more_resources.md
+++ b/docs/zh-cn/newbs_learn_more_resources.md
@@ -1,15 +1,35 @@
1# 学习资源 1# 学习资源
2 2
3这些资源旨在让QMK社区的新成员更了解新成员文档中提供的信息。 3<!---
4 original document: 0.15.12:docs/newbs_learn_more_resources.md
5 git diff 0.15.12 HEAD -- docs/newbs_learn_more_resources.md | cat
6-->
4 7
5Git 资源: 8些源旨在让QMK社区的新成员更了解新手教程中的基础知识。
6 9
7* [很好的通用教程](https://www.codecademy.com/learn/learn-git) 10*译注：以下资料超出了QMK核心概念范畴，恕不另行翻译*
8* [从例子中学习Git游戏](https://learngitbranching.js.org/)
9* [了解有关GitHub的更多信息的Git资源](getting_started_github.md)
10* [专门针对QMK的Git资源](contributing.md)
11 11
12### QMK参考资料
12 13
13命令行资源: 14* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 一个站在新人视角，探讨如何使用QMK固件的个人博客。
14 15
15* [超棒的命令行通用教程](https://www.codecademy.com/learn/learn-the-command-line) 16### 命令行操作参考资料 :id=command-line-resources
17
18* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line)
19* [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
20* [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
21
22### 文本编辑器相关参考资料 :id=text-editor-resources
23
24对文本编辑器有选择困难？
25* [a great introduction to the subject](https://learntocodewith.me/programming/basics/text-editors/)
26
27更适用于编程的文本编辑器：
28* [Sublime Text](https://www.sublimetext.com/)
29* [VS Code](https://code.visualstudio.com/)
30
31### Git参考资料
32
33* [Great General Tutorial](https://www.codecademy.com/learn/learn-git)
34* [Flight Rules For Git](https://github.com/k88hudson/git-flight-rules)
35* [Git Game To Learn From Examples](https://learngitbranching.js.org/)
diff --git a/docs/zh-cn/newbs_testing_debugging.md b/docs/zh-cn/newbs_testing_debugging.md
index d88d9b6f2..0016d3b81 100644
--- a/docs/zh-cn/newbs_testing_debugging.md
+++ b/docs/zh-cn/newbs_testing_debugging.md
@@ -1,46 +1,14 @@
1# 测试和调试 1# 测试和调试
2 2
3使用自定义固件刷新键盘后，您就可以测试它了。如果您幸运，一切都会完美运行，但如果没有，这份文件将帮助您找出问题所在。 3<!---
4 4 original document: 0.15.12:docs/newbs_testing_debugging.md
5 git diff 0.15.12 HEAD -- docs/newbs_testing_debugging.md | cat
6-->
5## 测试 7## 测试
6 8
7测试键盘通常非常简单。按下每一个键并确保它发送的是您期望的键。甚至有一些程序可以帮助您确保没有任何键失效。 9[已移到这里](zh-cn/faq_misc.md#testing)
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 10
37```c 11## 调试 :id=debugging
38#include "print.h"
39```
40 12
41之，您可以使一些不的打功: 13[里](zh-cn/faq_debug.md#debugging)
42 14
43* `print("string")`: 打印简单字符串.
44* `uprintf("%s string", var)`: 打印格式化字符串
45* `dprint("string")`: 仅在调试模式使能时打印简单字符串
46* `dprintf("%s string", var)`: 仅在调试模式使能时打印格式化字符串
diff --git a/docs/zh-cn/reference_configurator_support.md b/docs/zh-cn/reference_configurator_support.md
new file mode 100644
index 000000000..aa174ceed
--- /dev/null
+++ b/docs/zh-cn/reference_configurator_support.md
@@ -0,0 +1,200 @@
1# 在QMK配置器中支持您的键盘
2
3<!---
4 original document: 0.15.12:docs/reference_configurator_support.md
5 git diff 0.15.12 HEAD -- docs/reference_configurator_support.md | cat
6-->
7
8本章节详述了如何在[QMK配置器](https://config.qmk.fm/)中对键盘进行支持。
9
10
11## 配置器如何理解键盘
12
13若要了解配置器如何理解键盘，须先理解配列的宏定义。这里有一份练习，假设这里有一个17键的小键盘PCB方案，就叫做 `numpad`。
14
15```
16|---------------|
17|NLk| / | * | - |
18|---+---+---+---|
19|7 |8 |9 | + |
20|---+---+---| |
21|4 |5 |6 | |
22|---+---+---+---|
23|1 |2 |3 |Ent|
24|-------+---| |
25|0 | . | |
26|---------------|
27```
28
29?> 配列宏定义的更多资料，参见[理解QMK：矩阵扫描](zh-cn/understanding_qmk.md?id=matrix-scanning)及[理解QMK：矩阵到物理配列的映射](zh-cn/understanding_qmk.md?id=matrix-to-physical-layout-map)。
30
31配置器的API会从 `qmk_firmware/keyboards/<keyboard>/<keyboard>.h` 中读取键盘定义的 `.h` 文件。在上面的小键盘示例中，对应文件应为 `qmk_firmware/keyboards/numpad/numpad.h`：
32
33```c
34#pragma once
35
36#define LAYOUT( \
37 k00, k01, k02, k03, \
38 k10, k11, k12, k13, \
39 k20, k21, k22, \
40 k30, k31, k32, k33, \
41 k40, k42 \
42 ) { \
43 { k00, k01, k02, k03 }, \
44 { k10, k11, k12, k13 }, \
45 { k20, k21, k22, KC_NO }, \
46 { k30, k31, k32, k33 }, \
47 { k40, KC_NO, k42, KC_NO } \
48}
49```
50
51QMK使用 `KC_NO` 去标记开关矩阵中的空位。有时也会因方便或调试用途而使用 `XXX`，`___` 或 `____` 来替代。通产定义写在 `.h` 文件起始位置附近：
52
53```c
54#pragma once
55
56#define XXX KC_NO
57
58#define LAYOUT( \
59 k00, k01, k02, k03, \
60 k10, k11, k12, k13, \
61 k20, k21, k22, \
62 k30, k31, k32, k33, \
63 k40, k42 \
64 ) { \
65 { k00, k01, k02, k03 }, \
66 { k10, k11, k12, k13 }, \
67 { k20, k21, k22, XXX }, \
68 { k30, k31, k32, k33 }, \
69 { k40, XXX, k42, XXX } \
70}
71```
72
73!> 注意这里的使用模式与键映射中的宏完全不同，后者几乎都在用 `XXXXXXX`（7个大写X）替代 `KC_NO`，用 `_______`（7个下划线）替代 `KC_TRNS`。
74
75!> 为避免混淆，推荐使用 `KC_NO`。
76
77配列宏定义描述该键盘有17个按键，分布在五行四列。我们将这些开关命名为 `k<行号><列号>`，从0计起。命名成什么不太重要，但须确保负责从键映射中接收键码的上半段，与描述矩阵中按键位置的下半段定义匹配一致。
78
79为了能够重现键盘的物理组成样式，须构建并提供一份用于描述按键物理位置和尺寸与开关矩阵绑定关系的JSON文件，以告知配置器程序这些信息。
80
81## 构建JSON文件
82
83构建该JSON描述文件最简便的办法是使用[Keyboard Layout Editor](https://www.keyboard-layout-editor.com/) ("KLE"), 从中获取的原始数据（Raw Data）可以经QMK工具转换为配置器可用的JSON格式数据。由于KLE默认打开显示的是一个小键盘配列，请移除新手引导部分，从剩余部分开始使用。
84
85在配列编辑完毕后，从KLE的原始数据（Raw Data tab）页中拷贝类似如下的内容：
86
87```
88["Num Lock","/","*","-"],
89["7\nHome","8\n↑","9\nPgUp",{h:2},"+"],
90["4\n←","5","6\n→"],
91["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"],
92[{w:2},"0\nIns",".\nDel"]
93```
94
95要将这份数据转换为我们可用的JSON格式，请跳转至[QMK KLE-JSON转换工具](https://qmk.fm/converter/)页面并粘贴到输入框，点击转换按钮。稍后输出框中即可看到所需的JSON数据。将输出数据拷贝到文本文档中，并命名为 `info.json`，保存到 `numpad.h` 所在目录。
96
97可以通过 `keyboard_name` 元素来指定键盘名称。这里为了演示，会将每个按键独立分行，以更方便于阅读，这不影响配置器的功能。
98
99```json
100{
101 "keyboard_name": "Numpad",
102 "url": "",
103 "maintainer": "qmk",
104 "tags": {
105 "form_factor": "numpad"
106 },
107 "layouts": {
108 "LAYOUT": {
109 "layout": [
110 {"label":"Num Lock", "x":0, "y":0},
111 {"label":"/", "x":1, "y":0},
112 {"label":"*", "x":2, "y":0},
113 {"label":"-", "x":3, "y":0},
114 {"label":"7", "x":0, "y":1},
115 {"label":"8", "x":1, "y":1},
116 {"label":"9", "x":2, "y":1},
117 {"label":"+", "x":3, "y":1, "h":2},
118 {"label":"4", "x":0, "y":2},
119 {"label":"5", "x":1, "y":2},
120 {"label":"6", "x":2, "y":2},
121 {"label":"1", "x":0, "y":3},
122 {"label":"2", "x":1, "y":3},
123 {"label":"3", "x":2, "y":3},
124 {"label":"Enter", "x":3, "y":3, "h":2},
125 {"label":"0", "x":0, "y":4, "w":2},
126 {"label":".", "x":2, "y":4}
127 ]
128 }
129 }
130}
131```
132
133`layouts` 对象描述了键盘的物理配列信息，其下的 `LAYOUT` 对象命名须与 `numpad.h` 中的一致，而 `LAYOUT` 下的 `layout` 对象，其下每个JSON对象描述了各物理按键，格式如下：
134
135```
136 按键名，不会在配置器中展现。
137 |
138 | 按键的X坐标，从键盘左侧开始数。
139 | |
140 | |
141 | | 按键的Y坐标，从键盘上侧（后视角）开始数。
142 | | |
143 ↓ ↓ ↓
144{"label":"Num Lock", "x":0, "y":0},
145```
146
147部分对象包含 `"w"` 和 `"h"` 字段，用以描述按键的宽高值。
148
149?> 关于 `info.json` 文件的详细信息，参见[`info.json` 文件格式](zh-cn/reference_info_json.md)。
150
151
152## 配置器如何配置按键
153
154配置器API基于配列宏定义及JSON描述文件创建出键盘的可视化展现，并将每个可视化元素依序绑定到指定的按键：
155
156配列宏定义中的键 | 所使用的JSON对象
157:---: | :----
158k00 | {"label":"Num Lock", "x":0, "y":0}
159k01 | {"label":"/", "x":1, "y":0}
160k02 | {"label":"*", "x":2, "y":0}
161k03 | {"label":"-", "x":3, "y":0}
162k10 | {"label":"7", "x":0, "y":1}
163k11 | {"label":"8", "x":1, "y":1}
164k12 | {"label":"9", "x":2, "y":1}
165k13 | {"label":"+", "x":3, "y":1, "h":2}
166k20 | {"label":"4", "x":0, "y":2}
167k21 | {"label":"5", "x":1, "y":2}
168k22 | {"label":"6", "x":2, "y":2}
169k30 | {"label":"1", "x":0, "y":3}
170k31 | {"label":"2", "x":1, "y":3}
171k32 | {"label":"3", "x":2, "y":3}
172k33 | {"label":"Enter", "x":3, "y":3, "h":2}
173k40 | {"label":"0", "x":0, "y":4, "w":2}
174k42 | {"label":".", "x":2, "y":4}
175
176当用户在配置器中选中左上角的按键，并赋予数字区锁定键（NumLock）时，配置器会将 `KC_NLCK` 作为第一个按键进行键映射文件的构建工作，其它按键逻辑类似。其中 `label` 键值未被用到，其用于用户在调试 `info.json` 文件时，可以参考辨认出各按键。
177
178
179## 问题及副作用
180
181目前配置器还不支持按键偏转及类似ISO回车键这种非矩形按键。另外，对于纵向上偏离其行的按键 &mdash; 特别是像[TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/)这种1800配列的键盘中的方向键 &mdash; 如果 `info.json` 文件的贡献者没有做出修正，KLE转JSON数据工具将会不知如何处理。
182
183### 解决方案
184
185#### 非矩阵形状的按键
186
187针对ISO回车键的情况，QMK会将其定制化显示成一个矩形键，宽1.25u高2u，按键矩阵的右边与字母区的右边对齐。
188
189![](https://i.imgur.com/JKngtTw.png)
190*一款60% ISO配列的键盘, 在QMK配置器中的渲染样式。*
191
192#### 纵向偏移的按键
193
194对于纵向偏移的按键，将其视作未偏移的样子放入KLE，最后在转换后的JSON文件中，按需编辑其Y偏移值。
195
196![](https://i.imgur.com/fmDvDzR.png)
197*一款1800配列键盘在KLE中的渲染样式，方向键未进行纵向偏移移动。*
198
199![](https://i.imgur.com/8beYMBR.png)
200*这份Unix差异文件，展示了我们需要在JSON文件中进行的纵向偏移改动。*
diff --git a/docs/zh-cn/reference_glossary.md b/docs/zh-cn/reference_glossary.md
index 06d363250..e1dfccddd 100644
--- a/docs/zh-cn/reference_glossary.md
+++ b/docs/zh-cn/reference_glossary.md
@@ -1,5 +1,10 @@
1# QMK术语表 1# QMK术语表
2 2
3<!---
4 original document: 0.15.12:docs/reference_glossary.md
5 git diff 0.15.12 HEAD -- docs/reference_glossary.md | cat
6-->
7
3## ARM 8## ARM
4多家公司生产的32位单片机系列，例如Atmel, Cypress, Kinetis, NXP, ST, 和 TI等公司。 9多家公司生产的32位单片机系列，例如Atmel, Cypress, Kinetis, NXP, ST, 和 TI等公司。
5 10
@@ -7,16 +12,16 @@
7[Atmel](https://www.microchip.com/)公司的单片机系列。 AVR是TMK的初始支持平台。 12[Atmel](https://www.microchip.com/)公司的单片机系列。 AVR是TMK的初始支持平台。
8 13
9## AZERTY 14## AZERTY
10Français (法国)标准键盘布局。用键盘的前六个字母命名。 15Français （法语）标准键盘布局。用键盘的前六个字母命名。
11 16
12## Backlight(背光) 17## Backlight(背光)
13键盘上照明的通称。背光通常是一组LED灯，通过键帽或者按轴发光，但也不总是这样。 18键盘上照明的通称。背光通常是一组LED灯，穿过键帽或者轴体发光，但也不总是这样。
14 19
15## Bluetooth(蓝牙) 20## Bluetooth(蓝牙)
16一种短距离点对点无线协议。许多多无线键盘使用此协议。 21一种短距离点对点无线传输协议。许多无线键盘使用此协议。
17 22
18## Bootloader(引导加载程序) 23## Bootloader(引导加载程序)
19一种写到你单片机的保护区的特殊的程序，该程序可以使单片机升级自己的固件，通常是通过USB来升级。 24一种写到你单片机保护区的特殊程序，该程序可以使单片机升级自己的固件，通常是通过USB来升级。
20 25
21## Bootmagic(热改键) 26## Bootmagic(热改键)
22允许各种键盘行为动态变化的功能，如交换或禁用常用键。 27允许各种键盘行为动态变化的功能，如交换或禁用常用键。
@@ -36,12 +41,12 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。
36## Dynamic Macro(动态宏) 41## Dynamic Macro(动态宏)
37一种记录在键盘上的宏，当键盘拔出或计算机重新启动时，宏将丢失。 42一种记录在键盘上的宏，当键盘拔出或计算机重新启动时，宏将丢失。
38 43
39* [动态宏文档](feature_dynamic_macros.md) 44* [动态宏文档](zh-cn/feature_dynamic_macros.md)
40 45
41## Eclipse 46## Eclipse
42是一种受C语言开发者追捧的集成开发环境(IDE)。 47是一种受C语言开发者追捧的集成开发环境(IDE)。
43 48
44* [Eclipse安装说明](eclipse.md) 49* [Eclipse安装说明](zh-cn/other_eclipse.md)
45 50
46## Firmware(固件) 51## Firmware(固件)
47用来控制单片机的软件。 52用来控制单片机的软件。
@@ -52,14 +57,14 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。
52## GitHub 57## GitHub
53负责大多数QMK项目的网站。它是Git、问题跟踪和其他帮助我们运行qmk的功能的集成平台。 58负责大多数QMK项目的网站。它是Git、问题跟踪和其他帮助我们运行qmk的功能的集成平台。
54 59
55## ISP(在系统编程) 60## ISP(在统编程)
56在系统编程(In-system programming), 使用外部硬件和JTAG管脚对AVR芯片进行编程的一种方法。 61在统编程(In-system programming), 使用外部硬件和JTAG管脚对AVR芯片进行编程的一种方法。
57 62
58## hid_listen 63## hid_listen
59从键盘接收调试消息的接口。 您可以使用[QMK Flasher](https://github.com/qmk/qmk_flasher)或[PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)查看这些消息 64从键盘接收调试消息的接口。 您可以使用[QMK Flasher](https://github.com/qmk/qmk_flasher)或[PJRC's hid_listen](https://www.pjrc.com/teensy/hid_listen.html)查看这些消息
60 65
61## Keycode(键码) 66## Keycode(键码)
62表示特定键的2字节数据。`0x00`-`0xFF`用于[基本键码](keycodes_basic.md)而`0x100`-`0xFFFF`用于[量子键码](quantum_keycodes.md). 67表示特定键的2字节数据。`0x00`-`0xFF`用于[基本键码](zh-cn/keycodes_basic.md)而`0x100`-`0xFFFF`用于[量子键码](zh-cn/quantum_keycodes.md).
63 68
64## Key Down 69## Key Down
65一个键按下尚未抬起时触发的事件。 70一个键按下尚未抬起时触发的事件。
@@ -71,12 +76,12 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。
71映射到物理键盘布局的一组键码，在按键和按键释放时进行处理。有时翻译为布局，意为软件上表示的布局，即映射。 76映射到物理键盘布局的一组键码，在按键和按键释放时进行处理。有时翻译为布局，意为软件上表示的布局，即映射。
72 77
73## Layer(层) 78## Layer(层)
74为了让一个键实现多个功能的抽象结构。最高活层有限。 79为了让一个键实现多个功能的抽象结构。层上限。
75 80
76## Leader Key(前导键、设置菜单键) 81## Leader Key(前导键、设置菜单键)
77本功能允许您点击前导键，然后按顺序按1-3个键子来激活按键或其他量子功能。 82本功能允许您点击前导键，然后按顺序按1-3个键子来激活按键或其他量子功能。
78 83
79* [前导键文档](feature_leader_key.md) 84* [前导键文档](zh-cn/feature_leader_key.md)
80 85
81## LED 86## LED
82发光二极管，键盘上最常用的指示灯装置。 87发光二极管，键盘上最常用的指示灯装置。
@@ -90,18 +95,18 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。
90## Macro(宏) 95## Macro(宏)
91本功能可以在敲击单个键后发送多个按键事件(hid报告)。 96本功能可以在敲击单个键后发送多个按键事件(hid报告)。
92 97
93* [宏文档](feature_macros.md) 98* [宏文档](zh-cn/feature_macros.md)
94 99
95## MCU(单片机、微控制单元) 100## MCU(单片机、微控制单元)
96微控制单元，键盘的处理器。 101微控制单元，键盘的处理器。
97 102
98## Modifier(修改键、修、功能键) 103## Modifier(修、修改键、功能键)
99按住该键将会改变其他键的功能，修饰键包括 Ctrl, Alt, 和 Shift。 104按住该键将会改变其他键的功能，修饰键包括 Ctrl, Alt, 和 Shift。
100 105
101## Mousekeys(鼠标键) 106## Mousekeys(鼠标键)
102本功能在您敲击键盘时会控制鼠标光标。 107本功能在您敲击键盘时会控制鼠标光标。
103 108
104* [鼠标键文档](feature_mouse_keys.md) 109* [鼠标键文档](zh-cn/feature_mouse_keys.md)
105 110
106## N-Key Rollover (NKRO、全键无冲) 111## N-Key Rollover (NKRO、全键无冲)
107一种术语，适用于能够同时报告任意数量按键的键盘。 112一种术语，适用于能够同时报告任意数量按键的键盘。
@@ -128,17 +133,17 @@ Français (法国)标准键盘布局。用键盘的前六个字母命名。
128HID报告中的一个1字节的数字，表示一个键子。这些数字在下列文档中[HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)该文档发布于[USB-IF](https://www.usb.org/)。 133HID报告中的一个1字节的数字，表示一个键子。这些数字在下列文档中[HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf)该文档发布于[USB-IF](https://www.usb.org/)。
129 134
130## Space Cadet键盘的shift键 135## Space Cadet键盘的shift键
131一种特使的shift设置，能让你通过敲击左或右shift一次或多次键入不同的括号。 136一种特殊的shift设置，能让你通过敲击左或右shift一次或多次键入不同的括号。
132 137
133* [Space Cadet键盘文档](feature_space_cadet.md) 138* [Space Cadet键盘文档](zh-cn/feature_space_cadet.md)
134 139
135## Tap(敲击、单击) 140## Tap(敲击、单击)
136按下并释一个键。在某些情况下您需要区分键按下和键抬起，但是单击把两个事件都包括了。 141按下并起一个键。在某些情况下您需要区分键按下和键抬起，但是单击把两个事件都包括了。
137 142
138## Tap Dance(多击键) 143## Tap Dance(多击键)
139本功能允许向同一个键子分配多个键码，并根据按键次数区分。 144本功能允许向同一个键子分配多个键码，并根据按键次数区分。
140 145
141* [多击键文档](feature_tap_dance.md) 146* [多击键文档](zh-cn/feature_tap_dance.md)
142 147
143## Teensy 148## Teensy
144一种低成本AVR开发板<!--译者吐槽：我怎么感觉成本不低。好吧，我穷。 -->，通常用于手工连线键盘。这个teensy是有点小贵但是halfkay bootloader会让它刷写十分简单，所以也很常用。 149一种低成本AVR开发板<!--译者吐槽：我怎么感觉成本不低。好吧，我穷。 -->，通常用于手工连线键盘。这个teensy是有点小贵但是halfkay bootloader会让它刷写十分简单，所以也很常用。
@@ -147,21 +152,47 @@ HID报告中的一个1字节的数字，表示一个键子。这些数字在下
147用于照亮电路板底面的LED的总称。这些LED通常从印刷电路板的底部向键盘所在的表面发光。 152用于照亮电路板底面的LED的总称。这些LED通常从印刷电路板的底部向键盘所在的表面发光。
148 153
149## Unicode 154## Unicode
150在较大的计算机世界中，Unicode是一组编码方案，用于表示任何语言中的字符。 与qmk相关的是，它意味着使用各种操作系统方案来发送Unicode代码点，而不是扫描码。 155在广阔的计算机世界中，Unicode是一组编码方案，用于表示任何语言中的字符。 与qmk相关的是，它意味着使用各种操作系统方案来发送Unicode码点，而不是扫描码。
151 156
152* [Unicode文档](feature_unicode.md) 157* [Unicode文档](zh-cn/feature_unicode.md)
153 158
154## Unit Testing(单元测试) 159## Unit Testing(单元测试)
155针对qmk的自动运行测试框架。单元测试帮助我们确信我们的更改不会破坏任何东西。 160针对qmk的自动测试框架。单元测试帮助我们确信我们的更改不会破坏任何东西。
156 161
157* [单元测试文档](unit_testing.md) 162* [单元测试文档](zh-cn/unit_testing.md)
158 163
159## USB 164## USB
160通用串行总线，键盘最常见的有线接口。 165通用串行总线，键盘最常见的有线接口。
161 166
162## USB 主机 (或简易主机) 167## USB 主机 (简称主机)
163USB你的电脑，或者你的键盘所插的任何设备。 168USB是你的电脑，或者你的键盘所插的任何设备。
164 169
165# 并没有找到你想找到的术语? 170# 并没有找到你想找到的术语?
166 171
167[建立一个issue](https://github.com/qmk/qmk_firmware/issues) ，想好你的问题，或许你所问的术语就会添加到这里。创建一个PR帮我们添加需要添加的术语当然坠吼了:) 172[新建一个issue](https://github.com/qmk/qmk_firmware/issues) ，想好你的问题，或许你所问的术语就会添加到这里。创建一个PR帮我们添加需要添加的术语当然坠吼了:)
173
174## 中文翻译术语特别说明（terms of Chinese translation）:id=terms-of-zh-cn-translate
175!>如果你对QMK文档翻译中的细节不关心，请跳过该节
176
177由于语言及文化差异，QMK英文文档中的部分内容，很难在**保持原句结构**的情况下，完美地翻译为中文，而保持翻译前后的语句结构一致对于开源代码的文档翻译来讲十分重要，这样才能确保不同的文档贡献者不会*夹带私货*，防止不同的翻译风格、不同的翻译水准、不同的理解与润色最终产生糟糕的混合。
178因此，这里会对一些词组的的翻译进行规范化，并希望阅读者及后续文档翻译维护者，维持这种统一的范式。
179
180### keyboard（键盘）及keymap（键映射）
181QMK文档中使用最多的两个术语是keyboard及keymap
182* 键盘：在中文语境下，我们提及键盘，基本是在指物理键盘，而在QMK文档中到处可见的“键盘”一词，多对应的是代码中 `keyboards\` 目录下的键盘定义，其更接近于我们讲的“配列”的概念，主要描述了键盘的大体结构，物理键数量及排列。
183* 键映射：keymap的作用是定义物理键盘到实际输出键值(keycode)的映射关系，也是QMK最重要、涉及最多的概念。QMK很多功能就是为了能够在不改变键盘物理排列/电路组成/芯片程序的情况下，动态地改变物理按键输出的键值。如，通过层切换，将原先的wasd键，切换到可以上下左右的模式，或是一键切换CapsLock和Control，实现这些功能的核心工作就是一套动态的keymap，即键映射逻辑。这里不使用“布局”一词作为keymap的翻译，是因为该词过于宽泛。键映射即便是不好听，至少解释了意思且语境中不容易误解。
184
185### mod-tap
186倾向于不翻译，直接使用原词。因为找不到合适的译法
187
188### dead key
189直译为死键，西语体系下使用的特殊符号，中文中无对应概念。
190
191### flashing（firmware）
192使用“刷写”而非容易迷惑的“刷新”
193
194### option/configuration/setting
195根据上下文灵活考虑。对于组件化配置的概念，如一个功能支持与否，使用“配置”一词；对于客观上一定存在的某项设置值，使用“设置”一词。
196
197### commit/push/pull等Git术语
198倾向于不翻译。这些词语的对应中文词语过于宽泛或词性不明，非常容易混淆上下文。
diff --git a/docs/zh-cn/support.md b/docs/zh-cn/support.md
new file mode 100644
index 000000000..e636d29c9
--- /dev/null
+++ b/docs/zh-cn/support.md
@@ -0,0 +1,22 @@
1# 寻求帮助
2
3<!---
4 original document: 0.15.12:docs/support.md
5 git diff 0.15.12 HEAD -- docs/support.md | cat
6-->
7
8你可以从很多渠道获取QMK帮助。
9
10在你前往社区进行沟通前，请先阅览我们的社区[行为守则](https://qmk.fm/coc/)
11
12## 实时沟通
13
14在你需要帮助时，最便捷的办法是通过我们的[Discord服务器](https://discord.gg/Uq7gcHh)进行沟通，通常会有人在线，也有很多乐于助人的人。
15
16## OLKB Subreddit
17
18QMK的官方论坛是[reddit.com](https://reddit.com)上的[/r/olkb](https://reddit.com/r/olkb).
19
20## GitHub Issues
21
22你可以在[Github上发Issue](https://github.com/qmk/qmk_firmware/issues)，对于需要深入讨论或需要调试的问题，会方便得多。
diff --git a/docs/zh-cn/syllabus.md b/docs/zh-cn/syllabus.md
new file mode 100644
index 000000000..d0b861530
--- /dev/null
+++ b/docs/zh-cn/syllabus.md
@@ -0,0 +1,77 @@
1# QMK大纲
2
3<!---
4 original document: 0.15.12:docs/syllabus.md
5 git diff 0.15.12 HEAD -- docs/syllabus.md | cat
6-->
7
8这一页旨在帮你建立关于QMK的相关基础知识，并提供能引导你成为QMK大师所需的所有概念。
9
10# 基本概念
11
12如果你还没有看其它部分，先阅读这一节吧。在阅读了[介绍](zh-cn/newbs.md)之后，你可以制作、编译、刷写一个简单的键映射了，以下文档可以助你充实各系列的知识。
13
14* **了解如何使用QMK**
15 * [介绍](zh-cn/newbs.md)
16 * [CLI](zh-cn/cli.md)
17 * [GIT](zh-cn/newbs_git_best_practices.md)
18* **了解键映射**
19 * [层](zh-cn/feature_layers.md)
20 * [键码](zh-cn/keycodes.md)
21 * 含所有可用键码，一些会涉及进阶或高级的话题。
22* **配置IDE** - 可选的
23 * [Eclipse](zh-cn/other_eclipse.md)
24 * [VS Code](zh-cn/other_vscode.md)
25
26# 进阶话题
27
28包含窥探QMK主要功能内部原理的话题。你可以不用阅读这些，然而，跳过这些话题的话，去看高级话题的时候会让你很迷惑。
29
30* **各功能的配置**
31 <!-- * Configuration Overview FIXME(skullydazed/anyone): write this document -->
32 * [音频](zh-cn/feature_audio.md)
33 * 灯光
34 * [背光](zh-cn/feature_backlight.md)
35 * [LED矩阵](zh-cn/feature_led_matrix.md)
36 * [RGB灯光](zh-cn/feature_rgblight.md)
37 * [RGB矩阵](zh-cn/feature_rgb_matrix.md)
38 * [点按配置](zh-cn/tap_hold.md)
39 * [充分利用AVR的存储空间](zh-cn/squeezing_avr.md)
40* **深入键映射**
41 * [键映射](zh-cn/keymap.md)
42 * [键码与自定义函数](zh-cn/custom_quantum_functions.md)
43 * 宏
44 * [动态宏](zh-cn/feature_dynamic_macros.md)
45 * [宏](zh-cn/feature_macros.md)
46 * [Tap Dance](zh-cn/feature_tap_dance.md)
47 * [组合键](zh-cn/feature_combo.md)
48 * [用户空间](zh-cn/feature_userspace.md)
49 * [按键重定义](zh-cn/feature_key_overrides.md)
50
51# 高级话题
52
53这些话题需要较多基础知识，使用这些高级功能前，你应该对如何通过 `config.h` 和 `rules.mk` 来配置键盘选项非常熟悉。
54
55* **维护QMK键盘**
56 * [飞线指南](zh-cn/hand_wire.md)
57 * [键盘开发指引](zh-cn/hardware_keyboard_guidelines.md)
58 * [info.json参考资料](zh-cn/reference_info_json.md)
59 * [防抖API](zh-cn/feature_debounce_type.md)
60* **高级功能**
61 * [Unicode](zh-cn/feature_unicode.md)
62 * [API](zh-cn/api_overview.md)
63 * [Bootmagic Lite](zh-cn/feature_bootmagic.md)
64* **硬件相关**
65 * [键盘工作原理](zh-cn/how_keyboards_work.md)
66 * [键盘矩阵原理](zh-cn/how_a_matrix_works.md)
67 * [分体键盘](zh-cn/feature_split_keyboard.md)
68 * [速记](zh-cn/feature_stenography.md)
69 * [光标设备](zh-cn/feature_pointing_device.md)
70* **开发核心知识**
71 * [C编码规范](zh-cn/coding_conventions_c.md)
72 * [兼容的微处理器](zh-cn/compatible_microcontrollers.md)
73 * [自定义矩阵](zh-cn/custom_matrix.md)
74 * [理解QMK](zh-cn/understanding_qmk.md)
75* **CLI开发**
76 * [编码规范](zh-cn/coding_conventions_python.md)
77 * [CLI开发总览](zh-cn/cli_development.md)
diff --git a/docs/zh-cn/translating.md b/docs/zh-cn/translating.md
new file mode 100644
index 000000000..fa80ffd7f
--- /dev/null
+++ b/docs/zh-cn/translating.md
@@ -0,0 +1,60 @@
1# 翻译QMK文档
2
3<!---
4 original document: 0.15.12:docs/translating.md
5 git diff 0.15.12 HEAD -- docs/translating.md | cat
6-->
7
8根目录下（`docs/`）的所有文件应当是英语的 - 其它语言应使用 ISO 639-1 中定义的语言编码建立子目录，后跟随一个 `-` 以及必要的国家编码。[常见的语言编码可见这里](https://www.andiamo.co.uk/resources/iso-language-codes/)。如果此目录不存在，可以新建。每个翻译过的文件的文件名，都应保持与英语版本的一致，以确保超链接的退化兼容性。
9
10文件夹下的 `_summary.md` 文件中，有链接向其它文件的地址，在翻译过的名称后，跟随的链接前应添加该语言的目录名：
11
12```markdown
13 * [QMK简介](zh-cn/getting_started_introduction.md)
14```
15
16所有导向其它文档页面的链接也必须有语言目录名前缀，若还指向了页面指定位置（即特定的标题），必须使用标题的英文ID，如：
17
18```markdown
19[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment)
20
21## 建立你的环境 :id=set-up-your-environment
22```
23
24在翻译后，以下文件也需要进行修改：
25
26* [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md)
27 中的每一行应包含该语言国家国旗的[GitHub emoji编码](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag)标志：
28
29 ```markdown
30 - [:cn: 中文](/zh-cn/)
31 ```
32
33* [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html)
34 `placeholder` 及 `noData` 对象应有一个指向对应语言的入口项：
35
36 ```js
37 '/zh-cn/': '没有结果!',
38 ```
39
40 用于 "QMK固件" 边栏标题链接的 `nameLink` 同样需要添加对应配置：
41
42 ```js
43 '/zh-cn/': '/#/zh-cn/',
44 ```
45
46 最后确保在 `fallbackLanguages` 列表中添加该语言项，这样未翻译的文档链接将回退到英文版，而不是出现404页面：
47
48 ```js
49 fallbackLanguages: [
50 // ...
51 'zh-cn',
52 // ...
53 ],
54 ```
55
56## 预览你的翻译成果
57
58请阅读[文档预览](zh-cn/contributing.md#previewing-the-documentation)来设置文档的本地预览 - 在页面右上角的 "Translations" 菜单中应当可以看到你翻译的语言的入口。
59
60当你觉得一切就绪了，请发起pull request给我们吧！
diff --git a/docs/zh-cn/zh_cn_doc_status.sh b/docs/zh-cn/zh_cn_doc_status.sh
new file mode 100644
index 000000000..84693e546
--- /dev/null
+++ b/docs/zh-cn/zh_cn_doc_status.sh
@@ -0,0 +1,35 @@
1#! /bin/sh
2#
3# Script to display Simplified Chinese translation status of documents
4# Copied from the japanese one
5#
6if [ ! -d docs/zh-cn ]; then
7 echo "'docs/zh-cn' not found."
8 echo "do:"
9 echo " cd \$(QMK_TOP)"
10 echo " ./docs/zh-cn/zh-cn_doc_status.sh"
11 exit 1
12fi
13
14en_docs=`cd docs;ls -1 [a-z]*.md`
15zh_cn_docs=`cd docs/zh-cn;ls -1 [a-z]*.md`
16en_count=`echo $en_docs | wc -w`
17zh_cn_count=`echo $zh_cn_docs | wc -w`
18echo "English documents $en_count files."
19echo "Simplified Chinese documents $zh_cn_count files."
20
21echo "Files that have not been translated yet:"
22for docfile in $en_docs
23do
24 if [ ! -f docs/zh-cn/$docfile ]; then
25 wc docs/$docfile
26 fi
27done | sort
28echo "Files that have not been updated yet:"
29grep --no-filename "^[ ]*git diff" docs/zh-cn/*.md | while read cmd
30do
31 cline=`echo $cmd | sh | wc -l`
32 if [ $cline -gt 0 ]; then
33 echo "$cline $cmd"
34 fi
35done | sort
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-04 12:05:51 +0000