Skip to content

Commit d1178b6

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #252107 from laujan/issue-114806-translator-endpoint
update reference, resolve issue 114806
2 parents f67eda5 + a6c52c4 commit d1178b6

File tree

9 files changed

+205
-254
lines changed

9 files changed

+205
-254
lines changed

‎articles/ai-services/translator/reference/rest-api-guide.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ manager: nitinme
88
ms.service: cognitive-services
99
ms.subservice: translator-text
1010
ms.topic: reference
11-
ms.date: 07/18/2023
11+
ms.date: 09/18/2023
1212
ms.author: lajanuar
1313
---
1414

1515
# Text Translation REST API
1616

17-
Text Translation is a cloud-based feature of the Azure AI Translator service and is part of the Azure AI service family of REST APIs. The Text Translation API translates text between language pairs across all [supported languages and dialects](../../language-support.md). The available methods are listed in the table below:
17+
Text Translation is a cloud-based feature of the Azure AI Translator service and is part of the Azure AI service family of REST APIs. The Text Translation API translates text between language pairs across all [supported languages and dialects](../../language-support.md). The available methods are listed in the following table:
1818

1919
| Request| Method| Description|
2020
|---------|--------------|---------|

‎articles/ai-services/translator/reference/v3-0-break-sentence.md

Lines changed: 28 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -23,26 +23,29 @@ Send a `POST` request to:
2323

2424
```HTTP
2525
https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0
26+
2627
```
2728

