Add Japanese version of Basic Concepts documents

Author: seratch

docs/_advanced/async.md

@@ -1,5 +1,5 @@
 ---
-title: Using async
+title: Using async (asyncio)
 lang: en
 slug: async
 order: 2

docs/_basic/authenticating_oauth.md

@@ -7,9 +7,9 @@ order: 15
 
 <div class="section-content">
 
-Slack apps installed on multiple workspaces will need to implement OAuth, then store installation information (like access tokens) securely. By providing `client_id`, `client_secret`, `scopes`, `installation_store`, and `state_store` when initializing App, Bolt for Python will handle the work of setting up OAuth routes and verifying state. If you’re implementing a custom adapter, you can make use of our [OAuth library](https://slack.dev/python-slack-sdk/oauth/), which is what Bolt for Python uses under the hood.
+Slack apps installed on multiple workspaces will need to implement OAuth, then store installation information (like access tokens) securely. By providing `client_id`, `client_secret`, `scopes`, `installation_store`, and `state_store` when initializing App, Bolt for Python will handle the work of setting up OAuth routes and verifying state. If you're implementing a custom adapter, you can make use of our [OAuth library](https://slack.dev/python-slack-sdk/oauth/), which is what Bolt for Python uses under the hood.
 
-Bolt for Python will create a **Redirect URL** `slack/oauth_redirect`, which Slack uses to redirect users after they complete your app’s installation flow. You will need to add this **Redirect URL** in your app configuration settings under **OAuth and Permissions**. This path can be configured in the `OAuthSettings` argument described below.
+Bolt for Python will create a **Redirect URL** `slack/oauth_redirect`, which Slack uses to redirect users after they complete your app's installation flow. You will need to add this **Redirect URL** in your app configuration settings under **OAuth and Permissions**. This path can be configured in the `OAuthSettings` argument described below.
 
 Bolt for Python will also create a `slack/install` route, where you can find an **Add to Slack** button for your app to perform direct installs of your app. If you need any additional authorizations (user tokens) from users inside a team when your app is already installed or a reason to dynamically generate an install URL, you can pass your own custom URL generator to `oauth_settings` as `authorize_url_generator`.
 

docs/_basic/ja_acknowledging_events.md

@@ -0,0 +1,33 @@
+---
+title: イベントの確認
+lang: ja-jp
+slug: acknowledge
+order: 7
+---
+
+<div class="section-content">
+
+アクション（action）、コマンド（command）、およびオプション（options）の各イベントは、**必ず** `ack()` 関数を使って確認を行う必要があります。これによってイベントが受信されたことが Slack に認識され、Slack のユーザーインターフェイスが適切に更新されます。
+
+イベントの種類によっては、確認で通知方法が異なる場合があります。例えば、外部データソースを使用する選択メニューのオプションのリクエストに対する確認では、適切な[オプション](https://api.slack.com/reference/block-kit/composition-objects#option)のリストとともに `ack()` を呼び出します。
+
+確認までの猶予は 3 秒しかないため、新しいメッセージの送信や、データベースからの情報の取得は、`ack()` を呼び出した後で行うことをおすすめします。
+
+</div>
+
+```python
+# 外部データを使用する選択メニューオプションに応答するサンプル
+@app.options("menu_selection")
+def show_menu_options(ack):
+    options = [
+        {
+            "text": {"type": "plain_text", "text":"Option 1"},
+            "value":"1-1",
+        },
+        {
+            "text": {"type": "plain_text", "text":"Option 2"},
+            "value":"1-2",
+        },
+    ]
+    ack(options=options)
+```

docs/_basic/ja_authenticating_oauth.md

@@ -0,0 +1,103 @@
+---
+title: OAuth を使った認証
+lang: ja-jp
+slug: authenticating-oauth
+order: 15
+---
+
+<div class="section-content">
+
+Slack アプリを複数のワークスペースにインストールできるようにするためには、OAuth フローを実装した上で、アクセストークンなどのインストールに関する情報をセキュアな方法で保存する必要があります。アプリを初期化する際に `client_id`、`client_secret`、`scopes`、`installation_store`、`state_store` を指定することで、OAuth のエンドポイントのルート情報や stateパラメーターの検証をBolt for Python にハンドリングさせることができます。カスタムのアダプターを実装する場合は、SDK が提供する組み込みの[OAuth ライブラリ](https://slack.dev/python-slack-sdk/oauth/)を利用するのが便利です。これは Slack が開発したモジュールで、Bolt for Python 内部でも利用しています。
+
+Bolt for Python によって `slack/oauth_redirect` という**リダイレクト URL** が生成されます。Slack はアプリのインストールフローを完了させたユーザーをこの URL にリダイレクトします。この**リダイレクト URL** は、アプリの設定の「**OAuth and Permissions**」であらかじめ追加しておく必要があります。この URL は、後ほど説明するように `OAuthSettings` というコンストラクタの引数で指定することもできます。
+
+Bolt for Python は `slack/install` というルートも生成します。これはアプリを直接インストールするための「**Add to Slack**」ボタンを表示するために使われます。すでにワークスペースへのアプリのインストールが済んでいる場合に追加で各ユーザーのユーザートークンなどの情報を取得する場合や、カスタムのインストール用の URL を動的に生成したい場合などは、`oauth_settings` の `authorize_url_generator` でカスタムの URL ジェネレーターを指定することができます。
+
+バージョン 1.1.0 以降の Bolt for Python では、[OrG 全体へのインストール](https://api.slack.com/enterprise/apps)がデフォルトでサポートされています。OrG 全体へのインストールは、アプリの設定の「**Org Level Apps**」で有効化できます。
+
+Slack での OAuth を使ったインストールフローについて詳しくは、[API ドキュメントを参照してください](https://api.slack.com/authentication/oauth-v2)。
+
+</div>
+
+```python
+import os
+from slack_bolt import App
+from slack_bolt.oauth.oauth_settings import OAuthSettings
+from slack_sdk.oauth.installation_store import FileInstallationStore
+from slack_sdk.oauth.state_store import FileOAuthStateStore
+
+oauth_settings = OAuthSettings(
+    client_id=os.environ["SLACK_CLIENT_ID"],
+    client_secret=os.environ["SLACK_CLIENT_SECRET"],
+    scopes=["channels:read", "groups:read", "chat:write"],
+    installation_store=FileInstallationStore(base_dir="./data"),
+    state_store=FileOAuthStateStore(expiration_seconds=600, base_dir="./data")
+)
+
+app = App(
+    signing_secret=os.environ["SIGNING_SECRET"],
+    oauth_settings=oauth_settings
+)
+```
+
+<details class="secondary-wrapper">
+<summary class="section-head" markdown="0">
+<h4 class="section-head">OAuth デフォルト設定をカスタマイズ</h4>
+</summary>
+
+<div class="secondary-content" markdown="0">
+`oauth_settings` を使って OAuth モジュールのデフォルト設定を上書きすることができます。このカスタマイズされた設定は App の初期化時に渡します。以下の情報を変更可能です:
+
+- `install_path` : 「Add to Slack」ボタンのデフォルトのパスを上書きするために使用
+- `redirect_uri` : リダイレクト URL のデフォルトのパスを上書きするために使用
+- `callback_options` : OAuth フローの最後に表示するカスタムの成功ページと失敗ページの表示処理を提供するために使用
+- `state_store` : 組み込みの `FileOAuthStateStore` に代わる、カスタムの stateに関するデータストアを指定するために使用
+- `installation_store` : 組み込みの `FileInstallationStore` に代わる、カスタムのデータストアを指定するために使用
+
+</div>
+
+```python
+from slack_bolt.oauth.callback_options import CallbackOptions, SuccessArgs, FailureArgs
+from slack_bolt.response import BoltResponse
+
+def success(args:SuccessArgs) -> BoltResponse:
+    assert args.request is not None
+    return BoltResponse(
+        status=200,  # ユーザーをリダイレクトすることも可能
+        body="Your own response to end-users here"
+    )
+
+def failure(args:FailureArgs) -> BoltResponse:
+    assert args.request is not None
+    assert args.reason is not None
+    return BoltResponse(
+        status=args.suggested_status_code,
+        body="Your own response to end-users here"
+    )
+
+callback_options = CallbackOptions(success=success, failure=failure)
+
+import os
+from slack_bolt import App
+from slack_bolt.oauth.oauth_settings import OAuthSettings
+from slack_sdk.oauth.installation_store import FileInstallationStore
+from slack_sdk.oauth.state_store import FileOAuthStateStore
+
+app = App(
+    signing_secret=os.environ.get("SLACK_SIGNING_SECRET"),
+    installation_store=FileInstallationStore(base_dir="./data"),
+    oauth_settings=OAuthSettings(
+        client_id=os.environ.get("SLACK_CLIENT_ID"),
+        client_secret=os.environ.get("SLACK_CLIENT_SECRET"),
+        scopes=["app_mentions:read", "channels:history", "im:history", "chat:write"],
+        user_scopes=[],
+        redirect_uri=None,
+        install_path="/slack/install",
+        redirect_uri_path="/slack/oauth_redirect",
+        state_store=FileOAuthStateStore(expiration_seconds=600, base_dir="./data"),
+        callback_options=callback_options,
+    ),
+)
+```
+
+</details>

docs/_basic/ja_listening_actions.md

@@ -0,0 +1,54 @@
+---
+title: アクションのリスニング
+lang: ja-jp
+slug: action-listening
+order: 5
+---
+
+<div class="section-content">
+Bolt アプリは `action` メソッドを用いて、ボタンのクリック、メニューの選択、メッセージショートカットなどのユーザーのアクションをリッスンすることができます。
+
+アクションは `str` 型または `re.Pattern` 型の `action_id` でフィルタリングできます。`action_id` は、Slack プラットフォーム上のインタラクティブコンポーネントを区別する一意の識別子として機能します。
+
+`action()` を使ったすべての例で `ack()` が使用されていることに注目してください。アクションのリスナー内では、Slack からのイベントを受信したことを確認するために、`ack()` 関数を呼び出す必要があります。これについては、[イベントの確認](#acknowledge)セクションで説明しています。
+
+</div>
+
+```python
+# 'approve_button' という action_id のブロックエレメントがトリガーされるたびに、このリスナーが呼び出させれる
+@app.action("approve_button")
+def update_message(ack):
+    ack()
+    # アクションへの反応としてメッセージを更新
+```
+
+<details class="secondary-wrapper">
+<summary class="section-head" markdown="0">
+<h4 class="section-head">制約付きオブジェクトを使用したアクションのリスニング</h4>
+</summary>
+
+<div class="secondary-content" markdown="0">
+
+制約付きのオブジェクトを使用すると、`callback_id`、`block_id`、および `action_id` をそれぞれ、または任意に組み合わせてリッスンできます。オブジェクト内の制約は、`str` 型または `re.Pattern` 型で指定できます。
+
+</div>
+
+```python
+# この関数は、block_id が 'assign_ticket' に一致し
+# かつ action_id が 'select_user' に一致する場合にのみ呼び出される
+@app.action({
+    "block_id": "assign_ticket",
+    "action_id": "select_user"
+})
+def update_message(ack, body, client):
+    ack()
+
+    if "container" in body and "message_ts" in body["container"]:
+        client.reactions_add(
+            name="white_check_mark",
+            channel=body["channel"]["id"],
+            timestamp=body["container"]["message_ts"],
+        )
+```
+
+</details>

docs/_basic/ja_listening_events.md

@@ -0,0 +1,49 @@
+---
+title: イベントのリスニング
+lang: ja-jp
+slug: event-listening
+order: 3
+---
+
+<div class="section-content">
+
+`event()` メソッドを使うと、[Events API](https://api.slack.com/events) の任意のイベントをリッスンできます。リッスンするイベントは、アプリの設定であらかじめサブスクライブしておく必要があります。これを利用することで、アプリがインストールされたワークスペースで何らかのイベント（例：ユーザーがメッセージにリアクションをつけた、ユーザーがチャンネルに参加した）が発生したときに、アプリに何らかのアクションを実行させることができます。
+
+`event()` メソッドには `str` 型の `eventType` を指定する必要があります。
+
+</div>
+
+```python
+# ユーザーがワークスペースに参加した際に、自己紹介を促すメッセージを指定のチャンネルに送信
+@app.event("team_join")
+def ask_for_introduction(event, say):
+    welcome_channel_id = "C12345"
+    user_id = event["user"]
+    text = f"Welcome to the team, <@{user_id}>! 🎉 You can introduce yourself in this channel."
+    say(text=text, channel=welcome_channel_id)
+```
+
+<details class="secondary-wrapper" >
+  
+<summary class="section-head" markdown="0">
+  <h4 class="section-head">メッセージのサブタイプのフィルタリング</h4>
+</summary>
+
+<div class="secondary-content" markdown="0">
+`message()` リスナーは `event("message")` と等価の機能を提供します。
+
+`subtype` という追加のキーを指定して、イベントのサブタイプでフィルタリングすることもできます。よく使われるサブタイプには、`bot_message` や `message_replied` があります。詳しくは[メッセージイベントページ](https://api.slack.com/events/message#message_subtypes)を参照してください。
+
+</div>
+
+```python
+# 変更されたすべてのメッセージに一致
+@app.event({
+    "type": "message",
+    "subtype": "message_changed"
+})
+def log_message_change(logger, event):
+    user, text = event["user"], event["text"]
+    logger.info(f"The user {user} changed the message to {text}")
+```
+</details>

docs/_basic/ja_listening_messages.md

@@ -0,0 +1,45 @@
+---
+title: メッセージのリスニング
+lang: ja-jp
+slug: message-listening
+order: 1
+---
+
+<div class="section-content">
+
+[あなたのアプリがアクセス権限を持つ](https://api.slack.com/messaging/retrieving#permissions)メッセージの投稿イベントをリッスンするには `message()` メソッドを利用します。このメソッドは `type` が `message` ではないイベントを処理対象から除外します。
+
+`message()` の引数には `str` 型または `re.Pattern` オブジェクトを指定できます。この条件のパターンに一致しないメッセージは除外されます。
+
+</div>
+
+```python
+# '👋' が含まれるすべてのメッセージに一致
+@app.message(":wave:")
+def say_hello(message, say):
+    user = message['user']
+    say(f"Hi there, <@{user}>!")
+```
+
+<details class="secondary-wrapper">
+<summary markdown="0">
+<h4 class="secondary-header">正規表現パターンの使用</h4>
+</summary>
+
+<div class="secondary-content" markdown="0">
+
+文字列の代わりに `re.compile()` メソッドを使用すれば、より細やかな条件指定ができます。
+
+</div>
+
+```python
+import re
+
+@app.message(re.compile("(hi|hello|hey)"))
+def say_hello_regex(say, context):
+    # 正規表現のマッチ結果は context.matches に設定される
+    greeting = context['matches'][0]
+    say(f"{greeting}, how are you?")
+```
+
+</details>

docs/_basic/ja_listening_modals.md

@@ -0,0 +1,48 @@
+---
+title: モーダルの送信のリスニング
+lang: ja-jp
+slug: view_submissions
+order: 12
+---
+
+<div class="section-content">
+
+<a href="https://api.slack.com/reference/block-kit/views">モーダルのペイロード</a>に input ブロックを含める場合、その入力値を受け取るために`view_submission` イベントをリッスンする必要があります。`view_submission` イベントのリッスンには、組み込みの`view()` メソッドを利用することができます。`view()` の引数には、`str` 型または `re.Pattern` 型の `callback_id` を指定します。
+
+`input` ブロックの値にアクセスするには `state` オブジェクトを参照します。`state` 内には `values` というオブジェクトがあり、`block_id` と一意の `action_id` に紐づける形で入力値を保持しています。
+
+モーダルの送信について詳しくは、<a href="https://api.slack.com/surfaces/modals/using#interactions">API ドキュメント</a>を参照してください。
+
+</div>
+
+```python
+# view_submission イベントを処理
+@app.view("view_1")
+def handle_submission(ack, body, client, view):
+    # `block_c`という block_id に `dreamy_input` を持つ input ブロックがある場合
+    hopes_and_dreams = view["state"]["values"]["block_c"]["dreamy_input"]
+    user = body["user"]["id"]
+    # 入力値を検証
+    errors = {}
+    if hopes_and_dreams is not None and len(hopes_and_dreams) <= 5:
+        errors["block_c"] = "The value must be longer than 5 characters"
+    if len(errors) > 0:
+        ack(response_action="errors", errors=errors)
+        return
+    # view_submission イベントの確認を行い、モーダルを閉じる
+    ack()
+    # 入力されたデータを使った処理を実行。このサンプルでは DB に保存する処理を行う
+    # そして入力値の検証結果をユーザーに送信
+
+    # ユーザーに送信するメッセージ
+    msg = ""
+    try:
+        # DB に保存
+        msg = f"Your submission of {hopes_and_dreams} was successful"
+    except Exception as e:
+        # エラーをハンドリング
+        msg = "There was an error with your submission"
+    finally:
+        # ユーザーにメッセージを送信
+        client.chat_postMessage(channel=user, text=msg)
+```

docs/_basic/ja_listening_responding_commands.md

@@ -0,0 +1,27 @@
+---
+title: コマンドのリスニングと応答
+lang: ja-jp
+slug: commands
+order: 9
+---
+
+<div class="section-content">
+
+スラッシュコマンドが実行されたイベントをリッスンするには、`command()` メソッドを使用します。このメソッドでは `str` 型の `command_name` の指定が必要です。
+
+コマンドイベントをアプリが受信し確認したことを Slack に通知するため、`ack()` を呼び出す必要があります。
+
+スラッシュコマンドに応答する方法は 2 つあります。1 つ目は `say()` を使う方法で、文字列または JSON のペイロードを渡すことができます。2 つ目は `respond()` を使う方法です。これは `response_url` がある場合に活躍します。これらの方法は[アクションへの応答](#action-respond)セクションで詳しく説明しています。
+
+アプリの設定でコマンドを登録するときは、リクエスト URL の末尾に `/slack/events` をつけます。
+
+</div>
+
+```python
+# echoコマンドは受け取ったコマンドをそのまま返す
+@app.command("/echo")
+def repeat_text(ack, say, command):
+    # command リクエストを確認
+    ack()
+    say(f"{command['text']}")
+```