Merge pull request #4983 from MicrosoftDocs/release-public-preview-translator-v4

[Publishing] [Scheduled Publish] release-public-preview-translator-v4 -> main --  09/04 - 10:00 AM

Author: Albertyang0

.gitignore

@@ -20,3 +20,5 @@ _repo.*/
 .github/prompts/*.md
 .github/prompts/*.zip
 .github/patterns/*.md
+
+articles/ai-foundry/includes/get-started-fdp.md

articles/ai-services/document-intelligence/quickstarts/includes/rest-api.md

@@ -6,7 +6,7 @@ author: laujan
 manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.topic: include
-ms.date: 07/17/2025
+ms.date: 07/21/2025
 ms.author: lajanuar
 ---
 
@@ -30,7 +30,7 @@ In this quickstart, learn to use the Document Intelligence REST API to analyze a
 
 * Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
 
-* cURL command-line tool installed.
+* The `cURL` command line tool installed.
 
 * **PowerShell version 7.*+** (or a similar command-line application.):
   * [Windows](/powershell/scripting/install/installing-powershell-on-windows)

articles/ai-services/language-service/conversational-language-understanding/how-to/use-containers.md

@@ -39,9 +39,9 @@ The following table describes the minimum and recommended specifications for the
 
 We recommended that you have a CPU with AVX-512 instruction set, for the best experience (performance and accuracy).
 
-|     | Minimum host specs     | Recommended host specs |
+|  Processor   | Minimum host specs     | Recommended host specs |
 |---------------------|------------------------|------------------------|
-| **CLU**     | `1 core`, `2-GB memory`     | `4 cores`, `8-GB memory`    |
+| **CPU**     | 1-core, 2-GB memory     | 4-cores, 8-GB memory    |
 
 CPU core and memory correspond to the `--cpus` and `--memory` settings, which are used as part of the `docker run` command.
 
@@ -54,7 +54,7 @@ Before you proceed with running the docker image, you need to export your own tr
 |**{API_KEY}** |The key for your Language resource. You can find it on your resource's **Key and endpoint** page, on the Azure portal.|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|
 |**{ENDPOINT_URI}**|The endpoint for accessing the Conversational Language Understanding API. You can find it on your resource's **Key and endpoint** page, on the Azure portal.|`https://<your-custom-subdomain>.cognitiveservices.azure.com`|
 |**{PROJECT_NAME}**|The name of the project containing the model that you want to export. You can find it on your projects tab in the Language Studio portal.|myProject|
-|**{TRAINED_MODEL_NAME}** |The name of the trained model you want to export. You can find your trained models on your model evaluation tab under your project in the Language Studio portal|myTrainedModel
+|**{TRAINED_MODEL_NAME}** |The name of the trained model you want to export. You can find your trained models on your model evaluation tab under your project in the Language Studio portal|myTrainedModel|
 |**{EXPORTED_MODEL_NAME}** |The name to assign for the new exported model created.|myExportedModel |
 
 ```bash
@@ -74,8 +74,8 @@ The CLU container image can be found on the `mcr.microsoft.com` container regist
 
 The latest CLU container is available in several languages. To download the container for the English container, use the following command:
 
-```
-docker pull mcr.microsoft.com/azure-cognitive-services/language/clu:latest
+```bash
+  docker pull mcr.microsoft.com/azure-cognitive-services/language/clu:latest
 ```
 
 [!INCLUDE [Tip for using docker list](../../../includes/cognitive-services-containers-docker-list-tip.md)]
@@ -94,16 +94,18 @@ After the exported model is created, users have to run the container to download
 | **{PROJECT_NAME}**| Name of the project that the exported model belongs to  | myProject  |
 | **{EXPORTED_MODEL_NAME}**   | Exported model to be downloaded | myExportedModel   |
 
-```bash
-docker run --rm -it -p {LOCAL_CLU_PORT}:80 \
-mcr.microsoft.com/azure-cognitive-services/language/clu:{IMAGE_TAG} \ 
--v {LOCAL_MODEL_DIRECTORY}:/DeploymentPackage \
-Billing={ENDPOINT_URI} \ 
-ApiKey={API_KEY} \
-downloadmodel \
-projectName={PROJECT_NAME} \
-exportedModelName={EXPORTED_MODEL_NAME}
-```
+
+  
+  ```bash
+    docker run --rm -it -p {LOCAL_CLU_PORT}:80 \
+    mcr.microsoft.com/azure-cognitive-services/language/clu:{IMAGE_TAG} \ 
+    -v {LOCAL_MODEL_DIRECTORY}:/DeploymentPackage \
+    Billing={ENDPOINT_URI} \ 
+    ApiKey={API_KEY} \
+    downloadmodel \
+    projectName={PROJECT_NAME} \
+    exportedModelName={EXPORTED_MODEL_NAME}
+  ```
 
 DO NOT alter the downloaded files. Even altering the name or folder structure can affect the integrity of the container and might break it.
 

articles/ai-services/language-service/personally-identifiable-information/how-to/adapt-to-domain-pii.md

@@ -42,7 +42,7 @@ Once you test the service with your own data, you can use `entitySynonyms` to:
 ## Usage guidelines
 
 1. Synonyms must be restricted to phrases that directly refer to the type, and preserve semantic correctness. For example, for the entity type `InternationalBankAccountNumber`, a valid synonym could be "Financial Account Number" or *FAN*. But, the word *deposit* though may be associated with type, as it doesn't directly have a meaning of a bank account number and therefore shouldn't be used.
-1. Synonyms should be country agnostic. For example, *German passport* wouldn't be helpful to include.
+1. Synonyms should be country/region agnostic. For example, *German passport* wouldn't be helpful to include.
 1. Synonyms can't be reused for more than one entity type.
 1. This synonym recognition feature only accepts a subset of entity types supported by the service. The supported entity types and example synonyms include:
 

articles/ai-services/translator/containers/transliterate-text-parameters.md

@@ -66,7 +66,7 @@ A successful response is a JSON array with one result for each element in the in
 ### Sample request
 
 ```bash
-curl -X POST "http://localhost:5000/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn"
+curl -X POST "http://localhost:5000/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latin"
 ```
 
 ### Sample request body
@@ -92,11 +92,11 @@ The following limitations apply:
 [
   {
     "text": "Kon'nichiwa​",
-    "script": "Latn"
+    "script": "Latin"
   },
   {
     "text": "sayonara",
-    "script": "Latn"
+    "script": "Latin"
   }
 ]
 ```
@@ -111,7 +111,7 @@ The following limitations apply:
 
 ```bash
 
-  curl -X POST "http://localhost:5000/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn" -H "Content-Type: application/json" -d "[{'Text':'こんにちは'},{'Text':'さようなら'}]"
+  curl -X POST "http://localhost:5000/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latin" -H "Content-Type: application/json" -d "[{'Text':'こんにちは'},{'Text':'さようなら'}]"
 
 ```
 

articles/ai-services/translator/how-to/create-translator-resource.md

@@ -1,25 +1,51 @@
 ---
-title: Create a Translator resource
+title: Create and configure Azure AI resources
 titleSuffix: Azure AI services
-description: Learn how to create an Azure AI Translator resource and obtain your API key and endpoint URL through the Azure portal.
+description: Learn how to create and configure Azure AI resources for translation services.
 author: laujan
 ms.author: lajanuar
 manager: nitinme
-ms.date: 04/14/2025
+ms.date: 07/09/2025
 ms.service: azure-ai-translator
 ms.topic: how-to
 
 ---
 
-# Create a Translator resource
+# Azure resources for Azure AI translation
 
-In this article, you learn how to create a Translator resource in the Azure portal. [Azure AI Translator](../overview.md) is a cloud-based machine translation service that is part of the [Azure AI services](../../what-are-ai-services.md) family. Azure resources are instances of services that you create. All API requests to Azure AI services require an *endpoint* URL and a read-only *key* for authenticating access.
+Azure AI Translator is a cloud-based neural machine translation (NMT) service that allows you to add multilingual capabilities to your applications and workflows. The service supports both instant translation and batch processing, making it suitable for a wide range of business needs.
 
-## Prerequisites
+If you already have an Azure AI Translator or multi-service resource—whether used on its own or through Language Studio—you can continue to use those existing Translator resources within the Azure AI Foundry portal for NMT deployment. For more information, *see* [How to use Azure AI services in the Azure AI Foundry portal](../../connect-services-ai-foundry-portal.md).
+
+By default, Azure AI Translator utilizes neural Machine Translation (NMT) technology. With the newest preview release, you now can optionally select either the standard NMT translation or one of two Large Language Model (LLM) deployment types: GPT-4o-mini or GPT-4o. However, **using an LLM model requires you to have an Azure AI Foundry resource**.
+
+The following table provides an overview of the resource solutions for Translator within the Azure AI ecosystem:
+
+|AI Service|Scope|Use cases|
+|---------|------------|---------|
+| [Azure AI Foundry resource](/azure/ai-foundry/what-is-azure-ai-foundry) |This resource type is the recommended resource for building, deploying, and managing generative AI applications and agents in Azure AI Foundry. |The Azure AI Foundry resource is suitable for scenarios requiring orchestration of multiple AI models, custom AI agent development, and advanced AI application lifecycle management. |
+|[Azure AI Services resource](../../../ai-services/what-are-ai-services.md)|This multi-service resource provides prebuilt, ready-to-use AI models accessible through APIs for tasks like translation, language understanding, speech recognition, and computer vision.|An Azure AI Services resource allows you to integrate advanced features such as text translation, speech transcription,  and image recognition into your applications. You can also enhance models within the Azure AI Foundry portal using prebuilt AI capabilities.|
+| [Azure AI Translator services resource](../overview.md) | The Azure AI Translator resource offers access to cloud-based neural machine translation capabilities and the ability to create customized translation models using Custom Translator.|  Azure AI Translator is production-ready and can seamlessly scale up or down based on translation needs, accommodating both small and large volumes of text or documents across multiple languages.|
+
+## Step 1: create your resource
+
+## [Azure AI Foundry resource](#tab/foundry)
+
+* An Azure AI Foundry resource is your main tool for creating, deploying, and managing generative AI applications and agents. With this resource, you can access agent services, use models hosted in a serverless environment, run evaluations, and connect to the Azure OpenAI service.<br>
+
+* If you plan to use an LLM model for translation, **you must use an Azure AI Foundry resource**.<br>
+
+* To learn how to create and manage an AI Foundry resource *see* [Create your first AI Foundry resource](../../../ai-services/multi-service-resource.md)
+
+## [Azure AI Translator resource](#tab/translator)
+
+An Azure AI Translator resource is an instance of the service that you create. All API requests to Azure AI services can be accessed with an *endpoint* URL and a read-only *key* for authenticating access.
+
+### Prerequisites
 
-To get started, you need an active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [**create a free 12-month subscription**](https://azure.microsoft.com/free/).
+To get started, you need an active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/).
 
-## Create your resource
+### Create your Azure AI Translator resource
 
 With your Azure account, you can access the Translator service through two different resource types:
 
@@ -60,13 +86,13 @@ After you decide which resource type you want use to access the Translator servi
 
 ### Authentication keys and endpoint URL
 
-All Azure AI services API requests require an endpoint URL and a read-only key for authentication.
+The quickest method for authenticating your Azure AI services API requests is to include your endpoint URL and a read-only key in an authentication header. For more information, *see* [Authentication and authorization](../../authentication.md#authenticate-with-a-single-service-resource-key)
 
 * **Authentication keys**. Your key is a unique string that is passed on every request to the Translation service. You can pass your key through a query-string parameter or by specifying it in the HTTP request header.
 
 * **Endpoint URL**. Use the Global endpoint in your API request unless you need a specific Azure region or custom endpoint. For more information, see [Base URLs](../text-translation/reference/v3/reference.md#base-urls). The Global endpoint URL is `api.cognitive.microsofttranslator.com`.
 
-## Get your authentication keys and endpoint
+### Get your authentication keys and endpoint
 
 To authenticate your connection to your Translator resource, you need the key and endpoint for your resource.
 
@@ -76,7 +102,7 @@ To authenticate your connection to your Translator resource, you need the key an
 
 :::image type="content" source="../media/keys-and-endpoint-resource.png" alt-text="Screenshot of the Azure portal showing the Keys and Endpoint page of a Translator resource. The keys and endpoints are highlighted.":::
 
-## Create a Text translation client
+### Create a Text translation client
 
 Text translation supports both [global and regional endpoints](#complete-your-project-and-instance-details). Once you have your [authentication keys](#authentication-keys-and-endpoint-url), you need to create an instance of the `TextTranslationClient`, using an `AzureKeyCredential` for authentication, to interact with the Text translation service:
 
@@ -94,7 +120,61 @@ Text translation supports both [global and regional endpoints](#complete-your-pr
      TextTranslationClient client = new(credential, '<region>');
     ```
 
-## How to delete a  resource or resource group
+## Get started with Azure AI Translator REST APIs
+
+In our quickstart, learn how to use the Translator service with REST APIs.
+
+> [!div class="nextstepaction"]
+> [Get Started with Translator](../text-translation/quickstart/rest-api.md)
+
+---
+
+## Step 2: configure your resources for Azure AI Foundry
+
+Completing this setup is essential for fully integrating your environment with Azure AI Foundry. You only need to perform this setup once—afterward, you have seamless access to advanced, AI-powered question answering capabilities.
+
+In addition, we show you how to assign the correct roles and permissions within the Azure portal. These steps help you get started quickly and effectively with Azure AI Translator.
+
+## Prerequisites
+
+Before you can set up your environment, you need:
+
+* **An active Azure subscription**. If you don't have one, you can [create one for free](https://azure.microsoft.com/free/cognitive-services).
+* **Requisite permissions**. Make sure the person establishing the account and project is assigned as the Azure AI Account Owner role at the subscription level. Alternatively, having either the **Contributor** or **Cognitive Services Contributor** role at the subscription scope also meets this requirement. For more information, *see* [Role based access control (RBAC)](../../openai/how-to/role-based-access-control.md#cognitive-services-contributor).
+* An [Azure AI Foundry multi-service resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesAIFoundry) or an [Azure AI Translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation).
+
+> [!NOTE]
+>
+> We highly recommend that you use an Azure AI Foundry resource in the AI Foundry; however, you can also follow these instructions using an Azure AI Translator resource.
+
+
+Azure AI Foundry offers a unified platform for building, managing, and deploying AI solutions with a wide array of models and tools. With this integration, you gain access to features to expand your training data with generative AI. New features are continually added, making Azure AI Foundry the recommended choice for scalable Translator solutions.
+
+1. Navigate to the [Azure portal](https://azure.microsoft.com/#home).
+
+1. Go to your Azure AI Foundry resource (select **All resources** to locate your Azure AI Foundry or Azure AI Translator resource).
+
+1. Next, select **Access Control (IAM)** on the left panel, then select **Add role assignment**.
+
+   :::image type="content" source="../media/configure-resources/add-role-assignment.png" alt-text="Screenshot of add role assignment selector in the Azure portal.":::
+
+1. Search and select the **Cognitive Services User** role. Select **Next**.
+
+   :::image type="content" source="../media/configure-resources/cognitive-services-user.png" alt-text="Screenshot of Cognitive Services User from the job function roles list in the Azure portal.":::
+
+1. Navigate to the **Members** tab and then select **Managed Identity**.
+
+   :::image type="content" source="../media/configure-resources/managed-identity.png" alt-text="Screenshot of assign member access selector in the Azure portal.":::
+
+1. Select **Select members**, then in the right panel, search for and choose your Azure AI Foundry resource (the one you're using for this project), and choose **Select**.
+
+1. Finally, select **Review + assign** to confirm your selection.
+
+1. Your resources are now set up properly. Continue with setting up the fine-tuning task and continue customizing your Azure AI Translator projects.
+
+### Step 3 (optional): clean up resource
+
+If you want to clean up and remove an Azure AI resource, you can delete the resource or resource group. 
 
 > [!WARNING]
 >
@@ -114,13 +194,6 @@ To delete the resource group:
 1. Select **Delete resource group** from the top menu bar.
 1. Confirm the deletion request by entering the resource group name and selecting **Delete**.
 
-## How to get started with Azure AI Translator REST APIs
-
-In our quickstart, you learn how to use the Translator service with REST APIs.
-
-> [!div class="nextstepaction"]
-> [Get Started with Translator](../text-translation/quickstart/rest-api.md)
-
 ## Next Steps
 
 Learn more about Azure AI Translator features: