[Docs] add japanese translation (detail guide part) (#7722)

* add detail-guide part

* some updates for easy reading

* some updates for easy reading

* some updates for easy reading

* some updates for easy reading

* some updates for easy reading

* some updates for easy reading

* some updates for easy reading

* some updates for easy reading

* update file based on comment

* update file based on comment

* update file based on comment

* update git command in header

* update files based on comments, and update git command in header

* update file based on comment

* update file based on comment

* update file based on comment

* update file based on comment

* update file based on comment

* update file based on comment

* update file based on comment

* update file based on comment

Co-Authored-By: shela <shelaf@users.noreply.github.com>
Co-Authored-By: Takeshi ISHII <2170248+mtei@users.noreply.github.com>

6 files changed, 1300 insertions, 0 deletions

diff --git a/docs/ja/custom_quantum_functions.md b/docs/ja/custom_quantum_functions.md
new file mode 100644
index 000000000..f49df8f65
--- /dev/null
+++ b/docs/ja/custom_quantum_functions.md
@@ -0,0 +1,518 @@
+# キーボードの挙動をカスタマイズする方法
+
+<!---
+  original document: 7494490d6:docs/custom_quantum_functions.md
+  git diff 7494490d6 HEAD -- docs/custom_quantum_functions.md | cat
+-->
+
+多くの人にとって、カスタムキーボードはボタンの押下をコンピュータに送信するだけではありません。単純なボタンの押下やマクロよりも複雑なことを実行できるようにしたいでしょう。QMK にはコードを挿入したり、機能を上書きしたり、様々な状況でキーボードの挙動をカスタマイズできるフックがあります。
+
+このページでは、QMK に関する特別な知識は想定していませんが、[QMK の理解](ja/understanding_qmk.md)を読むとより根本的なレベルで何が起きているかを理解するのに役立ちます。
+
+## コア、キーボード、キーマップ階層 :id=a-word-on-core-vs-keyboards-vs-keymap
+
+私たちは QMK を階層として構造化しました:
+
+* コア (`_quantum`)
+   * キーボード/リビジョン (`_kb`)
+      * キーマップ (`_user`)
+
+以下で説明される各関数は `_kb()` サフィックスあるいは `_user()` サフィックスを使って定義することができます。`_kb()` サフィックスはキーボード/リビジョンレベルで使うことを意図しており、一方で `_user()` サフィックスはキーマップレベルで使われるべきです。
+
+キーボード/リビジョンレベルで関数を定義する場合、`_kb()` は他の何かを実行する前に `_user()` を呼び出すよう実装することが重要です。そうでなければ、キーマップレベル関数は呼ばれないでしょう。
+
+# カスタムキーコード
+
+最も一般的なタスクは、既存のキーコードの挙動を変更するか、新しいキーコードを作成することです。コードの観点からは、それぞれの仕組みは非常に似ています。
+
+## 新しいキーコードの定義
+
+独自のカスタムキーコードを作成する最初のステップは、それらを列挙することです。これは、カスタムキーコードに名前を付け、そのキーコードにユニークな番号を割り当てることの両方を意味します。QMK は、カスタムキーコードを固定範囲の番号に制限するのではなく、`SAFE_RANGE` マクロを提供します。カスタムキーコードを列挙する時に `SAFE_RANGE` を使うと、ユニークな番号を取得することが保証されます。
+
+
+これは2つのキーコードを列挙する例です。このブロックを `keymap.c` に追加した後で、キーマップの中で `FOO` と `BAR` を使うことができます。
+
+```c
+enum my_keycodes {
+  FOO = SAFE_RANGE,
+  BAR
+};
+```
+
+## 任意のキーコードの挙動のプログラミング
+
+既存のキーの挙動を上書きしたい場合、あるいは新しいキーについて挙動を定義する場合、`process_record_kb()` および `process_record_user()` 関数を使うべきです。これらは実際のキーイベントが処理される前のキー処理中に QMK によって呼び出されます。これらの関数が `true` を返す場合、QMK はキーコードを通常通りに処理します。これは、キーを置き換えるのではなく、キーの機能を拡張するのに便利です。これらの関数が `false` を返す場合、QMK は通常のキー処理をスキップし、必要なキーのアップまたはダウンイベントを送信するのかはユーザ次第です。
+
+これらの関数はキーが押されるか放されるたびに呼び出されます。
+
+### `process_record_user()` の実装例
+
+この例は2つの事を行います。`FOO` と呼ばれるカスタムキーコードの挙動を定義し、Enter キーが押されるたびに音を再生します。
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // 押された時に何かをします
+      } else {
+        // 放された時に何かをします
+      }
+      return false; // このキーの以降の処理をスキップします
+    case KC_ENTER:
+      // enter が押された時に音を再生します
+      if (record->event.pressed) {
+        PLAY_NOTE_ARRAY(tone_qwerty);
+      }
+      return true; // QMK に enter のプレスまたはリリースイベントを送信させます
+    default:
+      return true; // 他の全てのキーコードを通常通りに処理します
+  }
+}
+```
+
+### `process_record_*` 関数のドキュメント
+
+* キーボード/リビジョン: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
+* キーマップ: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
+
+`keycode` 引数はキーマップで定義されているものです。例えば `MO(1)`、`KC_L` など。これらのイベントを処理するには `switch...case` ブロックを使うべきです。
+
+`record` 引数は実際のプレスに関する情報を含みます:
+
+```c
+keyrecord_t record {
+  keyevent_t event {
+    keypos_t key {
+      uint8_t col
+      uint8_t row
+    }
+    bool     pressed
+    uint16_t time
+  }
+}
+```
+
+# LED 制御
+
+QMK は HID 仕様で定義された5つの LED の読み取りメソッドを提供します:
+
+* Num Lock
+* Caps Lock
+* Scroll Lock
+* Compose
+* Kana
+
+ロック LED の状態を取得するには2つの方法があります:
+
+* `bool led_update_kb(led_t led_state)` あるいは `_user(led_t led_state)` を実装する、または
+* `led_t host_keyboard_led_state()` を呼び出す
+
+!> `host_keyboard_led_state()` は `led_update_user()` が呼ばれる前に新しい値を既に反映している場合があります。
+
+LED の状態を `uint8_t` として提供する2つの非推奨の関数があります:
+
+* `uint8_t led_set_kb(uint8_t usb_led)` と `_user(uint8_t usb_led)`
+* `uint8_t host_keyboard_leds()`
+
+## `led_update_user()`
+
+この関数はこれら5つの LED のいずれかの状態が変化すると呼ばれます。LED の状態を構造体のパラメータとして受け取ります。
+
+慣例により、`led_update_kb()` にそのコードを実行するようフックさせるために `led_update_user()` から `true` を返し、`led_update_kb()` でコードを実行したくない場合は `false` を返します。
+
+以下はいくつかの例です:
+
+- レイヤー表示のような何かのために LED を使うために LED を上書きする
+   - `_kb()` 関数を実行したくないので、`false`  を返します。これはレイヤーの挙動を上書きするためです。
+- LED がオンあるいはオフになった時に音楽を再生する。
+   - `_kb` 関数を実行したいので、`true` を返します。これはデフォルトの LED の挙動に追加されます。
+
+?> `led_set_*` 関数は `bool` の代わりに `void` を返すため、キーボードの LED 制御を上書きすることができません。従って、代わりに `led_update_*` を使うことをお勧めします。
+
+### `led_update_kb()` の実装例
+
+```c
+bool led_update_kb(led_t led_state) {
+    bool res = led_update_user(led_state);
+    if(res) {
+        // writePin は 1 でピンを high に、0 で low に設定します。
+        // この例では、ピンは反転していて、
+        // low/0 は LED がオンになり、high/1 は LED がオフになります。
+        // この挙動は、LED がピンと VCC の間にあるか、ピンと GND の間にあるかどうかに依存します。
+        writePin(B0, !led_state.num_lock);
+        writePin(B1, !led_state.caps_lock);
+        writePin(B2, !led_state.scroll_lock);
+        writePin(B3, !led_state.compose);
+        writePin(B4, !led_state.kana);
+    }
+    return res;
+}
+```
+
+### `led_update_user()` の実装例
+
+この不完全な例は Caps Lock がオンまたはオフになった場合に音を再生します。また LED の状態を保持する必要があるため、`true` を返します。
+
+```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) {
+    #ifdef AUDIO_ENABLE
+    static uint8_t caps_state = 0;
+    if (caps_state != led_state.caps_lock) {
+        led_state.caps_lock ? PLAY_SONG(caps_on) : PLAY_SONG(caps_off);
+        caps_state = led_state.caps_lock;
+    }
+    #endif
+    return true;
+}
+```
+
+### `led_update_*` 関数のドキュメント
+
+* キーボード/リビジョン: `bool led_update_kb(led_t led_state)`
+* キーマップ: `bool led_update_user(led_t led_state)`
+
+## `host_keyboard_led_state()`
+
+最後に受信した LED の状態を `led_t` として取得するためにこの関数を呼びます。これは、`led_update_*` の外部から、例えば [`matrix_scan_user()`](#matrix-scanning-code) の中で LED の状態を読み取るのに便利です。
+
+## 物理的な LED の状態の設定
+
+一部のキーボードの実装は、物理的な LED の状態を設定するための便利なメソッドを提供しています。
+
+### Ergodox キーボード
+
+Ergodox の実装は、個々の LED をオンあるいはオフにするために `ergodox_right_led_1`/`2`/`3_on`/`off()` と、インデックスによってそれらをオンあるいはオフにするために `ergodox_right_led_on`/`off(uint8_t led)` を提供します。
+
+さらに、LED の明度を指定することができます。全ての LED に同じ明度を指定するなら `ergodox_led_all_set(uint8_t n)` を使い、個別の LED の明度を指定するなら `ergodox_right_led_1`/`2`/`3_set(uint8_t n)` を使い、LED のインデックスを指定して明度を指定するには  `ergodox_right_led_set(uint8_t led, uint8_t n)` を使います。
+
+Ergodox キーボードは、最低の明度として `LED_BRIGHTNESS_LO` を、最高の輝度(これはデフォルトです)として `LED_BRIGHTNESS_HI` も定義しています。
+
+# キーボードの初期化コード
+
+キーボードの初期化プロセスには幾つかのステップがあります。何をしたいかによって、どの関数を使うべきかに影響します。
+
+3つの主な初期化関数があり、呼び出される順番にリストされています。
+
+* `keyboard_pre_init_*` - ほとんどのものが開始される前に起こります。非常に早くに実行したいハードウェアのセットアップに適しています。
+* `matrix_init_*` - ファームウェアのスタートアッププロセスの途中で起こります。ハードウェアは初期化されますが、機能はまだ初期化されていない場合があります。
+* `keyboard_post_init_*` - ファームウェアのスタートアッププロセスの最後に起こります。これはほとんどの場合、 "カスタマイズ"コードを配置する場所です。
+
+!> ほとんどの人にとって、`keyboard_post_init_user` が呼び出したいものです。例えば、ここで RGB アンダーグローのセットアップを行います。
+
+## キーボードの事前初期化コード
+
+これは USB さえ起動する前の、起動中の非常に早い段階で実行されます。
+
+この直後にマトリックスが初期化されます。
+
+これは主にハードウェア向きの初期化のためであるため、ほとんどのユーザは使うべきではありません。
+
+ただし、初期化が必要なハードウェアがある場合には、これが最適な場所です (LED ピンの初期化など)。
+
+### `keyboard_pre_init_user()` の実装例
+
+この例は、キーボードレベルで、LED ピンとして B0、B1、B2、B3 および B4 をセットアップします。
+
+```c
+void keyboard_pre_init_user(void) {
+  // キーボードの事前初期コードを呼び出します。
+
+  // LED ピンを出力として設定します
+  setPinOutput(B0);
+  setPinOutput(B1);
+  setPinOutput(B2);
+  setPinOutput(B3);
+  setPinOutput(B4);
+}
+```
+
+### `keyboard_pre_init_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void keyboard_pre_init_kb(void)`
+* キーマップ: `void keyboard_pre_init_user(void)`
+
+## マトリックスの初期化コード
+
+これは、マトリックスが初期化され、ハードウェアの一部がセットアップされた後で、ただし機能の多くが初期化される前に、呼び出されます。
+
+他の場所で必要になるかもしれないものをセットアップするのに役立ちますが、ハードウェアに関連するものではなく、開始場所に依存するものでもありません。
+
+
+### `matrix_init_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void matrix_init_kb(void)`
+* キーマップ: `void matrix_init_user(void)`
+
+
+## キーボードの事後初期化コード
+
+キーボードの初期化プロセスの極めて最後のタスクとして実行されます。この時点で初期化される必要があるような、特定の機能を変更したい場合に便利です。
+
+
+### `keyboard_post_init_user()` の実装例
+
+この例は、他の全てのものが初期化された後で実行され、rgb アンダーグローの設定をセットアップします。
+
+```c
+void keyboard_post_init_user(void) {
+  // post init コードを呼びます
+  rgblight_enable_noeeprom(); // 設定を保存せずに Rgb を有効にします
+  rgblight_sethsv_noeeprom(180, 255, 255); // 保存せずに色を青緑/シアンに設定します
+  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // 保存せずにモードを高速なブリージングに設定します
+}
+```
+
+### `keyboard_post_init_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void keyboard_post_init_kb(void)`
+* キーマップ: `void keyboard_post_init_user(void)`
+
+# マトリックススキャンコード :id=matrix-scanning-code
+
+可能であれば常に `process_record_*()` を使ってキーボードをカスタマイズし、その方法でイベントをフックし、コードがキーボードのパフォーマンスに悪影響を与えないようにします。ただし、まれにマトリックススキャンにフックする必要があります。これらの関数は1秒あたり少なくとも10回は呼び出されるため、これらの関数のコードのパフォーマンスに非常に注意してください。
+
+### `matrix_scan_*` の実装例
+
+この例は意図的に省略されています。このようなパフォーマンスに敏感な領域にフックする前に、例を使わずにこれを書くために、QMK 内部について十分理解する必要があります。助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues/new) か [Discord で会話](https://discord.gg/Uq7gcHh)してください。
+
+### `matrix_scan_*` 関数のドキュメント
+
+* キーボード/リビジョン: `void matrix_scan_kb(void)`
+* キーマップ: `void matrix_scan_user(void)`
+
+この関数はマトリックススキャンのたびに呼び出されます。これは基本的に MCU が処理できる頻度です。大量に実行されるため、ここに何を置くかについては注意してください。
+
+カスタムマトリックススキャンコードが必要な場合は、この関数を使う必要があります。また、カスタムステータス出力 (LED あるいはディスプレイなど)や、ユーザが入力していない場合でも定期的にトリガーするその他の機能のために使うことができます。
+
+
+# キーボードアイドリング/ウェイクコード
+
+キーボードがサポートしている場合、多くの機能を停止することで"アイドル"にすることができます。これの良い例は、RGB ライトあるいはバックライトです。これにより、電力消費を節約できるか、キーボードの動作が改善されるかもしれません。
+
+これは2つの関数によって制御されます: `suspend_power_down_*` および `suspend_wakeup_init_*`。これらはシステムキーボードがアイドルになった時と、起動した時のそれぞれで呼ばれます。
+
+
+### suspend_power_down_user() と suspend_wakeup_init_user() の実装例
+
+
+```c
+void suspend_power_down_user(void) {
+    rgb_matrix_set_suspend_state(true);
+}
+
+void suspend_wakeup_init_user(void) {
+    rgb_matrix_set_suspend_state(false);
+}
+```
+
+### キーボードサスペンド/ウェイク関数のドキュメント
+
+* キーボード/リビジョン : `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_*` の実装例
+
+この例は、レイヤーに基づいて [RGB アンダーグロー](ja/feature_rgblight.md)を設定する方法を示していて、Planck を例として使っています。
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+    case _RAISE:
+        rgblight_setrgb (0x00,  0x00, 0xFF);
+        break;
+    case _LOWER:
+        rgblight_setrgb (0xFF,  0x00, 0x00);
+        break;
+    case _PLOVER:
+        rgblight_setrgb (0x00,  0xFF, 0x00);
+        break;
+    case _ADJUST:
+        rgblight_setrgb (0x7A,  0x00, 0xFF);
+        break;
+    default: //  他の全てのレイヤーあるいはデフォルトのレイヤー
+        rgblight_setrgb (0x00,  0xFF, 0xFF);
+        break;
+    }
+  return state;
+}
+```
+### `layer_state_set_*` 関数のドキュメント
+
+* キーボード/リビジョン: `layer_state_t layer_state_set_kb(layer_state_t state)`
+* キーマップ: `layer_state_t layer_state_set_user(layer_state_t state)`
+
+
+[キーマップの概要](ja/keymap.md#keymap-layer-status)で説明されるように、`state` はアクティブなレイヤーのビットマスクです。
+
+
+# 永続的な設定 (EEPROM)
+
+これによりキーボードのための永続的な設定を設定することができます。これらの設定はコントローラの EEPROM に保存され、電源が落ちた後であっても保持されます。設定は `eeconfig_read_kb` および `eeconfig_read_user` を使って読み取ることができ、`eeconfig_update_kb` および `eeconfig_update_user` を使って書きこむことができます。これは切り替え可能な機能 (rgb レイヤーの表示の切り替えなど)に役立ちます。さらに、`eeconfig_init_kb` および `eeconfig_init_user` を使って EEPROM のデフォルト値を設定できます。
+
+ここでの複雑な部分は、EEPROM を介してデータを保存およびアクセスできる方法がたくさんあり、これを行うための"正しい"方法が無いということです。ただし、各関数には DWORD (4 バイト)しかありません。
+
+EEPROM の書き込み回数には制限があることに注意してください。これは非常に高い値ですが、EEPROM に書き込むのはこれだけではなく、もし頻繁に書き込むと、MCU の寿命を大幅に短くする可能性があります。
+
+* この例を理解していない場合は、この機能はかなり複雑なため、この機能を使うことを避けても構いません。
+
+### 実装例
+
+これは、設定を追加し、読み書きする例です。この例では、ユーザキーマップを使っています。これは複雑な機能で、多くのことが行われています。実際、動作のために上記の多くの関数を使います！
+
+
+keymap.c ファイルの中で、先頭にこれを追加します:
+```c
+typedef union {
+  uint32_t raw;
+  struct {
+    bool     rgb_layer_change :1;
+  };
+} user_config_t;
+
+user_config_t user_config;
+```
+
+これは、設定をメモリ内に保存し、EEPROM に書き込むことができる32ビット構造体をセットアップします。これを使うと、この構造体に変数が定義されるため、変数を定義する必要が無くなります。`bool` (boolean) の値は1ビットを使い、`uint8_t` は8ビットを使い、`uint16_t` は16ビットを使うことに注意してください。組み合わせて使うことができますが、順番の変更は読み書きされる値が変更されるため、問題が発生するかもしれません。
+
+`layer_state_set_*` 関数のために `rgb_layer_change` を使い、全てを設定するために `keyboard_post_init_user` および `process_record_user` を使います。
+
+ここで、上の `keyboard_post_init_user` コードを使って、作成したばかりの構造体を設定するために `eeconfig_read_user()` を追加します。そして、この構造体をすぐに使ってキーマップの機能を制御することができます。それは以下のようになります:
+```c
+void keyboard_post_init_user(void) {
+  // キーマップレベルのマトリックスの初期化処理を呼びます
+
+  // EEPROM からユーザ設定を読み込みます
+  user_config.raw = eeconfig_read_user();
+
+  // 有効な場合はデフォルトレイヤーを設定します
+  if (user_config.rgb_layer_change) {
+    rgblight_enable_noeeprom();
+    rgblight_sethsv_noeeprom_cyan();
+    rgblight_mode_noeeprom(1);
+  }
+}
+```
+上記の関数は読み取ったばかりの EEPROM 設定を使い、デフォルトのレイヤーの RGB 色を設定します。その「生の」値は、上で作成した「共用体」に基づいて使用可能な構造に変換されます。
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+    switch (get_highest_layer(state)) {
+    case _RAISE:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); }
+        break;
+    case _LOWER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); }
+        break;
+    case _PLOVER:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); }
+        break;
+    case _ADJUST:
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); }
+        break;
+    default: //  他の全てのレイヤーあるいはデフォルトのレイヤー
+        if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); }
+        break;
+    }
+  return state;
+}
+```
+これにより、値が有効になっていた場合のみ、RGB アンダーグローが変更されます。この値を設定するために、`RGB_LYR` と呼ばれる `process_record_user` 用の新しいキーコードを作成します。さらに、通常の RGB コードを使う場合、上記の例を使ってオフになることを確認します。以下のようになります:
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      if (record->event.pressed) {
+        // 押された時に何かをします
+      } else {
+        // 放された時に何かをします
+      }
+      return false; // このキーの以降の処理をスキップします
+    case KC_ENTER:
+        // enter が押された時に音を再生します
+        if (record->event.pressed) {
+            PLAY_NOTE_ARRAY(tone_qwerty);
+        }
+        return true; // QMK に enter のプレスまたはリリースイベントを送信させます
+    case RGB_LYR:  // これにより、アンダーグローをレイヤー表示として、あるいは通常通りに使うことができます。
+        if (record->event.pressed) {
+            user_config.rgb_layer_change ^= 1; // 状態を切り替えます
+            eeconfig_update_user(user_config.raw); // 新しい状態を EEPROM に書き込みます
+            if (user_config.rgb_layer_change) { // レイヤーの状態表示が有効な場合
+                layer_state_set(layer_state);   // すぐにレイヤーの色を更新します
+            }
+        }
+        return false; break;
+    case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // 任意の RGB コード に対して(quantum_keycodes.h を見てください。400行目参照)
+        if (record->event.pressed) { // これはレイヤー表示を無効にします。これを変更する場合は、無効にしたいだろうため。
+            if (user_config.rgb_layer_change) {        // 有効な場合のみ
+                user_config.rgb_layer_change = false;  // 無効にします
+                eeconfig_update_user(user_config.raw); // 設定を EEPROM に書き込みます
+            }
+        }
+        return true; break;
+    default:
+      return true; // 他の全てのキーコードを通常通りに処理します
+  }
+}
+```
+最後に、`eeconfig_init_user` 関数を追加して、EEPROM がリセットされた時にデフォルト値、さらにはカスタムアクションを指定できるようにします。EEPROM を強制的にリセットするには、`EEP_RST` キーコードあるいは[ブートマジック](ja/feature_bootmagic.md)機能を使います。例えば、デフォルトで rgb レイヤー表示を設定し、デフォルト値を保存したい場合。
+
+```c
+void eeconfig_init_user(void) {  // EEPROM がリセットされます！
+  user_config.raw = 0;
+  user_config.rgb_layer_change = true; // デフォルトでこれを有効にします
+  eeconfig_update_user(user_config.raw); // デフォルト値を EEPROM に書き込みます
+
+  // これらの値も EEPROM に書き込むためには、noeeprom 以外のバージョンを使います
+  rgblight_enable(); // デフォルトで RGB を有効にします
+  rgblight_sethsv_cyan();  // デフォルトでシアンに設定します
+  rgblight_mode(1); // デフォルトでソリッドに設定します
+}
+```
+
+これで完了です。RGB レイヤー表示は必要な場合にのみ機能します。キーボードを取り外した後でも保存されます。RGB コードのいずれかを使うと、レイヤー表示が無効になり、設定したモードと色がそのままになります。
+
+### 'EECONFIG' 関数のドキュメント
+
+* キーボード/リビジョン: `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)`
+
+`val` は EEPROM に書き込みたいデータの値です。`eeconfig_read_*` 関数は EEPROM から32ビット(DWORD) 値を返します。
+
+# カスタムタッピング期間
+
+デフォルトでは、タッピング期間はグローバルに設定されていて、キーでは設定することができません。ほとんどのユーザにとって、これは全然問題ありません。しかし、場合によっては、`LT` キーとは異なるタイムアウトによって、デュアルファンクションキーが大幅に改善されます。なぜなら、一部のキーは他のキーよりも押し続けやすいためです。それぞれにカスタムキーコードを使う代わりに、キーごとに設定可能な `TAPPING_TERM` を使用できます。
+
+この機能を有効にするには、最初に `config.h` に `#define TAPPING_TERM_PER_KEY` を追加する必要があります。
+
+
+## `get_tapping_term` の実装例
+
+キーコードに基づいて `TAPPING TERM` を変更するには、次のようなものを `keymap.c` ファイルに追加します:
+
+```c
+uint16_t get_tapping_term(uint16_t keycode) {
+  switch (keycode) {
+    case SFT_T(KC_SPC):
+      return TAPPING_TERM + 1250;
+    case LT(1, KC_GRV):
+      return 130;
+    default:
+      return TAPPING_TERM;
+  }
+}
+```
+
+### `get_tapping_term` 関数のドキュメント
+
+ここにある他の多くの関数とは異なり、quantum あるいはキーボードレベルの関数を持つ必要はありません (または理由さえありません)。ここではユーザレベルの関数だけが有用なため、そのようにマークする必要はありません。
diff --git a/docs/ja/flashing.md b/docs/ja/flashing.md
new file mode 100644
index 000000000..1118fb5e2
--- /dev/null
+++ b/docs/ja/flashing.md
@@ -0,0 +1,247 @@
+# 書き込みの手順とブートローダ情報
+
+<!---
+  original document: 7494490d6:docs/flashing.md
+  git diff 7494490d6 HEAD -- docs/flashing.md | cat
+-->
+
+キーボードが使用するブートローダにはかなり多くの種類があり、ほぼ全てが異なる書き込みの方法を使います。幸いなことに、[QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) のようなプロジェクトは、あまり深く考える必要無しに様々なタイプと互換性を持つことを目指していますが、この文章では様々なタイプのブートローダとそれらを書き込むために利用可能な方法について説明します。
+
+`rules.mk` の `BOOTLOADER` 変数で選択されたブートローダがある場合、QMK は .hex ファイルがデバイスに書き込むのに適切なサイズかどうかを自動的に計算し、合計サイズをバイト単位で(最大値とともに)出力します。この処理を手動で実行するには、`check-size` を付けてコンパイルします。例えば、`make planck/rev4:default:check-size`。
+
+## DFU
+
+Atmel の DFU ブートローダはデフォルトで全ての atmega32u4 チップに搭載されており、PCB (旧 OLKB キーボード、Clueboard) に独自の IC を持つ多くのキーボードで使われています。一部のキーボードは、LUFA の DFU ブートローダ(または QMK のフォーク) (新しい OLKB キーボード)を使う場合もあり、そのハードウェアに固有の追加機能が追加されます。
+
+DFU ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください(オプションとして代わりに `lufa-dfu` や `qmk-dfu` が使えます):
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = atmel-dfu
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* QMK の [dfu-programmer](https://github.com/dfu-programmer/dfu-programmer) / `:dfu` (推奨のコマンドライン)
+* [Atmel の Flip](http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip) (非推奨)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RESET ボタンをタップします(または RST を GND にショートします)。
+2. OS がデバイスを検知するのを待ちます。
+3. メモリを消去します(自動的に実行されるかもしれません)
+4. .hex ファイルを書き込みます
+5. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+あるいは:
+
+    make <keyboard>:<keymap>:dfu
+
+### QMK DFU
+
+QMK には LUFA DFU ブートローダのフォークがあり、ブートローダを終了してアプリケーションに戻る時に単純なマトリックススキャンを行うことができます。また、何かが起きた時に、LED を点滅したり、スピーカーでカチカチ音をたてたりします。これらの機能を有効にするには、`config.h` で以下のブロックを有効にします (ブートローダを終了するキーは、ここで定義された INPUT と OUTPUT に接続する必要があります):
+
+    #define QMK_ESC_OUTPUT F1 // 通常 COL
+    #define QMK_ESC_INPUT D5 // 通常 ROW
+    #define QMK_LED E6
+    #define QMK_SPEAKER C6
+
+製造元と製品名は `config.h` から自動的に取得され、製品に「Bootloader」が追加されます。
+
+このブートローダを生成するには、`bootloader` ターゲット、例えば `make planck/rev4:default:bootloader` を使います。
+
+実稼働対応の .hex ファイル(アプリケーションおよびブートローダを含む)を生成するには、`production` ターゲット、例えば `make planck/rev4:default:production` を使います。
+
+### DFU コマンド
+
+ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:dfu` - これが通常のオプションで、DFU デバイスが使用可能になるまで待機したのちファームウェアを書き込みます。5秒ごとに、DFU デバイスが存在するかチェックしています。
+* `:dfu-ee` - 通常の hex ファイルの代わりに `eep` ファイルを書き込みます。これを使用するのはまれです。
+* `:dfu-split-left` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
+* `:dfu-split-right` - デフォルトオプション (`:dfu`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Elite C ベースの分割キーボードに最適です。_
+
+## Caterina
+
+Arduino ボードとそのクローンは [Caterina ブートローダ](https://github.com/arduino/ArduinoCore-avr/tree/master/bootloaders/caterina) (Pro Micro またはそのクローンで構築されたキーボード)を使用し、avr109 プロトコルを使って仮想シリアルを介して通信します。[A-Star](https://www.pololu.com/docs/0J61/9) のようなブートローダは Caterina に基づいています。
+
+Caterina ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = caterina
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* avr109 を使った [avrdude](http://www.nongnu.org/avrdude/) / `:avrdude` (推奨のコマンドライン)
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます)
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスが自動的にリセットされるのを待ちます
+
+あるいは
+
+    make <keyboard>:<keymap>:avrdude
+
+
+#### Caterina コマンド
+
+ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。
+* `:avrdude-loop` - これは `:avrdude` と同じコマンドを実行します。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへ書き込むのに便利です。_Ctrl+C を押して、手動でこの繰り返しを終了させる必要があります。_
+* `:avrdude-split-left` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_
+* `:avrdude-split-right` - デフォルトオプション (`:avrdude`) と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM ファイルも書き込まれます。_これは、Pro Micro ベースの分割キーボードに最適です。_
+
+
+
+## Halfkay
+
+Halfkay は PJRC によって開発された超スリムなプロトコルであり、HID を使用し、全ての Teensys (つまり 2.0)に搭載されています。
+
+Halfkay ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = halfkay
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html)
+* [Teensy ローダーコマンドライン](https://www.pjrc.com/teensy/loader_cli.html) (推奨のコマンドライン)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RST をすばやく GND にショートします (入力後7秒で書き込みます)
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+## USBasploader
+
+USBasploader は matrixstorm によって開発されたブートローダです。V-USB を実行する ATmega328P のような非 USB AVR チップで使われます。
+
+USBasploader ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = USBasp
+```
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* `usbasp` プログラマを使った [avrdude](http://www.nongnu.org/avrdude/)
+* [AVRDUDESS](https://github.com/zkemble/AVRDUDESS)
+
+書き込み手順:
+
+1. `RESET` キーコードを押すか、RST を GND にすばやくショートしながら、ブートピンを GND にショートしたままにします。
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+## BootloadHID
+
+BootloadHID は AVR マイクロコントローラ用の USB ブートローダです。アップローダーツールは Windows でカーネルレベルのドライバを必要としないため、DLL をインストールせずに実行することができます。
+
+bootloadHID ブートローダとの互換性を確保するために、以下のブロックが `rules.mk` にあることを確認してください:
+
+```make
+# Bootloader selection
+#   Teensy       halfkay
+#   Pro Micro    caterina
+#   Atmel DFU    atmel-dfu
+#   LUFA DFU     lufa-dfu
+#   QMK DFU      qmk-dfu
+#   ATmega32A    bootloadHID
+#   ATmega328P   USBasp
+BOOTLOADER = bootloadHID
+```
+
+互換性のあるフラッシャ:
+
+* [HIDBootFlash](http://vusb.wikidot.com/project:hidbootflash) (推奨の Windows GUI)
+* [bootloadhid コマンドライン](https://www.obdev.at/products/vusb/bootloadhid.html) / QMK の `:BootloadHID` (推奨のコマンドライン)
+
+書き込み手順:
+
+1. 以下のいずれかの方法を使ってブートローダに入ります:
+   * `RESET` キーコードをタップします (全てのデバイスでは動作しないかもしれません)
+   * キーボードを接続しながらソルトキーを押し続けます (通常はキーボードの readme に書かれています)
+2. OS がデバイスを検知するのを待ちます。
+3. .hex ファイルを書き込みます
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+
+あるいは:
+
+    make <keyboard>:<keymap>:bootloadHID
+
+## STM32
+
+全ての STM32 チップには、変更も削除もできない工場出荷時のブートローダがプリロードされています。一部の STM32 チップには USB プログラミングが付属していないブートローダがありますが(例えば STM32F103)、プロセスは同じです。
+
+現時点では、STM32 の `rules.mk` には、`BOOTLOADER` 変数は不要です。
+
+互換性のあるフラッシャ:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) (推奨の GUI)
+* [dfu-util](https://github.com/Stefan-Schmidt/dfu-util) / `:dfu-util` (推奨のコマンドライン)
+
+書き込み手順:
+
+1. 以下のいずれかの方法を使ってブートローダに入ります:
+   * `RESET` キーコードをタップします (STM32F042 デバイスでは動作しないかもしれません)
+   * リセット回路が存在する場合、RESET ボタンをタップします
+   * それ以外の場合は、(BOOT0 ボタンあるいはブリッジ経由で)BOOT0 を VCC にブリッジし、(REEST ボタンあるいはブリッジ経由で)RESET を GND にショートし、BOOT0 ブリッジを放す必要があります。
+2. OS がデバイスを検知するのを待ちます。
+3. .bin ファイルを書き込みます
+   * DFU 署名に関する警告が表示されます; 無視してください
+4. デバイスをアプリケーションモードにリセットします(自動的に実行されるかもしれません)
+   * コマンドラインからビルドする場合(例えば、`make planck/rev6:default:dfu-util`)、`rules.mk` の中で `:leave` が `DFU_ARGS` 変数に渡されるようにしてください (例えば、`DFU_ARGS = -d 0483:df11 -a 0 -s 0x08000000:leave`)。そうすれば、書き込みの後でデバイスがリセットされます
+
+### STM32 コマンド
+
+ファームウェアを STM32 デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:dfu-util` - STM32 デバイスに書き込むためのデフォルトコマンドで、STM32 ブートローダデバイスが見つかるまで待機します。
+* `:dfu-util-split-left` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」 EEPROM の設定も行われます。
+* `:dfu-util-split-right` - デフォルトのオプション (`:dfu-util`) と同様に、通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」 EEPROM の設定も行われます。
+* `:st-link-cli` - dfu-util ではなく、ST-LINK の CLI ユーティリティを介してファームウェアを書き込めます。
diff --git a/docs/ja/getting_started_build_tools.md b/docs/ja/getting_started_build_tools.md
new file mode 100644
index 000000000..1f7accb55
--- /dev/null
+++ b/docs/ja/getting_started_build_tools.md
@@ -0,0 +1,146 @@
+# ビルドツールのインストール
+
+<!---
+  original document: 5a02cc00a:docs/getting_started_build_tools.md
+  git diff 5a02cc00a HEAD -- docs/getting_started_build_tools.md | cat
+-->
+
+このページは QMK のためのビルド環境のセットアップを説明します。これらの手順は (atmega32u4 のような) AVR プロセッサを対象としてします。
+
+<!-- FIXME: We should have ARM instructions somewhere. -->
+
+**注意:** ここが初めての場合は、[QMK 初心者ガイド](ja/newbs.md)ページを調べてください。
+
+続ける前に、`make git-submodule` を実行して、サブモジュール(サードパーティライブラリ)が最新であることを再確認してください。
+
+## Linux
+
+常に最新の状態を保つためには、単に `sudo util/qmk_install.sh` を実行してください。全ての必要な依存関係が常にインストールされるはずです。**これは `apt-get upgrade` を実行します。**
+
+手動でインストールすることもできますが、このドキュメントは常に全ての要件を満たしているとは限りません。
+
+現在の要件は以下の通りですが、何をしようとしているかによっては全てが必要とは限りません。また、一部のシステムではパッケージとして全ての依存関係が利用できるとは限らず、あるいは名前が異なる場合があるかもしれません。
+
+```
+build-essential
+gcc
+unzip
+wget
+zip
+gcc-avr
+binutils-avr
+avr-libc
+dfu-programmer
+dfu-util
+gcc-arm-none-eabi
+binutils-arm-none-eabi
+libnewlib-arm-none-eabi
+git
+```
+
+好みのパッケージマネージャを使って依存関係をインストールします。
+
+Debian / Ubuntu の例:
+
+    sudo apt-get update
+    sudo apt-get install gcc unzip wget zip gcc-avr binutils-avr avr-libc dfu-programmer dfu-util gcc-arm-none-eabi binutils-arm-none-eabi libnewlib-arm-none-eabi
+
+Fedora / Red Hat の例:
+
+    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 の例:
+
+    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
+
+## Nix
+
+[NixOS](https://nixos.org/) の場合、あるいは Linux または MacOS に Nix をインストールした場合は、ビルド環境を取得するためにリポジトリのルートで `nix-shell` を実行します。
+
+デフォルトでは、これは AVR と ARM の両方のためのコンパイラをダウンロードします。両方が必要ではない場合は、`avr` あるいは `arm` 引数を無効にします。例えば:
+
+    nix-shell --arg arm false
+
+## macOS
+[Homebrew](http://brew.sh/) を使っている場合は、以下のコマンドを使うことができます:
+
+    brew tap osx-cross/avr
+    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 arm-gcc-bin@8
+    brew link --force arm-gcc-bin@8
+    brew install avrdude
+
+これはお勧めの方法です。homebrew が無い場合は、[インストールしてください！](http://brew.sh/) コマンドラインで作業する人にとってとても価値があります。`avr-gcc@8` の homebrew でのインストール中、`make` と `make install` 部分は20分以上かかり、CPU使用率が高くなることに注意してください。
+
+## msys2 を使った Windows (推奨) :id=windows-with-msys2-recommended
+
+Windows Vista 以降のバージョン(7および10でテスト済み)について、使用するのに最適な環境は [msys2](http://www.msys2.org) です。
+
+* msys2 をダウンロードし、こちらの指示に従ってインストールしてください: http://www.msys2.org
+* ``MSYS2 MingGW 64-bit`` のショートカットを開きます
+* QMK リポジトリに移動します。例えば、c ドライブのルートにある場合:
+* `$ cd /c/qmk_firmware`
+* `util/qmk_install.sh` を実行し、指示に従います
+
+## Windows 10 (非推奨)
+Windows 10 の古い手順です。[上記の概要のように MSYS2](#windows-with-msys2-recommended) を使うことをお勧めします。
+
+### Creators Update
+Creators Update 以降の Windows 10 の場合、ファームウェアを直接ビルドして書き込むことができます。Creators Update の前は、ビルドだけが可能でした。まだそうではないか、不明な場合は、[これらの指示](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update)に従ってください。
+
+### Linux 用の Windows Subsystem
+Creators Update に加えて、Linux 用の Windows 10 Subystem が必要ですので、[これらの指示](http://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/)に従ってインストールしてください。Anniversary update からの Linux 用の Windows 10 Subsystem が既にある場合、一部のキーボードは 14.04LTS に含まれるツールチェーンを使ってコンパイルしないため、16.04LTS に[アップグレード](https://betanews.com/2017/04/14/upgrade-windows-subsystem-for-linux/)することをお勧めします。`sudo do-release-upgrade` メソッドを選択した場合は、自分が何をしているかを知る必要があることに注意してください。
+
+### Git
+すでに Windows ファイルシステムにリポジトリをクローンしている場合は、この章を無視することができます。
+
+WSL Git では**なく**、Windows 用の通常の Git を使って Windows ファイルシステムにリポジトリをクローンする必要があります。以前に Git をインストールしたことが無ければ、[ダウンロード](https://git-scm.com/download/win)し、インストールしてください。次に[セットアップします](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)。特に貢献する予定がある場合は、eメールとユーザ名をセットアップすることが重要です。
+
+Git がインストールされたら、Git Bash コマンドを開き、QMK をクローンしたい場所へディレクトリを変更します: スラッシュを使う必要があり、c ドライブは `/c/path/to/where/you/want/to/go` のようにアクセスされることに注意してください。次に、`git clone --recurse-submodules https://github.com/qmk/qmk_firmware` を実行します。これは現在のフォルダのサブディレクトリとして新しいフォルダ `qmk_firmware` を作成します。
+
+### ツールチェーンのセットアップ
+ツールチェーンのセットアップは Linux 用の Windows サブシステムを介して行われ、手順は完全に自動化されています。全てを手動で行いたい場合は、スクリプト以外の手順はありませんが、常に issue を開いて詳細情報を求めることができます。
+
+1. スタートメニューから "Bash On Ubuntu On Windows" を開いてください。
+2. クローンした `qmk_firmware` ディレクトリに移動します。パスは WSL 内で `/mnt/` から始まることに注意してください。つまり、例えば `cd /mnt/c/path/to/qmk_firmware` と書く必要があります。
+3. `util/wsl_install.sh` を実行し、画面上の手順に従います。
+4. Bash コマンドウィンドウを閉じ、再び開きます。
+5. ファームウェアをコンパイルし書き込む準備ができました！
+
+### 心に留めておくべき幾つかの重要なこと
+* 全ての最新の更新を取得するために `util/wsl_install.sh` を再実行することができます。
+* WSL は外部で実行可能ファイルを実行できないため、QMK リポジトリは Windows ファイルシステム上にある必要があります。
+* WSL Git は Windows の Git と互換性が**無い**ため、全ての Git 操作には、Windows Git Bash あるいは windows Git GUI を使ってください。
+* WSL 内あるいは普通に Windows を使ってファイルを編集できますが、makefile あるいはシェルスクリプトを編集する場合は、行末をUnix形式にしてファイルを保存するエディタを使うようにしてください。そうでなければコンパイルは機能しないかもしれません。
+
+## Docker
+
+これが少し複雑な場合は、Docker があなたが必要とするすぐに使える解決法かもしれません。[Docker CE](https://docs.docker.com/install/#supported-platforms) をインストールした後で、キーボード/キーマップをビルドするために `qmk_firmware` ディレクトリから以下のコマンドを実行します:
+```bash
+util/docker_build.sh keyboard:keymap
+# 例えば: util/docker_build.sh ergodox_ez:steno
+```
+これは目的のキーボード/キーマップをコンパイルし、結果として書き込み用に `.hex` あるいは `.bin` ファイルを QMK ディレクトリの中に残します。`:keymap` が省略された場合は全てのキーマップが使われます。パラメータの形式は、`make` を使ってビルドする時と同じであることに注意してください。
+
+スクリプトをパラメータ無しで開始することもできます。この場合、1つずつビルドパラメータを入力するように求められます。これが使いやすいと思うかもしれません:
+```bash
+util/docker_build.sh
+# パラメータを入力として読み込みます (空白にすると全てのキーボード/キーマップ)
+```
+
+`target` を指定することで Docker から直接キーボードをビルドし_かつ_書き込むためのサポートもあります。
+```bash
+util/docker_build.sh keyboard:keymap:target
+# 例えば: util/docker_build.sh planck/rev6:default:flash
+```
+Linux を使っている場合は、これはそのままで動作するはずです。Windows と macOS では、実行するのに [Docker Machine](http://gw.tnode.com/docker/docker-machine-with-usb-support-on-windows-macos/) が必要です。これはセットアップが面倒なので、お勧めではありません: 代わりに [QMK Toolbox](https://github.com/qmk/qmk_toolbox) を使ってください。
+
+!> Docker for Windows は[Hyper-V](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v) を有効にする必要があります。これは、Windows 7、Windows 8 および **Windows 10 Home** のような Hyper-V を搭載していない Windows のバージョンでは機能しないことを意味します。
+
+## Vagrant
+ファームウェアをビルドするのに問題がある場合は、Vagrant と呼ばれるツールを試してみることができます。それは、ファームウェアをビルドする準備ができた既知の構成を搭載した仮想コンピュータをセットアップします。OLKB はこの仮想コンピュータのためのファイルをホストしません。Vagrant をセットアップする方法の詳細は、[vagrant ガイド](ja/getting_started_vagrant.md)にあります。
diff --git a/docs/ja/getting_started_make_guide.md b/docs/ja/getting_started_make_guide.md
new file mode 100644
index 000000000..d33485ce1
--- /dev/null
+++ b/docs/ja/getting_started_make_guide.md
@@ -0,0 +1,153 @@
+# より詳細な `make` 手順
+
+<!---
+  original document: 5f35203d1:docs/getting_started_make_guide.md
+  git diff 5f35203d1 HEAD -- docs/getting_started_make_guide.md | cat
+-->
+
+`make` コマンドの完全な構文は `<keyboard_folder>:<keymap>:<target>` です:
+
+* `<keyboard_folder>` はキーボードのパスです。例えば、`planck`
+   * 全てのキーボードをコンパイルするには `all` を使います。
+   * リビジョンを選択してコンパイルするためのパスを指定します。例えば `planck/rev4` あるいは `planck/rev3`
+   * キーボードにフォルダが無い場合は、省略することができます
+   * デフォルトのフォルダをコンパイルする場合は、省略することができます
+* `<keymap>` はキーマップの名前です。例えば、`algernon`
+   * 全てのキーマップをコンパイルするには `all` を使います。
+* `<target>` の詳細は以下で説明します。
+
+`<target>` は以下を意味します
+* target が指定されない場合は、以下の `all` と同じです
+* `all` は指定されたキーボード/リビジョン/キーマップの可能な全ての組み合わせのコンパイルを行います。例えば、`make planck/rev4:default` は1つの .hex を生成しますが、`make planck/rev4:all` は planck で利用可能な全てのキーマップについて hex を生成します。
+* `flash`、`dfu`、`teensy`、`avrdude`、`dfu-util` または `bootloadHID` はファームウェアをコンパイルし、キーボードにアップロードします。コンパイルが失敗すると、何もアップロードされません。使用するプログラマはキーボードに依存します。ほとんどのキーボードでは `dfu` ですが、ChibiOS キーボードについては `dfu-util` 、標準的な Teensy については `teensy` を使います。キーボードに使うコマンドを見つけるには、キーボード固有の readme をチェックしてください。
+* **注意**: 一部のオペレーティングシステムではこれらのコマンドが機能するためには root アクセスが必要です。その場合、例えば `sudo make planck/rev4:default:flash` を実行する必要があります。
+* `clean` は、全てをゼロからビルドするためにビルド出力フォルダを掃除します。説明できない問題がある場合は、通常のコンパイルの前にこれを実行してください。
+
+make コマンドの最後、つまり target の後に追加のオプションを追加することもできます
+
+* `make COLOR=false` - カラー出力をオフ
+* `make SILENT=true` - エラー/警告以外の出力をオフ
+* `make VERBOSE=true` - 全ての gcc のものを出力 (デバッグする必要が無い限り面白くありません)
+* `make EXTRAFLAGS=-E` - コンパイルせずにコードを前処理 (#define コマンドをデバッグしようとする場合に便利)
+
+make コマンド自体にもいくつかの追加オプションがあります。詳細は `make --help` を入力してください。最も有用なのはおそらく `-jx` です。これは複数の CPU を使ってコンパイルしたいことを指定し、`x` は使用したい CPU の数を表します。設定すると、特に多くのキーボード/キーマップをコンパイルしている場合は、コンパイル時間を大幅に短縮することができます。通常は、コンパイル中に他の作業を行うための余裕をもたせるために、持っている CPU の数より1つ少ない値に設定します。全てのオペレーティングシステムと make バージョンがオプションをサポートしているわけではないことに注意してください。
+
+コマンドの例を幾つか示します
+
+* `make all:all` は、全てをビルドします (全てのキーボードフォルダ、全てのキーマップ)。`root` から単に `make` を実行すると、これを実行します。
+* `make ergodox_infinity:algernon:clean` は、Ergodox Infinity キーボードのビルド出力を掃除します。
+* `make planck/rev4:default:flash COLOR=false` カラー出力なしでキーマップをビルドしアップロードします。
+
+## `rules.mk` オプション
+
+無効にするにはこれらの変数を `no` に設定します。有効にするには `yes` に設定します。
+
+`BOOTMAGIC_ENABLE`
+
+これにより、1つのキーとソルトキー(デフォルトではスペース)を押し続けることで、電力が失われても持続する様々な EEPROM 設定へアクセスできます。誤って設定が変更されることが多く、デバッグするのが難しい混乱した結果を生成するため、これを無効にしておくことをお勧めします。ヘルプセッションで発生する、より一般的な問題の1つです。
+
+`MOUSEKEY_ENABLE`
+
+これにより、キーコード/カスタム関数を介して、カーソルの動きとクリックを制御することができます。
+
+`EXTRAKEY_ENABLE`
+
+これにより、システムとオーディオ制御キーコードを使うことができます。
+
+`CONSOLE_ENABLE`
+
+これにより、[`hid_listen`](https://www.pjrc.com/teensy/hid_listen.html) を使って読むことができるメッセージを出力することができます。
+
+デフォルトで、全てのデバッグ( *dprint* ) 出力 ( *print*、*xprintf* )、およびユーザ出力 ( *uprint* ) メッセージが有効になります。これにより、フラッシュメモリの大部分が消費され、キーボードの .hex ファイルが大きすぎてプログラムできなくなるかもしれません。
+
+デバッグメッセージ( *dprint* ) を無効にし、.hex ファイルのサイズを小さくするには、`config.h` に `#define NO_DEBUG` を含めます。
+
+出力メッセージ( *print*、*xprintf* )とユーザ出力( *uprint* ) を無効にし、.hex のファイルサイズを小さくするには、`config.h` に `#define NO_PRINT` を含めます。
+
+出力メッセージ ( *print*、*xprintf* ) を無効にし、ユーザメッセージ ( *uprint* )を**そのままにする**には、`config.h` に `#define USER_PRINT` を含めます(この場合は、`#define NO_PRINT` も含めないでください)。
+
+テキストを見るには、`hid_listen` を開き、出力メッセージを見るのを楽しんでください。
+
+**注意:** キーマップコード以外の *uprint* メッセージを含めないでください。QMK システムフレームワーク内で使うべきではありません。さもないと、他の人の .hex ファイルが肥大化します。
+
+`COMMAND_ENABLE`
+
+これはマジックコマンドを有効にし、通常はデフォルトのマジックキーの組み合わせ `LSHIFT+RSHIFT+KEY` で起動されます。マジックコマンドは、デバッグメッセージ (`MAGIC+D`) の有効化や NKRO の一時的な切り替え (`MAGIC+N`) を含みます。
+
+`SLEEP_LED_ENABLE`
+
+コンピュータがスリープの間に LED がブレスできるようにします。ここでは Timer1 が使われます。この機能は大部分が未使用でテストされておらず、更新もしくは抽象化が必要です。
+
+`NKRO_ENABLE`
+
+これにより、キーボードはホスト OS に最大 248 個のキーが同時に押されていることを伝えることができます (NKRO 無しのデフォルトは 6 です)。NKRO は、`NKRO_ENABLE` が設定されていたとしても、デフォルトではオフです。config.h に `#define FORCE_NKRO` を追加するか、`MAGIC_TOGGLE_NKRO` をキーにバインドしてキーを押すことで、NKRO を強制することができます。
+
+`BACKLIGHT_ENABLE`
+
+これはスイッチ内の LED のバックライトを有効にします。`config.h` 内に以下を入れることでバックライトピンを指定することができます:
+
+    #define BACKLIGHT_PIN B7
+
+`MIDI_ENABLE`
+
+キーボードで MIDI の送受信を有効にします。MIDI 送信モードに入るためにキーコード `MI_ON` を使うことができ、オフにするために `MI_OFF` を使うことができます。これはほとんどテストされていない機能ですが、詳細については `quantum/quantum.c` ファイルで見つけることができます。
+
+`UNICODE_ENABLE`
+
+これによりキーマップで `UC(<code point>)` を使って Unicode 文字を送信することができます。`0x7FFF` までのコードポイントがサポートされます。これはほとんどの現代言語の文字と記号を対象にしますが、絵文字は対象外です。
+
+`UNICODEMAP_ENABLE`
+
+これによりキーマップで `X(<map index>)` を使って Unicode 文字を送信することができます。キーマップファイル内にマッピングテーブルを保持する必要があります。可能な全てのコードポイント( `0x10FFFF` まで)がサポートされます。
+
+`UCIS_ENABLE`
+
+これにより、送信したい文字に対応するニーモニックを入力することで Unicode 文字を送信することができます。キーマップファイル内にマッピングテーブルを保持する必要があります。可能な全てのコードポイント( `0x10FFFF` まで)がサポートされます。
+
+詳細と制限については、[Unicode ページ](ja/feature_unicode.md) を見てください。
+
+`BLUETOOTH_ENABLE`
+
+これによりキーコードをワイヤレスで送信するために Bluefruit EZ-key と連動することができます。D2 と D3 ピンを使います。
+
+`AUDIO_ENABLE`
+
+C6 ピン(抽象化が必要)でオーディオ出力できます。詳細は[オーディオページ](ja/feature_audio.md)を見てください。
+
+`FAUXCLICKY_ENABLE`
+
+クリック音のあるスイッチをエミュレートするためにブザーを使います。Cherry社製の青軸スイッチの安っぽい模倣です。デフォルトでは、`AUDIO_ENABLE` と同じように C6 ピンを使います。
+
+`VARIABLE_TRACE`
+
+これを使って変数の値の変更をデバッグします。詳細についてはユニットテストのページの[変数のトレース](ja/unit_testing.md#tracing-variables)のセクションを見てください。
+
+`API_SYSEX_ENABLE`
+
+これにより Quantum SYSEX API を使って文字列を送信することができます (どこに？)
+
+`KEY_LOCK_ENABLE`
+
+これは [キーロック](ja/feature_key_lock.md) を有効にします。
+
+`SPLIT_KEYBOARD`
+
+分割キーボード (let's split や bakingpy's boards のようなデュアル MCU) のサポートを有効にし、quantum/split_common にある全ての必要なファイルをインクルードします
+
+`SPLIT_TRANSPORT`
+
+ARM ベースの分割キーボード用の標準分割通信ドライバはまだ無いため、これらのために `SPLIT_TRANSPORT = custom` を使わなければなりません。カスタムの実装が使われるようにすることで、標準の分割キーボード通信コード(AVR 固有)が含まれないようにします。
+
+`CUSTOM_MATRIX`
+
+デフォルトのマトリックス走査ルーチンを独自のコードで置き換えます。詳細については、[カスタムマトリックスページ](ja/custom_matrix.md) を見てください。
+
+`DEBOUNCE_TYPE`
+
+デフォルトのキーデバウンスルーチンを別のものに置き換えます。`custom` の場合、独自の実装を提供する必要があります。
+
+## キーマップごとに Makefile オプションをカスタマイズ
+
+あなたのキーマップディレクトリに `rules.mk` というファイルがある場合、そのファイルで設定した全てのオプションは、あなたのキーボードの他の `rules.mk` オプションよりも優先されます。
+
+あなたのキーボードの `rules.mk` に `BACKLIGHT_ENABLE = yes` があるとします。あなたの特定のキーボードでバックライトが無いようにするには、`rules.mk` というファイルを作成し、`BACKLIGHT_ENABLE = no` を指定します。
diff --git a/docs/ja/getting_started_vagrant.md b/docs/ja/getting_started_vagrant.md
new file mode 100644
index 000000000..0bc5c4b79
--- /dev/null
+++ b/docs/ja/getting_started_vagrant.md
@@ -0,0 +1,62 @@
+# Vagrant クイックスタート
+
+<!---
+  original document: 7494490d6:docs/getting_started_vagrant.md
+  git diff 7494490d6 HEAD -- docs/getting_started_vagrant.md | cat
+-->
+
+このプロジェクトは、プライマリオペレーティングシステムに大きな変更を加えることなくキーボードの新しいファームウェアを非常に簡単に構築することができる `Vagrantfile` を含みます。これは、あなたがプロジェクトをクローンしビルドを実行した時に、ビルドのために Vagrantfile を使っている他のユーザと全く同じ環境を持つことも保証します。これにより、人々はあなたが遭遇した問題の解決をより簡単に行えるようになります。
+
+## 必要事項
+
+このリポジトリ内の `Vagrantfile` を使うには、[Vagrant](http://www.vagrantup.com/) およびサポートされるプロバイダがインストールされている必要があります:
+
+* [VirtualBox](https://www.virtualbox.org/) (バージョン 5.0.12 以降)
+   * 'Vagrant を使うために最もアクセスしやすいプラットフォーム' として販売
+* [VMware Workstation](https://www.vmware.com/products/workstation) および [Vagrant VMware プラグイン](http://www.vagrantup.com/vmware)
+   * (有料) VMware プラグインには、ライセンスされた VMware Workstation/Fusion のコピーが必要です。
+* [Docker](https://www.docker.com/)
+
+Vagrant 以外に、適切なプロバイダがインストールされ、その後におそらくコンピュータを再起動すると、このプロジェクトをチェックアウトしたフォルダ内の任意の場所で 'vagrant up' を単純に実行することができ、このプロジェクトをビルドするのに必要な全てのツールが含まれる環境(仮想マシンあるいはコンテナ)が開始されます。Vagrant をうまく始めるためのヒントの投稿がありますが、それ以外に、以下のビルドドキュメントを参照することもできます。
+
+## ファームウェアの書き込み
+
+ファームウェアを書き込む"簡単"な方法は、ホスト OS からツールを使うことです:
+
+* [QMK Toolbox](https://github.com/qmk/qmk_toolbox) (推奨)
+* [Teensy ローダー](https://www.pjrc.com/teensy/loader.html)
+* [Atmel FLIP](http://www.atmel.com/tools/flip.aspx)
+
+コマンドラインでプログラムしたい場合は、Vagranfile の ['modifyvm'] 行のコメントを解除して Linux への USB パススルーを有効にし、dfu-util/dfu-programmer のようなコマンドラインツールを使ってプログラムすることができます。あるいは Teensy CLI バージョンをインストールすることができます。
+
+## Vagrantfile の概要
+開発環境は QMK Docker イメージ、`qmkfm/base_container` を実行するように設定されています。これはシステム間の予測可能性が保証されるだけでなく、CI 環境もミラーされます。
+
+## FAQ
+
+### Virtualbox で問題が発生するのはなぜですか？
+Virtualbox 5 の特定のバージョンはこの Vagrantfile のボックスにインストールされている Virtualbox の拡張機能と互換性が無いようです。/vagrant のマウントで問題が発生した場合は、Virtualbox のバージョンを少なくとも 5.0.12 にアップグレードしてください。**または、以下のコマンドを実行してみることができます:**
+
+```console
+vagrant plugin install vagrant-vbguest
+```
+
+### 既存の環境を削除するにはどうすればいいですか？
+あなたの環境での作業が完了しましたか？このプロジェクトをチェックアウトしたフォルダの中のどこからでも、以下を実行してください:
+
+```console
+vagrant destroy
+```
+
+### Docker を直接使いたい場合はどうしますか？
+仮想マシン無しで Vagrant のワークフローを活用したいですか？Vagrantfile は仮想マシンの実行をバイパスし、コンテナを直接実行するように設定されています。Docker を強制的に使うように環境を立ち上げる場合は、以下を実行してください:
+```console
+vagrant up --provider=docker
+```
+
+### Docker コンテナではなく仮想マシンにアクセスするにはどうすればいいですか？
+以下を実行して、公式の QMK ビルダーイメージから直接起動する `vagrant` ユーザをバイパスするようにします:
+
+```console
+vagrant ssh -c 'sudo -i'
+```
diff --git a/docs/ja/keymap.md b/docs/ja/keymap.md
new file mode 100644
index 000000000..29eb1adc0
--- /dev/null
+++ b/docs/ja/keymap.md
@@ -0,0 +1,174 @@
+# キーマップの概要
+
+<!---
+  original document: 7494490d6:docs/keymap.md
+  git diff 7494490d6 HEAD -- docs/keymap.md | cat
+-->
+
+QMK のキーマップは C のソースファイルの中で定義されます。そのデータ構造は配列の配列です。外側はレイヤーを要素とする配列で、レイヤーはキーを要素とする配列。ほとんどのキーボードは `LAYOUT()` マクロを定義して、この配列の配列を作成しやすくしています。
+
+
+## キーマップとレイヤー
+QMKでは、**`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`**は、**アクションコード**を保持している **16 bit** データの中でキーマップ情報の複数の**レイヤー**を保持します。最大で**32個のレイヤー**を定義することができます。
+
+普通のキー定義の場合、**アクションコード**の上位8ビットは全て0で、下位8ビットは**キーコード**としてキーによって生成された USB HID usage コードを保持します。
+
+各レイヤーは同時に有効にできます。レイヤーには 0 から 31 までのインデックスが付けられ、上位のレイヤーが優先されます。
+
+    Keymap: 32 Layers                   Layer: action code matrix
+    -----------------                   ---------------------
+    stack of layers                     array_of_action_code[row][column]
+           ____________ precedence               _______________________
+          /           / | high                  / ESC / F1  / F2  / F3   ....
+      31 /___________// |                      /-----/-----/-----/-----
+      30 /___________// |                     / TAB /  Q  /  W  /  E   ....
+      29 /___________/  |                    /-----/-----/-----/-----
+       :   _:_:_:_:_:__ |               :   /LCtrl/  A  /  S  /  D   ....
+       :  / : : : : : / |               :  /  :     :     :     :
+       2 /___________// |               2 `--------------------------
+       1 /___________// |               1 `--------------------------
+       0 /___________/  V low           0 `--------------------------
+
+
+TMK の歴史的経緯から、キーマップに保存されたアクションコードは、一部のドキュメントではキーコードと呼ばれる場合があります。
+
+### キーマップレイヤーステータス
+キーマップレイヤーの状態は、2つの32ビットパラメータによって決定されます。
+
+* **`default_layer_state`** は、常に有効で参照される基本キーマップレイヤー (0-31) を示します (デフォルトレイヤー)。
+* **`layer_state`** は現在の各レイヤーのオン/オフの状態をビットで持ちます。
+
+キーマップレイヤー '0' は通常 `default_layer` で、他のレイヤーはファームウェアの起動後に最初はオフになっていますが、これは `config.h` で異なる設定にすることが可能です。例えば Qwerty ではなく Colemak に切り替えるなど、キーレイアウトを完全に切り替える場合、`default_layer` を変更すると便利です。
+
+    Initial state of Keymap          Change base layout
+    -----------------------          ------------------
+
+      31                               31
+      30                               30
+      29                               29
+       :                                :
+       :                                :   ____________
+       2   ____________                 2  /           /
+       1  /           /              ,->1 /___________/
+    ,->0 /___________/               |  0
+    |                                |
+    `--- default_layer = 0           `--- default_layer = 1
+         layer_state   = 0x00000001       layer_state   = 0x00000002
+
+一方、`layer_state` を変更して、基本レイヤーをナビゲーションキー、ファンクションキー (F1-F12)、メディアキー、特別なアクションなどの機能を持つ他のレイヤーでオーバーレイすることができます。
+
+    Overlay feature layer
+    ---------------------      bit|status
+           ____________        ---+------
+      31  /           /        31 |   0
+      30 /___________// -----> 30 |   1
+      29 /___________/  -----> 29 |   1
+       :                        : |   :
+       :   ____________         : |   :
+       2  /           /         2 |   0
+    ,->1 /___________/  ----->  1 |   1
+    |  0                        0 |   0
+    |                                 +
+    `--- default_layer = 1            |
+         layer_state   = 0x60000002 <-'
+
+
+
+### レイヤーの優先順位と透過性
+***上位のレイヤーはレイヤーのスタックでより高い優先順位を持つ***ことに注意してください。つまり、ファームウェアはキーコードを最上位から最下位まで検索します。レイヤーで **`KC_TRNS`**(透過)以外のキーコードを見つけると、検索を中止し、下位レイヤーは参照されません。
+
+オーバーレイレイヤーに `KC_TRANS`  を配置して、レイアウトの一部だけを変更して下位レイヤーまたは基本レイヤーにフォールバックすることができます。
+`KC_TRANS` (`KC_TRNS` と `_______` はエイリアス) のキーには独自のキーコードがなく、キーコードの有効な下位レイヤーを参照します。
+
+## `keymap.c` の分析
+
+この例では、[デフォルトの Clueboard 66% キーマップの古いバージョン](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/keyboards/clueboard/keymaps/default/keymap.c)を見ていきます。そのファイルを別のブラウザウィンドウで開くとコンテキスト内のすべてを見ることができるので便利です。
+
+`keymap.c` ファイルには、あなたが関心があるであろう以下の2つの主要なセクションがあります:
+
+* [定義](#definitions)
+* [レイヤー/キーマップデータ構造](#layers-and-keymaps)
+
+### 定義 :id=definitions
+
+ファイルの上部に以下のものがあります:
+
+    #include QMK_KEYBOARD_H
+    
+    // 便利な定義
+    #define GRAVE_MODS  (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
+    
+    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+    *  KC_TRNS (透過) の代わりに _______ を使うことができます   *
+     *  あるいは、KC_NO (NOOP)  として XXXXXXX を使うことができます    *
+    * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+    
+    // 各レイヤーは読みやすいように名前を持ちます。
+    // アンダースコアは何も意味を持ちません
+    // STUFF あるいは他の名前のレイヤーを持つことができます。
+    // レイヤー名は全て同じ長さである必要はなく、
+    // また名前を完全に省略して単に数字を使うことができます。
+    #define _BL 0
+    #define _FL 1
+    #define _CL 2
+
+これらはキーマップとカスタム関数を作成するときに使うことができる便利な定義です。`GRAVE_MODS` 定義は後でカスタム関数で使われ、その下の `_BL`、`_FL`、`_CL` 定義は各レイヤーを参照しやすくします。
+
+注意: 古いキーマップファイルに `_______` および `XXXXXXX` の定義が含まれているかもしれません。これらはそれぞれ `KC_TRNS` および `KC_NO` の代わりに使うことができ、レイヤーがどのキーを上書きしているかを簡単に確認することができます。これらの定義はデフォルトで含まれるため、今では不要になりました。
+
+### レイヤーとキーマップ :id=layers-and-keymaps
+
+このファイルの主要部分は `keymaps[]` 定義です。ここで、レイヤーとそれらの内容を列挙します。ファイルのこの部分は、以下の定義から始まります:
+
+    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+この後で、LAYOUT() マクロのリストがあります。LAYOUT() は単一のレイヤーを定義するためのキーのリストです。通常、1つ以上の"基本レイヤー" (QWERTY、Dvorak、Colemak など)があり、その上に1つ以上の"機能"レイヤーを重ねます。レイヤーの処理方法により、"より上位"のレイヤーの上に"より下位"のレイヤーを重ねることはできません。
+
+QMK の `keymaps[][MATRIX_ROWS][MATRIX_COLS]` は、16ビットのアクションコード( quantum キーコードとも呼ばれる)を保持します。一般的なキーを表すキーコードの場合、その上位バイトは0で、その下位バイトはキーボードの USB HID usage ID です。
+
+> QMK のフォーク元の TMK は、代わりに `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` を使い、8ビットキーコードを保持します。一部のキーコード値は、`fn_actions[]` 配列を介して特定のアクションコードの実行を引き起こすために予約されています。
+
+#### 基本レイヤー
+
+Clueboard の基本レイヤーの例です:
+
+    /* Keymap _BL: Base Layer (Default Layer)
+    */
+    [_BL] = LAYOUT(
+    F(0),    KC_1,    KC_2,   KC_3,   KC_4,   KC_5,   KC_6,   KC_7,   KC_8,   KC_9,    KC_0,     KC_MINS,  KC_EQL,   KC_GRV,  KC_BSPC,          KC_PGUP, \
+    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(_FL), KC_LEFT, KC_DOWN, KC_RGHT),
+
+これについて注意すべきいくつかの興味深いこと:
+
+* C ソースの観点からは、これは単一の配列に過ぎませんが、物理デバイス上の各キーがどこにあるかをより簡単に可視化するために、空白が埋め込まれています。
+* 単純なキーボードスキャンコードの先頭には KC_ が付いていますが、"特別な"キーには付いていません。
+* 左上のキーはカスタム機能 0 (`F(0)`) をアクティブにします。
+* "Fn" キーは `MO(_FL)` で定義され、そのキーが押されている間は `_FL` レイヤーに移動します。
+
+#### 機能オーバーレイレイヤー
+
+機能レイヤーはコードの観点から基本レイヤーと違いはありません。ただし概念的には、置き換えの代わりにオーバーレイとしてそのレイヤーを構築します。多くの人にとってはこの区別は重要ではありませんが、より複雑なレイヤー設定を構築するにつれて、ますます重要になります。
+
+    [_FL] = LAYOUT(
+    KC_GRV,  KC_F1,   KC_F2,  KC_F3,  KC_F4,  KC_F5,  KC_F6,  KC_F7,  KC_F8,  KC_F9,   KC_F10,   KC_F11,   KC_F12,   _______, KC_DEL,           BL_STEP, \
+    _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS,  _______,  _______,  _______,                   _______, \
+    _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______,  _______,  _______,  _______,                           \
+    _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______,  _______,  _______,  _______,          KC_PGUP,         \
+    _______, _______, _______, _______,        _______,_______,                        _______,  _______,  _______,  MO(_FL), KC_HOME, KC_PGDN, KC_END),
+
+注意すべきいくつかの興味深いこと:
+
+* `_______` 定義を使って、`KC_TRNS` を `_______` に変換しました。これによりこのレイヤーで変更されたキーを簡単に見つけることができます。
+* このレイヤーで `_______` キーのいずれかを押すと、次の下位のアクティブなレイヤーのキーがアクティブになります。
+
+# 核心となる詳細
+
+これで独自のキーマップを作成するための基本的な概要が得られました。詳細は以下のリソースを見てください:
+
+* [キーコード](ja/keycodes.md)
+* [キーマップ FAQ](ja/faq_keymap.md)
+
+これらのドキュメントの改善に積極的に取り組んでいます。それらを改善する方法について提案がある場合は、[issue を報告](https://github.com/qmk/qmk_firmware/issues/new)してください！