Update ja document

docs/ja/mutations.md

@@ -1,6 +1,6 @@
 # ミューテーション
 
-Vuex のミューテーションは基本的にイベントです。各ミューテーションは**名前**と**ハンドラ**を持ちます。ハンドラ関数は常に全体のステートツリーを第1引数として取得します:
+Vuex のミューテーションは本質的にイベントです。各ミューテーションは**名前**と**ハンドラ**を持ちます。ハンドラ関数は常に Vuex のstateを第1引数として取得します:
 
 ``` js
 import Vuex from 'vuex'
@@ -11,24 +11,24 @@ const store = new Vuex.Store({
   },
   mutations: {
     INCREMENT (state) {
-      // 変異するステート
+      // 状態の変更
       state.count++
     }
   }
 })
 ```
 
-ミューテーション名に対して全て大文字を使用するのは、容易にアクションと区別できるようにするための規則です。
+ミューテーションの名前に全て大文字を使用するのは、容易に通常の関数と区別できるようにするための規約です。
 
-直接ミューテーションハンドラ呼び出すことはできません。ここでのオプションは、よりイベント登録のようなものです。"`INCREMENT` イベントがディスパッチされるとき、このハンドラは呼ばれます。"ミューテーションハンドラを起動するためには、ミューテーションイベントをディスパッチする必要があります:
+直接ミューテーションハンドラを呼び出すことはできません。このmutationsオプションは、よりイベント登録のようなものです: "`INCREMENT` イベントがディスパッチされるとき、このハンドラが呼ばれる" ミューテーションハンドラを起動するためには、ミューテーションイベントをディスパッチする必要があります:
 
 ``` js
 store.dispatch('INCREMENT')
 ```
 
 ### 引数によるディスパッチ
 
-引数に沿って渡すことも可能です:
+引数を渡すことも可能です:
 
 ``` js
 // ...
@@ -42,27 +42,75 @@ mutations: {
 store.dispatch('INCREMENT', 10)
 ```
 
-ここの `10` は `state` に続く第2引数としてミューテーションハンドラに渡されます。任意の追加引数と同じです。これら引数は、特定のミューテーションに対して**ペイロード**と呼ばれています。
+ここでの `10` は `state` に続く第2引数としてミューテーションハンドラに渡されます。さらに追加される引数についても同様です。これらの引数は、特定のミューテーションに対する**ペイロード**と呼びます。
 
-### Vue のリアクティブなルールに従うミューテーション
+### オブジェクトスタイルのディスパッチ
 
-Vuex store のステートは Vue によってリアクティブになっているので、ステートを変異するとき、ステートを監視している Vue コンポーネントは自動的に更新されます。これはまた、Vuex のミューテーションは、純粋な Vue で動作しているとき、同じリアクティブな警告の対象となっているのを意味します:
+またオブジェクトを利用してミューテーションをディスパッチすることもできます:
 
-1. 前もって全て望まれるフィールドによって、あなたの store の初期ステートを初期化することを好みます
+```js
+store.dispatch({
+  type: 'INCREMENT',
+  payload: 10
+})
+```
 
-2. 新しいプロパティをオブジェクトに追加するとき、いずれか必要です:
+オブジェクトスタイルを利用するとき、全ての引数をディスパッチされるオブジェクトのプロパティとして含めなければいけないことに注意してください。全体のオブジェクトは、ミューテーションハンドラの第2引数として渡されます。
 
-  - `Vue.set(obj, 'newProp', 123)` を使用または -
+``` js
+mutations: {
+  INCREMENT (state, mutation) {
+    state.count += mutation.payload
+  }
+}
+```
 
