Translator 3.0: Transliterate
Converts text in one language from one script to another script.
Request URL
Send a POST request to:
https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0
See Virtual Network Support for Translator service selected network and private endpoint configuration and support.
Request parameters
Request parameters passed on the query string are:
| Query parameter | Description |
|---|---|
| api-version | Required parameter. Version of the API requested by the client. Value must be 3.0. |
| language | Required parameter. 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. |
| fromScript | Required parameter. Specifies the script used by the input text. Look up supported languages using the transliteration scope, to find input scripts available for the selected language. |
| toScript | Required parameter. Specifies the output script. Look up supported languages using the transliteration scope, to find output scripts available for the selected combination of input language and input script. |
Request headers include:
| Headers | Description |
|---|---|
| Authentication headers | Required request header. See available options for authentication. |
| Content-Type | Required request header. Specifies the content type of the payload. Possible values are: application/json |
| Content-Length | Optional. The length of the request body. |
| X-ClientTraceId | Optional. 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. |
Request body
The body of the request is a JSON array. Each array element is a JSON object with a string property named Text, which represents the string to convert.
[
{"Text":"こんにちは"},
{"Text":"さようなら"}
]
The following limitations apply:
- The array can have at most 10 elements.
- The text value of an array element can't exceed 1,000 characters including spaces.
- The entire text included in the request can't exceed 5,000 characters including spaces.
Response body
A successful response is a JSON array with one result for each element in the input array. A result object includes the following properties:
text: A string that results from converting the input string to the output script.script: A string specifying the script used in the output.
An example JSON response is:
[
{"text":"konnnichiha","script":"Latn"},
{"text":"sayounara","script":"Latn"}
]
Response headers
| Headers | Description |
|---|---|
| X-RequestId | Value generated by the service to identify the request and used for troubleshooting purposes. |
Response status codes
The following are the possible HTTP status codes that a request returns.
| Status Code | Description |
|---|---|
| 200 | Success. |
| 400 | One of the query parameters is missing or not valid. Correct request parameters before retrying. |
| 401 | The request couldn't be authenticated. Check that credentials are specified and valid. |
| 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. |
| 429 | The server rejected the request because the client exceeded request limits. |
| 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. |
| 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. |
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.
Examples
The following example shows how to convert two Japanese strings into Romanized Japanese.
The JSON payload for the request in this example:
[{"text":"こんにちは","script":"jpan"},{"text":"さようなら","script":"jpan"}]
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.
curl -X POST "https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d @request.txt