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
For more information on Translator service selected network and private endpoint configuration and support, *see*[**Virtual Network Support**](../reference/authentication.md#virtual-network-support).
26
26
27
-
####Request parameters
27
+
## Request parameters
28
28
29
-
Request parameters passed with the request are as follows:
29
+
Request parameters passed on the query string are:
30
30
31
-
| Parameter | Type | Required | Description |
32
-
| --- | --- | --- | --- |
33
-
|**api-version**|string|True|Version of the API requested by the client. Accepted value is 2025-05-01-preview.|
34
-
|**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. |
35
-
|**text**| string | True | Source text for translation. |
36
-
|**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. |
37
-
|**script**| string | False |**Specifies the script of the source text**. |
38
-
|**targets**| array | True | User-specified values for the translated (target) text. |
39
-
|**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.|
40
-
41
-
## Request headers
31
+
| Query parameter | Description |
32
+
| --- | --- |
33
+
| api-version |*Required parameter*.<br/>Version of the API requested by the client. Value must be `3.0`. |
34
+
| language |*Required parameter*.<br/>Specifies the language of the text to convert from one script to another. Possible languages are listed in the `transliteration` scope obtained by querying the service for its [supported languages](languages.md). |
35
+
| fromScript |*Required parameter*.<br/>Specifies the script used by the input text. Look up [supported languages](languages.md) using the `transliteration` scope, to find input scripts available for the selected language. |
36
+
| toScript |*Required parameter*.<br/>Specifies the output script. Look up [supported languages](languages.md) using the `transliteration` scope, to find output scripts available for the selected combination of input language and input script. |
42
37
43
-
Request headers include:
38
+
## Request headers
44
39
45
40
| Headers | Description |
46
41
| --- | --- |
47
-
|**Authentication headers**|_Required request header_.<br/>See [available options for authentication](../reference/authentication.md). |
48
-
|**Content-Type**|_Required request header_.<br/>Specifies the content type of the payload. Accepted values are: `application/json`; `charset=UTF-8`|
49
-
|**Content-Length**|_Optional_.<br/>The length of the request body. |
50
-
|**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`. |
51
-
52
-
#### Request parameters
53
-
54
-
Request parameters passed with the request are as follows:
55
-
56
-
| Parameter | Type | Required | Description |
57
-
| --- | --- | --- | --- |
58
-
|**api-version**|string|True|Version of the API requested by the client. Accepted value is 2025-05-01-preview.|
59
-
|**language**| string | True | 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. |
60
-
|**fromScript**| string | True |**Specifies the script for the source text**. *See*[supported languages](../../language-support.md),`transliteration`, to view input scripts available for the source language. |
61
-
|**toScript**| string | True | Specifies the script for the target text. *See*[supported languages](../../language-support.md), `transliteration`, to view input scripts available for the target language. |
| Content-Type |_Required request header_.<br/>Specifies the content type of the payload. Possible values are: `application/json`|
44
+
| Content-Length |_Optional_.<br/>The length of the request body. |
45
+
| X-ClientTraceId |_Optional_.<br/>A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
62
46
63
47
## Request body
64
48
@@ -79,51 +63,42 @@ The following limitations apply:
79
63
80
64
## Response body
81
65
82
-
A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:
83
-
84
-
*`detectedLanguage`: An object describing the detected language through the following properties:
85
-
86
-
*`language`: A string representing the code of the detected language.
87
-
88
-
*`score`: A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence.
89
-
90
-
The `detectedLanguage` property is only present in the result object when language `autodetection` is requested.
91
-
92
-
*`translations`: An array of translation results. The size of the array matches the number of target languages specified through the `to` query parameter. Each element in the array includes:
93
-
94
-
*`text`: A string giving the translated text.
95
-
96
-
*`language`: A string representing the language code of the target language.
66
+
A successful response is a JSON array with one result for each element in the input array. A result object includes the following properties:
97
67
98
-
*`transliteration`: An object giving the translated text in the script specified by the `toScript` parameter.
68
+
*`text`: A string that results from converting the input string to the output script.
99
69
100
-
*`script`: A string specifying the target script.
70
+
*`script`: A string specifying the script used in the output.
101
71
102
-
An example JSON response is:
72
+
An example JSON response is:
103
73
104
-
```json
105
-
[
106
-
{"text":"konnnichiha","script":"Latn"},
107
-
{"text":"sayounara","script":"Latn"}
108
-
]
109
-
```
110
-
111
-
* `text`: A string giving the translated text in the target script.
112
-
113
-
The `transliteration` object isn't included if transliteration doesn't take place.
74
+
```json
75
+
[
76
+
{"text":"konnnichiha","script":"Latn"},
77
+
{"text":"sayounara","script":"Latn"}
78
+
]
79
+
```
114
80
81
+
## Response headers
115
82
116
-
* `sourceText`: An object with a single string property named `text`, which gives the input text in the default script of the source language. `sourceText` property is present only when the input is expressed in a script that's not the usual script for the language. For example, if the input were Arabic written in Latin script, then `sourceText.text` would be the same Arabic text converted into Arab script`.`
83
+
| Headers | Description |
84
+
| --- | --- |
85
+
| X-RequestId | Value generated by the service to identify the request and used for troubleshooting purposes. |
117
86
118
-
Examples of JSON responses are provided in the [examples](#examples) section.
87
+
## Response status codes
119
88
120
-
## Response headers
89
+
The following are the possible HTTP status codes that a request returns.
121
90
122
-
| Headers | Description |
91
+
|Status Code| Description |
123
92
| --- | --- |
124
-
| X-requestid | Value generated by the service to identify the request used for troubleshooting purposes. |
125
-
| X-mt-system | Specifies the system type that was used for translation for each 'to' language requested for translation. The value is a comma-separated list of strings. Each string indicates a type: </br></br>*Custom - Request includes a custom system and at least one custom system was used during translation.*</br> Team - All other requests |
126
-
| X-metered-usage |Specifies consumption (the number of characters for which the user is charged) for the translation job request. For example, if the word "Hello" is translated from English (en) to French (fr), this field returns the value `5`.|
93
+
| 200 | Success. |
94
+
| 400 | One of the query parameters is missing or not valid. Correct request parameters before retrying. |
95
+
| 401 | The request couldn't be authenticated. Check that credentials are specified and valid. |
96
+
| 403 | The request isn't authorized. Check the details error message. This code often indicates that all free translations provided with a trial subscription are used. |
97
+
| 429 | The server rejected the request because the client exceeded request limits. |
98
+
| 500 | An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`. |
99
+
| 503 | Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header `X-RequestId`, and client identifier from request header `X-ClientTraceId`. |
100
+
101
+
If an error occurs, the request also returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the [v3 Translator reference page](../status-response-codes.md).
127
102
128
103
## Examples
129
104
@@ -135,7 +110,6 @@ The JSON payload for the request in this example:
If you're using cURL in a command-line window that doesn't support Unicode characters, take the following JSON payload and save it into a file named `request.txt`. Be sure to save the file with `UTF-8` encoding.
0 commit comments