Merge pull request #445 from seratch/migration-guide-ja

Add Japanese version to PR #442

docs/_advanced/ja_error_handling.md

@@ -6,9 +6,9 @@ order: 1
 ---
 
 <div class="section-content">
-リスナーの中でエラーが発生した場合は、リスナー内で直接ハンドリングすることが望ましいでしょう。しかし、リスナーがすでに return した後でエラーが発生する場合もあります。 (`say()` または `respond()` を呼び出した場合や、必要なときに `ack()` を呼び出さなかった場合など)。このようなエラーはデフォルトではコンソールにログ出力されます。ユーザー自身がこうしたエラーを処理するには、`error(fn)` メソッドを使用してグローバルエラーハンドラーをアプリにアタッチします。
+*注: Bolt 2.x からエラーハンドリングが改善されました！この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
 
-エラーをよりスマートに管理するには、`client` キーの配下で (`say()` や `respond()` の代わりに) アプリにアタッチされている [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) メソッドを使用することをお勧めします。これにより `Promise` が返されるため、そこでエラーをキャッチして処理することができます。
+リスナーでエラーが発生した場合は `try`/`catch` を使って直接ハンドリングすることをおすすめします。しかし、それでもなおすり抜けてしまうエラーのパターンもあるでしょう。デフォルトでは、このようなエラーはコンソールにログ出力されます。ご自身でこれらをハンドリングするには、`app.error(fn)` メソッドによって、グローバルエラーハンドラーを定義してください。
 </div>
 
 ```javascript

docs/_advanced/ja_middleware_global.md

@@ -11,6 +11,8 @@ order: 4
 グローバルミドルウェアとリスナーミドルウェアは、いずれも、`await next()` を呼び出して実行チェーンの制御を次のミドルウェアに渡すか、`throw` を呼び出して以前に実行したミドルウェアチェーンにエラーを渡す必要があります。
 
 たとえば、アプリが、対応する内部認証サービス (SSO プロバイダ、LDAP など) で識別されたユーザーにのみ応答する必要があるとします。この場合、グローバルミドルウェアを使用して認証サービス内のユーザーレコードを検索し、ユーザーが見つからない場合はエラーとなるように定義するのがよいでしょう。
+
+*注: Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
 </div>
 
 ```javascript

docs/_advanced/ja_middleware_listener.md

@@ -13,6 +13,8 @@ order: 5
 ただしもちろん、よりカスタマイズされた機能を追加するために、独自のミドルウェアを作成することもできます。独自のミドルウェアを記述する際には、関数で `await next()` を呼び出して制御を次のミドルウェアに渡すか、`throw` を呼び出して以前に実行されたミドルウェアチェーンにエラーを渡す必要があります。
 
 たとえば、リスナーが人間からのメッセージのみを扱うのであれば、ボットメッセージを除外するリスナーミドルウェアを作成できます。
+
+*注: Bolt 2.x からミドルウェアが `async` 関数をサポートしました！この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
 </div>
 
 ```javascript

docs/_basic/ja_listening_actions.md

@@ -12,6 +12,7 @@ order: 5
 
 すべての `action()` の例で `ack()` が使用されていることに注目してください。Slack からイベントを受信したことを確認するために、アクションリスナー内で `ack()` 関数を呼び出す必要があります。これについては、「[イベントの確認](#acknowledge)」 セクションで説明しています。
 
+*注: Bolt 2.x からメッセージショートカット（以前はメッセージアクションと呼ばれていました）は `action()` ではなく `shortcut()` メソッドを使用するようになりました。この変更については [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
 </div>
 
 ```javascript

docs/_tutorials/ja_hubot_migration.md

@@ -1,6 +1,6 @@
 ---
 title: Hubot のアプリを Bolt に移行する方法
-order: 1
+order: 2
 slug: hubot-migration
 lang: ja-jp
 layout: tutorial

docs/_tutorials/ja_migration_v2.md

