19 files changed, 1024 insertions, 58 deletions
diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md
index 65b4ea1e5..83ebafe60 100644
--- a/docs/feature_debounce_type.md
+++ b/docs/feature_debounce_type.md
@@ -1,43 +1,151 @@
-# Debounce algorithm
+# Contact bounce / contact chatter
 
-QMK supports multiple debounce algorithms through its debounce API.
+Mechanical switches often don't have a clean single transition between pressed and unpressed states.
+
+In an ideal world, when you press a switch, you would expect the digital pin to see something like this:
+(X axis showing time
+```
+voltage                   +----------------------
+ ^                        |
+ |                        |
+ |      ------------------+
+          ----> time
+```
+
+However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions,
+until the value finally settles.
+```
+                  +-+ +--+ +-------------
+                  | | |  | |
+                  | | |  | |
++-----------------+ +-+  +-+
+```
+The time it takes for the switch to settle might vary with switch type, age, and even pressing technique.
+
+If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated
+multiple times.
+
+There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter,
+while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software
+debouncing methods available in QMK.
+
+While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning,
+while the key is not changing state, sometimes short random 0->1 or 1->0 transitions might be read by the digital circuit, for example:
+```
+                  +-+
+                  | |
+                  | |
++-----------------+ +--------------------
+```
+
+Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is
+susceptible to noise, you must choose a debounce method that will also mitigate noise for you.
+
+## Types of debounce algorithms
 
-The logic for which debounce method called is below. It checks various defines that you have set in rules.mk
+1) Unit of time: Timestamp (milliseconds) vs Cycles (scans)
+   * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts.
+     This time might be measured in various units:
+     * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan
+     * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does substraction to figure out time elapsed.
+   * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical
+     switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard.
+   * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the
+     performance of the matrix scanning code. If you use cycles-based debouncing, and you significantly improve the performance of your scanning
+     code, you might end up with less effective debouncing. A situation in which cycles-based debouncing might be preferable is when
+     noise is present, and the scanning algorithm is slow, or variable speed. Even if your debounce algorithm is fundamentally noise-resistant,
+     if the scanning is slow, and you are using a timestamp-based algorithm, you might end up making a debouncing decision based on only two
+     sampled values, which will limit the noise-resistance of the algorithm.
+   * Currently all built-in debounce algorithms support timestamp-based debouncing only. In the future we might
+     implement cycles-based debouncing, and it will be selectable via a ```config.h``` macro.
+
+2) Symmetric vs Asymmetric
+   * Symmetric - apply the same debouncing algorithm, to both key-up and key-down events.
+     * Recommended naming convention: ```sym_*```
+   * Asymmetric - apply different debouncing algorithms to key-down and key-up events. E.g. Eager key-down, Defer key-up.
+     * Recommended naming convention: ```asym_*``` followed by details of the type of algorithm in use, in order, for key-down and then key-up
+
+3) Eager vs Defer
+   * Eager - any key change is reported immediately. All further inputs for DEBOUNCE ms are ignored.
+     * Eager algorithms are not noise-resistant.
+     * Recommended naming conventions:
+        * ```sym_eager_*```
+        * ```asym_eager_*_*```: key-down is using eager algorithm
+        * ```asym_*_eager_*```: key-up is using eager algorithm
+   * Defer - wait for no changes for DEBOUNCE ms before reporting change.
+     * Defer algorithms are noise-resistant
+     * Recommended naming conventions:
+        * ```sym_defer_*```
+        * ```asym_defer_*_*```: key-down is using eager algorithm
+        * ```asym_*_defer_*```: key-up is using eager algorithm
+
+4) Global vs Per-Key vs Per-Row
+   * Global - one timer for all keys. Any key change state affects global timer
+     * Recommended naming convention: ```*_g```
+   * Per-key - one timer per key
+     * Recommended naming convention: ```*_pk```
+   * Per-row - one timer per row
+     * Recommended naming convention: ```*_pr```
+   * Per-key and per-row algorithms consume more resources (in terms of performance,
+     and ram usage), but fast typists might prefer them over global.
+
+## Debounce algorithms supported by QMK
+
+QMK supports multiple debounce algorithms through its debounce API.
+The logic for which debounce method called is below. It checks various defines that you have set in ```rules.mk```
 
 ```
 DEBOUNCE_DIR:= $(QUANTUM_DIR)/debounce
-DEBOUNCE_TYPE?= sym_g
+DEBOUNCE_TYPE?= sym_defer_g
 ifneq ($(strip $(DEBOUNCE_TYPE)), custom)
     QUANTUM_SRC += $(DEBOUNCE_DIR)/$(strip $(DEBOUNCE_TYPE)).c
 endif
 ```
 
-# Debounce selection
+### Debounce selection
 
 | DEBOUNCE_TYPE    | Description                                          | What else is needed           |
 | -------------    | ---------------------------------------------------  | ----------------------------- |
-| Not defined      | Use the default algorithm, currently sym_g           | Nothing                       |
+| Not defined      | Use the default algorithm, currently sym_defer_g     | Nothing                       |
 | custom           | Use your own debounce code                           | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
