Merge pull request #186548 from ShawnJackson/get-started-speech-translation

edit pass: get-started-speech-translation

Author: Ja-Dunn

articles/cognitive-services/Speech-Service/get-started-speech-translation.md

@@ -1,7 +1,7 @@
 ---
 title: Speech translation quickstart - Speech service
 titleSuffix: Azure Cognitive Services
-description: Learn how to use the Speech SDK to translate speech. In this quickstart, you learn about object construction, supported audio input formats, and configuration options for speech translation.
+description: Learn how to use the Speech SDK to translate speech, including object construction, supported audio input formats, and configuration options.
 services: cognitive-services
 author: eric-urban
 manager: nitinme
@@ -44,5 +44,5 @@ keywords: speech translation
 
 ## Next steps
 
-* [Use codec compressed audio formats](how-to-use-codec-compressed-audio-input-streams.md)
+* Use [codec-compressed audio formats](how-to-use-codec-compressed-audio-input-streams.md).
 * See the [quickstart samples](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/quickstart) on GitHub.

articles/cognitive-services/Speech-Service/includes/how-to/speech-translation-basics/speech-translation-basics-cli.md

@@ -6,17 +6,17 @@ ms.date: 04/13/2020
 ms.author: eric-urban
 ---
 
-One of the core features of the Speech service is the ability to recognize human speech and translate it to other languages. In this quickstart you learn how to use the Speech SDK in your apps and products to perform high-quality speech translation. This quickstart translates speech from the microphone into text in another language.
+One of the core features of the Speech service is the ability to recognize human speech and translate it to other languages. In this quickstart, you learn how to use the Speech SDK in your apps and products to perform high-quality speech translation. This quickstart translates speech from the microphone to text in another language.
 
 ## Prerequisites
 
-This article assumes that you have an Azure account and Speech service subscription. If you don't have an account and subscription, [try the Speech service for free](../../../overview.md#try-the-speech-service-for-free).
+This article assumes that you have an Azure account and a Speech service subscription. If you don't have an account and a subscription, [try the Speech service for free](../../../overview.md#try-the-speech-service-for-free).
 
 [!INCLUDE [SPX Setup](../../spx-setup.md)]
 
-## Set source and target language
+## Set source and target languages
 
-This command calls Speech CLI to translate speech from the microphone from Italian to French.
+This command calls the Speech CLI to translate speech from the microphone from Italian to French:
 
 ```shell
  spx translate --microphone --source it-IT --target fr

articles/cognitive-services/Speech-Service/includes/how-to/speech-translation-basics/speech-translation-basics-cpp.md

@@ -7,9 +7,9 @@ ms.custom: devx-track-java
 ms.author: eur
 ---
 
-One of the core features of the Speech service is the ability to recognize human speech and translate it to other languages. In this quickstart you learn how to use the Speech SDK in your apps and products to perform high-quality speech translation. This quickstart covers topics including:
+One of the core features of the Speech service is the ability to recognize human speech and translate it to other languages. In this quickstart, you learn how to use the Speech SDK in your apps and products to perform high-quality speech translation. This quickstart covers these topics:
 
-* Translating speech-to-text
+* Translating speech to text
 * Translating speech to multiple target languages
 * Performing direct speech-to-speech translation
 
@@ -19,15 +19,15 @@ If you want to skip straight to sample code, see the [Java quickstart samples](h
 
 ## Prerequisites
 
-This article assumes that you have an Azure account and Speech service subscription. If you don't have an account and subscription, [try the Speech service for free](../../../overview.md#try-the-speech-service-for-free).
+This article assumes that you have an Azure account and a Speech service subscription. If you don't have an account and a subscription, [try the Speech service for free](../../../overview.md#try-the-speech-service-for-free).
 
-## Install the Speech SDK
+### Install the Speech SDK
 
-Before you can do anything, you'll need to install the Speech SDK. Depending on your platform, follow the instructions under the <a href="/azure/cognitive-services/speech-service/speech-sdk#get-the-speech-sdk" target="_blank">Get the Speech SDK </a> section of the _About the Speech SDK_ article.
+Before you can do anything, you need to install the Speech SDK. Depending on your platform, follow the instructions in the <a href="/azure/cognitive-services/speech-service/speech-sdk#get-the-speech-sdk" target="_blank">Get the Speech SDK </a> section of the _About the Speech SDK_ article.
 
-## Import dependencies
+### Import dependencies
 
-To run the examples in this article, include the following `import` statements at the top of the **.Java* code file.
+To run the examples in this article, include the following `import` statements at the top of the **.Java* code file:
 
 ```java
 package speech;
@@ -42,7 +42,7 @@ import com.microsoft.cognitiveservices.speech.translation.*;
 
 ## Sensitive data and environment variables
 
