97 files changed, 4004 insertions, 1731 deletions
diff --git a/docs/_langs.md b/docs/_langs.md
index 7fb4a29d3..f7b375fb9 100644
--- a/docs/_langs.md
+++ b/docs/_langs.md
@@ -4,5 +4,6 @@
  - [:es: Español](/es/)
  - [:fr: Français](/fr-fr/)
  - [:he: עברית](/he-il/)
+  - [:brazil: Português](/pt-br/)
  - [:ru: Русский](/ru-ru/)
  - [:jp: 日本語](/ja/)
diff --git a/docs/_summary.md b/docs/_summary.md
index 808a8de4a..de8148138 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -3,7 +3,10 @@
  * [Building Your First Firmware](newbs_building_firmware.md)
  * [Flashing Firmware](newbs_flashing.md)
  * [Testing and Debugging](newbs_testing_debugging.md)
-  * [Git Best Practices](newbs_best_practices.md)
+  * [Best Git Practices](newbs_git_best_practices.md)
+    * [Using Your Fork's Master](newbs_git_using_your_master_branch.md)
+    * [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
+    * [Resynchronizing a Branch](newbs_git_resynchronize_a_branch.md)
  * [Learning Resources](newbs_learn_more_resources.md)
 * [QMK Basics](README.md)
@@ -98,9 +101,11 @@
  * [Hand Wiring Guide](hand_wire.md)
  * [ISP Flashing Guide](isp_flashing_guide.md)
  * [ARM Debugging Guide](arm_debugging.md)
+  * [ADC Driver](adc_driver.md)
  * [I2C Driver](i2c_driver.md)
  * [WS2812 Driver](ws2812_driver.md)
  * [GPIO Controls](internals_gpio_control.md)
+  * [Custom Matrix](custom_matrix.md)
  * [Proton C Conversion](proton_c_conversion.md)
 * For a Deeper Understanding
@@ -111,7 +116,7 @@
  * [Using Eclipse with QMK](other_eclipse.md)
  * [Using VSCode with QMK](other_vscode.md)
  * [Support](support.md)
-  * [How to add translations](translating.md)
+  * [Translating the QMK Docs](translating.md)
 * QMK Internals (In Progress)
  * [Defines](internals_defines.md)
diff --git a/docs/adc_driver.md b/docs/adc_driver.md
new file mode 100644
index 000000000..26e148add
--- /dev/null
+++ b/docs/adc_driver.md
@@ -0,0 +1,50 @@
+# ADC Driver
+QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](feature_encoders.md).
+This driver is currently AVR-only. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V).
+## Usage
+To use this driver, add the following to your `rules.mk`:
+```make
+SRC += analog.c
+```
+Then place this include at the top of your code:
+```c
+#include "analog.h"
+```
+## Channels
+|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328P|
+|-------|-------------|-------------|---------|----------|
+|0      |`F0`         |`F0`         |`A0`     |`C0`      |
+|1      |`F1`         |`F1`         |`A1`     |`C1`      |
+|2      |`F2`         |             |`A2`     |`C2`      |
+|3      |`F3`         |             |`A3`     |`C3`      |
+|4      |`F4`         |`F4`         |`A4`     |`C4`      |
+|5      |`F5`         |`F5`         |`A5`     |`C5`      |
+|6      |`F6`         |`F6`         |`A6`     |*         |
+|7      |`F7`         |`F7`         |`A7`     |*         |
+|8      |             |`D4`         |         |          |
+|9      |             |`D6`         |         |          |
+|10     |             |`D7`         |         |          |
+|11     |             |`B4`         |         |          |
+|12     |             |`B5`         |         |          |
+|13     |             |`B6`         |         |          |
+<sup>\* The ATmega328P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
+## Functions
+|Function                    |Description                                                                                                        |
+|----------------------------|-------------------------------------------------------------------------------------------------------------------|
+|`analogReference(mode)`     |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
+|`analogRead(pin)`           |Reads the value from the specified Arduino pin, eg. `4` for ADC6 on the ATmega32U4.                                |
+|`analogReadPin(pin)`        |Reads the value from the specified QMK pin, eg. `F6` for ADC6 on the ATmega32U4.                                   |
+|`pinToMux(pin)`             |Translates a given QMK pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)".   |
+|`adc_read(mux)`             |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information.        |
diff --git a/docs/arm_debugging.md b/docs/arm_debugging.md
index 448b7a8fc..04887d88b 100644
--- a/docs/arm_debugging.md
+++ b/docs/arm_debugging.md
@@ -1,4 +1,4 @@
-# ARM Debugging usign Eclipse
+# ARM Debugging using Eclipse
 This page describes how to setup debugging for ARM MCUs using an SWD adapter and open-source/free tools. In this guide we will install GNU MCU Eclipse IDE for C/C++ Developers and OpenOCD together with all the necessary dependencies.
@@ -18,7 +18,7 @@ XPM installation instructions can be found [here](https://www.npmjs.com/package/
 ### The ARM Toolchain
-Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @gnu-mcu-eclipse/arm-none-eabi-gcc`.
+Using XPM it is very easy to install the ARM toolchain. Enter the command `xpm install --global @xpack-dev-tools/arm-none-eabi-gcc`.
 ### Windows build tools
@@ -33,7 +33,7 @@ If you have an ST-Link the drivers can be found [here](https://www.st.com/en/dev
 ### OpenOCD
-This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @gnu-mcu-eclipse/openocd`.
+This dependency allows SWD access from GDB and it is essential for debugging. Run `xpm install --global @xpack-dev-tools/openocd`.
 ### Java
@@ -45,17 +45,17 @@ Now its finally time to install the IDE. Use the Release page [here](https://git
 ## Configuring Eclipse
-Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing code as Makefile Project. Select next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
+Open up the Eclipse IDE we just downloaded. To import our QMK directory select File -> Import -> C/C++ -> Existing Code as Makefile Project. Select Next and use Browse to select your QMK folder. In the tool-chain list select ARM Cross GCC and select Finish.
-Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchain Paths. Press xPack and OK. Repeat for OpenOCD Path  and if you are on windows for Build Tool Path. Select Apply and Close.
+Now you can see the QMK folder on the left hand side. Right click it and select Properties. On the left hand side, expand MCU and select ARM Toolchains Paths. Press xPack and OK. Repeat for OpenOCD Path and if you are on Windows for Build Tools Path. Select Apply and Close.
-Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Open Perspective -> Others -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
+Now its time to install the necessary MCU packages. Go to Packs perspective by selecting Window -> Perspective -> Open Perspective -> Other... -> Packs. Now select the yellow refresh symbol next to the Packs tab. This will take a long time as it is requesting the MCU definitions from various places. If some of the links fail you can probably select Ignore.
-When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectonics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Open Perspective -> Others -> C/C++.
+When this finishes you must find the MCU which we will be building/debugging for. In this example I will be using the STM32F3 series MCUs. On the left, select STMicroelectronics -> STM32F3 Series. On the middle window we can see the pack. Right click and select Install. Once that is done we can go back to the default perspective, Window -> Perspective -> Open Perspective -> Other... -> C/C++.
-We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under devices select the appropriate variant of your MCU. For my example it is STM32F303CC
+We need to let eclipse know the device we intent to build QMK on. Right click on the QMK folder -> Properties -> C/C++ Build -> Settings. Select the Devices tab and under Devices select the appropriate variant of your MCU. For my example it is STM32F303CC
-While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
+While we are here let's setup the build command as well. Select C/C++ Build and then the Behavior tab. On the Build command, replace `all` with your necessary make command. For example for a rev6 Planck with the default keymap this would be `planck/rev6:default`. Select Apply and Close.
 ## Building
@@ -71,7 +71,7 @@ NOTE: Make sure the SWCLK and SWDIO pins are not used in the matrix of your keyb
 ### Configuring the Debugger
-Right click on your QMK folder, select Debug As -> Debug Configuration. Here double click on GDB OpenOCD Debugging. Select the debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and googleing to find out. The default script for the STM32F3 is called stm32f3discovery.cfg. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
+Right click on your QMK folder, select Debug As -> Debug Configurations... . Here double click on GDB OpenOCD Debugging. Select the Debugger tab and enter the configuration necessary for your MCU. This might take some fiddling and Googling to find out. The default script for the STM32F3 is called `stm32f3discovery.cfg`. To let OpenOCD know, in the Config options enter `-f board/stm32f3discovery.cfg`.
 NOTE: In my case this configuration script requires editing to disable the reset assertion. The locations of the scripts can be found in the actual executable field usually under the path `openocd/version/.content/scripts/board`. Here I edited `reset_config srst_only` to `reset_config none`.
@@ -81,7 +81,7 @@ Select Apply and Close.
 Reset your keyboard.
-Press the bug icon and if all goes well you should soon find yourself in the debug perspective. Here the program counter will pause at the beginning of the main function and way for you to press Play. Most of the features of all debuggers work on ARM MCUs but for exact details google is your friend!
+Press the bug icon and if all goes well you should soon find yourself in the Debug perspective. Here the program counter will pause at the beginning of the main function and wait for you to press Play. Most of the features of all debuggers work on Arm MCUs but for exact details Google is your friend!
 Happy debugging!
diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md
index b5bcb7a1c..56d14438d 100644
--- a/docs/breaking_changes.md
+++ b/docs/breaking_changes.md
@@ -10,16 +10,16 @@ The breaking change period is when we will merge PR's that change QMK in dangero
 ## When is the next Breaking Change?
-The next Breaking Change is scheduled for Nov 29.
+The next Breaking Change is scheduled for February 29, 2020.
 ### Important Dates
 * [x] 2019 Sep 21 - `future` is created. It will be rebased weekly.
-* [ ] 2019 Nov 01 - `future` closed to new PR's.
+* [ ] 2020 Feb 1 - `future` closed to new PR's.
-* [ ] 2019 Nov 01 - Call for testers.
+* [ ] 2020 Feb 1 - Call for testers.
-* [ ] 2019 Nov 27 - `master` is locked, no PR's merged.
+* [ ] 2020 Feb 26 - `master` is locked, no PR's merged.
-* [ ] 2019 Nov 29 - Merge `future` to `master`.
+* [ ] 2020 Feb 28 - Merge `future` to `master`.
-* [ ] 2019 Nov 30 - `master` is unlocked. PR's can be merged again.
+* [ ] 2020 Feb 29 - `master` is unlocked. PR's can be merged again.
 ## What changes will be included?
diff --git a/docs/coding_conventions_c.md b/docs/coding_conventions_c.md
index 08994bfbb..16e28b288 100644
--- a/docs/coding_conventions_c.md
+++ b/docs/coding_conventions_c.md
@@ -14,7 +14,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
  * Think of them as a story describing the feature
  * Use them liberally to explain why particular decisions were made.
  * Do not write obvious comments
-  * If you not sure if a comment is obvious, go ahead and include it.
+  * If you're not sure if a comment is obvious, go ahead and include it.
 * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
 * We use `#pragma once` at the start of header files rather than old-style include guards (`#ifndef THIS_FILE_H`, `#define THIS_FILE_H`, ..., `#endif`)
 * We accept both forms of preprocessor if's: `#ifdef DEFINED` and `#if defined(DEFINED)`
diff --git a/docs/coding_conventions_python.md b/docs/coding_conventions_python.md
index 694aa38cf..1aefc044e 100644
--- a/docs/coding_conventions_python.md
+++ b/docs/coding_conventions_python.md
@@ -8,7 +8,7 @@ Most of our style follows PEP8 with some local modifications to make things less
  * Think of them as a story describing the feature
  * Use them liberally to explain why particular decisions were made.
  * Do not write obvious comments
-  * If you not sure if a comment is obvious, go ahead and include it.
+  * If you're not sure if a comment is obvious, go ahead and include it.
 * We require useful docstrings for all functions.
 * In general we don't wrap lines, they can be as long as needed. If you do choose to wrap lines please do not wrap any wider than 76 columns.
 * Some of our practices conflict with the wider python community to make our codebase more approachable to non-pythonistas.
@@ -309,6 +309,18 @@ FIXME(username): Revisit this code when the frob feature is done.
 ...where username is your GitHub username.
-# Unit Tests
+# Testing
-These are good. We should have some one day.
+We use a combination of Integration and Unit testing to ensure that the our code is as bug-free as possible. All the tests can be found in `lib/python/qmk/tests/`. You can run all the tests with `qmk pytest`.
+At the time of this writing our tests are not very comprehensive. Looking at the current tests and writing new test cases for untested situations is a great way to both familiarize yourself with the codebase and contribute to QMK.
+## Integration Tests
+Integration tests can be found in `lib/python/qmk/tests/test_cli_commands.py`. This is where CLI commands are actually run and their overall behavior is verified. We use [`subprocess`](https://docs.python.org/3.5/library/subprocess.html#module-subprocess) to launch each CLI command and a combination of checking output and returncode to determine if the right thing happened.
+## Unit Tests
+The other `test_*.py` files in `lib/python/qmk/tests/` contain unit tests. You can write tests for individual functions inside `lib/python/qmk/` here. Generally these files are named after the module, with dots replaced by underscores.
+At the time of this writing we do not do any mocking for our tests. If you would like to help us change this please [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there.
diff --git a/docs/config_options.md b/docs/config_options.md
index 0cf3fb78a..6df082335 100644
--- a/docs/config_options.md
+++ b/docs/config_options.md
@@ -143,10 +143,14 @@ If you define these options you will enable the associated feature, which may in
 * `#define IGNORE_MOD_TAP_INTERRUPT`
  * makes it possible to do rolling combos (zx) with keys that convert to other keys on hold, by enforcing the `TAPPING_TERM` for both keys.
  * See [Mod tap interrupt](feature_advanced_keycodes.md#ignore-mod-tap-interrupt) for details
+* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+  * enables handling for per key `IGNORE_MOD_TAP_INTERRUPT` settings
 * `#define TAPPING_FORCE_HOLD`
  * makes it possible to use a dual role key as modifier shortly after having been tapped
  * See [Hold after tap](feature_advanced_keycodes.md#tapping-force-hold)
  * Breaks any Tap Toggle functionality (`TT` or the One Shot Tap Toggle)
+* `#define TAPPING_FORCE_HOLD_PER_KEY`
+  * enables handling for per key `TAPPING_FORCE_HOLD` settings
 * `#define LEADER_TIMEOUT 300`
  * how long before the leader key times out
    * If you're having issues finishing the sequence before it times out, you may need to increase the timeout setting. Or you may want to enable the `LEADER_PER_KEY_TIMING` option, which resets the timeout after each key is tapped.
@@ -287,8 +291,27 @@ This is a [make](https://www.gnu.org/software/make/manual/make.html) file that i
  * Defines which format (bin, hex) is copied to the root `qmk_firmware` folder after building.
 * `SRC`
  * Used to add files to the compilation/linking list.
+* `LIB_SRC`
+  * Used to add files as a library to the compilation/linking list.  
+    The files specified by `LIB_SRC` is linked after the files specified by `SRC`.  
+    For example, if you specify:
+    ```
+    SRC += a.c
+    LIB_SRC += lib_b.c
+    SRC += c.c
+    LIB_SRC += lib_d.c
+    ```
+    The link order is as follows.
+    ```
+     ...  a.o c.o  ...  lib_b.a lib_d.a  ...
+    ```
 * `LAYOUTS`
  * A list of [layouts](feature_layouts.md) this keyboard supports.
+* `LINK_TIME_OPTIMIZATION_ENABLE`
+  * Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.
+  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`
+* `LTO_ENABLE`
+  * It has the same meaning as LINK_TIME_OPTIMIZATION_ENABLE.  You can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`.
 ## AVR MCU Options
 * `MCU = atmega32u4`
@@ -347,9 +370,6 @@ Use these to enable or disable building certain features. The more you have enab
  * Forces the keyboard to wait for a USB connection to be established before it starts up
 * `NO_USB_STARTUP_CHECK`
  * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
-* `LINK_TIME_OPTIMIZATION_ENABLE`
-  * Enables Link Time Optimization (`LTO`) when compiling the keyboard.  This makes the process take longer, but can significantly reduce the compiled size (and since the firmware is small, the added time is not noticeable).  However, this will automatically disable the old Macros and Functions features automatically, as these break when `LTO` is enabled.  It does this by automatically defining `NO_ACTION_MACRO` and `NO_ACTION_FUNCTION`
-  * Alternatively, you can use `LTO_ENABLE` instead of `LINK_TIME_OPTIMIZATION_ENABLE`. 
 ## USB Endpoint Limitations
diff --git a/docs/contributing.md b/docs/contributing.md
index 04dc0da20..c4d5057a0 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -85,7 +85,7 @@ Limited experimentation on the devices I have available shows that 7 is high eno
 Documentation is one of the easiest ways to get started contributing to QMK. Finding places where the documentation is wrong or incomplete and fixing those is easy! We also very badly need someone to edit our documentation, so if you have editing skills but aren't sure where or how to jump in please [reach out for help](#where-can-i-go-for-help)!
-You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click "Suggest An Edit" at the top of each page on http://docs.qmk.fm/.
+You'll find all our documentation in the `qmk_firmware/docs` directory, or if you'd rather use a web based workflow you can click the "Edit this page" link at the bottom of each page on https://docs.qmk.fm/.
 When providing code examples in your documentation, try to observe naming conventions used elsewhere in the docs. For example, standardizing enums as `my_layers` or `my_keycodes` for consistency:
@@ -101,6 +101,18 @@ enum my_keycodes {
 };
 ```
+### Previewing the Documentation
+Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the `qmk_firmware/` folder:
+    ./bin/qmk docs
+or if you only have Python 3 installed:
+    python3 -m http.server 8936
+and navigating to `http://localhost:8936/`.
 ## Keymaps
 Most first-time QMK contributors start with their personal keymaps. We try to keep keymap standards pretty casual (keymaps, after all, reflect the personality of their creators) but we do ask that you follow these guidelines to make it easier for others to discover and learn from your keymap.
diff --git a/docs/custom_matrix.md b/docs/custom_matrix.md
new file mode 100644
index 000000000..cfa900a33
--- /dev/null
+++ b/docs/custom_matrix.md
@@ -0,0 +1,108 @@
+# Custom Matrix
+QMK provides a mechanism to supplement or replace the default matrix scanning routine with your own code.
+The reasons to use this feature include:
+* Extra hardware between the keyboard's switches and MCU pins
+  * I/O multiplexer
+  * Line decoder
+* Irregular switch matrix
+  * Simultaneous use of `COL2ROW` and `ROW2COL`
+## Prerequisites
+Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`.
+Add a new file to your keyboard directory:
+```text
+keyboards/<keyboard>/matrix.c
+```
+And to configure compilation for the new file, add this to your `rules.mk`:
+```make
+SRC += matrix.c
+```
+## 'lite'
+Provides a default implementation for various scanning functions, reducing the boilerplate code when implementing custom matrix.
+To configure it, add this to your `rules.mk`:
+```make
+CUSTOM_MATRIX = lite
+```
+And implement the following functions in a `matrix.c` file in your keyboard folder:
+```c
+void matrix_init_custom(void) {
+    // TODO: initialize hardware here
+}
+bool matrix_scan_custom(matrix_row_t current_matrix[]) {
+    bool matrix_has_changed = false;
+    // TODO: add matrix scanning routine here
+    return matrix_has_changed;
+}
+```
+## Full Replacement
+When more control over the scanning routine is required, you can choose to implement the full scanning routine.
+To configure it, add this to your rules.mk:
+```make
+CUSTOM_MATRIX = yes
+```
+And implement the following functions in a `matrix.c` file in your keyboard folder:
+```c
+matrix_row_t matrix_get_row(uint8_t row) {
+    // TODO: return the requested row data
+}
+void matrix_print(void) {
+    // TODO: use print() to dump the current matrix state to console
+}
+void matrix_init(void) {
+    // TODO: initialize hardware and global matrix state here
+    // Unless hardware debouncing - Init the configured debounce routine
+    debounce_init(MATRIX_ROWS);
+    // This *must* be called for correct keyboard behavior
+    matrix_init_quantum();
+}
+uint8_t matrix_scan(void) {
+    bool matrix_has_changed = false;
+    // TODO: add matrix scanning routine here
+    // Unless hardware debouncing - use the configured debounce routine
+    debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+    // This *must* be called for correct keyboard behavior
+    matrix_scan_quantum();
+    return matrix_has_changed;
+}
+```
+And also provide defaults for the following callbacks:
+```c
+__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
+__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
+__attribute__((weak)) void matrix_init_user(void) {}
+__attribute__((weak)) void matrix_scan_user(void) {}
+```
diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md
index 2d505b075..9c8f89ae1 100644
--- a/docs/custom_quantum_functions.md
+++ b/docs/custom_quantum_functions.md
@@ -114,7 +114,15 @@ Two more deprecated functions exist that provide the LED state as a `uint8_t`:
 This function will be called when the state of one of those 5 LEDs changes. It receives the LED state as a struct parameter.
-You must return either `true` or `false` from this function, depending on whether you want to override the keyboard-level implementation.
+By convention, return `true` from `led_update_user()` to get the `led_update_kb()` hook to run its code, and
+return `false` when you would prefer not to run the code in `led_update_kb()`.
+Some examples include:
+  - overriding the LEDs to use them for something else like layer indication
+    - return `false` because you do not want the `_kb()` function to run, as it would override your layer behavior.
+  - play a sound when an LED turns on or off.
+    - return `true` because you want the `_kb` function to run, and this is in addition to the default LED behavior.
 ?> Because the `led_set_*` functions return `void` instead of `bool`, they do not allow for overriding the keyboard LED control, and thus it's recommended to use `led_update_*` instead.
@@ -122,66 +130,41 @@ You must return either `true` or `false` from this function, depending on whethe
 ```c
 bool led_update_kb(led_t led_state) {
-    if(led_update_user(led_state)) {
+    bool res = led_update_user(led_state);
-        if (led_state.num_lock) {
+    if(res) {
-            writePinLow(B0);
+        // writePin sets the pin high for 1 and low for 0.
-        } else {
+        // In this example the pins are inverted, setting
-            writePinHigh(B0);
+        // it low/0 turns it on, and high/1 turns the LED off.
-        }
+        // This behavior depends on whether the LED is between the pin
-        if (led_state.caps_lock) {
+        // and VCC or the pin and GND.
-            writePinLow(B1);
+        writePin(B0, !led_state.num_lock);
-        } else {
+        writePin(B1, !led_state.caps_lock);
-            writePinHigh(B1);
+        writePin(B2, !led_state.scroll_lock);
-        }
+        writePin(B3, !led_state.compose);
-        if (led_state.scroll_lock) {
+        writePin(B4, !led_state.kana);
-            writePinLow(B2);
-        } else {
-            writePinHigh(B2);
-        }
-        if (led_state.compose) {
-            writePinLow(B3);
-        } else {
-            writePinHigh(B3);
-        }
-        if (led_state.kana) {
-            writePinLow(B4);
-        } else {
-            writePinHigh(B4);
-        }
-        return true;
    }
+    return res;
 }
 ```
 ### Example `led_update_user()` Implementation
+This incomplete example would play a sound if Caps Lock is turned on or off. It returns `true`, because you also want the LEDs to maintain their state.
 ```c
+#ifdef AUDIO_ENABLE
+  float caps_on[][2] = SONG(CAPS_LOCK_ON_SOUND);
+  float caps_off[][2] = SONG(CAPS_LOCK_OFF_SOUND);
+#endif
 bool led_update_user(led_t led_state) {
-    if (led_state.num_lock) {
+    #ifdef AUDIO_ENABLE
-        writePinLow(B0);
+    static uint8_t caps_state = 0;
-    } else {
+    if (caps_state != led_state.caps_lock) {
-        writePinHigh(B0);
+        led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
-    }
+        caps_state = led_state.caps_lock;
-    if (led_state.caps_lock) {
-        writePinLow(B1);
-    } else {
-        writePinHigh(B1);
-    }
-    if (led_state.scroll_lock) {
-        writePinLow(B2);
-    } else {
-        writePinHigh(B2);
-    }
-    if (led_state.compose) {
-        writePinLow(B3);
-    } else {
-        writePinHigh(B3);
-    }
-    if (led_state.kana) {
-        writePinLow(B4);
-    } else {
-        writePinHigh(B4);
    }
+    #endif
    return true;
 }
 ```
@@ -411,7 +394,7 @@ void keyboard_post_init_user(void) {
  // Set default layer, if enabled
  if (user_config.rgb_layer_change) {
    rgblight_enable_noeeprom();
-    rgblight_sethsv_noeeprom_cyan(); 
+    rgblight_sethsv_noeeprom_cyan();
    rgblight_mode_noeeprom(1);
  }
 }
@@ -459,18 +442,18 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
        }
        return true; // Let QMK send the enter press/release events
    case RGB_LYR:  // This allows me to use underglow as layer indication, or as normal
-        if (record->event.pressed) { 
+        if (record->event.pressed) {
            user_config.rgb_layer_change ^= 1; // Toggles the status
            eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM
-            if (user_config.rgb_layer_change) { // if layer state indication is enabled, 
+            if (user_config.rgb_layer_change) { // if layer state indication is enabled,
                layer_state_set(layer_state);   // then immediately update the layer color
            }
        }
        return false; break;
    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference)
        if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled
-            if (user_config.rgb_layer_change) {        // only if this is enabled 
+            if (user_config.rgb_layer_change) {        // only if this is enabled
-                user_config.rgb_layer_change = false;  // disable it, and 
+                user_config.rgb_layer_change = false;  // disable it, and
                eeconfig_update_user(user_config.raw); // write the setings to EEPROM
            }
        }
@@ -483,7 +466,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. 
 ```c
-void eeconfig_init_user(void) {  // EEPROM is getting reset! 
+void eeconfig_init_user(void) {  // EEPROM is getting reset!
  user_config.raw = 0;
  user_config.rgb_layer_change = true; // We want this enabled by default
  eeconfig_update_user(user_config.raw); // Write default value to EEPROM now
@@ -506,14 +489,24 @@ The `val` is the value of the data that you want to write to EEPROM.  And the `e
 # Custom Tapping Term
-By default, the tapping term is defined globally, and is not configurable by key.  For most users, this is perfectly fine.  But in come cases, dual function keys would be greatly improved by different timeouts than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable `TAPPING_TERM`.
+By default, the tapping term and related options (such as `IGNORE_MOD_TAP_INTERRUPT`) are defined globally, and are not configurable by key.  For most users, this is perfectly fine.  But in some cases, dual function keys would be greatly improved by different timeout behaviors than `LT` keys, or because some keys may be easier to hold than others.  Instead of using custom key codes for each, this allows for per key configurable timeout behaviors.
+There are two configurable options to control per-key timeout behaviors:
-To enable this functionality, you need to add `#define TAPPING_TERM_PER_KEY` to your `config.h`, first.  
+- `TAPPING_TERM_PER_KEY`
+- `IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+You need to add `#define` lines to your `config.h` for each feature you want.
+```
+#define TAPPING_TERM_PER_KEY
+#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
+```
 ## Example `get_tapping_term` Implementation
-To change the `TAPPING TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file: 
+To change the `TAPPING_TERM` based on the keycode, you'd want to add something like the following to your `keymap.c` file:
 ```c
 uint16_t get_tapping_term(uint16_t keycode) {
@@ -528,6 +521,21 @@ uint16_t get_tapping_term(uint16_t keycode) {
 }
 ```
-### `get_tapping_term` Function Documentation
+## Example `get_ignore_mod_tap_interrupt` Implementation
+To change the `IGNORE_MOD_TAP_INTERRUPT` value based on the keycode, you'd want to add something like the following to your `keymap.c` file:
+```c
+bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return true;
+    default:
+      return false;
+  }
+}
+```
+## `get_tapping_term` / `get_ignore_mod_tap_interrupt` Function Documentation
-Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only a user level function is useful here, so no need to mark it as such.
+Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only user level functions are useful here, so no need to mark them as such.
diff --git a/docs/de/_summary.md b/docs/de/_summary.md
index 37768355f..f3ce806ba 100644
--- a/docs/de/_summary.md
+++ b/docs/de/_summary.md
@@ -111,7 +111,7 @@
  * [Support](de/support.md)
  * [Übersetzungen](de/translating.md)
-* QMK Internals (de/In Progress)
+* QMK Internals (In Progress)
  * [Defines](de/internals_defines.md)
  * [Input Callback Reg](de/internals_input_callback_reg.md)
  * [Midi Device](de/internals_midi_device.md)
diff --git a/docs/es/README.md b/docs/es/README.md
index 73e7a7097..d39b27800 100644
--- a/docs/es/README.md
+++ b/docs/es/README.md
@@ -19,7 +19,7 @@ De cualquier manera, también puedes descargarlo directamente en formatos ([zip]
 ## Cómo compilar
-Antes de poder compilar, necesitarás [instalar un entorno](getting_started_build_tools.md) para el desarrollo de AVR y/o ARM. Una vez hayas completado este paso, usarás el comando `make` para compilar un teclado y keymap con la siguiente notación:
+Antes de poder compilar, necesitarás [instalar un entorno](es/getting_started_build_tools.md) para el desarrollo de AVR y/o ARM. Una vez hayas completado este paso, usarás el comando `make` para compilar un teclado y keymap con la siguiente notación:
    make planck/rev4:default
@@ -29,4 +29,4 @@ Este ejemplo compilaría la revisión `rev4` del teclado `planck` con el keymap
 ## Cómo personalizar
-QMK tiene montones de [características](features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](keymap.md), y cambiando los [keycodes](keycodes.md).
+QMK tiene montones de [características](es/features.md) para explorar, y una buena cantidad de [documentación de referencia](http://docs.qmk.fm) en la que sumergirse. Se pueden sacar provecho de la mayoría de las características modificando tu [keymap](es/keymap.md), y cambiando los [keycodes](es/keycodes.md).
diff --git a/docs/es/_summary.md b/docs/es/_summary.md
index 684d7ab6c..03bf05ba8 100644
--- a/docs/es/_summary.md
+++ b/docs/es/_summary.md
@@ -1,121 +1,121 @@
-* [Guía completa para novatos](newbs.md)
+* [Guía completa para novatos](es/newbs.md)
-  * [Empezando](newbs_getting_started.md)
+  * [Empezando](es/newbs_getting_started.md)
-  * [Construyendo tu primer firmare](newbs_building_firmware.md)
+  * [Construyendo tu primer firmare](es/newbs_building_firmware.md)
-  * [Flasheando el firmware](newbs_flashing.md)
+  * [Flasheando el firmware](es/newbs_flashing.md)
-  * [Testeando y depurando ](newbs_testing_debugging.md)
+  * [Testeando y depurando ](es/newbs_testing_debugging.md)
-  * [Mejores práticas](newbs_best_practices.md)
+  * [Mejores práticas](es/newbs_best_practices.md)
-  * [Recursos de aprendizaje](newbs_learn_more_resources.md)
+  * [Recursos de aprendizaje](es/newbs_learn_more_resources.md)
-* [QMK Basics](README.md)
+* [QMK Basics](es/README.md)
-  * [Introducción a QMK](getting_started_introduction.md)
+  * [Introducción a QMK](es/getting_started_introduction.md)
-  * [QMK CLI](cli.md)
+  * [QMK CLI](es/cli.md)
-  * [Configuración de QMK CLI](cli_configuration.md)
+  * [Configuración de QMK CLI](es/cli_configuration.md)
-  * [Contribuyendo a QMK](contributing.md)
+  * [Contribuyendo a QMK](es/contributing.md)
-  * [Cómo usar Github](getting_started_github.md)
+  * [Cómo usar Github](es/getting_started_github.md)
-  * [Obtener ayuda](getting_started_getting_help.md)
+  * [Obtener ayuda](es/getting_started_getting_help.md)
-* [Cambios incompatibles](breaking_changes.md)
+* [Cambios incompatibles](es/breaking_changes.md)
-  * [30 Ago 2019](ChangeLog/20190830.md)
+  * [30 Ago 2019](es/ChangeLog/20190830.md)
-* [Preguntas frecuentes](faq.md)
+* [Preguntas frecuentes](es/faq.md)
-  * [General](faq_general.md)
+  * [General](es/faq_general.md)
-  * [Construir/Compilar QMK](faq_build.md)
+  * [Construir/Compilar QMK](es/faq_build.md)
-  * [Depurando/Encontrando problemas en QMK](faq_debug.md)
+  * [Depurando/Encontrando problemas en QMK](es/faq_debug.md)
-  * [Keymap](faq_keymap.md)
+  * [Keymap](es/faq_keymap.md)
-  * [Instalación de drivers con Zadig](driver_installation_zadig.md)
+  * [Instalación de drivers con Zadig](es/driver_installation_zadig.md)
 * Guías detalladas
-  * [Instalar herramientas construcción](getting_started_build_tools.md)
+  * [Instalar herramientas construcción](es/getting_started_build_tools.md)
-  * [Guía Vagrant](getting_started_vagrant.md)
+  * [Guía Vagrant](es/getting_started_vagrant.md)
-  * [Instrucciones de Construcción/Compilado](getting_started_make_guide.md)
+  * [Instrucciones de Construcción/Compilado](es/getting_started_make_guide.md)
-  * [Flasheando Firmware](flashing.md)
+  * [Flasheando Firmware](es/flashing.md)
-  * [Personalizando funcionalidad](custom_quantum_functions.md)
+  * [Personalizando funcionalidad](es/custom_quantum_functions.md)
-  * [Visión general del Keymap](keymap.md)
+  * [Visión general del Keymap](es/keymap.md)
-* [Hardware](hardware.md)
+* [Hardware](es/hardware.md)
-  * [Procesadores AVR](hardware_avr.md)
+  * [Procesadores AVR](es/hardware_avr.md)
-  * [Drivers](hardware_drivers.md)
+  * [Drivers](es/hardware_drivers.md)
 * Referencia
-  * [Pautas de teclados](hardware_keyboard_guidelines.md)
+  * [Pautas de teclados](es/hardware_keyboard_guidelines.md)
-  * [Opciones de configuración](config_options.md)
+  * [Opciones de configuración](es/config_options.md)
-  * [Keycodes](keycodes.md)
+  * [Keycodes](es/keycodes.md)
-  * [Convenciones de código - C](coding_conventions_c.md)
+  * [Convenciones de código - C](es/coding_conventions_c.md)
-  * [Convenciones de código - Python](coding_conventions_python.md)
+  * [Convenciones de código - Python](es/coding_conventions_python.md)
-  * [Mejores prácticas de documentación](documentation_best_practices.md)
+  * [Mejores prácticas de documentación](es/documentation_best_practices.md)
-  * [Plantillas de documentación](documentation_templates.md)
+  * [Plantillas de documentación](es/documentation_templates.md)
-  * [Glosario](reference_glossary.md)
+  * [Glosario](es/reference_glossary.md)
-  * [Tests unitarios](unit_testing.md)
+  * [Tests unitarios](es/unit_testing.md)
-  * [Funciones útiles](ref_functions.md)
+  * [Funciones útiles](es/ref_functions.md)
-  * [Sporte configurador](reference_configurator_support.md)
+  * [Sporte configurador](es/reference_configurator_support.md)
-  * [Formato info.json](reference_info_json.md)
+  * [Formato info.json](es/reference_info_json.md)
-  * [Desarrollo Python CLI](cli_development.md)
+  * [Desarrollo Python CLI](es/cli_development.md)
-* [Características](features.md)
+* [Características](es/features.md)
-  * [Keycodes Básicos](keycodes_basic.md)
+  * [Keycodes Básicos](es/keycodes_basic.md)
-  * [Teclas US ANSI Shifted](keycodes_us_ansi_shifted.md)
+  * [Teclas US ANSI Shifted](es/keycodes_us_ansi_shifted.md)
-  * [Keycodes Quantum](quantum_keycodes.md)
+  * [Keycodes Quantum](es/quantum_keycodes.md)
-  * [Keycodes Avanzados](feature_advanced_keycodes.md)
+  * [Keycodes Avanzados](es/feature_advanced_keycodes.md)
-  * [Audio](feature_audio.md)
+  * [Audio](es/feature_audio.md)
-  * [Auto Shift](feature_auto_shift.md)
+  * [Auto Shift](es/feature_auto_shift.md)
-  * [Retroiluminación](feature_backlight.md)
+  * [Retroiluminación](es/feature_backlight.md)
-  * [Bluetooth](feature_bluetooth.md)
+  * [Bluetooth](es/feature_bluetooth.md)
-  * [Bootmagic](feature_bootmagic.md)
+  * [Bootmagic](es/feature_bootmagic.md)
-  * [Combos](feature_combo.md)
+  * [Combos](es/feature_combo.md)
-  * [Comando](feature_command.md)
+  * [Comando](es/feature_command.md)
-  * [API Debounce](feature_debounce_type.md)
+  * [API Debounce](es/feature_debounce_type.md)
-  * [Switch DIP](feature_dip_switch.md)
+  * [Switch DIP](es/feature_dip_switch.md)
-  * [Macros Dinámicas](feature_dynamic_macros.md)
+  * [Macros Dinámicas](es/feature_dynamic_macros.md)
-  * [Encoders](feature_encoders.md)
+  * [Encoders](es/feature_encoders.md)
-  * [Grave Escape](feature_grave_esc.md)
+  * [Grave Escape](es/feature_grave_esc.md)
-  * [Feedback Háptico](feature_haptic_feedback.md)
+  * [Feedback Háptico](es/feature_haptic_feedback.md)
-  * [Controlador LCD HD44780](feature_hd44780.md)
+  * [Controlador LCD HD44780](es/feature_hd44780.md)
-  * [Key Lock](feature_key_lock.md)
+  * [Key Lock](es/feature_key_lock.md)
-  * [Layouts](feature_layouts.md)
+  * [Layouts](es/feature_layouts.md)
-  * [Tecla Leader](feature_leader_key.md)
+  * [Tecla Leader](es/feature_leader_key.md)
-  * [Matriz LED](feature_led_matrix.md)
+  * [Matriz LED](es/feature_led_matrix.md)
-  * [Macros](feature_macros.md)
+  * [Macros](es/feature_macros.md)
-  * [Teclas del ratón](feature_mouse_keys.md)
+  * [Teclas del ratón](es/feature_mouse_keys.md)
-  * [Driver OLED](feature_oled_driver.md)
+  * [Driver OLED](es/feature_oled_driver.md)
-  * [Teclas One Shot](feature_advanced_keycodes.md#one-shot-keys)
+  * [Teclas One Shot](es/feature_advanced_keycodes.md#one-shot-keys)
-  * [Dispositivo de apuntado](feature_pointing_device.md)
+  * [Dispositivo de apuntado](es/feature_pointing_device.md)
-  * [Ratón PS/2](feature_ps2_mouse.md)
+  * [Ratón PS/2](es/feature_ps2_mouse.md)
-  * [Iluminación RGB](feature_rgblight.md)
+  * [Iluminación RGB](es/feature_rgblight.md)
-  * [Matriz RGB](feature_rgb_matrix.md)
+  * [Matriz RGB](es/feature_rgb_matrix.md)
-  * [Cadete espacial](feature_space_cadet.md)
+  * [Cadete espacial](es/feature_space_cadet.md)
-  * [Teclado dividido](feature_split_keyboard.md)
+  * [Teclado dividido](es/feature_split_keyboard.md)
-  * [Stenografía](feature_stenography.md)
+  * [Stenografía](es/feature_stenography.md)
-  * [Swap Hands](feature_swap_hands.md)
+  * [Swap Hands](es/feature_swap_hands.md)
-  * [Tap Dance](feature_tap_dance.md)
+  * [Tap Dance](es/feature_tap_dance.md)
-  * [Terminal](feature_terminal.md)
+  * [Terminal](es/feature_terminal.md)
-  * [Impresora Térmica](feature_thermal_printer.md)
+  * [Impresora Térmica](es/feature_thermal_printer.md)
-  * [Unicode](feature_unicode.md)
+  * [Unicode](es/feature_unicode.md)
-  * [Userspace](feature_userspace.md)
+  * [Userspace](es/feature_userspace.md)
-  * [Velocikey](feature_velocikey.md)
+  * [Velocikey](es/feature_velocikey.md)
 * Para Makers y Modders
-  * [Guía de cableado a mano](hand_wire.md)
+  * [Guía de cableado a mano](es/hand_wire.md)
-  * [Guía de flasheado de ISP](isp_flashing_guide.md)
+  * [Guía de flasheado de ISP](es/isp_flashing_guide.md)
-  * [Guía de depuración de ARM](arm_debugging.md)
+  * [Guía de depuración de ARM](es/arm_debugging.md)
-  * [Driver I2C](i2c_driver.md)
+  * [Driver I2C](es/i2c_driver.md)
-  * [Controles GPIO](internals_gpio_control.md)
+  * [Controles GPIO](es/internals_gpio_control.md)
-  * [Conversión Proton C](proton_c_conversion.md)
+  * [Conversión Proton C](es/proton_c_conversion.md)
 * Para entender en profundidad
-  * [Cómo funcionan los teclados](how_keyboards_work.md)
+  * [Cómo funcionan los teclados](es/how_keyboards_work.md)
-  * [Entendiendo QMK](understanding_qmk.md)
+  * [Entendiendo QMK](es/understanding_qmk.md)
 * Otros temas
-  * [Usando Eclipse con QMK](other_eclipse.md)
+  * [Usando Eclipse con QMK](es/other_eclipse.md)
-  * [Usando VSCode con QMK](other_vscode.md)
+  * [Usando VSCode con QMK](es/other_vscode.md)
-  * [Soporte](support.md)
+  * [Soporte](es/support.md)
-  * [Cómo añadir traducciones](translating.md)
+  * [Cómo añadir traducciones](es/translating.md)
 * QMK Internals (En progreso)
-  * [Defines](internals_defines.md)
+  * [Defines](es/internals_defines.md)
-  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Input Callback Reg](es/internals_input_callback_reg.md)
-  * [Dispositivo Midi](internals_midi_device.md)
+  * [Dispositivo Midi](es/internals_midi_device.md)
-  * [Proceso de configuración de un dispositivo Midi](internals_midi_device_setup_process.md)
+  * [Proceso de configuración de un dispositivo Midi](es/internals_midi_device_setup_process.md)
-  * [Utilidad Midi](internals_midi_util.md)
+  * [Utilidad Midi](es/internals_midi_util.md)
-  * [Funciones Send](internals_send_functions.md)
+  * [Funciones Send](es/internals_send_functions.md)
-  * [Herramientas Sysex](internals_sysex_tools.md)
+  * [Herramientas Sysex](es/internals_sysex_tools.md)
diff --git a/docs/faq_build.md b/docs/faq_build.md
index f11cb76aa..70a16afea 100644
--- a/docs/faq_build.md
+++ b/docs/faq_build.md
@@ -47,7 +47,7 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
 ```
-**/etc/udev/rules.d/55-catalina.rules:**
+**/etc/udev/rules.d/55-caterina.rules:**
 ```
 # ModemManager should ignore the following devices
 ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
@@ -69,6 +69,12 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="066
 SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
 ```
+**/etc/udev/rules.d/57-bootloadhid.rules:**
+```
+# bootloadHID
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
+```
 ### Serial device is not detected in bootloader mode on Linux
 Make sure your kernel has appropriate support for your device. If your device uses USB ACM, such as
 Pro Micro (Atmega32u4), make sure to include `CONFIG_USB_ACM=y`. Other devices may require `USB_SERIAL` and any of its sub options.
@@ -81,10 +87,6 @@ Re-running the QMK installation script (`./util/qmk_install.sh` from the `qmk_fi
 If that doesn't work, then you may need to download and run Zadig. See [Bootloader Driver Installation with Zadig](driver_installation_zadig.md) for more detailed information.
-## WINAVR is Obsolete
-It is no longer recommended and may cause some problem.
-See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
 ## USB VID and PID
 You can use any ID you want with editing `config.h`. Using any presumably unused ID will be no problem in fact except for very low chance of collision with other product.
@@ -97,29 +99,6 @@ You can buy a really unique VID:PID here. I don't think you need this for person
 - http://www.obdev.at/products/vusb/license.html
 - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
-## Cortex: `cstddef: No such file or directory`
-GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA.
-https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
-https://github.com/tmk/tmk_keyboard/issues/212
-https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
-https://developer.mbed.org/forum/mbed/topic/5205/
-## `clock_prescale_set` and `clock_div_1` Not Available
-Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.
-```
-Compiling C: ../../tmk_core/protocol/lufa/lufa.c
-avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8  -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d  ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o
-../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu':
-../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set'
-../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function)
-../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once
-../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.)
-make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
-```
 ## BOOTLOADER_SIZE for AVR
 Note that Teensy2.0++ bootloader size is 2048byte. Some Makefiles may have wrong comment.
@@ -140,24 +119,29 @@ The solution is to remove and reinstall all affected modules.
 ```
 brew rm avr-gcc
+brew rm avr-gcc@8
 brew rm dfu-programmer
 brew rm dfu-util
 brew rm gcc-arm-none-eabi
+brew rm arm-gcc-bin@8
 brew rm avrdude
-brew install avr-gcc
+brew install avr-gcc@8
 brew install dfu-programmer
 brew install dfu-util
-brew install gcc-arm-none-eabi
+brew install arm-gcc-bin@8
 brew install avrdude
+brew link --force avr-gcc@8
+brew link --force arm-gcc-bin@8
 ```
-### avr-gcc 8.1 and LUFA
+### `avr-gcc` and LUFA
-If you updated your avr-gcc to above 7 you may see errors involving LUFA. For example:
+If you updated your `avr-gcc` and you see errors involving LUFA, for example:
 `lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
-For now, you need to rollback avr-gcc to 7 in brew.
+For now, you need to rollback `avr-gcc` to 8 in Homebrew.
 ```
 brew uninstall --force avr-gcc
diff --git a/docs/faq_debug.md b/docs/faq_debug.md
index 1e0cdc82b..6c66defbd 100644
--- a/docs/faq_debug.md
+++ b/docs/faq_debug.md
@@ -112,56 +112,6 @@ In C `1` means one of [int] type which is [16 bit] in case of AVR so you can't s
 http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
-## Bootloader Jump Doesn't Work
-Properly configure bootloader size in **Makefile**. With wrong section size bootloader won't probably start with **Magic command** and **Boot Magic**.
-```
-# Size of Bootloaders in bytes:
-#   Atmel DFU loader(ATmega32U4)   4096
-#   Atmel DFU loader(AT90USB128)   8192
-#   LUFA bootloader(ATmega32U4)    4096
-#   Arduino Caterina(ATmega32U4)   4096
-#   USBaspLoader(ATmega***)        2048
-#   Teensy   halfKay(ATmega32U4)   512
-#   Teensy++ halfKay(AT90USB128)   2048
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
-```
-AVR Boot section size are defined by setting **BOOTSZ** fuse in fact. Consult with your MCU datasheet.
-Note that **Word**(2 bytes) size and address are used in datasheet while TMK uses **Byte**.
-AVR Boot section is located at end of Flash memory like the followings.
-```
-byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-4KB               |               | 128KB-8KB
-0x6000   +---------------+               0x1E000  +---------------+
-         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-512B              |               | 128KB-2KB
-0x7E00   +---------------+               0x1FC00  +---------------+
-         |  Bootloader   | 512B                   |  Bootloader   | 2KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-```
-And see this discussion for further reference.
-https://github.com/tmk/tmk_keyboard/issues/179
-If you are using a TeensyUSB, there is a [known bug](https://github.com/qmk/qmk_firmware/issues/164) in which the hardware reset button prevents the RESET key from working. Unplugging the keyboard and plugging it back in should resolve the problem.
 ## Special Extra Key Doesn't Work (System, Audio Control Keys)
 You need to define `EXTRAKEY_ENABLE` in `rules.mk` to use them in QMK.
@@ -194,24 +144,6 @@ If you would like to keep JTAG enabled, just add the following to your `config.h
 #define NO_JTAG_DISABLE
 ```
-## Adding LED Indicators of Lock Keys
-You need your own LED indicators for CapsLock, ScrollLock and NumLock? See this post.
-http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
-## Program Arduino Micro/Leonardo
-Push reset button and then run command like this within 8 seconds.
-```
-avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
-```
-Device name will vary depending on your system.
-http://arduino.cc/en/Main/ArduinoBoardMicro
-https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
 ## USB 3 Compatibility
 I heard some people have a problem with USB 3 port, try USB 2 port.
diff --git a/docs/faq_keymap.md b/docs/faq_keymap.md
index 84d8548d4..2d00e8bef 100644
--- a/docs/faq_keymap.md
+++ b/docs/faq_keymap.md
@@ -67,24 +67,8 @@ After enabling this feature use keycodes `KC_LCAP`, `KC_LNUM` and `KC_LSCR` in y
 Old vintage mechanical keyboards occasionally have lock switches but modern ones don't have. ***You don't need this feature in most case and just use keycodes `KC_CAPS`, `KC_NLCK` and `KC_SLCK`.***
 ## Input Special Characters Other Than ASCII like Cédille 'Ç'
-NO UNIVERSAL METHOD TO INPUT THOSE WORKS OVER ALL SYSTEMS. You have to define **MACRO** in way specific to your OS or layout.
-See this post for example **MACRO** code.
+See the [Unicode](feature_unicode.md) feature.
-http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
-On **Windows** you can use `AltGr` key or **Alt code**.
-* http://en.wikipedia.org/wiki/AltGr_key
-* http://en.wikipedia.org/wiki/Alt_code
-On **Mac** OS defines `Option` key combinations.
-* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
-On **Xorg** you can use `compose` key, instead.
-* http://en.wikipedia.org/wiki/Compose_key
-And see this for **Unicode** input.
-* http://en.wikipedia.org/wiki/Unicode_input
 ## `Fn` Key on macOS
@@ -130,51 +114,6 @@ https://github.com/tekezo/Karabiner/issues/403
 See the [Grave Escape](feature_grave_esc.md) feature.
-## Arrow on Right Modifier Keys with Dual-Role
-This turns right modifier keys into arrow keys when the keys are tapped while still modifiers when the keys are hold. In TMK the dual-role function is dubbed **TAP**.
-```
-#include "keymap_common.h"
-/* Arrow keys on right modifier keys with TMK dual role feature
- *
- *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
- *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
- */
-const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-    /* 0: qwerty */
-    [0] = LAYOUT( \
-        ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
-        TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
-        LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
-        LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
-        FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
-    [1] = LAYOUT( \
-        GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
-        TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
-};
-const uint16_t PROGMEM fn_actions[] = {
-    [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
-    [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
-    [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
-    [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
-    [4] = ACTION_LAYER_MOMENTARY(1),
-    [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
-    [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
-    [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
-    [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
-};
-```
-Dual-role key: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 ## Eject on Mac OSX
 `KC_EJCT` keycode works on OSX. https://github.com/tmk/tmk_keyboard/issues/250
 It seems Windows 10 ignores the code and Linux/Xorg recognizes but has no mapping by default.
diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md
index e73258d51..ebb24dc99 100644
--- a/docs/feature_advanced_keycodes.md
+++ b/docs/feature_advanced_keycodes.md
@@ -155,7 +155,7 @@ You can control the behavior of one shot keys by defining these in `config.h`:
 Sometimes, you want to activate a one-shot key as part of a macro or tap dance routine.  
-For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `set_oneshot_layer(ONESHOT_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
+For one shot layers, you need to call `set_oneshot_layer(LAYER, ONESHOT_START)` on key down, and `clear_oneshot_layer_state(ONESHOT_OTHER_KEY_PRESSED)` on key up. If you want to cancel the oneshot, call `reset_oneshot_layer()`.
 For one shot mods, you need to call `set_oneshot_mods(MOD)` to set it, or `clear_oneshot_mods()` to cancel it.
@@ -291,6 +291,25 @@ Normally, this would send `X` (`SHIFT`+`x`). With `Ignore Mod Tap Interrupt` ena
 ?> If you have `Permissive Hold` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
+For more granular control of this feature, you can add the following to your `config.h`:
+```c
+#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY
+```
+You can then add the following function to your keymap:
+```c
+bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return true;
+    default:
+      return false;
+  }
+}
+```
 ## Tapping Force Hold
 To enable `tapping force hold`, add the following to your `config.h`: 
@@ -315,6 +334,25 @@ With `TAPPING_FORCE_HOLD`, the second press will be interpreted as a Shift, allo
 !> `TAPPING_FORCE_HOLD` will break anything that uses tapping toggles (Such as the `TT` layer keycode, and the One Shot Tapping Toggle).
+For more granular control of this feature, you can add the following to your `config.h`:
+```c
+#define TAPPING_FORCE_HOLD_PER_KEY
+```
+You can then add the following function to your keymap:
+```c
+bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case LT(1, KC_BSPC):
+      return true;
+    default:
+      return false;
+  }
+}
+```
 ## Retro Tapping
 To enable `retro tapping`, add the following to your `config.h`: 
diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md
index 71f375594..22abaa60a 100644
--- a/docs/feature_backlight.md
+++ b/docs/feature_backlight.md
@@ -6,16 +6,14 @@ QMK is able to control the brightness of these LEDs by switching them on and off
 The MCU can only supply so much current to its GPIO pins. Instead of powering the backlight directly from the MCU, the backlight pin is connected to a transistor or MOSFET that switches the power to the LEDs.
-## Driver configuration
+## Feature Configuration
 Most keyboards have backlighting enabled by default if they support it, but if it is not working for you, check that your `rules.mk` includes the following:
 ```makefile
-BACKLIGHT_ENABLE = software # Valid driver values are 'yes,software,no'
+BACKLIGHT_ENABLE = yes
 ```
-See below for help on individual drivers.
 ## Keycodes
 Once enabled the following keycodes below can be used to change the backlight level.
@@ -51,6 +49,16 @@ Once enabled the following keycodes below can be used to change the backlight le
 |`breathing_enable()`  |Turns on backlight breathing           |
 |`breathing_disable()` |Turns off backlight breathing          |
+## Driver Configuration
+To select which driver to use, configure your `rules.mk` with the following:
+```makefile
+BACKLIGHT_DRIVER = software # Valid driver values are 'pwm,software,no'
+```
+See below for help on individual drivers.
 ## Common Driver Configuration
 To change the behavior of the backlighting, `#define` these in your `config.h`:
@@ -72,9 +80,9 @@ This functionality is configured at the keyboard level with the `BACKLIGHT_ON_ST
 ## AVR driver
-On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. To enable it, add this to your rules.mk:
+On AVR boards, the default driver currently sniffs the configuration to pick the best scenario. The driver is configured by default, however the equivalent setting within rules.mk would be:
 ```makefile
-BACKLIGHT_ENABLE = yes
+BACKLIGHT_DRIVER = pwm
 ```
 ### Caveats
@@ -150,9 +158,9 @@ The breathing effect is the same as in the hardware PWM implementation.
 ## ARM Driver
-While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. To enable it, add this to your rules.mk:
+While still in its early stages, ARM backlight support aims to eventually have feature parity with AVR. The driver is configured by default, however the equivalent setting within rules.mk would be:
 ```makefile
-BACKLIGHT_ENABLE = yes
+BACKLIGHT_DRIVER = pwm
 ```
 ### Caveats
@@ -176,7 +184,7 @@ To change the behavior of the backlighting, `#define` these in your `config.h`:
 Emulation of PWM while running other keyboard tasks, it offers maximum hardware compatibility without extra platform configuration. The tradeoff is the backlight might jitter when the keyboard is busy. To enable, add this to your rules.mk:
 ```makefile
-BACKLIGHT_ENABLE = software
+BACKLIGHT_DRIVER = software
 ```
 ### Software PWM Configuration
@@ -200,3 +208,29 @@ To activate multiple backlight pins, you need to add something like this to your
 #undef BACKLIGHT_PIN
 #define BACKLIGHT_PINS { F5, B2 }
 ```
+## Custom Driver
+To enable, add this to your rules.mk:
+```makefile
+BACKLIGHT_DRIVER = custom
+```
+When implementing the custom driver API, the provided keyboard hooks are as follows:
+```c
+void backlight_init_ports(void) {
+    // Optional - Run on startup
+    //          - usually you want to configure pins here
+}
+void backlight_set(uint8_t level) {
+    // Optional - Run on level change
+    //          - usually you want to respond to the new value
+}
+void backlight_task(void) {
+    // Optional - Run periodically
+    //          - long running actions here can cause performance issues
+}
+```
diff --git a/docs/feature_bootmagic.md b/docs/feature_bootmagic.md
index ed00d5129..a19b5e548 100644
--- a/docs/feature_bootmagic.md
+++ b/docs/feature_bootmagic.md
@@ -56,37 +56,37 @@ Hold down the Bootmagic key (Space by default) and the desired hotkey while plug
 ## Keycodes
-|Keycode                           |Aliases  |Description                               |
+|Key                               |Aliases  |Description                                                               |
-|----------------------------------|---------|------------------------------------------|
+|----------------------------------|---------|--------------------------------------------------------------------------|
-|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Left Control           |
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |`CL_SWAP`|Swap Caps Lock and Left Control                                           |
-|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Left Control   |
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |`CL_NORM`|Unswap Caps Lock and Left Control                                         |
-|`MAGIC_HOST_NKRO`                 |         |Force N-Key Rollover (NKRO) on            |
+|`MAGIC_CAPSLOCK_TO_CONTROL`       |`CL_CTRL`|Treat Caps Lock as Control                                                |
-|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                            |
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |`CL_CAPS`|Stop treating Caps Lock as Control                                        |
-|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                       |
+|`MAGIC_SWAP_LCTL_LGUI`            |`LCG_SWP`|Swap Left Control and GUI                                                 |
-|`MAGIC_NO_GUI`                    |         |Disable the GUI keys (useful when gaming) |
+|`MAGIC_UNSWAP_LCTL_LGUI`          |`LCG_NRM`|Unswap Left Control and GUI                                               |
-|`MAGIC_UNNO_GUI`                  |         |Enable the GUI keys                       |
+|`MAGIC_SWAP_RCTL_RGUI`            |`RCG_SWP`|Swap Right Control and GUI                                                |
-|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides (for macOS)|
+|`MAGIC_UNSWAP_RCTL_RGUI`          |`RCG_NRM`|Unswap Right Control and GUI                                              |
-|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI                        |
+|`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Control and GUI on both sides                                        |
-|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap                   |
+|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Control and GUI on both sides                                      |
-|`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)|
+|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Control and GUI swap on both sides                                 |
-|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Ctrl and GUI                       |
+|`MAGIC_SWAP_LALT_LGUI`            |`LAG_SWP`|Swap Left Alt and GUI                                                     |
-|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Ctrl and GUI swap                  |
+|`MAGIC_UNSWAP_LALT_LGUI`          |`LAG_NRM`|Unswap Left Alt and GUI                                                   |
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                    |
+|`MAGIC_SWAP_RALT_RGUI`            |`RAG_SWP`|Swap Right Alt and GUI                                                    |
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                  |
+|`MAGIC_UNSWAP_RALT_RGUI`          |`RAG_NRM`|Unswap Right Alt and GUI                                                  |
-|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Left Control and Caps Lock           |
+|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides                                            |
-|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Left Control and Caps Lock         |
+|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides                                          |
-|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape        |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides                                     |
-|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape      |
+|`MAGIC_NO_GUI`                    |`GUI_OFF`|Disable the GUI keys                                                      |
-|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and Left GUI                |
+|`MAGIC_UNNO_GUI`                  |`GUI_ON` |Enable the GUI keys                                                       |
-|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and Left GUI              |
+|`MAGIC_SWAP_GRAVE_ESC`            |`GE_SWAP`|Swap <code>&#96;</code> and Escape                                        |
-|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and Right GUI              |
+|`MAGIC_UNSWAP_GRAVE_ESC`          |`GE_NORM`|Unswap <code>&#96;</code> and Escape                                      |
-|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and Right GUI            |
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |`BS_SWAP`|Swap `\` and Backspace                                                    |
-|`MAGIC_SWAP_LCTL_LGUI`            |         |Swap Left Control and Left GUI            |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace                                                  |
-|`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and Left GUI          |
+|`MAGIC_HOST_NKRO`                 |`NK_ON`  |Enable N-key rollover                                                     |
-|`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and Right GUI          |
+|`MAGIC_UNHOST_NKRO`               |`NK_OFF` |Disable N-key rollover                                                    |
-|`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and Right GUI        |
+|`MAGIC_TOGGLE_NKRO`               |`NK_TOGG`|Toggle N-key rollover                                                     |
-|`MAGIC_EE_HANDS_LEFT`             |         |Set "Left Hand" for EE_HANDS handedness   |
+|`MAGIC_EE_HANDS_LEFT`             |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
-|`MAGIC_EE_HANDS_RIGHT`            |         |Set "Right Hand" for EE_HANDS handedness  |
+|`MAGIC_EE_HANDS_RIGHT`            |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
 ## Configuration
diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md
index 227363322..ff7337a51 100644
--- a/docs/feature_haptic_feedback.md
+++ b/docs/feature_haptic_feedback.md
@@ -2,7 +2,7 @@
 ## Haptic feedback rules.mk options
-The following options are currently available for haptic feedback in `rule.mk`:
+The following options are currently available for haptic feedback in `rules.mk`:
 `HAPTIC_ENABLE += DRV2605L`
diff --git a/docs/feature_leader_key.md b/docs/feature_leader_key.md
index 82cf78901..22370bf23 100644
--- a/docs/feature_leader_key.md
+++ b/docs/feature_leader_key.md
@@ -22,10 +22,10 @@ void matrix_scan_user(void) {
      SEND_STRING("QMK is awesome.");
    }
    SEQ_TWO_KEYS(KC_D, KC_D) {
-      SEND_STRING(SS_LCTRL("a")SS_LCTRL("c"));
+      SEND_STRING(SS_LCTL("a") SS_LCTL("c"));
    }
    SEQ_THREE_KEYS(KC_D, KC_D, KC_S) {
-      SEND_STRING("https://start.duckduckgo.com"SS_TAP(X_ENTER));
+      SEND_STRING("https://start.duckduckgo.com\n");
    }
    SEQ_TWO_KEYS(KC_A, KC_S) {
      register_code(KC_LGUI);
@@ -115,11 +115,11 @@ void matrix_scan_user(void) {
    SEQ_ONE_KEY(KC_E) {
      // Anything you can do in a macro.
-      SEND_STRING(SS_LCTRL(SS_LSFT("t")));
+      SEND_STRING(SS_LCTL(SS_LSFT("t")));
      did_leader_succeed = true;
    } else 
    SEQ_TWO_KEYS(KC_E, KC_D) {
-      SEND_STRING(SS_LGUI("r")"cmd"SS_TAP(KC_ENTER)SS_LCTRL("c"));
+      SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
      did_leader_succeed = true;
    }
    leader_end();
diff --git a/docs/feature_macros.md b/docs/feature_macros.md
index d81c3c655..c13ae8206 100644
--- a/docs/feature_macros.md
+++ b/docs/feature_macros.md
@@ -67,14 +67,14 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    case QMKURL:
      if (record->event.pressed) {
        // when keycode QMKURL is pressed
-        SEND_STRING("https://qmk.fm/" SS_TAP(X_ENTER));
+        SEND_STRING("https://qmk.fm/\n");
      } else {
        // when keycode QMKURL is released
      }
      break;
    case MY_OTHER_MACRO:
      if (record->event.pressed) {
-                SEND_STRING(SS_LCTRL("ac")); // selects all and copies
+                SEND_STRING(SS_LCTL("ac")); // selects all and copies
      }
      break;
  }
@@ -109,18 +109,21 @@ Which would send "VE" followed by a `KC_HOME` tap, and "LO" (spelling "LOVE" if
 There's also a couple of mod shortcuts you can use:
-* `SS_LCTRL(string)`
+* `SS_LCTL(string)`
-* `SS_LGUI(string)`
-* `SS_LALT(string)`
 * `SS_LSFT(string)`
-* `SS_RALT(string)`
+* `SS_LALT(string)`
+* `SS_LGUI(string)`, `SS_LCMD(string)` or `SS_LWIN(string)`
+* `SS_RCTL(string)`
+* `SS_RSFT(string)`
+* `SS_RALT(string)` or `SS_ALGR(string)`
+* `SS_RGUI(string)`, `SS_RCMD(string)` or `SS_RWIN(string)`
 These press the respective modifier, send the supplied string and then release the modifier.
 They can be used like this:
-    SEND_STRING(SS_LCTRL("a"));
+    SEND_STRING(SS_LCTL("a"));
-Which would send LCTRL+a (LCTRL down, a, LCTRL up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes.
+Which would send Left Control+`a` (Left Control down, `a`, Left Control up) - notice that they take strings (eg `"k"`), and not the `X_K` keycodes.
 ### Alternative Keymaps
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index 3e69361fb..23082ef2a 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -173,16 +173,20 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
 All RGB keycodes are currently shared with the RGBLIGHT system:
-* `RGB_TOG` - toggle
+|Key                |Aliases   |Description                                                                           |
-* `RGB_MOD` - cycle through modes
+|-------------------|----------|--------------------------------------------------------------------------------------|
-* `RGB_HUI` - increase hue
+|`RGB_TOG`          |          |Toggle RGB lighting on or off                                                         |
-* `RGB_HUD` - decrease hue
+|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held                             |
-* `RGB_SAI` - increase saturation
+|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held                  |
-* `RGB_SAD` - decrease saturation
+|`RGB_HUI`          |          |Increase hue, decrease hue when Shift is held                                         |
-* `RGB_VAI` - increase value
+|`RGB_HUD`          |          |Decrease hue, increase hue when Shift is held                                         |
-* `RGB_VAD` - decrease value
+|`RGB_SAI`          |          |Increase saturation, decrease saturation when Shift is held                           |
-* `RGB_SPI` - increase speed effect (no EEPROM support)
+|`RGB_SAD`          |          |Decrease saturation, increase saturation when Shift is held                           |
-* `RGB_SPD` - decrease speed effect (no EEPROM support)
+|`RGB_VAI`          |          |Increase value (brightness), decrease value when Shift is held                        |
+|`RGB_VAD`          |          |Decrease value (brightness), increase value when Shift is held                        |
+|`RGB_SPI`          |          |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
+|`RGB_SPD`          |          |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
 * `RGB_MODE_*` keycodes will generally work, but are not currently mapped to the correct effects for the RGB Matrix system
 ## RGB Matrix Effects
@@ -195,6 +199,7 @@ enum rgb_matrix_effects {
    RGB_MATRIX_SOLID_COLOR = 1,     // Static single hue, no speed support
    RGB_MATRIX_ALPHAS_MODS,         // Static dual hue, speed is hue for secondary hue
    RGB_MATRIX_GRADIENT_UP_DOWN,    // Static gradient top to bottom, speed controls how much gradient changes
+    RGB_MATRIX_GRADIENT_LEFT_RIGHT,    // Static gradient left to right, speed controls how much gradient changes
    RGB_MATRIX_BREATHING,           // Single hue brightness cycling animation
    RGB_MATRIX_BAND_SAT,        // Single hue band fading saturation scrolling left to right
    RGB_MATRIX_BAND_VAL,        // Single hue band fading brightness scrolling left to right
@@ -282,7 +287,7 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 ## Custom RGB Matrix Effects
-By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
+By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rules.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files.
 To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this:
@@ -375,6 +380,10 @@ These are defined in [`rgblight_list.h`](https://github.com/qmk/qmk_firmware/blo
 #define RGB_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness)
 #define RGB_MATRIX_MAXIMUM_BRIGHTNESS 200 // limits maximum brightness of LEDs to 200 out of 255. If not defined maximum brightness is set to 255
 #define RGB_MATRIX_STARTUP_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set
+#define RGB_MATRIX_STARTUP_HUE 0 // Sets the default hue value, if none has been set
+#define RGB_MATRIX_STARTUP_SAT 255 // Sets the default saturation value, if none has been set
+#define RGB_MATRIX_STARTUP_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set
+#define RGB_MATRIX_STARTUP_SPD 127 // Sets the default animation speed, if none has been set
 ```
 ## EEPROM storage
diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md
index 2e9610163..69a6aaaed 100644
--- a/docs/feature_rgblight.md
+++ b/docs/feature_rgblight.md
@@ -48,12 +48,12 @@ Changing the **Value** sets the overall brightness.<br>
 |`RGB_TOG`          |          |Toggle RGB lighting on or off                                       |
 |`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held           |
 |`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held|
-|`RGB_HUI`          |          |Increase hue                                                        |
+|`RGB_HUI`          |          |Increase hue, decrease hue when Shift is held                       |
-|`RGB_HUD`          |          |Decrease hue                                                        |
+|`RGB_HUD`          |          |Decrease hue, increase hue when Shift is held                       |
-|`RGB_SAI`          |          |Increase saturation                                                 |
+|`RGB_SAI`          |          |Increase saturation, decrease saturation when Shift is held         |
-|`RGB_SAD`          |          |Decrease saturation                                                 |
+|`RGB_SAD`          |          |Decrease saturation, increase saturation when Shift is held         |
-|`RGB_VAI`          |          |Increase value (brightness)                                         |
+|`RGB_VAI`          |          |Increase value (brightness), decrease value when Shift is held      |
-|`RGB_VAD`          |          |Decrease value (brightness)                                         |
+|`RGB_VAD`          |          |Decrease value (brightness), increase value when Shift is held      |
 |`RGB_MODE_PLAIN`   |`RGB_M_P `|Static (no animation) mode                                          |
 |`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode                                            |
 |`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode                                              |
diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md
index e162d423c..a2657c1f6 100644
--- a/docs/feature_userspace.md
+++ b/docs/feature_userspace.md
@@ -208,15 +208,15 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
            clear_mods(); clear_oneshot_mods();
            SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP);
    #ifndef FLASH_BOOTLOADER
-            if ( (temp_mod | temp_osm) & MOD_MASK_SHIFT ) 
+            if ((temp_mod | temp_osm) & MOD_MASK_SHIFT)
    #endif
-            { // 
+            {
                SEND_STRING(":flash");
            }
-            if ( (temp_mod | temp_osm) & MOD_MASK_CTRL) { 
+            if ((temp_mod | temp_osm) & MOD_MASK_CTRL) {
-                SEND_STRING(" -j8 --output-sync"); 
+                SEND_STRING(" -j8 --output-sync");
            }
-            SEND_STRING(SS_TAP(X_ENTER));
+            tap_code(KC_ENT);
            set_mods(temp_mod);
        }
        break;
diff --git a/docs/flashing_bootloadhid.md b/docs/flashing_bootloadhid.md
index c51d8ce4b..731d92772 100644
--- a/docs/flashing_bootloadhid.md
+++ b/docs/flashing_bootloadhid.md
@@ -13,7 +13,7 @@ General flashing sequence:
 ## bootloadHID Flashing Target
-Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed.
+?> Using the QMK installation script, detailed [here](newbs_getting_started.md), the required bootloadHID tools should be automatically installed.
 To flash via the command line, use the target `:bootloadHID` by executing the following command:
diff --git a/docs/fr-fr/README.md b/docs/fr-fr/README.md
index d3591554b..4527ec4b4 100644
--- a/docs/fr-fr/README.md
+++ b/docs/fr-fr/README.md
@@ -19,7 +19,7 @@ Sinon, vous pouvez aussi le télécharger directement en ([zip](https://github.c
 ## Comment le compiler
-Avant d'être prêt à compiler vous allez devoir [installer un environnement](getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type :
+Avant d'être prêt à compiler vous allez devoir [installer un environnement](fr-fr/getting_started_build_tools.md) pour les développements AVR et/ou ARM. Une fois ceci fait, vous pourrez utiliser la commande `make` pour compiler le clavier et la disposition avec une commande de ce type :
    make planck/rev4:default
@@ -29,4 +29,4 @@ Cette commande compilera la révision `rev4` du clavier `planck` avec la disposi
 ## Comment le personnaliser
-QMK a beaucoup de [fonctionnalités](features.md) à explorer, et [une documentation](http://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](keymap.md) (keymaps) et de changer [les codes de caractères](keycodes.md) (keycodes).
+QMK a beaucoup de [fonctionnalités](fr-fr/features.md) à explorer, et [une documentation](http://docs.qmk.fm) très abondante que vous pourrez parcourir. La plupart des fonctionnalités vous permettrons de modifier vos [dispositions](fr-fr/keymap.md) (keymaps) et de changer [les codes de caractères](fr-fr/keycodes.md) (keycodes).
diff --git a/docs/fr-fr/_summary.md b/docs/fr-fr/_summary.md
index eef486176..38e3abe7c 100644
--- a/docs/fr-fr/_summary.md
+++ b/docs/fr-fr/_summary.md
@@ -29,97 +29,97 @@
 **En Anglais**
 * Guides détaillés
-  * [Installation des outils de compilation](getting_started_build_tools.md)
+  * [Installation des outils de compilation](fr-fr/getting_started_build_tools.md)
-  * [Guide Vagrant](getting_started_vagrant.md)
+  * [Guide Vagrant](fr-fr/getting_started_vagrant.md)
-  * [Commandes de compilations](getting_started_make_guide.md)
+  * [Commandes de compilations](fr-fr/getting_started_make_guide.md)
  * [Flasher les firmwares](fr-fr/flashing.md)
-  * [Personnaliser les fonctionnalités](custom_quantum_functions.md)
+  * [Personnaliser les fonctionnalités](fr-fr/custom_quantum_functions.md)
-  * [Aperçu des fonctionnalités des dispositions](keymap.md)
+  * [Aperçu des fonctionnalités des dispositions](fr-fr/keymap.md)
-* [Hardware](hardware.md)
+* [Hardware](fr-fr/hardware.md)
-  * [Processeurs AVR](hardware_avr.md)
+  * [Processeurs AVR](fr-fr/hardware_avr.md)
-  * [Pilotes / Drivers](hardware_drivers.md)
+  * [Pilotes / Drivers](fr-fr/hardware_drivers.md)
 * Réferences
-  * [Lignes de conduite des claviers](hardware_keyboard_guidelines.md)
+  * [Lignes de conduite des claviers](fr-fr/hardware_keyboard_guidelines.md)
-  * [Options de configurations](config_options.md)
+  * [Options de configurations](fr-fr/config_options.md)
-  * [Keycodes / Codes des caractères](keycodes.md)
+  * [Keycodes / Codes des caractères](fr-fr/keycodes.md)
-  * [Conventions de codage - C](coding_conventions_c.md)
+  * [Conventions de codage - C](fr-fr/coding_conventions_c.md)
-  * [Conventions de codage - Python](coding_conventions_python.md)
+  * [Conventions de codage - Python](fr-fr/coding_conventions_python.md)
-  * [Meilleurs pratiques sur la documentation](documentation_best_practices.md)
+  * [Meilleurs pratiques sur la documentation](fr-fr/documentation_best_practices.md)
-  * [Modèles de documentation](documentation_templates.md)
+  * [Modèles de documentation](fr-fr/documentation_templates.md)
-  * [Glossaire](reference_glossary.md)
+  * [Glossaire](fr-fr/reference_glossary.md)
-  * [Tests unitaires](unit_testing.md)
+  * [Tests unitaires](fr-fr/unit_testing.md)
-  * [Fonctions utiles](ref_functions.md)
+  * [Fonctions utiles](fr-fr/ref_functions.md)
-  * [Support de configuration](reference_configurator_support.md)
+  * [Support de configuration](fr-fr/reference_configurator_support.md)
-  * [Format du fichier info.json](reference_info_json.md)
+  * [Format du fichier info.json](fr-fr/reference_info_json.md)
-  * [Développer la CLI en Python](cli_development.md)
+  * [Développer la CLI en Python](fr-fr/cli_development.md)
-* [Fonctionnalités](features.md)
+* [Fonctionnalités](fr-fr/features.md)
-  * [Keycodes basiques](keycodes_basic.md)
+  * [Keycodes basiques](fr-fr/keycodes_basic.md)
-  * [Touches utilisées avec Shift (US ANSI)](keycodes_us_ansi_shifted.md)
+  * [Touches utilisées avec Shift (US ANSI)](fr-fr/keycodes_us_ansi_shifted.md)
-  * [Keycodes quantiques](quantum_keycodes.md)
+  * [Keycodes quantiques](fr-fr/quantum_keycodes.md)
-  * [Keycodes avancés](feature_advanced_keycodes.md)
+  * [Keycodes avancés](fr-fr/feature_advanced_keycodes.md)
-  * [Fonctionnalités audio](feature_audio.md)
+  * [Fonctionnalités audio](fr-fr/feature_audio.md)
-  * [Majuscule automatique](feature_auto_shift.md)
+  * [Majuscule automatique](fr-fr/feature_auto_shift.md)
-  * [Rétroéclairage](feature_backlight.md)
+  * [Rétroéclairage](fr-fr/feature_backlight.md)
-  * [Bluetooth](feature_bluetooth.md)
+  * [Bluetooth](fr-fr/feature_bluetooth.md)
-  * [Bootmagic](feature_bootmagic.md)
+  * [Bootmagic](fr-fr/feature_bootmagic.md)
-  * [Combos](feature_combo.md)
+  * [Combos](fr-fr/feature_combo.md)
-  * [Commande](feature_command.md)
+  * [Commande](fr-fr/feature_command.md)
-  * [API anti-rebond](feature_debounce_type.md)
+  * [API anti-rebond](fr-fr/feature_debounce_type.md)
-  * [DIP Switch](feature_dip_switch.md)
+  * [DIP Switch](fr-fr/feature_dip_switch.md)
-  * [Macros dynamiques](feature_dynamic_macros.md)
+  * [Macros dynamiques](fr-fr/feature_dynamic_macros.md)
-  * [Interrupteurs rotatifs](feature_encoders.md)
+  * [Interrupteurs rotatifs](fr-fr/feature_encoders.md)
-  * [Grave Escape](feature_grave_esc.md)
+  * [Grave Escape](fr-fr/feature_grave_esc.md)
-  * [Retour haptique](feature_haptic_feedback.md)
+  * [Retour haptique](fr-fr/feature_haptic_feedback.md)
-  * [Contrôleur LCD HD44780](feature_hd44780.md)
+  * [Contrôleur LCD HD44780](fr-fr/feature_hd44780.md)
-  * [Touche à verrou / Lock-key](feature_key_lock.md)
+  * [Touche à verrou / Lock-key](fr-fr/feature_key_lock.md)
-  * [Dispositions / layouts](feature_layouts.md)
+  * [Dispositions / layouts](fr-fr/feature_layouts.md)
-  * [Touche leader](feature_leader_key.md)
+  * [Touche leader](fr-fr/feature_leader_key.md)
-  * [Matrice LED](feature_led_matrix.md)
+  * [Matrice LED](fr-fr/feature_led_matrix.md)
-  * [Macros](feature_macros.md)
+  * [Macros](fr-fr/feature_macros.md)
-  * [Boutons de souris](feature_mouse_keys.md)
+  * [Boutons de souris](fr-fr/feature_mouse_keys.md)
-  * [Pilotes / Drivers OLED](feature_oled_driver.md)
+  * [Pilotes / Drivers OLED](fr-fr/feature_oled_driver.md)
-  * [Touche one-shot](feature_advanced_keycodes.md#one-shot-keys)
+  * [Touche one-shot](fr-fr/feature_advanced_keycodes.md#one-shot-keys)
-  * [Périphériques de pointage](feature_pointing_device.md)
+  * [Périphériques de pointage](fr-fr/feature_pointing_device.md)
-  * [Souris PS/2](feature_ps2_mouse.md)
+  * [Souris PS/2](fr-fr/feature_ps2_mouse.md)
-  * [Éclairage RGB](feature_rgblight.md)
+  * [Éclairage RGB](fr-fr/feature_rgblight.md)
-  * [Matrice RGB](feature_rgb_matrix.md)
+  * [Matrice RGB](fr-fr/feature_rgb_matrix.md)
-  * [Space Cadet](feature_space_cadet.md)
+  * [Space Cadet](fr-fr/feature_space_cadet.md)
-  * [Claviers scindés / splittés](feature_split_keyboard.md)
+  * [Claviers scindés / splittés](fr-fr/feature_split_keyboard.md)
-  * [Stenographie](feature_stenography.md)
+  * [Stenographie](fr-fr/feature_stenography.md)
-  * [Inversion des mains](feature_swap_hands.md)
+  * [Inversion des mains](fr-fr/feature_swap_hands.md)
-  * [Tap Dance](feature_tap_dance.md)
+  * [Tap Dance](fr-fr/feature_tap_dance.md)
-  * [Terminale](feature_terminal.md)
+  * [Terminale](fr-fr/feature_terminal.md)
-  * [Imprimante thermique](feature_thermal_printer.md)
+  * [Imprimante thermique](fr-fr/feature_thermal_printer.md)
-  * [Caractères unicodes](feature_unicode.md)
+  * [Caractères unicodes](fr-fr/feature_unicode.md)
-  * [Dossier utilisateur](feature_userspace.md)
+  * [Dossier utilisateur](fr-fr/feature_userspace.md)
-  * [Velocikey](feature_velocikey.md)
+  * [Velocikey](fr-fr/feature_velocikey.md)
 * Pour les makers et les bricoleurs
-  * [Guide des claviers soudés à la main](hand_wire.md)
+  * [Guide des claviers soudés à la main](fr-fr/hand_wire.md)
-  * [Guide de flash de l’ISP](isp_flashing_guide.md)
+  * [Guide de flash de l’ISP](fr-fr/isp_flashing_guide.md)
-  * [Guide du débogage ARM](arm_debugging.md)
+  * [Guide du débogage ARM](fr-fr/arm_debugging.md)
-  * [Drivers i2c](i2c_driver.md)
+  * [Drivers i2c](fr-fr/i2c_driver.md)
-  * [Contrôles des GPIO](internals_gpio_control.md)
+  * [Contrôles des GPIO](fr-fr/internals_gpio_control.md)
-  * [Conversion en Proton C](proton_c_conversion.md)
+  * [Conversion en Proton C](fr-fr/proton_c_conversion.md)
 * Pour aller plus loin
-  * [Comment fonctionnent les claviers](how_keyboards_work.md)
+  * [Comment fonctionnent les claviers](fr-fr/how_keyboards_work.md)
-  * [Comprendre QMK](understanding_qmk.md)
+  * [Comprendre QMK](fr-fr/understanding_qmk.md)
 * Autres sujets
-  * [Utiliser Eclipse avec QMK](other_eclipse.md)
+  * [Utiliser Eclipse avec QMK](fr-fr/other_eclipse.md)
-  * [Utiliser VSCode avec QMK](other_vscode.md)
+  * [Utiliser VSCode avec QMK](fr-fr/other_vscode.md)
-  * [Support](support.md)
+  * [Support](fr-fr/support.md)
-  * [Comment ajouter des traductions](translating.md)
+  * [Comment ajouter des traductions](fr-fr/translating.md)
 * À l’intérieur de QMK (En cours de documentation)
-  * [Définitions](internals_defines.md)
+  * [Définitions](fr-fr/internals_defines.md)
-  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Input Callback Reg](fr-fr/internals_input_callback_reg.md)
-  * [Appareils Midi](internals_midi_device.md)
+  * [Appareils Midi](fr-fr/internals_midi_device.md)
-  * [Installation d’un appareil Midi](internals_midi_device_setup_process.md)
+  * [Installation d’un appareil Midi](fr-fr/internals_midi_device_setup_process.md)
-  * [Utilitaires Midi](internals_midi_util.md)
+  * [Utilitaires Midi](fr-fr/internals_midi_util.md)
-  * [Fonctions Midi](internals_send_functions.md)
+  * [Fonctions Midi](fr-fr/internals_send_functions.md)
-  * [Outils Sysex](internals_sysex_tools.md)
+  * [Outils Sysex](fr-fr/internals_sysex_tools.md)
diff --git a/docs/fr-fr/faq_build.md b/docs/fr-fr/faq_build.md
index 774bf6880..84d88afcd 100644
--- a/docs/fr-fr/faq_build.md
+++ b/docs/fr-fr/faq_build.md
@@ -86,10 +86,6 @@ Relancer le script d'installation de QMK (`./util/qmk_install.sh` situé dans r�
 Si vous rencontrez toujours des problèmes, essayez de télécharger et lancer Zadig. Voir [Installation du driver du bootloader avec Zadig](driver_installation_zadig.md) pour plus d'informations.
-## WINAVR est obsolète
-Il n'est plus recommandé et peut causer des problèmes. Voir [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
 ## USB VID et PID
 Vous pouvez utiliser l'ID de votre choix en modifier `config.h`. Il y a peu de chance de conflit avec d'autres produits.
@@ -103,30 +99,6 @@ Vous pouvez acheter un VID:PID unique ici. Je ne pense pas que ce soit nécessai
 - http://www.obdev.at/products/vusb/license.html
 - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
-## Cortex: `cstddef: No such file or directory`
-Ce problème existait avec le GCC 4.8 d'Ubuntu 14.04, la solution a nécessité de mettre à jour vers 4.9 avec ce PPA.
-https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
-https://github.com/tmk/tmk_keyboard/issues/212
-https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
-https://developer.mbed.org/forum/mbed/topic/5205/
-## `clock_prescale_set` and `clock_div_1` Not Available
-Votre chaîne d'outils (Toolchain) est trop vieille pour supporter le MCU. Par exemple, WinAVR 20100110 ne supporte pas ATMega32u2.
-```
-Compiling C: ../../tmk_core/protocol/lufa/lufa.c
-avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8  -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d  ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o
-../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu':
-../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set'
-../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function)
-../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once
-../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.)
-make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
-```
 ## BOOTLOADER_SIZE pour AVR
 Notez que la taille du bootloader pour les Teensy2.0++ est de 2048bytes. Quelques Makefiles peuvent contenir une erreur et avoir le mauvais commentaire.
diff --git a/docs/fr-fr/faq_debug.md b/docs/fr-fr/faq_debug.md
index 7a85fd1f2..754c79921 100644
--- a/docs/fr-fr/faq_debug.md
+++ b/docs/fr-fr/faq_debug.md
@@ -104,58 +104,6 @@ En C, `1` implique un type [int] qui est [16 bits] pour les AVR, ce qui implique
 http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
-## Bootloader Jump ne fonctionne pas
-Configurez correctement la taille du bootloader dans le **Makefile**. Une mauvaise taille de section du bootloader empêchera probablement le démarrage avec **Magic command** et **Boot Magic**.
-```
-# Size of Bootloaders in bytes:
-#   Atmel DFU loader(ATmega32U4)   4096
-#   Atmel DFU loader(AT90USB128)   8192
-#   LUFA bootloader(ATmega32U4)    4096
-#   Arduino Caterina(ATmega32U4)   4096
-#   USBaspLoader(ATmega***)        2048
-#   Teensy   halfKay(ATmega32U4)   512
-#   Teensy++ halfKay(AT90USB128)   2048
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
-```
-La taille de la section de démarrage de AVR est définie par l'option **BOOTSZ** fuse. Vérifiez la fiche technique du MCU. Veuilez noter que les tailles et adresses sont définies en **Word** (2 octets) dans la fiche technique alors que TMK utilise des **Byte**.
-La section de boot AVR se trouve à la fin de la mémoire flash, comme suit.
-```
-byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-4KB               |               | 128KB-8KB
-0x6000   +---------------+               0x1E000  +---------------+
-         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-512B              |               | 128KB-2KB
-0x7E00   +---------------+               0x1FC00  +---------------+
-         |  Bootloader   | 512B                   |  Bootloader   | 2KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-```
-Référez-vous à cette discussion pour plus de référence.
-https://github.com/tmk/tmk_keyboard/issues/179
-Si vous utilisez un TeensyUSB, il y a un [bug connu](https://github.com/qmk/qmk_firmware/issues/164) qui fait que le bouton reset matériel empêche la touche RESET de fonctionner. Débrancher et rebrancher le clavier devrait résoudre le problème.
 ## Les touches spéciales ne fonctionnent pas (Touche Système, Touches de contrôle du son)
 Vous devez définir `EXTRAKEY_ENABLE` dans le fichier `rules.mk` pour les utiliser dans QMK.
@@ -189,25 +137,6 @@ Si vous voulez garder JTAG activé, ajoutez la ligne suivante à votre fichier `
 #define NO_JTAG_DISABLE
 ```
-## Adding LED Indicators of Lock Keys
-Si vous souhaitez votre propre indicateur LED pour CapsLock, ScrollLock et NumLock alors lisez ce post.
-http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
-## Programmer Arduino Micro/Leonardo
-Appuyez sur le bouton reset puis lancez la commande suivante dans les 8 secondes.
-```
-avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
-```
-Le nom du périphérique peut varier en fonction de votre système.
-http://arduino.cc/en/Main/ArduinoBoardMicro
-https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
 ## Compatibilité USB 3
 Il semble que certaines personnes ont eu des problèmes avec les ports USB 3, essayez un port USB 2.
diff --git a/docs/fr-fr/faq_keymap.md b/docs/fr-fr/faq_keymap.md
index 8244d4225..2cbbe9308 100644
--- a/docs/fr-fr/faq_keymap.md
+++ b/docs/fr-fr/faq_keymap.md
@@ -72,24 +72,7 @@ Des vieux claviers mécaniques ont parfois des touches à verrouillage, mais les
 ## Ajouter des caractères spéciaux autres que ASCII comme la cédille 'Ç'
-IL N'EXISTE AUCUNE METHODE UNIVERSELLE POUR LES AJOUTER QUI FONCTIONNE SUR TOUS LES SYSTEMES. Vous devez définir une **MACRO** d'une manière spécifique à votre OS ou layout.
+Voir la fonctionnalité [Unicode](feature_unicode.md).
-Voir ce post pour un exemple de code **MACRO**.
-http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
-Sous **Windows** vous pouvez utiliser la touche `AltGr` ou **Alt code**.
-* http://en.wikipedia.org/wiki/AltGr_key
-* http://en.wikipedia.org/wiki/Alt_code
-Sous **Mac OS** définissez une combinaison de touche `Option`.
-* http://en.wikipedia.org/wiki/Option_key#Alternative_keyboard_input
-Sous **Xorg** vous pouvez utiliser une touche `compose` à la place.
-* http://en.wikipedia.org/wiki/Compose_key
-Et voir ceci pour une entrée **Unicode**.
-* http://en.wikipedia.org/wiki/Unicode_input
 ## Touche `Fn` sur macOS
@@ -144,54 +127,6 @@ Cette fonctionnalité permet d'utiliser une touche à la fois comme touche Écha
 Voir la fonctionnalité [Grave Escape](feature_grave_esc.md).
-## Avoir les touches modificatrices qui ont double usage en flèches directionnelles.
-Ceci transforme les touches "modificateur droit" en touches fléchées lorsque les touches sont seulement "tapées" tout en restant des modificateurs lorsqu'elles sont maintenues.
-Dans TMK la fonction double rôle s'appelle **TAP**.
-```C
-#include "keymap_common.h"
-/* Arrow keys on right modifier keys with TMK dual role feature
- *
- *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
- *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
- */
-const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-    /* 0: qwerty */
-    [0] = LAYOUT( \
-        ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
-        TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
-        LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
-        LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
-        FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
-    [1] = LAYOUT( \
-        GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
-        TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
-};
-const uint16_t PROGMEM fn_actions[] = {
-    [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
-    [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
-    [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
-    [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
-    [4] = ACTION_LAYER_MOMENTARY(1),
-    [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
-    [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
-    [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
-    [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
-};
-```
-Touches double rôle : https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 ## Eject sur Mac OSX
 Le keycode`KC_EJCT` fonctionne sous OSX. https://github.com/tmk/tmk_keyboard/issues/250
diff --git a/docs/fr-fr/getting_started_github.md b/docs/fr-fr/getting_started_github.md
index 22c6ee749..48755625a 100644
--- a/docs/fr-fr/getting_started_github.md
+++ b/docs/fr-fr/getting_started_github.md
@@ -16,17 +16,23 @@ Faites attention à sélectionner "HTTPS", et sélectionnez le lien et copiez-le
 ![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
-Ensuite, entrez `git clone` dans la ligne de commande, et collez votre lien:
+Ensuite, entrez `git clone --recurse-submodules ` dans la ligne de commande, et collez votre lien:
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
+remote: Enumerating objects: 9, done.
-remote: Compressing objects: 100% (2/2), done.
+remote: Counting objects: 100% (9/9), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
+remote: Compressing objects: 100% (5/5), done.
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
-Resolving deltas: 100% (29362/29362), done.
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
-Checking out files: 100% (2799/2799), done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 Vous avez maintenant votre fork QMK sur votre machine locale, vous pouvez ajouter votre keymap, la compiler et la flasher sur votre board. Une fois heureux avec vos changements, vous pouvez les ajouter, commit, et pousser vers votre fork comme suit:
diff --git a/docs/fr-fr/getting_started_introduction.md b/docs/fr-fr/getting_started_introduction.md
index a7f0ff96a..b2711a167 100644
--- a/docs/fr-fr/getting_started_introduction.md
+++ b/docs/fr-fr/getting_started_introduction.md
@@ -4,7 +4,7 @@ Le but de cette page est d'expliquer les informations de base qui vous serons n�
 ## Structure de base de QMK
-QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`.
+QMK est un fork du projet [tmk_keyboard](https://github.com/tmk/tmk_keyboard) créé par [Jun Wako](https://github.com/tmk). Le code originel de TMK, avec quelques modifications, se trouve dans le dossier `tmk_core`. Les additions que QMK amène au projet se trouvent dans le dossier `quantum`. Les projets de clavier se trouvent dans les dossiers `handwired` et `keyboard`.
 ### Structure du Userspace
diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md
index 2721a9a03..fea20e59b 100644
--- a/docs/getting_started_build_tools.md
+++ b/docs/getting_started_build_tools.md
@@ -43,7 +43,7 @@ Debian / Ubuntu example:
 Fedora / Red Hat example:
    sudo dnf install gcc unzip wget zip dfu-util dfu-programmer avr-gcc avr-libc binutils-avr32-linux-gnu arm-none-eabi-gcc-cs arm-none-eabi-binutils-cs arm-none-eabi-newlib
-    
 Arch / Manjaro example:
    pacman -S base-devel gcc unzip wget zip avr-gcc avr-binutils avr-libc dfu-util arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib git dfu-programmer dfu-util
@@ -57,16 +57,17 @@ By default, this will download compilers for both AVR and ARM. If you don't need
    nix-shell --arg arm false
 ## macOS
-If you're using [homebrew,](http://brew.sh/) you can use the following commands:
+If you're using [Homebrew](http://brew.sh/), you can use the following commands:
    brew tap osx-cross/avr
-    brew tap PX4/homebrew-px4
+    brew tap osx-cross/arm
    brew update
    brew install avr-gcc@8
    brew link --force avr-gcc@8
    brew install dfu-programmer
    brew install dfu-util
-    brew install gcc-arm-none-eabi
+    brew install arm-gcc-bin@8
+    brew link --force arm-gcc-bin@8
    brew install avrdude
 This is the recommended method. If you don't have homebrew, [install it!](http://brew.sh/) It's very much worth it for anyone who works in the command line. Note that the `make` and `make install` portion during the homebrew installation of `avr-gcc@8` can take over 20 minutes and exhibit high CPU usage.
@@ -119,12 +120,12 @@ If this is a bit complex for you, Docker might be the turnkey solution you need.
 util/docker_build.sh keyboard:keymap
 # For example: util/docker_build.sh ergodox_ez:steno
 ```
-This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, the `default` keymap is used. Note that the parameter format is the same as when building with `make`.
+This will compile the desired keyboard/keymap and leave the resulting `.hex` or `.bin` file in the QMK directory for you to flash. If `:keymap` is omitted, all keymaps are used. Note that the parameter format is the same as when building with `make`.
 You can also start the script without any parameters, in which case it will ask you to input the build parameters one by one, which you may find easier to use:
 ```bash
 util/docker_build.sh
-# Reads parameters as input (leave blank for defaults)
+# Reads parameters as input (leave blank for all keyboards/keymaps)
 ```
 There is also support for building _and_ flashing the keyboard straight from Docker by specifying the `target` as well:
diff --git a/docs/getting_started_github.md b/docs/getting_started_github.md
index aeb8738b7..07f523f57 100644
--- a/docs/getting_started_github.md
+++ b/docs/getting_started_github.md
@@ -16,17 +16,23 @@ And be sure to select "HTTPS", and select the link and copy it:
 ![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
-From here, enter `git clone ` into the command line, and then paste your link:
+From here, enter `git clone --recurse-submodules ` into the command line, and then paste your link:
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
+remote: Enumerating objects: 9, done.
-remote: Compressing objects: 100% (2/2), done.
+remote: Counting objects: 100% (9/9), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
+remote: Compressing objects: 100% (5/5), done.
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
-Resolving deltas: 100% (29362/29362), done.
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
-Checking out files: 100% (2799/2799), done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 You now have your QMK fork on your local machine, and you can add your keymap, compile it and flash it to your board. Once you're happy with your changes, you can add, commit, and push them to your fork like this:
diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md
index e183d77ee..6dc51b82b 100644
--- a/docs/getting_started_introduction.md
+++ b/docs/getting_started_introduction.md
@@ -4,7 +4,7 @@ This page attempts to explain the basic information you need to know to work wit
 ## Basic QMK Structure
-QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
+QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk_core` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
 ### Userspace Structure
diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md
index d2596b2e2..df82a001f 100644
--- a/docs/getting_started_make_guide.md
+++ b/docs/getting_started_make_guide.md
@@ -59,7 +59,7 @@ To disable debug messages (*dprint*) and reduce the .hex file size, include `#de
 To disable print messages (*print*, *xprintf*) and user print messages (*uprint*) and reduce the .hex file size, include `#define NO_PRINT` in your `config.h` file.
-To disable print messages (*print*, *xprintf*) and **KEEP** user print messages (*uprint*), include `#define USER_PRINT` in your `config.h` file.
+To disable print messages (*print*, *xprintf*) and **KEEP** user print messages (*uprint*), include `#define USER_PRINT` in your `config.h` file (do not also include `#define NO_PRINT` in this case).
 To see the text, open `hid_listen` and enjoy looking at your printed messages.
@@ -135,7 +135,7 @@ As there is no standard split communication driver for ARM-based split keyboards
 `CUSTOM_MATRIX`
-Lets you replace the default matrix scanning routine with your own code. You will need to provide your own implementations of matrix_init() and matrix_scan().
+Lets you replace the default matrix scanning routine with your own code. For further details, see the [Custom Matrix page](custom_matrix.md).
 `DEBOUNCE_TYPE`
diff --git a/docs/he-il/README.md b/docs/he-il/README.md
index db0ad43c3..8e0c470b4 100644
--- a/docs/he-il/README.md
+++ b/docs/he-il/README.md
@@ -20,7 +20,7 @@ QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open sour
 ## איך לקמפל
-לפני שתצליחו לקמפל, תדרשו [להתקין סביבה](getting_started_build_tools.md) עבור פיתוח AVR ו/או ARM. ברגע שהדבר בוצע, תוכלו להריץ פקודת `make` כדי לבנות מקלדת ומיפוי עם התחביר הבא: 
+לפני שתצליחו לקמפל, תדרשו [להתקין סביבה](he-il/getting_started_build_tools.md) עבור פיתוח AVR ו/או ARM. ברגע שהדבר בוצע, תוכלו להריץ פקודת `make` כדי לבנות מקלדת ומיפוי עם התחביר הבא: 
    make planck/rev4:default
@@ -30,5 +30,5 @@ QMK (*Quantum Mechanical Keyboard*) היא קהילת קוד פתוח (open sour
 ## איך להתאים
-לQMK יש המון [יכולות](features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](http://docs.qmk.fm) בה אפשר לנבור. רוב הפיצ׳רים באים לידי ביטוי על ידי שינוי  [מיפוי המקלדת](keymap.md) ושינוי  [קודי המקשים](keycodes.md).
+לQMK יש המון [יכולות](he-il/features.md) שאפשר לנווט בהן, וכמות נכבדת של [תיעוד ודוקומנטציה](http://docs.qmk.fm) בה אפשר לנבור. רוב הפיצ׳רים באים לידי ביטוי על ידי שינוי  [מיפוי המקלדת](he-il/keymap.md) ושינוי  [קודי המקשים](he-il/keycodes.md).
 </div>
diff --git a/docs/he-il/_summary.md b/docs/he-il/_summary.md
index acc0546d0..804db534a 100644
--- a/docs/he-il/_summary.md
+++ b/docs/he-il/_summary.md
@@ -1,6 +1,7 @@
 <div dir="rtl" markdown="1">
 **בשפה העברית**
-* [המדריך המלא למתחילים](newbs.md)
+* [המדריך המלא למתחילים](he-il/newbs.md)
  * [מקורות ללמידה](he-il/newbs_learn_more_resources.md)
 * [בסיס QMK](he-il/README.md)
    * [מבוא לQMK](he-il/getting_started_introduction.md)
@@ -13,126 +14,126 @@
  * [איך לתעד נכון](he-il/documentation_best_practices.md)
 **בשפה האנגלית**
-* [המדריך המלא למתחילים](newbs.md)
+* [המדריך המלא למתחילים](he-il/newbs.md)
-  * [התחלה](newbs_getting_started.md)
+  * [התחלה](he-il/newbs_getting_started.md)
-  * [בנייה של הקושחה הראשונה שלך](newbs_building_firmware.md)
+  * [בנייה של הקושחה הראשונה שלך](he-il/newbs_building_firmware.md)
-  * [צריבה של הקושחה](newbs_flashing.md)
+  * [צריבה של הקושחה](he-il/newbs_flashing.md)
-  * [בדיקות ודיבאגינג](newbs_testing_debugging.md)
+  * [בדיקות ודיבאגינג](he-il/newbs_testing_debugging.md)
-  * [עבודה נכונה ב GIT](newbs_best_practices.md)
+  * [עבודה נכונה ב GIT](he-il/newbs_best_practices.md)
-  * [מקורות ללמידה](newbs_learn_more_resources.md)
+  * [מקורות ללמידה](he-il/newbs_learn_more_resources.md)
-* [בסיס QMK](README.md)
+* [בסיס QMK](he-il/README.md)
-  * [מבוא לQMK](getting_started_introduction.md)
+  * [מבוא לQMK](he-il/getting_started_introduction.md)
-  * [QMK CLI](cli.md)
+  * [QMK CLI](he-il/cli.md)
-  * [QMK CLI Config](cli_configuration.md)
+  * [QMK CLI Config](he-il/cli_configuration.md)
-  * [תרומה ל QMK](contributing.md)
+  * [תרומה ל QMK](he-il/contributing.md)
-  * [איך להשתמש בGithub](getting_started_github.md)
+  * [איך להשתמש בGithub](he-il/getting_started_github.md)
-  * [קבלת עזרה](getting_started_getting_help.md)
+  * [קבלת עזרה](he-il/getting_started_getting_help.md)
-* [שינויים משמעותיים](breaking_changes.md)
+* [שינויים משמעותיים](he-il/breaking_changes.md)
-  * [2019 Aug 30](ChangeLog/20190830.md)
+  * [2019 Aug 30](he-il/ChangeLog/20190830.md)
-* [שאלות נפוצות](faq.md)
+* [שאלות נפוצות](he-il/faq.md)
-  * [שאלות נפוצות כלליות](faq_general.md)
+  * [שאלות נפוצות כלליות](he-il/faq_general.md)
-  * [בנייה/קומפילציה של QMK](faq_build.md)
+  * [בנייה/קומפילציה של QMK](he-il/faq_build.md)
-  * [דיבאגינג ופתרון תקלות של QMK](faq_debug.md)
+  * [דיבאגינג ופתרון תקלות של QMK](he-il/faq_debug.md)
-  * [מיפוי מקשים](faq_keymap.md)
+  * [מיפוי מקשים](he-il/faq_keymap.md)
-  * [התקנת דרייברים עם Zadig](driver_installation_zadig.md)
+  * [התקנת דרייברים עם Zadig](he-il/driver_installation_zadig.md)
 * מדריכים מפורטים
-  * [התקנת כלי Build](getting_started_build_tools.md)
+  * [התקנת כלי Build](he-il/getting_started_build_tools.md)
-  * [מדריך Vagrant](getting_started_vagrant.md)
+  * [מדריך Vagrant](he-il/getting_started_vagrant.md)
-  * [הוראות בנייה/קומפילציה](getting_started_make_guide.md)
+  * [הוראות בנייה/קומפילציה](he-il/getting_started_make_guide.md)
-  * [צריבת קושחה](flashing.md)
+  * [צריבת קושחה](he-il/flashing.md)
-  * [התאמה אישית של הפונקציונאליות](custom_quantum_functions.md)
+  * [התאמה אישית של הפונקציונאליות](he-il/custom_quantum_functions.md)
-  * [מיפוי מקשים](keymap.md)
+  * [מיפוי מקשים](he-il/keymap.md)
-* [חומרה](hardware.md)
+* [חומרה](he-il/hardware.md)
-  * [מעבדי AVR](hardware_avr.md)
+  * [מעבדי AVR](he-il/hardware_avr.md)
-  * [דרייברים](hardware_drivers.md)
+  * [דרייברים](he-il/hardware_drivers.md)
 * התייחסויות
-  * [מדריך למקלדות](hardware_keyboard_guidelines.md)
+  * [מדריך למקלדות](he-il/hardware_keyboard_guidelines.md)
-  * [אפשרויות הגדרות](config_options.md)
+  * [אפשרויות הגדרות](he-il/config_options.md)
-  * [קודי מקשים](keycodes.md)
+  * [קודי מקשים](he-il/keycodes.md)
-  * [קונבנציות קוד - C](coding_conventions_c.md)
+  * [קונבנציות קוד - C](he-il/coding_conventions_c.md)
-  * [קונבנציות קוד - Python](coding_conventions_python.md)
+  * [קונבנציות קוד - Python](he-il/coding_conventions_python.md)
-  * [איך לתעד נכון](documentation_best_practices.md)
+  * [איך לתעד נכון](he-il/documentation_best_practices.md)
-  * [טמפלטים לדוקומנטציה](documentation_templates.md)
+  * [טמפלטים לדוקומנטציה](he-il/documentation_templates.md)
-  * [מילון](reference_glossary.md)
+  * [מילון](he-il/reference_glossary.md)
-  * [בדיקות יחידה](unit_testing.md)
+  * [בדיקות יחידה](he-il/unit_testing.md)
-  * [פונקציות שימושיות](ref_functions.md)
+  * [פונקציות שימושיות](he-il/ref_functions.md)
-  * [תמיכה בConfigurator](reference_configurator_support.md)
+  * [תמיכה בConfigurator](he-il/reference_configurator_support.md)
-  * [פורמט info.json](reference_info_json.md)
+  * [פורמט info.json](he-il/reference_info_json.md)
-  * [פיתוח בPython CLI](cli_development.md)
+  * [פיתוח בPython CLI](he-il/cli_development.md)
-* [תכונות](features.md)
+* [תכונות](he-il/features.md)
-  * [Basic Keycodes](keycodes_basic.md)
+  * [Basic Keycodes](he-il/keycodes_basic.md)
-  * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
+  * [US ANSI Shifted Keys](he-il/keycodes_us_ansi_shifted.md)
-  * [Quantum Keycodes](quantum_keycodes.md)
+  * [Quantum Keycodes](he-il/quantum_keycodes.md)
-  * [Advanced Keycodes](feature_advanced_keycodes.md)
+  * [Advanced Keycodes](he-il/feature_advanced_keycodes.md)
-  * [Audio](feature_audio.md)
+  * [Audio](he-il/feature_audio.md)
-  * [Auto Shift](feature_auto_shift.md)
+  * [Auto Shift](he-il/feature_auto_shift.md)
-  * [Backlight](feature_backlight.md)
+  * [Backlight](he-il/feature_backlight.md)
-  * [Bluetooth](feature_bluetooth.md)
+  * [Bluetooth](he-il/feature_bluetooth.md)
-  * [Bootmagic](feature_bootmagic.md)
+  * [Bootmagic](he-il/feature_bootmagic.md)
-  * [Combos](feature_combo.md)
+  * [Combos](he-il/feature_combo.md)
-  * [Command](feature_command.md)
+  * [Command](he-il/feature_command.md)
-  * [Debounce API](feature_debounce_type.md)
+  * [Debounce API](he-il/feature_debounce_type.md)
-  * [DIP Switch](feature_dip_switch.md)
+  * [DIP Switch](he-il/feature_dip_switch.md)
-  * [Dynamic Macros](feature_dynamic_macros.md)
+  * [Dynamic Macros](he-il/feature_dynamic_macros.md)
-  * [Encoders](feature_encoders.md)
+  * [Encoders](he-il/feature_encoders.md)
-  * [Grave Escape](feature_grave_esc.md)
+  * [Grave Escape](he-il/feature_grave_esc.md)
-  * [Haptic Feedback](feature_haptic_feedback.md)
+  * [Haptic Feedback](he-il/feature_haptic_feedback.md)
-  * [HD44780 LCD Controller](feature_hd44780.md)
+  * [HD44780 LCD Controller](he-il/feature_hd44780.md)
-  * [Key Lock](feature_key_lock.md)
+  * [Key Lock](he-il/feature_key_lock.md)
-  * [Layouts](feature_layouts.md)
+  * [Layouts](he-il/feature_layouts.md)
-  * [Leader Key](feature_leader_key.md)
+  * [Leader Key](he-il/feature_leader_key.md)
-  * [LED Matrix](feature_led_matrix.md)
+  * [LED Matrix](he-il/feature_led_matrix.md)
-  * [Macros](feature_macros.md)
+  * [Macros](he-il/feature_macros.md)
-  * [Mouse Keys](feature_mouse_keys.md)
+  * [Mouse Keys](he-il/feature_mouse_keys.md)
-  * [OLED Driver](feature_oled_driver.md)
+  * [OLED Driver](he-il/feature_oled_driver.md)
-  * [One Shot Keys](feature_advanced_keycodes.md#one-shot-keys)
+  * [One Shot Keys](he-il/feature_advanced_keycodes.md#one-shot-keys)
-  * [Pointing Device](feature_pointing_device.md)
+  * [Pointing Device](he-il/feature_pointing_device.md)
-  * [PS/2 Mouse](feature_ps2_mouse.md)
+  * [PS/2 Mouse](he-il/feature_ps2_mouse.md)
-  * [RGB Lighting](feature_rgblight.md)
+  * [RGB Lighting](he-il/feature_rgblight.md)
-  * [RGB Matrix](feature_rgb_matrix.md)
+  * [RGB Matrix](he-il/feature_rgb_matrix.md)
-  * [Space Cadet](feature_space_cadet.md)
+  * [Space Cadet](he-il/feature_space_cadet.md)
-  * [Split Keyboard](feature_split_keyboard.md)
+  * [Split Keyboard](he-il/feature_split_keyboard.md)
-  * [Stenography](feature_stenography.md)
+  * [Stenography](he-il/feature_stenography.md)
-  * [Swap Hands](feature_swap_hands.md)
+  * [Swap Hands](he-il/feature_swap_hands.md)
-  * [Tap Dance](feature_tap_dance.md)
+  * [Tap Dance](he-il/feature_tap_dance.md)
-  * [Terminal](feature_terminal.md)
+  * [Terminal](he-il/feature_terminal.md)
-  * [Thermal Printer](feature_thermal_printer.md)
+  * [Thermal Printer](he-il/feature_thermal_printer.md)
-  * [Unicode](feature_unicode.md)
+  * [Unicode](he-il/feature_unicode.md)
-  * [Userspace](feature_userspace.md)
+  * [Userspace](he-il/feature_userspace.md)
-  * [Velocikey](feature_velocikey.md)
+  * [Velocikey](he-il/feature_velocikey.md)
 * למייקרים ומודרים
-  * [מדריך לכתיבה ידנית](hand_wire.md)
+  * [מדריך לכתיבה ידנית](he-il/hand_wire.md)
-  * [מדריך לצריבת ISP](isp_flashing_guide.md)
+  * [מדריך לצריבת ISP](he-il/isp_flashing_guide.md)
-  * [מדריך לדיבאגינג ARM](arm_debugging.md)
+  * [מדריך לדיבאגינג ARM](he-il/arm_debugging.md)
-  * [מנהל התקן I2C](i2c_driver.md)
+  * [מנהל התקן I2C](he-il/i2c_driver.md)
-  * [בקרת GPIO](internals_gpio_control.md)
+  * [בקרת GPIO](he-il/internals_gpio_control.md)
-  * [המרת Proton C](proton_c_conversion.md)
+  * [המרת Proton C](he-il/proton_c_conversion.md)
 * להבנה עמוקה יותר
-  * [איך עובדות מקלדות](how_keyboards_work.md)
+  * [איך עובדות מקלדות](he-il/how_keyboards_work.md)
-  * [להבין את QMK](understanding_qmk.md)
+  * [להבין את QMK](he-il/understanding_qmk.md)
 * נושאים נוספים
-  * [שימוש ב - Eclipse עם QMK](other_eclipse.md)
+  * [שימוש ב - Eclipse עם QMK](he-il/other_eclipse.md)
-  * [שימוש ב - VSCode עם QMK](other_vscode.md)
+  * [שימוש ב - VSCode עם QMK](he-il/other_vscode.md)
-  * [תמיכה](support.md)
+  * [תמיכה](he-il/support.md)
-  * [כיצד להוסיף תרגום](translating.md)
+  * [כיצד להוסיף תרגום](he-il/translating.md)
 * QMK מבפנים (בתהליך)
-  * [Defines](internals_defines.md)
+  * [Defines](he-il/internals_defines.md)
-  * [Input Callback Reg](internals_input_callback_reg.md)
+  * [Input Callback Reg](he-il/internals_input_callback_reg.md)
-  * [Midi Device](internals_midi_device.md)
+  * [Midi Device](he-il/internals_midi_device.md)
-  * [Midi Device Setup Process](internals_midi_device_setup_process.md)
+  * [Midi Device Setup Process](he-il/internals_midi_device_setup_process.md)
-  * [Midi Util](internals_midi_util.md)
+  * [Midi Util](he-il/internals_midi_util.md)
-  * [Send Functions](internals_send_functions.md)
+  * [Send Functions](he-il/internals_send_functions.md)
-  * [Sysex Tools](internals_sysex_tools.md)
+  * [Sysex Tools](he-il/internals_sysex_tools.md)
 </div>
diff --git a/docs/he-il/getting_started_github.md b/docs/he-il/getting_started_github.md
index 55602c814..e5d0f7c78 100644
--- a/docs/he-il/getting_started_github.md
+++ b/docs/he-il/getting_started_github.md
@@ -17,19 +17,25 @@ Github עלול להיות קצת טריקי למי שלא מכיר את העב�
 ![קישור HTTPS](http://i.imgur.com/eGO0ohO.jpg)
-מכאן והלאה, הקיש `git clone ` בשורת הפקודה והדביקו את הלינק שלכם:
+מכאן והלאה, הקיש `git clone --recurse-submodules ` בשורת הפקודה והדביקו את הלינק שלכם:
 <div dir="ltr" markdown="1">
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
+remote: Enumerating objects: 9, done.
-remote: Compressing objects: 100% (2/2), done.
+remote: Counting objects: 100% (9/9), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
+remote: Compressing objects: 100% (5/5), done.
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
-Resolving deltas: 100% (29362/29362), done.
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
-Checking out files: 100% (2799/2799), done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 </div>
@@ -66,4 +72,4 @@ To https://github.com/whoeveryouare/qmk_firmware.git
 ![צרו Pull Request](http://i.imgur.com/Ojydlaj.jpg)
 אחרי שהגשתם, אנו עלולים לפנות אליכם לגבי השינויים שהצעתם, נבקש שתבצעו שינויים ובסופו של דבר נקבל את השינויים! תודה שתרמתם לפרוייקט QMK :)
-</div>
-\ No newline at end of file
+</div>
diff --git a/docs/he-il/getting_started_introduction.md b/docs/he-il/getting_started_introduction.md
index 4b7f56b2a..fca86bdaa 100644
--- a/docs/he-il/getting_started_introduction.md
+++ b/docs/he-il/getting_started_introduction.md
@@ -5,7 +5,7 @@
 ## מבנה QMK בסיסי
-QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`.
+QMK הוא פורק של הפרוייקט [tmk_keyboard](https://github.com/tmk/tmk_keyboard) של [Jun Wako](https://github.com/tmk). קוד הTMK המקורי, עם התאמות, יכול להמצא בתיקיית `tmk_core`. התוספות של QMK לפרוייקט יכולות להמצא בתיקיית `quantum`. פרוייקטי מקלדות יכולות להמצא בתיקיות `handwired` ו- `keyboard`.
 ### מבנה אחסון המשתמש
@@ -69,4 +69,4 @@ In every keymap folder, the following files may be found. Only `keymap.c` is req
 ```
 </div>
-</div>
-\ No newline at end of file
+</div>
diff --git a/docs/he-il/quantum_keycodes.md b/docs/he-il/quantum_keycodes.md
index 3ca545e97..5374fd47a 100644
--- a/docs/he-il/quantum_keycodes.md
+++ b/docs/he-il/quantum_keycodes.md
@@ -17,18 +17,8 @@
 |`DEBUG`        |           |Toggle debug mode                                                    |
 |`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
 |`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
-|`KC_LCPO`      |           |Left Control when held, `(` when tapped                              |
-|`KC_RCPC`      |           |Right Control when held, `)` when tapped                             |
-|`KC_LAPO`      |           |Left Alt when held, `(` when tapped                                  |
-|`KC_RAPC`      |           |Right Alt when held, `)` when tapped                                 |
-|`KC_SFTENT`    |           |Right Shift when held, Enter when tapped                             |
 |`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
 |`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`         |           |Call macro `n`                                                       |
-|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
 ```
 </div>
diff --git a/docs/index.html b/docs/index.html
index d2ba99897..9b33cd263 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -21,7 +21,7 @@
  <div id="app"></div>
  <script>
    window.$docsify = {
-      alias : {
+      alias: {
        '/en/(.*)': '/$1',
        '/en-us/(.*)': '/$1',
        '/en-gb/(.*)': '/$1',
@@ -29,12 +29,32 @@
      },
      basePath: '/',
      name: 'QMK Firmware',
-      nameLink: '/',
+      nameLink: {
+        '/de/': '/#/de/',
+        '/es/': '/#/es/',
+        '/fr-fr/': '/#/fr-fr/',
+        '/he-il/': '/#/he-il/',
+        '/ja/': '/#/ja/',
+        '/pt-br/': '/#/pt-br/',
+        '/ru-ru/': '/#/ru-ru/',
+        '/zh-cn/': '/#/zh-cn/',
+        '/': '/#/'
+      },
      repo: 'qmk/qmk_firmware',
      loadSidebar: '_summary.md',
      loadNavbar: '_langs.md',
      mergeNavbar: true,
      auto2top: true,
+      fallbackLanguages: [
+        'de',
+        'es',
+        'fr-fr',
+        'he-il',
+        'ja',
+        'pt-br',
+        'ru-ru',
+        'zh-cn'
+      ],
      formatUpdated: '{YYYY}/{MM}/{DD} {HH}:{mm}',
      search: {
        paths: 'auto',
@@ -42,12 +62,14 @@
          '/es/': 'Buscar',
          '/zh-cn/': '搜索',
          '/ja/': '検索',
+          '/pt-br/': 'Busca',
          '/': 'Search'
        },
        noData: {
          '/es/': '¡Ningún resultado!',
          '/zh-cn/': '没有结果!',
          '/ja/': '見つかりません!',
+          '/pt-br/': 'Nenhum resultado!',
          '/': 'No results!'
        },
        depth: 6
@@ -60,9 +82,9 @@
                .replace('raw.githubusercontent.com', 'github.com')
                .replace(/\/master/, '/blob/master')
            } else {
-              url = 'https://github.com/qmk/qmk_firmware/blob/master/docs/' + vm.route.file
+              url = 'https://github.com/qmk/qmk_firmware/edit/master/docs/' + vm.route.file
            }
-            var editHtml = '[:memo: Edit Document](' + url + ')\n'
+            var editHtml = ':pencil2: [Edit this page](' + url + ')\n'
            return html
              + '\n\n----\n\n'
              + editHtml
diff --git a/docs/ja/README.md b/docs/ja/README.md
new file mode 100644
index 000000000..8959a9dd9
--- /dev/null
+++ b/docs/ja/README.md
@@ -0,0 +1,37 @@
+# Quantum Mechanical Keyboard Firmware
+<!---
+  original document: eae21eed7:docs/README.md
+  git diff eae21eed7 HEAD -- docs/README.md | cat
+-->
+[![現在のバージョン](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![ビルド状態](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![ドキュメントの状態](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![GitHub 貢献者](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![GitHub フォーク](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
+## QMK ファームウェアとは何か？
+QMK (*Quantum Mechanical Keyboard*)は QMK ファームウェア、QMK ツールボックス、qmk.fm およびそれらのドキュメントを保守するオープンソースコミュニティです。QMK ファームウェアは[tmk\_keyboard](http://github.com/tmk/tmk_keyboard) を元にしたキーボードファームウェアで、Atmel AVR コントローラ、より具体的には [OLKB 製品](http://olkb.com)、[ErgoDox EZ](http://www.ergodox-ez.com) キーボードおよび [Clueboard 製品](http://clueboard.co/) のための幾つかの便利な機能を持ちます。また、ChibiOS を使って ARM チップに移植されています。これを使ってあなたの作った手配線のキーボードあるいはカスタムキーボード PCB で作ったキーボードを動かすことができます。
+## 入手方法
+QMK のキーマップ、キーボード、機能に貢献をする予定がある場合、最も簡単なのは、[Github を介してリポジトリをフォークし](https://github.com/qmk/qmk_firmware#fork-destination-box)、リポジトリをあなたの開発環境にクローンして変更を加え、それらをプッシュし、[プルリクエスト](https://github.com/qmk/qmk_firmware/pulls)を開くことです。
+それ以外の場合は、`git clone https://github.com/qmk/qmk_firmware` を介して直接クローンすることができます。zip または tar ファイルをダウンロードしないでください。コンパイルするためのサブモジュールをダウンロードするために git リポジトリが必要です。
+## コンパイル方法
+コンパイルをする前に、AVR または ARM 開発のための[環境をインストール](ja/getting_started_build_tools.md)する必要があります。それが完了したら、`make` コマンドを使用して、以下の表記でキーボードとキーマップをビルドします。
+    make planck/rev4:default
+これは、`planck` の `rev4` リビジョンを `default` キーマップでビルドします。全てのキーボードにリビジョン(サブプロジェクトまたはフォルダとも呼ばれます)があるわけではありません。その場合は省略されます:
+    make preonic:default
+## カスタマイズ方法
+QMK には、探求すべき多くの[機能](ja/features.md)と、深堀りするための[リファレンス ドキュメント](http://docs.qmk.fm)がたくさんあります。ほとんどの機能は[キーマップ](ja/keymap.md)を変更し、[キーコード](ja/keycodes.md)を変更することで活用されます。
diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md
new file mode 100644
index 000000000..e5e19ddc8
--- /dev/null
+++ b/docs/ja/_summary.md
@@ -0,0 +1,124 @@
+* [完全な初心者のガイド](ja/newbs.md)
+   * [はじめに](ja/newbs_getting_started.md)
+   * [初めてのファームウェアの構築](ja/newbs_building_firmware.md)
+   * [ファームウェアのフラッシュ](ja/newbs_flashing.md)
+   * [テストとデバッグ](ja/newbs_testing_debugging.md)
+   * [QMK における Git 運用作法](ja/newbs_git_best_practices.md)
+     * [あなたのフォークの master ブランチ](ja/newbs_git_using_your_master_branch.md)
+     * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
+     * [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md)
+   * [学習リソース](ja/newbs_learn_more_resources.md)
+* [QMKの基本](ja/README.md)
+   * [QMKの導入](ja/getting_started_introduction.md)
+   * [QMK CLI](ja/cli.md)
+   * [QMK CLI 設定](ja/cli_configuration.md)
+   * [QMKへの貢献](ja/contributing.md)
+   * [Githubの使い方](ja/getting_started_github.md)
+   * [ヘルプ](ja/getting_started_getting_help.md)
+* [破壊的な変更](ja/breaking_changes.md)
+   * [2019年8月30日](ja/ChangeLog/20190830.md)
+* [FAQ](ja/faq.md)
+   * [一般的なFAQ](ja/faq_general.md)
+   * [QMKのビルド/コンパイル](ja/faq_build.md)
+   * [QMKのデバッグ/トラブルシューティング](ja/faq_debug.md)
+   * [キーマップ](ja/faq_keymap.md)
+   * [Zadigを使ったドライバのインストール](ja/driver_installation_zadig.md)
+* 詳細なガイド
+   * [ビルドツールのインストール](ja/getting_started_build_tools.md)
+   * [Vagrantのガイド](ja/getting_started_vagrant.md)
+   * [ビルド/コンパイルの説明](ja/getting_started_make_guide.md)
+   * [ファームウェアのフラッシュ](ja/flashing.md)
+   * [機能のカスタマイズ](ja/custom_quantum_functions.md)
+   * [キーマップの概要](ja/keymap.md)
+* [ハードウェア](ja/hardware.md)
+   * [AVR プロセッサ](ja/hardware_avr.md)
+   * [ドライバ](ja/hardware_drivers.md)
+* リファレンス
+   * [キーボード ガイドライン](ja/hardware_keyboard_guidelines.md)
+   * [設定オプション](ja/config_options.md)
+   * [キーコード](ja/keycodes.md)
+   * [コーディング規約 - C](ja/coding_conventions_c.md)
+   * [コーディング規約 - Python](ja/coding_conventions_python.md)
+   * [ドキュメント ベストプラクティス](ja/documentation_best_practices.md)
+   * [ドキュメント テンプレート](ja/documentation_templates.md)
+   * [用語](ja/reference_glossary.md)
+   * [ユニットテスト](ja/unit_testing.md)
+   * [便利な関数](ja/ref_functions.md)
+   * [Configurator サポート](ja/reference_configurator_support.md)
+   * [info.json 形式](ja/reference_info_json.md)
+   * [Python CLI 開発](ja/cli_development.md)
+* [機能](ja/features.md)
+   * [基本的なキーコード](ja/keycodes_basic.md)
+   * [US ANSI シフトキー](ja/keycodes_us_ansi_shifted.md)
+   * [Quantum キーコード](ja/quantum_keycodes.md)
+   * [Advanced キーコード](ja/feature_advanced_keycodes.md)
+   * [オーディオ](ja/feature_audio.md)
+   * [自動シフト](ja/feature_auto_shift.md)
+   * [バックライト](ja/feature_backlight.md)
+   * [ブルートゥース](ja/feature_bluetooth.md)
+   * [ブートマジック](ja/feature_bootmagic.md)
+   * [コンボ](ja/feature_combo.md)
+   * [コマンド](ja/feature_command.md)
+   * [Debounce API](ja/feature_debounce_type.md)
+   * [DIP スイッチ](ja/feature_dip_switch.md)
+   * [動的マクロ](ja/feature_dynamic_macros.md)
+   * [エンコーダ](ja/feature_encoders.md)
+   * [グレイブ エスケープ](ja/feature_grave_esc.md)
+   * [触覚フィードバック](ja/feature_haptic_feedback.md)
+   * [HD44780 LCD コントローラ](ja/feature_hd44780.md)
+   * [キーロック](ja/feature_key_lock.md)
+   * [レイアウト](ja/feature_layouts.md)
+   * [リーダー キー](ja/feature_leader_key.md)
+   * [LED マトリクス](ja/feature_led_matrix.md)
+   * [マクロ](ja/feature_macros.md)
+   * [マウスキー](ja/feature_mouse_keys.md)
+   * [OLED ドライバ](ja/feature_oled_driver.md)
+   * [One Shot Keys](ja/feature_advanced_keycodes.md#one-shot-keys)
+   * [ポインティング デバイス](ja/feature_pointing_device.md)
+   * [PS/2 マウス](ja/feature_ps2_mouse.md)
+   * [RGB ライト](ja/feature_rgblight.md)
+   * [RGB マトリクス](ja/feature_rgb_matrix.md)
+   * [Space Cadet](ja/feature_space_cadet.md)
+   * [分割キーボード](ja/feature_split_keyboard.md)
+   * [Stenography](ja/feature_stenography.md)
+   * [Swap Hands](ja/feature_swap_hands.md)
+   * [タップ ダンス](ja/feature_tap_dance.md)
+   * [Terminal](ja/feature_terminal.md)
+   * [感熱式プリンタ](ja/feature_thermal_printer.md)
+   * [ユニコード](ja/feature_unicode.md)
+   * [Userspace](ja/feature_userspace.md)
+   * [Velocikey](ja/feature_velocikey.md)
+* メーカーおよびモッダーのために
+   * [Hand Wiring Guide](ja/hand_wire.md)
+   * [ISP Flashing Guide](ja/isp_flashing_guide.md)
+   * [ARM デバッグ ガイド](ja/arm_debugging.md)
+   * [I2C ドライバ](ja/i2c_driver.md)
+   * [GPIO コントロール](ja/internals_gpio_control.md)
+   * [Proton C 規約](ja/proton_c_conversion.md)
+* より深く知るために
+   * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
+   * [QMKの理解](ja/understanding_qmk.md)
+* 他の話題
+   * [EclipseでQMKを使用](ja/other_eclipse.md)
+   * [VSCodeでQMKを使用](ja/other_vscode.md)
+   * [サポート](ja/support.md)
+   * [翻訳を追加する方法](ja/translating.md)
+* QMK の内部詳細(作成中)
+   * [定義](ja/internals_defines.md)
+   * [Input Callback Reg](ja/internals_input_callback_reg.md)
+   * [Midi ドライバ](ja/internals_midi_device.md)
+   * [Midi デバイスのセットアップ手順](ja/internals_midi_device_setup_process.md)
+   * [Midi ユーティリティ](ja/internals_midi_util.md)
+   * [Send Functions](ja/internals_send_functions.md)
+   * [Sysex Tools](ja/internals_sysex_tools.md)
diff --git a/docs/ja/arm_debugging.md b/docs/ja/arm_debugging.md
new file mode 100644
index 000000000..6267d0f8a
--- /dev/null
+++ b/docs/ja/arm_debugging.md
@@ -0,0 +1,92 @@
+# Eclipse を使った ARM デバッグ
+<!---
+  original document: eae21eed7:docs/arm_debugging.md
+  git diff eae21eed7 HEAD -- docs/arm_debugging.md | cat
+-->
+このページでは、SWD アダプタとオープンソース/フリーツールを使って ARM MCU をデバッグするためのセットアップ方法について説明します。このガイドでは、GNU MCU Eclipse IDE for C/C++ Developers および OpenOCD を必要な依存関係と一緒にインストールします。
+このガイドは上級者向けであり、あなたのマシンで、MAKE フローを使って、ARM 互換キーボードをコンパイルできることを前提にしています。
+## ソフトウェアのインストール
+ここでの主な目的は MCU Eclipse IDE を正しくマシンにインストールすることです。必要な手順は[この](https://gnu-mcu-eclipse.github.io/install/)インストールガイドから派生しています。
+### xPack マネージャ
+このツールはソフトウェアパッケージマネージャであり、必要な依存関係を取得するために使われます。
+XPM は Node.js を使って実行されるため、[ここ](https://nodejs.org/en/)から取得してください。インストール後に、ターミナルを開き `npm -v` と入力します。バージョン番号が返ってくるとインストールは成功です。
+XPM のインストール手順は[ここ](https://www.npmjs.com/package/xpm)で見つけることができ、OS 固有のものです。ターミナルに `xpm --version` と入力すると、ソフトウェアのバージョンが返ってくるはずです。
+### ARM ツールチェーン
+XPM を使うと、ARM ツールチェーンをとても簡単にインストールできます。`xpm install --global @xpack-dev-tools/arm-none-eabi-gcc` とコマンドを入力します。
+### Windows ビルドツール
+Windows を使っている場合は、これをインストールする必要があります！
+`xpm install --global @gnu-mcu-eclipse/windows-build-tools`
+### プログラマ/デバッガドライバ
+プログラマのドライバをインストールします。このチュートリアルはほとんどどこでも入手できる ST-Link v2 を使って作成されました。
+ST-Link を持っている場合は、ドライバは[ここ](https://www.st.com/en/development-tools/stsw-link009.html)で見つけることができます。そうでない場合はツールの製造元にお問い合わせください。
+### OpenOCD
+この依存関係により、SWD は GDB からアクセスでき、デバッグに不可欠です。`xpm install --global @xpack-dev-tools/openocd` を実行します。
+### Java
+Java は Eclipse で必要とされるため、[ここ](https://www.oracle.com/technetwork/java/javase/downloads/index.html)からダウンロードしてください。
+### GNU MCU Eclipse IDE
+最後に IDE をインストールする番です。[ここ](https://github.com/gnu-mcu-eclipse/org.eclipse.epp.packages/releases/)のリリースページから最新バージョンを取得します。
+## Eclipse の設定
+ダウンロードした Eclipse IDE を開きます。QMK ディレクトリをインポートするために、File -> Import -> C/C++ -> Existing Code as Makefile Project を選択します。Next を選択し、Browse を使用して QMK フォルダを選択します。tool-chain リストから ARM Cross GCC を選択し、Finish を選択します。
+これで、左側に QMK フォルダが表示されます。右クリックして、Properties を選択します。左側で MCU を展開し、ARM Toolchains Paths を選択します。xPack を押して OK を押します。OpenOCD Path で同じことを繰り返し、Windows の場合は、Build Tools Path でも同じことを繰り返します。Apply and Close を選択します。
+ここで、必要な MCU パッケージをインストールします。Window -> Perspective -> Open Perspective -> Other... -> Packs を選択して、Packs perspective に移動します。Packs タブの横にある黄色のリフレッシュ記号を選択します。これは様々な場所から MCU の定義を要求するため、時間が掛かります。一部のリンクが失敗した場合は、おそらく Ignore を選択できます。
+これが終了すると、ビルドやデバッグする MCU を見つけることができるはずです。この例では、STM32F3 シリーズの MCU を使います。左側で、STMicroelectronics -> STM32F3 Series を選択します。中央のウィンドウに、pack が表示されます。右クリックし、Install を選択します。それが終了したら、Window -> Perspective -> Open Perspective -> Other... -> C/C++ を選択してデフォルトのパースペクティブに戻ることができます。
+Eclipse に QMK をビルドしようとするデバイスを教える必要があります。QMK フォルダを右クリック -> Properties -> C/C++ Build -> Settings を選択します。Devices タブを選択し、Devices の下から MCU の適切な種類を選択します。私の例では、STM32F303CC です。
+この間に、Build コマンドもセットアップしましょう。C/C++ Build を選択し、Behavior タブを選択します。build コマンドのところで、`all` を必要な make コマンドに置き換えます。例えば、rev6 Planck の default キーマップの場合、これは `planck/rev6:default` になります。Apply and Close を選択します。
+## ビルド
+全て正しくセットアップできていれば、ハンマーボタンを押すとファームウェアがビルドされ、.binファイルが出力されるはずです。
+## デバッグ
+### デバッガの接続
+ARM MCU は、クロック信号(SWCLK) とデータ信号(SWDIO) で構成される Single Wire Debug (SWD) プロトコルを使います。MCUを 完全に操作するには、この2本のワイヤとグラウンドを接続するだけで十分です。ここでは、キーボードは USB を介して電力が供給されると想定しています。手動でリセットボタンを使えるため、RESET 信号は必要ありません。より高度なセットアップのために printf と scanf をホストに非同期にパイプする SWO 信号を使用できますが、私たちのセットアップでは無視します。
+注意: SWCLK と SWDIO ピンがキーボードのマトリックスで使われていないことを確認してください。もし使われている場合は、一時的に他のピンに切り替えることができます。
+### デバッガの設定
+QMK フォルダを右クリックし、Debug As -> Debug Configurations... を選択します。ここで、GDB OpenOCD Debugging をダブルクリックします。Debugger タブを選択し、MCU に必要な設定を入力します。これを見つけるにはいじったりググったりする必要があるかもしれません。STM32F3 用のデフォルトスクリプトは stm32f3discovery.cfg と呼ばれます。OpenOCD に伝えるには、Config options で `-f board/stm32f3discovery.cfg` と入力します。
+注意: 私の場合、この設定スクリプトはリセット操作を無効にするために編集が必要です。スクリプトの場所は、通常はパス `openocd/version/.content/scripts/board` の下の実際の実行可能フィールドの中で見つかります。ここで、私は `reset_config srst_only` を `reset_config none` に編集しました。
+Apply and Close を選択します。
+### デバッガの実行
+キーボードをリセットしてください。
+虫アイコンをクリックし、もし全てうまく行けば Debug パースペクティブに移動します。ここでは、main 関数の最初でプログラムカウンタが停止するので、Play ボタンを押します。全てのデバッガのほとんどの機能は ARM MCU で動作しますが、正確な詳細については google があなたのお友達です！
+ハッピーデバッギング！
diff --git a/docs/ja/cli.md b/docs/ja/cli.md
new file mode 100644
index 000000000..ef3752873
--- /dev/null
+++ b/docs/ja/cli.md
@@ -0,0 +1,227 @@
+# QMK CLI
+<!---
+  original document: d598f01cb:docs/cli.md
+  git diff d598f01cb HEAD -- docs/cli.md | cat
+-->
+このページは QMK CLI のセットアップと使用方法について説明します。
+# 概要
+QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。
+* [グローバル CLI](#global-cli)
+* [ローカル CLI](#local-cli)
+* [CLI コマンド](#cli-commands)
+# 必要事項
+CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) にリストされているパッケージもインストールする必要があります。
+# グローバル CLI :id=global-cli
+QMK は、QMK ビルド環境のセットアップ、QMK の操作、および `qmk_firmware` の複数のコピーの操作を容易にできるインストール可能な CLI を提供します。これを定期的にインストールおよび更新することをお勧めします。
+## Homebrew を使ったインストール (macOS、いくつかの Linux)
+[Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます:
+```
+brew tap qmk/qmk
+brew install qmk
+export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します
+qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
+```
+## easy_install あるいは pip を使ってインストール
+上のリストにあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.5 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします:
+```
+pip3 install qmk
+export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します
+qmk setup  # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします
+```
+## 他のオペレーティングシステムのためのパッケージ
+より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください:
+* これらのガイドラインと矛盾する場合は、OS のベストプラクティスに従ってください
+   * 逸脱する場合は、理由をコメントに文章化してください。
+* virtualenv を使ってインストールしてください
+* 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。
+# ローカル CLI :id=local-cli
+グローバル CLI を使いたくない場合は、`qmk_firmware` に付属のローカル CLI があります。`qmk_firmware/bin/qmk` で見つけることができます。任意のディレクトリから `qmk` コマンドを実行でき、常に `qmk_firmware` のコピー上で動作します。
+**例**:
+```
+$ ~/qmk_firmware/bin/qmk hello
+Ψ Hello, World!
+```
+## ローカル CLI の制限
+グローバル CLI と比較して、ローカル CLI には幾つかの制限があります:
+* ローカル CLI は `qmk setup` あるいは `qmk clone` をサポートしません。
+* 複数のリポジトリがクローンされている場合でも、ローカル CLI は常に `qmk_firmware` ツリー上で動作します。
+* ローカル CLI は virtualenv で動作しません。そのため依存関係が競合する可能性があります
+# CLI コマンド :id=cli-commands
+## `qmk cformat`
+このコマンドは clang-format を使って C コードを整形します。引数無しで実行して全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。
+**使用法**:
+```
+qmk cformat [file1] [file2] [...] [fileN]
+```
+## `qmk compile`
+このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルすることができます。
+**Configurator Exports での使い方**:
+```
+qmk compile <configuratorExport.json>
+```
+**キーマップでの使い方**:
+```
+qmk compile -kb <keyboard_name> -km <keymap_name>
+```
+## `qmk flash`
+このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。
+違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、<https://docs.qmk.fm/#/ja/flashing>
+を見てください。
+**Configurator Exports での使い方**:
+```
+qmk flash <configuratorExport.json> -bl <bootloader>
+```
+**キーマップでの使い方**:
+```
+qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader>
+```
+**ブートローダのリスト**
+```
+qmk flash -b
+```
+## `qmk config`
+このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。
+**使用法**:
+```
+qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN]
+```
+## `qmk docs`
+このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。
+**使用法**:
+```
+qmk docs [-p PORT]
+```
+## `qmk doctor`
+このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。
+**使用法**:
+```
+qmk doctor
+```
+## `qmk json-keymap`
+QMK Configurator からエクスポートしたものから keymap.c を生成します。
+**使用法**:
+```
+qmk json-keymap [-o OUTPUT] filename
+```
+## `qmk kle2json`
+このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。
+**使用法**:
+```
+qmk kle2json [-f] <filename>
+```
+**例**:
+```
+$ qmk kle2json kle.txt 
+☒ File info.json already exists, use -f or --force to overwrite.
+```
+```
+$ qmk kle2json -f kle.txt -f
+Ψ Wrote out to info.json
+```
+## `qmk list-keyboards`
+このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードをリスト化します。
+**使用法**:
+```
+qmk list-keyboards
+```
+## `qmk new-keymap`
+このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。
+**使用法**:
+```
+qmk new-keymap [-kb KEYBOARD] [-km KEYMAP]
+```
+## `qmk pyformat`
+このコマンドは `qmk_firmware` 内の python コードを整形します。
+**使用法**:
+```
+qmk pyformat
+```
+## `qmk pytest`
+このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。
+**使用法**:
+```
+qmk pytest
+```
diff --git a/docs/ja/cli_configuration.md b/docs/ja/cli_configuration.md
new file mode 100644
index 000000000..7e9c3e57f
--- /dev/null
+++ b/docs/ja/cli_configuration.md
@@ -0,0 +1,126 @@
+# QMK CLI 設定
+<!---
+  original document: d598f01cb:docs/cli_configuration.md
+  git diff d598f01cb HEAD -- docs/cli_configuration.md | cat
+-->
+このドキュメントは `qmk config` がどのように動作するかを説明します。
+# はじめに
+QMK CLI の設定はキーバリューシステムです。各キーはピリオドで区切られたサブコマンドと引数名で構成されます。これにより、設定キーと設定された引数の間で簡単かつ直接的な変換が可能になります。
+## 簡単な例
+例として、`qmk compile --keyboard clueboard/66/rev4 --keymap default` コマンドを見てみましょう。
+設定から読み取ることができる2つのコマンドライン引数があります:
+* `compile.keyboard`
+* `compile.keymap`
+これらを設定してみましょう:
+```
+$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default
+compile.keyboard: None -> clueboard/66/rev4
+compile.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+これで、毎回キーボードとキーマップを設定することなく、`qmk compile` を実行することができます。
+## ユーザデフォルトの設定
+複数のコマンド間で設定を共有したい場合があります。例えば、いくつかのコマンドは引数 `--keyboard` を受け取ります。全てのコマンドでこの値を設定する代わりに、その引数を受け取る全てのコマンドで使われるユーザ値を設定することができます。
+例:
+```
+$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default
+user.keyboard: None -> clueboard/66/rev4
+user.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+# CLI ドキュメント (`qmk config`)
+`qmk config` コマンドは基礎となる設定とやり取りするために使われます。引数無しで実行すると、現在の設定を表示します。引数が指定された場合、それらは設定トークンと見なされます。設定トークンは以下の形式の空白を含まない文字列です:
+    <subcommand|general|default>[.<key>][=<value>]
+## 設定値の設定
+設定キーに等号 (=) を入れることで、設定値を設定することができます。キーは常に完全な `<section>.<key>` 形式である必要があります。
+例:
+```
+$ qmk config default.keymap=default
+default.keymap: None -> default
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+## 設定値の読み込み
+設定全体、単一のキー、あるいはセクション全体の設定値を読み取ることができます。1つ以上の値を表示するために複数のキーを指定することができます。
+### 全体の構成例
+    qmk config
+### セクション全体の例
+    qmk config compile
+### 単一キーの例
+    qmk config compile.keyboard
+### 複数キーの例
+    qmk config user compile.keyboard compile.keymap
+## 設定値の削除
+設定値を特別な文字列 `None` に設定することで、設定値を削除することができます。
+例:
+```
+$ qmk config default.keymap=None
+default.keymap: default -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+## 複数の操作
+複数の読み込みおよび書き込み操作を1つのコマンドに組み合わせることができます。それらは順番に実行および表示されます:
+```
+$ qmk config compile default.keymap=default compile.keymap=None
+compile.keymap=skully
+compile.keyboard=clueboard/66_hotswap/gen1
+default.keymap: None -> default
+compile.keymap: skully -> None
+Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini'
+```
+# ユーザ設定オプション
+| キー | デフォルト値 | 説明 |
+|-----|---------------|-------------|
+| user.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
+| user.keymap | None | キーマップ名 (例: `default`) |
+| user.name | None | ユーザの github のユーザ名。 |
+# 全ての設定オプション
+| キー | デフォルト値 | 説明 |
+|-----|---------------|-------------|
+| compile.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
+| compile.keymap | None | キーマップ名 (例: `default`) |
+| hello.name | None | 実行時の挨拶の名前 |
+| new_keyboard.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) |
+| new_keyboard.keymap | None | キーマップ名 (例: `default`) |
diff --git a/docs/ja/config_options.md b/docs/ja/config_options.md
new file mode 100644
index 000000000..6cdbd2cf1
--- /dev/null
+++ b/docs/ja/config_options.md
@@ -0,0 +1,393 @@
+# QMK の設定
+<!---
+  original document: 0f43c2652:docs/config_options.md
+  git diff 0f43c2652 HEAD -- docs/config_options.md | cat
+-->
+QMK はほぼ無制限に設定可能です。可能なところはいかなるところでも、やりすぎな程、ユーザーがコードサイズを犠牲にしてでも彼らのキーボードをカスタマイズをすることを許しています。ただし、このレベルの柔軟性により設定が困難になります。
+QMK には主に２種類の設定ファイルがあります- `config.h` と `rules.mk`。これらのファイルは QMK の様々なレベルに存在し、同じ種類の全てのファイルは最終的な設定を構築するために組み合わされます。最低の優先度から最高の優先度までのレベルは以下の通りです:
+* QMK デフォルト
+* キーボード
+* フォルダ (最大5レべルの深さ)
+* キーマップ
+## QMK デフォルト
+QMK での全ての利用可能な設定にはデフォルトがあります。その設定がキーボード、フォルダ、あるいはキーマップレべルで設定されない場合、これが使用される設定です。
+## キーボード
+このレベルにはキーボード全体に適用される設定オプションが含まれています。一部の設定は、リビジョンあるいはほとんどのキーマップで変更されません。他の設定はこのキーボードのデフォルトに過ぎず、フォルダあるいはキーマップによって上書きされる可能性があります。
+## フォルダ
+一部のキーボードには、異なるハードウェア構成のためのフォルダとサブフォルダがあります。ほとんどのキーボードは深さ1のフォルダのみですが、QMK は最大深さ5のフォルダの構造をサポートします。各フォルダは、最終的な設定に組み込まれる独自の `config.h` と `rules.mk` ファイルを持つことができます。
+## キーマップ
+このレベルには特定のキーマップのための全てのオプションが含まれています。以前の定義を上書きしたい場合は、`#undef <variable>` を使って定義を解除し、エラー無しで再定義することができます。
+# `config.h` ファイル
+これは最初に include されるものの 1 つである C ヘッダファイルで、プロジェクト全体(もし含まれる場合)にわたって持続します。多くの変数をここで設定し、他の場所からアクセスすることができます。`config.h` ファイルでは、以下のもの以外の、他の `config.h`  ファイルやその他のファイルの include をしないでください:
+    #include "config_common.h"
+## ハードウェアオプション
+* `#define VENDOR_ID 0x1234`
+   * VID を定義します。ほとんどの DIY プロジェクトにおいて、任意のものを定義できます
+* `#define PRODUCT_ID 0x5678`
+   * PID を定義します。ほとんどの DIY プロジェクトでは、任意のものを定義できます
+* `#define DEVICE_VER 0`
+   * デバイスのバージョンを定義します (多くの場合リビジョンに使われます)
+* `#define MANUFACTURER Me`
+   * 一般的に、誰もしくはどのブランドがボードを作成したか
+* `#define PRODUCT Board`
+   * キーボードの名前
+* `#define DESCRIPTION a keyboard`
+   * キーボードの簡単な説明
+* `#define MATRIX_ROWS 5`
+   * キーボードのマトリックスの行の数
+* `#define MATRIX_COLS 15`
+   * キーボードのマトリックスの列の数
+* `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }`
+   * 行のピン、上から下へ
+* `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }`
+   * 列のピン、左から右へ
+* `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }`
+   * 参考として、キーボードで使われていないピン
+* `#define MATRIX_HAS_GHOST`
+   * マトリックスにゴーストがあるか(ありそうにないか)定義します
+* `#define DIODE_DIRECTION COL2ROW`
+   * COL2ROW あるいは ROW2COL - マトリックスがどのように設定されているか。COL2ROW は、スイッチとロウ(行)ラインの間にダイオードが黒い印をロウ(行)ラインに向けて置いてあることを意味します。
+* `#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
+   * ロウ(行)ラインとカラム(列)ラインにマップされているピンを左から右に。各スイッチが個別のピンとグラウンドに接続されているマトリックスを定義します。
+* `#define AUDIO_VOICES`
+   * (循環させるために)代替音声を有効にします
+* `#define C4_AUDIO`
+   * ピン C4 のオーディオを有効にします
+* `#define C5_AUDIO`
+   * ピン C5 のオーディオを有効にします
+* `#define C6_AUDIO`
+   * ピン C6 のオーディオを有効にします
+* `#define B5_AUDIO`
+   * ピン B5 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+* `#define B6_AUDIO`
+   * ピン B6 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+* `#define B7_AUDIO`
+   * ピン B7 のオーディオを有効にします (C[4-6]\_AUDIO の1つとともに B[5-7]\_AUDIO の1つが有効にされている場合、疑似ステレオが有効にされます)
+* `#define BACKLIGHT_PIN B7`
+   * バックライトのピン
+* `#define BACKLIGHT_LEVELS 3`
+   * バックライトのレベル数 (off を除いて最大15)
+* `#define BACKLIGHT_BREATHING`
+   * バックライトのブレスを有効にします
+* `#define BREATHING_PERIOD 6`
+   * 1つのバックライトの "ブレス" の長さの秒数
+* `#define DEBOUNCE 5`
+   * ピンの値を読み取る時の遅延 (5がデフォルト)
+* `#define LOCKING_SUPPORT_ENABLE`
+   * メカニカルロックのサポート。キーマップで KC_LCAP、 KC_LNUM そして KC_LSCR を使えるようにします
+* `#define LOCKING_RESYNC_ENABLE`
+   * キーボードの LED の状態をスイッチの状態と一致させ続けようとします
+* `#define IS_COMMAND() (get_mods() == MOD_MASK_SHIFT)`
+   * マジックコマンドの使用を可能にするキーの組み合わせ (デバッグに便利です)
+* `#define USB_MAX_POWER_CONSUMPTION 500`
+   * デバイスの USB 経由の最大電力(mA) を設定します (デフォルト: 500)
+* `#define USB_POLLING_INTERVAL_MS 10`
+   * キーボード、マウス および 共有 (NKRO/メディアキー) インタフェースのための USB ポーリングレートをミリ秒で設定します
+* `#define F_SCL 100000L`
+   * I2C を使用するキーボードのための I2C クロックレート速度を設定します。デフォルトは `400000L` ですが、`split_common` を使っているキーボードは別でデフォルトは `100000L` です。
+## 無効にできる機能
+これらのオプションを定義すると、関連する機能が無効になり、コードサイズを節約できます。
+* `#define NO_DEBUG`
+   * デバッグを無効にします
+* `#define NO_PRINT`
+   * hid_listen を使った出力やデバッグを無効にします
+* `#define NO_ACTION_LAYER`
+   * レイヤーを無効にします
+* `#define NO_ACTION_TAPPING`
+   * タップダンスと他のタップ機能を無効にします
+* `#define NO_ACTION_ONESHOT`
+   * ワンショットモディファイアを無効にします
+* `#define NO_ACTION_MACRO`
+   * 古い形式のマクロ処理を無効にします: MACRO() & action_get_macro
+* `#define NO_ACTION_FUNCTION`
+   * fn_actions 配列(非推奨)からの action_function() の呼び出しを無効にします 
+## 有効にできる機能
+これらのオプションを定義すると、関連する機能が有効になり、コードサイズが大きくなるかもしれません。
+* `#define FORCE_NKRO`
+   * NKRO をデフォルトでオンにする必要があります。これにより EEPROM の設定に関係なく、キーボードの起動時に NKRO が強制的にオンになります。NKRO は引き続きオフにできますが、キーボードを再起動すると再びオンになります。
+* `#define STRICT_LAYER_RELEASE`
+   * キーリリースがどのレイヤーから来たのかを覚えるのではなく、現在のレイヤースタックを使って強制的に評価されるようにします (高度なケースに使われます)
+## 設定可能な挙動
+* `#define TAPPING_TERM 200`
+   * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照)
+* `#define TAPPING_TERM_PER_KEY`
+   * キーごとの `TAPPING_TERM` 設定の処理を有効にします
+* `#define RETRO_TAPPING`
+   * 押下とリリースの間に他のキーによる中断がなければ、TAPPING_TERM の後であってもとにかくタップします
+   * 詳細は [Retro Tapping](ja/feature_advanced_keycodes.md#retro-tapping) を見てください
+* `#define TAPPING_TOGGLE 2`
+   * トグルを引き起こす前のタップ数
+* `#define PERMISSIVE_HOLD`
+   * `TAPPING_TERM` にヒットしていなくても、リリースする前に別のキーが押されると、タップとフォールドキーがホールドを引き起こします
+   * 詳細は [Permissive Hold](ja/feature_advanced_keycodes.md#permissive-hold) を見てください
+* `#define IGNORE_MOD_TAP_INTERRUPT`
+   * 両方のキーに `TAPPING_TERM` を適用することで、ホールド時に他のキーに変換するキーを使ってローリングコンボ (zx) をすることができるようにします
+   * 詳細は [Mod tap interrupt](ja/feature_advanced_keycodes.md#ignore-mod-tap-interrupt) を見てください
+* `#define IGNORE_MOD_TAP_INTERRUPT_PER_KEY`
+   * キーごとの `IGNORE_MOD_TAP_INTERRUPT` 設定の処理を有効にします
+* `#define TAPPING_FORCE_HOLD`
+   * タップされた直後に、デュアルロールキーを修飾子として使用できるようにします
+   * [Hold after tap](ja/feature_advanced_keycodes.md#tapping-force-hold)を見てください
+   * タップトグル機能を無効にします (`TT` あるいは One Shot Tap Toggle)
+* `#define LEADER_TIMEOUT 300`
+   * リーダーキーがタイムアウトするまでの時間
+      * タイムアウトする前にシーケンスを終了できない場合は、タイムアウトの設定を増やす必要があるかもしれません。あるいは、`LEADER_PER_KEY_TIMING` オプションを有効にすると良いでしょう。これは各キーがタップされた後でタイムアウトを再設定します。
+* `#define LEADER_PER_KEY_TIMING`
+   * 全体では無く各キーを押すたびに実行されるリーダーキーコードのタイマーを設定します
+* `#define LEADER_KEY_STRICT_KEY_PROCESSING`
+   * Mod-Tap および Layer-Tap キーコードのためのキーコードフィルタリングを無効にします。例えば、これを有効にすると、`KC_A` を使いたい場合は `MT(MOD_CTL, KC_A)` を指定する必要があります。
+* `#define ONESHOT_TIMEOUT 300`
+   * ワンショットがタイムアウトするまでの時間
+* `#define ONESHOT_TAP_TOGGLE 2`
+   * ワンショットトグルが引き起こされるまでのタップ数
+* `#define QMK_KEYS_PER_SCAN 4`
+   * 走査ごとに1つ以上のキーを送信できるようにします。デフォルトでは、走査ごとに `process_record()` 経由で1つのキーイベントのみが送信されます。これはほとんどのタイピングにほとんど影響しませんが、多くのコードを入力しているか、走査レートが最初から遅い場合、キーイベントの処理に多少の遅延が生じる可能性があります。それぞれのプレスとリリースは別のイベントです。スキャン時間が 1ms 程度のキーボードの場合、とても高速なタイピストでさえ、実際にキーボードから数 ms 以上の遅延を発生させるのに必要な 500 キーストロークを1秒間に生成することはないでしょう。しかし、3～4ms の走査時間でコードを入力している場合はどうでしょうか？おそらくこれが必要です。
+* `#define COMBO_COUNT 2`
+   * [コンボ](ja/feature_combo.md)機能で使っているコンボの数にこれを設定します。
+* `#define COMBO_TERM 200`
+   * コンボキーが検出されるまでの時間。定義されていない場合は、デフォルトは `TAPPING_TERM` です。
+* `#define TAP_CODE_DELAY 100`
+   * 適切な登録に問題がある場合(VUSB ボードで珍しくない)、`register_code` と `unregister_code` の間の遅延を設定します。値はミリ秒です。
+* `#define TAP_HOLD_CAPS_DELAY 80`
+   * MacOS で特別な処理が行われるため、`KC_CAPSLOCK` を使う時にタップホールドキー (`LT`, `MT`) に遅延を設定します。この値はミリ秒で、定義されていない場合はデフォルトは80msです。macOS については、これを200以上に設定すると良いでしょう。
+## RGB ライト設定 :id=rgb-light-configuration
+* `#define RGB_DI_PIN D7`
+   * WS2812 の DI 端子につなぐピン
+* `#define RGBLIGHT_ANIMATIONS`
+   * RGB アニメーションを実行します
+* `#define RGBLED_NUM 12`
+   * LED の数
+* `#define RGBLIGHT_SPLIT`
+   * 分割キーボードの左半分の RGB LED の出力を右半分の RGB LED の入力につなげるかわりに、それぞれの側で個別にコントローラの出力ピンが直接 RGB LED の入力に繋がっているときは、この定義が必要です。
+* `#define RGBLED_SPLIT { 6, 6 }`
+   * 分割キーボードの各半分の `RGB_DI_PIN` に直接配線されている接続されているLEDの数
+   * 最初の値は左半分の LED の数を示し、2番目の値は右半分です。
+   * RGBLED_SPLIT が定義されている場合、RGBLIGHT_SPLIT は暗黙的に定義されます。
+* `#define RGBLIGHT_HUE_STEP 12`
+   * 色相の増減時のステップ単位
+* `#define RGBLIGHT_SAT_STEP 25`
+   * 彩度の増減時のステップ単位
+* `#define RGBLIGHT_VAL_STEP 12`
+   * 値(明度)の増減時のステップ単位
+* `#define RGBW`
+   * RGBW LED のサポートを有効にします
+## マウスキーオプション
+* `#define MOUSEKEY_INTERVAL 20`
+* `#define MOUSEKEY_DELAY 0`
+* `#define MOUSEKEY_TIME_TO_MAX 60`
+* `#define MOUSEKEY_MAX_SPEED 7`
+* `#define MOUSEKEY_WHEEL_DELAY 0`
+## 分割キーボードオプション
+分割キーボード固有のオプション。あなたの rules.mk に 'SPLIT_KEYBOARD = yes' が有ることを確認してください。
+* `SPLIT_TRANSPORT = custom`
+   * 標準の分割通信ルーチンをカスタムのものに置き換えることができます。現在、ARM ベースの分割キーボードはこれを使わなければなりません。
+### 左右の設定
+一つ覚えておかなければならないことは、USB ポートが接続されている側が常にマスター側であるということです。USB に接続されていない側はスレーブです。
+分割キーボードの左右を設定するには、幾つかの異なる方法があります (優先度の順にリストされています):
+1. `SPLIT_HAND_PIN` を設定します: 左右を決定するためにピンを読み込みます。ピンが high の場合、それが左側です。low であれば、その半分側が右側であると決定されます。
+2. `EE_HANDS` を設定し、各半分に `eeprom-lefthand.eep`/`eeprom-righthand.eep` を書き込みます
+   * DFU ブートローダを搭載したボードでは、これらの EEPROM ファイルを書き込むために `:dfu-split-left`/`:dfu-split-right` を使うことができます
+   * Caterina ブートローダを搭載したボード (標準的な Pro Micros など)では、`:avrdude-split-left`/`:avrdude-split-right` を使ってください
+   * ARM DFU ブートローダを搭載したボード (Proton C など)では、`:dfu-util-split-left`/`:dfu-util-split-right` を使ってください
+3. `MASTER_RIGHT` を設定します: USBポートに差し込まれた側はマスター側で右側であると決定されます(デフォルトの逆)
+4. デフォルト: USB ポートに差し込まれている側がマスター側であり、左側であると見なされます。スレーブ側は右側です
+#### 左右を定義します
+* `#define SPLIT_HAND_PIN B7`
+   * high/low ピンを使って左右を決定します。low = 右手、high = 左手。`B7` を使っているピンに置き換えます。これはオプションで、`SPLIT_HAND_PIN` が未定義のままである場合、EE_HANDS メソッドまたは標準の Let's Splitが使っている MASTER_LEFT / MASTER_RIGHT 定義をまだ使うことができます。
+* `#define EE_HANDS` (`SPLIT_HAND_PIN` が定義されていない場合のみ動作します)
+   * `eeprom-lefthand.eep`/`eeprom-righthand.eep` がそれぞれの半分に書き込まれた後で、EEPROM 内に格納されている左右の設定の値を読み込みます。
+* `#define MASTER_RIGHT`
+   * マスター側が右側と定義されます。
+### 他のオプション
+* `#define USE_I2C`
+   * Serial の代わりに I2C を使う場合 (デフォルトは serial)
+* `#define SOFT_SERIAL_PIN D0`
+   * serial を使う場合、これを定義します。`D0` あるいは `D1`,`D2`,`D3`,`E6`。
+* `#define MATRIX_ROW_PINS_RIGHT { <row pins> }`
+* `#define MATRIX_COL_PINS_RIGHT { <col pins> }`
+   * 右半分に左半分と異なるピン配置を指定したい場合は、`MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT` を定義することができます。現在のところ、`MATRIX_ROW_PINS` のサイズは `MATRIX_ROW_PINS_RIGHT` と同じでなければならず、列の定義も同様です。
+* `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }`
+   * 右半分に左半分と異なる直接ピン配置を指定したい場合は、`DIRECT_PINS_RIGHT` を定義することができます。現在のところ、`DIRECT_PINS` のサイズは `DIRECT_PINS_RIGHT` と同じでなければなりません。
+* `#define RGBLED_SPLIT { 6, 6 }`
+   * [RGB ライト設定](#rgb-light-configuration)を見てください。
+* `#define SELECT_SOFT_SERIAL_SPEED <speed>` (デフォルトの速度は1です)
+   * serial 通信を使う時のプロトコルの速度を設定します。
+   * 速度:
+      * 0: 約189kbps (実験目的のみ)
+      * 1: 約 137kbps (デフォルト)
+      * 2: 約 75kbps
+      * 3: 約 39kbps
+      * 4: 約 26kbps
+      * 5: 約 20kbps
+* `#define SPLIT_USB_DETECT`
+   * マスタ/スレーブを委任する時に(タイムアウト付きで) USB 接続を検出します
+   * ARM についてはデフォルトの挙動
+   * AVR Teensy については必須
+* `#define SPLIT_USB_TIMEOUT 2500`
+   * `SPLIT_USB_DETECT` を使う時のマスタ/スレーブを検出する場合の最大タイムアウト
+# `rules.mk` ファイル
+これは、トップレベルの `Makefile` から include される [make](https://www.gnu.org/software/make/manual/make.html) ファイルです。これは特定の機能を有効または無効にするだけでなく、コンパイルする MCU に関する情報を設定するために使われます。
+## ビルドオプション
+* `DEFAULT_FOLDER`
+   * キーボードに1つ以上のサブフォルダがある場合にデフォルトのフォルダを指定するために使われます。
+* `FIRMWARE_FORMAT`
+   * ビルドの後でルート `qmk_firmware` フォルダにコピーされる形式 (bin, hex) を定義します。
+* `SRC`
+   * コンパイル・リンクリストにファイルを追加するために使われます。
+* `LIB_SRC`
+  * コンパイル・リンクリストにライブラリとしてファイルを追加するために使われます。  
+    `LIB_SRC` で指定されたファイルは、`SRC` で指定されたファイルの後にリンクされます。  
+    例えば、次のように指定した場合:
+    ```
+    SRC += a.c
+    LIB_SRC += lib_b.c
+    SRC += c.c
+    LIB_SRC += lib_d.c
+    ```
+    リンク順は以下の通りです。
+    ```
+     ...  a.o c.o  ...  lib_b.a lib_d.a  ...
+    ```
+* `LAYOUTS`
+   * このキーボードがサポートする[レイアウト](ja/feature_layouts.md)のリスト
+* `LINK_TIME_OPTIMIZATION_ENABLE`
+   * キーボードをコンパイルする時に、Link Time Optimization (`LTO`) を有効にします。これは処理に時間が掛かりますが、コンパイルされたサイズを大幅に減らします (そして、ファームウェアが小さいため、追加の時間は分からないくらいです)。ただし、`LTO` が有効な場合、古いマクロと関数の機能が壊れるため、自動的にこれらの機能を無効にします。これは `NO_ACTION_MACRO` と `NO_ACTION_FUNCTION` を自動的に定義することで行われます。
+* `LTO_ENABLE`
+   * LINK_TIME_OPTIMIZATION_ENABLE と同じ意味です。`LINK_TIME_OPTIMIZATION_ENABLE` の代わりに `LTO_ENABLE` を使うことができます。
+## AVR MCU オプション
+* `MCU = atmega32u4`
+* `F_CPU = 16000000`
+* `ARCH = AVR8`
+* `F_USB = $(F_CPU)`
+* `OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT`
+* `BOOTLOADER = atmel-dfu` と以下のオプション:
+   * `atmel-dfu`
+   * `lufa-dfu`
+   * `qmk-dfu`
+   * `halfkay`
+   * `caterina`
+   * `bootloadHID`
+   * `USBasp`
+## 機能オプション
+これらを使って特定の機能のビルドを有効または無効にします。有効にすればするほどファームウェアが大きくなり、MCU には大きすぎるファームウェアを構築するリスクがあります。
+* `BOOTMAGIC_ENABLE`
+   * 仮想 DIP スイッチ設定
+* `MOUSEKEY_ENABLE`
+   * マウスキー
+* `EXTRAKEY_ENABLE`
+   * オーディオ制御とシステム制御
+* `CONSOLE_ENABLE`
+   * デバッグ用コンソール
+* `COMMAND_ENABLE`
+   * デバッグ及び設定用のコマンド
+* `COMBO_ENABLE`
+   * キーコンボ機能
+* `NKRO_ENABLE`
+   * USB N-キーロールオーバー - これが動作しない場合は、ここを見てください: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
+* `AUDIO_ENABLE`
+   * オーディオサブシステムを有効にします。
+* `RGBLIGHT_ENABLE`
+   * キーボードアンダーライト機能を有効にします
+* `LEADER_ENABLE`
+   * リーダーキーコードを有効にします
+* `MIDI_ENABLE`
+   * MIDI 制御
+* `UNICODE_ENABLE`
+   * Unicode
+* `BLUETOOTH_ENABLE`
+   * Adafruit EZ-Key HID で Bluetooth を有効にするレガシーオプション。BLUETOOTH を見てください
+* `BLUETOOTH`
+   * 現在のオプションは、AdafruitEzKey、AdafruitBLE、RN42
+* `SPLIT_KEYBOARD`
+   * 分割キーボード (let's split や bakingpy のキーボードのようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
+* `CUSTOM_MATRIX`
+   * 標準マトリックス走査ルーチンを独自のものに置き換えることができます。
+* `DEBOUNCE_TYPE`
+   * 標準キーデバウンスルーチンを代替または独自のものに置き換えることができます。
+* `WAIT_FOR_USB`
+   * キーボードが起動する前に、USB 接続が確立されるのをキーボードに待機させます
+* `NO_USB_STARTUP_CHECK`
+   * キーボードの起動後の usb サスペンドチェックを無効にします。通常、キーボードはタスクが実行される前にホストがウェイク アップするのを待ちます。分割キーボードは半分はウェイクアップコールを取得できませんが、マスタにコマンドを送信する必要があるため、役に立ちます。
+## USB エンドポイントの制限
+USB 経由でサービスを提供するために、QMK は USB エンドポイントを使う必要があります。
+これらは有限なリソースです: 各マイクロコントローラは特定の数しか持ちません。
+これは一緒に有効にできる機能を制限します。
+利用可能なエンドポイントを超えると、ビルドエラーをひきおこします。
+以下の機能は個別のエンドポイントを必要とするかもしれません:
+* `MOUSEKEY_ENABLE`
+* `EXTRAKEY_ENABLE`
+* `CONSOLE_ENABLE`
+* `NKRO_ENABLE`
+* `MIDI_ENABLE`
+* `RAW_ENABLE`
+* `VIRTSER_ENABLE`
+エンドポイントの使用率を向上させるために、HID 機能を組み合わせて1つのエンドポイントを使うようにすることができます。
+デフォルトでは、`MOUSEKEY`、`EXTRAKEY` および `NKRO` が単一のエンドポイントに結合されます。
+基本キーボード機能も、`KEYBOARD_SHARED_EP = yes` を設定することで同じエンドポイントに結合することができます。
+これによりもう1つのエンドポイントが解放されますが、一部の BIOS ではブートキーボードプロトコルの切り替えを実装しないため、キーボードが動作しなくなるかもしれません。
+マウスの結合も、ブートマウス互換性を破壊します。
+この機能が必要な場合は、`MOUSE_SHARED_EP = no` を設定することで、マウスを結合しないようにすることができます。
diff --git a/docs/ja/contributing.md b/docs/ja/contributing.md
new file mode 100644
index 000000000..401cabcd4
--- /dev/null
+++ b/docs/ja/contributing.md
@@ -0,0 +1,173 @@
+# 貢献方法
+<!---
+  original document: d47809575:docs/contributing.md
+  git diff d47809575 HEAD -- docs/contributing.md | cat
+-->
+👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍
+サードパーティの貢献は、QMK の成長と改善に役立ちます。プルリクエストと貢献プロセスを貢献者とメンテナの両方にとって便利で簡単なものにしたいです。この目的のために、大きな変更をせずにプルリクエストが受け入れられるように貢献者向けのガイドラインをまとめました。
+* [プロジェクトの概要](#project-overview)
+* [コーディング規約](#coding-conventions)
+* [一般的なガイドライン](#general-guidelines)
+* [行動規範は私にとって何を意味しますか？](#what-does-the-code-of-conduct-mean-for-me)
+## この全てを読みたくはありません！単純に質問があります！
+QMK について質問したい場合は、[OLKB Subreddit](https://reddit.com/r/olkb) あるいは [Discord](https://discord.gg/Uq7gcHh) ですることができます。
+以下の事を覚えておいてください:
+* 誰かがあなたの質問に答えるのに数時間掛かるかもしれません。しばらくお待ちください！
+* QMK に関わる全ての人が彼らの時間とエネルギーを提供しています。QMK に関する作業や質問への回答に対する報酬はありません。
+* できるだけ簡単に答えられるように質問してみてください。その方法が分からない場合は、以下に幾つかの良いガイドがあります:
+   * https://opensource.com/life/16/10/how-ask-technical-questions
+   * http://www.catb.org/esr/faqs/smart-questions.html
+# プロジェクトの概要 :id=project-overview
+QMK は主に C で書かれており、特定の機能と部品は C++ で書かれています。QMK は、キーボードの中の組み込みプロセッサ、特に AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) と ARM ([ChibiOS](http://www.chibios.com)) を対象にしています。すでに Arduino プログラミングに精通している場合は、多くの概念と制限がおなじみのものです。QMK に貢献するには Arduino を使用した経験は必要ありません。
+<!-- FIXME: We should include a list of resources for learning C here. -->
+# どこで助けを得られますか？
+助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues) か [Discord で会話する](https://discord.gg/Uq7gcHh)ことができます。
+# どうやって貢献することができますか？
+以前にオープンソースに貢献したことはありませんか？ QMK で貢献がどのように機能するかが疑問ですか？ ここに簡単な説明があります！
+0. [GitHub](https://github.com) アカウントにサインアップします。
+1. 貢献するためのキーマップをまとめるか、解決に興味がある[問題を見つける](https://github.com/qmk/qmk_firmware/issues)、あるいは追加したい[機能](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)を見つけます。
+2. 問題に関連付けられているリポジトリをあなたの GitHub アカウントにフォークします。これは、`GitHub上のあなたのユーザー名/qmk_firmware` の下にリポジトリのコピーを持つことを意味します。
+3. `git clone https://github.com/GitHub上のあなたのユーザー名/repository-name.git` を使ってローカルマシンにリポジトリをクローンします。
+4. 新しい機能に取り組んでいる場合は、issue を開きこれから行う作業について話し合うことを検討してください。
+5. `git checkout -b branch-name-here` を使って修正用の新しいブランチを作成します。
+6. 解決しようとしている問題、あるいは追加したい機能について適切な変更を加えます。
+7. `git add insert-paths-of-changed-files-here` を使って変更されたファイルの内容を git がプロジェクトの状態を管理するために使用する "snapshot"、インデックスとしても知られている、に追加します。
+8. `git commit -m "Insert a short message of the changes made here"` を使って、説明的なメッセージとともにインデックスの内容を保存します。
+9. `git push origin branch-name-here` を使って GitHub 上のリポジトリに変更をプッシュします。
+10. プルリクエストを [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master) にサブミットします。
+11. 行われた変更の簡単な説明と、変更に関する問題またはバグ番号を使って、プルリクエストにタイトルを付けます。例えば、issue に "Added more log outputting to resolve #4352" のようなタイトルをつけることができます。
+12. プルリクエストの説明では、行った変更、行ったプルリクエストに存在すると思われる問題、およびメンテナに対する質問を説明します。プルリクエストが完ぺきではない場合(プルリクエストが無い場合)でも問題ありません。レビュワーが問題の修正と改善を手伝います。
+13. プルリクエストがメンテナによってレビューされるのを待ちます。
+14. レビューをしているメンテナが変更を推奨する場合は、プルリクエストに変更を加えます。
+15. プルリクエストがマージされた後で成功を祝います！
+# コーディング規約 :id=coding-conventions
+私たちのスタイルのほとんどは簡単に理解できます。C あるいは Python のいずれかに精通している場合は、ローカルスタイルにそれほど問題はないはずです。
+* [コーディング規約 - C](ja/coding_conventions_c.md)
+* [コーディング規約 - Python](ja/coding_conventions_python.md)
+# 一般的なガイドライン :id=general-guidelines
+QMK には幾つかの異なるタイプの変更があり、それぞれ異なるレベルの厳密さが必要です。どのような種類の変更を行っても、次のガイドラインに留意してください。
+* PR を論理単位に分割します。例えば、2つの個別の機能をカバーする1つの PR を送信するのではなく、代わりに機能ごとに個別の PR をサブミットします。
+* コミットする前に、`git diff --check` を使って不要な空白を確認します。
+* コードの変更が実際にコンパイルされることを確認してください。
+   * キーマップ: `make keyboard:your_new_keymap` がエラーを返さないことを確認してください。
+   * キーボード: `make keyboard:all` がエラーを返さないことを確認してください。
+   * コア: `make all` がエラーを返さないことを確認してください。
+* コミットメッセージがそれ自体で理解できることを確認してください。最初の行に短い説明(70文字以内)を入れ、2行目は空にし、3行目以降では必要に応じてコミットを詳細に説明する必要があります。例:
+```
+kerpleplork の fronzlebop を調整します
+kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork はN回の繰り返しごとにアクティブになります。
+私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。
+```
+!> **重要:** デフォルト以外のキーマップ、ユーザスペースおよびレイアウトのようなユーザコードへのバグ修正あるいは改善に貢献したい場合は、PR にコードの元の提出者にタグをつけてください。Git と GitHub のスキルレベルに関係なく、多くのユーザは知らないうちにコードが変更されることに混乱したりイライラしたりするかもしれません。
+## ドキュメント
+ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です！私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、[助けをもとめて](#where-can-i-go-for-help)ください！
+全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、https://docs.qmk.fm/ の各ページの下部にある "Edit this page" リンクをクリックすることができます。
+ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、`my_layers` あるいは `my_keycodes` として列挙型を標準化します:
+```c
+enum my_layers {
+  _FIRST_LAYER,
+  _SECOND_LAYER
+};
+enum my_keycodes {
+  FIRST_LAYER = SAFE_RANGE,
+  SECOND_LAYER
+};
+```
+### ドキュメントのプレビュー
+開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます:
+    ./bin/qmk docs
+または、Python 3 のみがインストールされている場合:
+    python3 -m http.server 8936
+その後、ウェブブラウザで、`http://localhost:8936/` を表示します。
+## キーマップ
+ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。
+* [the template](documentation_templates.md) を使って `readme.md` を書きます。
+* 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。
+* キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。
+* `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。
+* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します)
+## キーボード
+キーボードは QMK の存在理由です。一部のキーボードはコミュニティによって管理されていますが、他のキーボードはそれぞれのキーボードを作成する責任者によって管理されています。`readme.md` を見るとそのキーボードを管理しているのが誰かが分かります。特定のキーボードに関する質問がある場合、[Issue を開いて](https://github.com/qmk/qmk_firmware/issues)質問にメンテナをタグ付けしてください。(訳注: タグ付け は [メンションする](https://help.github.com/ja/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) という意味です。)
+また以下のガイドラインに従うことをお願いします:
+* [the template](ja/documentation_templates.md) を使って `readme.md` を書きます。
+* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。
+* コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。
+* `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards/<kb1>/<kb2>/<kb2>.[ch]`
+* `Makefile` をキーボードフォルダに含めないでください(もう使われていません)
+* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します)
+## Quantum/TMK コア
+新しい機能をビルドするために多くの作業を行う前に、最適な方法で実装していることを確認する必要があります。[QMK の理解](ja/understanding_qmk.md)を読むことで、QMK の基本的な理解を得ることができます。これはあなたを QMK のプログラムフローのツアーに連れて行きます。ここから、あなたのアイデアを実装するための最良の方法の感覚をつかむために、私たちと話す必要があります。これを行うには主に2つの方法があります:
+* [Discord でのチャット](https://discord.gg/Uq7gcHh)
+* [Issue を開く](https://github.com/qmk/qmk_firmware/issues/new)
+機能とバグ修正の PR は全てのキーボードに影響します。また、私たちは QMK の再編も進めています。このため、実装が行われる前に特に重要な変更について議論することが特に重要です。最初に私たちと話をせずに PR を開いた場合、あなたの選択が私たちの計画した方向とうまく合わない場合は幾つかの大きな再作業を行う覚悟をしてください。
+機能やバグの修正に取り組む時に留意すべき幾つかの事があります。
+* **デフォルトで無効** - QMK がサポートするほとんどのチップでメモリがかなり制限されており、現在のキーマップが壊れていないことが重要です。ですので、あなたの機能をオフにするのではなく**オン**にするようにしてください。デフォルトでオンにすべき場合、あるいはコードのサイズを小さくする必要がある場合は、相談してください。
+* **サブミットする前にローカルでコンパイル** - これが明白であることを願っていますが、コンパイルする必要があります。私たちの Travis システムは全ての問題をキャッチしますが、結果が返ってくるのを待つ代わりに幾つかのキーボードをローカルでコンパイルする方が一般的に速いです。
+* **リビジョンと異なるチップベースを考慮** - 僅かに異なる設定、さらには異なるチップベースを可能にするリビジョンを持つキーボードが幾つかあります。ARM および AVR でサポートされる機能を作成する、あるいは動作しないプラットフォームでは自動的に無効化するようにしてください。
+* **機能の説明** - 新しいファイルあるいは既存のファイルの一部として、`docs/` の中に文章化します。文章化しないと、他の人はあなたの苦労から利益を得ることができません。
+また以下のガイドラインに従うことをお願いします:
+* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。
+* キーボードあるいはキーマップをコアの変更にまとめないでください。コアの変更を最初にサブミットしてください。
+* 機能のための[ユニット テスト](ja/unit_testing.md)を書いてください。
+* 編集しているファイルのスタイルに従ってください。スタイルが明確でないか、スタイルが混在している場合は、上記の[コーディング規約](#coding-conventions)に準拠する必要があります。
+## リファクタリング
+QMK で物事がどのようにレイアウトされるかについて明確なビジョンを維持するために、私たちはリファクタリングを詳細に計画し、変更をする協力者がいます。リファクタリングのアイデアあるいは提案がある場合は、[issue を開いてください](https://github.com/qmk/qmk_firmware/issues)。QMK を改善する方法についてお話ししたいと思います。
+# 行動規範は私にとって何を意味しますか？ :id=what-does-the-code-of-conduct-mean-for-me
+私たちの[行動規範](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md)は、身元に関係なくあなたがプロジェクトの全員を敬意と礼儀を持って扱う責任があることを意味します。あなたが行動規範に記載されている不適切な行動やコメントの被害者である場合は、私たちはあなたのためにここにおり、私たちのコードに従って虐待者が適切に懲戒されるように最善を尽くします。
diff --git a/docs/ja/driver_installation_zadig.md b/docs/ja/driver_installation_zadig.md
new file mode 100644
index 000000000..268940ec0
--- /dev/null
+++ b/docs/ja/driver_installation_zadig.md
@@ -0,0 +1,53 @@
+# Zadig を使ったブートローダドライバのインストール
+<!---
+  original document: d598f01cb:docs/driver_installation_zadig.md
+  git diff d598f01cb HEAD -- docs/driver_installation_zadig.md | cat
+-->
+QMK はホストにたいして通常の HID キーボードデバイスとして振る舞うため特別なドライバは必要ありません。しかし、Windows でのキーボードへの書き込みは、多くの場合、キーボードをリセットした時に現れるブートローダデバイスで*行います*。
+2つの注目すべき例外があります: 通常 Pro Micro で見られる Caterina ブートローダや、PJRC Teensy に書き込まれている HalfKay ブートローダは、それぞれシリアルポートと汎用 HID デバイスとして振る舞うため、ドライバは必要ありません。
+[Zadig](https://zadig.akeo.ie/) ユーティリティを使うことをお勧めします。MSYS2 あるいは WSL を使って開発環境をセットアップした場合、`qmk_install.sh` スクリプトはドライバをインストールするかどうかをたずねます。
+## インストール
+`RESET` キーコード (別のレイヤにあるかもしれません)を押すか、通常はキーボードの下面にあるリセットスイッチを押して、キーボードをブートローダモードにします。どちらもキーボードに無い場合は、Escape または Space+`B` を押しながら接続してみてください (詳細は、[ブートマジック](ja/feature_bootmagic.md) ドキュメントを見てください)。一部のキーボードはブートマジックの代わりに[コマンド](ja/feature_command.md)を使います。この場合、キーボードが接続されている状態で「左Shift + 右Shift + `B`」あるいは「左Shift + 右Shift + Escape」を押すと、ブートローダモードに入ることができます。
+一部のキーボードはブートローダに入るために特定の操作をする必要があります。例えば、[ブートマジック Lite](ja/feature_bootmagic.md#bootmagic-lite) キー (デフォルト: Escape) は別のキー(例えば、左Control)かもしれません。また、コマンドを有効にするキーの組み合わせ (デフォルト: 左Shift + 右Shift) は何か他のキー(例えば 左Control + 右Control)を押し続ける必要がある場合があります。不明な場合は、キーボードの README ファイルを参照してください。
+USBaspLoader を使ってデバイスをブートローダモードにするには、`BOOT` ボタンを押しながら `RESET` ボタンをタップしてください。
+あるいは `BOOT` を押し続けながら USB ケーブルを挿入します。
+Zadig は自動的にブートローダデバイスを検知します。**Options → List All Devices** を確認する必要がある場合があります。
+- Atmel AVR MCU を搭載したキーボードの場合、ブートローダは `ATm32U4DFU` に似た名前が付けられ、ベンダー ID は `03EB` です。
+- USBasp ブートローダは `USBasp` として表示され、VID/PID は`16C0:05DC` です。
+- QMK-DFU ブートローダを使って書き込まれた AVR キーボードは `<keyboard name> Bootloader` という名前が付けられ、VID は `03EB` です。
+- ほとんどの ARM キーボードでは、`STM32 BOOTLOADER` と呼ばれ、VID/PID は `0483:DF11` です。
+!> Zadig が `HidUsb` ドライバを使用する1つ以上のデバイスを表示する場合、キーボードはおそらくブートローダモードではありません。矢印はオレンジ色になり、システムドライバの変更を確認するように求められます。この場合、続行**しないでください**！
+矢印が緑色で表示されたら、ドライバを選択し、**Install Driver** をクリックします。`libusb-win32` ドライバは通常 AVR で動作し、`WinUSB`は ARM で動作しますが、それでもキーボードに書き込みできない場合は、リストから異なるドライバをインストールしてみてください。msys2 を使ってコマンドライン経由で USBaspLoader デバイスに書き込むには、`libusbk` ドライバがお勧めです。そうではなく書き込みに QMK Toolbox を使っている場合は `libusb-win32` がうまく動作します。
+![ブートローダドライバが正常にインストールされた Zadig](https://i.imgur.com/b8VgXzx.png)
+最後に、新しいドライバがロードされたことを確認するためにキーボードのプラグを抜いて再接続します。書き込みに QMK Toolbox を使う場合は、ドライバの変更を認識しない場合があるため、QMK Toolkit を終了して再起動します。
+## 間違ったデバイスのインストールからの回復
+キーボードが入力できなくなった場合は、ブートローダではなくキーボード自体のドライバを間違って入れ替えた可能性があります。これはキーボードがブートローダモードでない場合に起こりえます。これは Zadig で簡単に確認することができます - 健全なキーボードには、全てのインタフェースに `HidUsb` ドライバがインストールされています:
+![Zadig から見た健全なキーボード](https://i.imgur.com/Hx0E5kC.png)
+デバイスマネージャーを開き、キーボードと思われるデバイスを探します。
+![デバイスマネージャーにおける、間違ったドライバがインストールされたキーボード](https://i.imgur.com/L3wvX8f.png)
+右クリックし、**デバイスのアンインストール** をクリックします。最初に **このデバイスのドライバーソフトウェアを削除します** にチェックが付いていることを確認してください。
+!["ドライバの削除"にチェックボックスにチェックが付いた、デバイスのアンインストールダイアログ](https://i.imgur.com/aEs2RuA.png)
+**Action → Scan for hardware changes** をクリックします。この時点で、再び入力できるようになっているはずです。Zadig でキーボードデバイスが `HidUsb` ドライバを使っていることを再確認します。そうであれば完了です。キーボードは再び機能するはずです！
+?> Windows が新しいドライバを使えるようにするために、この時点でコンピュータを完全に再起動する必要があるかもしれません。
diff --git a/docs/ja/faq.md b/docs/ja/faq.md
new file mode 100644
index 000000000..00b0ff827
--- /dev/null
+++ b/docs/ja/faq.md
@@ -0,0 +1,11 @@
+# よくある質問
+<!---
+  original document: d598f01cb:docs/faq.md
+  git diff d598f01cb HEAD -- docs/faq.md | cat
+-->
+* [一般](ja/faq_general.md)
+* [QMK のビルドあるいはコンパイル](ja/faq_build.md)
+* [QMK のデバッグとトラブルシューティング](ja/faq_debug.md)
+* [キーマップ](ja/faq_keymap.md)
diff --git a/docs/ja/faq_build.md b/docs/ja/faq_build.md
new file mode 100644
index 000000000..9b4ce12a4
--- /dev/null
+++ b/docs/ja/faq_build.md
@@ -0,0 +1,160 @@
+# よくあるビルドの質問
+<!---
+  original document: 0f43c2652:docs/faq_build.md
+  git diff 0f43c2652 HEAD -- docs/faq_build.md | cat
+-->
+このページは QMK のビルドに関する質問を説明します。まだビルドをしていない場合は、[ビルド環境のセットアップ](ja/getting_started_build_tools.md) および [Make 手順](ja/getting_started_make_guide.md)ガイドを読むべきです。
+## Linux でプログラムできません
+デバイスを操作するには適切な権限が必要です。Linux ユーザの場合は、以下の `udev` ルールに関する指示を見てください。`udev` に問題がある場合は、回避策は `sudo` コマンドを使うことです。このコマンドに慣れていない場合は、`man sudo` コマンドでマニュアルを確認するか、[この web ページを見てください](https://linux.die.net/man/8/sudo)。
+コントローラが ATMega32u4 の場合の `sudo` の使い方の例:
+    $ sudo dfu-programmer atmega32u4 erase --force
+    $ sudo dfu-programmer atmega32u4 flash your.hex
+    $ sudo dfu-programmer atmega32u4 reset
+あるいは、単純に:
+    $ sudo make <keyboard>:<keymap>:dfu
+`make` を `sudo` で実行することは一般的には良い考えでは***なく***、可能であれば前者の方法のいずれかを使うべきです。
+### Linux の `udev` ルール
+Linux では、MCU にアクセスするには適切な権限が必要です。ファームウェアを書き込む時に `sudo` を使うか、`/etc/udev/rules.d/` にこれらのファイルを配置することで、アクセスすることができます。権限の追加が完了したら、以下を実行します:
+```console
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+**/etc/udev/rules.d/50-atmel-dfu.rules:**
+```
+# Atmel ATMega32U4
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff4", MODE:="0666"
+# Atmel USBKEY AT90USB1287
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ffb", MODE:="0666"
+# Atmel ATMega32U2
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2ff0", MODE:="0666"
+```
+**/etc/udev/rules.d/52-tmk-keyboard.rules:**
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+**/etc/udev/rules.d/54-input-club-keyboard.rules:**
+```
+# Input Club keyboard bootloader
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
+```
+**/etc/udev/rules.d/55-caterina.rules:**
+```
+# ModemManager should ignore the following devices
+ATTRS{idVendor}=="2a03", ENV{ID_MM_DEVICE_IGNORE}="1"
+ATTRS{idVendor}=="2341", ENV{ID_MM_DEVICE_IGNORE}="1"
+```
+**注意:** ModemManager フィルタリングは厳格モードでは無い場合のみ動作します。以下のコマンドでその設定を変更することができます:
+```console
+sudo sed -i 's/--filter-policy=strict/--filter-policy=default/' /lib/systemd/system/ModemManager.service
+sudo systemctl daemon-reload
+sudo systemctl restart ModemManager
+```
+**/etc/udev/rules.d/56-dfu-util.rules:**
+```
+# stm32duino
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="1eaf", ATTRS{idProduct}=="0003", MODE:="0666"
+# Generic stm32
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE:="0666"
+```
+**/etc/udev/rules.d/57-bootloadhid.rules:**
+```
+# bootloadHID
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", MODE:="0666"
+```
+### Linux のブートローダモードで Serial デバイスが検知されない
+カーネルがデバイスを適切にサポートしていることを確認してください。デバイスが、Pro Micro (Atmega32u4) のように USB ACM を使う場合、`CONFIG_USB_ACM=y` を含めるようにしてください。他のデバイスは `USB_SERIAL` およびそのサブオプションを必要とするかもしれません。
+## DFU ブートローダの不明なデバイス
+Windows 上でキーボードを書き込む時に発生する問題は、ブートローダ用に間違ったドライバがインストールされているか、全くインストールされていないかによるものがほとんどです。
+QMK インストールスクリプト (MSYS2 あるいは WSL 内の `qmk_firmware` ディレクトリから `./util/qmk_install.sh`) を再実行するか、QMK Toolbox の再インストールでこの問題が解決するかもしれません。別のやり方として、手動で [`qmk_driver_installer`](https://github.com/qmk/qmk_driver_installer) パッケージをダウンロードして実行することができます。
+それでもうまく行かない場合は、Zadig をダウンロードして実行する必要があります。詳細な情報は [Zadig を使ったブートローダドライバのインストール](ja/driver_installation_zadig.md)を見てください。
+## USB VID と PID
+`config.h` を編集することで任意の ID を使うことができます。おそらく未使用の ID を使っても、他の製品と衝突するとても低い可能性があることを除いて、実際には問題はありません。
+QMK のほとんどのキーボードは、vendor ID として、`0xFEED` を使います。他のキーボードを調べて、ユニークな ID を選択してください。
+またこれも見てください。
+https://github.com/tmk/tmk_keyboard/issues/150
+ここで本当にユニークな VID:PID を買うことができます。個人的な使用にはこれは必要ないと思います。
+- http://www.obdev.at/products/vusb/license.html
+- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
+## AVR のための BOOTLOADER_SIZE
+Teensy2.0++ ブートローダのサイズは 2048 バイトであることに注意してください。一部の Makefile には間違ったコメントがあります。
+```
+# Boot Section Size in *bytes*
+#   Teensy halfKay   512
+#   Teensy++ halfKay 2048
+#   Atmel DFU loader 4096       (TMK Alt Controller)
+#   LUFA bootloader  4096
+#   USBaspLoader     2048
+OPT_DEFS += -DBOOTLOADER_SIZE=2048
+```
+## MacOS での `avr-gcc: internal compiler error: Abort trap: 6 (program cc1)` 
+これは brew での更新に関する問題で、avr-gcc が依存するシンボリックリンクを壊します。
+解決法は全ての影響を受けたモジュールを削除し再インストールすることです。
+```
+brew rm avr-gcc
+brew rm avr-gcc@8
+brew rm dfu-programmer
+brew rm dfu-util
+brew rm gcc-arm-none-eabi
+brew rm arm-gcc-bin@8
+brew rm avrdude
+brew install avr-gcc@8
+brew install dfu-programmer
+brew install dfu-util
+brew install arm-gcc-bin@8
+brew install avrdude
+brew link --force avr-gcc@8
+brew link --force arm-gcc-bin@8
+```
+### `avr-gcc` と LUFA
+`avr-gcc` を更新し、LUFA に関連するエラーが表示された場合、例えば:
+`lib/lufa/LUFA/Drivers/USB/Class/Device/AudioClassDevice.h:380:5: error: 'const' attribute on function returning 'void'`
+今のところ、Homebrew で `avr-gcc` を 8 にロールバックする必要があります。
+```
+brew uninstall --force avr-gcc
+brew install avr-gcc@8
+brew link --force avr-gcc@8
+```
+### キーボードに書き込んだが何も起こらない、あるいはキーの押下が登録されない - ARM (rev6 planck、clueboard 60、hs60v2 など) でも同じ (Feb 2019)
+ARM ベースのチップ上での EEPROM の動作によって、保存された設定が無効になる場合があります。これはデフォルトレイヤに影響し、まだ調査中の特定の環境下でキーボードが使えなくなる*しれません*。EEPROM のリセットでこれが修正されます。
+[Planck rev6 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/539284620861243409/planck_rev6_default.bin) を使って eeprom のリセットを強制することができます。このイメージを書き込んだ後で、通常のファームウェアを書き込むと、キーボードが_通常_ の動作順序に復元されます。
+[Preonic rev3 reset EEPROM](https://cdn.discordapp.com/attachments/473506116718952450/537849497313738762/preonic_rev3_default.bin)
+いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](feature_bootmagic.md)とキーボード情報を見てください)。
diff --git a/docs/ja/faq_debug.md b/docs/ja/faq_debug.md
new file mode 100644
index 000000000..8e42aebbb
--- /dev/null
+++ b/docs/ja/faq_debug.md
@@ -0,0 +1,161 @@
+# デバッグの FAQ
+<!---
+  original document: 376419a4f:docs/faq_debug.md
+  git diff 376419a4f HEAD -- docs/faq_debug.md | cat
+-->
+このページは、キーボードのトラブルシューティングについての様々な一般的な質問を説明します。
+# デバッグコンソール
+## `hid_listen` がデバイスを認識できない
+デバイスのデバッグコンソールの準備ができていない場合、以下のように表示されます:
+```
+Waiting for device:.........
+```
+デバイスが接続されると、*hid_listen* がデバイスを見つけ、以下のメッセージが表示されます:
+```
+Waiting for new device:.........................
+Listening:
+```
+この 'Listening:' のメッセージが表示されない場合は、[Makefile] を `CONSOLE_ENABLE=yes` に設定してビルドしてみてください
+Linux のような OS でデバイスにアクセスするには、権限が必要かもしれません。
+- `sudo hid_listen` を試してください
+## コンソールにメッセージが表示されない
+以下を調べてください:
+- *hid_listen* がデバイスを検出する。上記を見てください。
+- **Magic**+d を使ってデバッグを有効にする。[マジックコマンド](https://github.com/tmk/tmk_keyboard#magic-commands)を見てください。
+- `debug_enable=true` を設定します。[テストとデバッグ](ja/newbs_testing_debugging.md#debugging)を見てください
+- デバッグ print の代わりに 'print' 関数を使ってみてください。**common/print.h** を見てください。
+- コンソール機能を持つ他のデバイスを切断します。[Issue #97](https://github.com/tmk/tmk_keyboard/issues/97) を見てください。
+## Linux あるいは UNIX のようなシステムはスーパーユーザ権限を必要とします
+権限付きで *hid_listen* を実行するために 'sudo' を使ってください。
+```
+$ sudo hid_listen
+```
+または rules ディレクトリにファイルを置いて、TMK デバイスのための *udev rule* を追加します。ディレクトリは各システムで異なるかもしれません。
+File: /etc/udev/rules.d/52-tmk-keyboard.rules (Ubuntu の場合)
+```
+# tmk keyboard products     https://github.com/tmk/tmk_keyboard
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
+```
+***
+# 雑多なこと
+## 安全性の考慮
+あなたはおそらくキーボードを「文鎮化」したくないでしょう。文鎮化するとファームウェアを書き換えられないようになります。リスクがあまりに高い(そしてそうでないかもしれない)ものの一部のリストを示します。
+- キーボードマップに RESET が含まれない場合、DFU モードに入るには、PCB のリセットボタンを押す必要があります。底部のネジを外す必要があります。
+- tmk_core / common にあるファイルを触るとキーボードが操作不能になるかもしれません。
+- .hex ファイルが大きすぎると問題を引き起こします; `make dfu` コマンドはブロックを削除し、
+サイズを検査し(おっと、間違った順序です！)、エラーを出力し、
+キーボードへの書き込みに失敗し、DFU モードのままになります。
+   - この目的のためには、Planck の最大の .hex ファイルサイズは 7000h (10進数で28672)であることに注意してください。
+```
+Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
+Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]
+Size after:
+   text    data     bss     dec     hex filename
+      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
+```
+- 上のファイルのサイズは 22396/577ch で、28672/7000h より小さいです
+- 適切な替わりの .hex ファイルがある限り、それをロードして再試行することができます
+- あなたがキーボードの Makefile で指定したかもしれない一部のオプションは、余分なメモリを消費します; BOOTMAGIC_ENABLE、MOUSEKEY_ENABLE、EXTRAKEY_ENABLE、CONSOLE_ENABLE、API_SYSEX_ENABLE に注意してください
+- DFU ツールは(オプションの余計なフルーツサラダを投げ込まない限り)ブートローダに書き込むことを許可しないので、
+ここにはリスクはほとんどありません。
+- EEPROM の書き込みサイクルは、約100000です。ファームウェアを繰り返し継続的に書き換えるべきではありません。それは最終的に EEPROM を焼き焦がします。
+## NKRO が動作しません
+最初に、**Makefile** 内でビルドオプション `NKRO_ENABLE` を使ってファームウェアをコンパイルする必要があります。
+**NKRO** がまだ動作しない場合は、`Magic` **N** コマンド(デフォルトでは `LShift+RShift+N`)を試してみてください。**NKRO** モードと **6KRO** モード間を一時的に切り替えるためにこのコマンドを使うことができます。**NKRO** が機能しない状況、特に BIOS の場合は **6KRO** モードに切り替える必要があります。
+ファームウェアを `BOOTMAGIC_ENABLE` でビルドした場合、`ブートマジック` **N** コマンドで切り替える必要があります (デフォルトでは `Space+N`)。この設定は EEPROM に格納され、電源を入れ直しても保持されます。
+https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switch
+## TrackPoint はリセット回路が必要です (PS/2 マウスサポート)
+リセット回路が無いとハードウェアの不適切な初期化のために一貫性の無い結果になります。TPM754 の回路図を見てください。
+- http://geekhack.org/index.php?topic=50176.msg1127447#msg1127447
+- http://www.mikrocontroller.net/attachment/52583/tpm754.pdf
+## 16 を超えるマトリックの列を読み込めない
+列が 16 を超える場合、[matrix.h] の `read_cols()` 内の `1<<16` の代わりに `1UL<<16` を使ってください。
+C では、AVR の場合 `1` は [16 bit] である [int] 型の1を意味し、15 を超えて左にシフトすることはできません。`1<<16` すると予期しないゼロが発生します。`1UL` として [unsigned long] 型を使う必要があります。
+http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
+## 特別なエクストラキーが動作しない (システム、オーディオコントロールキー)
+QMK でそれらを使うには、`rules.mk` 内で `EXTRAKEY_ENABLE` を定義する必要があります。
+```
+EXTRAKEY_ENABLE = yes          # オーディオ制御とシステム制御
+```
+## スリープから復帰しない
+Windows では、**デバイスマネージャ**の**電源の管理**タブ内の `このデバイスで、コンピュータのスタンバイ状態を解除できるようにする` 設定を調べてください。また BIOS 設定も調べてください。
+スリープ中に任意のキーを押すとホストが起動するはずです。
+## Arduino を使っていますか？
+**Arduino のピンの命名は実際のチップと異なることに注意してください。** 例えば、Arduino のピン `D0` は `PD0` ではありません。回路図を自身で確認してください。
+- http://arduino.cc/en/uploads/Main/arduino-leonardo-schematic_3b.pdf
+- http://arduino.cc/en/uploads/Main/arduino-micro-schematic.pdf
+Arduino の Leonardo と micro には **ATMega32U4** が載っていて、TMK 用に使うことができますが、Arduino のブートローダが問題になることがあります。
+## JTAG を有効にする
+デフォルトでは、キーボードが起動するとすぐに JTAG デバッグインタフェースが無効になります。JTAG 対応 MCU は `JTAGEN` ヒューズが設定された状態で出荷されており、キーボードがスイッチマトリックス、LED などに使用している可能性のある MCU の特定のピンを乗っ取ります。
+JTAG を有効にしたままにしたい場合は、単に以下のものを `config.h` に追加します:
+```c
+#define NO_JTAG_DISABLE
+```
+## USB 3 の互換性
+USB 3 ポートで問題がある人がいると聞きました。USB 2 ポートを試してください。
+## Mac の互換性
+### OS X 10.11 と Hub
+https://geekhack.org/index.php?topic=14290.msg1884034#msg1884034
+## リジューム (スリープとウェークアップ)/電源サイクルの問題
+一部の人がキーボードが BIOS で動作しなくなった、またはリジューム(電源サイクル)の後で動作しなくなったと報告しました。
+今のところ、この問題の根本は明確ではないですが、幾つかのビルドオプションが関係しているようです。Makefileで、`CONSOLE_ENABLE`、`NKRO_ENABLE`、`SLEEP_LED_ENABLE` あるいは他のオプションを無効にしてみてください。
+https://github.com/tmk/tmk_keyboard/issues/266
+https://geekhack.org/index.php?topic=41989.msg1967778#msg1967778
+## FLIP が動作しない
+### `AtLibUsbDfu.dll` が見つかりません
+デバイスマネージャから現在のドライバを削除し、FLIP が提供するものを再インストールします。
+http://imgur.com/a/bnwzy
diff --git a/docs/ja/faq_general.md b/docs/ja/faq_general.md
new file mode 100644
index 000000000..935d1a3c6
--- /dev/null
+++ b/docs/ja/faq_general.md
@@ -0,0 +1,20 @@
+# よくある質問
+<!---
+  original document: d598f01cb:docs/faq_general.md
+  git diff d598f01cb HEAD -- docs/faq_general.md | cat
+-->
+## QMK とは何か？
+Quantum Mechanical Keyboard の略である [QMK](https://github.com/qmk) は、カスタムキーボードのためのツールをビルドしている人々のグループです。[TMK](https://github.com/tmk/tmk_keyboard) の大幅に修正されたフォークである [QMK ファームウェア](https://github.com/qmk/qmk_firmware)から始まりました。
+## QMK と TMK の違いは何か？
+TMK は [Jun Wako](https://github.com/tmk) によって設計され実装されました。QMK は [Jack Humbert](https://github.com/jackhumbert) の Planck 用 TMK のフォークとして始まりました。しばらくして、Jack のフォークは TMK からかなり分岐し、2015年に Jack はフォークを QMK に名前を変えることにしました。
+技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](keycodes.md)でこれらのキーコードの完全なリストを見ることができます。
+プロジェクトとコミュニティの管理の観点から、TMK は公式にサポートされている全てのキーボードを自分で管理しており、コミュニティのサポートも少し受けています。他のキーボード用に別個のコミュニティが維持するフォークが存在するか、作成できます。デフォルトでは少数のキーマップのみが提供されるため、ユーザは一般的にお互いにキーマップを共有しません。QMK は集中管理されたリポジトリを介して、キーボードとキーマップの両方を共有することを奨励しており、品質基準に準拠する全てのプルリクエストを受け付けます。これらはほとんどコミュニティで管理されますが、必要な場合は QMK チームも支援します。
+どちらのアプローチもメリットとデメリットがあり、理に適う場合は TMK と QMK の間でコードは自由にやり取りされます。
diff --git a/docs/ja/faq_keymap.md b/docs/ja/faq_keymap.md
new file mode 100644
index 000000000..0c742bf6b
--- /dev/null
+++ b/docs/ja/faq_keymap.md
@@ -0,0 +1,149 @@
+# キーマップの FAQ
+<!---
+  original document: 376419a4f:docs/faq_keymap.md
+  git diff 376419a4f HEAD -- docs/faq_keymap.md | cat
+-->
+このページは人々がキーマップについてしばしば持つ疑問について説明します。まだ読んだことが無い場合には、[キーマップの概要](ja/keymap.md)を最初に読むべきです。
+## どのキーコードを使えますか？
+あなたが利用可能なキーコードのインデックスについては、[キーコード](ja/keycodes.md)を見てください。より広範なドキュメントがある場合は、そこからリンクしてあります。
+キーコードは実際には [common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h) で定義されています。
+## デフォルトのキーコードとは何か？
+世界中で使用されている ANSI、ISO および JIS の3つの標準キーボードがあります。北米では主に ANSI が使われ、ヨーロッパおよびアフリカでは主に ISO が使われ、日本では JIS が使われます。言及されていない地域では、ANSI あるいは ISO が使われています。これらのレイアウトに対応するキーコードは以下の通りです:
+<!-- Source for this image: http://www.keyboard-layout-editor.com/#/gists/bf431647d1001cff5eff20ae55621e9a -->
+![キーボードのレイアウトイメージ](https://i.imgur.com/5wsh5wM.png)
+## 一部のキーが入れ替わっているか、または動作しない
+QMK には2つの機能、ブートマジックとコマンドがあり、これによりその場でキーボードの動作を変更することができます。これには Ctrl/Caps の交換、Gui の無効化、Alt/GUI の交換、Backspace/Backslash の交換、全てのキーの無効化およびその他の動作の変更が含まれますが、これらに限定されません。
+迅速な解決策として、キーボードを接続している時に `Space`+`Backspace` を押してみてください。これはキーボードに保存されている設定をリセットし、これらのキーを通常の操作に戻します。うまく行かない場合は、以下を見てください:
+* [ブートマジック](ja/feature_bootmagic.md)
+* [コマンド](ja/feature_command.md)
+## メニューキーが動作しない
+ほとんどの最近のキーボードにある、`KC_RGUI` と `KC_RCTL` の間にあるキーは、実際には `KC_APP` と呼ばれます。これは、そのキーが発明された時に、関連する標準にすでに `MENU` という名前のキーが存在していたため、MS はそれを `APP` キーと呼ぶことを選択したためです。
+## `KC_SYSREQ` が動作しません
+`KC_SYSREQ` の代わりに、Print Screen(`KC_PSCREEN` あるいは `KC_PSCR`) のキーコードを使ってください。'Alt + Print Screen' のキーの組み合わせは、'システムリクエスト' と認識されます。
+[issue #168](https://github.com/tmk/tmk_keyboard/issues/168) と以下を見てください
+* http://en.wikipedia.org/wiki/Magic_SysRq_key
+* http://en.wikipedia.org/wiki/System_request
+## 電源キーが動作しません
+やや紛らわしいことに、QMK には2つの "Power" キーコードがあります: キーボード/キーパッド HID usage page では `KC_POWER`、Consumer page では `KC_SYSTEM_POWER` (あるいは `KC_PWR`)。
+前者は macOS でのみ認識されますが、後者 `KC_SLEP` および `KC_WAKE` は3つの主要なオペレーティングシステム全てでサポートされるため、これらを使うことをお勧めします。Windows ではこれらのキーはすぐに機能しますが、macOS ではそれらはダイアログが表示されるまで押し続ける必要があります。
+## ワンショットモディファイア
+私の個人的な 'the' の問題を解決します。'The' ではなく 'the' あるいは 'THe' を間違って入力することがありました。ワンショットシフトはこれを軽減します。
+https://github.com/tmk/tmk_keyboard/issues/67
+## モディファイヤ/レイヤスタック
+修飾キーあるいはレイヤは、レイヤの切り替えが適切に設定されていない場合、スタックするかもしれません。
+修飾キーおよびレイヤ切り替えの場合、リリースイベント時に修飾キーの登録を解除する、もしくは前のレイヤに戻るために、目的のレイヤの同じ位置に `KC_TRANS` を配置する必要があります。
+* https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#31-momentary-switching
+* http://geekhack.org/index.php?topic=57008.msg1492604#msg1492604
+* https://github.com/tmk/tmk_keyboard/issues/248
+## メカニカルロックスイッチのサポート
+この機能は [Alps](http://deskthority.net/wiki/Alps_SKCL_Lock) のような*メカニカルロックスイッチ*用です。以下を `config.h` に追加することで有効にすることができます:
+```
+#define LOCKING_SUPPORT_ENABLE
+#define LOCKING_RESYNC_ENABLE
+```
+この機能を有効にした後で、キーマップでキーコード `KC_LCAP`、`KC_LNUM` および `KC_LSCR` を使います。
+古いビンテージメカニカルキーボードにはロックスイッチが付いている場合がありますが、最新のものにはありません。***ほとんどの場合この機能は必要なく、単にキーコード `KC_CAPS`、`KC_NLCK` および `KC_SLCK`*** を使います。
+## セディーユ 'Ç' のような ASCII 以外の特別文字の入力
+[ユニコード](ja/feature_unicode.md) 機能を見てください。
+## macOS での `Fn` キー
+ほとんどの Fn キーと異なり、Apple のキーボードの Fn キーには実際には独自のキーコードのようなものがあります。基本的な 6KRO HID レポートの6番目のキーコードの代わりになります -- つまり、Apple キーボードは実際には 5KRO のみです。
+QMK にこのキーを送信させることは技術的に可能です。ただし、そうするには Fn キーの状態を追加するためにレポート形式の修正を必要とします。 
+さらに悪いことに、キーボードの VID と PID が実際の Apple のキーボードのものと一致しない限り、認識されません。公式の QMK がこの機能をサポートすることで法的な問題が起きるため、サポートされることはないでしょう。
+詳細については、[この issue](https://github.com/qmk/qmk_firmware/issues/2179) を見てください。
+## Mac OSX でサポートされるキーは？
+このソースコードから、どのキーコードが OSX でサポートされるかを知ることができます。
+`usb_2_adb_keymap` 配列は、キーボード/キーパッドページの Page usages を ADB スキャンコード(OSX 内部キーコード)にマップします。
+https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/Cosmo_USB2ADB.c
+`IOHIDConsumer::dispatchConsumerEvent` は Consumer page usages を処理します。
+https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-606.1.7/IOHIDFamily/IOHIDConsumer.cpp
+## Mac OSX での JIS キー
+`無変換(Muhenkan)`, `変換(Henkan)`, `ひらがな(hiragana)` のような日本語 JIS キーボード固有のキーは OSX では認識されません。**Seil** を使ってこれらのキーを使うことができます。以下のオプションを試してください。
+* PC キーボードで NFER キーを有効にする
+* PC キーボードで XFER キーを有効にする
+* PC キーボードで KATAKANA キーを有効にする
+https://pqrs.org/osx/karabiner/seil.html
+## RN-42 Bluetooth が Karabiner で動作しない
+Karabiner - Mac OSX 上のキーマッピングツール - は、デフォルトでは RN-42 モジュールからの入力を無視します。Karabiner をキーボードで動作させるにはこのオプションを有効にする必要があります。
+https://github.com/tekezo/Karabiner/issues/403#issuecomment-102559237
+この問題の詳細についてはこれらを見てください。
+https://github.com/tmk/tmk_keyboard/issues/213
+https://github.com/tekezo/Karabiner/issues/403
+## 単一のキーでの Esc と<code>&#96;</code>
+[Grave Escape](feature_grave_esc.md) 機能を見てください。
+## Mac OSX での Eject
+`KC_EJCT` キーコードは OSX で動作します。https://github.com/tmk/tmk_keyboard/issues/250
+Windows 10 はコードを無視し、Linux/Xorg は認識しますが、デフォルトではマッピングがありません。
+実際の Apple キーボードにある Eject キーコードは実際には分かりません。HHKB は Mac モードでは Eject キー (`Fn+f`) に `F20` を使いますが、これはおそらく Apple の Eject キーコードと同じではありません。
+## `action_util.c` の `weak_mods` と `real_mods` は何か
+___改善されるべきです___
+real_mods は実際の物理的な修飾キーの状態を保持することを目的にしていますが、weak_mods は実際の修飾キーの状態に影響しない仮想あるいは一時的なモディファイアの状態を保持します。
+物理的な左シフトキーを押しながら ACTION_MODS_KEY(LSHIFT, KC_A) を入力するとします
+weak_mods では、
+* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT)
+* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: weak_mods |= MOD_BIT(LSHIFT)
+* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: weak_mods &= ~MOD_BIT(LSHIFT)
+real_mods はモディファイアの状態を維持します。
+weak mods 無しでは、
+* (1) 左シフトキーを押し続ける: real_mods |= MOD_BIT(LSHIFT)
+* (2) ACTION_MODS_KEY(LSHIFT, KC_A) を押す: real_mods |= MOD_BIT(LSHIFT)
+* (3) ACTION_MODS_KEY(LSHIFT, KC_A) を放す: real_mods &= ~MOD_BIT(LSHIFT)
+ここで、real_mods は 'physical left shift' '物理的な左シフト' の状態を見失います。
+キーボードレポートが送信される時、weak_mods は real_mods と論理和がとられます。
+https://github.com/tmk/tmk_core/blob/master/common/action_util.c#L57
diff --git a/docs/ja/getting_started_getting_help.md b/docs/ja/getting_started_getting_help.md
new file mode 100644
index 000000000..4b5d492fa
--- /dev/null
+++ b/docs/ja/getting_started_getting_help.md
@@ -0,0 +1,20 @@
+# 助けを得る
+<!---
+  original document: d598f01cb:docs/getting_started_getting_help.md
+  git diff d598f01cb HEAD -- docs/getting_started_getting_help.md | cat
+-->
+QMK に関して助けを得るための多くのリソースがあります。
+## リアルタイム チャット
+メインの [Discord server](https://discord.gg/Uq7gcHh) で QMK の開発者とユーザを見つけることができます。サーバには、ファームウェア、Toolbox、ハードウェアおよび Configurator についてチャットするための特定のチャンネルがあります。
+## OLKB Subreddit
+公式の QMK フォーラムは [reddit.com](https://reddit.com) の [/r/olkb](https://reddit.com/r/olkb) です。
+## Github Issues
+[GitHub で issue](https://github.com/qmk/qmk_firmware/issues) を開くことができます。issue が長期的な議論あるいはデバッグを必要とする場合は、特に便利です。
diff --git a/docs/ja/getting_started_github.md b/docs/ja/getting_started_github.md
new file mode 100644
index 000000000..261f1d391
--- /dev/null
+++ b/docs/ja/getting_started_github.md
@@ -0,0 +1,70 @@
+# QMK で Github を使う方法
+<!---
+  original document: d598f01cb:docs/getting_started_github.md
+  git diff d598f01cb HEAD -- docs/getting_started_github.md | cat
+-->
+Github は慣れていない人には少し注意が必要です - このガイドは、QMK におけるフォーク、クローン、プルリクエストのサブミットの各ステップについて説明します。
+?> このガイドでは、あなたがコマンドラインでの実行にある程度慣れており、システムに git がインストールされていることを前提にしています。
+[QMK Github ページ](https://github.com/qmk/qmk_firmware)を開くと、右上に "Fork" というボタンが見えます:
+![Git でのフォーク](http://i.imgur.com/8Toomz4.jpg)
+あなたが組織の一員である場合は、どのアカウントにフォークするかを選択する必要があります。ほとんどの場合、あなたの個人のアカウントにフォークしたいでしょう。フォークが完了したら(しばらく時間が掛かる場合があります)、"Clone or Download" ボタンをクリックします:
+![Git からダウンロード](http://i.imgur.com/N1NYcSz.jpg)
+必ず "HTTPS" を選択し、リンクを選択してコピーします:
+![HTTPS リンク](http://i.imgur.com/eGO0ohO.jpg)
+ここから、`git clone --recurse-submodules ` をコマンドラインに入力し、リンクを貼り付けます:
+```
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
+Cloning into 'qmk_firmware'...
+remote: Enumerating objects: 9, done.
+remote: Counting objects: 100% (9/9), done.
+remote: Compressing objects: 100% (5/5), done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
+```
+ローカルマシンに QMK のフォークができるので、キーマップの追加、コンパイル、キーボードへの書き込みができます。変更に満足したら、以下のようにそれらをフォークへ追加、コミットおよびプッシュすることができます:
+```
+user@computer:~$ git add .
+user@computer:~$ git commit -m "adding my keymap"
+[master cccb1608] adding my keymap
+ 1 file changed, 1 insertion(+)
+ create mode 100644 keyboards/planck/keymaps/mine/keymap.c
+user@computer:~$ git push
+Counting objects: 1, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (1/1), done.
+Writing objects: 100% (1/1), 1.64 KiB | 0 bytes/s, done.
+Total 1 (delta 1), reused 0 (delta 0)
+remote: Resolving deltas: 100% (1/1), completed with 1 local objects.
+To https://github.com/whoeveryouare/qmk_firmware.git
+ + 20043e64...7da94ac5 master -> master
+```
+あなたの変更は今では Github 上のフォークにあります - フォーク (`https://github.com/<whoeveryouare>/qmk_firmware`)に戻ると、"New Pull Request" ボタンをクリックすることで新しいプルリクエストを作成することができます:
+![New Pull Request](http://i.imgur.com/DxMHpJ8.jpg)
+ここでは、コミットした内容を正確に確認することができます - 全て良いように見える場合は、"Create Pull Request" をクリックすることで最終的に承認することができます:
+![Create Pull Request](http://i.imgur.com/Ojydlaj.jpg)
+サブミットの後で、私たちはあなたの変更について話し、変更を依頼し、最終的にそれを受け入れるでしょう！QMK に貢献してくれてありがとう :)
diff --git a/docs/ja/getting_started_introduction.md b/docs/ja/getting_started_introduction.md
new file mode 100644
index 000000000..b4f8b574d
--- /dev/null
+++ b/docs/ja/getting_started_introduction.md
@@ -0,0 +1,65 @@
+# はじめに
+<!---
+  original document: d598f01cb:docs/getting_started_introduction.md
+  git diff d598f01cb HEAD -- docs/getting_started_introduction.md | cat
+-->
+このページでは、QMK プロジェクトで作業するために知っておくべき基本的な情報について説明しようと思います。Unix シェルの操作に精通していることを前提としていますが、C について、または make を使ったコンパイルについて精通しているとは想定していません。
+## 基本的な QMK の構造
+QMK は [Jun Wako](https://github.com/tmk) の [tmk_keyboard](https://github.com/tmk/tmk_keyboard) プロジェクトのフォークです。変更された元の TMK コードは、`tmk_core` フォルダで見つけることができます。プロジェクトへの QMK の追加は、`quantum` フォルダで見つけることができます。キーボードプロジェクトは `handwired` および `keyboard` フォルダで見つけることができます。
+### ユーザスペースの構造
+`users` フォルダ内は各ユーザのためのディレクトリです。これはユーザがキーボード間で使うかもしれないコードを置くためのフォルダです。詳細は[ユーザスペース機能](ja/feature_userspace.md) のドキュメントを見てください。
+### キーボードプロジェクトの構造
+`keyboards` フォルダ、そのサブフォルダ `handwired`、ベンダと製品のサブディレクトリ (例えば、`clueboard`) の中には、各キーボードプロジェクトのためのディレクトリ (例えば `qmk_firmware/keyboards/clueboard/2x1800`) があります。その中には、以下の構造があります:
+* `keymaps/`: ビルドできる様々なキーマップ
+* `rules.mk`: デフォルトの "make" オプションを設定するファイル。このファイルを直接編集しないでください。代わりにキーマップ固有の `rules.mk` を使ってください。
+* `config.h`: デフォルトのコンパイル時のオプションを設定するファイル。このファイルを直接編集しないでください。代わりにキーマップ固有の `config.h` を使ってください。
+* `info.json`: QMK Configurator のためのレイアウトの設定に使われるファイル。詳細は [Configurator サポート](ja/reference_configurator_support.md)を見てください。
+* `readme.md`: キーボードの簡単な概要
+* `<keyboardName>.h`: このファイルは、キーボードのスイッチマトリックスに対してキーボードレイアウトが定義されるファイルです。
+* `<keyboardName>.c`: このファイルには、キーボードのためのカスタムコードがあります。
+プロジェクトの構造についての詳細は、[QMK キーボードガイドライン](ja/hardware_keyboard_guidelines.md)を見てください。
+### キーマップ構造
+全てのキーマップフォルダには、以下のファイルがあります。`keymap.c` だけが必須で、残りのファイルが見つからない場合は、デフォルトのオプションが選択されます。
+* `config.h`: キーマップを設定するためのオプション
+* `keymap.c`: 全てのキーマップコード。必須
+* `rules.mk`: 有効になっている QMK の機能
+* `readme.md`: キーマップの説明。他の人が使う方法および機能の説明。imgur のようなサービスに画像をアップロードしてください。
+# `config.h` ファイル
+3つの `config.h` の場所が考えられます:
+* キーボード (`/keyboards/<keyboard>/config.h`)
+* ユーザスペース (`/users/<user>/config.h`)
+* キーマップ (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
+ビルドシステムは自動的に上の順に config ファイルを取得します。前の `config.h` で設定された設定を上書きしたい場合は、変更したい設定の準備のために最初に定型コードを置く必要があります。
+```
+#pragma once
+```
+次に、前の `config.h` ファイルの設定を上書きするために、設定を `#undef` し再び `#define` する必要があります。
+定型コードと設定は、以下のようになります:
+```
+#pragma once
+// ここに上書きします！
+#undef MY_SETTING
+#define MY_SETTING 4
+```
diff --git a/docs/ja/newbs.md b/docs/ja/newbs.md
index d1043a4a1..465b82106 100644
--- a/docs/ja/newbs.md
+++ b/docs/ja/newbs.md
@@ -2,8 +2,8 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: ed0575fc8:docs/newbs.md
+  original document: adf4acf59:docs/newbs.md
-  git diff ed0575fc8 HEAD docs/newbs.md | cat
+  git diff adf4acf59 HEAD -- docs/newbs.md | cat
 -->
 QMK は、メカニカルキーボード用の強力なオープンソースファームウェアです。
@@ -19,18 +19,18 @@ QMK は[多くの趣味のキーボード](http://qmk.fm/keyboards/)をサポー
 このガイドには7つの主要なセクションがあります。
-* [はじめに](newbs_getting_started.md)
+* [はじめに](ja/newbs_getting_started.md)
-* [コマンドラインを使用して初めてのファームウェアを構築する](newbs_building_firmware.md)
+* [コマンドラインを使用して初めてのファームウェアを構築する](ja/newbs_building_firmware.md)
-* [オンライン GUI を使用して初めてのファームウェアを構築する](newbs_building_firmware_configurator.md)
+* [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md)
-* [ファームウェアを書きこむ](newbs_flashing.md)
+* [ファームウェアを書きこむ](ja/newbs_flashing.md)
-* [テストとデバッグ](newbs_testing_debugging.md)
+* [テストとデバッグ](ja/newbs_testing_debugging.md)
-* [QMK における Git 運用作法](newbs_best_practices.md)
+* [QMK における Git 運用作法](ja/newbs_git_best_practices.md)
-* [さらに学ぶための学習リソース](newbs_learn_more_resources.md)
+* [さらに学ぶための学習リソース](ja/newbs_learn_more_resources.md)
 このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。
 その観点から選択と推奨を行います。
 これらの手順の多くには代替方法があり、これらの代替方法のほとんどをサポートしています。
-タスクを達成する方法について疑問がある場合は、[案内を求めることができます](getting_started_getting_help.md)。
+タスクを達成する方法について疑問がある場合は、[案内を求めることができます](ja/getting_started_getting_help.md)。
 ## 追加のリソース(英語)
diff --git a/docs/ja/newbs_best_practices.md b/docs/ja/newbs_best_practices.md
deleted file mode 100644
index 2e90ffcab..000000000
--- a/docs/ja/newbs_best_practices.md
+++ /dev/null
@@ -1,263 +0,0 @@
-<!-- # Best Practices -->
-# QMK における Git 運用作法
-<!---
-  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: e75919960:docs/newbs_best_practices.md
-  git diff e75919960 HEAD docs/newbs_best_practices.md | cat
-->
-<!-- ## Or, "How I Learned to Stop Worrying and Love Git." -->
-## または、如何にして私は心配することをやめて Git を愛することを学んだか。
-<!-- _Almost the same as #7231:25fdbf2a0:newbs_git_best_practices.md L5_ -->
-<!-- This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. -->
-この文書は、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。
-QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。
-その後、意図的に一部を壊してみせて、それらを修正する方法を教えます。
-<!-- This document assumes a few things: -->
-このドキュメントは以下のことを前提としています:
-<!-- _Same as #7231:25fdbf2a0:newbs_git_best_practices.md L9_  -->
-<!-- 1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. -->
-<!-- 2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). -->
-<!-- #7231:da7d49246: 2. You've set up both [your build environment](newbs_getting_started.md?id=set-up-your-environment) and [QMK](newbs_getting_started.md?id=set-up-qmk). -->
-1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](getting_started_github.md) している。
-2. あなたは、[環境構築](newbs_getting_started.md#環境構築) と [QMK の設定](newbs_getting_started.md#qmk-の設定) を両方とも完了している。
-<!-- ## Your fork's master: Update Often, Commit Never -->
-## あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L3_  -->
-<!-- It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. -->
-QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。
-代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L5_  -->
-<!-- To reduce the chances of merge conflicts &mdash; instances where two or more users have edited the same part of a file concurrently &mdash; keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. -->
-マージの競合 &mdash; これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 &mdash; の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。
-<!-- ### Updating your master branch -->
-### あなたの master ブランチを更新する
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L9_  -->
-<!-- To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: -->
-`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。
-これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。
-```
-git remote add upstream https://github.com/qmk/qmk_firmware.git
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L15_  -->
-<!-- To verify that the repository has been added, run `git remote -v`, which should return the following: -->
-リポジトリが追加されたことを確認するには、`git remote -v` を実行します。
-次のように表示されます。(訳注: `upstream` は`上流`という意味です。)
-```
-$ git remote -v
-origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
-origin  https://github.com/<your_username>/qmk_firmware.git (push)
-upstream        https://github.com/qmk/qmk_firmware.git (fetch)
-upstream        https://github.com/qmk/qmk_firmware.git (push)
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L25_  -->
-<!-- Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. -->
-これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。
-このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ &mdash; "refs" と総称されます &mdash; を取得します。
-これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L27_  -->
-<!-- To update your fork's master, run the following, hitting the Enter key after each line: -->
-あなたのフォークの `master` を更新するには、次を実行します、各行の後にEnterキーを押してください:
-```
-git checkout master
-git fetch upstream
-git pull upstream master
-git push origin master
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L36_  -->
-<!-- This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. -->
-これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。
-<!-- ### Making Changes -->
-### 変更を行なう
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L40_  -->
-<!-- To make changes, create a new branch by entering: -->
-変更するには、以下を入力して新しいブランチを作成します:
-```
-git checkout -b dev_branch
-git push --set-upstream origin dev_branch
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L47_  -->
-<!-- This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. -->
-これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。
-`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。
-この引数は最初のプッシュでのみ使用する必要があります。
-その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L49_  -->
-<!--  With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`. -->
-!> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L51_  -->
-<!-- You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. -->
-ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L53_  -->
-<!-- By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: -->
-デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。
-コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます:
-```
-git checkout -b dev_branch master
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L59_  -->
-<!-- Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: -->
-これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。
-ブランチに対して多くの小さなコミットを行うことをお勧めします。
-そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。
-変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします:
-```
-git add path/to/updated_file
-git commit -m "My commit message."
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L66_  -->
-<!-- `git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. -->
-`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。
-これは、Git の「ロードゾーン」です。
-これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。
-変更内容が一目でわかるように、説明的なコミットメッセージを使用します。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L68_  -->
-<!-- !> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. -->
-!> 多くのファイルを変更したが、すべてのファイルが同じ変更の一部である場合、各ファイルを個別に追加するのではなく、 `git add .` を使用して、現在のディレクトリにあるすべての変更されたファイルを追加できます。
-<!-- ### Publishing Your Changes -->
-### 変更を公開する
-<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L72_  -->
-<!-- The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. -->
-最後のステップは、変更をフォークにプッシュすることです。これを行うには、`git push`と入力します。
-Git は `dev_branch` の現在の状態をフォークに公開します。
-<!-- ## Resolving Merge Conflicts -->
-##  マージの競合の解決
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L3_  -->
-<!-- Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. -->
-ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。
-これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。
-<!-- ### Rebasing Your Changes -->
-### 変更のリベース
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L9_  -->
-<!-- A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. -->
-*リベース* は、ある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。
-マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L11_  -->
-<!-- To start, run the following: -->
-開始するには、次を実行します:
-```
-git fetch upstream
-git rev-list --left-right --count HEAD...upstream/master
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L18_  -->
-<!-- The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: -->
-ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。
-最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。
-入力された `git rev-list` コマンドの出力は2つの数値を返します:
-```
-$ git rev-list --left-right --count HEAD...upstream/master
-7       35
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L25_  -->
-<!-- The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. -->
-最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L27_-->
-<!-- Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: -->
-現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます:
-```
-git rebase upstream/master
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L33_  -->
-<!-- This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. -->
-これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。
-```
-$ git rebase upstream/master
-First, rewinding head to replay your work on top of it...
-Applying: Commit #1
-Using index info to reconstruct a base tree...
-M       conflicting_file_1.txt
-Falling back to patching base and 3-way merge...
-Auto-merging conflicting_file_1.txt
-CONFLICT (content): Merge conflict in conflicting_file_1.txt
-error: Failed to merge in the changes.
-hint: Use 'git am --show-current-patch' to see the failed patch
-Patch failed at 0001 Commit #1
-Resolve all conflicts manually, mark them as resolved with
-"git add/rm <conflicted_files>", then run "git rebase --continue".
-You can instead skip this commit: run "git rebase --skip".
-To abort and get back to the state before "git rebase", run "git rebase --abort".
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L54_  -->
-<!-- This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: -->
-これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。
-テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります:
-```
-<<<<<<< HEAD
-<p>For help with any issues, email us at support@webhost.us.</p>
-=======
-<p>Need help? Email support@webhost.us.</p>
->>>>>>> Commit #1
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L64_  -->
-<!-- The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. -->
-行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。
-`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L66_  -->
-<!-- Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. -->
-Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。
-ファイルを再編集して、競合を解決します。
-変更を加えてから、ファイルを保存します。
-```
-<p>Need help? Email support@webhost.us.</p>
-```
-そしてコマンド実行:
-```
-git add conflicting_file_1.txt
-git rebase --continue
-```
-<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L79_  -->
-<!-- Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. -->
-Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。
diff --git a/docs/ja/newbs_building_firmware.md b/docs/ja/newbs_building_firmware.md
index 5fb10d424..bcbc64a21 100644
--- a/docs/ja/newbs_building_firmware.md
+++ b/docs/ja/newbs_building_firmware.md
@@ -2,8 +2,8 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: ed0575fc8:docs/newbs_building_firmware.md
+  original document: 0f43c2652:docs/newbs_building_firmware.md
-  git diff ed0575fc8 HEAD docs/newbs_building_firmware.md | cat
+  git diff 0f43c2652 HEAD -- docs/newbs_building_firmware.md | cat
 -->
 ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。
@@ -56,7 +56,7 @@ macOS または Windows を使用している場合は、キーマップフォ�
 この行はレイヤーのリストの開始を表わしています。
 その下には、`LAYOUT` または `KEYMAP` のいずれかを含む行があり、これらの行はレイヤーの開始を表わしています。
-その行の下には、その特定������イヤーを構成するキーのリストがあります。
+その行の下には、そのレイヤーを構成するキーのリストがあります。
 !> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。
@@ -67,9 +67,9 @@ macOS または Windows を使用している場合は、キーマップフォ�
 あるレイヤー全体が必要ない場合はレイヤーを削除することもでき、必要があれば、合計 32 個までレイヤーを追加することもできます。
 ここで定義できる内容については、次のドキュメントを参照してください。
-* [キーコード](keycodes.md)
+* [キーコード](ja/keycodes.md)
-* [機能](features.md)
+* [機能](ja/features.md)
-* [FAQ](faq.md)
+* [FAQ](ja/faq.md)
 ?> キーマップがどのように機能するかを感じながら、各変更を小さくしてください。大きな変更は、発生する問題のデバッグを困難にします。
@@ -96,4 +96,4 @@ Checking file size of planck_rev5_xyverz.hex
 ## ファームウェアを書きこむ
-[「ファームウェアを書きこむ」](newbs_flashing.md) に移動して、キーボードに新しいファームウェアを書き込む方法を学習します。
+[「ファームウェアを書きこむ」](ja/newbs_flashing.md) に移動して、キーボードに新しいファームウェアを書き込む方法を学習します。
diff --git a/docs/ja/newbs_building_firmware_configurator.md b/docs/ja/newbs_building_firmware_configurator.md
index b44504ade..ae3d3cf28 100644
--- a/docs/ja/newbs_building_firmware_configurator.md
+++ b/docs/ja/newbs_building_firmware_configurator.md
@@ -3,7 +3,7 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
  original document: ed0575fc8:docs/newbs_building_firmware_configurator.md
-  git diff ed0575fc8 HEAD docs/newbs_building_firmware_configurator.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_building_firmware_configurator.md | cat
 -->
 [QMK Configurator](https://config.qmk.fm) は、QMKファームウェアの hex ファイルを生成するオンライングラフィカルユーザーインターフェイスです。
@@ -83,7 +83,7 @@ QMK Configurator は Chrome/Firefox で最適に動作します。
 ## キーボードに書き込む(フラッシュする)
-[ファームウェアを書きこむ](newbs_flashing.md) を参照してください。
+[ファームウェアを書きこむ](ja/newbs_flashing.md) を参照してください。
 ## トラブルシューティング
diff --git a/docs/ja/newbs_flashing.md b/docs/ja/newbs_flashing.md
index 0c85514cf..f2ca914ee 100644
--- a/docs/ja/newbs_flashing.md
+++ b/docs/ja/newbs_flashing.md
@@ -3,7 +3,7 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
  original document: ed0575fc8:docs/newbs_flashing.md
-  git diff ed0575fc8 HEAD docs/newbs_flashing.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_flashing.md | cat
 -->
 カスタムファームウェアは出来たので、キーボードに書き込みたくなるでしょう/フラッシュしたくなるでしょう。
@@ -13,7 +13,7 @@
 キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。
 ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。
-Linuxを使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](newbs_flashing.md#コマンドラインでファームウェアを書き込む)で行なう必要があります。
+Linuxを使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](ja/newbs_flashing.md#flash-your-keyboard-from-the-command-line)で行なう必要があります。
 ### QMK Toolbox にファイルをロードする
@@ -98,7 +98,7 @@ QMK Toolbox の `Flash` ボタンをクリックします。
 *** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
 ```
-## コマンドラインでファームウェアを書き込む
+## コマンドラインでファームウェアを書き込む :id=flash-your-keyboard-from-the-command-line
 これは、以前のものと比較して非常に単純になりました。
 ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
@@ -123,7 +123,7 @@ QMK Toolbox の `Flash` ボタンをクリックします。
 ブートローダは主に 5 種類のものが使われています。
 Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKBの AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。
-より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](flashing.md) にあります。
+より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](ja/flashing.md) にあります。
 使用しているブートローダがわかっているならば、ファームウェアをコンパイルするときに、実は `make` コマンドにブートローダを指定するテキストを追加して、書き込みプロセスを自動化できます。
@@ -172,7 +172,7 @@ Checking file size of planck_rev5_xyverz.hex
 >>> dfu-programmer atmega32u4 reset
 ```
-?> `dfu-programmer：no device present` など、これに関する問題がある場合は、[よくある質問](faq_build.md) を参照してください。
+?> `dfu-programmer：no device present` など、これに関する問題がある場合は、[よくある質問](ja/faq_build.md) を参照してください。
 #### DFU コマンド
@@ -397,4 +397,4 @@ Uploading 22016 (0x5600) bytes starting at 0 (0x0)
 おめでとうございます！ カスタムファームウェアがキーボードにプログラムされました！
 使ってみて、すべてがあなたの望むように動作するかどうか確認してください。
-この初心者ガイドを完全なものにするために [テストとデバッグ](newbs_testing_debugging.md) を書いたので、カスタム機能のトラブルシューティング方法については、こちらをご覧ください。
+この初心者ガイドを完全なものにするために [テストとデバッグ](ja/newbs_testing_debugging.md) を書いたので、カスタム機能のトラブルシューティング方法については、こちらをご覧ください。
diff --git a/docs/ja/newbs_getting_started.md b/docs/ja/newbs_getting_started.md
index a57e6e054..6f5cd92cd 100644
--- a/docs/ja/newbs_getting_started.md
+++ b/docs/ja/newbs_getting_started.md
@@ -2,8 +2,8 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
-  original document: docs/newbs_getting_started.md
+  original document: 161d469:docs/newbs_getting_started.md
-  git diff 161d469 HEAD docs/newbs_getting_started.md | cat
+  git diff 161d469 HEAD -- docs/newbs_getting_started.md | cat
 -->
 キーボードにはプロセッサが入っており、それはコンピュータに入っているものと大して違わないものです。
@@ -20,7 +20,7 @@ QMK は、簡単なことは簡単に、そして、難しいことを可能な�
 ファームウェアをコンパイルするキーボードの数に関わらず、この作業を一度だけ実行する必要があります。
 もし、GUI で作業をしたい場合、オンラインで作業できる [QMK Configurator](https://config.qmk.fm) を使ってください。
-使い方は [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md) を参照してください。
+使い方は [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md) を参照してください。
 ## ソフトウェアのダウンロード
@@ -45,7 +45,7 @@ QMK Toolbox は、Windows と macOS で使える GUI を備えたプログラム
 * Windows 版: `qmk_toolbox.exe` (portable) または `qmk_toolbox_install.exe` (installer)
 * macOS 版: `QMK.Toolbox.app.zip` (portable) または `QMK.Toolbox.pkg` (installer)
-## 環境構築
+## 環境構築 :id=set-up-your-environment
 私たちは、QMK を可能な限り簡単に構築できるように努力しています。
 Linux か Unix 環境を用意するだけで、QMK に残りをインストールさせることができます。
@@ -77,9 +77,9 @@ Git のインストールが必要です。既にインストールされてい�
 * Fedora / Red Hat / CentOS: `yum install git`
 * Arch: `pacman -S git`
-?> 全てのプラットフォームにおいて、Docker を使うことも可能です。[詳細はこちらをクリックしてください](getting_started_build_tools.md#docker)。
+?> 全てのプラットフォームにおいて、Docker を使うことも可能です。[詳細はこちらをクリックしてください](ja/getting_started_build_tools.md#docker)。
-## QMK の設定
+## QMK の設定 :id=set-up-qmk
 Linux/Unix 環境が準備できたら QMK のダウンロードの準備は完了です。Git を使用して QMK のリポジトリを「クローン」することで QMK をダウンロードします。ターミナルか MSYS2 MinGW ウィンドウを開いて、このガイドの残りの部分では開いたままにします。そのウィンドウ内で、次の2つのコマンドを実行します。
@@ -88,7 +88,7 @@ git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
 cd qmk_firmware
 ```
-?> 既に [GitHub の使いかた](getting_started_github.md)を知っているなら、clone ではなく fork を勧めます。この一文の意味が分からない場合、このメッセージは無視してかまいません。
+?> 既に [GitHub の使いかた](ja/getting_started_github.md)を知っているなら、clone ではなく fork を勧めます。この一文の意味が分からない場合、このメッセージは無視してかまいません。
 QMK には、必要な残りの設定を手助けするスクリプトが含まれています。
 セットアップ作業を完了させるため、次のコマンドを実行します。
@@ -119,4 +119,4 @@ Checking file size of clueboard_66_rev3_default.hex
 # キーマップの作成
 これであなた専用のキーマップを作成する準備ができました！
-次は [Building Your First Firmware](newbs_building_firmware.md) で専用のキーマップを作成します。
+次は [Building Your First Firmware](ja/newbs_building_firmware.md) で専用のキーマップを作成します。
diff --git a/docs/ja/newbs_git_best_practices.md b/docs/ja/newbs_git_best_practices.md
new file mode 100644
index 000000000..4e20e4e0b
--- /dev/null
+++ b/docs/ja/newbs_git_best_practices.md
@@ -0,0 +1,24 @@
+# QMK における Git 運用作法 :id=best-git-practices-for-working-with-qmk
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_best_practices.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_best_practices.md | cat
+-->
+## または、"如何にして私は心配することをやめて Git を愛することを学んだか。"
+このセクションは、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。
+QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。
+その後、意図的に一部を壊してみせて、それらを修正する方法を説明します。
+このセクションは以下のことを前提としています:
+1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](ja/getting_started_github.md) している。
+2. あなたは、[環境構築](ja/newbs_getting_started.md#set-up-your-environment) と [QMK の設定](ja/newbs_getting_started.md#set-up-qmk) を両方とも完了している。
+---
+- パート 1: [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md)
+- パート 2: [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md)
+- パート 3: [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md)
diff --git a/docs/ja/newbs_git_resolving_merge_conflicts.md b/docs/ja/newbs_git_resolving_merge_conflicts.md
new file mode 100644
index 000000000..893c3d503
--- /dev/null
+++ b/docs/ja/newbs_git_resolving_merge_conflicts.md
@@ -0,0 +1,94 @@
+#  マージの競合の解決
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_resolving_merge_conflicts.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_resolving_merge_conflicts.md | cat
+-->
+ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。
+これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。
+?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。
+その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。
+## 変更のリベース
+*リベース* は、コミット履歴のある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。
+マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。
+開始するには、次を実行します:
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。
+最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。
+入力された `git rev-list` コマンドの出力は2つの数値を返します:
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。
+現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます:
+```
+git rebase upstream/master
+```
+これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。
+テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります:
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。
+`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。
+Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。
+ファイルを再編集して、競合を解決します。
+変更を加えてから、ファイルを保存します。
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+そしてコマンド実行:
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。
diff --git a/docs/ja/newbs_git_resynchronize_a_branch.md b/docs/ja/newbs_git_resynchronize_a_branch.md
new file mode 100644
index 000000000..80ae794a9
--- /dev/null
+++ b/docs/ja/newbs_git_resynchronize_a_branch.md
@@ -0,0 +1,88 @@
+# 同期のとれていない git ブランチの再同期
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_resynchronize_a_branch.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_resynchronize_a_branch.md | cat
+-->
+仮にあなたの `master` ブランチにあなたのコミットを行い、そしてあなたの QMK リポジトリの更新が必要になったとします。
+(フォーク元の) QMKの `master` ブランチをあなたの `master` ブランチに `git pull` することもできますが、GitHub は、あなたのブランチが `qmk:master` より何コミットか先行していると通知します、この状態で QMK にプルリクエストを行う場合、問題が発生する可能性があります。
+(訳注：この通知は、GitHub のあなたのリポジトリの code ペインのブランチ選択メニューの下のあたりで `This branch is 3 commit ahead of qmk:master` という様な文面で表示されています。)
+?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。  
+(訳注：この文書で言う、「同期のとれていない git ブランチ」とは、master ブランチに関する、この「コミットしない」方針を逸脱して、QMK の master リポジトリに存在しないコミットがあなたのフォークの master ブランチに入っている状態を指します。)
+## あなた自身の `master` ブランチでの変更のバックアップ（オプション）
+救えるものなら自分の行った変更を失いたくはないでしょう。
+あなたの `master` ブランチに既に加えた変更を保存したい場合、最も簡単な方法は、単に「ダーティな」`master` ブランチの複製を作成することです：
+```sh
+git branch old_master master
+```
+これで、 `master` ブランチの複製である `old_master` という名前のブランチができました。
+## あなたのブランチの再同期
+さあ、`master` ブランチを再同期します。
+この手順では、QMK のリポジトリを git のリモートリポジトリとして設定する必要があります。
+設定済みのリモートリポジトリを確認するには、`git remote -v` を実行し、次のような結果が返されなければなりません。
+```sh
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+もし、上記のようにならずに以下のように参照されるフォークが、1つだけ表示される場合：
+```sh
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/qmk/qmk_firmware.git (fetch)
+origin  https://github.com/qmk/qmk_firmware.git (push)
+```
+新しいリモートリポジトリを追加します：
+```sh
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+次に、`origin` リモートリポジトリを、あなた自身のフォークにリダイレクトします：
+```sh
+git remote set-url origin https://github.com/<あなたのユーザ名>/qmk_firmware.git
+```
+両方のリモートリポジトリが設定されたので、次を実行して、QMK である `upstream` リポジトリの参照を更新する必要があります。
+```sh
+git fetch upstream
+```
+この時点で、次を実行してあなたの(訳注：master)ブランチを QMK のブランチに再同期します。
+(訳注： 今現在 `master` ブランチがチェックアウトされていなければなりません。
+ そうなってなければ、`git checkout master` を先に実行しておく必要があります。)
+```sh
+git reset --hard upstream/master
+```
+これらの手順により、あなたのコンピュータ上のリポジトリが更新されますが、あなたの GitHub 上のフォークはまだ同期されていません。
+GitHub 上のフォークを再同期するには、あなたのフォークにプッシュして、ローカルリポジトリに反映されていないリモート変更をオーバーライドするように Git に指示する必要があります。
+これを行うには、次を実行します：
+```sh
+git push --force-with-lease
+```
+!> 他のユーザーがコミットを投稿するフォークで `git push --force-with-lease` を**実行しないでください**。これをすると、かれらのコミットが消去されてしまいます。
+これで、あなたの GitHub フォーク、あなたのローカルファイル、および QMK のリポジトリはすべて同じになりました。
+ここから、[ブランチを使って](ja/newbs_git_using_your_master_branch.md#making-changes)さらに必要な変更を加え、通常どおりそれらを投稿できます。
diff --git a/docs/ja/newbs_git_using_your_master_branch.md b/docs/ja/newbs_git_using_your_master_branch.md
new file mode 100644
index 000000000..086005034
--- /dev/null
+++ b/docs/ja/newbs_git_using_your_master_branch.md
@@ -0,0 +1,101 @@
+# あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: adf4acf59:docs/newbs_git_using_your_master_branch.md
+  git diff adf4acf59 HEAD -- docs/newbs_git_using_your_master_branch.md | cat
+-->
+QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。
+代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。
+マージの競合 &mdash; これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 &mdash; の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。
+## あなたの master ブランチを更新する
+`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。
+これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+?> `upstream`(訳注: `upstream` は`上流`という意味です)という名前は任意ですが、一般的な慣習です。
+QMK のリモートリポジトリには、あなたにとって分かりやすい名前を付けることができます。
+Git の `remote` コマンドは、構文 `git remote add <name> <url>` を使用します。
+`<name>` はリモートリポジトリの省略形としてあなたが指定するものです。
+この名前は、`fetch`、`pull`、`push` やそれ以外の多くの Git コマンドで、対象のリモートリポジトリを指定するために使用されます。
+リポジトリが追加されたことを確認するには、`git remote -v` を実行します。
+次のように表示されます。
+```
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。
+このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ &mdash; "refs" と総称されます &mdash; を取得します。
+これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。
+あなたのフォークの `master` を更新するには、次を実行します、各行の後にEnterキーを押してください:
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。
+## 変更を行なう :id=making-changes
+変更するには、以下を入力して新しいブランチを作成します:
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。
+`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。
+この引数は最初のプッシュでのみ使用する必要があります。
+その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。
+?> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。
+ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。
+デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。
+コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます:
+```
+git checkout -b dev_branch master
+```
+これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。
+ブランチに対して多くの小さなコミットを行うことをお勧めします。
+そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。
+変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします:
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。
+これは、Git の「ロードゾーン」です。
+これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。
+変更内容が一目でわかるように、説明的なコミットメッセージを使用します。
+?> 複数のファイルを変更した場合、`git add -- path/to/file1 path/to/file2 ...` を実行すれば、あなたの望むファイルを追加できます。
+## 変更を公開する
+最後のステップは、変更をフォークにプッシュすることです。
+これを行うには、`git push`と入力します。
+Gitは、 `dev_branch`の現在の状態をフォークに公開します。
diff --git a/docs/ja/newbs_learn_more_resources.md b/docs/ja/newbs_learn_more_resources.md
index 632cd9100..9adcf5360 100644
--- a/docs/ja/newbs_learn_more_resources.md
+++ b/docs/ja/newbs_learn_more_resources.md
@@ -3,7 +3,7 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
  original document: ed0575fc8:docs/newbs_learn_more_resources.md
-  git diff ed0575fc8 HEAD docs/newbs_learn_more_resources.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_learn_more_resources.md | cat
 -->
 これらのリソースは、QMKコミュニティの新しいメンバーに、初心者向けドキュメントで提供されている情報に対する理解を深めることを目的としています。
@@ -21,6 +21,10 @@
 _日本語のリソース情報を募集中です。_
+* [Git Game To Learn From Examples(日本語対応有り)](https://learngitbranching.js.org/)
+* [QMK で Github を使う方法](ja/getting_started_github.md)
+* [貢献方法](ja/contributing.md)
 ## コマンドラインに関するリソース:
 ### 英語
diff --git a/docs/ja/newbs_testing_debugging.md b/docs/ja/newbs_testing_debugging.md
index a96406187..5ec5811a1 100644
--- a/docs/ja/newbs_testing_debugging.md
+++ b/docs/ja/newbs_testing_debugging.md
@@ -3,7 +3,7 @@
 <!---
  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
  original document: ed0575fc8:docs/newbs_testing_debugging.md
-  git diff ed0575fc8 HEAD docs/newbs_testing_debugging.md | cat
+  git diff ed0575fc8 HEAD -- docs/newbs_testing_debugging.md | cat
 -->
 カスタムファームウェアをキーボードへ書き込んだら、テストする準備が整います。運が良ければ全て問題なく動作しているはずですが、もしそうでなければこのドキュメントがどこが悪いのか調べるのに役立ちます。
@@ -22,7 +22,7 @@
 ## デバッグ
-`rules.mk`へ`CONSOLE_ENABLE = yes`の設定をするとキーボードはデバッグ情報を出力します。デフォルトの出力は非常に限られたものですが、デバッグモードをオンにすることでデバッグ情報の量を増やすことが出来ます。キーマップの`DEBUG`キーコードを使用するか、デバッグモードを有効にする [Command](feature_command.md) 機能を使用するか、以下のコードをキーマップに追加します。
+`rules.mk`へ`CONSOLE_ENABLE = yes`の設定をするとキーボードはデバッグ情報を出力します。デフォルトの出力は非常に限られたものですが、デバッグモードをオンにすることでデバッグ情報の量を増やすことが出来ます。キーマップの`DEBUG`キーコードを使用するか、デバッグモードを有効にする [Command](ja/feature_command.md) 機能を使用するか、以下のコードをキーマップに追加します。
 ```c
 void keyboard_post_init_user(void) {
@@ -46,7 +46,7 @@ void keyboard_post_init_user(void) {
 ## 独自のデバッグメッセージを送信する
-[custom code](custom_quantum_functions.md)内からデバッグメッセージを出力すると便利な場合があります。それはとても簡単です。ファイルの先頭に`print.h`のインクルードを追加します:
+[custom code](ja/custom_quantum_functions.md)内からデバッグメッセージを出力すると便利な場合があります。それはとても簡単です。ファイルの先頭に`print.h`のインクルードを追加します:
    #include <print.h>
@@ -59,7 +59,7 @@ void keyboard_post_init_user(void) {
 ## デバッグの例
-以下は現実世界での実際のデバッグ手法の例を集めたものです。追加情報は[Debugging/Troubleshooting QMK](faq_debug.md)を参照してください。
+以下は現実世界での実際のデバッグ手法の例を集めたものです。追加情報は[Debugging/Troubleshooting QMK](ja/faq_debug.md)を参照してください。
 ### マトリックス上のどの場所でキー押下が起こったか？
diff --git a/docs/keycodes.md b/docs/keycodes.md
index fa01df63d..dd4c4418b 100644
--- a/docs/keycodes.md
+++ b/docs/keycodes.md
@@ -214,18 +214,8 @@ This is a reference only. Each group of keys links to the page documenting their
 |`DEBUG`        |           |Toggle debug mode                                                    |
 |`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
 |`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
-|`KC_LCPO`      |           |Left Control when held, `(` when tapped                              |
-|`KC_RCPC`      |           |Right Control when held, `)` when tapped                             |
-|`KC_LAPO`      |           |Left Alt when held, `(` when tapped                                  |
-|`KC_RAPC`      |           |Right Alt when held, `)` when tapped                                 |
-|`KC_SFTENT`    |           |Right Shift when held, Enter when tapped                             |
 |`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
 |`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`         |           |Call macro `n`                                                       |
-|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
 ## [Audio Keys](feature_audio.md)
@@ -257,37 +247,37 @@ This is a reference only. Each group of keys links to the page documenting their
 ## [Bootmagic](feature_bootmagic.md)
-|Key                               |Aliases  |Description                                |
+|Key                               |Aliases  |Description                                                               |
-|----------------------------------|---------|-------------------------------------------|
+|----------------------------------|---------|--------------------------------------------------------------------------|
-|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |         |Swap Caps Lock and Left Control            |
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`     |`CL_SWAP`|Swap Caps Lock and Left Control                                           |
-|`MAGIC_CAPSLOCK_TO_CONTROL`       |         |Treat Caps Lock as Control                 |
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |`CL_NORM`|Unswap Caps Lock and Left Control                                         |
-|`MAGIC_SWAP_LCTL_LGUI`            |         |Swap Left Control and GUI                  |
+|`MAGIC_CAPSLOCK_TO_CONTROL`       |`CL_CTRL`|Treat Caps Lock as Control                                                |
-|`MAGIC_SWAP_RCTL_RGUI`            |         |Swap Right Control and GUI                 |
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |`CL_CAPS`|Stop treating Caps Lock as Control                                        |
-|`MAGIC_SWAP_LALT_LGUI`            |         |Swap Left Alt and GUI                      |
+|`MAGIC_SWAP_LCTL_LGUI`            |`LCG_SWP`|Swap Left Control and GUI                                                 |
-|`MAGIC_SWAP_RALT_RGUI`            |         |Swap Right Alt and GUI                     |
+|`MAGIC_UNSWAP_LCTL_LGUI`          |`LCG_NRM`|Unswap Left Control and GUI                                               |
-|`MAGIC_NO_GUI`                    |         |Disable the GUI key                        |
+|`MAGIC_SWAP_RCTL_RGUI`            |`RCG_SWP`|Swap Right Control and GUI                                                |
-|`MAGIC_SWAP_GRAVE_ESC`            |         |Swap <code>&#96;</code> and Escape         |
+|`MAGIC_UNSWAP_RCTL_RGUI`          |`RCG_NRM`|Unswap Right Control and GUI                                              |
-|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |         |Swap `\` and Backspace                     |
+|`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Control and GUI on both sides                                        |
-|`MAGIC_HOST_NKRO`                 |         |Force NKRO on                              |
+|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Control and GUI on both sides                                      |
-|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides             |
+|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Control and GUI swap on both sides                                 |
-|`MAGIC_SWAP_CTL_GUI`              |`CG_SWAP`|Swap Ctrl and GUI on both sides (for macOS)|
+|`MAGIC_SWAP_LALT_LGUI`            |`LAG_SWP`|Swap Left Alt and GUI                                                     |
-|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`   |         |Unswap Caps Lock and Left Control          |
+|`MAGIC_UNSWAP_LALT_LGUI`          |`LAG_NRM`|Unswap Left Alt and GUI                                                   |
-|`MAGIC_UNCAPSLOCK_TO_CONTROL`     |         |Stop treating Caps Lock as Control         |
+|`MAGIC_SWAP_RALT_RGUI`            |`RAG_SWP`|Swap Right Alt and GUI                                                    |
-|`MAGIC_UNSWAP_LCTL_LGUI`          |         |Unswap Left Control and GUI                |
+|`MAGIC_UNSWAP_RALT_RGUI`          |`RAG_NRM`|Unswap Right Alt and GUI                                                  |
-|`MAGIC_UNSWAP_RCTL_RGUI`          |         |Unswap Right Control and GUI               |
+|`MAGIC_SWAP_ALT_GUI`              |`AG_SWAP`|Swap Alt and GUI on both sides                                            |
-|`MAGIC_UNSWAP_LALT_LGUI`          |         |Unswap Left Alt and GUI                    |
+|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides                                          |
-|`MAGIC_UNSWAP_RALT_RGUI`          |         |Unswap Right Alt and GUI                   |
+|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides                                     |
-|`MAGIC_UNNO_GUI`                  |         |Enable the GUI key                         |
+|`MAGIC_NO_GUI`                    |`GUI_OFF`|Disable the GUI keys                                                      |
-|`MAGIC_UNSWAP_GRAVE_ESC`          |         |Unswap <code>&#96;</code> and Escape       |
+|`MAGIC_UNNO_GUI`                  |`GUI_ON` |Enable the GUI keys                                                       |
-|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|         |Unswap `\` and Backspace                   |
+|`MAGIC_SWAP_GRAVE_ESC`            |`GE_SWAP`|Swap <code>&#96;</code> and Escape                                        |
-|`MAGIC_UNHOST_NKRO`               |         |Force NKRO off                             |
+|`MAGIC_UNSWAP_GRAVE_ESC`          |`GE_NORM`|Unswap <code>&#96;</code> and Escape                                      |
-|`MAGIC_UNSWAP_ALT_GUI`            |`AG_NORM`|Unswap Alt and GUI on both sides           |
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`  |`BS_SWAP`|Swap `\` and Backspace                                                    |
-|`MAGIC_UNSWAP_CTL_GUI`            |`CG_NORM`|Unswap Ctrl and GUI on both sides          |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|`BS_NORM`|Unswap `\` and Backspace                                                  |
-|`MAGIC_TOGGLE_ALT_GUI`            |`AG_TOGG`|Toggle Alt and GUI swap on both sides      |
+|`MAGIC_HOST_NKRO`                 |`NK_ON`  |Enable N-key rollover                                                     |
-|`MAGIC_TOGGLE_CTL_GUI`            |`CG_TOGG`|Toggle Ctrl and GUI swap on both sides     |
+|`MAGIC_UNHOST_NKRO`               |`NK_OFF` |Disable N-key rollover                                                    |
-|`MAGIC_TOGGLE_NKRO`               |         |Turn NKRO on or off                        |
+|`MAGIC_TOGGLE_NKRO`               |`NK_TOGG`|Toggle N-key rollover                                                     |
-|`MAGIC_EE_HANDS_LEFT`             |         |Set "Left Hand" for EE_HANDS handedness    |
+|`MAGIC_EE_HANDS_LEFT`             |`EH_LEFT`|Set the master half of a split keyboard as the left hand (for `EE_HANDS`) |
-|`MAGIC_EE_HANDS_RIGHT`            |         |Set "Right Hand" for EE_HANDS handedness   |
+|`MAGIC_EE_HANDS_RIGHT`            |`EH_RGHT`|Set the master half of a split keyboard as the right hand (for `EE_HANDS`)|
 ## [Bluetooth](feature_bluetooth.md)
@@ -389,12 +379,12 @@ This is a reference only. Each group of keys links to the page documenting their
 |`RGB_TOG`          |          |Toggle RGB lighting on or off                                       |
 |`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held           |
 |`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held|
-|`RGB_HUI`          |          |Increase hue                                                        |
+|`RGB_HUI`          |          |Increase hue, decrease hue when Shift is held                       |
-|`RGB_HUD`          |          |Decrease hue                                                        |
+|`RGB_HUD`          |          |Decrease hue, increase hue when Shift is held                       |
-|`RGB_SAI`          |          |Increase saturation                                                 |
+|`RGB_SAI`          |          |Increase saturation, decrease saturation when Shift is held         |
-|`RGB_SAD`          |          |Decrease saturation                                                 |
+|`RGB_SAD`          |          |Decrease saturation, increase saturation when Shift is held         |
-|`RGB_VAI`          |          |Increase value (brightness)                                         |
+|`RGB_VAI`          |          |Increase value (brightness), decrease value when Shift is held      |
-|`RGB_VAD`          |          |Decrease value (brightness)                                         |
+|`RGB_VAD`          |          |Decrease value (brightness), increase value when Shift is held      |
 |`RGB_MODE_PLAIN`   |`RGB_M_P `|Static (no animation) mode                                          |
 |`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode                                            |
 |`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode                                              |
@@ -407,19 +397,19 @@ This is a reference only. Each group of keys links to the page documenting their
 ## [RGB Matrix Lighting](feature_rgb_matrix.md)
-|Key                |Aliases   |Description                                                         |
+|Key                |Aliases   |Description                                                                           |
-|-------------------|----------|--------------------------------------------------------------------|
+|-------------------|----------|--------------------------------------------------------------------------------------|
-|`RGB_TOG`          |          |Toggle RGB lighting on or off                                       |
+|`RGB_TOG`          |          |Toggle RGB lighting on or off                                                         |
-|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held           |
+|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held                             |
-|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held|
+|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held                  |
-|`RGB_HUI`          |          |Increase hue                                                        |
+|`RGB_HUI`          |          |Increase hue, decrease hue when Shift is held                                         |
-|`RGB_HUD`          |          |Decrease hue                                                        |
+|`RGB_HUD`          |          |Decrease hue, increase hue when Shift is held                                         |
-|`RGB_SAI`          |          |Increase saturation                                                 |
+|`RGB_SAI`          |          |Increase saturation, decrease saturation when Shift is held                           |
-|`RGB_SAD`          |          |Decrease saturation                                                 |
+|`RGB_SAD`          |          |Decrease saturation, increase saturation when Shift is held                           |
-|`RGB_VAI`          |          |Increase value (brightness)                                         |
+|`RGB_VAI`          |          |Increase value (brightness), decrease value when Shift is held                        |
-|`RGB_VAD`          |          |Decrease value (brightness)                                         |
+|`RGB_VAD`          |          |Decrease value (brightness), increase value when Shift is held                        |
-|`RGB_SPI`          |          |Increase effect speed (does no support eeprom yet)                  |
+|`RGB_SPI`          |          |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
-|`RGB_SPD`          |          |Decrease effect speed (does no support eeprom yet)                  |
+|`RGB_SPD`          |          |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
 ## [Thermal Printer](feature_thermal_printer.md)
@@ -461,6 +451,18 @@ This is a reference only. Each group of keys links to the page documenting their
 |`OSM(mod)`  |Hold `mod` for one keypress       |
 |`OSL(layer)`|Switch to `layer` for one keypress|
+## [Space Cadet](feature_space_cadet.md)
+|Key        |Description                             |
+|-----------|----------------------------------------|
+|`KC_LCPO`  |Left Control when held, `(` when tapped |
+|`KC_RCPC`  |Right Control when held, `)` when tapped|
+|`KC_LSPO`  |Left Shift when held, `(` when tapped   |
+|`KC_RSPC`  |Right Shift when held, `)` when tapped  |
+|`KC_LAPO`  |Left Alt when held, `(` when tapped     |
+|`KC_RAPC`  |Right Alt when held, `)` when tapped    |
+|`KC_SFTENT`|Right Shift when held, Enter when tapped|
 ## [Swap Hands](feature_swap_hands.md)
 |Key        |Description                                                              |
diff --git a/docs/newbs.md b/docs/newbs.md
index 904a52945..775bba2ca 100644
--- a/docs/newbs.md
+++ b/docs/newbs.md
@@ -13,7 +13,7 @@ There are 7 main sections to this guide:
 * [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md)
 * [Flashing Firmware](newbs_flashing.md)
 * [Testing and Debugging](newbs_testing_debugging.md)
-* [Git Best Practices](newbs_best_practices.md)
+* [Best Git Practices](newbs_git_best_practices.md)
 * [Learn More with these Resources](newbs_learn_more_resources.md)
 This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md).
diff --git a/docs/newbs_best_practices.md b/docs/newbs_best_practices.md
deleted file mode 100644
index 61bcc0c6a..000000000
--- a/docs/newbs_best_practices.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# Best Practices
-## Or, "How I Learned to Stop Worrying and Love Git."
-This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them.
-This document assumes a few things:
-1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account.
-2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup).
-## Your fork's master: Update Often, Commit Never
-It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing.
-To reduce the chances of merge conflicts &mdash; instances where two or more users have edited the same part of a file concurrently &mdash; keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch.
-### Updating your master branch
-To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter:
-```
-git remote add upstream https://github.com/qmk/qmk_firmware.git
-```
-To verify that the repository has been added, run `git remote -v`, which should return the following:
-```
-$ git remote -v
-origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
-origin  https://github.com/<your_username>/qmk_firmware.git (push)
-upstream        https://github.com/qmk/qmk_firmware.git (fetch)
-upstream        https://github.com/qmk/qmk_firmware.git (push)
-```
-Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK.
-To update your fork's master, run the following, hitting the Enter key after each line:
-```
-git checkout master
-git fetch upstream
-git pull upstream master
-git push origin master
-```
-This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork.
-### Making Changes
-To make changes, create a new branch by entering:
-```
-git checkout -b dev_branch
-git push --set-upstream origin dev_branch
-```
-This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments.
-!> With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`.
-You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make.
-By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command:
-```
-git checkout -b dev_branch master
-```
-Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch:
-```
-git add path/to/updated_file
-git commit -m "My commit message."
-```
-`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance.
-!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually.
-### Publishing Your Changes
-The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork.
-## Resolving Merge Conflicts
-Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files.
-### Rebasing Your Changes
-A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time.
-To start, run the following:
-```
-git fetch upstream
-git rev-list --left-right --count HEAD...upstream/master
-```
-The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers:
-```
-$ git rev-list --left-right --count HEAD...upstream/master
-7       35
-```
-The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch.
-Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation:
-```
-git rebase upstream/master
-```
-This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch.
-```
-$ git rebase upstream/master
-First, rewinding head to replay your work on top of it...
-Applying: Commit #1
-Using index info to reconstruct a base tree...
-M       conflicting_file_1.txt
-Falling back to patching base and 3-way merge...
-Auto-merging conflicting_file_1.txt
-CONFLICT (content): Merge conflict in conflicting_file_1.txt
-error: Failed to merge in the changes.
-hint: Use 'git am --show-current-patch' to see the failed patch
-Patch failed at 0001 Commit #1
-Resolve all conflicts manually, mark them as resolved with
-"git add/rm <conflicted_files>", then run "git rebase --continue".
-You can instead skip this commit: run "git rebase --skip".
-To abort and get back to the state before "git rebase", run "git rebase --abort".
-```
-This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this:
-```
-<<<<<<< HEAD
-<p>For help with any issues, email us at support@webhost.us.</p>
-=======
-<p>Need help? Email support@webhost.us.</p>
->>>>>>> Commit #1
-```
-The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit.
-Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file.
-```
-<p>Need help? Email support@webhost.us.</p>
-```
-Now run:
-```
-git add conflicting_file_1.txt
-git rebase --continue
-```
-Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end.
diff --git a/docs/newbs_building_firmware.md b/docs/newbs_building_firmware.md
index 5a8f181b8..d7d31c07f 100644
--- a/docs/newbs_building_firmware.md
+++ b/docs/newbs_building_firmware.md
@@ -42,7 +42,7 @@ Open up your `keymap.c`. Inside this file you'll find the structure that control
    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.
+This line indicates the start of the list of Layers. Below that you'll find lines containing either `LAYOUT` or `KEYMAP`, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.
 !> When editing your keymap file be careful not to add or remove any commas. If you do you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.
diff --git a/docs/newbs_git_best_practices.md b/docs/newbs_git_best_practices.md
new file mode 100644
index 000000000..c0cb3a294
--- /dev/null
+++ b/docs/newbs_git_best_practices.md
@@ -0,0 +1,16 @@
+# Best Git Practices for Working with QMK
+## Or, "How I Learned to Stop Worrying and Love Git."
+This section aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them.
+This section assumes a few things:
+1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account.
+2. You've set up both [your build environment](newbs_getting_started.md#set-up-your-environment) and [QMK](newbs_getting_started.md#set-up-qmk).
+---
+- Part 1: [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md)
+- Part 2: [Resolving Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
+- Part 3: [Resynchronizing an Out-of-Sync Git Branch](newbs_git_resynchronize_a_branch.md)
diff --git a/docs/newbs_git_resolving_merge_conflicts.md b/docs/newbs_git_resolving_merge_conflicts.md
new file mode 100644
index 000000000..467c13abb
--- /dev/null
+++ b/docs/newbs_git_resolving_merge_conflicts.md
@@ -0,0 +1,79 @@
+# Resolving Merge Conflicts
+Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files.
+?> This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md). If you are not familiar with that document, please read it first, then return here.
+## Rebasing Your Changes
+A *rebase* is Git's way of taking changes that were applied at one point in the commit history, reversing them, and then applying the same changes at another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time.
+To start, run the following:
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers:
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch.
+Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation:
+```
+git rebase upstream/master
+```
+This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch.
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this:
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit.
+Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file.
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+Now run:
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end.
diff --git a/docs/newbs_git_resynchronize_a_branch.md b/docs/newbs_git_resynchronize_a_branch.md
new file mode 100644
index 000000000..3e7acdba7
--- /dev/null
+++ b/docs/newbs_git_resynchronize_a_branch.md
@@ -0,0 +1,71 @@
+# Resynchronizing an Out-of-Sync Git Branch
+Suppose you have committed to your `master` branch, and now need to update your QMK repository. You could `git pull` QMK's `master` branch into your own, but GitHub will tell you that your branch is a number of commits ahead of `qmk:master`, which can create issues if you want to make a pull request to QMK.
+?> This document builds upon the concepts detailed in [Your Fork's Master: Update Often, Commit Never](newbs_git_using_your_master_branch.md). If you are not familiar with that document, please read it first, then return here.
+## Backing Up the Changes on Your Own Master Branch (Optional)
+No one wants to lose work if it can be helped. If you want to save the changes you've already made to your `master` branch, the simplest way to do so is to simply create a duplicate of your "dirty" `master` branch:
+```sh
+git branch old_master master
+```
+Now you have a branch named `old_master` that is a duplicate of your `master` branch.
+## Resynchronizing Your Branch
+Now it's time to resynchronize your `master` branch. For this step, you'll want to have QMK's repository configured as a remote in Git. To check your configured remotes, run `git remote -v`, which should return something similar to:
+```sh
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+If you only see one fork referenced:
+```sh
+QMKuser ~/qmk_firmware (master)
+$ git remote -v
+origin  https://github.com/qmk/qmk_firmware.git (fetch)
+origin  https://github.com/qmk/qmk_firmware.git (push)
+```
+add a new remote with:
+```sh
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+Then, redirect the `origin` remote to your own fork with:
+```sh
+git remote set-url origin https://github.com/<your_username>/qmk_firmware.git
+```
+Now that you have both remotes configured, you need to update the references for the upstream repository, which is QMK's, by running:
+```sh
+git fetch upstream
+```
+At this point, resynchronize your branch to QMK's by running:
+```sh
+git reset --hard upstream/master
+```
+These steps will update the repository on your computer, but your GitHub fork will still be out of sync. To resynchronize your fork on GitHub, you need to push to your fork, instructing Git to override any remote changes that are not reflected in your local repository. To do this, run:
+```sh
+git push --force-with-lease
+```
+!> **DO NOT** run `git push --force-with-lease` on a fork to which other users post commits. This will erase their commits.
+Now your GitHub fork, your local files, and QMK's repository are all the same. From here you can make further needed changes ([use a branch!](newbs_git_using_your_master_branch.md#making-changes)) and post them as normal.
diff --git a/docs/newbs_git_using_your_master_branch.md b/docs/newbs_git_using_your_master_branch.md
new file mode 100644
index 000000000..2032b83b2
--- /dev/null
+++ b/docs/newbs_git_using_your_master_branch.md
@@ -0,0 +1,74 @@
+# Your Fork's Master: Update Often, Commit Never
+It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing.
+To reduce the chances of merge conflicts &mdash; instances where two or more users have edited the same part of a file concurrently &mdash; keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch.
+## Updating your master branch
+To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter:
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+?> The name `upstream` is arbitrary, but a common convention; you can give the QMK remote any name that suits you. Git's `remote` command uses the syntax `git remote add <name> <url>`, `<name>` being shorthand for the remote repo. This name can be used with many Git commands, including but not limited to `fetch`, `pull` and `push`, to specify the remote repo on which to act.
+To verify that the repository has been added, run `git remote -v`, which should return the following:
+```
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK.
+To update your fork's master, run the following, hitting the Enter key after each line:
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork.
+## Making Changes
+To make changes, create a new branch by entering:
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments.
+?> With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`.
+You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make.
+By default `git checkout -b` will base your new branch on the branch that is currently checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command:
+```
+git checkout -b dev_branch master
+```
+Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch:
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance.
+?> If you've changed multiple files, you can use `git add -- path/to/file1 path/to/file2 ...` to add all your desired files.
+## Publishing Your Changes
+The last step is to push your changes to your fork. To do this, enter `git push`. Git will then publish the current state of `dev_branch` to your fork.
diff --git a/docs/proton_c_conversion.md b/docs/proton_c_conversion.md
index 8014a35e0..dc0a3f484 100644
--- a/docs/proton_c_conversion.md
+++ b/docs/proton_c_conversion.md
@@ -29,3 +29,5 @@ These are defaults based on what has been implemented for ARM boards.
 | [Audio](feature_audio.md)           | Enabled                                                                                                          |  
 | [RGB Lighting](feature_rgblight.md) | Disabled                                                                                                         |
 | [Backlight](feature_backlight.md)   | Forces [task driven PWM](feature_backlight.md#software-pwm-driver) until ARM can provide automatic configuration |
+| USB Host (e.g. USB-USB converter)   | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
+| [Split keyboards](feature_split_keyboard.md) | Not supported yet                                                                                       |
diff --git a/docs/pt-br/README.md b/docs/pt-br/README.md
new file mode 100644
index 000000000..7cff6ce62
--- /dev/null
+++ b/docs/pt-br/README.md
@@ -0,0 +1,31 @@
+# Quantum Mechanical Keyboard Firmware
+[![Current Version](https://img.shields.io/github/tag/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/tags)
+[![Build Status](https://travis-ci.org/qmk/qmk_firmware.svg?branch=master)](https://travis-ci.org/qmk/qmk_firmware)
+[![Discord](https://img.shields.io/discord/440868230475677696.svg)](https://discord.gg/Uq7gcHh)
+[![Docs Status](https://img.shields.io/badge/docs-ready-orange.svg)](https://docs.qmk.fm)
+[![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly)
+[![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/)
+## O que é o firmware QMK?
+QMK (*Quantum Mechanical Keyboard*) é uma comunidade de código aberto que mantém o QMK Firmware, o QMK Toolbox, qmk.fm e suas documentações. O QMK Firmware é um software embarcado ("firmware") de teclado baseado no [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) com alguns recursos úteis para os controladores Atmel AVR e, mais especificamente, na [linha de produtos OLKB](http://olkb.com), o teclado [ErgoDox EZ](http://www.ergodox-ez.com) e a [linha de produtos Clueboard](http://clueboard.co/). Também foi portado para chips ARM usando o ChibiOS. Você pode usá-lo no seu próprio teclado com fio ou personalizado.
+## Como obter e usar o QMK
+Se você planeja contribuir com um _keymap_ ("mapa de teclas"), teclado ou recursos para o QMK, o jeito mais fácil é [percorrer o repositório através do Github](https://github.com/qmk/qmk_firmware#fork-destination-box) e clonar seu repositório localmente para fazer suas alterações, dê um _push_ nelas e abra uma [_Pull request_](https://github.com/qmk/qmk_firmware/pulls) no seu fork.
+Caso contrário, você pode cloná-lo diretamente com `git clone https://github.com/qmk/qmk_firmware`. Não faça o download dos arquivos zip ou tar; é necessário um repositório git para baixar os submódulos para compilar.
+## Como compilar
+Antes de compilar, você precisará [instalar um ambiente específico](getting_started_build_tools.md) para o desenvolvimento em plataforma AVR e/ou ARM; vez que isto for feito, você usará o comando `make` para criar um teclado e um mapa de teclas com a seguinte notação:
+    make planck/rev4:default
+Isso compilaria a revisão `rev4` do teclado ` planck` com o mapa de teclas `default`. Nem todos os teclados têm revisões (também chamadas de _subprojects_ ou _folders_); nesse caso, a revisão pode ser omitida:
+    make preonic:default
+## Como personalizar
+O QMK tem muitos [recursos](features.md) para explorar e uma boa quantidade de [documentação de referência](http://docs.qmk.fm) para explorar. A maioria dos recursos é aproveitada modificando seu [keymap](keymap.md) e alterando os [keycodes](keycodes.md).
diff --git a/docs/pt-br/_summary.md b/docs/pt-br/_summary.md
new file mode 100644
index 000000000..27efd73ab
--- /dev/null
+++ b/docs/pt-br/_summary.md
@@ -0,0 +1,121 @@
+* [Complete Newbs Guide](pt-br/newbs.md)
+  * [Getting Started](pt-br/newbs_getting_started.md)
+  * [Building Your First Firmware](pt-br/newbs_building_firmware.md)
+  * [Flashing Firmware](pt-br/newbs_flashing.md)
+  * [Testing and Debugging](pt-br/newbs_testing_debugging.md)
+  * [Git Best Practices](pt-br/newbs_best_practices.md)
+  * [Learning Resources](pt-br/newbs_learn_more_resources.md)
+* [QMK Basics](pt-br/README.md)
+  * [QMK Introduction](pt-br/getting_started_introduction.md)
+  * [QMK CLI](pt-br/cli.md)
+  * [QMK CLI Config](pt-br/cli_configuration.md)
+  * [Contributing to QMK](pt-br/contributing.md)
+  * [How to Use Github](pt-br/getting_started_github.md)
+  * [Getting Help](pt-br/getting_started_getting_help.md)
+* [Breaking Changes](pt-br/breaking_changes.md)
+  * [2019 Aug 30](pt-br/ChangeLog/20190830.md)
+* [FAQ](faq.md)
+  * [General FAQ](pt-br/faq_general.md)
+  * [Build/Compile QMK](pt-br/faq_build.md)
+  * [Debugging/Troubleshooting QMK](pt-br/faq_debug.md)
+  * [Keymap](pt-br/faq_keymap.md)
+  * [Driver Installation with Zadig](pt-br/driver_installation_zadig.md)
+* Detailed Guides
+  * [Install Build Tools](pt-br/getting_started_build_tools.md)
+  * [Vagrant Guide](pt-br/getting_started_vagrant.md)
+  * [Build/Compile Instructions](pt-br/getting_started_make_guide.md)
+  * [Flashing Firmware](pt-br/flashing.md)
+  * [Customizing Functionality](pt-br/custom_quantum_functions.md)
+  * [Keymap Overview](pt-br/keymap.md)
+* [Hardware](hardware.md)
+  * [AVR Processors](pt-br/hardware_avr.md)
+  * [Drivers](pt-br/hardware_drivers.md)
+* Reference
+  * [Keyboard Guidelines](pt-br/hardware_keyboard_guidelines.md)
+  * [Config Options](pt-br/config_options.md)
+  * [Keycodes](pt-br/keycodes.md)
+  * [Coding Conventions - C](pt-br/coding_conventions_c.md)
+  * [Coding Conventions - Python](pt-br/coding_conventions_python.md)
+  * [Documentation Best Practices](pt-br/documentation_best_practices.md)
+  * [Documentation Templates](pt-br/documentation_templates.md)
+  * [Glossary](pt-br/reference_glossary.md)
+  * [Unit Testing](pt-br/unit_testing.md)
+  * [Useful Functions](pt-br/ref_functions.md)
+  * [Configurator Support](pt-br/reference_configurator_support.md)
+  * [info.json Format](pt-br/reference_info_json.md)
+  * [Python CLI Development](pt-br/cli_development.md)
+* [Features](pt-br/features.md)
+  * [Basic Keycodes](pt-br/keycodes_basic.md)
+  * [US ANSI Shifted Keys](pt-br/keycodes_us_ansi_shifted.md)
+  * [Quantum Keycodes](pt-br/quantum_keycodes.md)
+  * [Advanced Keycodes](pt-br/feature_advanced_keycodes.md)
+  * [Audio](pt-br/feature_audio.md)
+  * [Auto Shift](pt-br/feature_auto_shift.md)
+  * [Backlight](pt-br/feature_backlight.md)
+  * [Bluetooth](pt-br/feature_bluetooth.md)
+  * [Bootmagic](pt-br/feature_bootmagic.md)
+  * [Combos](pt-br/feature_combo.md)
+  * [Command](pt-br/feature_command.md)
+  * [Debounce API](pt-br/feature_debounce_type.md)
+  * [DIP Switch](pt-br/feature_dip_switch.md)
+  * [Dynamic Macros](pt-br/feature_dynamic_macros.md)
+  * [Encoders](pt-br/feature_encoders.md)
+  * [Grave Escape](pt-br/feature_grave_esc.md)
+  * [Haptic Feedback](pt-br/feature_haptic_feedback.md)
+  * [HD44780 LCD Controller](pt-br/feature_hd44780.md)
+  * [Key Lock](pt-br/feature_key_lock.md)
+  * [Layouts](pt-br/feature_layouts.md)
+  * [Leader Key](pt-br/feature_leader_key.md)
+  * [LED Matrix](pt-br/feature_led_matrix.md)
+  * [Macros](pt-br/feature_macros.md)
+  * [Mouse Keys](pt-br/feature_mouse_keys.md)
+  * [OLED Driver](pt-br/feature_oled_driver.md)
+  * [One Shot Keys](pt-br/feature_advanced_keycodes.md#one-shot-keys)
+  * [Pointing Device](pt-br/feature_pointing_device.md)
+  * [PS/2 Mouse](pt-br/feature_ps2_mouse.md)
+  * [RGB Lighting](pt-br/feature_rgblight.md)
+  * [RGB Matrix](pt-br/feature_rgb_matrix.md)
+  * [Space Cadet](pt-br/feature_space_cadet.md)
+  * [Split Keyboard](pt-br/feature_split_keyboard.md)
+  * [Stenography](pt-br/feature_stenography.md)
+  * [Swap Hands](pt-br/feature_swap_hands.md)
+  * [Tap Dance](pt-br/feature_tap_dance.md)
+  * [Terminal](pt-br/feature_terminal.md)
+  * [Thermal Printer](pt-br/feature_thermal_printer.md)
+  * [Unicode](pt-br/feature_unicode.md)
+  * [Userspace](pt-br/feature_userspace.md)
+  * [Velocikey](pt-br/feature_velocikey.md)
+* For Makers and Modders
+  * [Hand Wiring Guide](pt-br/hand_wire.md)
+  * [ISP Flashing Guide](pt-br/isp_flashing_guide.md)
+  * [ARM Debugging Guide](pt-br/arm_debugging.md)
+  * [I2C Driver](pt-br/i2c_driver.md)
+  * [GPIO Controls](pt-br/internals_gpio_control.md)
+  * [Proton C Conversion](pt-br/proton_c_conversion.md)
+* For a Deeper Understanding
+  * [How Keyboards Work](pt-br/how_keyboards_work.md)
+  * [Understanding QMK](pt-br/understanding_qmk.md)
+* Other Topics
+  * [Using Eclipse with QMK](pt-br/other_eclipse.md)
+  * [Using VSCode with QMK](pt-br/other_vscode.md)
+  * [Support](pt-br/support.md)
+  * [How to add translations](pt-br/translating.md)
+* QMK Internals (In Progress)
+  * [Defines](pt-br/internals_defines.md)
+  * [Input Callback Reg](pt-br/internals_input_callback_reg.md)
+  * [Midi Device](pt-br/internals_midi_device.md)
+  * [Midi Device Setup Process](pt-br/internals_midi_device_setup_process.md)
+  * [Midi Util](pt-br/internals_midi_util.md)
+  * [Send Functions](pt-br/internals_send_functions.md)
+  * [Sysex Tools](pt-br/internals_sysex_tools.md)
diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md
index a2ba34c32..26ce6d244 100644
--- a/docs/quantum_keycodes.md
+++ b/docs/quantum_keycodes.md
@@ -14,15 +14,5 @@ On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are
 |`DEBUG`        |           |Toggle debug mode                                                    |
 |`EEPROM_RESET` |`EEP_RST`  |Resets EEPROM state by reinitializing it                             |
 |`KC_GESC`      |`GRAVE_ESC`|Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI|
-|`KC_LSPO`      |           |Left Shift when held, `(` when tapped                                |
-|`KC_RSPC`      |           |Right Shift when held, `)` when tapped                               |
-|`KC_LCPO`      |           |Left Control when held, `(` when tapped                              |
-|`KC_RCPC`      |           |Right Control when held, `)` when tapped                             |
-|`KC_LAPO`      |           |Left Alt when held, `(` when tapped                                  |
-|`KC_RAPC`      |           |Right Alt when held, `)` when tapped                                 |
-|`KC_SFTENT`    |           |Right Shift when held, Enter when tapped                             |
 |`KC_LEAD`      |           |The [Leader key](feature_leader_key.md)                              |
 |`KC_LOCK`      |           |The [Lock key](feature_key_lock.md)                                  |
-|`FUNC(n)`      |`F(n)`     |Call `fn_action(n)` (deprecated)                                     |
-|`M(n)`         |           |Call macro `n`                                                       |
-|`MACROTAP(n)`  |           |Macro-tap `n` idk FIXME                                              |
diff --git a/docs/ru-ru/_summary.md b/docs/ru-ru/_summary.md
new file mode 100644
index 000000000..3269ac86d
--- /dev/null
+++ b/docs/ru-ru/_summary.md
@@ -0,0 +1,123 @@
+* [Complete Newbs Guide](ru-ru/newbs.md)
+  * [Getting Started](ru-ru/newbs_getting_started.md)
+  * [Building Your First Firmware](ru-ru/newbs_building_firmware.md)
+  * [Flashing Firmware](ru-ru/newbs_flashing.md)
+  * [Testing and Debugging](ru-ru/newbs_testing_debugging.md)
+  * [Git Best Practices](ru-ru/newbs_best_practices.md)
+  * [Learning Resources](ru-ru/newbs_learn_more_resources.md)
+* [QMK Basics](ru-ru/README.md)
+  * [QMK Introduction](ru-ru/getting_started_introduction.md)
+  * [QMK CLI](ru-ru/cli.md)
+  * [QMK CLI Config](ru-ru/cli_configuration.md)
+  * [Contributing to QMK](ru-ru/contributing.md)
+  * [How to Use Github](ru-ru/getting_started_github.md)
+  * [Getting Help](ru-ru/getting_started_getting_help.md)
+* [Breaking Changes](ru-ru/breaking_changes.md)
+  * [2019 Aug 30](ru-ru/ChangeLog/20190830.md)
+* [FAQ](ru-ru/faq.md)
+  * [General FAQ](ru-ru/faq_general.md)
+  * [Build/Compile QMK](ru-ru/faq_build.md)
+  * [Debugging/Troubleshooting QMK](ru-ru/faq_debug.md)
+  * [Keymap](ru-ru/faq_keymap.md)
+  * [Driver Installation with Zadig](ru-ru/driver_installation_zadig.md)
+* Detailed Guides
+  * [Install Build Tools](ru-ru/getting_started_build_tools.md)
+  * [Vagrant Guide](ru-ru/getting_started_vagrant.md)
+  * [Build/Compile Instructions](ru-ru/getting_started_make_guide.md)
+  * [Flashing Firmware](ru-ru/flashing.md)
+  * [Customizing Functionality](ru-ru/custom_quantum_functions.md)
+  * [Keymap Overview](ru-ru/keymap.md)
+* [Hardware](ru-ru/hardware.md)
+  * [Compatible Microcontrollers](ru-ru/compatible_microcontrollers.md)
+  * [AVR Processors](ru-ru/hardware_avr.md)
+  * [Drivers](ru-ru/hardware_drivers.md)
+* Reference
+  * [Keyboard Guidelines](ru-ru/hardware_keyboard_guidelines.md)
+  * [Config Options](ru-ru/config_options.md)
+  * [Keycodes](ru-ru/keycodes.md)
+  * [Coding Conventions - C](ru-ru/coding_conventions_c.md)
+  * [Coding Conventions - Python](ru-ru/coding_conventions_python.md)
+  * [Documentation Best Practices](ru-ru/documentation_best_practices.md)
+  * [Documentation Templates](ru-ru/documentation_templates.md)
+  * [Glossary](ru-ru/reference_glossary.md)
+  * [Unit Testing](ru-ru/unit_testing.md)
+  * [Useful Functions](ru-ru/ref_functions.md)
+  * [Configurator Support](ru-ru/reference_configurator_support.md)
+  * [info.json Format](ru-ru/reference_info_json.md)
+  * [Python CLI Development](ru-ru/cli_development.md)
+* [Features](ru-ru/features.md)
+  * [Basic Keycodes](ru-ru/keycodes_basic.md)
+  * [US ANSI Shifted Keys](ru-ru/keycodes_us_ansi_shifted.md)
+  * [Quantum Keycodes](ru-ru/quantum_keycodes.md)
+  * [Advanced Keycodes](ru-ru/feature_advanced_keycodes.md)
+  * [Audio](ru-ru/feature_audio.md)
+  * [Auto Shift](ru-ru/feature_auto_shift.md)
+  * [Backlight](ru-ru/feature_backlight.md)
+  * [Bluetooth](ru-ru/feature_bluetooth.md)
+  * [Bootmagic](ru-ru/feature_bootmagic.md)
+  * [Combos](ru-ru/feature_combo.md)
+  * [Command](ru-ru/feature_command.md)
+  * [Debounce API](ru-ru/feature_debounce_type.md)
+  * [DIP Switch](ru-ru/feature_dip_switch.md)
+  * [Dynamic Macros](ru-ru/feature_dynamic_macros.md)
+  * [Encoders](ru-ru/feature_encoders.md)
+  * [Grave Escape](ru-ru/feature_grave_esc.md)
+  * [Haptic Feedback](ru-ru/feature_haptic_feedback.md)
+  * [HD44780 LCD Controller](ru-ru/feature_hd44780.md)
+  * [Key Lock](ru-ru/feature_key_lock.md)
+  * [Layouts](ru-ru/feature_layouts.md)
+  * [Leader Key](ru-ru/feature_leader_key.md)
+  * [LED Matrix](ru-ru/feature_led_matrix.md)
+  * [Macros](ru-ru/feature_macros.md)
+  * [Mouse Keys](ru-ru/feature_mouse_keys.md)
+  * [OLED Driver](ru-ru/feature_oled_driver.md)
+  * [One Shot Keys](ru-ru/feature_advanced_keycodes.md#one-shot-keys)
+  * [Pointing Device](ru-ru/feature_pointing_device.md)
+  * [PS/2 Mouse](ru-ru/feature_ps2_mouse.md)
+  * [RGB Lighting](ru-ru/feature_rgblight.md)
+  * [RGB Matrix](ru-ru/feature_rgb_matrix.md)
+  * [Space Cadet](ru-ru/feature_space_cadet.md)
+  * [Split Keyboard](ru-ru/feature_split_keyboard.md)
+  * [Stenography](ru-ru/feature_stenography.md)
+  * [Swap Hands](ru-ru/feature_swap_hands.md)
+  * [Tap Dance](ru-ru/feature_tap_dance.md)
+  * [Terminal](ru-ru/feature_terminal.md)
+  * [Thermal Printer](ru-ru/feature_thermal_printer.md)
+  * [Unicode](ru-ru/feature_unicode.md)
+  * [Userspace](ru-ru/feature_userspace.md)
+  * [Velocikey](ru-ru/feature_velocikey.md)
+* For Makers and Modders
+  * [Hand Wiring Guide](ru-ru/hand_wire.md)
+  * [ISP Flashing Guide](ru-ru/isp_flashing_guide.md)
+  * [ARM Debugging Guide](ru-ru/arm_debugging.md)
+  * [I2C Driver](ru-ru/i2c_driver.md)
+  * [WS2812 Driver](ru-ru/ws2812_driver.md)
+  * [GPIO Controls](ru-ru/internals_gpio_control.md)
+  * [Proton C Conversion](ru-ru/proton_c_conversion.md)
+* For a Deeper Understanding
+  * [How Keyboards Work](ru-ru/how_keyboards_work.md)
+  * [Understanding QMK](ru-ru/understanding_qmk.md)
+* Other Topics
+  * [Using Eclipse with QMK](ru-ru/other_eclipse.md)
+  * [Using VSCode with QMK](ru-ru/other_vscode.md)
+  * [Support](ru-ru/support.md)
+  * [Translating the QMK Docs](ru-ru/translating.md)
+* QMK Internals (In Progress)
+  * [Defines](ru-ru/internals_defines.md)
+  * [Input Callback Reg](ru-ru/internals_input_callback_reg.md)
+  * [Midi Device](ru-ru/internals_midi_device.md)
+  * [Midi Device Setup Process](ru-ru/internals_midi_device_setup_process.md)
+  * [Midi Util](ru-ru/internals_midi_util.md)
+  * [Send Functions](ru-ru/internals_send_functions.md)
+  * [Sysex Tools](ru-ru/internals_sysex_tools.md)
diff --git a/docs/ru-ru/becoming_a_qmk_collaborator.md b/docs/ru-ru/becoming_a_qmk_collaborator.md
new file mode 100644
index 000000000..653f01ac8
--- /dev/null
+++ b/docs/ru-ru/becoming_a_qmk_collaborator.md
@@ -0,0 +1,9 @@
+# Стать соавтором QMK
+Соавтор QMK - это производитель или разработчик клавиатуры, который заинтересован в том, чтобы помочь QMK вырасти. Для этого он полностью поддерживает свои клавиатуры, поощряет пользователей и клиентов создавать новый функционал, идеи и раскладки клавиатур. Мы всегда стремимся добавлять больше клавиатур и соавторов, но нам важно, чтобы они соответствовали следующим требованиям:
+* **Иметь печатную плату на продажу.** К сожалению, у собранных вручную клавиатур слишком много вариаций и сложностей.
+* **Поддерживать вашу клавиатуру в QMK.** Это может потребовать просто начальной настройки, чтобы ваша клавиатура заработала. Но поддержка также может заключаться в адаптации изменений ядра QMK, которые способны сломать или сделать избыточным любой пользовательский код.
+* **Одобрять и производить слияние пулреквестов для вашей клавиатуры.** Мы призываем пользователей делиться своими раскладками клавиатур, чтобы другие могли их видеть и опираться на них при создании своих собственных.
+Если вы чувствуете, что удовлетворяете этим требованиям, напишите нам письмо по адресу hello@qmk.fm с кратким описанием и ссылками на вашу клавиатуру!
diff --git a/docs/ru-ru/getting_started_github.md b/docs/ru-ru/getting_started_github.md
index 8a0fd07a2..3b4940dd1 100644
--- a/docs/ru-ru/getting_started_github.md
+++ b/docs/ru-ru/getting_started_github.md
@@ -15,17 +15,23 @@ GitHub может показаться несколько сложным для
 ![HTTPS link](http://i.imgur.com/eGO0ohO.jpg)
-Теперь введите `git clone` в командную строку, а затем вставьте ссылку:
+Теперь введите `git clone --recurse-submodules ` в командную строку, а затем вставьте ссылку:
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
+remote: Enumerating objects: 9, done.
-remote: Compressing objects: 100% (2/2), done.
+remote: Counting objects: 100% (9/9), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
+remote: Compressing objects: 100% (5/5), done.
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
-Resolving deltas: 100% (29362/29362), done.
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
-Checking out files: 100% (2799/2799), done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 Теперь у вас есть форк QMK на вашем локальном компьютере, и вы можете добавить свою раскладку, скомпилировать ее и прошить ей свою клавиатуру. Как только вы будете довольны своими изменениями, есть возможность добавить, зафиксировать их и сделать коммит в свой форк следующим образом:
diff --git a/docs/ru-ru/getting_started_introduction.md b/docs/ru-ru/getting_started_introduction.md
new file mode 100644
index 000000000..ccc441806
--- /dev/null
+++ b/docs/ru-ru/getting_started_introduction.md
@@ -0,0 +1,58 @@
+# Введение
+Эта страница пытается объяснить основную информацию, которую вы должны знать, чтобы работать с проектом QMK. Предполагается, что вы знакомы с навигацией в оболочке Unix, но не предполагается, что вы знакомы с C или с компиляцией с использованием make.
+## Базовая структура QMK
+QMK - это форк [Джуна Вако (Jun Wako)](https://github.com/tmk) проекта [tmk_keyboard](https://github.com/tmk/tmk_keyboard). Оригинальный код TMK с изменениями можно найти в папке `tmk_core`. Дополнения QMK к проекту можно найти в папке `quantum`. Проекты клавиатур можно найти в папках `handwired` и `keyboard`.
+### Структура пространства пользователя
+Внутри папки `users` находится каталог для каждого пользователя. Это место для пользователей, куда они могут поместить код, чтобы использовать его с разными клавиатурами. Для получения дополнительной информации обратитесь к документации по [функциям пользовательского пространства](ru-ru/feature_userspace.md).
+### Структура проекта клавиатуры
+Внутри папки `keyboards` есть подпапки `handwired` и есть подкаталоги поставщиков и производителей, для примера, `clueboard` - это каталог для каждого проекта клавиатуры, например, `qmk_firmware/keyboards/clueboard/2x1800`. В нем вы найдете следующую структуру:
+* `keymaps/`: Различные раскладки клавиш, которые можно собрать.
+* `rules.mk`: Файл, который устанавливает параметры по умолчанию для команды "make". Не редактируйте этот файл напрямую, вместо этого используйте `rules.mk`, относящийся к конкретной раскладке.
+* `config.h`: Файл, который устанавливает параметры времени компиляции по умолчанию. Не редактируйте этот файл напрямую, вместо этого используйте `config.h`, относящийся к конкретной раскладке.
+* `info.json`: Файл настройки раскладки для QMK Configurator. Посмотрите [Поддержку конфигуратора](ru-ru/reference_configurator_support.md) для дополнительной информации.
+* `readme.md`: Краткий обзор клавиатуры.
+* `<keyboardName>.h`: В этом файле определяется раскладка клавиатуры по матрице переключателей клавиатуры.
+* `<keyboardName>.c`: В этом файле вы можете найти пользовательский код для клавиатуры.
+Для получения дополнительной информации о структуре проекта обратитесь к [Руководству QMK по клавиатуре](ru-ru/hardware_keyboard_guidelines.md).
+### Структура раскладки клавиатуры
+В каждой папке раскладки клавиатуры могут быть найдены следующие файлы. Обязательным является только файл `keymap.c`, и если остальные файлы не найдены, то будут выбраны параметры по умолчанию.
+* `config.h`: настройки вашей раскладки клавиатуры.
+* `keymap.c`: весь код вашей раскладки клавиатуры (обязателен).
+* `rules.mk`: активированные функции QMK.
+* `readme.md`: описание вашей раскладки клавиш, как ее могут использовать другие, и объяснения функций. Пожалуйста, загрузите изображения на сервис, такой как imgur.
+# Файл `config.h`
+Существует 3 возможных местоположения `config.h`:
+* клавиатура (`/keyboards/<keyboard>/config.h`)
+* пространство пользователя (`/users/<user>/config.h`)
+* раскладка клавиш (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
+Система сборки автоматически загружает файлы конфигурации в указанном выше порядке. Если вы хотите переопределить любую настройку, заданную предыдущим `config.h`, вам сначала нужно будет включить некоторый шаблонный код для настроек, которые вы хотите изменить.
+```
+#pragma once
+```
+Затем, чтобы переопределить настройку из предыдущего файла `config.h`, вы должны сделать `#undef` и `#define` для неё снова.
+Код и настройка шаблона вместе выглядят так:
+```
+#pragma once
+// Переопределения производятся здесь!
+#undef MY_SETTING
+#define MY_SETTING 4
+```
diff --git a/docs/translating.md b/docs/translating.md
index 6eb268763..436581759 100644
--- a/docs/translating.md
+++ b/docs/translating.md
@@ -1,29 +1,55 @@
-# How to translate the QMK docs into different languages
+# Translating the QMK Docs
 All files in the root folder (`docs/`) should be in English - all other languages should be in subfolders with the ISO 639-1 language codes, followed by `-` and the country code where relevant. [A list of common ones can be found here](https://www.andiamo.co.uk/resources/iso-language-codes/). If this folder doesn't exist, you may create it. Each of the translated files should have the same name as the English version, so things can fall back successfully.
 A `_summary.md` file should exist in this folder with a list of links to each file, with a translated name, and link preceded by the language folder:
-    * [QMK简介](zh-cn/getting_started_introduction.md)
+```markdown
+ * [QMK简介](zh-cn/getting_started_introduction.md)
+```
+All links to other docs pages must also be prefixed with the language folder. If the link is to a specific part of the page (ie. a certain heading), you must use the English ID for the heading, like so:
+```markdown
+[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment)
+## 建立你的环境 :id=set-up-your-environment
+```
 Once you've finished translating a new language, you'll also need to modify the following files:
 * [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md)  
-  Each line should contain a country flag in the format `:us:` followed by the name represented in its own language:  
+  Each line should contain a country flag as a [GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) followed by the name represented in its own language:
-  
-      - [:cn: 中文](/zh-cn/)
+  ```markdown
+   - [:cn: 中文](/zh-cn/)
+  ```
 * [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html)  
-  Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string:  
+  Both `placeholder` and `noData` objects should have a dictionary entry for the language folder in a string:
-  
-      '/zh-cn/': '没有结果!',
+  ```js
+  '/zh-cn/': '没有结果!',
+  ```
+  The `nameLink` object, for setting the "QMK Firmware" heading link in the sidebar, must also be added to:
+  ```js
+  '/zh-cn/': '/#/zh-cn/',
+  ```
-## Previewing the translations
+  And make sure to add the language folder in the `fallbackLanguages` list, so it will properly fall back to English instead of 404ing:
-Before opening a pull request, you can preview your additions if you have Python 3 installed by running this command in the `docs/` folder:
+  ```js
+  fallbackLanguages: [
+    // ...
+    'zh-cn',
+    // ...
+  ],
+  ```
-    python -m http.server 9000
+## Previewing the Translations
-and navigating to http://localhost:9000/ - you should be able to select your new language from the "Translations" menu at the top-right.
+See [Previewing the Documentation](contributing.md#previewing-the-documentation) for how to set up a local instance of the docs - you should be able to select your new language from the "Translations" menu at the top-right.
 Once you're happy with your work, feel free to open a pull request!
diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md
index 67481c458..80b694858 100644
--- a/docs/ws2812_driver.md
+++ b/docs/ws2812_driver.md
@@ -14,7 +14,7 @@ These LEDs are called "addressable" because instead of using a wire per color, e
 |----------|--------------------|--------------------|
 | bit bang | :heavy_check_mark: | :heavy_check_mark: |
 | I2C      | :heavy_check_mark: |                    |
-| SPI      |                    | Soon™              |
+| SPI      |                    | :heavy_check_mark: |
 | PWM      |                    | Soon™              |
 ## Driver configuration
@@ -40,3 +40,30 @@ Configure the hardware via your config.h:
 #define WS2812_ADDRESS 0xb0 // default: 0xb0
 #define WS2812_TIMEOUT 100 // default: 100
 ```
+### SPI
+Targeting STM32 boards where WS2812 support is offloaded to an SPI hardware device. The advantage is that the use of DMA offloads processing of the WS2812 protocol from the MCU. `RGB_DI_PIN` for this driver is the configured SPI MOSI pin. Due to the nature of repurposing SPI to drive the LEDs, the other SPI pins, MISO and SCK, **must** remain unused. To configure it, add this to your rules.mk:
+```make
+WS2812_DRIVER = spi
+```
+Configure the hardware via your config.h:
+```c
+#define WS2812_SPI SPID1 // default: SPID1
+#define WS2812_SPI_MOSI_PAL_MODE 5 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 5
+```
+You must also turn on the SPI feature in your halconf.h and mcuconf.h
+#### Testing Notes
+While not an exhaustive list, the following table provides the scenarios that have been partially validated:
+| | SPI1 | SPI2 | SPI3 |
+|-|-|-|-|
+| f072 | ? | B15 :heavy_check_mark: | N/A |
+| f103 | A7 :heavy_check_mark: | B15 :heavy_check_mark: | N/A |
+| f303 | A7 :heavy_check_mark: B5 :heavy_check_mark:  | B15 :heavy_check_mark: | B5 :heavy_check_mark: |
+*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*
+\ No newline at end of file
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
index 9eb4ea777..bb7e0130f 100644
--- a/docs/zh-cn/README.md
+++ b/docs/zh-cn/README.md
@@ -19,7 +19,7 @@ QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包�
 ## 如何编译
-在你能编译之前, 你需要[部署环境](getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令:
+在你能编译之前, 你需要[部署环境](zh-cn/getting_started_build_tools.md) 用于 AVR or/and ARM 开发。完成后, 你可以使用 `make` 命令来编译一个键盘和布局使用以下命令:
    make planck/rev4:default
@@ -29,4 +29,4 @@ QMK (*Quantum Mechanical Keyboard*) 是一个社区维护的开源软件，包�
 ## 如何定制
-QMK 有许多 [特性](features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](keymap.md)和[键码](keycodes.md)来利用许多特性。
+QMK 有许多 [特性](zh-cn/features.md)来探索，也有很多 [参考文档](http://docs.qmk.fm) 供您发掘。你可以通过修改 [布局](zh-cn/keymap.md)和[键码](zh-cn/keycodes.md)来利用许多特性。
diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md
index 42ceba9ca..f2c6098dc 100644
--- a/docs/zh-cn/custom_quantum_functions.md
+++ b/docs/zh-cn/custom_quantum_functions.md
@@ -1,31 +1,31 @@
-# ��ζ�������̵Ĺ���
+# ���何定制你键盘的功能
-���ںܶ�����˵���ƻ����̿ɲ�ֻ������ĵ��Է����㰴���Ǹ�����ô�򵥡���϶���ʵ�ֱȼ򵥰����ͺ�����ӵĹ��ܡ�QMK��������ע�����Ĺ���, ���ǹ���, ���⣬�������Զ�������ڲ�ͬ����µ���Ϊ��
+对于很多人来说客制化键盘可不只是向你的电脑发送你按了那个件这么简单。你肯定想实现比简单按键和宏更复杂的功能。QMK有能让你注入代码的钩子, 覆盖功能, 另外，还可以自定义键盘在不同情况下的行为。
-��ҳ���ٶ��κ������QMK֪ʶ�����Ķ�[����QMK](understanding_qmk.md)�����ڸ������Ĳ���������ⷢ����ʲô��
+本页不假定任何特殊的QMK知识，但阅读[理解QMK](understanding_qmk.md)将会在更基础的层面帮你理解发生了什么。
-## A Word on Core vs ���� vs ����
+## A Word on Core vs 键盘 vs 布局
-���ǰ�qmk��֯��������νṹ��
+我们把qmk���织成���个层次结构：
 * Core (`_quantum`)
  * Keyboard/Revision (`_kb`)
    * Keymap (`_user`)
-����������ÿһ�������������ڶ����ϼ�һ��`_kb()`�� `_user()` ��׺�� �����ڼ���/�޶���ʹ��`_kb()`��׺���ڲ��ֲ�ʹ��`_user()`��׺��
+下面描述的每一个函数都可以在定义上加一个`_kb()`或 `_user()` 后缀。 建议在键盘/修订层使用`_kb()`后缀，在布局层使用`_user()`后缀。
-�ڼ���/�޶��㶨�庯��ʱ��`_kb()`��ִ���κδ���ǰ�ȵ���`_user()`�Ǳ�Ҫ�ģ���Ȼ���ֲ㺯���Ͳ�Ҫ�����á�
+在键盘/修订层定义函数时，`_kb()`在执行任何代码前先调用`_user()`是必要的，不然布局层函数就不要被调用。
-<!-- �������⣺�����Ǿ�����Ĳ�̫��-->
+<!-- 翻译问题：���面那句��译的不太好-->
-# �Զ�������
+# 自���义键码
-��ĿǰΪֹ������������Ǹ������м������Ϊ�򴴽��µļ��롣�Ӵ���Ƕ�������Щ�����������ơ�
+到目前为止，最常见的任务是更改现有键码的行为或创建新的键码。从代码角度来看这些操作都很相似。
-## ����һ���¼���
+## ���义���个新键码
-���������һ������ö�ٳ���ȫ����Ҳ���Ǹ�����������ֲ�����Ψһ��ֵ��QMKû��ֱ������������ֵ��С�������ṩ��һ��`SAFE_RANGE`�ꡣ�������ö��ʱ��`SAFE_RANGE`����֤��ȡ����Ψһ�ļ���ֵ��
+创建键码第一步，先枚举出它全部，也就是给键码起个名字并分配唯一数值。QMK没有直接限制最大键码值大小，而是提供了一个`SAFE_RANGE`宏。你可以在枚举时用`SAFE_RANGE`来保证你取得了唯一的键码值。
-����ö��������������ӡ�������ӵ�`keymap.c`�Ļ�����ڲ���������`FOO`��`BAR`�ˡ�
+这有枚�����个���码的例子。把这块加到`keymap.c`的话你���在布局中能用`FOO`和`BAR`了。
 ```c
 enum my_keycodes {
@@ -34,46 +34,46 @@ enum my_keycodes {
 };
 ```
-## Ϊ�������Ϊ���
+## 为键码的行为���程
-���㸲��һ���Ѵ��ڰ�������Ϊʱ���������Ϊ�����¼�ʱ����Ҫ��`process_record_kb()`��`process_record_user()`���������������ڼ���������ʵ���¼�������ǰ��QMK���á����������������`true`��QMK�����������ķ�ʽ�������롣�������Ժܷ������չ����Ĺ��ܶ������滻���������������`false` QMK������������������Ȼ���ͼ���̧���ǰ����¼�����������ˡ�
+当你覆盖一个已存在按键的行为时，或将这个行为赋给新键时，你要用`process_record_kb()`和`process_record_user()`函数。这俩函数在键处理中真实键事件被处理前被QMK调用。如果这俩函数返回`true`，QMK将会用正常的方式处理键码。这样可以很方便的扩展键码的功能而不是替换它。如果函数返回`false` QMK会跳过正常键处理，然后发送键子抬起还是按下事件就由你决定了。
-��ĳ�������»��ͷ�ʱ���������ᱻ���á�
+当某���键按下或释放时这俩函数���被���用。
-### process_record_user()`��������ʵ��
+### process_record_user()`函数�����实现
-�����������������¡��Զ�����һ������`FOO`���������Ϊ�����������ڰ��»���ʱ����������
+这���例子做了���个事。自���义了���个叫做`FOO`的键码的行为������补充���在按下回车时播放��符。
 ```c
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  switch (keycode) {
    case FOO:
      if (record->event.pressed) {
-        // ����ʱ��Щʲô
+        // 按下时做些什么
      } else {
-        // �ͷ�ʱ��Щʲô
+        // 释放时做些什么
      }
-      return false; // �����˼������н�һ������
+      return false; // 跳过此键的所有进一步处理
    case KC_ENTER:
-      // �����»���ʱ��������
+      // 当按下回车时播放��符
      if (record->event.pressed) {
        PLAY_NOTE_ARRAY(tone_qwerty);
      }
-      return true; // ��QMK�����س�����/�ͷ��¼�
+      return true; // 让QMK触发回车按下/释放事件
    default:
-      return true; // ����������������
+      return true; // ��常处理其���键码
  }
 }
 ```
-### `process_record_*` �����ĵ�
+### `process_record_*` 函数文档
-* ����/�޶�: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* 键盘/修订: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
-* ����: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
+* 布局: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
-`keycode(����)`�������ڲ����϶���ģ�����`MO(1)`, `KC_L`, �ȵȡ� ��Ҫ�� `switch...case` ����������Щ�¼���
+`keycode(键码)`参数是在布局上定义的，比如`MO(1)`, `KC_L`, 等等。 你要用 `switch...case` 块来处理这些事件。
-`record`��������ʵ����������Ϣ��
+`record`参��含有实际按键的信息���
 ```c
 keyrecord_t record {
@@ -88,9 +88,9 @@ keyrecord_t record {
 }
 ```
-# LED����
+# LED控制
-qmk�ṩ�˶�ȡHID�淶������5��LED�ķ�����:
+qmk提供了读取HID规范包含的5���LED的方法。:
 * `USB_LED_NUM_LOCK`
 * `USB_LED_CAPS_LOCK`
@@ -98,20 +98,20 @@ qmk�ṩ�˶�ȡHID�淶������5��LED�ķ�����:
 * `USB_LED_COMPOSE`
 * `USB_LED_KANA`
-�����������Ӧ������LED״̬��λ��λ��
+这五个��量对应于��机LED状态的位置位。
-�����ַ��������������LED״̬��
+有两种方法可���获得��机LED状态：
-* ͨ��ִ�� `led_set_user()`
+* 通过执行 `led_set_user()`
-* �������� `host_keyboard_leds()`
+* 通过调�� `host_keyboard_leds()`
 ## `led_set_user()`
-��5��LED���κ�һ����״̬��Ҫ�ı�ʱ���˺����������á��˺���������������LED������
+当5���LED���任何������的状态需要改变时，此��数将��调��。此函数通过参数输入LED参数。
-ʹ��`IS_LED_ON(usb_led, led_name)`��`IS_LED_OFF(usb_led, led_name)`�������������LED״̬��
+使用`IS_LED_ON(usb_led, led_name)`和`IS_LED_OFF(usb_led, led_name)`这���个宏来检查LED状态。
-!> `host_keyboard_leds()`���ܻ���`led_set_user()`��������������ֵ��
+!> `host_keyboard_leds()`可能会在`led_set_user()`被���用前返回新值。
-### `led_set_user()`��������ʵ��
+### `led_set_user()`函数�����实现
 ```c
 void led_set_user(uint8_t usb_led) {
@@ -143,59 +143,59 @@ void led_set_user(uint8_t usb_led) {
 }
 ```
-### `led_set_*`�����ĵ�
+### `led_set_*`函数文档
-* ����/�޶�: `void led_set_kb(uint8_t usb_led)`
+* 键盘/修订: `void led_set_kb(uint8_t usb_led)`
-* ����: `void led_set_user(uint8_t usb_led)`
+* 布局: `void led_set_user(uint8_t usb_led)`
 ## `host_keyboard_leds()`
-������������᷵������յ���LED״̬�����������`led_set_*`֮���ȡLED״̬ʱ�����ã�������[`matrix_scan_user()`](#����ɨ�����).
+调用这个函数会返回最后收到的LED状态。这个函数在`led_set_*`之外读取LED状态时很有用，比如在[`matrix_scan_user()`](#矩阵扫描代码).
-Ϊ�˱�ݣ��������`IS_HOST_LED_ON(led_name)`��`IS_HOST_LED_OFF(led_name)` �꣬����ֱ�ӵ��úͼ��`host_keyboard_leds()`��
+为了便捷，你可以用`IS_HOST_LED_ON(led_name)`和`IS_HOST_LED_OFF(led_name)` 宏，而不直接调用和检查`host_keyboard_leds()`。
-## ��������LED״̬
+## ���置物理LED状态
-һЩ����ʵ����Ϊ��������LED��״̬�����˷����ķ�����
+一些键盘实现了为���置物理LED的状态提供了��便的方法���
 ### Ergodox Boards
-Ergodoxʵ�����ṩ`ergodox_right_led_1`/`2`/`3_on`/`off()`����ÿ��LED�����, Ҳ������ `ergodox_right_led_on`/`off(uint8_t led)` �������򿪻�ر����ǡ�
+Ergodox实现了提供`ergodox_right_led_1`/`2`/`3_on`/`off()`来让每个LED开或关, 也可以用 `ergodox_right_led_on`/`off(uint8_t led)` 按索引打开或关闭他们。
-���⣬������ʹ��`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)`��
+此外，还可以使用`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)`。
-Ergodox boards ͬʱ������������ȼ���`LED_BRIGHTNESS_LO`��������ȼ���`LED_BRIGHTNESS_HI`(Ĭ�����).
+Ergodox boards �����定义了最低亮度级别`LED_BRIGHTNESS_LO`和最高���度级别`LED_BRIGHTNESS_HI`(默认最高).
-# ���̳�ʼ������
+# 键盘初始化���码
-���̳�ʼ�������м����������������������ȡ��������Ҫ��ʲô��
+键盘初始化过程有几���步骤。���是用�����函数取决���你想要做什么���
-������������ʼ��������������˳���г���
+有�������要初始化函��，按调用���序列出。
-* `keyboard_pre_init_*` - ���ڴ��������������������������������Щ������ǰ���е�Ӳ����ʼ����
+* `keyboard_pre_init_*` - ���在大多��其他东西运���前���行。适用于��些需要提前运���的硬件初始化。
-* `matrix_init_*` - �ڹ̼����������м������á���ʱӲ���ѳ�ʼ����������δ��ʼ����
+* `matrix_init_*` - 在固����动过程�����被调用。此时�����已初始化，功能尚未初始化。
-* `keyboard_post_init_*` - �ڹ̼�����������󱻵��á����������£���ġ����ƻ������붼���Է������
+* `keyboard_post_init_*` - 在固件启动过程最后被调用。大多数情况下，你的“客制化”代码都可以放在这里。
-!> �������������˵`keyboard_post_init_user`������Ҫ���õĺ���������, ��ʱ���������RGB�Ʒ��⡣
+!> 对于大多数人来��`keyboard_post_init_user`��你想要调���的函数。例如, 此时你可以���置RGB灯发光。
-## ����Ԥ��ʼ������
+## 键盘预初始化���码
-����뼫����������������USB��ʼ��ǰ������
+这��码极早运行���甚至都在USB初始化前运���。
-����֮�󲻾þ��������ʼ���ˡ�
+在这之后不久矩阵��被初始化了。
-���ڴ�����û���˵,���ò�������Ϊ����Ҫ����������Ӳ���ĳ�ʼ����
+对于��多数用户来��,这用不到���因为它��要��用于面向���件的初始化。
-����������Ӳ����ʼ���Ļ������������ò�����(�����ʼ��LED���������).
+但如果你有������初始化的���放在这里再好不过���(���如初始化LED引脚一��的).
-### `keyboard_pre_init_user()`��������ʵ��
+### `keyboard_pre_init_user()`函数�����实现
-�����������̼������� B0, B1, B2, B3, �� B4 ��LED���š�
+本���中在键盘级别������定 B0, B1, B2, B3, 和 B4 是LED引脚。
 ```c
 void keyboard_pre_init_user(void) {
-  // ���ü���Ԥ��ʼ������
+  // 调用键盘预初始化���码
-  // ����LED����Ϊ����ģʽ
+  // ���置LED引脚���输出模式
  setPinOutput(B0);
  setPinOutput(B1);
  setPinOutput(B2);
@@ -204,73 +204,73 @@ void keyboard_pre_init_user(void) {
 }
 ```
-### `keyboard_pre_init_*` �����ĵ�
+### `keyboard_pre_init_*` 函数文档
-* ����/�޶�: `void keyboard_pre_init_kb(void)`
+* 键盘/修订: `void keyboard_pre_init_kb(void)`
-* ����: `void keyboard_pre_init_user(void)`
+* 布局: `void keyboard_pre_init_user(void)`
-## �����ʼ������
+## 矩阵初始化���码
-�⽫���ھ��������ʱ�����ã���ĳ��Ӳ�������ú��������Щ���ܱ�������ǰ�� 
+这将���在��阵初始化时���调用，在某��������设置好后���但在一些功能被初始化前。 
-���������������ط����õ���������ʱ��������ã�����Ӳ�����أ�Ҳ����������������λ�á�
+���在��设��������地��会用到的东西的时候会很有用，但与�����无关，也不依赖于它的��动位置。
-### `matrix_init_*`�����ĵ�
+### `matrix_init_*`函数文档
-* ����/�޶�: `void matrix_init_kb(void)`
+* 键盘/修订: `void matrix_init_kb(void)`
-* ����: `void matrix_init_user(void)`
+* 布局: `void matrix_init_user(void)`
-## ���̺��ʼ������
+## 键盘后初始化���码
-���Ǽ��̳�ʼ�������е����һ����������������ĳЩ���ԣ��������ã���Ϊ��ʱӦ�ö����ǽ��г�ʼ����
+这是键盘初始化过程中的最后一个任务。如果您想更改某些特性，这会很有用，因为此时应该对它们进行初始化。
-### `keyboard_post_init_user()`����ʵ��
+### `keyboard_post_init_user()`示���实现
-��ʾ�������г�ʼ����ɺ����У�����RGB�ơ�
+��示���在所有初始化完成后运行，配置RGB灯。
 ```c
 void keyboard_post_init_user(void) {
-  // ���ú��ʼ������
+  // 调用后初始化���码
-  rgblight_enable_noeeprom(); // ʹ��Rgb������������
+  rgblight_enable_noeeprom(); // 使能Rgb，不保存���置
-  rgblight_sethsv_noeeprom(180, 255, 255); // ����ɫ���õ�����ɫ(��ɫ)������
+  rgblight_sethsv_noeeprom(180, 255, 255); // 将颜���设���到蓝绿色(青��)不保存
-  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // ���ÿ��ٺ���ģ��������
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // ������快速呼吸���式不保存
 }
 ```
-### `keyboard_post_init_*` �����ĵ�
+### `keyboard_post_init_*` 函数文档
-* ����/�޶�: `void keyboard_post_init_kb(void)`
+* 键盘/修订: `void keyboard_post_init_kb(void)`
-* ����: `void keyboard_post_init_user(void)`
+* 布局: `void keyboard_post_init_user(void)`
-# ����ɨ�����
+# 矩阵扫描代码
-���ܵĻ���Ҫ��`process_record_*()`�Զ�����̣������ַ�ʽ���ӵ��¼��У���ȷ�����벻��Լ��̲������������Ӱ�졣Ȼ�����ڼ���������£��б�Ҫ���о���ɨ�衣����Щ������Ҫ�ر�ע���������ܣ���Ϊ��ÿ�����ٱ�����10�Ρ�
+可能的话你要用`process_record_*()`自定义键盘，以这种方式连接到事件中，以确保代码不会对键盘产生负面的性能影响。然而，在极少数情况下，有必要进行矩阵扫描。在这些函数中要特别注意代码的性能，因为它每秒至少被调用10次。
-### `matrix_scan_*`����ʵ��
+### `matrix_scan_*`示���实现
-������ӱ�����ʡ���ˡ���hook����һ�������ܼ������е�����֮ǰ����Ӧ���㹻�˽�qmk���ڲ��ṹ���Ա���û��ʾ��������±�д���������Ҫ��������[����һ��issue](https://github.com/qmk/qmk_firmware/issues/new)��[��Discord�������ǽ���](https://discord.gg/Uq7gcHh).
+这个例子被故意省略了。在hook这样一个对性能及其敏感的区域之前，您应该足够了解qmk的内部结构，以便在没有示例的情况下编写。如果你需要帮助，请[建立一个issue](https://github.com/qmk/qmk_firmware/issues/new)或[在Discord上与我们交流](https://discord.gg/Uq7gcHh).
-### `matrix_scan_*` �����ĵ�
+### `matrix_scan_*` 函数文档
-* ����/�޶�: `void matrix_scan_kb(void)`
+* 键盘/修订: `void matrix_scan_kb(void)`
-* ����: `void matrix_scan_user(void)`
+* 布局: `void matrix_scan_user(void)`
-�ú�����ÿ�ξ���ɨ��ʱ�����ã��������MCU��������������ͬ��������д����Ҫ��������Ϊ�������кܶ�Ρ�
+该函数在每次矩阵扫描时被调用，这基本与MCU处理能力上限相同。在这里写代码要谨慎，因为它会运行很多次。
-������Զ������ɨ�����ʱ�õ������������Ҳ���������Զ���״̬���(����LED�ƻ�����Ļ)�������������û���������Ҳ�붨�����еĹ��ܡ�
+你会在自定义矩阵扫描代码时用到这个函数。这也可以用作自定义状态输出(比如LED灯或者屏幕)或者其他即便用户不输入你也想定期运行的功能。
-# ���� ����/���� ����
+# 键盘 空闲/唤醒 代码
-�������֧�־Ϳ���ͨ��ֹͣһ��Ʊ�������ﵽ"����"��RGB�ƺͱ�����Ǻܺõ����ӡ�����Խ�Լ�ܺģ�Ҳ����������̷�ζ���ѡ�
+如果键盘支持就可以通过停止一大票功能来达到"空闲"。RGB灯和背光就是很好的例子。这可以节约能耗，也可能让你键盘风味更佳。
-��������������: `suspend_power_down_*`��`suspend_wakeup_init_*`, �ֱ���ϵͳ������ͻ���ʱ���á�
+用���个函数控制: `suspend_power_down_*`和`suspend_wakeup_init_*`, ���别在系统����闲和唤醒时调用。
-### suspend_power_down_user()��suspend_wakeup_init_user()����ʵ��
+### suspend_power_down_user()和suspend_wakeup_init_user()示���实现
 ```c
@@ -283,18 +283,18 @@ void suspend_wakeup_init_user(void) {
 }
 ```
-### ���� ����/���� �����ĵ�
+### 键盘 挂起/唤醒 函数文档
-* ����/�޶�: `void suspend_power_down_kb(void)` ��`void suspend_wakeup_init_user(void)`
+* 键盘/修订: `void suspend_power_down_kb(void)` 和`void suspend_wakeup_init_user(void)`
-* ����: `void suspend_power_down_kb(void)` �� `void suspend_wakeup_init_user(void)`
+* 布局: `void suspend_power_down_kb(void)` 和 `void suspend_wakeup_init_user(void)`
-# ���������
+# ���改变���码
-ÿ����ı����������д���������ڲ�ָ�����Զ�������������á�
+每当���改变这��就运�����码���这对于层指示或自定义层处理���有�����
-### `layer_state_set_*` ����ʵ��
+### `layer_state_set_*` 示���实现
-����ʹ����Planck����ʾ����������� [RGB�����](feature_rgblight.md)��֮����Ӧ
+本���使用了Planck键��������了如何设置 [RGB背光灯](feature_rgblight.md)使���与层对应
 ```c
 uint32_t layer_state_set_user(uint32_t state) {
@@ -318,31 +318,31 @@ uint32_t layer_state_set_user(uint32_t state) {
  return state;
 }
 ```
-### `layer_state_set_*` �����ĵ�
+### `layer_state_set_*` 函数文档
-* ����/�޶�: `uint32_t layer_state_set_kb(uint32_t state)`
+* 键盘/修订: `uint32_t layer_state_set_kb(uint32_t state)`
-* ����: `uint32_t layer_state_set_user(uint32_t state)`
+* 布局: `uint32_t layer_state_set_user(uint32_t state)`
-��`״̬`�ǻ������bitmask, ���[��������](keymap.md#���ֵĲ�״̬)
+该`��态`��活动层的bitmask, 详见[���局概述](keymap.md#布局的层状态)
-# ���籣������ (EEPROM)
+# ���电���存配置 (EEPROM)
-�����������ó��ڵı����ڼ����С���Щ���ñ����������ص�EEPROM����粻����ʧ�� ���ÿ�����`eeconfig_read_kb`��`eeconfig_read_user`��ȡ��������`eeconfig_update_kb`��`eeconfig_update_user`д�롣�������ϣ���ܹ��л��Ĺ��ܺ�����(�����л�RGB��ָʾ�����⣬�������`eeconfig_init_kb`��`eeconfig_init_user`������EEPROMĬ��ֵ�� 
+这会让你的配置长期的保存在键盘中。这些配置保存在你主控的EEPROM里，掉电不会消失。 设置可以用`eeconfig_read_kb`和`eeconfig_read_user`读取，可以用`eeconfig_update_kb`和`eeconfig_update_user`写入。这对于您希望能够切换的功能很有用(比如切换RGB层指示。此外，你可以用`eeconfig_init_kb`和`eeconfig_init_user`来设置EEPROM默认值。 
-��ӵĲ��ֿ����ǣ��кܶ෽������ͨ��EEPROM�洢�ͷ������ݣ����Ҳ�û�������ַ����ǡ�������ȷ���ġ���ÿ������ֻ��һ��˫��(���ֽ�)�ռ䡣
+最复杂的部分可能是，有很多方法可以通过EEPROM存储和访问数据，并且并没有用哪种方法是“政治正确”的。你每个功能只有一个双字(四字节)空间。
-��סEEPROM����д�������ġ�����д�������ܸߣ����ǲ�����ֻ������д��EEPROM�С������д��Ƶ�������MCU���������̡�
+记住EEPROM是有写入寿命的。尽管写入寿命很高，但是并不是只有设置写道EEPROM中。如果你写入频繁，你的MCU寿命将会变短。
-* �����������������������ô�������������������������ԣ��������൱���ӡ�
+* 如果您���理�����个例子，�����您可能���望避免使用这��特性，因���它相当复杂。
-### ����ʵ��
+### 示���实现
-��������������������ã����Ҷ�д������ʹ�����û����֡�����һ�����ӵĺ������кܶ�����Ҫ����ʵ���ϣ���ʹ���˺ܶ�����������������
+本例讲解了如何添加设置，并且读写。本里使用了用户布局。这是一个复杂的函数，有很多事情要做。实际上，它使用了很多上述函数来工作！
-�����keymap.c�������������´�������������:
+在你的keymap.c文件中���将以下��码添加至��部:
 ```c
 typedef union {
  uint32_t raw;
@@ -354,19 +354,19 @@ typedef union {
 user_config_t user_config;
 ```
-���ϴ��뽨����һ���ṹ�壬�ýṹ����Դ洢���ò�������д��EEPROM�������㽫���趨���������Ϊ�ڽṹ������Ȼ���塣Ҫ��ס`bool` (����)ֵʹ��1λ, `uint8_t`ʹ��8λ, `uint16_t`ʹ��16λ������Ի�ϴ���ʹ�ã�����˳��Ǵ����ܻ������鷳����Ϊ�ǻ�ı�д��д����ֵ�� 
+以上代码建立了一个结构体，该结构体可以存储设置并可用于写入EEPROM。如此这般将无需定义变量，因为在结构体中已然定义。要记住`bool` (布尔)值使用1位, `uint8_t`使用8位, `uint16_t`使用16位。你可以混合搭配使用，但是顺序记错可能会招致麻烦，因为那会改变写入写出的值。 
- `layer_state_set_*`������ʹ����`rgb_layer_change`��ʹ����`keyboard_post_init_user`��`process_record_user`������һ�С�
+ `layer_state_set_*`函数中使用了`rgb_layer_change`，使用了`keyboard_post_init_user`和`process_record_user`来配置一切。
-����Ҫʹ��`keyboard_post_init_user����Ҫ����`eeconfig_read_user()`�������ոմ����Ľṹ�塣Ȼ������������ʹ������ṹ���������Ĳ����еĹ��ܡ����������� 
+首先要使用`keyboard_post_init_user，你要加入`eeconfig_read_user()`来填充你刚刚创建的结构体。然后您可以立即使用这个结构来控制您的布局中的功能。就像这样： 
 ```c
 void keyboard_post_init_user(void) {
-  // ���ò��ּ����ľ����ʼ��
+  // 调用布���级别的矩��初始化
-  // ��EEPROM����������
+  // 从EEPROM��用户配置
  user_config.raw = eeconfig_read_user();
-  // ��ʹ�ܣ�����Ĭ�ϲ�
+  // 如使能，设���默���层
  if (user_config.rgb_layer_change) {
    rgblight_enable_noeeprom();
    rgblight_sethsv_noeeprom_cyan(); 
@@ -374,7 +374,7 @@ void keyboard_post_init_user(void) {
  }
 }
 ```
-���Ϻ������ڶ�EEPROM���ú�����ʹ�ø�����������Ĭ�ϲ�RGB��ɫ��"raw"��ֵ�Ǵ����������"union"�����Ľṹ����ת�����ġ� 
+以上函数会在读EEPROM配置后立即使用该设置来设置默认层RGB颜色。"raw"的值是从你上面基于"union"创建的结构体中转换来的。 
 ```c
 uint32_t layer_state_set_user(uint32_t state) {
@@ -391,86 +391,86 @@ uint32_t layer_state_set_user(uint32_t state) {
    case _ADJUST:
        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
        break;
-    default: //  ������������Ĭ�ϲ�
+    default: //  针对����层或默认层
        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
        break;
    }
  return state;
 }
 ```
-��������ֵʹ��ʱ��ı�RGB����ơ������������ֵ, Ϊ`process_record_user`����һ���¼������`RGB_LYR`������Ҫȷ�������ʹ��������RGB���룬ʹ�������ʾ������رգ��뽫������Ϊ��
+这样仅在值使能时会改变RGB背光灯。现在配置这个值, 为`process_record_user`创建一个新键码叫做`RGB_LYR`。我们要确保，如果使用正常的RGB代码，使用上面的示例将其关闭，请将其设置为：
 ```c
 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
  switch (keycode) {
    case FOO:
      if (record->event.pressed) {
-        // ����ʱ����ʲô
+        // 按下时做点什么
      } else {
-        // �ͷ�ʱ����ʲô
+        // 释放时做点什么
      }
-      return false; // �����˼��Ľ�һ������
+      return false; // 跳过此键的进一步处理
    case KC_ENTER:
-        // �ڰ��»���ʱ��������
+        // 在按下回车时播放��符
        if (record->event.pressed) {
            PLAY_NOTE_ARRAY(tone_qwerty);
        }
-        return true; // ��QMK�����س�����/�ͷ��¼�
+        return true; // 让QMK产生回车按下/释放事件
-    case RGB_LYR:  // ������underglow��Ϊ����ʾ��������ʹ�á�
+    case RGB_LYR:  // 本句让underglow作���层指示，或��常使用。
        if (record->event.pressed) { 
-            user_config.rgb_layer_change ^= 1; // �л�״̬
+            user_config.rgb_layer_change ^= 1; // 切换状态
-            eeconfig_update_user(user_config.raw); // ��EEPROMд����״̬
+            eeconfig_update_user(user_config.raw); // 向EEPROM写入新状态
-            if (user_config.rgb_layer_change) { // �����״̬��ʹ��
+            if (user_config.rgb_layer_change) { // 如果���状态被使能
-                layer_state_set(layer_state);   // �������̸�������ɫ
+                layer_state_set(layer_state);   // 那么立刻��新层�����
            }
        }
        return false; break;
-    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // �������е�RGB���� (see quantum_keycodes.h, L400 ���Բο�)
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 对于所有的RGB代码 (see quantum_keycodes.h, L400 可以参考)
-        if (record->event.pressed) { //����ʧ�ܲ�ָʾ��������ı���������������������
+        if (record->event.pressed) { //本句��能层指示，假�����改变了���个…���要把它禁用
-            if (user_config.rgb_layer_change) {        // ����ʹ��ʱ
+            if (user_config.rgb_layer_change) {        // 仅���使能时
-                user_config.rgb_layer_change = false;  // ʧ�ܣ�Ȼ�� 
+                user_config.rgb_layer_change = false;  // 失能，然后 
-                eeconfig_update_user(user_config.raw); // ��EEPROMд������
+                eeconfig_update_user(user_config.raw); // 向EEPROM写入���置
            }
        }
        return true; break;
    default:
-      return true; // ������������
+      return true; // 按其���键��常
  }
 }
 ```
-�����Ҫ����`eeconfig_init_user`���������Ե�EEPROM����ʱ������ָ��Ĭ��ֵ, �����Զ����������ǿ������EEPROM������`EEP_RST`�����[Bootmagic](feature_bootmagic.md)���������磬���Ҫ��Ĭ�����������RGB��ָʾ��������Ĭ��ֵ
+最后你要加入`eeconfig_init_user`函数，所以当EEPROM重置时，可以指定默认值, 甚至自定义操作。想强制重置EEPROM，请用`EEP_RST`键码或[Bootmagic](feature_bootmagic.md)函数。比如，如果要在默认情况下设置RGB层指示，并保存默认值
 ```c
-void eeconfig_init_user(void) {  // EEPROM��������
+void eeconfig_init_user(void) {  // EEPROM正被重置
  user_config.raw = 0;
-  user_config.rgb_layer_change = true; // ������Ҫ����ʹ��
+  user_config.rgb_layer_change = true; // 我��想要默认使能
-  eeconfig_update_user(user_config.raw); // ��EEPROMд��Ĭ��ֵ
+  eeconfig_update_user(user_config.raw); // 向EEPROM写入默认值
-  // use the non noeeprom versions, ��Ҫ��EEPROMд����Щֵ
+  // use the non noeeprom versions, 还要向EEPROM写入这些值
-  rgblight_enable(); // Ĭ��ʹ��RGB
+  rgblight_enable(); // 默认使能RGB
-  rgblight_sethsv_cyan();  // Ĭ��������ɫ
+  rgblight_sethsv_cyan();  // 默���设置青色
-  rgblight_mode(1); // Ĭ�����ó���
+  rgblight_mode(1); // 默���设置长亮
 }
 ```
-Ȼ��������ˡ�RGB��ָʾ����������������ʱ������������û�һֱ���棬��������¼��̡������ʹ������RGB���룬��ָʾ��ʧ�ܣ��������������������ˡ� 
+然后就完事了。RGB层指示会在你想让它工作时工作。这个设置会一直保存，即便你拔下键盘。如果你使用其他RGB代码，层指示将失能，现在它可以做你所想了。 
-### 'EECONFIG' �����ĵ�
+### 'EECONFIG' 函数文档
-* ����/�޶�: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`��`void eeconfig_update_kb(uint32_t val)`
+* 键盘/修订: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)`和`void eeconfig_update_kb(uint32_t val)`
-* ����: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`��`void eeconfig_update_user(uint32_t val)`
+* 布局: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)`和`void eeconfig_update_user(uint32_t val)`
-`val` ������д��EEPROM��ֵ��`eeconfig_read_*`�������EEPROM����һ��32λ(˫��)��ֵ��
+`val` 是你想写入EEPROM的值，`eeconfig_read_*`函数会���EEPROM返回���个32位(双字)的值。
-# �Զ������-�����ٽ�ֵ(TAPPING_TERM)
+# 自���义��键-长按�����值(TAPPING_TERM)
-Ĭ�������,����-�����ٽ�ֵ��ȫ��ͳһ�ģ����Ҳ���ͨ�����������á����ڴ�����û���˵��ܺá���������Щ����£�����`LT`����˵������ʱ��˫���ܼ����������󣬿�������Ϊ��Щ���������ļ������װ�ס��Ϊ�˲���ÿ�����Զ�����룬�����ܿ���Ϊÿ��������`TAPPING_TERM`��
+默认情况下,击键-长按临界值是全球统一的，并且不能通过键进行配置。对于大多数用户来说这很好。但是在有些情况下，对于`LT`键来说按键延时对双功能键的提升更大，可能是因为有些键比其他的键更容易按住。为了不给每个都自定义键码，本功能可以为每个键定义`TAPPING_TERM`。
-��ʹ���������ܵĻ�, Ҫ����`config.h`����`#define TAPPING_TERM_PER_KEY`��
+想使能这���功能的话, 要先在`config.h`加上`#define TAPPING_TERM_PER_KEY`。
-## `get_tapping_term`����ʵ��
+## `get_tapping_term`示���实现
-��Ҫ�޸Ļ��ڼ����`TAPPING TERM`,��Ҫ��`keymap.c`�ļ��������´���: 
+想要修改基于键码的`TAPPING TERM`,你要向`keymap.c`文件添加如下代���: 
 ```c
 uint16_t get_tapping_term(uint16_t keycode) {
@@ -485,6 +485,6 @@ uint16_t get_tapping_term(uint16_t keycode) {
 }
 ```
-### `get_tapping_term` �����ĵ�
+### `get_tapping_term` 函数文档
-������ƪ����������,����������quantum���߼��̼����������ֻҪ�û����������ɡ�
+��像这篇的其���功���,这��不需要quantum或者键盘���别的函数���只要用户���函数即��。
diff --git a/docs/zh-cn/faq_build.md b/docs/zh-cn/faq_build.md
index 8fb449db3..0d9047bc5 100644
--- a/docs/zh-cn/faq_build.md
+++ b/docs/zh-cn/faq_build.md
@@ -56,11 +56,6 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="1c11", MODE:="0666"
 ?> 事实上没有一个驱动的最佳选择，有些选项就是和某些系统相辅相成。但libUSB和WinUSB似乎也算是这里的最佳选择了。
 如果bootloader在设备列表中没有显示，你可能要使能 "List all devices"选项在选项菜单中`Options`，然后找到有问题的bootloader设备。(译者注：在win10中可能为 查看-显示隐藏的设备)
-## WINAVR已淘汰
-不再推荐使用WINAVR，使用可能会导致问题
-详情请见[TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).
 ## USB VID 和 PID
 你可以在编辑`config.h`时使用任何你想用的ID值。实际上，使用任何可能未使用的ID都没有问题，除了有极低的与其他产品发生冲突的可能性。
@@ -73,29 +68,6 @@ https://github.com/tmk/tmk_keyboard/issues/150
 - http://www.obdev.at/products/vusb/license.html
 - http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1
-## Cortex: `cstddef: No such file or directory`
-在Ubuntu 14.04上的GCC 4.8 会出现这种问题需要用这个PPA升级到4.9。
-https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded
-https://github.com/tmk/tmk_keyboard/issues/212
-https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstddef
-https://developer.mbed.org/forum/mbed/topic/5205/
-## `clock_prescale_set` and `clock_div_1` Not Available
-你的工具链太旧了不支持MCU。比如WinAVR 20100110就不支持ATMega32u2.
-```
-Compiling C: ../../tmk_core/protocol/lufa/lufa.c
-avr-gcc -c -mmcu=atmega32u2 -gdwarf-2 -DF_CPU=16000000UL -DINTERRUPT_CONTROL_ENDPOINT -DBOOTLOADER_SIZE=4096 -DF_USB=16000000UL -DARCH=ARCH_AVR8 -DUSB_DEVICE_ONLY -DUSE_FLASH_DESCRIPTORS -DUSE_STATIC_OPTIONS="(USB_DEVICE_OPT_FULLSPEED | USB_OPT_REG_ENABLED | USB_OPT_AUTO_PLL)" -DFIXED_CONTROL_ENDPOINT_SIZE=8  -DFIXED_NUM_CONFIGURATIONS=1 -DPROTOCOL_LUFA -DEXTRAKEY_ENABLE -DCONSOLE_ENABLE -DCOMMAND_ENABLE -DVERSION=unknown -Os -funsigned-char -funsigned-bitfields -ffunction-sections -fdata-sections -fno-inline-small-functions -fpack-struct -fshort-enums -fno-strict-aliasing -Wall -Wstrict-prototypes -Wa,-adhlns=obj_alps64/protocol/lufa/lufa.lst -I. -I../../tmk_core -I../../tmk_core/protocol/lufa -I../../tmk_core/protocol/lufa/LUFA-git -I../../tmk_core/common -std=gnu99 -include config.h -MMD -MP -MF .dep/obj_alps64_protocol_lufa_lufa.o.d  ../../tmk_core/protocol/lufa/lufa.c -o obj_alps64/protocol/lufa/lufa.o
-../../tmk_core/protocol/lufa/lufa.c: In function 'setup_mcu':
-../../tmk_core/protocol/lufa/lufa.c:575: warning: implicit declaration of function 'clock_prescale_set'
-../../tmk_core/protocol/lufa/lufa.c:575: error: 'clock_div_1' undeclared (first use in this function)
-../../tmk_core/protocol/lufa/lufa.c:575: error: (Each undeclared identifier is reported only once
-../../tmk_core/protocol/lufa/lufa.c:575: error: for each function it appears in.)
-make: *** [obj_alps64/protocol/lufa/lufa.o] Error 1
-```
 ## AVR的BOOTLOADER_SIZE
 注意Teensy2.0++ bootloader的大小是2048字节。有些Makefile注释错了。
diff --git a/docs/zh-cn/faq_debug.md b/docs/zh-cn/faq_debug.md
index a3cc7c510..7eff7f265 100644
--- a/docs/zh-cn/faq_debug.md
+++ b/docs/zh-cn/faq_debug.md
@@ -101,56 +101,6 @@ https://github.com/tmk/tmk_keyboard#boot-magic-configuration---virtual-dip-switc
 http://deskthority.net/workshop-f7/rebuilding-and-redesigning-a-classic-thinkpad-keyboard-t6181-60.html#p146279
-## Bootloader跳转不好用
-在**Makefile**中正确配置**Makefile**大小。如果分区大小不正确，引导加载程序可能无法从**Magic command**和**Boot Magic**加载。
-```
-#   bootloader字节数：
-#   Atmel DFU loader(ATmega32U4)   4096
-#   Atmel DFU loader(AT90USB128)   8192
-#   LUFA bootloader(ATmega32U4)    4096
-#   Arduino Caterina(ATmega32U4)   4096
-#   USBaspLoader(ATmega***)        2048
-#   Teensy   halfKay(ATmega32U4)   512
-#   Teensy++ halfKay(AT90USB128)   2048
-OPT_DEFS += -DBOOTLOADER_SIZE=4096
-```
-AVR引导大小是通过**BOOTSZ**熔丝位来设置的。查阅你单片机的datasheet。
-记住，datasheet用的是**Word**(2字节)表示大小和地址，TMK用的是**Byte**。
-AVR引导部分位于闪存的末尾，如下所示（Application是应用区，Bootloader是引导区）。
-```
-byte     Atmel/LUFA(ATMega32u4)          byte     Atmel(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-4KB               |               | 128KB-8KB
-0x6000   +---------------+               0x1E000  +---------------+
-         |  Bootloader   | 4KB                    |  Bootloader   | 8KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-byte     Teensy(ATMega32u4)              byte     Teensy++(AT90SUB1286)
-0x0000   +---------------+               0x00000  +---------------+
-         |               |                        |               |
-         |               |                        |               |
-         |  Application  |                        |  Application  |
-         |               |                        |               |
-         =               =                        =               =
-         |               | 32KB-512B              |               | 128KB-2KB
-0x7E00   +---------------+               0x1FC00  +---------------+
-         |  Bootloader   | 512B                   |  Bootloader   | 2KB
-0x7FFF   +---------------+               0x1FFFF  +---------------+
-```
-详情请见下方issue。
-https://github.com/tmk/tmk_keyboard/issues/179
-如果你使用TeensyUSB, 有一个[已知bug](https://github.com/qmk/qmk_firmware/issues/164)硬件重置按钮阻止软件定义重置键工作。重新插拔键盘就好了。
 ## 特殊额外键不起作用(系统，音频控制键)
 你要在`rules.mk`定义`EXTRAKEY_ENABLE`在QMK中使用它们。
@@ -173,24 +123,6 @@ EXTRAKEY_ENABLE = yes          # 音频控制和系统控制
 Arduino Leonardo和micro使用**ATMega32U4**，该芯片TMK可用，但Arduino的bootloader会导致问题。
-## 为锁定键添加指示灯
-你要自制CapsLock, ScrollLock 和 NumLock指示灯？见下文。
-http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p191560
-## 为Arduino Micro/Leonardo编程
-按下重置键然后在8秒内运行下方这样的命令。
-```
-avrdude -patmega32u4 -cavr109 -b57600 -Uflash:w:adb_usb.hex -P/dev/ttyACM0
-```
-设备名称因系统而异。
-http://arduino.cc/en/Main/ArduinoBoardMicro
-https://geekhack.org/index.php?topic=14290.msg1563867#msg1563867
 ## USB 3 兼容性
 据传说有些人用USB3接口会有问题，用USB2的试试。
diff --git a/docs/zh-cn/faq_keymap.md b/docs/zh-cn/faq_keymap.md
index ee8e3c06b..7fb434b4c 100644
--- a/docs/zh-cn/faq_keymap.md
+++ b/docs/zh-cn/faq_keymap.md
@@ -66,24 +66,8 @@ https://github.com/tmk/tmk_keyboard/issues/67
 远古机械键盘偶尔会有自锁机械开关，现在几乎没有了。***大多数情况下你不需要使用该功能，且要使用`KC_CAPS`, `KC_NLCK`和`KC_SLCK`这三个键码。***
 ## 输入ASCII之外的特殊字符比如Cédille 'Ç'
-没有在所有系统中输入这个的通用方法。你要定义针对你的特定操作系统或布局的**宏**。
-比如看这个**宏**代码的文章。
+请见[Unicode](feature_unicode.md)功能。
-http://deskthority.net/workshop-f7/tmk-keyboard-firmware-collection-t4478-120.html#p195620
-<!--翻译问题：下方维基百科链接应全部替换为中文链接，暂未找到全部-->
-在**Windows**上，可以用`AltGr`键或**Alt码**。
-* http://en.wikipedia.org/wiki/AltGr_key
-* https://zh.wikipedia.org/wiki/Alt%E7%A0%81
-在**Mac OS**定义`Option`键组合。
-* https://zh.wikipedia.org/wiki/Option%E9%94%AE#%E6%9B%BF%E4%BB%A3%E9%94%AE%E7%9B%98%E8%BE%93%E5%85%A5
-在**Xorg**可以改用`compose`键。
-* http://en.wikipedia.org/wiki/Compose_key
-下方链接查看**Unicode**输入。
-* http://en.wikipedia.org/wiki/Unicode_input
 ## macOS上的`Fn` 
@@ -136,51 +120,6 @@ https://github.com/tekezo/Karabiner/issues/403
 请见[Grave Escape](feature_grave_esc.md)功能。
-## 右侧双角色修改键(诸如Shift、Alt等有修改其他键作用的键)变箭头键
-右侧修改键单击时会变为箭头键，长按就还是修改键。在TMK中双角色键称之为**TAP**.
-```
-#include "keymap_common.h"
-/* 用TMK双角色键功能实现右侧修改键改箭头键
- *
- *  https://github.com/tmk/tmk_core/blob/master/doc/keymap.md#213-modifier-with-tap-keydual-role
- *  https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
- */
-const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
-    /* 0: qwerty */
-    [0] = LAYOUT( \
-        ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, NUHS,BSPC, \
-        TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSLS, \
-        LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   SCLN,QUOT,ENT,  \
-        LSFT,NUBS,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,FN0, ESC, \
-        FN4, LGUI,LALT,          SPC,                     APP, FN2, FN1, FN3),
-    [1] = LAYOUT( \
-        GRV, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, TRNS,TRNS, \
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,\
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS, \
-        TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,FN5, TRNS, \
-        TRNS,TRNS,TRNS,          TRNS,                    TRNS,FN7, FN6, FN8),
-};
-const uint16_t PROGMEM fn_actions[] = {
-    [0] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_UP),
-    [1] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_DOWN),
-    [2] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_LEFT),
-    [3] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_RIGHT),
-    [4] = ACTION_LAYER_MOMENTARY(1),
-    [5] = ACTION_MODS_TAP_KEY(MOD_RSFT, KC_PGUP),
-    [6] = ACTION_MODS_TAP_KEY(MOD_RGUI, KC_PGDN),
-    [7] = ACTION_MODS_TAP_KEY(MOD_RALT, KC_HOME),
-    [8] = ACTION_MODS_TAP_KEY(MOD_RCTL, KC_END),
-};
-```
-双角色键说明: https://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 ## Mac OSX的弹出键
 `KC_EJCT` 键码在OSX可以使用 https://github.com/tmk/tmk_keyboard/issues/250
 似乎Windows10会忽略该键码，Linux/Xorg可以识别该键码但默认不映射。
diff --git a/docs/zh-cn/getting_started_github.md b/docs/zh-cn/getting_started_github.md
index 0400eea64..2b2f7a75c 100644
--- a/docs/zh-cn/getting_started_github.md
+++ b/docs/zh-cn/getting_started_github.md
@@ -16,17 +16,23 @@ Github can be a little tricky to those that aren't familiar with it - this guide
 ![HTTPS链接](http://i.imgur.com/eGO0ohO.jpg)
-然后，在命令行输入`git clone `，然后粘贴你的链接:
+然后，在命令行输入`git clone --recurse-submodules `，然后粘贴你的链接:
 ```
-user@computer:~$ git clone https://github.com/whoeveryouare/qmk_firmware.git
+user@computer:~$ git clone --recurse-submodules https://github.com/whoeveryouare/qmk_firmware.git
 Cloning into 'qmk_firmware'...
-remote: Counting objects: 46625, done.
+remote: Enumerating objects: 9, done.
-remote: Compressing objects: 100% (2/2), done.
+remote: Counting objects: 100% (9/9), done.
-remote: Total 46625 (delta 0), reused 0 (delta 0), pack-reused 46623
+remote: Compressing objects: 100% (5/5), done.
-Receiving objects: 100% (46625/46625), 84.47 MiB | 3.14 MiB/s, done.
+remote: Total 183883 (delta 5), reused 4 (delta 4), pack-reused 183874
-Resolving deltas: 100% (29362/29362), done.
+Receiving objects: 100% (183883/183883), 132.90 MiB | 9.57 MiB/s, done.
-Checking out files: 100% (2799/2799), done.
+Resolving deltas: 100% (119972/119972), done.
+...
+Submodule path 'lib/chibios': checked out '587968d6cbc2b0e1c7147540872f2a67e59ca18b'
+Submodule path 'lib/chibios-contrib': checked out 'ede48346eee4b8d6847c19bc01420bee76a5e486'
+Submodule path 'lib/googletest': checked out 'ec44c6c1675c25b9827aacd08c02433cccde7780'
+Submodule path 'lib/lufa': checked out 'ce10f7642b0459e409839b23cc91498945119b4d'
+Submodule path 'lib/ugfx': checked out '3e97b74e03c93631cdd3ddb2ce43b963fdce19b2'
 ```
 现在你本地计算机有QMK的分叉了,你可以添加你的布局了, 为你的键盘编译并刷新固件吧。如果你觉得你的修改很不错, 你可以添加,提交,然后想你的分叉推出（pull）你的改变，像这样:
diff --git a/docs/zh-cn/getting_started_introduction.md b/docs/zh-cn/getting_started_introduction.md
index dcd0b72a5..b977b6339 100644
--- a/docs/zh-cn/getting_started_introduction.md
+++ b/docs/zh-cn/getting_started_introduction.md
@@ -4,7 +4,7 @@
 ## 基本QMK结构
-QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。
+QMK是[Jun Wako](https://github.com/tmk)的[tmk_keyboard](https://github.com/tmk/tmk_keyboard)工程的一个分叉。经过更改的TMK原始代码放在`tmk_core` 文件夹中。 QMK增加的新东西可以在 `quantum` 文件夹中找到。 键盘项目可以在 `handwired`（手动飞线） 和 `keyboard`（PCB键盘）这两个文件夹找到。
 ### 用户空间结构