Merge remote-tracking branch 'upstream/master'

8 files changed, 1177 insertions, 0 deletions

diff --git a/docs/ja/newbs.md b/docs/ja/newbs.md
new file mode 100644
index 000000000..d1043a4a1
--- /dev/null
+++ b/docs/ja/newbs.md
@@ -0,0 +1,41 @@
+# QMK 初心者ガイド
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: ed0575fc8:docs/newbs.md
+  git diff ed0575fc8 HEAD docs/newbs.md | cat
+-->
+
+QMK は、メカニカルキーボード用の強力なオープンソースファームウェアです。
+QMK を使用して、シンプルかつ強力な方法でキーボードをカスタマイズできます。
+完全な初心者からプログラマーに至るまで、あらゆるスキルレベルの人々が QMK を使用してキーボードをカスタマイズしています。
+このガイドは、あなたのスキルにかかわらず、同じことを行う手助けをします。
+
+お使いのキーボードで QMK を実行できるかどうか不明ですか？
+もし作成したキーボードがメカニカルキーボードの場合、実行できる可能性が高いです。
+QMK は[多くの趣味のキーボード](http://qmk.fm/keyboards/)をサポートしているため、もし現在のキーボードで QMK を実行できない場合でも、ニーズに合ったキーボードを見つけるのに問題はないはずです。
+
+## 概要
+
+このガイドには7つの主要なセクションがあります。
+
+* [はじめに](newbs_getting_started.md)
+* [コマンドラインを使用して初めてのファームウェアを構築する](newbs_building_firmware.md)
+* [オンライン GUI を使用して初めてのファームウェアを構築する](newbs_building_firmware_configurator.md)
+* [ファームウェアを書きこむ](newbs_flashing.md)
+* [テストとデバッグ](newbs_testing_debugging.md)
+* [QMK における Git 運用作法](newbs_best_practices.md)
+* [さらに学ぶための学習リソース](newbs_learn_more_resources.md)
+
+このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。
+その観点から選択と推奨を行います。
+これらの手順の多くには代替方法があり、これらの代替方法のほとんどをサポートしています。
+タスクを達成する方法について疑問がある場合は、[案内を求めることができます](getting_started_getting_help.md)。
+
+## 追加のリソース(英語)
+
+* [Thomas Baart's QMK Basics Blog](https://thomasbaart.nl/category/mechanical-keyboards/firmware/qmk/qmk-basics/) – 新規ユーザ視点から見た QMK ファームウェアの基本的な使用方法をカバーしたユーザ作成のブログ。
+
+## 追加のリソース(日本語)
+
+_日本語のリソース情報を募集中です。_
diff --git a/docs/ja/newbs_best_practices.md b/docs/ja/newbs_best_practices.md
new file mode 100644
index 000000000..2e90ffcab
--- /dev/null
+++ b/docs/ja/newbs_best_practices.md
@@ -0,0 +1,263 @@
+<!-- # Best Practices -->
+# QMK における Git 運用作法
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: e75919960:docs/newbs_best_practices.md
+  git diff e75919960 HEAD docs/newbs_best_practices.md | cat
+-->
+
+<!-- ## Or, "How I Learned to Stop Worrying and Love Git." -->
+## または、如何にして私は心配することをやめて Git を愛することを学んだか。
+
+<!-- _Almost the same as #7231:25fdbf2a0:newbs_git_best_practices.md L5_ -->
+<!-- This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. -->
+この文書は、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。
+QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。
+その後、意図的に一部を壊してみせて、それらを修正する方法を教えます。
+
+<!-- This document assumes a few things: -->
+このドキュメントは以下のことを前提としています:
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_best_practices.md L9_  -->
+<!-- 1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. -->
+<!-- 2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). -->
+<!-- #7231:da7d49246: 2. You've set up both [your build environment](newbs_getting_started.md?id=set-up-your-environment) and [QMK](newbs_getting_started.md?id=set-up-qmk). -->
+
+1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](getting_started_github.md) している。
+2. あなたは、[環境構築](newbs_getting_started.md#環境構築) と [QMK の設定](newbs_getting_started.md#qmk-の設定) を両方とも完了している。
+
+<!-- ## Your fork's master: Update Often, Commit Never -->
+## あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L3_  -->
+<!-- It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. -->
+QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。
+代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L5_  -->
+<!-- To reduce the chances of merge conflicts &mdash; instances where two or more users have edited the same part of a file concurrently &mdash; keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. -->
+マージの競合 &mdash; これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 &mdash; の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。
+
+<!-- ### Updating your master branch -->
+### あなたの master ブランチを更新する
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L9_  -->
+<!-- To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: -->
+`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。
+これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。
+
+```
+git remote add upstream https://github.com/qmk/qmk_firmware.git
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L15_  -->
+<!-- To verify that the repository has been added, run `git remote -v`, which should return the following: -->
+リポジトリが追加されたことを確認するには、`git remote -v` を実行します。
+次のように表示されます。(訳注: `upstream` は`上流`という意味です。)
+
+```
+$ git remote -v
+origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
+origin  https://github.com/<your_username>/qmk_firmware.git (push)
+upstream        https://github.com/qmk/qmk_firmware.git (fetch)
+upstream        https://github.com/qmk/qmk_firmware.git (push)
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L25_  -->
+<!-- Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags &mdash; collectively referred to as "refs" &mdash; from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. -->
+これが完了すると、`git fetch upstream` を実行してリポジトリの更新を確認できます。
+このコマンドは `upstream` というニックネームを持つ QMK リポジトリから、ブランチとタグ &mdash; "refs" と総称されます &mdash; を取得します。
+これで、あなたのフォーク `origin` のデータを QMK が保持するデータと比較できます。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L27_  -->
+<!-- To update your fork's master, run the following, hitting the Enter key after each line: -->
+あなたのフォークの `master` を更新するには、次を実行します、各行の後にEnterキーを押してください:
+
+```
+git checkout master
+git fetch upstream
+git pull upstream master
+git push origin master
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L36_  -->
+<!-- This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. -->
+これにより、あなたの `master` ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の `master` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。
+
+<!-- ### Making Changes -->
+### 変更を行なう
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L40_  -->
+<!-- To make changes, create a new branch by entering: -->
+変更するには、以下を入力して新しいブランチを作成します:
+
+```
+git checkout -b dev_branch
+git push --set-upstream origin dev_branch
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L47_  -->
+<!-- This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. -->
+これにより、`dev_branch` という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。
+`--set-upstream` 引数は、このブランチから `git push` または `git pull` を使用するたびに、あなたのフォークと `dev_branch` ブランチを使用するように git に指示します。
+この引数は最初のプッシュでのみ使用する必要があります。
+その後、残りの引数なしで `git push` または `git pull` を安全に使用できます。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L49_  -->
+<!--  With `git push`, you can use `-u` in place of `--set-upstream` &mdash; `-u` is an alias for `--set-upstream`. -->
+!> `git push` では、`-set-upstream` の代わりに `-u` を使用できます、 `-u` は `--set-upstream` のエイリアスです。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L51_  -->
+<!-- You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. -->
+ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L53_  -->
+<!-- By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: -->
+デフォルトでは、`git checkout -b`は、今チェックアウトされているブランチに基づいて新しいブランチを作成します。
+コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます:
+
+```
+git checkout -b dev_branch master
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L59_  -->
+<!-- Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: -->
+これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。
+ブランチに対して多くの小さなコミットを行うことをお勧めします。
+そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。
+変更を加えるには、更新が必要なファイルを編集して保存し、Git の *ステージングエリア* に追加してから、ブランチにコミットします:
+
+```
+git add path/to/updated_file
+git commit -m "My commit message."
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L66_  -->
+<!-- `git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. -->
+`git add`は、変更されたファイルを Git の *ステージングエリア* に追加します。
+これは、Git の「ロードゾーン」です。
+これには、`git commit` によって *コミット* される変更が含まれており、リポジトリへの変更が保存されます。
+変更内容が一目でわかるように、説明的なコミットメッセージを使用します。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L68_  -->
+<!-- !> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. -->
+!> 多くのファイルを変更したが、すべてのファイルが同じ変更の一部である場合、各ファイルを個別に追加するのではなく、 `git add .` を使用して、現在のディレクトリにあるすべての変更されたファイルを追加できます。
+
+<!-- ### Publishing Your Changes -->
+### 変更を公開する
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_using_your_master_branch.md L72_  -->
+<!-- The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. -->
+最後のステップは、変更をフォークにプッシュすることです。これを行うには、`git push`と入力します。
+Git は `dev_branch` の現在の状態をフォークに公開します。
+
+<!-- ## Resolving Merge Conflicts -->
+##  マージの競合の解決
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L3_  -->
+<!-- Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. -->
+ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。
+これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。
+
+<!-- ### Rebasing Your Changes -->
+### 変更のリベース
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L9_  -->
+<!-- A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. -->
+*リベース* は、ある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。
+マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L11_  -->
+<!-- To start, run the following: -->
+開始するには、次を実行します:
+
+```
+git fetch upstream
+git rev-list --left-right --count HEAD...upstream/master
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L18_  -->
+<!-- The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: -->
+ここに入力された `git rev-list` コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。
+最初に `git fetch` を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。
+入力された `git rev-list` コマンドの出力は2つの数値を返します:
+
+```
+$ git rev-list --left-right --count HEAD...upstream/master
+7       35
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L25_  -->
+<!-- The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. -->
+最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから `upstream/master` に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L27_-->
+<!-- Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: -->
+現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます:
+
+```
+git rebase upstream/master
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L33_  -->
+<!-- This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. -->
+これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。
+
+```
+$ git rebase upstream/master
+First, rewinding head to replay your work on top of it...
+Applying: Commit #1
+Using index info to reconstruct a base tree...
+M       conflicting_file_1.txt
+Falling back to patching base and 3-way merge...
+Auto-merging conflicting_file_1.txt
+CONFLICT (content): Merge conflict in conflicting_file_1.txt
+error: Failed to merge in the changes.
+hint: Use 'git am --show-current-patch' to see the failed patch
+Patch failed at 0001 Commit #1
+
+Resolve all conflicts manually, mark them as resolved with
+"git add/rm <conflicted_files>", then run "git rebase --continue".
+You can instead skip this commit: run "git rebase --skip".
+To abort and get back to the state before "git rebase", run "git rebase --abort".
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L54_  -->
+<!-- This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: -->
+これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。
+テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります:
+
+```
+<<<<<<< HEAD
+<p>For help with any issues, email us at support@webhost.us.</p>
+=======
+<p>Need help? Email support@webhost.us.</p>
+>>>>>>> Commit #1
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L64_  -->
+<!-- The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. -->
+行 `<<<<<<< HEAD` はマージ競合の始まりを示し、行 `>>>>>>> commit #1` は終了を示し、競合するセクションは `=======` で区切られます。
+`HEAD` 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L66_  -->
+<!-- Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. -->
+Git はファイルの内容ではなく *ファイルへの変更* を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。
+ファイルを再編集して、競合を解決します。
+変更を加えてから、ファイルを保存します。
+
+```
+<p>Need help? Email support@webhost.us.</p>
+```
+
+そしてコマンド実行:
+
+```
+git add conflicting_file_1.txt
+git rebase --continue
+```
+
+<!-- _Same as #7231:25fdbf2a0:newbs_git_resolving_merge_conflicts.md L79_  -->
+<!-- Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end. -->
+Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。
diff --git a/docs/ja/newbs_building_firmware.md b/docs/ja/newbs_building_firmware.md
new file mode 100644
index 000000000..5fb10d424
--- /dev/null
+++ b/docs/ja/newbs_building_firmware.md
@@ -0,0 +1,99 @@
+# 初めてのファームウェアを構築する(コマンドライン版)
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: ed0575fc8:docs/newbs_building_firmware.md
+  git diff ed0575fc8 HEAD docs/newbs_building_firmware.md | cat
+-->
+
+ビルド環境をセットアップしたので、カスタムファームウェアのビルドを開始する準備ができました。
+ガイドのこのセクションでは、ファイルマネージャ、テキストエディタ、ターミナルウィンドウの3つのプログラム間を行き来します。
+キーボードファームウェアが完成して満足するまで、この3つすべてを開いたままにします。
+
+ガイドの最初の部分を読んだ後でターミナルウィンドウを閉じて再度開いていた場合は、ターミナルが正しいディレクトリにあるように `cd qmk_firmware` を忘れないでください。
+
+## キーマップフォルダに移動する
+
+あなたのキーボードの `keymaps`フォルダに移動することから始めます。
+
+macOS または Windows を使用している場合は、キーマップフォルダを簡単に開くために使用できるコマンドがあります。
+
+### macOS:
+
+``` open keyboards/<keyboard_folder>/keymaps ```
+
+### Windows:
+
+``` start .\\keyboards\\<keyboard_folder>\\keymaps ```
+
+## `default` キーマップのコピーを作成する
+
+`keymaps` フォルダを開いたら、`default`フォルダのコピーを作成します。
+フォルダには、あなたの GitHub でのユーザー名と同じ名前を付けることを強くお勧めしますが、小文字、数字、アンダースコアのみが含まれている限り、任意の名前を使用できます。
+
+この手順を自動化するために、`new_keymap.sh`スクリプトを実行する方法もあります。
+
+`qmk_firmware/util` ディレクトリに移動して、次を入力します。
+
+```
+./new_keymap.sh <keyboard path> <username>
+```
+
+たとえば、John という名前のユーザーが 1up60hse の新しいキーマップを作成しようとするには、次のように入力します。
+
+```
+./new_keymap.sh 1upkeyboards/1up60hse john
+```
+
+## あなたの好みのテキストエディタで `keymap.c` を開く
+
+`keymap.c`を開きます。
+このファイル内には、キーボードの動作を制御する構造があります。
+`keymap.c`の上部には、キーマップを読みやすくする `define` と `enum` があります。
+さらに下には、次のような行があります。
+
+    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
+
+この行はレイヤーのリストの開始を表わしています。
+その下には、`LAYOUT` または `KEYMAP` のいずれかを含む行があり、これらの行はレイヤーの開始を表わしています。
+その行の下には、その特定のレイヤーを構成するキーのリストがあります。
+
+!> キーマップファイルを編集するときは、カンマを追加したり削除したりしないように注意してください。そうするとファームウェアのコンパイルができなくなり、余分であったり欠落していたりするカンマがどこにあるのかを容易に把握できない場合があります。
+
+## 好みに合わせてレイアウトをカスタマイズ
+
+納得のいくまでこのステップを繰り返します。
+気になる点をひとつづつ変更して試すのもよし、全部作りなおすのもよし。
+あるレイヤー全体が必要ない場合はレイヤーを削除することもでき、必要があれば、合計 32 個までレイヤーを追加することもできます。
+ここで定義できる内容については、次のドキュメントを参照してください。
+
+* [キーコード](keycodes.md)
+* [機能](features.md)
+* [FAQ](faq.md)
+
+?> キーマップがどのように機能するかを感じながら、各変更を小さくしてください。大きな変更は、発生する問題のデバッグを困難にします。
+
+## ファームウェアをビルドする
+
+キーマップの変更が完了したら、ファームウェアをビルドする必要があります。これを行うには、ターミナルウィンドウに戻り、ビルドコマンドを実行します:
+
+    make <my_keyboard>:<my_keymap>
+
+たとえば、キーマップの名前が "xyverz" で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します:
+
+    make planck/rev5:xyverz
+
+これがコンパイルされる間、どのファイルがコンパイルされているかを知らせる多くの出力が画面に表示されます。
+次のような出力で終わるはずです。
+
+```
+Linking: .build/planck_rev5_xyverz.elf                                              [OK]
+Creating load file for flashing: .build/planck_rev5_xyverz.hex                      [OK]
+Copying planck_rev5_xyverz.hex to qmk_firmware folder                               [OK]
+Checking file size of planck_rev5_xyverz.hex                                        [OK]
+ * File size is fine - 18392/28672
+```
+
+## ファームウェアを書きこむ
+
+[「ファームウェアを書きこむ」](newbs_flashing.md) に移動して、キーボードに新しいファームウェアを書き込む方法を学習します。
diff --git a/docs/ja/newbs_building_firmware_configurator.md b/docs/ja/newbs_building_firmware_configurator.md
new file mode 100644
index 000000000..b44504ade
--- /dev/null
+++ b/docs/ja/newbs_building_firmware_configurator.md
@@ -0,0 +1,113 @@
+# QMK Configurator
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: ed0575fc8:docs/newbs_building_firmware_configurator.md
+  git diff ed0575fc8 HEAD docs/newbs_building_firmware_configurator.md | cat
+-->
+
+[QMK Configurator](https://config.qmk.fm) は、QMKファームウェアの hex ファイルを生成するオンライングラフィカルユーザーインターフェイスです。
+
+?> **次の手順を順番に実行してください。**
+
+[Video Tutorial](https://youtu.be/tx54jkRC9ZY) を見てください。
+
+QMK Configurator は Chrome/Firefox で最適に動作します。
+
+!> **KLE や kbfirmware などの他のツールのファイルは、QMK Configurator と互換性がありません。それらをロードしたり、インポートしたりしないでください。QMK Configurator は異なるツールです。**
+
+## キーボードを選ぶ
+
+ドロップダウンボックスをクリックして、キーマップを作成するキーボードを選択します。
+
+?> **キーボードに複数のバージョンがある場合は、正しいバージョンを選択してください。**
+
+大事なことなのでもう一度言います。
+
+!> **正しいバージョンを選択してください!**
+
+キーボードが QMK を搭載していると宣伝されていてもリストにない場合は、開発者がまだ作業中か、私たちがまだマージするきっかけがなかった可能性があります。
+アクティブな [Pull Request](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+is%3Apr+label%3Akeyboard) がない場合、[qmk_firmware](https://github.com/qmk/qmk_firmware/issues)で報告して、その特定のキーボードのサポートをリクエストします。
+製作者自身の github アカウントにある QMK 搭載キーボードもあります。
+それも再確認してください。
+
+## キーボードのレイアウトを選択する
+
+作成したいと思うキーマップに最も近いレイアウトを選択します。一部のキーボードには、まだ十分なレイアウトまたは正しいレイアウトが定義されていません。これらは将来サポートされる予定です。
+
+## キーマップの名前
+
+お好みの名前をキーマップにつけます。
+
+?> コンパイル時に問題が発生した場合は、もしかすると QMK ファームウェアリポジトリに既に同じ名前が存在しているのかもしれません、名前を変更してみてください。
+
+## キーマップを作る
+
+キーコード入力は3つの方法で実行できます。  
+1. ドラッグ・アンド・ドロップ
+2. レイアウト上の空の場所をクリックして、希望するキーコードをクリックします
+3. レイアウト上の空の場所をクリックして、キーボードの物理キーを押します
+
+マウスをキーの上に置くと、そのキーコードの機能の短い説明文が出ます。より詳細な説明については以下を見てください。
+
+[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic)    
+[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes)    
+
+キーマップをサポートするレイアウトが見つからない場合、例えばスペースバーが3分割されていたり、バックスペースが2分割されていたり、シフトが2分割されているような場合、それらを全て埋めてください。
+
+### 例:
+
+3分割のスペースバー: 全てスペースバーで埋めます。
+
+2分割のバックスペース: 両方ともバックスペースで埋めます。
+
+2分割の右シフト: 両方とも右シフトで埋めます。
+
+左シフトとISOサポート用に1つずつ: 両方とも左シフトで埋めます。
+
+5分割だが4キーのみ: 以前やったことがある人を推測して確認するか尋ねてください。
+
+## 後日のためにキーマップを保存する
+
+キーマップに満足するか、または後で作業したい場合は、`Export Keymap' ボタンを押します。上記で選択した名前に .json が追加されたキーマップが保存されます。
+
+後日、`Import Keymap` ボタンを押すことで、この .json ファイルをロードできます。
+
+!> **注意:** このファイルは、kbfirmware.com またはその他のツールに使用される .jsonファイルと同じ形式ではありません。これらのツールにこれを使用したり、QMK Configurator でこれらのツールの .json を使用しようとすると、キーボードが **爆発** する可能性があります。
+
+## ファームウェアファイルを生成する
+
+緑色の `Compile` ボタンを押します。
+
+コンパイルが完了すると、緑色の `Download Firmware` ボタンを押すことができます。
+
+## キーボードに書き込む(フラッシュする)
+
+[ファームウェアを書きこむ](newbs_flashing.md) を参照してください。
+
+## トラブルシューティング
+
+#### 私の .json ファイルが動きません
+
+.json ファイルが QMK Configurator で作ったものの場合、おめでとうございます。バグに遭遇しました。 [qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。
+
+そうでない場合は、... 他の .json ファイルを使用しないようにという、上に書いた注意書きを見逃してませんか？
+
+#### レイアウトに余分なスペースがありますか？どうすればいいですか？
+
+もしスペースバーが3つに分かれている場合は、全てスペースバーで埋めるのが最善の方法です。バックスペースやシフトについても同じことができます。
+
+#### キーコードってなに？
+
+以下を見てください。
+
+[Basic Keycode Reference](https://docs.qmk.fm/#/keycodes_basic)    
+[Advanced Keycode Reference](https://docs.qmk.fm/#/feature_advanced_keycodes)    
+
+#### コンパイルできません
+
+キーマップの他のレイヤーを再確認して、ランダムなキーが存在しないことを確認してください。
+
+## 問題とバグ
+
+私たちは利用者の依頼やバグレポートを常に受け入れています。[qmk_configurator](https://github.com/qmk/qmk_configurator/issues) で報告してください。
diff --git a/docs/ja/newbs_flashing.md b/docs/ja/newbs_flashing.md
new file mode 100644
index 000000000..0c85514cf
--- /dev/null
+++ b/docs/ja/newbs_flashing.md
@@ -0,0 +1,400 @@
+# ファームウェアを書きこむ
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: ed0575fc8:docs/newbs_flashing.md
+  git diff ed0575fc8 HEAD docs/newbs_flashing.md | cat
+-->
+
+カスタムファームウェアは出来たので、キーボードに書き込みたくなるでしょう/フラッシュしたくなるでしょう。
+
+## QMK Toolbox を使ってキーボードに書き込む
+
+キーボードに書き込む最も簡単な方法は [QMK Toolbox](https://github.com/qmk/qmk_toolbox/releases) を使うことです。
+
+ただし、QMK Toolbox は、現在は Windows と macOS でしか使えません。
+Linuxを使用している場合(および、コマンドラインでファームウェアを書き込みたい場合)は、下の方で概説する[方法](newbs_flashing.md#コマンドラインでファームウェアを書き込む)で行なう必要があります。
+
+### QMK Toolbox にファイルをロードする
+
+まず QMK Toolbox アプリケーションを起動します。
+Finder またはエクスプローラーでファームウェアのファイルを探します。
+ファイル名は `.hex` または `.bin` のどちらかの形式です。
+ビルド時に QMK は、キーボードに適した形式のものを `qmk_firmware` のトップフォルダにコピーしているはずです。
+
+Windows か macOS を使用しているときは現在のファームウェアフォルダをエクスプローラーか Finder で簡単に開くためのコマンドがあります。
+
+#### Windows
+
+```
+start .
+```
+
+#### macOS
+
+```
+open .
+```
+
+ファームウェアファイルは常に以下の命名形式に従っています。
+
+```
+<keyboard_name>_<keymap_name>.{bin,hex}
+```
+
+例えば、`plank/rev5` の `default` キーマップのファイル名は以下のようになります。
+
+```
+planck_rev5_default.hex
+```
+
+ファームウェアファイルを見つけたら、QMK Toolbox の "Local file" ボックスにドラッグするか、"Open" をクリックしてファームウェアファイルを指定します。
+
+### キーボードを DFU (Bootloader) モードにする
+
+ファームウェアを書き込むには、キーボードを普段とは違う特別な状態、フラッシュモードにする必要があります。
+このモードでは、キーボードはキーボードとしての機能をはたしません。
+ファームウェアの書き込み中にキーボードのケーブルを抜いたり、書き込みプロセスを中断したりしないことが非常に重要です。
+
+キーボードによって、この特別なモードに入る方法は異なります。
+キーボードが現在 QMK または TMK を実行しており、キーボードメーカーから具体的な指示が与えられていない場合は、次を順番に試してください。
+
+* 両方のシフトキーを押しながら、`Pause` キーを押す
+* 両方のシフトキーを押しながら、`B` キーを押す
+* キーボードのケーブルを抜いて、スペースバーとBを同時に押しながら、キーボードを再び接続し、1秒待ってからキーを放す
+* 基板(PCB)に付けられている物理的な `RESET` ボタンを押す
+* PCB 上の `BOOT0` か `RESET` のラベルの付いたヘッダピンを探し、PCB 接続中にそれらを互いにショートする
+
+うまくいけば、QMK Toolboxに次のようなメッセージが表示されます。
+
+```
+*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
+*** DFU device connected
+```
+
+### キーボードへの書き込み
+
+QMK Toolbox の `Flash` ボタンをクリックします。
+次のような出力が表示されます。
+
+```
+*** Clueboard - Clueboard 66% HotSwap disconnected -- 0xC1ED:0x2390
+*** DFU device connected
+*** Attempting to flash, please don't remove device
+>>> dfu-programmer atmega32u4 erase --force
+    Erasing flash...  Success
+    Checking memory from 0x0 to 0x6FFF...  Empty.
+>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
+    Checking memory from 0x0 to 0x55FF...  Empty.
+    0%                            100%  Programming 0x5600 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    0%                            100%  Reading 0x7000 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    Validating...  Success
+    0x5600 bytes written into 0x7000 bytes memory (76.79%).
+>>> dfu-programmer atmega32u4 reset
+    
+*** DFU device disconnected
+*** Clueboard - Clueboard 66% HotSwap connected -- 0xC1ED:0x2390
+```
+
+## コマンドラインでファームウェアを書き込む
+
+これは、以前のものと比較して非常に単純になりました。
+ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+
+    make <my_keyboard>:<my_keymap>:flash
+
+たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。
+
+    make planck/rev5:xyverz:flash
+
+これにより、キーボードの構成が確認され、指定されたブートローダに基づいてキーボードへの書き込みが試行されます。
+これはあなたがキーボードが使用するブートローダを知る必要がないことを意味します。
+コマンドをただ実行して、コマンド自身に難しい処理を任せます。
+
+ただし、これはキーボードごとに設定されているブートローダに依存します。
+もしこの情報が設定されていない場合、または使用しているキーボードのファームウェアの書き込みにサポートしていないターゲットが設定されている場合、次のエラーが表示されます。
+
+    WARNING: This board's bootloader is not specified or is not supported by the ":flash" target at this time.
+
+この場合、あなたは明示的にブートローダを指定する方法を使わなければなりません。
+
+ブートローダは主に 5 種類のものが使われています。
+Pro Micro とそのクローンは Caterina を、Teensy は HalfKay を、OLKBの AVR ボードは QMK-DFU を、その他の ATmega32U4 ボードは DFU を、そして多くの ARM ボードは ARM DFU を使います。
+
+より詳しいブートローダの情報は、[Flashing Instructions and Bootloader Information](flashing.md) にあります。
+
+使用しているブートローダがわかっているならば、ファームウェアをコンパイルするときに、実は `make` コマンドにブートローダを指定するテキストを追加して、書き込みプロセスを自動化できます。
+
+### DFU
+
+DFU ブートローダの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+
+    make <my_keyboard>:<my_keymap>:dfu
+
+たとえば、キーマップの名前が xyverz で、rev5 planck のキーマップを作成している場合、次のコマンドを使用します。
+
+    make planck/rev5:xyverz:dfu
+
+コンパイルが終了すると、以下の出力になるはずです。
+
+```
+Linking: .build/planck_rev5_xyverz.elf                                          [OK]
+Creating load file for flashing: .build/planck_rev5_xyverz.hex                  [OK]
+Copying planck_rev5_xyverz.hex to qmk_firmware folder                           [OK]
+Checking file size of planck_rev5_xyverz.hex
+ * File size is fine - 18574/28672
+ ```
+
+ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。
+デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。
+
+    dfu-programmer: no device present.
+    Error: Bootloader not found. Trying again in 5s.
+
+これを実行したら、コントローラーをリセットする必要があります。
+そして下のような出力が表示されます。
+
+```
+*** Attempting to flash, please don't remove device
+>>> dfu-programmer atmega32u4 erase --force
+    Erasing flash...  Success
+    Checking memory from 0x0 to 0x6FFF...  Empty.
+>>> dfu-programmer atmega32u4 flash /Users/skully/qmk_firmware/clueboard_66_hotswap_gen1_skully.hex
+    Checking memory from 0x0 to 0x55FF...  Empty.
+    0%                            100%  Programming 0x5600 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    0%                            100%  Reading 0x7000 bytes...
+    [>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>]  Success
+    Validating...  Success
+    0x5600 bytes written into 0x7000 bytes memory (76.79%).
+>>> dfu-programmer atmega32u4 reset
+```
+
+?> `dfu-programmer：no device present` など、これに関する問題がある場合は、[よくある質問](faq_build.md) を参照してください。
+
+#### 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 ボードとそれらのクローンの場合(たとえば SparkFun ProMicro)、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+
+    make <my_keyboard>:<my_keymap>:avrdude
+
+たとえば、キーマップの名前が xyverz で、rev2 Lets Split のキーマップを作成している場合、次のコマンドを使用します。
+
+    make lets_split/rev2:xyverz:avrdude
+
+ファームウェアのコンパイルが完了すると、以下のように出力されます。
+
+```
+Linking: .build/lets_split_rev2_xyverz.elf                                      [OK]
+Creating load file for flashing: .build/lets_split_rev2_xyverz.hex              [OK]
+Checking file size of lets_split_rev2_xyverz.hex                                [OK]
+ * File size is fine - 27938/28672
+Detecting USB port, reset your controller now..............
+```
+
+この時点で、キーボードをリセットすると、スクリプトがブートローダを検出し、キーボードに書き込みます。出力は次のようになります。
+
+```
+Detected controller on USB port at /dev/ttyS15
+
+Connecting to programmer: .
+Found programmer: Id = "CATERIN"; type = S
+    Software Version = 1.0; No Hardware Version given.
+Programmer supports auto addr increment.
+Programmer supports buffered memory access with buffersize=128 bytes.
+
+Programmer supports the following devices:
+    Device code: 0x44
+
+avrdude.exe: AVR device initialized and ready to accept instructions
+
+Reading | ################################################## | 100% 0.00s
+
+avrdude.exe: Device signature = 0x1e9587 (probably m32u4)
+avrdude.exe: NOTE: "flash" memory has been specified, an erase cycle will be performed
+             To disable this feature, specify the -D option.
+avrdude.exe: erasing chip
+avrdude.exe: reading input file "./.build/lets_split_rev2_xyverz.hex"
+avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
+avrdude.exe: writing flash (27938 bytes):
+
+Writing | ################################################## | 100% 2.40s
+
+avrdude.exe: 27938 bytes of flash written
+avrdude.exe: verifying flash memory against ./.build/lets_split_rev2_xyverz.hex:
+avrdude.exe: load data flash data from input file ./.build/lets_split_rev2_xyverz.hex:
+avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex auto detected as Intel Hex
+avrdude.exe: input file ./.build/lets_split_rev2_xyverz.hex contains 27938 bytes
+avrdude.exe: reading on-chip flash data:
+
+Reading | ################################################## | 100% 0.43s
+
+avrdude.exe: verifying ...
+avrdude.exe: 27938 bytes of flash verified
+
+avrdude.exe: safemode: Fuses OK (E:CB, H:D8, L:FF)
+
+avrdude.exe done.  Thank you.
+```
+うまくいかない時は、以下のようにする必要があるかもしれません。
+
+    sudo make <my_keyboard>:<my_keymap>:avrdude
+
+
+#### Caterina コマンド
+
+ファームウェアを DFU デバイスに書き込むために使用できる DFU コマンドがいくつかあります。
+
+* `:avrdude` - これが通常のオプションで、Caterina デバイスが(新しい COM ポートを検出して)使用可能になるまで待機し、ファームウェアを書き込みます。
+* `:avrdude-loop` - これは `:avrdude` と同じです。ただし書き込みが終了すると再び Caterina デバイスの書き込み待ちに戻ります。これは何台ものデバイスへの書き込みに便利です。_Control+C を押して、手動でこの繰り返しを終了させる必要があります。_
+* `:avrdude-split-left` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「左側の」EEPROMファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
+* `:avrdude-split-right` - デフォルトオプション(`:avrdude`)と同様に通常のファームウェアが書き込まれます。ただし、分割キーボードの「右側の」EEPROMファイルもフラッシュされます。 _これは、Pro Micro ベースの分割キーボードに最適です。_
+
+### HalfKay
+
+PJRC デバイス(Teensy シリーズ)の場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+
+    make <my_keyboard>:<my_keymap>:teensy
+
+たとえば、キーマップの名前が xyverz で、Ergodox または Ergodox EZ のキーマップを作成している場合、次のコマンドを使用します。
+
+    make ergodox_ez:xyverz:teensy
+
+ファームウェアのコンパイルが完了すると、以下のように出力されます。
+
+```
+Linking: .build/ergodox_ez_xyverz.elf                                            [OK]
+Creating load file for flashing: .build/ergodox_ez_xyverz.hex                    [OK]
+Checking file size of ergodox_ez_xyverz.hex                                      [OK]
+ * File size is fine - 25584/32256
+ Teensy Loader, Command Line, Version 2.1
+Read "./.build/ergodox_ez_xyverz.hex": 25584 bytes, 79.3% usage
+Waiting for Teensy device...
+ (hint: press the reset button)
+ ```
+
+この時点で、キーボードをリセットします。すると、次のような出力が表示されます。
+
+ ```
+ Found HalfKay Bootloader
+Read "./.build/ergodox_ez_xyverz.hex": 28532 bytes, 88.5% usage
+Programming............................................................................................................................................................................
+...................................................
+Booting
+```
+
+### STM32 (ARM)
+
+主な ARM ボード (Proton C, Planck Rev 6, Preonic Rev 3 を含む)の場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+
+    make <my_keyboard>:<my_keymap>:dfu-util
+
+たとえば、キーマップの名前が xyverz で、Planck Revision 6 のキーマップを作成している場合、次のコマンドを使用し、(コンパイルが終わる前に)キーボードを再起動してブートローダを起動します:
+
+    make planck/rev6:xyverz:dfu-util
+
+ファームウェアのコンパイルが完了すると、以下のように出力されます。
+
+```
+Linking: .build/planck_rev6_xyverz.elf                                          [OK]
+Creating binary load file for flashing: .build/planck_rev6_xyverz.bin           [OK]
+Creating load file for flashing: .build/planck_rev6_xyverz.hex                  [OK]
+
+Size after:
+   text    data     bss     dec     hex filename
+      0   41820       0   41820    a35c .build/planck_rev6_xyverz.hex
+
+Copying planck_rev6_xyverz.bin to qmk_firmware folder                           [OK]
+dfu-util 0.9
+
+Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
+Copyright 2010-2016 Tormod Volden and Stefan Schmidt
+This program is Free Software and has ABSOLUTELY NO WARRANTY
+Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+Invalid DFU suffix signature
+A valid DFU suffix will be required in a future dfu-util release!!!
+Opening DFU capable USB device...
+ID 0483:df11
+Run-time device DFU version 011a
+Claiming USB DFU Interface...
+Setting Alternate Setting #0 ...
+Determining device status: state = dfuERROR, status = 10
+dfuERROR, clearing status
+Determining device status: state = dfuIDLE, status = 0
+dfuIDLE, continuing
+DFU mode device DFU version 011a
+Device returned transfer size 2048
+DfuSe interface name: "Internal Flash  "
+Downloading to address = 0x08000000, size = 41824
+Download        [=========================] 100%        41824 bytes
+Download done.
+File downloaded successfully
+Transitioning to dfuMANIFEST state
+```
+
+#### 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 ユーティリティを介してファームウェアを書き込めます。
+
+### BootloadHID
+
+Bootmapper Client(BMC)/bootloadHID/ATmega32A ベースのキーボードの場合、ファームウェアをコンパイルして書き込む準備ができたら、ターミナルウィンドウを開いてビルドコマンドを実行します。
+
+    make <my_keyboard>:<my_keymap>:bootloaderHID
+
+たとえば、キーマップの名前が xyverz で、jj40 のキーマップを作成している場合、次のコマンドを使用します。
+
+    make jj40:xyverz:bootloaderHID
+
+ファームウェアのコンパイルが完了すると、以下のように出力されます。
+
+```
+Linking: .build/jj40_default.elf                                                [OK]
+Creating load file for flashing: .build/jj40_default.hex                        [OK]
+Copying jj40_default.hex to qmk_firmware folder                                 [OK]
+Checking file size of jj40_default.hex                                          [OK]
+ * The firmware size is fine - 21920/28672 (6752 bytes free)
+```
+
+ここまでくると、ビルドスクリプトは5秒ごとに DFU ブートローダを探します。
+デバイスが見つかるか、あなたがキャンセルするまで、以下を繰り返します。
+
+```
+Error opening HIDBoot device: The specified device was not found
+Trying again in 5s.
+```
+
+これを実行したら、コントローラーをリセットする必要があります。
+そして下のような出力が表示されます。
+
+```
+Page size   = 128 (0x80)
+Device size = 32768 (0x8000); 30720 bytes remaining
+Uploading 22016 (0x5600) bytes starting at 0 (0x0)
+0x05580 ... 0x05600
+```
+
+## テストしましょう！
+
+おめでとうございます！ カスタムファームウェアがキーボードにプログラムされました！
+
+使ってみて、すべてがあなたの望むように動作するかどうか確認してください。
+この初心者ガイドを完全なものにするために [テストとデバッグ](newbs_testing_debugging.md) を書いたので、カスタム機能のトラブルシューティング方法については、こちらをご覧ください。
diff --git a/docs/ja/newbs_getting_started.md b/docs/ja/newbs_getting_started.md
new file mode 100644
index 000000000..a57e6e054
--- /dev/null
+++ b/docs/ja/newbs_getting_started.md
@@ -0,0 +1,122 @@
+# イントロダクション
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: docs/newbs_getting_started.md
+  git diff 161d469 HEAD docs/newbs_getting_started.md | cat
+-->
+
+キーボードにはプロセッサが入っており、それはコンピュータに入っているものと大して違わないものです。
+このプロセッサでは、キーボードのボタンの押し下げの検出を担当しキーボードのどのボタンが押されている/離されているかのレポートをコンピュータに送信するソフトウェアが動作しています。
+QMK は、そのソフトウェアの役割を果たし、ボタンの押下を検出しその情報をホストコンピュータに渡します。
+カスタムキーマップを作るということは、キーボード上で動くプログラムを作るということなのです。
+
+QMK は、簡単なことは簡単に、そして、難しいことを可能なことにすることで、あなたの手にたくさんのパワーをもたらします。
+パワフルなキーマップを作るためにプログラムを作成する方法を知る必要はありません。いくつかのシンプルな文法に従うだけでOKです。
+
+# はじめに
+
+キーマップをビルドする前に、いくつかのソフトウェアをインストールしてビルド環境を構築する必要があります。
+ファームウェアをコンパイルするキーボードの数に関わらず、この作業を一度だけ実行する必要があります。
+
+もし、GUI で作業をしたい場合、オンラインで作業できる [QMK Configurator](https://config.qmk.fm) を使ってください。
+使い方は [Building Your First Firmware using the online GUI](newbs_building_firmware_configurator.md) を参照してください。
+
+## ソフトウェアのダウンロード
+
+### テキストエディタ
+
+GUI を使わない場合、プレーンテキストを編集・保存できるエディタが必要です。
+Windows の場合、メモ帳が使えます。Linux の場合、gedit が使えます。
+どちらもシンプルですが機能的なテキストエディタです。
+macOS では、デフォルトのテキストエディットアプリに注意してください。_フォーマット_ メニューから _標準テキストにする_ を選択しない限り、プレーンテキストとして保存されません。
+
+[Sublime Text](https://www.sublimetext.com/) や [VS Code](https://code.visualstudio.com/) のような専用のテキストエディタをダウンロードしてインストールすることもできます。これらのプログラムはコードを編集するために特別に作成されているため、これはプラットフォームに関係なくベストな方法です。
+
+?> どのエディタを使えば良いか分からない場合、Laurence Bradford が書いたこの記事 [a great introduction](https://learntocodewith.me/programming/basics/text-editors/) を読んでください。
+
+### QMK Toolbox
+
+QMK Toolbox は、Windows と macOS で使える GUI を備えたプログラムで、カスタムキーボードのプログラミングとデバッグの両方ができます。
+このプログラムは、キーボードに簡単にファームウェアを書き込んだり、出力されるデバッグメッセージを確認する際に、かけがえのないものであることがわかるでしょう。
+
+[QMK Toolbox の最新版](https://github.com/qmk/qmk_toolbox/releases/latest)
+
+* Windows 版: `qmk_toolbox.exe` (portable) または `qmk_toolbox_install.exe` (installer)
+* macOS 版: `QMK.Toolbox.app.zip` (portable) または `QMK.Toolbox.pkg` (installer)
+
+## 環境構築
+
+私たちは、QMK を可能な限り簡単に構築できるように努力しています。
+Linux か Unix 環境を用意するだけで、QMK に残りをインストールさせることができます。
+
+?> もし、Linux か Unix のコマンドを使ったことがない場合、こちらで基本的な概念や各種コマンドを学んでください。これらの教材で QMK を使うのに必要なことを学ぶことができます。
+
+[Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
+[Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
+
+### Windows
+
+MSYS2 と Git のインストールが必要です。
+
+* [MSYS2 homepage](http://www.msys2.org) の手順に従って MSYS2 をインストールします。
+* 開いている MSYS2 の全ターミナル画面を閉じて、新しい MSYS2 MinGW 64-bit のターミナル画面を開きます。
+* `pacman -S git` を実行して Git をインストールします。
+
+### macOS
+
+[Homebrew homepage](https://brew.sh) の手順に従って Homebrew をインストールしてください。
+
+Homebrew をインストールしたら、以下の _QMK の設定_ に進んでください。そのステップでは、他のパッケージをインストールするスクリプトを実行します。
+
+### Linux
+
+Git のインストールが必要です。既にインストールされている可能性は高いですが、そうでない場合、次のコマンドでインストールできます。
+
+* Debian / Ubuntu / Devuan: `apt-get install git`
+* Fedora / Red Hat / CentOS: `yum install git`
+* Arch: `pacman -S git`
+
+?> 全てのプラットフォームにおいて、Docker を使うことも可能です。[詳細はこちらをクリックしてください](getting_started_build_tools.md#docker)。
+
+## QMK の設定
+
+Linux/Unix 環境が準備できたら QMK のダウンロードの準備は完了です。Git を使用して QMK のリポジトリを「クローン」することで QMK をダウンロードします。ターミナルか MSYS2 MinGW ウィンドウを開いて、このガイドの残りの部分では開いたままにします。そのウィンドウ内で、次の2つのコマンドを実行します。
+
+```shell
+git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
+cd qmk_firmware
+```
+
+?> 既に [GitHub の使いかた](getting_started_github.md)を知っているなら、clone ではなく fork を勧めます。この一文の意味が分からない場合、このメッセージは無視してかまいません。
+
+QMK には、必要な残りの設定を手助けするスクリプトが含まれています。
+セットアップ作業を完了させるため、次のコマンドを実行します。
+
+    util/qmk_install.sh
+
+## ビルド環境の確認
+
+これで QMK のビルド環境が用意できましたので、キーボードのファームウェアをビルドできます。
+キーボードのデフォルトキーマップをビルドすることから始めます。次の形式のコマンドでビルドできるはずです。
+
+    make <keyboard>:default
+
+例）Clueboard 66% のファームウェアをビルドする
+
+    make clueboard/66/rev3:default
+
+大量の出力の最後に次のように出力されると完了です。
+
+```
+Linking: .build/clueboard_66_rev3_default.elf                                     [OK]
+Creating load file for flashing: .build/clueboard_66_rev3_default.hex             [OK]
+Copying clueboard_66_rev3_default.hex to qmk_firmware folder                      [OK]
+Checking file size of clueboard_66_rev3_default.hex                               [OK]
+ * The firmware size is fine - 26356/28672 (2316 bytes free)
+```
+
+# キーマップの作成
+
+これであなた専用のキーマップを作成する準備ができました！
+次は [Building Your First Firmware](newbs_building_firmware.md) で専用のキーマップを作成します。
diff --git a/docs/ja/newbs_learn_more_resources.md b/docs/ja/newbs_learn_more_resources.md
new file mode 100644
index 000000000..632cd9100
--- /dev/null
+++ b/docs/ja/newbs_learn_more_resources.md
@@ -0,0 +1,32 @@
+# 学習リソース
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: ed0575fc8:docs/newbs_learn_more_resources.md
+  git diff ed0575fc8 HEAD docs/newbs_learn_more_resources.md | cat
+-->
+
+これらのリソースは、QMKコミュニティの新しいメンバーに、初心者向けドキュメントで提供されている情報に対する理解を深めることを目的としています。
+
+## Git に関するリース:
+
+### 英語
+
+* [Great General Tutorial](https://www.codecademy.com/learn/learn-git)
+* [Git Game To Learn From Examples](https://learngitbranching.js.org/)
+* [Git Resources to Learn More About Github](getting_started_github.md)
+* [Git Resources Aimed Specifically toward QMK](contributing.md)
+
+### 日本語
+
+_日本語のリソース情報を募集中です。_
+
+## コマンドラインに関するリソース:
+
+### 英語
+
+* [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line)
+
+### 日本語
+
+_日本語のリソース情報を募集中です。_
diff --git a/docs/ja/newbs_testing_debugging.md b/docs/ja/newbs_testing_debugging.md
new file mode 100644
index 000000000..a96406187
--- /dev/null
+++ b/docs/ja/newbs_testing_debugging.md
@@ -0,0 +1,107 @@
+# テストとデバッグ
+
+<!---
+  grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh
+  original document: ed0575fc8:docs/newbs_testing_debugging.md
+  git diff ed0575fc8 HEAD docs/newbs_testing_debugging.md | cat
+-->
+
+カスタムファームウェアをキーボードへ書き込んだら、テストする準備が整います。運が良ければ全て問題なく動作しているはずですが、もしそうでなければこのドキュメントがどこが悪いのか調べるのに役立ちます。
+
+## テスト
+
+通常、キーボードをテストするのは非常に簡単です。全てのキーをひとつずつ押して、期待されるキーが送信されていることを確認します。キーを押したことを見逃さないためのプログラムもあります。
+
+メモ：　これらのプログラムはQMKによって提供・承認されたものではありません。
+
+* [QMK Configurator](https://config.qmk.fm/#/test/) (Web Based)
+* [Switch Hitter](https://web.archive.org/web/20190413233743/https://elitekeyboards.com/switchhitter.php) (Windows Only)
+* [Keyboard Viewer](https://www.imore.com/how-use-keyboard-viewer-your-mac) (Mac Only)
+* [Keyboard Tester](http://www.keyboardtester.com) (Web Based)
+* [Keyboard Checker](http://keyboardchecker.com) (Web Based)
+
+## デバッグ
+
+`rules.mk`へ`CONSOLE_ENABLE = yes`の設定をするとキーボードはデバッグ情報を出力します。デフォルトの出力は非常に限られたものですが、デバッグモードをオンにすることでデバッグ情報の量を増やすことが出来ます。キーマップの`DEBUG`キーコードを使用するか、デバッグモードを有効にする [Command](feature_command.md) 機能を使用するか、以下のコードをキーマップに追加します。
+
+```c
+void keyboard_post_init_user(void) {
+  // Customise these values to desired behaviour
+  debug_enable=true;
+  debug_matrix=true;
+  //debug_keyboard=true;
+  //debug_mouse=true;
+}
+```
+
+### QMK Toolboxを使ったデバッグ
+
+互換性のある環境では、[QMK Toolbox](https://github.com/qmk/qmk_toolbox)を使うことでキーボードからのデバッグメッセージを表示できます。
+
+### hid_listenを使ったデバッグ
+
+ターミナルベースの方法がお好みですか？PJRCが提供する[hid_listen](https://www.pjrc.com/teensy/hid_listen.html)もデバッグメッセージの表示に使用できます。ビルド済みの実行ファイルはWindows, Linux, MacOS用が用意されています。
+
+<!-- FIXME: Describe the debugging messages here. -->
+
+## 独自のデバッグメッセージを送信する
+
+[custom code](custom_quantum_functions.md)内からデバッグメッセージを出力すると便利な場合があります。それはとても簡単です。ファイルの先頭に`print.h`のインクルードを追加します:
+
+    #include <print.h>
+
+そのあとは、いくつかの異なったprint関数を使用することが出来ます。
+
+* `print("string")`: シンプルな文字列を出力します
+* `uprintf("%s string", var)`: フォーマットされた文字列を出力します
+* `dprint("string")` デバッグモードが有効な場合のみ、シンプルな文字列を出力します
+* `dprintf("%s string", var)`: デバッグモードが有効な場合のみ、フォーマットされた文字列を出力します
+
+## デバッグの例
+
+以下は現実世界での実際のデバッグ手法の例を集めたものです。追加情報は[Debugging/Troubleshooting QMK](faq_debug.md)を参照してください。
+
+### マトリックス上のどの場所でキー押下が起こったか？
+
+移植する、PCBの問題を診断する場合、キー入力が正しくスキャンされているかどうかを確認することが役立つ場合があります。この手法でのロギングを有効化するには、`keymap.c`へ以下のコードを追加します。
+
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  // コンソールが有効化されている場合、マトリックス上の位置とキー押下状態を出力します
+#ifdef CONSOLE_ENABLE
+    uprintf("KL: kc: %u, col: %u, row: %u, pressed: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed);
+#endif 
+  return true;
+}
+```
+
+出力の例
+```text
+Waiting for device:.......
+Listening:
+KL: kc: 169, col: 0, row: 0, pressed: 1
+KL: kc: 169, col: 0, row: 0, pressed: 0
+KL: kc: 174, col: 1, row: 0, pressed: 1
+KL: kc: 174, col: 1, row: 0, pressed: 0
+KL: kc: 172, col: 2, row: 0, pressed: 1
+KL: kc: 172, col: 2, row: 0, pressed: 0
+```
+
+### キースキャンにかかる時間の測定
+
+パフォーマンスの問題をテストする場合、スイッチマトリックスをスキャンする頻度を知ることが役立ちます。この手法でのロギングを有効化するには`config.h`へ以下のコードを追加します。
+
+
+```c
+#define DEBUG_MATRIX_SCAN_RATE
+```
+
+出力例
+```text
+  > matrix scan frequency: 315
+  > matrix scan frequency: 313
+  > matrix scan frequency: 316
+  > matrix scan frequency: 316
+  > matrix scan frequency: 316
+  > matrix scan frequency: 316
+```