29+
_See_ [**Virtual Network Support**](v3-0-reference.md#virtual-network-support) for Translator service selected network and private endpoint configuration and support.
30+
2831
## Request parameters
2932

3033
Request parameters passed on the query string are:
3134

3235
| Query Parameter | Description |
3336
| -------| ----------- |
3437
| api-version <img width=200/> | **Required query parameter**.<br/>Version of the API requested by the client. Value must be `3.0`. |
35-
| language | **Optional query parameter**.<br/>Language tag identifying the language of the input text. If a code isn't specified, automatic language detection will be applied. |
36-
| script | **Optional query parameter**.<br/>Script tag identifying the script used by the input text. If a script isn't specified, the default script of the language will be assumed. |
38+
| language | **Optional query parameter**.<br/>Language tag identifying the language of the input text. If a code isn't specified, automatic language detection is applied. |
39+
| script | **Optional query parameter**.<br/>Script tag identifying the script used by the input text. If a script isn't specified, the default script of the language is assumed. |
3740

3841
Request headers include:
3942

4043
| Headers | Description |
4144
| ------- | ----------- |
4245
| Authentication header(s) <img width=200/> | **Required request header**.<br/>See <a href="v3-0-reference.md#authentication">available options for authentication</a>. |
4346
| Content-Type | **Required request header**.<br/>Specifies the content type of the payload. Possible values are: `application/json`. |
44-
| Content-Length | **Required request header**.<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`. |
47+
| Content-Length | **Required request header**.<br/>The length of the request body. |
48+
| 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`. |
4649

4750
## Request body
4851

@@ -59,21 +62,21 @@ The following limitations apply:
5962
* The array can have at most 100 elements.
6063
* The text value of an array element can't exceed 50,000 characters including spaces.
6164
* The entire text included in the request can't exceed 50,000 characters including spaces.
62-
* If the `language` query parameter is specified, then all array elements must be in the same language. Otherwise, language auto-detection is applied to each array element independently.
65+
* If the `language` query parameter is specified, then all array elements must be in the same language. Otherwise, language autodetection is applied to each array element independently.
6366

6467
## Response body
6568

6669
A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:
6770

68-
* `sentLen`: An array of integers representing the lengths of the sentences in the text element. The length of the array is the number of sentences, and the values are the length of each sentence.
71+
* `sentLen`: An array of integers representing the lengths of the sentences in the text element. The length of the array is the number of sentences, and the values are the length of each sentence.
6972

7073
* `detectedLanguage`: An object describing the detected language through the following properties:
7174

7275
* `language`: Code of the detected language.
7376

7477
* `score`: A float value indicating the confidence in the result. The score is between zero (0) and one (1.0). A low score (<= 0.4) indicates a low confidence.
7578

76-
The `detectedLanguage` property is only present in the result object when language auto-detection is requested.
79+
The `detectedLanguage` property is only present in the result object when language autodetection is requested.
7780

7881
An example JSON response is:
7982

@@ -95,57 +98,30 @@ An example JSON response is:
9598

9699
## Response headers
97100

98-
<table width="100%">
99-
<th width="20%">Headers</th>
100-
<th>Description</th>
101-
<tr>
102-
<td>X-RequestId</td>
103-
<td>Value generated by the service to identify the request. It's used for troubleshooting purposes.</td>
104-
</tr>
105-
</table>
101+
|Headers|Description|
102+
|--- |--- |
103+
|X-RequestId|Value generated by the service to identify the request. It's used for troubleshooting purposes.|
106104

107105
## Response status codes
108106

109-
The following are the possible HTTP status codes that a request returns.
110-
111-
<table width="100%">
112-
<th width="20%">Status Code</th>
113-
<th>Description</th>
114-
<tr>
115-
<td>200</td>
116-
<td>Success.</td>
117-
</tr>
118-
<tr>
119-
<td>400</td>
120-
<td>One of the query parameters is missing or not valid. Correct request parameters before retrying.</td>
121-
</tr>
122-
<tr>
123-
<td>401</td>
124-
<td>The request couldn't be authenticated. Check that credentials are specified and valid.</td>
125-
</tr>
126-
<tr>
127-
<td>403</td>
128-
<td>The request isn't authorized. Check the details error message. This response code often indicates that all free translations provided with a trial subscription have been used up.</td>
129-
</tr>
130-
<tr>
131-
<td>429</td>
132-
<td>The server rejected the request because the client has exceeded request limits.</td>
133-
</tr>
134-
<tr>
135-
<td>500</td>
136-
<td>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`.</td>
137-
</tr>
138-
<tr>
139-
<td>503</td>
140-
<td>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`.</td>
141-
</tr>
142-
</table>
143-
144-
If an error occurs, the request will also return 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](./v3-0-reference.md#errors).
107+
The following are the possible HTTP status codes that a request returns.
108+
109+
|Status Code|Description|
110+
|--- |--- |
111+
|200|Success.|
112+
|400|One of the query parameters is missing or not valid. Correct request parameters before retrying.|
113+
|401|The request couldn't be authenticated. Check that credentials are specified and valid.|
114+
|403|The request isn't authorized. Check the details error message. This response code often indicates that all free translations provided with a trial subscription have been used up.|
115+
|429|The server rejected the request because the client has exceeded request limits.|
116+
|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`.|
117+
|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`.|
118+
119+
120+
If an error occurs, the request 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](./v3-0-reference.md#errors).
145121

146122
## Examples
147123

148-
The following example shows how to obtain sentence boundaries for a single sentence. The language of the sentence is automatically detected by the service.
124+
The following example shows how to obtain sentence boundaries for a single sentence. The service automatically detects the sentence language.
149125

150126
```curl
151127
curl -X POST "https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'How are you? I am fine. What did you do today?'}]"

‎articles/ai-services/translator/reference/v3-0-detect.md

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,11 @@ manager: nitinme
99
ms.service: cognitive-services
1010
ms.subservice: translator-text
1111
ms.topic: reference
12-
ms.date: 07/18/2023
12+
ms.date: 09/19/2023
1313
ms.author: lajanuar
1414
---
1515

16+
<!-- markdownlint-disable MD033 -->
1617
# Translator 3.0: Detect
1718

1819
Identifies the language of a piece of text.
@@ -23,28 +24,31 @@ Send a `POST` request to:
2324

2425
```HTTP
2526
https://api.cognitive.microsofttranslator.com/detect?api-version=3.0
27+
2628
```
2729

30+
_See_ [**Virtual Network Support**](v3-0-reference.md#virtual-network-support) for Translator service selected network and private endpoint configuration and support.
31+
2832
## Request parameters
2933

3034
Request parameters passed on the query string are:
3135

3236
| Query parameter | Description |
3337
| --- | --- |
34-
| api-version | *Required parameter*.<br/>Version of the API requested by the client. Value must be `3.0`. |
38+
| api-version | *Required parameter*.<br>Version of the API requested by the client. Value must be `3.0`. |
3539

3640
Request headers include:
3741

3842
| Headers | Description |
3943
| --- | --- |
40-
| Authentication header(s) | <em>Required request header</em>.<br/>See [available options for authentication](./v3-0-reference.md#authentication)</a>. |
41-
| Content-Type | *Required request header*.<br/>Specifies the content type of the payload. Possible values are: `application/json`. |
42-
| Content-Length | *Required request header*.<br/>The length of the request body. |
43-
| X-ClientTraceId | *Optional*.<br/>A client-generated GUID to uniquely identify the request. Note that you can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |
44+
| Authentication header(s) | <em>Required request header</em>.<br>See [available options for authentication](./v3-0-reference.md#authentication)</a>. |
45+
| Content-Type | *Required request header*.<br>Specifies the content type of the payload. Possible values are: `application/json`. |
46+
| Content-Length | *Required request header*.<br>The length of the request body. |
47+
| 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`. |
4448

4549
## Request body
4650

47-
The body of the request is a JSON array. Each array element is a JSON object with a string property named `Text`. Language detection is applied to the value of the `Text` property. The language auto-detection works better with longer input text. A sample request body looks like that:
51+
The body of the request is a JSON array. Each array element is a JSON object with a string property named `Text`. Language detection is applied to the value of the `Text` property. The language autodetection works better with longer input text. A sample request body looks like that:
4852

4953
```json
5054
[
@@ -55,21 +59,21 @@ The body of the request is a JSON array. Each array element is a JSON object wit
5559
The following limitations apply:
5660

5761
* The array can have at most 100 elements.
58-
* The entire text included in the request cannot exceed 50,000 characters including spaces.
62+
* The entire text included in the request can't exceed 50,000 characters including spaces.
5963

6064
## Response body
6165

6266
A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:
6367

64-
* `language`: Code of the detected language.
68+
* `language`: Code of the detected language.
69+
70+
* `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.
6571

66-
* `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.
72+
* `isTranslationSupported`: A boolean value that is true if the detected language is one of the languages supported for text translation.
6773

68-
* `isTranslationSupported`: A boolean value which is true if the detected language is one of the languages supported for text translation.
74+
* `isTransliterationSupported`: A boolean value that is true if the detected language is one of the languages supported for transliteration.
6975

70-
* `isTransliterationSupported`: A boolean value which is true if the detected language is one of the languages supported for transliteration.
71-
72-
* `alternatives`: An array of other possible languages. Each element of the array is another object with the same properties listed above: `language`, `score`, `isTranslationSupported` and `isTransliterationSupported`.
76+
* `alternatives`: An array of other possible languages. Each element of the array is another object the following properties: `language`, `score`, `isTranslationSupported` and `isTransliterationSupported`.
7377

7478
An example JSON response is:
7579

@@ -95,23 +99,23 @@ An example JSON response is:
9599

96100
| Headers | Description |
97101
| --- | --- |
98-
| X-RequestId | Value generated by the service to identify the request. It is used for troubleshooting purposes. |
102+
| X-RequestId | Value generated by the service to identify the request. It's used for troubleshooting purposes. |
99103

100104
## Response status codes
101105

102-
The following are the possible HTTP status codes that a request returns.
106+
The following are the possible HTTP status codes that a request returns.
103107

104108
| Status Code | Description |
105109
| --- | --- |
106110
| 200 | Success. |
107111
| 400 | One of the query parameters is missing or not valid. Correct request parameters before retrying. |
108-
| 401 | The request could not be authenticated. Check that credentials are specified and valid. |
109-
| 403 | The request is not authorized. Check the details error message. This often indicates that all free translations provided with a trial subscription have been used up. |
112+
| 401 | The request couldn't be authenticated. Check that credentials are specified and valid. |
113+
| 403 | The request isn't authorized. Check the details error message. This code often indicates that all free translations provided with a trial subscription have been used up. |
110114
| 429 | The server rejected the request because the client has exceeded request limits. |
111115
| 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`. |
112116
| 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`. |
113117

114-
If an error occurs, the request will also return 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](./v3-0-reference.md#errors).
118+
If an error occurs, the request 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](./v3-0-reference.md#errors).
115119

116120
## Examples
117121

0 commit comments

Comments
 (0)