-| anything_else    | Use another algorithm from quantum/debounce/*        | Nothing                       |
+| Anything Else    | Use another algorithm from quantum/debounce/*        | Nothing                       |
 
 **Regarding split keyboards**:
 The debounce code is compatible with split keyboards.
 
-# Use your own debouncing code
-* Set ```DEBOUNCE_TYPE = custom```.
-* Add ```SRC += debounce.c```
+### Selecting an included debouncing method
+Keyboards may select one of the already implemented debounce methods, by adding to ```rules.mk``` the following line:
+```
+DEBOUNCE_TYPE = <name of algorithm>
+```
+Where name of algorithm is one of:
+* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
+  * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
+* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. 
+For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
+appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
+* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
+* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
+
+### A couple algorithms that could be implemented in the future:
+* ```sym_defer_pr```
+* ```sym_eager_g```
+* ```asym_eager_defer_pk```
+
+### Use your own debouncing code
+You have the option to implement you own debouncing algorithm. To do this:
+* Set ```DEBOUNCE_TYPE = custom``` in ```rules.mk```.
+* Add ```SRC += debounce.c``` in ```rules.mk```
 * Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples.
 * Debouncing occurs after every raw matrix scan.
 * Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
+* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce```
 
-# Changing between included debouncing methods
-You can either use your own code, by including your own debounce.c, or switch to another included one.
-Included debounce methods are:
-* eager_pr - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. 
-For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
-appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
-* eager_pk - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
-* sym_g - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occured, all input changes are pushed.
-* sym_pk - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occured on that key, the key status change is pushed.
+### Old names
+The following old names for existing algorithms will continue to be supported, however it is recommended to use the new names instead.
 
+* sym_g - old name for sym_defer_g
+* eager_pk - old name for sym_eager_pk
+* sym_pk - old name for sym_defer_pk
+* eager_pr - old name for sym_eager_pr
 
diff --git a/docs/ja/api_development_environment.md b/docs/ja/api_development_environment.md
new file mode 100644
index 000000000..8dce1ba2f
--- /dev/null
+++ b/docs/ja/api_development_environment.md
@@ -0,0 +1,8 @@
+# 開発環境のセットアップ
+
+<!---
+  original document: 0.9.50:docs/api_development_environment.md
+  git diff 0.9.50 HEAD -- docs/api_development_environment.md | cat
+-->
+
+開発環境をセットアップするには、[qmk_web_stack](https://github.com/qmk/qmk_web_stack) に行ってください。
diff --git a/docs/ja/api_development_overview.md b/docs/ja/api_development_overview.md
new file mode 100644
index 000000000..0612507b4
--- /dev/null
+++ b/docs/ja/api_development_overview.md
@@ -0,0 +1,49 @@
+# QMK コンパイラ開発ガイド	 
+
+<!---
+  original document: 0.9.50:docs/api_development_overview.md
+  git diff 0.9.50 HEAD -- docs/api_development_overview.md | cat
+-->
+
+このページでは、開発者に QMK コンパイラを紹介しようと思います。コードを読まなければならないような核心となる詳細に立ち入って調べることはしません。ここで得られるものは、コードを読んで理解を深めるためのフレームワークです。
+
+# 概要
+
+QMK Compile API は、いくつかの可動部分からできています:
+
+![構造図](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg)
+
+API クライアントは API サービスと排他的にやりとりをします。ここでジョブをサブミットし、状態を調べ、結果をダウンロードします。API サービスはコンパイルジョブを [Redis Queue](https://python-rq.org) に挿入し、それらのジョブの結果について RQ と S3 の両方を調べます。
+
+ワーカーは RQ から新しいコンパイルジョブを取り出し、ソースとバイナリを S3 互換のストレージエンジンにアップロードします。
+
+# ワーカー
+
+QMK コンパイラワーカーは実際のビルド作業に責任を持ちます。ワーカーは RQ からジョブを取り出し、ジョブを完了するためにいくつかの事を行います:
+
+* 新しい qmk_firmware のチェックアウトを作成する
+* 指定されたレイヤーとキーボードメタデータを使って `keymap.c` をビルドする
+* ファームウェアをビルドする
+* ソースのコピーを zip 形式で圧縮する
+* ファームウェア、ソースの zip ファイル、メタデータファイルを S3 にアップロードする
+* ジョブの状態を RQ に送信する
+
+# API サービス
+
+API サービスは比較的単純な Flask アプリケーションです。理解しておくべきことが幾つかあります。
+
+## @app.route('/v1/compile', methods=['POST'])
+
+これは API の主なエントリーポイントです。クライアントとのやりとりはここから開始されます。クライアントはキーボードを表す JSON ドキュメントを POST し、API はコンパイルジョブをサブミットする前にいくらかの(とても)基本的な検証を行います。
+
+## @app.route('/v1/compile/&lt;string:job_id&gt;', methods=['GET'])
+
+これは最もよく呼ばれるエンドポイントです。ジョブの詳細が redis から利用可能であればそれを取り出し、そうでなければ S3 からキャッシュされたジョブの詳細を取り出します。
+
+## @app.route('/v1/compile/&lt;string:job_id&gt;/download', methods=['GET'])
+
+このメソッドによりユーザはコンパイルされたファームウェアファイルをダウンロードすることができます。
+
+## @app.route('/v1/compile/&lt;string:job_id&gt;/source', methods=['GET'])
+
+このメソッドによりユーザはファームウェアのソースをダウンロードすることができます。
diff --git a/docs/ja/api_docs.md b/docs/ja/api_docs.md
new file mode 100644
index 000000000..b483c045e
--- /dev/null
+++ b/docs/ja/api_docs.md
@@ -0,0 +1,73 @@
+# QMK API
+
+<!---
+  original document: 0.9.50:docs/api_docs.md
+  git diff 0.9.50 HEAD -- docs/api_docs.md | cat
+-->
+
+このページは QMK API の使い方を説明します。もしあなたがアプリケーション開発者であれば、全ての [QMK](https://qmk.fm) キーボードのファームウェアをコンパイルするために、この API を使うことができます。
+
+## 概要
+
+このサービスは、カスタムキーマップをコンパイルするための非同期 API です。API に 何らかの JSON を POST し、定期的に状態をチェックし、ファームウェアのコンパイルが完了していれば、結果のファームウェアと(もし希望すれば)そのファームウェアのソースコードをダウンロードすることができます。
+
+#### JSON ペイロードの例:
+
+```json
+{
+  "keyboard": "clueboard/66/rev2",
+  "keymap": "my_awesome_keymap",
+  "layout": "LAYOUT_all",
+  "layers": [
+    ["KC_GRV","KC_1","KC_2","KC_3","KC_4","KC_5","KC_6","KC_7","KC_8","KC_9","KC_0","KC_MINS","KC_EQL","KC_GRV","KC_BSPC","KC_PGUP","KC_TAB","KC_Q","KC_W","KC_E","KC_R","KC_T","KC_Y","KC_U","KC_I","KC_O","KC_P","KC_LBRC","KC_RBRC","KC_BSLS","KC_PGDN","KC_CAPS","KC_A","KC_S","KC_D","KC_F","KC_G","KC_H","KC_J","KC_K","KC_L","KC_SCLN","KC_QUOT","KC_NUHS","KC_ENT","KC_LSFT","KC_NUBS","KC_Z","KC_X","KC_C","KC_V","KC_B","KC_N","KC_M","KC_COMM","KC_DOT","KC_SLSH","KC_RO","KC_RSFT","KC_UP","KC_LCTL","KC_LGUI","KC_LALT","KC_MHEN","KC_SPC","KC_SPC","KC_HENK","KC_RALT","KC_RCTL","MO(1)","KC_LEFT","KC_DOWN","KC_RIGHT"],
+    ["KC_ESC","KC_F1","KC_F2","KC_F3","KC_F4","KC_F5","KC_F6","KC_F7","KC_F8","KC_F9","KC_F10","KC_F11","KC_F12","KC_TRNS","KC_DEL","BL_STEP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","_______","KC_TRNS","KC_PSCR","KC_SLCK","KC_PAUS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_PGUP","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_LEFT","KC_PGDN","KC_RGHT"],
+    ["KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","RESET","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(2)","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","KC_TRNS","MO(1)","KC_TRNS","KC_TRNS","KC_TRNS"]
+  ]
+}
+```
+
+ご覧のとおり、ペイロードにはファームウェアを作成および生成するために必要なキーボードの全ての側面を記述します。各レイヤーは QMK キーコードの1つのリストで、キーボードの `LAYOUT` マクロと同じ長さです。もしキーボードが複数の `LAYOUT` マクロをサポートする場合、どのマクロを使うかを指定することができます。
+
+## コンパイルジョブのサブミット
+
+キーマップをファームウェアにコンパイルするには、単純に JSON を `/v1/compile` エンドポイントに POST します。以下の例では、JSON ペイロードを `json_data` という名前のファイルに配置しています。
+
+```
+$ curl -H "Content-Type: application/json" -X POST -d "$(< json_data)" http://api.qmk.fm/v1/compile
+{
+  "enqueued": true,
+  "job_id": "ea1514b3-bdfc-4a7b-9b5c-08752684f7f6"
+}
+```
+
+## 状態のチェック
+
+キーマップをサブミットした後で、簡単な HTTP GET 呼び出しを使って状態をチェックすることができます:
+
+```
+$ curl http://api.qmk.fm/v1/compile/ea1514b3-bdfc-4a7b-9b5c-08752684f7f6
+{
+  "created_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "enqueued_at": "Sat, 19 Aug 2017 21:39:12 GMT",
+  "id": "f5f9b992-73b4-479b-8236-df1deb37c163",
+  "status": "running",
+  "result": null
+}
+```
+
+これは、ジョブをキューに入れることに成功し、現在実行中であることを示しています。5つの状態がありえます:
+
+* **failed**: なんらかの理由でコンパイルサービスが失敗しました。
+* **finished**: コンパイルが完了し、結果を見るには `result` をチェックする必要があります。
+* **queued**: キーマップはコンパイルサーバが利用可能になるのを待っています。
+* **running**: コンパイルが進行中で、まもなく完了するはずです。
+* **unknown**: 深刻なエラーが発生し、[バグを報告](https://github.com/qmk/qmk_compiler/issues)する必要があります。
+
+## 完了した結果を検証
+
+コンパイルジョブが完了したら、`result` キーをチェックします。このキーの値は幾つかの情報を含むハッシュです:
+
+* `firmware_binary_url`: 書き込み可能なファームウェアの URL のリスト
+* `firmware_keymap_url`: `keymap.c` の URL のリスト
+* `firmware_source_url`: ファームウェアの完全なソースコードの URL のリスト
+* `output`: このコンパイルジョブの stdout と stderr。エラーはここで見つけることができます。
diff --git a/docs/ja/api_overview.md b/docs/ja/api_overview.md
new file mode 100644
index 000000000..18b8eae10
--- /dev/null
+++ b/docs/ja/api_overview.md
@@ -0,0 +1,20 @@
+# QMK API
+
+<!---
+  original document: 0.9.50:docs/api_overview.md
+  git diff 0.9.50 HEAD -- docs/api_overview.md | cat
+-->
+
+QMK API は、Web と GUI ツールが [QMK](http://qmk.fm/) によってサポートされるキーボード用の任意のキーマップをコンパイルするために使うことができる、非同期 API を提供します。標準のキーマップテンプレートは、C コードのサポートを必要としない全ての QMK キーコードをサポートします。キーボードのメンテナは独自のカスタムテンプレートを提供して、より多くの機能を実現することができます。
+
+## アプリケーション開発者
+
+もしあなたがアプリケーションでこの API を使うことに興味があるアプリケーション開発者であれば、[API の使用](ja/api_docs.md) に行くべきです。
+
+## キーボードのメンテナ
+
+もし QMK Compiler API でのあなたのキーボードのサポートを強化したい場合は、[キーボードサポート](ja/reference_configurator_support.md) の節に行くべきです。
+
+## バックエンド開発者
+
+もし API 自体に取り組むことに興味がある場合は、[開発環境](ja/api_development_environment.md)のセットアップから始め、それから [API のハッキング](ja/api_development_overview.md) を調べるべきです。
diff --git a/docs/ja/faq_build.md b/docs/ja/faq_build.md
index 97e1bd8cf..62c36f249 100644
--- a/docs/ja/faq_build.md
+++ b/docs/ja/faq_build.md
@@ -145,4 +145,4 @@ ARM ベースのチップ上での 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)とキーボード情報を見てください)。
+いずれかの形式でブートマジックが有効になっている場合は、これも実行できるはずです (実行方法の詳細については、[ブートマジックドキュメント](ja/feature_bootmagic.md)とキーボード情報を見てください)。
diff --git a/docs/ja/faq_general.md b/docs/ja/faq_general.md
index a365e380b..83d1a557b 100644
--- a/docs/ja/faq_general.md
+++ b/docs/ja/faq_general.md
@@ -51,7 +51,7 @@ OK、問題ありません。[GitHub で issue を開く](https://github.com/qmk
 
 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)でこれらのキーコードの完全なリストを見ることができます。
+技術的な観点から、QMK は幾つかの新しい機能を追加した TMK に基づいています。最も注目すべきことは、QMK は利用可能なキーコードの数を増やし、`S()`、`LCTL()` および `MO()` などの高度な機能を実装するためにこれらを使っています。[キーコード](ja/keycodes.md)でこれらのキーコードの完全なリストを見ることができます。
 
 プロジェクトとコミュニティの管理の観点から、TMK は公式にサポートされている全てのキーボードを自分で管理しており、コミュニティのサポートも少し受けています。他のキーボード用に別個のコミュニティが維持するフォークが存在するか、作成できます。デフォルトでは少数のキーマップのみが提供されるため、ユーザは一般的にお互いにキーマップを共有しません。QMK は集中管理されたリポジトリを介して、キーボードとキーマップの両方を共有することを奨励しており、品質基準に準拠する全てのプルリクエストを受け付けます。これらはほとんどコミュニティで管理されますが、必要な場合は QMK チームも支援します。
 
diff --git a/docs/ja/faq_keymap.md b/docs/ja/faq_keymap.md
index 2726e1872..311ebe0e4 100644
--- a/docs/ja/faq_keymap.md
+++ b/docs/ja/faq_keymap.md
@@ -128,7 +128,7 @@ https://github.com/tekezo/Karabiner/issues/403
 
 ## 単一のキーでの Esc と<code>&#96;</code>
 
-[Grave Escape](feature_grave_esc.md) 機能を見てください。
+[Grave Escape](ja/feature_grave_esc.md) 機能を見てください。
 
 ## Mac OSX での Eject
 `KC_EJCT` キーコードは OSX で動作します。https://github.com/tmk/tmk_keyboard/issues/250
diff --git a/docs/ja/feature_split_keyboard.md b/docs/ja/feature_split_keyboard.md
index 74b62310f..1efc98e40 100644
--- a/docs/ja/feature_split_keyboard.md
+++ b/docs/ja/feature_split_keyboard.md
@@ -20,12 +20,12 @@ QMK ファームウェアには、任意のキーボードで使用可能な一�
 
 | Transport | AVR | ARM |
 |------------------------------|--------------------|--------------------|
-| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
+| ['serial'](ja/serial_driver.md) | :heavy_check_mark: | :white_check_mark: <sup>1</sup> |
 | I2C | :heavy_check_mark: |  |
 
 注意:
 
-1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](serial_driver.md)の中で説明されます。
+1. ハードウェアとソフトウェアの両方の制限は、[ドライバーのドキュメント](ja/serial_driver.md)の中で説明されます。
 
 ## ハードウェア設定
 
diff --git a/docs/ja/how_a_matrix_works.md b/docs/ja/how_a_matrix_works.md
index ff4fbb115..b6ded186b 100644
--- a/docs/ja/how_a_matrix_works.md
+++ b/docs/ja/how_a_matrix_works.md
@@ -101,4 +101,4 @@
 - [Deskthority の記事](https://deskthority.net/wiki/Keyboard_matrix)
 - [Dave Dribin による Keyboard Matrix Help (2000)](https://www.dribin.org/dave/keyboard/one_html/)
 - [PCBheaven による How Key Matrices Works](http://pcbheaven.com/wikipages/How_Key_Matrices_Works/) (アニメーションの例)
-- [キーボードの仕組み - QMK ドキュメント](how_keyboards_work.md)
+- [キーボードの仕組み - QMK ドキュメント](ja/how_keyboards_work.md)
diff --git a/docs/ja/quantum_keycodes.md b/docs/ja/quantum_keycodes.md
new file mode 100644
index 000000000..ffcc49446
--- /dev/null
+++ b/docs/ja/quantum_keycodes.md
@@ -0,0 +1,20 @@
+# Quantum キーコード
+
+<!---
+  original document: 0.9.55:docs/quantum_keycodes.md
+  git diff 0.9.55 HEAD -- docs/quantum_keycodes.md | cat
+-->
+
+Quantum キーコードにより、カスタムアクションを定義することなく、基本的なものが提供するものより簡単にキーマップをカスタマイズすることができます。
+
+quantum 内の全てのキーコードは `0x0000` と `0xFFFF` の間の数値です。`keymap.c` の中では、関数やその他の特別な場合があるように見えますが、最終的には C プリプロセッサによってそれらは単一の4バイト整数に変換されます。QMK は標準的なキーコードのために `0x0000` から `0x00FF` を予約しています。これらは、`KC_A`、`KC_1` および `KC_LCTL` のようなキーコードで、USB HID 仕様で定義された基本的なキーです。
+
+このページでは、高度な quantum 機能を実装するために使われる `0x00FF` と `0xFFFF` の間のキーコードを説明します。独自のカスタムキーコードを定義する場合は、それらもこの範囲に配置されます。
+
+## QMK キーコード :id=qmk-keycodes
+
+| キー           | エイリアス | 説明                                                   |
+|----------------|------------|--------------------------------------------------------|
+| `RESET`        |            | 書き込みのために、キーボードを bootloader モードにする |
+| `DEBUG`        |            | デバッグモードの切り替え                               |
+| `EEPROM_RESET` | `EEP_RST`  | キーボードの EEPROM (永続化メモリ) を再初期化する      |
diff --git a/docs/ja/reference_configurator_support.md b/docs/ja/reference_configurator_support.md
new file mode 100644
index 000000000..0151731e9
--- /dev/null
+++ b/docs/ja/reference_configurator_support.md
@@ -0,0 +1,202 @@
+# QMK Configurator でのキーボードのサポート
+
+<!---
+  original document: 0.9.46:docs/reference_configurator_support.md
+  git diff 0.9.46 HEAD -- docs/reference_configurator_support.md | cat
+-->
+
+このページは [QMK Configurator](https://config.qmk.fm/) でキーボードを適切にサポートする方法について説明します。
+
+
+## Configurator がキーボードを理解する方法
+
+Configurator がキーボードをどのように理解するかを理解するには、最初にレイアウトマクロを理解する必要があります。この演習では、17キーのテンキー PCB を想定します。これを `numpad` と呼びます。
+
+```
+|---------------|
+|NLk| / | * | - |
+|---+---+---+---|
+|7  |8  |9  | + |
+|---+---+---|   |
+|4  |5  |6  |   |
+|---+---+---+---|
+|1  |2  |3  |Ent|
+|-------+---|   |
+|0      | . |   |
+|---------------|
+```
+
+?> レイアウトマクロの詳細については、[QMK の理解: マトリックススキャン](ja/understanding_qmk.md?id=matrix-scanning) と [QMK の理解: マトリックスから物理レイアウトへのマップ](ja/understanding_qmk.md?id=matrix-to-physical-layout-map) を見てください。
+
+Configurator の API はキーボードの `.h` ファイルを `qmk_firmware/keyboards/<keyboard>/<keyboard>.h` から読み取ります。numpad の場合、このファイルは `qmk_firmware/keyboards/numpad/numpad.h` です:
+
+```c
+#pragma once
+
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22,      \
+    k30, k31, k32, k33, \
+    k40,      k42       \
+  ) { \
+    { k00, k01,   k02, k03   }, \
+    { k10, k11,   k12, k13   }, \
+    { k20, k21,   k22, KC_NO }, \
+    { k30, k31,   k32, k33   }, \
+    { k40, KC_NO, k42, KC_NO }  \
+}
+```
+
+QMK は `KC_NO` を使って、スイッチマトリックス内のスイッチがない場所を指定します。デバッグが必要な場合に、このセクションを読みやすくするために、`XXX`、`___`、`____` を略記として使うこともあります。通常は `.h` ファイルの先頭近くで定義されます:
+
+```c
+#pragma once
+
+#define XXX KC_NO
+
+#define LAYOUT( \
+    k00, k01, k02, k03, \
+    k10, k11, k12, k13, \
+    k20, k21, k22,      \
+    k30, k31, k32, k33, \
+    k40,      k42       \
+  ) { \
+    { k00, k01, k02, k03 }, \
+    { k10, k11, k12, k13 }, \
+    { k20, k21, k22, XXX }, \
+    { k30, k31, k32, k33 }, \
+    { k40, XXX, k42, XXX }  \
+}
+```
+
+!> この使用方法はキーマップマクロと異なります。キーマップマクロはほとんど常に`KC_NO`については`XXXXXXX` (7つの大文字の X) を、`KC_TRNS` については `_______` (7つのアンダースコア)を使います。
+
+!> ユーザの混乱を防ぐために、`KC_NO` を使うことをお勧めします。
+
+レイアウトマクロは、キーボードに17個のキーがあり、4列それぞれが5行に配置されていることを Configurator に伝えます。スイッチの位置は、0から始まる `k<row><column>` という名前が付けられています。キーマップからキーコードを受け取る上部セクションと、マトリックス内の各キーの位置を指定する下部セクションとが一致する限り、名前自体は実際には問題ではありません。
+
+物理的なキーボードに似た形でキーボードを表示するには、それぞれのキーの物理的な位置とサイズをスイッチマトリックスに結びつけることを Configurator に伝える JSON ファイルを作成する必要があります。
+
+## JSON ファイルのビルド
+
+JSON ファイルをビルドする最も簡単な方法は、[Keyboard Layout Editor](http://www.keyboard-layout-editor.com/) ("KLE") でレイアウトを作成することです。この Raw Data を QMK tool に入れて、Configurator が読み出して使用する JSON ファイルに変換します。KLE は numpad レイアウトをデフォルトで開くため、Getting Started の説明を削除し、残りを使います。
+
+レイアウトが望み通りのものになったら、KLE の Raw Data タブに移動し、内容をコピーします:
+
+```
+["Num Lock","/","*","-"],
+["7\nHome","8\n↑","9\nPgUp",{h:2},"+"],
+["4\n←","5","6\n→"],
+["1\nEnd","2\n↓","3\nPgDn",{h:2},"Enter"],
+[{w:2},"0\nIns",".\nDel"]
+```
+
+このデータを JSON に変換するには、[QMK KLE-JSON Converter](https://qmk.fm/converter/) に移動し、Raw Data を Input フィールド に貼り付け、Convert ボタンをクリックします。しばらくすると、JSON データが Output フィールドに表示されます。内容を新しいテキストドキュメントにコピーし、ドキュメントに `info.json` という名前を付け、`numpad.h` を含む同じフォルダに保存します。
+
+`keyboard_name` オブジェクトを使ってキーボードの名前を設定します。説明のために、各キーのオブジェクトを各行に配置します。これはファイルを人間が読みやすいものにするためのもので、Configurator の機能には影響しません。
+
+```json
+{
+    "keyboard_name": "Numpad",
+    "url": "",
+    "maintainer": "qmk",
+    "tags": {
+        "form_factor": "numpad"
+    },
+    "width": 4,
+    "height": 5,
+    "layouts": {
+        "LAYOUT": {
+            "layout": [
+                {"label":"Num Lock", "x":0, "y":0},
+                {"label":"/", "x":1, "y":0},
+                {"label":"*", "x":2, "y":0},
+                {"label":"-", "x":3, "y":0},
+                {"label":"7", "x":0, "y":1},
+                {"label":"8", "x":1, "y":1},
+                {"label":"9", "x":2, "y":1},
+                {"label":"+", "x":3, "y":1, "h":2},
+                {"label":"4", "x":0, "y":2},
+                {"label":"5", "x":1, "y":2},
+                {"label":"6", "x":2, "y":2},
+                {"label":"1", "x":0, "y":3},
+                {"label":"2", "x":1, "y":3},
+                {"label":"3", "x":2, "y":3},
+                {"label":"Enter", "x":3, "y":3, "h":2},
+                {"label":"0", "x":0, "y":4, "w":2},
+                {"label":".", "x":2, "y":4}
+            ]
+        }
+    }
+}
+```
+
+`layouts` オブジェクトにはキーボードの物理レイアウトを表すデータが含まれます。このオブジェクトには `LAYOUT` という名前のオブジェクトがあり、このオブジェクト名は `numpad.h` のレイアウトマクロの名前と一致する必要があります。`LAYOUT` オブジェクト自体には `layout` という名前のオブジェクトがあります。このオブジェクトにはキーボードの物理キーごとに 1つの JSON オブジェクトが以下の形式で含まれています:
+
+```
+  キーの名前。Configurator では表示されません。
+  |
+  |                   キーボードの左端からのキー単位での
+  |                   | キーの X 軸の位置。
+  |                   |
+  |                   |      キーボードの上端(奥側)からのキー単位での
+  |                   |      | キーの Y 軸位置。
+  ↓                   ↓      ↓
+{"label":"Num Lock", "x":0, "y":0},
+```
+
+一部のオブジェクトには、それぞれキーの幅と高さを表す `"w"` 属性キーと `"h"` 属性キーがあります。
+
+?> `info.json` ファイルの詳細については、[`info.json` 形式](ja/reference_info_json.md) を参照してください。
+
+
+## Configurator がキーをプログラムする方法
+
+Configurator の API は、指定されたレイアウトマクロと JSON ファイルを使って、特定のキーに関連付けられた各ビジュアルオブジェクトを順番に持つキーボードのビジュアル表現を作成します:
+
+| レイアウトマクロのキー | 使用される JSON オブジェクト |
+:---: | :----
+| k00 | {"label":"Num Lock", "x":0, "y":0} |
+| k01 | {"label":"/", "x":1, "y":0} |
+| k02 | {"label":"*", "x":2, "y":0} |
+| k03 | {"label":"-", "x":3, "y":0} |
+| k10 | {"label":"7", "x":0, "y":1} |
+| k11 | {"label":"8", "x":1, "y":1} |
+| k12 | {"label":"9", "x":2, "y":1} |
+| k13 | {"label":"+", "x":3, "y":1, "h":2} |
+| k20 | {"label":"4", "x":0, "y":2} |
+| k21 | {"label":"5", "x":1, "y":2} |
+| k22 | {"label":"6", "x":2, "y":2} |
+| k30 | {"label":"1", "x":0, "y":3} |
+| k31 | {"label":"2", "x":1, "y":3} |
+| k32 | {"label":"3", "x":2, "y":3} |
+| k33 | {"label":"Enter", "x":3, "y":3, "h":2} |
+| k40 | {"label":"0", "x":0, "y":4, "w":2} |
+| k42 | {"label":".", "x":2, "y":4} |
+
+ユーザが Configurator で左上のキーを選択し、Num Lock を割り当てると、Configurator は最初のキーとして `KC_NLCK` を持つキーマップを作成し、同様にキーマップが作成されます。`label` キーは使われません; それらは `info.json` ファイルをデバッグする時に特定のキーを識別するためのユーザの参照のためだけのものです。
+
+
+## 問題と危険
+
+現在のところ、Configurator はキーの回転または ISO Enter などの長方形ではないキーをサポートしません。さらに、"行"から垂直方向にずれているキー、&mdash; 顕著な例として [TKC1800](https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/) のような1800レイアウト上の矢印キー &mdash; は、 `info.json` ファイルの提供者によって調整されていない場合は、KLE-to-JSON コンバータを混乱させます。
+
+### 回避策
+
+#### 長方形ではないキー
+
+ISO Enter キーについては、QMK custom は幅 1.25u、高さ 2u の長方形のキーとして表示し、右端が英数字キーブロックの右端に揃うように配置されます。
+
+![](https://i.imgur.com/JKngtTw.png)  
+*QMK Configurator によって描画される標準 ISO レイアウトの60%キーボード。*
+
+#### 垂直方向にずれたキー
+
+垂直方向にずれたキーについては、ずれていないかのように KLE で配置し、変換された JSON ファイルで必要に応じて Y 値を編集します。
+
+![](https://i.imgur.com/fmDvDzR.png)  
+*矢印キーに適用される垂直方向のずれのない、Keyboard Layout Editor で描画された1800レイアウトのキーボード。*
+
+![](https://i.imgur.com/8beYMBR.png)  
+*キーボードの JSON ファイルで矢印キーを垂直方向にずらすために必要な変更を示す、Unix の diff ファイル。*
diff --git a/docs/ja/reference_glossary.md b/docs/ja/reference_glossary.md
new file mode 100644
index 000000000..19791206f
--- /dev/null
+++ b/docs/ja/reference_glossary.md
@@ -0,0 +1,173 @@
+# QMK 用語集
+
+<!---
+  original document: 0.9.46:docs/reference_glossary.md
+  git diff 0.9.46 HEAD -- docs/reference_glossary.md | cat
+-->
+
+## ARM
+Atmel、Cypress、Kinetis、NXP、ST、TI など多くの企業が生産する 32 ビット MCU のライン。
+
+## AVR
+[Atmel](http://www.microchip.com/) が生産する 8 ビット MCU のライン。AVR は TMK がサポートしていた元のプラットフォームでした。
+
+## AZERTY
+標準的な Français (フランス) キーボードレイアウト。キーボードの最初の6つのキーから命名されました。
+
+## バックライト
+キーボードのライトの総称。バックライトが一般的ですが、それだけではなく、キーキャップあるいはスイッチを通して光る LED の配列。
+
+## Bluetooth
+短距離のピアツーピア無線プロトコル。キーボード用のもっとも一般的なワイヤレスプロトコル。
+
+## ブートローダ
+MCU の保護領域に書き込まれる特別なプログラムで、MCU が独自のファームウェアを通常は USB 経由でアップグレードできるようにします。
+
+## ブートマジック
+よくあるキーの交換あるいは無効化など、様々なキーボードの挙動の変更をその場で実行できる機能。
+
+## C
+システムコードに適した低レベルプログラミング言語。QMK のほとんどのコードは C で書かれています。
+
+## Colemak
+人気が出始めている代替キーボードレイアウト。
+
+## コンパイル
+人間が読めるコードを MCU が実行できるマシンコードに変換するプロセス。
+
+## Dvorak
+1930年代に Dr. August Dvorak によって開発された代替キーボードレイアウト。Dvorak Simplified Keyboard の短縮形。
+
+## 動的マクロ
+キーボードに記録されたマクロで、キーボードのプラグを抜くか、コンピュータを再起動すると失われます。
+
+* [動的マクロドキュメント](ja/feature_dynamic_macros.md)
+
+## Eclipse
+多くの C 開発者に人気のある IDE。
+
+* [Eclipse セットアップ手順](ja/other_eclipse.md)
+
+## ファームウェア
+MCU を制御するソフトウェア
+
+## git
+コマンドラインで使用されるバージョン管理ソフトウェア
+
+## GitHub
+QMK プロジェクトのほとんどをホストする Web サイト。git、課題管理、および QMK の実行に役立つその他の機能を統合して提供します。
+
+## ISP
+インシステムプログラミング。外部ハードウェアと JTAG ピンを使って AVR チップをプログラミングする方法。
+
+## hid_listen
+キーボードからデバッグメッセージを受信するためのインタフェース。[QMK Flasher](https://github.com/qmk/qmk_flasher) あるいは [PJRC の hid_listen](https://www.pjrc.com/teensy/hid_listen.html) を使ってこれらのメッセージを見ることができます。
+
+## キーコード
+特定のキーを表す2バイトの数値。`0x00`-`0xFF` は[基本キーコード](ja/keycodes_basic.md)に使われ、`0x100`-`0xFFFF` は [Quantum キーコード](ja/quantum_keycodes.md) に使われます。
+
+## キーダウン
+キーが押された時に発生し、キーが放される前に完了するイベント。
+
+## キーアップ
+キーが放された時に発生するイベント。
+
+## キーマップ
+物理的なキーボードレイアウトにマップされたキーコードの配列。キーの押下およびリリース時に処理されます。
+
+## レイヤー
+1つのキーが複数の目的を果たすために使われる抽象化。最上位のアクティブなレイヤーが優先されます。
+
+## リーダーキー
+リーダーキーに続けて1, 2 あるいは3つのキーをタップすることで、キーの押下あるいは他の quantum 機能をアクティブにする機能。
+
+* [リーダーキードキュメント](ja/feature_leader_key.md)
+
+## LED
+発光ダイオード。キーボードの表示に使われる最も一般的なデバイス。
+
+## Make
+全てのソースファイルをコンパイルするために使われるソフトウェアパッケージ。キーボードファームウェアをコンパイルするために、様々なオプションを指定して `make` を実行します。
+
+## マトリックス
+MCU がより少ないピン数でキー押下を検出できるようにする列と行の配線パターン。マトリックスには多くの場合、NKRO を可能にするためのダイオードが組み込まれています。
+
+## マクロ
+単一のキーのみを押した後で、複数のキー押下イベント (HID レポート) を送信できる機能。
+
+* [マクロドキュメント](ja/feature_macros.md)
+
+## MCU
+マイクロコントロールユニット。キーボードを動かすプロセッサ。
+
+## モディファイア
+別のキーを入力する間押したままにして、そのキーのアクションを変更するキー。例として、Ctrl、Alt および Shift があります。
+(訳注：モディファイヤ、モディファイヤキー、修飾キーなど、訳語が統一されていませんが同じものです)
+
+## マウスキー
+キーボードからマウスカーソルを制御し、クリックできる機能。
+
+* [マウスキードキュメント](ja/feature_mouse_keys.md)
+
+## N キーロールオーバー (NKRO)
+一度に任意の数のキーの押下を送信できるキーボードに当てはまる用語。
+
+## ワンショットモディファイア
+別のキーが放されるまで押されているかのように機能するモディファイア。キーを押している間に mod を押し続けるのではなく、mod を押してからキーを押すことができます。スティッキーキーまたはデッドキーとも呼びます。
+
+## ProMicro
+低コストの AVR 開発ボード。このデバイスのクローンは ebay で非常に安価(5ドル未満)に見つかることがありますが、多くの場合 pro micro の書き込みに苦労します。
+
+## プルリクエスト
+QMK にコードを送信するリクエスト。全てのユーザが個人のキーマップのプルリクエストを送信することを推奨します。
+
+## QWERTY
+標準の英語キーボードレイアウト。多くの場合、他の言語の標準レイアウトへのショートカット。キーボードの最初の6文字から命名されました。
+
+## QWERTZ
+標準的な Deutsche (ドイツ語) キーボードレイアウト。キーボードの最初の6文字から命名されました。
+
+## ロールオーバー
+キーが既に押されている間にキーを押すことを指す用語。似たものに 2KRO、6KRO、NKRO が含まれます。
+
+## スキャンコード
+単一のキーを表す USB 経由の HID レポートの一部として送信される1バイトの数値。これらの値は、[USB-IF](http://www.usb.org/) が発行する [HID Usage Tables](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) に記載されています。
+
+## スペースカデットシフト
+左または右 shift を1回以上タップすることで、様々なタイプの括弧を入力できる特別な shift キーのセット。
+
+* [スペースカデットシフトドキュメント](ja/feature_space_cadet_shift.md)
+
+## タップ
+キーを押して放す。状況によってはキーダウンイベントとキーアップイベントを区別する必要がありますが、タップは常に両方を一度に指します。
+
+## タップダンス
+押す回数に基づいて、同じキーに複数のキーコードを割り当てることができる機能。
+
+* [タップダンスドキュメント](ja/feature_tap_dance.md)
+
+## Teensy
+手配線での組み立てによく用いられる低コストの AVR 開発ボード。halfkay ブートローダによって書き込みが非常に簡単になるために、数ドル高いにもかかわらず teensy がしばしば選択されます。
+
+## アンダーライト
+キーボードの下側を照らす LED の総称。これらの LED は通常 PCB の底面からキーボードが置かれている表面に向けて照らします。
+
+## ユニコード
+大規模なコンピュータの世界では、ユニコードは任意の言語で文字を表現するためのエンコード方式のセットです。QMK に関しては、様々な OS スキームを使ってスキャンコードの代わりにユニコードコードポイントを送信することを意味します。
+
+* [ユニコードドキュメント](ja/feature_unicode.md)
+
+## 単体テスト
+QMK に対して自動テストを実行するためのフレームワーク。単体テストは、変更が何も壊さないことを確信するのに役立ちます。
+
+* [単体テストドキュメント](ja/unit_testing.md)
+
+## USB
+ユニバーサルシリアルバス。キーボード用の最も一般的な有線インタフェース。
+
+## USB ホスト (あるいは単にホスト)
+USB ホストは、あなたのコンピュータ、またはキーボードが差し込まれているデバイスのことです。
+
+# 探している用語が見つかりませんでしたか？
+
+質問についての [issue を開いて](https://github.com/qmk/qmk_firmware/issues) 、質問した用語についてここに追加することができます。さらに良いのは、定義についてのプルリクエストを開くことです。:)
diff --git a/docs/ja/reference_info_json.md b/docs/ja/reference_info_json.md
new file mode 100644
index 000000000..708f7c19a
--- /dev/null
+++ b/docs/ja/reference_info_json.md
@@ -0,0 +1,78 @@
+# `info.json`
+
+<!---
+  original document: 0.9.46:docs/reference_info_json.md
+  git diff 0.9.46 HEAD -- docs/reference_info_json.md | cat
+-->
+
+このファイルは [QMK API](https://github.com/qmk/qmk_api) によって使われます。このファイルは [QMK Configurator](https://config.qmk.fm/) がキーボードの画像を表示するために必要な情報を含んでいます。ここにメタデータを設定することもできます。
+
+このメタデータを指定するために、`qmk_firmware/keyboards/<name>` の下の全てのレベルで `info.json` を作成することができます。これらのファイルは結合され、より具体的なファイルがそうではないファイルのキーを上書きします。つまり、メタデータ情報を複製する必要はありません。例えば、`qmk_firmware/keyboards/clueboard/info.json` は `manufacturer` および `maintainer` を指定し、`qmk_firmware/keyboards/clueboard/66/info.json` は Clueboard 66% についてのより具体的な情報を指定します。
+
+## `info.json` の形式
+
+`info.json` ファイルは設定可能な以下のキーを持つ JSON 形式の辞書です。全てを設定する必要はなく、キーボードに適用するキーだけを設定します。
+
+* `keyboard_name`
+   * キーボードを説明する自由形式のテキスト文字列。
+   * 例: `Clueboard 66%`
+* `url`
+   * キーボードの製品ページ、[QMK.fm/keyboards](https://qmk.fm/keyboards) のページ、あるいはキーボードに関する情報を説明する他のページの URL。
+* `maintainer`
+   * メンテナの GitHub のユーザ名、あるいはコミュニティが管理するキーボードの場合は `qmk`
+* `width`
+   * キー単位でのキーボードの幅
+* `height`
+   * キー単位でのキーボードの高さ
+* `layouts`
+   * 物理的なレイアウト表現。詳細は以下のセクションを見てください。
+
+### レイアウトの形式
+
+`info.json` ファイル内の辞書の `layouts` 部分は、幾つかの入れ子になった辞書を含みます。外側のレイヤーは QMK レイアウトマクロで構成されます。例えば、`LAYOUT_ansi` あるいは `LAYOUT_iso`。各レイアウトマクロ内には、`width`、 `height`、`key_count` のキーがあります。これらは自明でなければなりません。
+
+* `width`
+   * オプション: キー単位でのレイアウトの幅
+* `height`
+   * オプション: キー単位でのレイアウトの高さ
+* `key_count`
+   * **必須**: このレイアウトのキーの数
+* `layout`
+   * 物理レイアウトを説明するキー辞書のリスト。詳細は次のセクションを見てください。
+
+### キー辞書形式
+
+レイアウトの各キー辞書は、キーの物理プロパティを記述します。<http://keyboard-layout-editor.com> の Raw Code に精通している場合、多くの概念が同じであることが分かります。可能な限り同じキー名とレイアウトの選択を再利用しますが、keyboard-layout-editor とは異なって各キーはステートレスで、前のキーからプロパティを継承しません。
+
+全てのキーの位置と回転は、キーボードの左上と、各キーの左上を基準にして指定されます。
+
+* `x`
+   * **必須**: 水平軸でのキーの絶対位置(キー単位)。
+* `y`
+   * **必須**: 垂直軸でのキーの絶対位置(キー単位)。
+* `w`
+   * キー単位でのキーの幅。`ks` が指定された場合は無視されます。デフォルト: `1`
+* `h`
+   * キー単位でのキーの高さ。`ks` が指定された場合は無視されます。デフォルト: `1`
+* `r`
+   * キーを回転させる時計回りの角度。
+* `rx`
+   * キーを回転させる点の水平軸における絶対位置。デフォルト: `x`
+* `ry`
+   * キーを回転させる点の垂直軸における絶対位置。デフォルト: `y`
+* `ks`
+   * キー形状: キー単位で頂点を列挙することでポリゴンを定義します。
+   * **重要**: これらはキーの左上からの相対位置で、絶対位置ではありません。
+   * ISO Enter の例: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]`
+* `label`
+   * マトリックス内のこの位置につける名前。
+   * これは通常 PCB 上でこの位置にシルクスクリーン印刷されるものと同じ名前でなければなりません。
+
+## メタデータはどのように公開されますか？
+
+このメタデータは主に2つの方法で使われます:
+
+* Web ベースの configurator が動的に UI を生成できるようにする。
+* 新しい `make keyboard:keymap:qmk` ターゲットをサポートする。これは、このメタデータをファームウェアにバンドルして QMK Toolbox をよりスマートにします。
+
+Configurator の作成者は、JSON API の使用に関する詳細について、[QMK Compiler](https://docs.api.qmk.fm/using-the-api) ドキュメントを参照することができます。
diff --git a/docs/ja/serial_driver.md b/docs/ja/serial_driver.md
new file mode 100644
index 000000000..72071f4f7
--- /dev/null
+++ b/docs/ja/serial_driver.md
@@ -0,0 +1,75 @@
+# 'シリアル' ドライバ
+
+<!---
+  original document: 0.9.51:docs/serial_drive.md
+  git diff 0.9.51 HEAD -- docs/serial_drive.md | cat
+-->
+
+このドライバは[分割キーボード](ja/feature_split_keyboard.md) 機能に使います。
+
+?> この文章でのシリアルは、UART/USART/RS485/RS232 規格の実装ではなく、**一度に1ビットの情報を送信するもの**として読まれるべきです。
+
+このカテゴリの全てのドライバには以下の特徴があります:
+* 1本の線上でデータと信号を提供
+* シングルマスタ、シングルスレーブに限定
+
+## サポートされるドライバの種類
+
+|                   | AVR                | ARM                |
+|-------------------|--------------------|--------------------|
+| bit bang          | :heavy_check_mark: | :heavy_check_mark: |
+| USART Half-duplex |                    | :heavy_check_mark: |
+
+## ドライバ設定
+
+### Bitbang
+デフォルトのドライバ。設定がない場合はこのドライバが想定されます。設定するには、以下を rules.mk に追加します:
+
+```make
+SERIAL_DRIVER = bitbang
+```
+
+config.h を介してドライバを設定します:
+```c
+#define SOFT_SERIAL_PIN D0  // または D1, D2, D3, E6
+#define SELECT_SOFT_SERIAL_SPEED 1 // または 0, 2, 3, 4, 5
+                                   //  0: 約 189kbps (実験目的のみ)
+                                   //  1: 約 137kbps (デフォルト)
+                                   //  2: 約 75kbps
+                                   //  3: 約 39kbps
+                                   //  4: 約 26kbps
+                                   //  5: 約 20kbps
+```
+
+#### ARM
+
+!> bitbang ドライバは bitbang WS2812 ドライバと接続の問題があります
+
+上記の一般的なオプションに加えて、halconf.h で `PAL_USE_CALLBACKS` 機能もオンにする必要があります。
+
+### USART Half-duplex
+通信が USART ハードウェアデバイスに送信される STM32 ボードが対象です。これにより高速で正確なタイミングを提供できることが利点です。このドライバの `SOFT_SERIAL_PIN` は、設定された USART TX ピンです。**TX ピンに適切なプルアップ抵抗が必要です**。設定するには、以下を rules.mk に追加します:
+
+```make
+SERIAL_DRIVER = usart
+```
+
+config.h を介してハードウェアを設定します:
+```c
+#define SOFT_SERIAL_PIN B6  // USART TX ピン
+#define SELECT_SOFT_SERIAL_SPEED 1 // または 0, 2, 3, 4, 5
+                                   //  0: 約 460800 ボー
+                                   //  1: 約 230400 ボー (デフォルト)
+                                   //  2: 約 115200 ボー
+                                   //  3: 約 57600 ボー
+                                   //  4: 約 38400 ボー
+                                   //  5: 約 19200 ボー
+#define SERIAL_USART_DRIVER SD1 // TX ピンの USART ドライバ。デフォルトは SD1
+#define SERIAL_USART_TX_PAL_MODE 7 // 「代替機能」 ピン。MCU の適切な値については、それぞれのデータシートを見てください。デフォルトは 7
+```
+
+また、ChibiOS `SERIAL` 機能を有効にする必要があります:
+* キーボードの halconf.h: `#define HAL_USE_SERIAL TRUE`
+* キーボードの mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (ここで、'n' は MCU で選択した USART のペリフェラル番号と一致)
+
+必要な構成は、`UART` 周辺機器ではなく、`SERIAL` 周辺機器であることに注意してください。
diff --git a/docs/ja/support.md b/docs/ja/support.md
new file mode 100644
index 000000000..01c2d41d1
--- /dev/null
+++ b/docs/ja/support.md
@@ -0,0 +1,22 @@
+# 助けを得る
+
+<!---
+  original document: 0.9.51:docs/support.md
+  git diff 0.9.51 HEAD -- docs/support.md | cat
+-->
+
+QMK に関して助けを得るための多くのリソースがあります。
+
+コミュニティスペースに参加する前に[行動規範](https://qmk.fm/coc/)を読んでください。
+
+## リアルタイムチャット
+
+何かについて助けが必要な場合は、迅速なサポートを受けるための最良の場所は、[Discord Server](https://discord.gg/Uq7gcHh) です。通常は誰かがオンラインで、非常に助けになる多くの人がいます。
+
+## 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/syllabus.md b/docs/ja/syllabus.md
new file mode 100644
index 000000000..14e743ee9
--- /dev/null
+++ b/docs/ja/syllabus.md
@@ -0,0 +1,75 @@
+# QMK シラバス
+
+<!---
+  original document: 0.9.51:docs/syllabus.md
+  git diff 0.9.51 HEAD -- docs/syllabus.md | cat
+-->
+
+このページは最初に基本を紹介し、そして、QMK に習熟するために必要な全ての概念を理解するように導くことで、QMK の知識を構築するのに役立ちます。
+
+# 初級トピック
+
+他に何も読んでいない場合は、このセクションのドキュメントを読んでください。[QMK 初心者ガイド](ja/newbs.md)を読み終わると、基本的なキーマップを作成し、それをコンパイルし、キーボードに書き込みできるようになっているはずです。残りのドキュメントはこれらの基本的な知識を具体的に肉付けします。
+
+* **QMK Tools の使い方を学ぶ**
+   * [QMK 初心者ガイド](ja/newbs.md)
+   * [CLI](ja/cli.md)
+   * [Git](ja/newbs_git_best_practices.md)
+* **キーマップについて学ぶ**
+   * [レイヤー](ja/feature_layers.md)
+   * [キーコード](ja/keycodes.md)
+      * 使用できるキーコードの完全なリスト。中級または上級トピックにある知識が必要な場合もあることに注意してください。
+* **IDE の設定** - オプション
+   * [Eclipse](ja/other_eclipse.md)
+   * [VS Code](ja/other_vscode.md)
+
+# 中級トピック
+
+これらのトピックでは、QMK がサポートする幾つかの機能について掘り下げます。これらのドキュメントを全て読む必要はありませんが、これらの一部をスキップすると、上級トピックのセクションの一部のドキュメントが意味をなさなくなるかもしれません。
+
+* **機能の設定方法を学ぶ**
+   <!-- * Configuration Overview  FIXME(skullydazed/anyone): write this document -->
+   * [オーディオ](ja/feature_audio.md)
+   * 電飾
+      * [バックライト](ja/feature_backlight.md)
+      * [LED マトリックス](ja/feature_led_matrix.md)
+      * [RGB ライト](ja/feature_rgblight.md)
+      * [RGB マトリックス](ja/feature_rgb_matrix.md)
+   * [タップホールド設定](ja/tap_hold.md)
+* **キーマップについてさらに学ぶ**
+   * [キーマップ](ja/keymap.md)
+   * [カスタム関数とキーコード](ja/custom_quantum_functions.md)
+   * マクロ
+      * [動的マクロ](ja/feature_dynamic_macros.md)
+      * [コンパイル済みのマクロ](ja/feature_macros.md)
+   * [タップダンス](ja/feature_tap_dance.md)
+   * [コンボ](ja/feature_combo.md)
+   * [ユーザスペース](ja/feature_userspace.md)
+
+# 上級トピック
+
+以下の全ては多くの基礎知識を必要とします。高度な機能を使ってキーマップを作成できることに加えて、`config.h` と `rules.mk` の両方を使ってキーボードのオプションを設定することに慣れている必要があります。
+
+* **QMK 内のキーボードの保守**
+   * [キーボードの手配線](ja/hand_wire.md)
+   * [キーボードガイドライン](ja/hardware_keyboard_guidelines.md)
+   * [info.json リファレンス](ja/reference_info_json.md)
+   * [デバウンス API](ja/feature_debounce_type.md)
+* **高度な機能**
+   * [ユニコード](ja/feature_unicode.md)
+   * [API](ja/api_overview.md)
+   * [ブートマジック](ja/feature_bootmagic.md)
+* **ハードウェア**
+   * [キーボードがどのように動作するか](ja/how_keyboards_work.md)
+   * [キーボードマトリックスの仕組み](ja/how_a_matrix_works.md)
+   * [分割キーボード](ja/feature_split_keyboard.md)
+   * [速記](ja/feature_stenography.md)
+   * [ポインティングデバイス](ja/feature_pointing_device.md)
+* **コア開発**
+   * [コーディング規約](ja/coding_conventions_c.md)
+   * [互換性のあるマイクロコントローラ](ja/compatible_microcontrollers.md)
+   * [カスタムマトリックス](ja/custom_matrix.md)
+   * [QMK を理解する](ja/understanding_qmk.md)
+* **CLI 開発**
+   * [コーディング規約](ja/coding_conventions_python.md)
+   * [CLI 開発の概要](ja/cli_development.md)
diff --git a/docs/ja/translating.md b/docs/ja/translating.md
new file mode 100644
index 000000000..f7a273308
--- /dev/null
+++ b/docs/ja/translating.md
@@ -0,0 +1,60 @@
+# QMK ドキュメントを翻訳する
+
+<!---
+  original document: 0.9.51:docs/translating.md
+  git diff 0.9.51 HEAD -- docs/translating.md | cat
+-->
+
+ルートフォルダ (`docs/`) にある全てのファイルは英語でなければなりません - 他の全ての言語は、ISO 639-1 言語コードと、それに続く`-`と関連する国コードのサブフォルダにある必要があります。[一般的なもののリストはここで見つかります](https://www.andiamo.co.uk/resources/iso-language-codes/)。このフォルダが存在しない場合、作成することができます。翻訳された各ファイルは英語バージョンと同じ名前でなければなりません。そうすることで、正常にフォールバックできます。
+
+`_summary.md` ファイルはこのフォルダの中に存在し、各ファイルへのリンクのリスト、翻訳された名前、言語フォルダに続くリンクが含まれている必要があります。
+
+```markdown
+ * [QMK简介](zh-cn/getting_started_introduction.md)
+```
+
+他の docs ページへの全てのリンクにも、言語のフォルダが前に付いている必要があります。もしリンクがページの特定の部分(例えば、特定の見出し)への場合、以下のように見出しに英語の ID を使う必要があります:
+
+```markdown
+[建立你的环境](zh-cn/newbs-getting-started.md#set-up-your-environment)
+
+## 建立你的环境 :id=set-up-your-environment
+```
+
+新しい言語の翻訳が完了したら、以下のファイルも修正する必要があります:
+
+* [`docs/_langs.md`](https://github.com/qmk/qmk_firmware/blob/master/docs/_langs.md)
+各行は、[GitHub emoji shortcode](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md#country-flag) の形式で国フラグと、それに続く言語で表される名前を含む必要があります。
+
+  ```markdown
+   - [:cn: 中文](/zh-cn/)
+  ```
+
+* [`docs/index.html`](https://github.com/qmk/qmk_firmware/blob/master/docs/index.html)
+`placeholder` と `noData` の両方のオブジェクトは、文字列で言語フォルダの辞書エントリが必要です:
+
+  ```js
+  '/zh-cn/': '没有结果!',
+  ```
+
+   サイドバーの「QMK ファームウェア」の見出しリンクを設定するために、`nameLink` オブジェクトも以下のように追加される必要があります:
+
+  ```js
+  '/zh-cn/': '/#/zh-cn/',
+  ```
+
+   また、`fallbackLanguages` リストに言語フォルダを追加して、404 ではなく英語に適切にフォールバックするようにしてください:
+
+  ```js
+  fallbackLanguages: [
+    // ...
+    'zh-cn',
+    // ...
+  ],
+  ```
+
+## 翻訳のプレビュー
+
+ドキュメントのローカルインスタンスをセットアップする方法については、[ドキュメントのプレビュー](ja/contributing.md#previewing-the-documentation)を見てください - 右上の "Translations" メニューから新しい言語を選択することができるはずです。
+
+作業に満足したら、遠慮なくプルリクエストを開いてください！
diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md
index 8755552b9..22e8a3fe1 100644
--- a/docs/pr_checklist.md
+++ b/docs/pr_checklist.md
@@ -1,39 +1,42 @@
 # PR checklists
 
-This is a non-exhaustive checklist of what the QMK collaborators will be checking when reviewing submitted PRs.
+This is a non-exhaustive checklist of what the QMK Collaborators will be checking when reviewing submitted PRs.
 
-If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on Discord.
+If there are any inconsistencies with these recommendations, you're best off [creating an issue](https://github.com/qmk/qmk_firmware/issues/new) against this document, or getting in touch with a QMK Collaborator on [Discord](https://discord.gg/Uq7gcHh).
 
 ## General PRs
 
 - PR should be submitted using a non-`master` branch on the source repository
-    - This does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
-    - If submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message)
-- Newly-added directories and filenames must be lowercase
-    - This rule may be relaxed if upstream sources originally had uppercase characters (e.g. ChibiOS, or imported files from other repositories etc.)
-    - If there is enough justification (i.e. consistency with existing core files etc.) this can be relaxed
+    - this does not mean you target a different branch for your PR, rather that you're not working out of your own master branch
+    - if submitter _does_ use their own `master` branch, they'll be given a link to the ["how to git"](https://docs.qmk.fm/#/newbs_git_using_your_master_branch) page after merging -- (end of this document will contain the contents of the message)
+- newly-added directories and filenames must be lowercase
+    - this rule may be relaxed if upstream sources originally had uppercase characters (e.g. ChibiOS, or imported files from other repositories etc.)
+    - if there is enough justification (i.e. consistency with existing core files etc.) this can be relaxed
         - a board designer naming their keyboard with uppercase letters is not enough justification
-- Valid license headers on all `*.c` and `*.h` source files
+- valid license headers on all `*.c` and `*.h` source files
     - GPL2/GPL3 recommended for consistency
-    - Other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged.
-- QMK codebase "best practices" followed
-    - This is not an exhaustive list, and will likely get amended as time goes by
+    - other licenses are permitted, however they must be GPL-compatible and must allow for redistribution. Using a different license will almost certainly delay a PR getting merged.
+- QMK Codebase "best practices" followed
+    - this is not an exhaustive list, and will likely get amended as time goes by
     - `#pragma once` instead of `#ifndef` include guards in header files
-    - No "old-school" GPIO/I2C/SPI functions used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
-    - Timing abstractions should be followed too:
+    - no "old-school" GPIO/I2C/SPI functions used -- must use QMK abstractions unless justifiable (and laziness is not valid justification)
+    - timing abstractions should be followed too:
         - `wait_ms()` instead of `_delay_ms()` (remove `#include <util/delay.h>` too)
         - `timer_read()` and `timer_read32()` etc. -- see [timer.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/timer.h) for the timing APIs
-    - If you think a new abstraction is useful, you're encouraged to:
+    - if you think a new abstraction is useful, you're encouraged to:
         - prototype it in your own keyboard until it's feature-complete
         - discuss it with QMK Collaborators on Discord
         - refactor it as a separate core change
         - remove your specific copy in your board
+- rebase and fix all merge conflicts before opening the PR (in case you need help or advice, reach out to QMK Collaborators on Discord)
 
-## Core PRs
+## Keymap PRs
 
-- Must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
-- Other notes TBD
-    - Core is a lot more subjective given the breadth of posted changes
+- `#include QMK_KEYBOARD_H` preferred to including specific board files
+- prefer layer `enum`s to `#define`s
+- require custom keycode `enum`s to `#define`s, first entry must have ` = SAFE_RANGE`
+- terminating backslash (`\`) in lines of LAYOUT macro parameters is superfluous
+- some care with spacing (e.g., alignment on commas or first char of keycodes) makes for a much nicer-looking keymap
 
 ## Keyboard PRs
 
@@ -48,12 +51,14 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
     - standard template should be present
     - flash command has `:flash` at end
     - valid hardware availability link (unless handwired) -- private groupbuys are okay, but one-off prototypes will be questioned. If open-source, a link to files should be provided.
+    - clear instructions on how to reset the board into bootloader mode
+    - a picture about the keyboard and preferably about the PCB, too
 - `rules.mk`
     - removed `MIDI_ENABLE`, `FAUXCLICKY_ENABLE` and `HD44780_ENABLE`
     - modified `# Enable Bluetooth with the Adafruit EZ-Key HID` -> `# Enable Bluetooth`
-    - No `(-/+size)` comments related to enabling features
-    - Remove the list of alternate bootloaders if one has been specified
-    - No re-definitions of the default MCU parameters if same value, when compared to the equivalent MCU in [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/quantum/mcu_selection.mk)
+    - no `(-/+size)` comments related to enabling features
+    - remove the list of alternate bootloaders if one has been specified
+    - no re-definitions of the default MCU parameters if same value, when compared to the equivalent MCU in [mcu_selection.mk](https://github.com/qmk/qmk_firmware/blob/master/quantum/mcu_selection.mk)
 - keyboard `config.h`
     - don't repeat `MANUFACTURER` in the `PRODUCT` value
     - no `#define DESCRIPTION`
@@ -71,12 +76,12 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
 - `keyboard.h`
     - `#include "quantum.h"` appears at the top
     - `LAYOUT` macros should use standard definitions if applicable
-        - Use the Community Layout macro names where they apply (preferred above `LAYOUT`/`LAYOUT_all`)
+        - use the Community Layout macro names where they apply (preferred above `LAYOUT`/`LAYOUT_all`)
 - keymap `config.h`
     - no duplication of `rules.mk` or `config.h` from keyboard
 - `keymaps/default/keymap.c`
     - `QMKBEST`/`QMKURL` removed (sheesh)
-    - If using `MO(_LOWER)` and `MO(_RAISE)` keycodes or equivalent, and the keymap has an adjust layer when holding both keys -- if the keymap has no "direct-to-adjust" keycode (such as `MO(_ADJUST)`) then you should prefer to write...
+    - if using `MO(_LOWER)` and `MO(_RAISE)` keycodes or equivalent, and the keymap has an adjust layer when holding both keys -- if the keymap has no "direct-to-adjust" keycode (such as `MO(_ADJUST)`) then you should prefer to write...
         ```
         layer_state_t layer_state_set_user(layer_state_t state) {
           return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST);
@@ -90,22 +95,20 @@ https://github.com/qmk/qmk_firmware/pulls?q=is%3Apr+is%3Aclosed+label%3Akeyboard
 - submitters can also have a "manufacturer-matching" keymap that mirrors existing functionality of the commercial product, if porting an existing board
 
 Also, specific to ChibiOS:
-- **Strong** preference to using existing ChibiOS board definitions.
-    - A lot of the time, an equivalent Nucleo board can be used with a different flash size or slightly different model in the same family
-        - Example: For an STM32L082KZ, given the similarity to an STM32L073RZ, you can use `BOARD = ST_NUCLEO64_L073RZ` in rules.mk
+- **strong** preference to using existing ChibiOS board definitions.
+    - a lot of the time, an equivalent Nucleo board can be used with a different flash size or slightly different model in the same family
+        - example: For an STM32L082KZ, given the similarity to an STM32L073RZ, you can use `BOARD = ST_NUCLEO64_L073RZ` in rules.mk
     - QMK is migrating to not having custom board definitions if at all possible, due to the ongoing maintenance burden when upgrading ChibiOS
-- If a board definition is unavoidable, `board.c` must have a standard `__early_init()` (as per normal ChibiOS board defs) and an empty `boardInit()`:
+- if a board definition is unavoidable, `board.c` must have a standard `__early_init()` (as per normal ChibiOS board defs) and an empty `boardInit()`:
     - see Arm/ChibiOS [early initialization](https://docs.qmk.fm/#/platformdev_chibios_earlyinit?id=board-init)
     - `__early_init()` should be replaced by either `early_hardware_init_pre()` or `early_hardware_init_post()` as appropriate
     - `boardInit()` should be migrated to `board_init()`
 
-## Keymap PRs
+## Core PRs
 
-- `#include QMK_KEYBOARD_H` preferred to including specific board files
-- Prefer layer `enum`s to `#define`s
-- Require custom keycode `enum`s to `#define`s, first entry must have ` = SAFE_RANGE`
-- Terminating backslash (`\`) in lines of LAYOUT macro parameters is superfluous
-- Some care with spacing (e.g., alignment on commas or first char of keycodes) makes for a much nicer-looking keymap
+- must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline
+- other notes TBD
+    - core is a lot more subjective given the breadth of posted changes
 
 ---