-  - 全く新しいものでオブジェクトを置き換える。例えば、stage-2 の [object spread syntax](https://github.com/sebmarkbage/ecmascript-rest-spread) を使用して、このようにそれを書くことができます:
+### サイレントディスパッチ
+
+場合によっては、プラグインに状態の変化を記録して欲しくないかもしれません。あるいは、短い間隔、ポーリングでのストアへの複数のディスパッチも、常に追跡する必要はないでしょう。これらの状況では、ミューテーションを沈黙( silence )させることが適切であると考えることができます。
+
+Note: サイレントディスパッチは可能な限り避けるべきです。サイレントミューテーションは、開発ツールの全ての状態の変更を追跡するという規約を壊します。絶対に必要だという状況で控えめに使用してください。
+
+``` js
+/**
+ * 例: プログレス アクション
+ * 追跡する必要がない変更を頻繁に送ります
+ **/
+export function start(store, options = {}) {
+  let timer = setInterval(() => {
+    store.dispatch({
+      type: INCREMENT,
+      silent: true,
+      payload: {
+        amount: 1,
+      },
+    });
+    if (store.state.progress === 100) {
+      clearInterval(timer);
+    }
+  }, 10);
+}
+```
+
+### Vue のリアクティブなルールに則ったミューテーション
+
+Vuex store のステートは Vue によってリアクティブになっているので、ステートを変更すると、ステートを監視している Vue コンポーネントは自動的に更新されます。これは、Vuex のミューテーションは、通常の Vue で動作させているときと同じリアクティブな警告の対象となることを意味します:
+
+1. 前もって、全ての必要なフィールドによって、ストアの初期状態を初期化することを好みます
+
+2. 新しいプロパティをオブジェクトに追加するとき、以下のいずれかが必要です:
+
+  - `Vue.set(obj, 'newProp', 123)` を使用するか -
+
+  - 全く新しいオブジェクトで既存のオブジェクトを置き換える。例えば、stage-2 の [object spread syntax](https://github.com/sebmarkbage/ecmascript-rest-spread) を使用して、以下のように書くことができます:
 
   ``` js
   state.obj = { ...state.obj, newProp: 123 }
   ```
 
-### ミューテーション名に対して定数を使用
+### ミューテーション名に定数を使用する
 
-ミューテーション名には定数を使用することが一般的です。コードに対してリンタのようなツールの長所を利用することができ、そして、単一ファイルに全ての定数を設定することは、あなたの協力者にミューテーションがアプリケーション全体で可能であるかが一目見ただけで理解できるビューを得ることができます:
+ミューテーション名には定数を使用することが一般的です。これは、コードに対してリントツールのようなツールを利用できるという利点があり、また、単一ファイルに全ての定数を設定することで、共同で作業する人にアプリケーション全体で何のミューテーションが可能であるか一目見ただけで理解できるようにします:
 
 ``` js
 // mutation-types.js
@@ -86,10 +134,24 @@ const store = new Vuex.Store({
 })
 ```
 
-定数を使用するかどうか大部分が好みであり、それは多くの開発者による大規模アプリケーションで役に立ちますが、好きではないならば、それは完全にオプションです。
+定数を使用するかどうか大抵は好みであり、多くの開発者による大規模アプリケーションで役に立ちますが、もし好きではないならば、それは完全にオプションです。
+
+### ミューテーションは同期的でなければならない
+
+ひとつの重要なルールを覚えておきましょう。それは、ミューテーションハンドラ関数は同期的でなければならないということです。なぜか？ 次の例で考えてみましょう:
+
+```js
+mutations: {
+  SOME_MUTATION (state) {
+    api.callAsyncMethod(() => {
+      state.count++
+    })
+  }
+}
+```
 
-### アクションの上へ
+いま、ミューテーションのログを見て、アプリケーションのデバッグを行っていることを想像してください。全てのミューテーションはログに記録されていて、ミューテーションの前後の状態のスナップショットを比較することが可能です。しかし、例のミューテーション内の非同期コールバックは、それを不可能にします: そのコールバックは、ミューテーションがディスパッチされたときにまだ呼ばれません。そして、コールバックが実際いつ呼ばれるかは分かりません。いかなる状態変更でも、コールバック内で起きる場合は本質的に追跡不可能です。
 
-これまでのところ、`store.dispatch` の手動呼び出しによってミューテーションをトリガしていました。これは実行可能なアプローチですが、実際には私たちのコンポーネントのコードでこれを行うことはほとんどありません。ほとんどの時間、[アクション](actions.md) を呼び出し、非同期データフェッチングのようなより複雑なロジックをカプセル化することができます。
+### アクションに続けて
 
-また、全てのミューテーションハンドラは**同期**でなければならないという、1つ重要なルールを覚えておきましょう。任意の非同期な操作はアクションに属しています。
+状態変更を非同期に組み合わせることは、プログラムの動きを予測することを非常に困難にするかもしれません。例えば、状態を変更する非同期コールバックを持った2つのメソッドを両方呼び出しとき、どうやってそれらが呼び出されたか、先に呼び出されたかのはどちらかを知ればよいのでしょう？ 2つの概念を分離したい理由は明確です。 Vuex では、全ての状態変更は同期的におこなうという作法になっています。全ての非同期命令は [アクション](actions.md) の内部でおこなうことになるでしょう。