@@ -0,0 +1,120 @@
+---
+title: 2.x マイグレーションガイド
+order: 1
+slug: migration-v2
+lang: ja-jp
+layout: tutorial
+permalink: /ja-jp/tutorial/migration-v2
+---
+# 2.x マイグレーションガイド
+
+<div class="section-content">
+このガイドは Bolt 1.x を利用しているアプリを 2.x にアップグレードするための手順について説明します。いくつかの変更が必要とはなりますが、ほとんどのアプリの場合で、おそらく対応に必要な時間は 5 〜 15 分程度です。
+</div> 
+
+---
+
+## リスナー関数を `async` 関数に変更
+
+Bolt アプリ内のリスナー関数は、全て `async` 関数に変更する必要があります。そして、そのリスナー関数内の `say()`、`respond()`、`ack()` メソッドの呼び出しも全て `await` を呼び出しの前につける必要があります。
+
+これまで:
+
+```javascript
+app.action('some-action-id', ({action, ack, say}) => {
+  ack();
+  say('hello world');
+})
+```
+
+これから:
+
+```javascript
+app.action('some-action-id', async ({action, ack, say}) => {
+  await ack();
+  await say('hello world');
+})
+```
+
+
+## エラーハンドリング
+
+Bolt for JavaScript 2.x では、より多くのユースケースで、必要に応じてエラーをキャッチし、グローバルエラーハンドラーにそれを送るかを制御できるよう改善されました。これまでと同様、グローバルエラーハンドラーに全て任せるよりは、可能な限り、リスナー関数の内部でエラーに対処することをおすすめします。
+
+### リスナー関数内で `try`/`catch` 節を用いたエラーハンドリング
+
+```javascript
+app.action('some-action-id', async ({action, ack, say, logger}) => {
+  try {
+    await ack();
+    await say('hello world');
+  } catch (error) {
+    // ここでエラーに対処
+    logger.error(error);
+  }
+})
+```
+
+### グローバルエラーハンドラーによるエラーハンドリング
+
+```javascript
+app.error((error) => {
+  // エラーの詳細をチェックして、メッセージ送信のリトライやアプリの停止などの対処を行う
+  console.error(error);
+});
+```
+
+その他のエラーに関する変更:
+
+- リスナー関数が `ack()` メソッドを 3 秒間のうちに呼び出さなかった場合、これまでのように例外を投げるのではなくログを出力するようになりました
+- もし一つのイベントに対して複数のリスナー関数を実行中に複数のエラーが発生した場合、Bolt for JavaScript は `ErrorCode.MultipleListenerError` の値での `code` と、発生した個々のエラーの配列を含む `originals` というパラメーターをラップしたエラーを返します
+
+## メッセージショートカット
+
+[メッセージショートカット](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) (以前はメッセージアクションと呼ばれていました)は、これまで `action()` メソッドでハンドリングしていましたが `shortcut()` メソッドを使うようになりました。
+
+これまで:
+
+```javascript
+app.action({ callback_id: 'message-action-callback' }, ({action, ack, context}) => {
+  ack();
+  // ここで処理を行う
+})
+```
+
+これから:
+
+```javascript
+app.shortcut('message-action-callback', async ({shortcut, ack, context}) => {
+  await ack();
+  // Do stuff
+})
+```
+
+## ミドルウェアに関する変更
+
+もしカスタムのミドルウェアを書いている場合は、その関数を `async` に変更し、さらに `next()` の呼び出しを `await next()` に変更してください。もし後続の処理がある場合は、関数右を `next()` に渡す代わりに、その後続の処理を `await next()` の後に実行してください。
+
+これまで:
+
+```javascript
+function noBotMessages({message, next }) {
+  function doAfter() {
+    // 後続の処理をここでやる
+  }
+if (!message.subtype || message.subtype !== 'bot_message') {
+    next(doAfter);
+  }
+}
+```
+
+これから:
+
+```javascript
+async function noBotMessages({message, next }) {
+  if (!message.subtype || message.subtype !== 'bot_message') {
+    await next();
+    // 後続の処理をここでやる
+  }
+}
+```