-The example source code in this article depends on environment variables for storing sensitive data, such as the Speech resource subscription key and region. The Java code file contains two `static final String` values that are assigned from the host machines environment variables, namely `SPEECH__SUBSCRIPTION__KEY` and `SPEECH__SERVICE__REGION`. Both of these fields are at the class scope, making them accessible within method bodies of the class. For more information on environment variables, see [environment variables and application configuration](../../../../cognitive-services-security.md#environment-variables-and-application-configuration).
+The example source code in this article depends on environment variables for storing sensitive data, such as the Speech resource's subscription key and region. The Java code file contains two `static final String` values that are assigned from the host machine's environment variables: `SPEECH__SUBSCRIPTION__KEY` and `SPEECH__SERVICE__REGION`. Both of these fields are at the class scope, so they're accessible within method bodies of the class: 
 
 ```java
 public class App {
@@ -54,21 +54,23 @@ public class App {
 }
 ```
 
+For more information on environment variables, see [Environment variables and application configuration](../../../../cognitive-services-security.md#environment-variables-and-application-configuration).
+
 ## Create a speech translation configuration
 
-To call the Speech service using the Speech SDK, you need to create a [`SpeechTranslationConfig`][config]. This class includes information about your subscription, like your key and associated region, endpoint, host, or authorization token.
+To call the Speech service by using the Speech SDK, you need to create a [`SpeechTranslationConfig`][config] instance. This class includes information about your subscription, like your key and associated region, endpoint, host, or authorization token.
 
 > [!TIP]
 > Regardless of whether you're performing speech recognition, speech synthesis, translation, or intent recognition, you'll always create a configuration.
 
-There are a few ways that you can initialize a [`SpeechTranslationConfig`][config]:
+You can initialize a `SpeechTranslationConfig` instance in a few ways:
 
 * With a subscription: pass in a key and the associated region.
 * With an endpoint: pass in a Speech service endpoint. A key or authorization token is optional.
 * With a host: pass in a host address. A key or authorization token is optional.
 * With an authorization token: pass in an authorization token and the associated region.
 
-Let's take a look at how a [`SpeechTranslationConfig`][config] is created using a key and region. Get these credentials by following steps in [Try the Speech service for free](../../../overview.md#try-the-speech-service-for-free).
+Let's look at how you create a `SpeechTranslationConfig` instance by using a key and region. Get these credentials by following the steps in [Try the Speech service for free](../../../overview.md#try-the-speech-service-for-free).
 
 ```java
 public class App {
@@ -93,9 +95,9 @@ public class App {
 }
 ```
 
-## Change source language
+## Change the source language
 
-One common task of speech translation is specifying the input (or source) language. Let's take a look at how you would change the input language to Italian. In your code, interact with the [`SpeechTranslationConfig`][config] instance, calling the `setSpeechRecognitionLanguage` method.
+One common task of speech translation is specifying the input (or source) language. The following example shows how you would change the input language to Italian. In your code, interact with the `SpeechTranslationConfig` instance by calling the `setSpeechRecognitionLanguage` method:
 
 ```java
 static void translateSpeech() {
@@ -107,11 +109,11 @@ static void translateSpeech() {
 }
 ```
 
-The [`setSpeechRecognitionLanguage`][recognitionlang] function expects a language-locale format string. You can provide any value in the **Locale** column in the list of supported [locales/languages](../../../language-support.md).
+The [`setSpeechRecognitionLanguage`][recognitionlang] function expects a language-locale format string. You can provide any value in the **Locale** column in the [list of supported locales/languages](../../../language-support.md).
 
-## Add translation language
+## Add a translation language
 
-Another common task of speech translation is to specify target translation languages, at least one is required but multiples are supported. The following code snippet sets both French and German as translation language targets.
+Another common task of speech translation is to specify target translation languages. At least one is required, but multiples are supported. The following code snippet sets both French and German as translation language targets:
 
 ```java
 static void translateSpeech() {
@@ -120,7 +122,7 @@ static void translateSpeech() {
 
     translationConfig.setSpeechRecognitionLanguage("it-IT");
 
-    // Translate to languages. See, https://aka.ms/speech/sttt-languages
+    // Translate to languages. See https://aka.ms/speech/sttt-languages
     translationConfig.addTargetLanguage("fr");
     translationConfig.addTargetLanguage("de");
 }
@@ -130,9 +132,9 @@ With every call to [`addTargetLanguage`][addlang], a new target translation lang
 
 ## Initialize a translation recognizer
 
-After you've created a [`SpeechTranslationConfig`][config], the next step is to initialize a [`TranslationRecognizer`][recognizer]. When you initialize a [`TranslationRecognizer`][recognizer], you'll need to pass it your `translationConfig`. The configuration object provides the credentials that the speech service requires to validate your request.
+After you've created a [`SpeechTranslationConfig`][config] instance, the next step is to initialize [`TranslationRecognizer`][recognizer]. When you initialize `TranslationRecognizer`, you need to pass it your `translationConfig` instance. The configuration object provides the credentials that the Speech service requires to validate your request.
 
-If you're recognizing speech using your device's default microphone, here's what the [`TranslationRecognizer`][recognizer] should look like:
+If you're recognizing speech by using your device's default microphone, here's what `TranslationRecognizer` should look like:
 
 ```java
 static void translateSpeech() {
@@ -151,12 +153,12 @@ static void translateSpeech() {
 }
 ```
 
-If you want to specify the audio input device, then you'll need to create an [`AudioConfig`][audioconfig] and provide the `audioConfig` parameter when initializing your [`TranslationRecognizer`][recognizer].
+If you want to specify the audio input device, then you need to create an [`AudioConfig`][audioconfig] class instance and provide the `audioConfig` parameter when initializing `TranslationRecognizer`.
 
 > [!TIP]
 > [Learn how to get the device ID for your audio input device](../../../how-to-select-audio-input-devices.md).
 
-First, you'll reference the `AudioConfig` object as follows:
+First, reference the `AudioConfig` object as follows:
 
 ```java
 static void translateSpeech() {
@@ -177,7 +179,7 @@ static void translateSpeech() {
 }
 ```
 
-If you want to provide an audio file instead of using a microphone, you'll still need to provide an `audioConfig`. However, when you create an [`AudioConfig`][audioconfig], instead of calling `fromDefaultMicrophoneInput`, you'll call `fromWavFileInput` and pass the `filename` parameter.
+If you want to provide an audio file instead of using a microphone, you still need to provide an `audioConfig` parameter. However, when you create an `AudioConfig` class instance, instead of calling `fromDefaultMicrophoneInput`, you call `fromWavFileInput` and pass the `filename` parameter:
 
 ```java
 static void translateSpeech() {
@@ -200,7 +202,7 @@ static void translateSpeech() {
 
 ## Translate speech
 
-To translate speech, the Speech SDK relies on a microphone or an audio file input. Speech recognition occurs before speech translation. After all objects have been initialized, call the recognize-once function and get the result.
+To translate speech, the Speech SDK relies on a microphone or an audio file input. Speech recognition occurs before speech translation. After all objects have been initialized, call the recognize-once function and get the result:
 
 ```java
 static void translateSpeech() throws ExecutionException, InterruptedException {
@@ -232,14 +234,16 @@ For more information about speech-to-text, see [the basics of speech recognition
 
 ## Synthesize translations
 
-After a successful speech recognition and translation, the result contains all the translations in a dictionary. The [`getTranslations`][translations] function returns a dictionary with the key as the target translation language and the value is the translated text. Recognized speech can be translated, then synthesized in a different language (speech-to-speech).
+After a successful speech recognition and translation, the result contains all the translations in a dictionary. The [`getTranslations`][translations] function returns a dictionary with the key as the target translation language and the value as the translated text. Recognized speech can be translated and then synthesized in a different language (speech-to-speech).
 
 ### Event-based synthesis
 
-The `TranslationRecognizer` object exposes a `synthesizing` event. The event fires several times, and provides a mechanism to retrieve the synthesized audio from the translation recognition result. If you're translating to multiple languages, see [manual synthesis](#manual-synthesis). Specify the synthesis voice by assigning a [`setVoiceName`][voicename] and provide an event handler for the `synthesizing` event, get the audio. The following example saves the translated audio as a *.wav* file.
+The `TranslationRecognizer` object exposes a `synthesizing` event. The event fires several times and provides a mechanism to retrieve the synthesized audio from the translation recognition result. If you're translating to multiple languages, see [Manual synthesis](#manual-synthesis). 
+
+Specify the synthesis voice by assigning a [`setVoiceName`][voicename] instance, and provide an event handler for the `synthesizing` event to get the audio. The following example saves the translated audio as a .wav file.
 
 > [!IMPORTANT]
-> The event-based synthesis only works with a single translation, **do not** add multiple target translation languages. Additionally, the [`setVoiceName`][voicename] should be the same language as the target translation language, for example; `"de"` could map to `"de-DE-Hedda"`.
+> The event-based synthesis works only with a single translation. *Do not* add multiple target translation languages. Additionally, the `setVoiceName` value should be the same language as the target translation language. For example, `"de"` could map to `"de-DE-Hedda"`.
 
 ```java
 static void translateSpeech() throws ExecutionException, FileNotFoundException, InterruptedException, IOException {
@@ -286,7 +290,9 @@ static void translateSpeech() throws ExecutionException, FileNotFoundException,
 
 ### Manual synthesis
 
-The [`getTranslations`][translations] function returns a dictionary that can be used to synthesize audio from the translation text. Iterate through each translation, and synthesize the translation. When creating a `SpeechSynthesizer` instance, the `SpeechConfig` object needs to have its [`setSpeechSynthesisVoiceName`][speechsynthesisvoicename] property set to the desired voice. The following example translates to five languages, and each translation is then synthesized to an audio file in the corresponding neural language.
+The [`getTranslations`][translations] function returns a dictionary that you can use to synthesize audio from the translation text. Iterate through each translation and synthesize it. When you're creating a `SpeechSynthesizer` instance, the `SpeechConfig` object needs to have its [`setSpeechSynthesisVoiceName`][speechsynthesisvoicename] property set to the desired voice. 
+
+The following example translates to five languages. Each translation is then synthesized to an audio file in the corresponding neural language.
 
 ```java
 static void translateSpeech() throws ExecutionException, InterruptedException {