From 105d171b1541cccee67616aa4fd8af409e5db57a Mon Sep 17 00:00:00 2001
From: Todd Johnson <todd@toddejohnson.net>
Date: Tue, 27 Dec 2022 02:18:06 -0600
Subject: [PATCH] Update google_translate to include dialects (#25113)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
---
 .../_integrations/google_translate.markdown   | 98 ++++++++++++++++++-
 1 file changed, 96 insertions(+), 2 deletions(-)

diff --git a/source/_integrations/google_translate.markdown b/source/_integrations/google_translate.markdown
index 3b40a13439a..929b06ce756 100644
--- a/source/_integrations/google_translate.markdown
+++ b/source/_integrations/google_translate.markdown
@@ -29,12 +29,37 @@ language:
   required: false
   type: string
   default: "`en`"
+tld:
+  description: "The default Google domain you want to use to choose dialect."
+  required: false
+  type: string
+  default: "`com`"
 {% endconfiguration %}
 
 Check the [complete list of supported languages](https://translate.google.com/intl/en_ALL/about/languages/) (languages where "Talk" feature is enabled in Google Translate) for allowed values.
-Use the 2 digit language code which you can find at the end of URL when you click on Language name.
+Use the 2-digit language code which you can find at the end of the URL when you click on the language name. 
+
+Check the [complete list of supported tld](https://www.google.com/supported_domains) for allowed TLD values. This is used to force the dialect used when multiple fall into the same 2-digit language code(i.e., *US, UK, AU*)
+
+You can also use supported BCP 47 tags like the below or the 2-2 digit format for your supported dialect(`en-gb` or `en-us`). Below is a list of the currently implemented mappings:
+
+| Dialect | Language | TLD |
+|---------|----------|-----|
+|en-us|en|com|
+|en-gb|en|co.uk|
+|en-uk|en|co.uk|
+|en-au|en|com.au|
+|en-ca|en|ca|
+|en-in|en|co.in|
+|en-ie|en|ie|
+|en-za|en|co.za|
+|fr-ca|fr|ca|
+|fr-fr|fr|fr|
+|pt-br|pt|com.br|
+|pt-pt|pt|pt|
+|es-es|es|es|
+|es-us|es|com|
 
-For more information about using text-to-speech with Home Assistant and more details on all the options it provides, see the [TTS documentation](/integrations/tts/).
 
 ## Full configuration example
 
@@ -45,4 +70,73 @@ A full configuration sample including optional variables:
 tts:
   - platform: google_translate
     language: "de"
+    tld: com
 ```
+
+## Service say
+
+The `google_translate_say` service supports `language` and also `options` for setting `tld`. The text for speech is set with `message`. Since release 0.92, the service name can be defined in the configuration `service_name` option.
+
+Say to all `media_player` device entities:
+
+```yaml
+# Replace google_translate_say with <platform>_say when you use a different platform.
+service: tts.google_translate_say
+data:
+  entity_id: all
+  message: "May the force be with you."
+```
+
+Say to the `media_player.floor` device entity:
+
+```yaml
+service: tts.google_translate_say
+data:
+  entity_id: media_player.floor
+  message: "May the force be with you."
+```
+
+Say to the `media_player.floor` device entity in French:
+
+```yaml
+service: tts.google_translate_say
+data:
+  entity_id: media_player.floor
+  message: "Que la force soit avec toi."
+  language: "fr"
+```
+
+Say to the `media_player.floor` device entity in UK English:
+
+```yaml
+service: tts.google_translate_say
+data:
+  entity_id: media_player.floor
+  message: "May the force be with you."
+  language: "en-uk"
+```
+
+```yaml
+service: tts.google_translate_say
+data:
+  entity_id: media_player.floor
+  message: "May the force be with you."
+  language: "en"
+  options:
+    tld: co.uk  
+```
+
+With a template:
+
+{% raw %}
+
+```yaml
+service: tts.google_translate_say
+data:
+  message: "Temperature is {{states('sensor.temperature')}}."
+  cache: false
+```
+
+{% endraw %}
+
+For more information about using text-to-speech with Home Assistant and more details on all the options it provides, see the [TTS documentation](/integrations/tts/).
\ No newline at end of file