Add assist docs (#25968)

* Add Assist docs

* Add supported languages

source/_includes/asides/docs_navigation.html

@@ -40,9 +40,17 @@
         </ul>
       </li>
       <li>
-        <b>Home Energy Management</b>
+        <b>{% active_link /docs/assist/ Assist %}</b>
+        <ul>
+          <li>{% active_link /docs/assist/android/ Assist for Android Wear %}</li>
+          <li>{% active_link /docs/assist/apple/ Assist for Apple devices %}</li>
+          <li>{% active_link /docs/assist/builtin_sentences/ Built-in sentences %}</li>
+          <li>{% active_link /docs/assist/custom_sentences/ Custom sentences %}</li>
+        </ul>
+      </li>
+      <li>
+        <b>{% active_link /docs/energy/ Home Energy Management %}</b>
         <ul>
-          <li>{% active_link /docs/energy/ Introduction %}</li>
           <li>{% active_link /docs/energy/electricity-grid/ Electricity Grid %}</li>
           <li>{% active_link /docs/energy/solar-panels/ Solar Panels %}</li>
           <li>{% active_link /docs/energy/individual-devices/ Individual Devices %}</li>
@@ -50,7 +58,7 @@
         </ul>
       </li>
       <li>
-        <b>Advanced Configuration</b>
+        Advanced Configuration
         <ul>
           <li>{% active_link /docs/configuration/remote/ Remote access %}</li>
           <li>
@@ -81,7 +89,7 @@
         </ul>
       </li>
       <li>
-        <b>Core objects</b>
+        Core objects
         <ul>
           <li>{% active_link /docs/configuration/events/ Events %}</li>
           <li>

source/docs/assist/aliases.markdown

@@ -0,0 +1,9 @@
+---
+title: "Assist - Entity Aliases"
+---
+
+Assist will use the names of your entities, as well as any aliases you've configured.
+
+![Alias example](/images/blog/2023-01/aliases-cloud-multi-language.png)
+
+By adding aliases in your native language, you can speak to Home Assistant with the language configured on your [Android watch](/docs/assist/android/) or [Apple device](/docs/assist/apple/).

source/docs/assist/android.markdown

@@ -0,0 +1,30 @@
+---
+title: "Assist on Android."
+---
+
+_The new tile is currently available in the [Android beta](https://play.google.com/apps/testing/io.homeassistant.companion.android) and will be part of the next Android release._
+
+Assist is available on WearOS using the [Home Assistant Companion App](https://companion.home-assistant.io/) and "Assist" tile.
+
+<lite-youtube videoid="Dr_ZCbt8w5k" videotitle="Assist on Android Wear"></lite-youtube>
+
+## Installation
+
+After [installing the companion app](https://companion.home-assistant.io/docs/getting_started/) and connecting it to your Home Assistant, visit the Android WatchOS app and click "Add tile" inside the Tiles area. Select the "Assist" tile to add it to your watch:
+
+![Conversation tile](/images/assist/android_tile.png)
+
+
+## Usage
+
+Swipe left on your watch until the "Assist" button is visible:
+
+![Assist button](/images/assist/android_watch_1.png)
+
+After pressing "Assist", wait for "Speak Now" to be displayed:
+
+![Assist button](/images/assist/android_watch_2.png)
+
+Speak your command, then press the "play" icon on the right to send the command to Home Assistant:
+
+![Assist button](/images/assist/android_watch_3.png)

source/docs/assist/apple.markdown

@@ -0,0 +1,65 @@
+---
+title: "Assist on Apple devices"
+---
+
+_The Assist shortcut will be available in the Mac and iOS beta channel today and will be part of the next release for iOS and Mac._
+
+Assist is integrated into Apple devices using the [Shortcuts app](https://support.apple.com/guide/shortcuts/welcome/ios) that is available on all Apple devices. Assist can be used in the following ways on Apple devices:
+
+- Activated by Siri by saying the shortcut name "Hey Siri, Assist"
+- Added to your iPhone home screen
+- Pinned to your Mac menu bar
+- Activated via a keyboard shortcut on your Mac
+- Added as an Apple Watch complication
+
+<lite-youtube videoid="sQ7X7jz1SrA" videotitle="Assist on Apple HomePod"></lite-youtube>
+
+## Installation
+
+To get started make sure you're running the latest version of the [Home Assistant Companion app](https://apps.apple.com/us/app/home-assistant/id1099568401?itsct=apps_box_badge&itscg=30200) and have updated your Apple devices. Then download the two shortcuts and open them to import them:
+
+- [Assist shortcut](https://www.icloud.com/shortcuts/4172210db1d74599bf9ae4f9e1e3d6ed)
+- [Assist Button shortcut](https://www.icloud.com/shortcuts/73ebb68ca1a24ae1811b7d6971203334)
+
+![Expanded Shortcuts Action](/images/assist/ios-expanded-shortcut-action.jpeg)
+
+There are two versions of the shortcut. The normal shortcut works better with Siri while the Button shortcut has the ability to use speech-to-text when triggered outside of Siri and can customize the input language (instead of relying on the OS language)
+
+[_Last updated: Jan 26, 2022_](#changelog)
+
+### Adjusting the language
+
+Shortcuts triggerd via Siri will always use the same language as Siri is set to. The Assist Button shortcut is meant to be manually triggered and can be configured for any language.
+
+Open the shortcuts app, and edit the Button Assist shortcut. The text in quotes will be shown in the language of your device.
+
+- Use the arrow to expand the _"Dictate text"_ action options, and select your language
+- Use the arrow to expand the _"Assist with `Provided Input`"_ options, and select your language.
+
+<p class='note'>
+You can import the button shortcut multiple times to create versions for different languages, when asked if you would like to replace your Shortcut, choose "Keep Both".
+</p>
+
+## Multiple servers
+
+The Assist shortcut works also if you have configured multiple Home Assistant servers. By default it will prompt you to pick the server to sent the command too. This is not very hands-off, and so you can update the shortcut to point at a specific server. You will need to import the shortcuts multiple times, once for each server.
+
+Open the shortcuts app and edit each Assist shortcut. The text in quotes will be shown in the language of your device.
+
+- Use the arrow to expand the _"Assist with `Provided Input`"_ action, and select your Home Assistant server.
+
+## Customizing the Siri experience
+
+Siri allows activating shortcuts by their name. If you change the name of the "Assist" shortcut, you will also have to refer to it by its new name: "Hey Siri, my new name". Be aware that Siri can get confused and might not work if your shortcut name overlaps with actual Siri commands.
+
+It is possible to change the text that Siri says when activating the Assist shortcut. Open the shortcuts app and edit each your Assist shortcut. The text in quotes will be shown in the language of your device.
+
+- Find _"Ask for `Text`"_ and tap on _`How can I assist?`_ and change it to your desired prompt.
+
+You can also use the share action to [add a Shortcut to your Home Screen](https://support.apple.com/guide/shortcuts/apd735880972/ios) or set an [Accessibility Shortcut](https://support.apple.com/en-gb/HT204390) to run this Shortcut when you triple-click the Side button.
+
+## Changelog
+
+### Version 1 - Jan 26, 2022
+
+Initial release

source/docs/assist/builtin_sentences.markdown

@@ -0,0 +1,27 @@
+---
+title: "Assist - Default Sentences"
+---
+
+Home Assistant comes with built-in sentences [contributed by the community](https://github.com/home-assistant/intents/) for [dozens of languages](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages).
+These sentences allow you to:
+
+* **Turn entities on and off**
+    * *"turn on the living room light"*
+    * *"turn off ceiling fan"*
+* **Open and close covers**
+    * *"Close the garage door"*
+    * *"Open kitchen window"*
+* **Set the brightness and color of lights**
+    * *"Change kitchen lights brightness to 50%"*
+    * *"Set bed light to green"*
+    
+In addition to individual entities, commands can target **areas**:
+
+* *"turn on all lights in the living room"*
+* *"open windows in the kitchen"*
+* *"change kitchen brightness to 50%"*
+* *"set bedroom lights to green"*
+
+Entity [aliases](/docs/assist/aliases) are also matched so multiple names can be used, even in different languages.
+
+You can extend the built-in sentences or [add your own](/docs/assist/custom_sentences) to trigger any action in Home Assistant.

source/docs/assist/custom_sentences.markdown

@@ -0,0 +1,120 @@
+---
+title: "Assist - Custom Sentences"
+---
+
+You may add your own sentences to the intent recognizer by either extending an [existing intent](https://developers.home-assistant.io/docs/intent_builtin/) or creating a new one. You may also [customize responses](#customizing-responses) for existing intents.
+
+## In configuration.yaml
+
+Intents and sentences may be added in the [`conversation`](/integrations/conversation/) config in your `configuration.yaml` file:
+
+{% raw %}
+
+```yaml
+# Example configuration.yaml
+conversation:
+  intents:
+    HassTurnOn:
+      - "activate [the] {name}"
+```
+
+```yaml
+# Example configuration.yaml
+conversation:
+  intents:
+    HassTurnOn:
+      - "activate [the] {name}"
+```
+
+{% endraw %}
+
+This extends the default English sentences for the `HassTurnOn` intent, allowing you to say "activate the kitchen lights" as well as "turn on the kitchen lights".
+
+New intents can also be added, with their responses and actions defined using the [`intent_script`](/integrations/intent_script/) integration:
+
+{% raw %}
+
+```yaml
+# Example configuration.yaml
+conversation:
+  intents:
+    YearOfVoice:
+      - "how is the year of voice going"
+      
+intent_script:
+  YearOfVoice:
+    speech:
+      text: "Great! We're at over 40 languages and counting."
+```
+
+{% endraw %}
+
+Besides a text response, `intent_script` can trigger any `action` available in Home Assistant, such as calling a service or firing an event.
+
+## In config directory
+
+More advanced customization can be done in Home Assistant's `config` directory. YAML files in `config/custom_sentences/en`, for example, will be loaded when English sentences (language code `en`) are requested.
+
+The following example creates a new `SetVolume` intent that changes the volume on one of two media players:
+
+{% raw %}
+
+```yaml
+# Example config/custom_sentences/en/media.yaml
+language: "en"
+intents:
+  SetVolume:
+    data:
+      - sentences:
+          - "(set|change) {media_player} volume to {volume} [percent]"
+          - "(set|change) [the] volume for {media_player} to {volume} [percent]"
+lists:
+  media_player:
+    values:
+      - in: "living room"
+        out: "media_player.living_room"
+      - in: "bedroom"
+        out: "media_player.bedroom"
+  volume:
+    range:
+      from: 0
+      to: 100
+```
+
+{% endraw %}
+
+As mentioned above, you can then use the `intent_script` integration to implement an action and provide a response for `SetVolume`:
+
+{% raw %}
+
+```yaml
+# Example configuration.yaml
+intent_script:
+  SetVolume:
+    action:
+      service: "media_player.volume_set"
+      data:
+        entity_id: "{{ media_player }}"
+        volume_level: "{{ volume / 100.0 }}"
+    speech:
+      text: "Volume changed to {{ volume }}"
+```
+
+{% endraw %}
+
+## Customizing Responses
+
+Responses for existing intents can be customized as well in `config/custom_sentences/<language>`:
+
+{% raw %}
+
+```yaml
+# Example config/custom_sentences/en/responses.yaml
+language: "en"
+responses:
+  intents:
+    HassTurnOn:
+      default: "I have turned on the {{ slots.name }}"
+```
+
+{% endraw %}

source/docs/assist/index.markdown

@@ -0,0 +1,21 @@
+---
+title: Assist - Talking to Home Assistant
+---
+
+<img src='/images/assist/assist-logo.png' class='no-shadow' alt='Assist logo' style='width: 150px; float: right'>
+
+Assist is our feature to allow you to control Home Assistant using natural language. It is built on top of an open voice foundation and powered by knowledge provided by our community. You can use the [built-in sentences](/docs/assist/builtin_sentences) to control entities and areas, or [create your own](/docs/assist/custom_sentences).
+
+[List of supported languages.](https://developers.home-assistant.io/docs/voice/intent-recognition/supported-languages)
+
+Assist is available to use on most platforms that can interface with Home Assistant. Look for the Assist icon <img src='/images/assist/assist-icon.svg' alt='Assist icon' style='height: 32px' class='no-shadow'>:
+
+- Inside the Home Assistant app in the top-right corner
+- On Android Watch using [Assist tile](/docs/assist/android)
+- On Apple devices via [Siri and Assist shortcuts](/docs/assist/apple)
+
+Did Assist not understand your sentence? [Contribute them.](https://developers.home-assistant.io/docs/voice/intent-recognition/)
+
+_Assist was introduced in Home Assistant 2023.2._
+
+<lite-youtube videoid="sQ7X7jz1SrA" videotitle="Assist on Apple HomePod"></lite-youtube>