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/preview/transliterate-api.md
+42-67Lines changed: 42 additions & 67 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,13 +6,13 @@ author: laujan
6
6
manager: nitinme
7
7
ms.service: azure-ai-translator
8
8
ms.topic: reference
9
-
ms.date: 09/02/2025
9
+
ms.date: 09/04/2025
10
10
ms.author: lajanuar
11
11
---
12
12
13
13
# Transliterate (2025-05-01-preview)
14
14
15
-
The Text transliteration API maps your source language script or alphabet to a target language script or alphabet.
15
+
The Text transliteration API maps your source language script or alphabet to a target language script or alphabet. Unlike translation, transliteration doesn't return the meaning, only the way the text is written.
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 headers
27
+
## Request parameters
28
28
29
-
Request headers include:
29
+
Request parameters passed on the query string are:
30
30
31
-
|Headers| Description |
31
+
|Query parameter| Description |
32
32
| --- | --- |
33
-
|**Authentication headers**|_Required request header_.<br/>See [available options for authentication](../reference/authentication.md). |
34
-
|**Content-Type**|_Required request header_.<br/>Specifies the content type of the payload. Accepted values are: `application/json`; `charset=UTF-8`|
35
-
|**Content-Length**|_Optional_.<br/>The length of the request body. |
36
-
|**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`. |
37
-
38
-
39
-
#### Request parameters
40
-
41
-
Request parameters passed with the request are as follows:
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](get-languages.md). |
35
+
| fromScript |*Required parameter*.<br/>Specifies the script used by the input text. Look up [supported languages](get-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](get-languages.md) using the `transliteration` scope, to find output scripts available for the selected combination of input language and input script. |
42
37
43
-
| Parameter | Type | Required | Description |
44
-
| --- | --- | --- | --- |
45
-
|**api-version**|string|True|Version of the API requested by the client. Accepted value is 2025-05-01-preview.|
46
-
|**text**| string | True | Source text for translation. |
47
-
|**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. |
48
-
|**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. |
49
-
|**script**| string | False |**Specifies the script of the source text**. |
50
-
|**targets**| array | True | User-specified values for the translated (target) text. |
51
-
|**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.|
38
+
## Request headers
52
39
53
-
54
-
#### Targets array (user-specified values for translated text)
55
-
56
-
| Parameter | Type | Required? | Description |
57
-
| --- | --- | --- | --- |
58
-
|**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.|
59
-
|**targets.script**| string | False | Specify the script of the transliterated text. |
60
-
|**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. |
| 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`. |
61
46
62
47
## Request body
63
48
@@ -78,51 +63,42 @@ The following limitations apply:
78
63
79
64
## Response body
80
65
81
-
A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:
82
-
83
-
*`detectedLanguage`: An object describing the detected language through the following properties:
84
-
85
-
*`language`: A string representing the code of the detected language.
86
-
87
-
*`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.
88
-
89
-
The `detectedLanguage` property is only present in the result object when language `autodetection` is requested.
90
-
91
-
*`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:
92
-
93
-
*`text`: A string giving the translated text.
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:
94
67
95
-
*`language`: A string representing the language code of the target language.
68
+
*`text`: A string that results from converting the input string to the output script.
96
69
97
-
*`transliteration`: An object giving the translated text in the script specified by the `toScript` parameter.
70
+
*`script`: A string specifying the script used in the output.
98
71
99
-
*`script`: A string specifying the target script.
72
+
An example JSON response is:
100
73
101
-
An example JSON response is:
102
-
103
-
```json
104
-
[
105
-
{"text":"konnnichiha","script":"Latn"},
106
-
{"text":"sayounara","script":"Latn"}
107
-
]
108
-
```
109
-
110
-
* `text`: A string giving the translated text in the target script.
111
-
112
-
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
+
```
113
80
81
+
## Response headers
114
82
115
-
* `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. |
116
86
117
-
Examples of JSON responses are provided in the [examples](#examples) section.
87
+
## Response status codes
118
88
119
-
## Response headers
89
+
The following are the possible HTTP status codes that a request returns.
120
90
121
-
| Headers | Description |
91
+
|Status Code| Description |
122
92
| --- | --- |
123
-
| X-requestid | Value generated by the service to identify the request used for troubleshooting purposes. |
124
-
| 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 |
125
-
| 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 [Status code reference page](../reference/status-response-codes.md).
126
102
127
103
## Examples
128
104
@@ -134,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.
@@ -36,7 +36,7 @@ Request parameters passed on the query string are:
36
36
| 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. |
37
37
| 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. |
0 commit comments