You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/ai-services/translator/text-translation/how-to/migrate-to-v4.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: Migrate to v4.0 - Azure AI Translator
2
+
title: Migrate from Translator v3 to the latest Azure AI Translator version.
3
3
titleSuffix: Azure AI services
4
4
description: This article provides the steps to help you migrate from Azure AI Translator v3 to 2025-05-01-preview Text translation API.
5
5
author: laujan
@@ -12,7 +12,7 @@ ms.author: lajanuar
12
12
13
13
# Azure AI Translator 2025-05-01-preview migration
14
14
15
-
Azure AI Translator text translation 2025-05-01-preview (v4.0) is our latest cloud-based, multilingual neural machine translation service. As Azure AI Translator matures, we're focused on patterns and practices to best support and add value to our users.
15
+
Azure AI Translator text translation 2025-05-01-preview is our latest cloud-based, multilingual neural machine translation service. As Azure AI Translator matures, we're focused on patterns and practices to best support and add value to our users.
16
16
17
17
>[!IMPORTANT]
18
18
> * Azure AI Translator REST API `2025-05-01-preview` is new version of the Azure AI Translator REST API **with breaking changes**.
@@ -52,10 +52,10 @@ The following table compares Translator `2025-05-01-preview` and Translator v3 A
|Feature no longer supported|[Detect language](../reference/v3/detect.md)|
56
-
|Feature no longer supported|[BreakSentence](../reference/v3/break-sentence.md)|
57
-
|Feature no longer supported|[Dictionary Lookup](../reference/v3/dictionary-lookup.md)|
58
-
|Feature no longer supported|[Dictionary Examples](../reference/v3/dictionary-examples.md)|
55
+
[BreakSentence](../reference/v3/break-sentence.md)|Feature no longer supported.<br>Use sentence delimiters function or a Natural Language Processing (NLP) library supported for your programming language.|
56
+
[Dictionary Lookup](../reference/v3/dictionary-lookup.md)|Feature no longer supported|
57
+
|[Dictionary Examples](../reference/v3/dictionary-examples.md)|Feature no longer supported|
Copy file name to clipboardExpand all lines: articles/ai-services/translator/text-translation/reference/v4/reference-overview.md
+54-15Lines changed: 54 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ author: laujan
6
6
manager: nitinme
7
7
ms.service: azure-ai-translator
8
8
ms.topic: reference
9
-
ms.date: 04/18/2025
9
+
ms.date: 05/05/2025
10
10
ms.author: lajanuar
11
11
---
12
12
@@ -16,7 +16,6 @@ Azure AI Translator `2025-05-01-preview` is our latest cloud-based, multilingual
16
16
17
17
The Translator service is an optimal solution for managing extensive multilingual content. It easily integrates with your applications and workflows through a single REST API call and supports multiple programming languages. Translator supports over 100 languages and dialects, making it ideal for businesses, developers, and organizations seeking to seamlessly integrate multilingual communication.
18
18
19
-
Azure AI Translator prioritizes data security and privacy, complying with regulations like GDPR, HIPAA, and ISO/SOC, thus ensuring that it's a reliable solution for handling sensitive and confidential information.
20
19
21
20
>[!IMPORTANT]
22
21
> * Azure AI Translator REST API `2025-05-01-preview` is new version of the Azure AI Translator REST API **with breaking changes**.
@@ -28,7 +27,7 @@ Azure AI Translator prioritizes data security and privacy, complying with regula
28
27
29
28
***`LLM` choice**. You can choose a large language model for translation based on factors such as quality, cost, and other considerations.
30
29
31
-
***Adaptive custom translation**. You can provide reference translations or translation memory datasets to enable an `LLM` model to perform few-shot translations tailored to your needs. Few-shot translation is a machine translation method where the model is trained or fine-tuned with only a limited number of examples to translate between languages.
30
+
***Adaptive custom translation**. You can provide reference translations or translation memory datasets to enable an `LLM` model to perform few-shot translations tailored to your needs.
32
31
33
32
* The **Translator** resource doesn't support Neural Machine Translation (`NMT`) translations.
34
33
@@ -40,21 +39,61 @@ Metrics allow you to view the translator usage and availability information in A
40
39
41
40
:::image type="content" source="../../../media/azure-portal-metrics-v4.png" alt-text="Screenshot of HTTP request metrics in the Azure portal.":::
42
41
43
-
This table lists available metrics with description of how they're used to monitor translation API calls.
42
+
#### Metrics terminology
43
+
44
+
***PTU**: provisioned throughput units
45
+
***TPS**: transactions per second
46
+
***TPM**: tokens per minute
47
+
48
+
The following tables list available metrics with description of how they're used to monitor **Translator resource** API calls.
49
+
50
+
#### Translator resource HTTP requests
51
+
52
+
| Metrics | Description |
53
+
|:----|:-----|
54
+
|`BlockedCalls`| Number of calls that exceeded rate or quota limit.|
55
+
|`ClientErrors`| Number of calls with client-side error(4XX).|
56
+
|`Latency`| Duration to complete request in milliseconds.|
57
+
|`Ratelimit`| The current rate limit of the rate limit key.|
58
+
|`ServerErrors`| Number of calls with server internal error(5XX).|
59
+
|`SuccessfulCalls`| Number of successful calls.|
60
+
|`TotalCalls`| Total number of API calls.|
61
+
|`TotalErrors`| Number of calls with error response.|
62
+
|`TotalTokenCalls`| Total number of API calls via token service using authentication token.|
63
+
64
+
#### Translator resource usage
65
+
66
+
| Metrics | Description |
67
+
|:----|:-----|
68
+
|`TextCharactersTranslated`|Number of characters in incoming text translation request.|
69
+
|`TextCustomCharactersTranslated`|Number of characters in incoming custom text translation request.|
70
+
|`TextTrainedCharacters`|Number of characters trained using text translation.|
71
+
|`DocumentCharactersTranslated`|Number of characters in document translation request.|
72
+
|`DocumentCustomCharactersTranslated`|Number of characters in custom document translation request.|
73
+
74
+
The following tables list available metrics with description of how they're used to monitor **Azure OpenAI** API calls.
75
+
76
+
#### Azure OpenAI HTTP requests
44
77
45
78
| Metrics | Description |
46
79
|:----|:-----|
47
-
| BlockCalls| Number of calls that exceed rate or quota.|
48
-
| ClientErrors| Number of calls with client-side error (HTTP response code 4xx)|
49
-
| DataIn| Size of incoming data in bytes.|
50
-
| DataOut| Size of outgoing data in bytes.|
51
-
| Latency| Duration to complete request in milliseconds.|
52
-
| RateLimit| The current rate limit of the ratelimit key.|
53
-
| ServerErrors| Number of calls with server internal error (HTTP response code 5xx).|
54
-
| SuccessfulCalls| Number of successful calls (HTTP response code 2xx).|
55
-
| TotalCalls| Total number of calls.|
56
-
| TotalErrors|Total number of calls with error response (HTTP response code 4xx or 5xx)|
57
-
| TotalTokenCalls|Total number of token calls|
80
+
|`AzureOpenAIAvailabilityRate`|Availability percentage with the following calculation:<br>`(Total Calls - Server Errors) / Total Calls`. Server Errors include any HTTP response >= 500.|
81
+
|`AzureOpenAIRequests`|Number of calls made to the Azure OpenAI API over a period of time. Applies to `PTU`, `PTU`-managed, and Pay-as-you-go deployments. To breakdown API requests, you can add a filter or apply splitting by the following dimensions: <br> `ModelDeploymentName`, `ModelName`, `ModelVersion`, `StatusCode` (successful, client errors, server errors), `StreamType` (streaming vs nonstreaming requests), and `Operation`.|
82
+
83
+
#### Azure OpenAI usage
84
+
85
+
| Metrics | Description |
86
+
|:----|:-----|
87
+
|`ActiveTokens`|Total tokens minus cached tokens over a period of time. Applies to `PTU` and `PTU`-managed deployments. Use this metric to understand your `TPS`- or `TPM`-based utilization for `PTU`s and compare your benchmarks for target `TPS` or `TPM` for your scenarios. <br> To breakdown API requests, you can add a filter or apply splitting by the following dimensions: `ModelDeploymentName`, `ModelName`, `ModelVersion`.|
88
+
|`GeneratedTokens`|Number of tokens generated (output) from an OpenAI model. Applies to `PTU`, `PTU`-managed, and Pay-as-you-go deployments. To analyze this metric in detail, you can add a filter or apply splitting by the following dimensions:<br>`ModelDeploymentName`or `ModelName`.|
89
+
|`FineTunedTrainingHours`|Number of training hours processed on an OpenAI fine-tuned model.|
90
+
|`TokenTransaction`|Number of inference tokens processed on an OpenAI model. Calculated as prompt tokens (input) plus generated tokens (output). Applies to `PTU`, `PTU`-managed, and Pay-as-you-go deployments. To analyze this metric in detail, you can add a filter or apply splitting by the following dimensions:<br>`ModelDeploymentName`or `ModelName`.|
91
+
|`ProcessedPromptTokens`|Number of prompt tokens processed (input) on an OpenAI model. Applies to `PTU`, `PTU`-managed, and Pay-as-you-go deployments. To analyze this metric in detail, you can add a filter or apply splitting by the following dimensions:<br>`ModelDeploymentName`or `ModelName`.|
92
+
|`AzureOpenAIContextTokensCacheMatchRate`|Percentage of prompt tokens that hit the cache. Applies to `PTU` and `PTU`-managed deployments.
93
+
|`AzureOpenAIProvisionedManagedUtilizationV2`|Utilization percentage for a provisioned-managed deployment, calculated as (`PTU`s consumed / `PTU`s deployed) x 100. When utilization is greater than or equal to 100%, calls are throttled and error code 429 is returned. To analyze this metric in detail, you can add a filter or apply splitting by the following dimensions: `ModelDeploymentName`, `ModelName`, `ModelVersion`, and `StreamType` (streaming vs nonstreaming requests).|
Copy file name to clipboardExpand all lines: articles/ai-services/translator/text-translation/reference/v4/translate-api.md
+28-25Lines changed: 28 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,41 +42,36 @@ Request headers include:
42
42
|**Content-Length**|_Optional_.<br/>The length of the request body. |
43
43
|**X-ClientTraceId**|_Optional_.<br/>A client-generated GUID to uniquely identify the request. You can omit this optional header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
44
44
45
-
#### Required parameters
45
+
#### Request parameters
46
46
47
47
Request parameters passed with the request are as follows:
48
48
49
-
| Parameter | Type | Required?| Description |
49
+
| Parameter | Type | Required | Description |
50
50
| --- | --- | --- | --- |
51
51
|**`api-version`**|string|True|Version of the API requested by the client. Accepted value is `2025-05-01-preview`.|
52
52
|**`text`**| string | True | Source text for translation. |
53
53
|**`targets`**| array | True | User-specified values for the translated (`target`) text. |
54
54
|**`language`**| string | True |The language code for the translated (`target`) text *specified in the `targets` array*. Accepted values are [supported language](../../../language-support.md) codes for the translation operation.|
55
-
56
-
57
-
#### Optional parameters (not included in the targets array)
58
-
59
-
| Parameter | Type | Required? | Description |
60
-
| --- | --- | --- | --- |
61
55
|**textType**| string | False | Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Accepted values are: plain (default) or html. |
62
56
|**language**| string | False | Specifies the language code for the `source` text. If not specified, the system autodetects the language of the source text. Accepted values are list of language code supported by the specified model. |
63
57
|**script**| string | False | Specifies the script of the source text. |
64
58
65
-
#### Optional parameters (included in the targets array)
59
+
#### Targets array (user-specified values for translated text)
66
60
67
61
| Parameter | Type | Required? | Description |
68
62
| --- | --- | --- | --- |
69
-
|**script**| string | False | Specify the script of the translated text. |
70
-
|**deploymentName**| string | False | Default is `general`, which uses `NMT` system. `your-model-name-gpt-4o-mini` is an example deployment name for the GPT-4o-mini model. `gpt-4o` uses GPT-4o model.<br> `<custom model id>` uses the custom `NMT` model tuned by customer.<br> |
71
-
|**allowFallback**| string | False | Specifies that if the intended model isn't supported for a given source and target language pair, the service is permitted to fall back to a general system. This action ensures that translations can still be provided even when the preferred model is unavailable. Default is `true`. If `false` system returns an error if language pair isn't supported. |
72
-
|**tone**| string | False | Desired tone of target translation. Accepted values are `formal`, `informal`, or `neutral`. |
73
-
|**gender** (For more information, *see*[Gender-specific translations](#gender-specific-translations))| string | False | Desired gender of target translation. Accepted values are `male`, `female`, or `neutral`.|
74
-
|**adaptiveDatasetId**| string | False | Reference dataset ID having sentence pair to generate adaptive customized translation |
75
-
|**referenceTextPairs**| string | False | Reference text pairs to generate adaptive customized translation |
76
-
|**referenceTextPairs.source**| string | False | Source text in reference text pair. If provided, `adaptiveDatasetId` is ignored |
77
-
|**referenceTextPairs.target**| string | False | Target text in reference text pair. |
78
-
|**profanityAction**| string | False | Specifies how profanities should be treated in translations. Accepted values are: `NoAction` (default), `Marked`, or `Deleted`. |
79
-
|**profanityMarker**| string | False | Specifies how profanities should be marked in translations. Accepted values are `Asterisk` (default) or Tag. |
63
+
|**targets.language**| string | True |The language code for the translated (`target`) text *specified in the `targets` array*. Accepted values are [supported language](../../../language-support.md) codes for the translation operation.|
64
+
|**targets.script**| string | False | Specify the script of the translated text. |
65
+
|**targets.deploymentName**| string | False | Default is `general`, which uses `NMT` system. `your-model-name-gpt-4o-mini` is an example deployment name for the GPT-4o-mini model. `gpt-4o` uses GPT-4o model.<br> `<categoryID>` uses the custom `NMT` model tuned by customer.<br> |
66
+
|**targets.allowFallback**| string | False | If the desired model doesn't support a particular pair of source and target languages, an alternative approach may be employed. In such cases, the service may default to utilizing a general system as a substitute. This action ensures that translations can still be provided even when the preferred model is unavailable. Default is `true`. If `false` system returns an error if language pair isn't supported. |
67
+
|**targets.tone**| string | False | Desired tone of target translation. Accepted values are `formal`, `informal`, or `neutral`. |
68
+
|**targets.gender** (For more information, *see*[Gender-specific translations](#gender-specific-translations))| string | False | Desired gender of target translation. Accepted values are `male`, `female`, or `neutral`.|
69
+
|**targets.adaptiveDatasetId**| string | False | Reference dataset ID having sentence pair to generate adaptive customized translation. The maximum number of reference text pairs to generate adaptive customized translation is five (5).|
70
+
|**targets.referenceTextPairs**| string | False | Reference text pairs to generate adaptive customized translation. |
71
+
|**targets.referenceTextPairs.source**| string | False | Source text in reference text pair. If provided, `adaptiveDatasetId` is ignored. |
72
+
|**targets.referenceTextPairs.target**| string | False | Target text in reference text pair. |
73
+
|**targets.profanityAction**| string | False | Specifies how profanities should be treated in translations. Accepted values are: `NoAction` (default), `Marked`, or `Deleted`. |
74
+
|**targets.profanityMarker**| string | False | Specifies how profanities should be marked in translations. Accepted values are `Asterisk` (default) or Tag. |
80
75
81
76
##### Gender-specific translations
82
77
@@ -98,6 +93,7 @@ The request body is formatted as a JSON array, where each element is a JSON obje
98
93
[
99
94
{
100
95
"text": "I would really like to drive your car around the block a few times.",
96
+
"language": "en",
101
97
"targets": [
102
98
{
103
99
"language": "es"
@@ -157,6 +153,7 @@ Examples of JSON responses are provided in the [examples](#examples) section.
157
153
[
158
154
{
159
155
"text": "Doctor is available next Monday. Do you want to schedule an appointment?",
156
+
"language": "en",
160
157
"targets": [
161
158
{
162
159
"language": "es"
@@ -200,6 +197,7 @@ Examples of JSON responses are provided in the [examples](#examples) section.
200
197
[
201
198
{
202
199
"text": "Doctor is available next Monday. Do you want to schedule an appointment?",
200
+
"language": "en",
203
201
"targets": [
204
202
{
205
203
"language": "es"
@@ -253,10 +251,11 @@ Here, users request specific `GPT` models for deployment.
253
251
[
254
252
{
255
253
"text": "Doctor is available next Monday. Do you want to schedule an appointment?",
0 commit comments