add new glossary article

Author: laujan

articles/cognitive-services/Translator/document-translation/how-to-guides/create-use-glossary-dictionary.md

@@ -5,22 +5,34 @@ ms.topic: how-to
 manager: nitinme
 ms.author: lajanuar
 author: laujan
-ms.date: 03/13/2023
+ms.date: 03/14/2023
 ---
 
 # Create and use a glossary with Document Translation
 
-A glossary is a custom dictionary that you create for the Document Translation service to use during the translation process. Common use cases for glossaries include:
+A glossary is a custom dictionary that you create for the Document Translation service to use during the translation process. Currently, the glossary feature supports one-to-one source-to-target (not one-to-many language) language translations. Common use cases for glossaries include:
 
-* **Domain-specific terminology**. Designate specific meanings for your unique context.
+* **Domain-specific terminology**. Create a glossary that designates specific meanings for your unique context.
 
 * **Name brand preservation**. Restrict Document Translation from translating product name brands by using a glossary with the same source and target text.
 
-* **Specify translation for words with several meanings**. Choose a specific translation for polysemantic words.
+* **Specify translation for words with several meanings**. Choose a specific translation for poly​semantic words.
+
+## Case sensitivity
+
+By default, Azure Cognitive Services Translator service API is **case-sensitive**, meaning that it matches terms in the source text based on case.
+
+#### Partial sentence application
+
+When your glossary is applied to **part of a sentence**, the Document Translation API checks whether the glossary term matches the case in the source text. If the casing doesn't match, the glossary isn't applied.
+
+#### Complete sentence application
+
+When your glossary is applied to a **complete sentence**, the service becomes **case-insensitive**. It matches the glossary term regardless of its casing in the source text. This provision applies the correct results for use cases involving idioms and quotes.
 
 ## Create, upload, and use a glossary file
 
-1. Create a file in a supported format that contains all the terms and phrases you want to use in your translation. You can check to see if your format is supported using the [Get supported glossary formats](../reference/get-supported-glossary-formats.md). The following is a sample REST API call using PowerShell. Update `your-document-translation-key` and `your-document-translation-endpoint` with values from the Azure portal. Only one key is necessary to make an API call.:
+1. **Create your glossary file.** Create a file in a supported format that contains all the terms and phrases you want to use in your translation. You can check to see if your format is supported using the [Get supported glossary formats](../reference/get-supported-glossary-formats.md). To follow, is a sample REST API call using PowerShell. Update `your-document-translation-key` and `your-document-translation-endpoint` with values from the Azure portal. Only one key is necessary to make an API call.
 
    :::image type="content" source="../media/key-endpoint.png" alt-text="Screenshot showing the key and endpoint fields in the Azure portal.":::
 
@@ -40,8 +52,19 @@ A glossary is a custom dictionary that you create for the Document Translation s
 
    :::image type="content" source="../media/tsv-file.png" alt-text="Example of a TSV formatted glossary file formatted":::
 
-In this English-source glossary, the words can have different meanings depending upon the context in which they are used. The glossary provides translations for each word in the file to help ensure accurate translations.
+In this English-source glossary, the words can have different meanings depending upon the context in which they're used. The glossary provides translations for each word in the file to help ensure accurate translations.
+
+For instance, when the word `Bank` appears in a financial document, it would be translated as `Banque` to reflect its financial meaning. If the word `Bank` appears in a geography document, it might be translated as `land beside a river` to reflect its topographical meaning. Similarly, the word `Crane` can refer to either a `bird` or a `machine`.
+
+1. **Upload your glossary to the Azure storage**. To complete this step, you need an [Azure Blob Storage account](https://ms.portal.azure.com/#create/Microsoft.StorageAccount) with [containers](/azure/storage/blobs/storage-quickstart-blobs-portal?branch=main#create-a-container) to store and organize your blob data within your storage account.
+
+1. **Specify your glossary in the translation request.** Include the glossary URL, format, and version in your **`POST`** request:
+
+   :::code language="json" source="translate-with-glossary.json" range="1-23" highlight="13-15":::
+
+## Next steps
 
-For instance, if the word "Bank" appears in a financial document, it would be translated as "Banque" to reflect its financial meaning. If the word "Bank" appears in a geography document, it might be translated as "land beside a river" to reflect its geographic meaning. Similarly, the word "Crane" can refer to either a bird or a machine.
+Try the Document Translation how-to guide to asynchronously translate whole documents using a programming language of your choice:
 
-1. Next, Upload your glossary: upload your glossary to your Azure Blob Storage account. 
+> [!div class="nextstepaction"]
+> [Use Document Translation REST APIs](use-rest-api-programmatically.md)

articles/cognitive-services/Translator/document-translation/how-to-guides/translate-with-glossary.json

@@ -0,0 +1,23 @@
+{
+    "inputs": [
+        {
+            "source": {
+                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
+            },
+            "targets": [
+                {
+                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
+                    "language": "fr",
+                    "glossaries": [
+                        {
+                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
+                            "format": "xliff",
+                            "version": "1.2"
+                        }
+                    ]
+
+                }
+            ]
+        }
+    ]
+}