swagger: '2.0' info: version: 2020-08-01-preview title: Microsoft Azure AccessControlClient AccessConnector Languages API schemes: - https tags: - name: Languages paths: /languages: post: summary: Microsoft Azure Detect Language description: The API returns the detected language and a numeric score between 0 and 1. Scores close to 1 indicate 100% certainty that the identified language is true. See the Supported languages in Text Analytics API for the list of enabled languages. operationId: microsoftAzureLanguages consumes: - application/json - text/json produces: - application/json - text/json parameters: - $ref: '#/parameters/ModelVersion' - $ref: '#/parameters/ShowStats' - $ref: '#/parameters/LanguageInput' responses: '200': description: A successful call results in the detected language with the highest probability for each valid document schema: $ref: '#/definitions/LanguageResult' '400': description: Bad Request. schema: $ref: '#/definitions/ErrorResponse' x-ms-error-response: true '500': description: Internal error response schema: $ref: '#/definitions/ErrorResponse' x-ms-error-response: true x-ms-examples: Successful Detect Language request: $ref: .//examples//SuccessfulLanguagesRequest.json deprecated: false tags: - Languages get: operationId: microsoftAzureGetlanguages summary: Microsoft Azure Gets The Set Of Languages Currently Supported By Other Operations Of The Translator description: Gets the set of languages currently supported by other operations of the Translator. parameters: - name: X-ClientTraceId in: header description: A client-generated GUID to uniquely identify the request. required: false type: string x-ms-client-name: clientTraceId - $ref: '#/parameters/GetLanguageParameters.scope' - $ref: '#/parameters/GetLanguageParameters.acceptLanguage' - $ref: '#/parameters/GetLanguageParameters.ifNoneMatch' - name: api-version in: query description: Mandatory API version parameter required: true type: string x-ms-client-name: apiVersion responses: '200': description: The request has succeeded. schema: $ref: '#/definitions/GetLanguagesResult' headers: ETag: type: string description: "Current value of the entity tag for the requested groups of supported languages. \nTo make subsequent requests more efficient, the client may send the `ETag` value in an \n`If-None-Match` header field." X-RequestId: type: string description: Value generated by the service to identify the request. It is used for troubleshooting purposes. default: description: An unexpected error response. schema: $ref: '#/definitions/ErrorResponse_2' headers: X-RequestId: type: string description: Value generated by the service to identify the request. It is used for troubleshooting purposes. x-ms-examples: Gets the set of languages currently supported by other operations of the Translator with minimum properties.: $ref: ./examples/GetLanguages_MinimumSet_Gen.json Gets the set of languages currently supported by other operations of the Translator.: $ref: ./examples/GetLanguages_MaximumSet_Gen.json tags: - Languages /Languages: get: description: 'Gets the set of languages currently supported by other operations of the Translator Text API.
**Authentication is not required to get language resources.**

# Response Body
A client uses the `scope` query parameter to define which groups of languages it is interested in.
* `scope=translation` provides languages supported to translate text from one language to another language.
* `scope=transliteration` provides capabilities for converting text in one language from one script to another script.
* `scope=dictionary` provides language pairs for which `Dictionary` operations return data.

A client may retrieve several groups simultaneously by specifying a comma-separated list of names. For example, `scope=translation,transliteration,dictionary` would return supported languages for all groups.

A successful response is a JSON object with one property for each requested group.
The value for each property is as follows.

* `translation` property
The value of the `translation` property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A key identifies a language for which text can be translated to or translated from. The value associated with the key is a JSON object with properties that describe the language
* `name-` Display name of the language in the locale requested via `Accept-Language` header.
* `nativeName-` Display name of the language in the locale native for this language.
* `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.
```json
{
"translation": {
...
"fr": {
"name": "French",
"nativeName": "Français",
"dir": "ltr"
},
...
}
}
```
* `transliteration` property
The value of the `transliteration` property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A key identifies a language for which text can be converted from one script to another script. The value associated with the key is a JSON object with properties that describe the language and its supported scripts
* `name-` Display name of the language in the locale requested via `Accept-Language` header.
* `nativeName-` Display name of the language in the locale native for this language.
* `scripts-` List of scripts to convert from. Each element of the `scripts` list has properties-
* `code-` Code identifying the script.
* `name-` Display name of the script in the locale requested via `Accept-Language` header.
* `nativeName-` Display name of the language in the locale native for the language.
* `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.
* `toScripts-` List of scripts available to convert text to. Each element of the `toScripts` list has properties `code`, `name`, `nativeName`, and `dir` as described earlier.

```json
{
"transliteration": {
...
"ja": {
"name": "Japanese",
"nativeName": "日本語",
"scripts": [
{
"code": "Jpan",
"name": "Japanese",
"nativeName": "日本語",
"dir": "ltr",
"toScripts": [
{
"code": "Latn",
"name": "Latin",
"nativeName": "ラテン語",
"dir": "ltr"
}
]
},
{
"code": "Latn",
"name": "Latin",
"nativeName": "ラテン語",
"dir": "ltr",
"toScripts": [
{
"code": "Jpan",
"name": "Japanese",
"nativeName": "日本語",
"dir": "ltr"
}
]
}
]
},
...
}
}

```
* `dictionary` property
The value of the `dictionary` property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. The key identifies a language for which alternative translations and back-translations are available. The value is a JSON object that describes the source language and the target languages with available translations.
* `name-` Display name of the source language in the locale requested via `Accept-Language` header.
* `nativeName-` Display name of the language in the locale native for this language.
* `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.
* `translations-` List of languages with alterative translations and examples for the query expressed in the source language. Each element of the `translations` list has properties
* `name-` Display name of the target language in the locale requested via `Accept-Language` header.
* `nativeName-` Display name of the target language in the locale native for the target language.
* `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.
* `code-` Language code identifying the target language.

```json

"es": {
"name": "Spanish",
"nativeName": "Español",
"dir": "ltr",
"translations": [
{
"name": "English",
"nativeName": "English",
"dir": "ltr",
"code": "en"
}
]
},

```

The structure of the response object will not change without a change in the version of the API. For the same version of the API, the list of available languages may change over time because Microsoft Translator continually extends the list of languages supported by its services.

The list of supported languages will not change frequently. To save network bandwidth and improve responsiveness, a client application should consider caching language resources and the corresponding entity tag (`ETag`). Then, the client application can periodically (for example, once every 24 hours) query the service to fetch the latest set of supported languages. Passing the current `ETag` value in an `If-None-Match` header field will allow the service to optimize the response. If the resource has not been modified, the service will return status code 304 and an empty response body.

# Response Header
ETag - Current value of the entity tag for the requested groups of supported languages. To make subsequent requests more efficient, the client may send the `ETag` value in an `If-None-Match` header field.

X-RequestId - Value generated by the service to identify the request. It is used for troubleshooting purposes.


' tags: - Languages operationId: microsoftAzureTranslatorLanguages consumes: [] produces: - application/json parameters: - $ref: '#/parameters/ApiVersion' - name: scope description: A comma-separated list of names defining the group of languages to return. Allowed group names are- `translation`, `transliteration` and `dictionary`. If no scope is given, then all groups are returned, which is equivalent to passing `scope=translation,transliteration,dictionary`. To decide which set of supported languages is appropriate for your scenario, see the description of the response object. in: query required: false type: array minItems: 0 maxItems: 3 items: type: string enum: - translation - transliteration - dictionary - name: Accept-Language description: The language to use for user interface strings. Some of the fields in the response are names of languages or names of regions. Use this parameter to define the language in which these names are returned. The language is specified by providing a well-formed BCP 47 language tag. For instance, use the value `fr` to request names in French or use the value `zh-Hant` to request names in Chinese Traditional. Names are provided in the English language when a target language is not specified or when localization is not available. in: header type: string required: false - name: X-ClientTraceId description: 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. in: header required: false type: string responses: '200': description: Success schema: $ref: '#/definitions/LanguagesResult' default: description: Error response. schema: $ref: '#/definitions/ErrorMessage' x-ms-examples: Languages success example: $ref: ./examples/languagesSuccess.json deprecated: false summary: Microsoft Azure Get Languages definitions: ErrorMessage: type: object properties: error: type: object properties: code: type: string message: type: string ErrorDetails: type: object description: Error details as returned by Translator Service. properties: code: type: integer format: int32 description: Number identifier of the error. message: type: string description: Human readable error description. required: - code - message RequestStatistics: type: object required: - documentsCount - validDocumentsCount - erroneousDocumentsCount - transactionsCount properties: documentsCount: type: integer format: int32 description: Number of documents submitted in the request. validDocumentsCount: type: integer format: int32 description: Number of valid documents. This excludes empty, over-size limit or non-supported languages documents. erroneousDocumentsCount: type: integer format: int32 description: Number of invalid documents. This includes empty, over-size limit or non-supported languages documents. transactionsCount: type: integer format: int64 description: Number of transactions for the request. description: if showStats=true was specified in the request this field will contain information about the request payload. DocumentLanguage: type: object required: - id - detectedLanguage - warnings properties: id: type: string description: Unique, non-empty document identifier. detectedLanguage: description: Detected Language. $ref: '#/definitions/DetectedLanguage' warnings: type: array description: Warnings encountered while processing document. items: $ref: '#/definitions/TextAnalyticsWarning' statistics: description: if showStats=true was specified in the request this field will contain information about the document payload. $ref: '#/definitions/DocumentStatistics' TargetDictionaryLanguage: type: object description: Properties of the target dictionary language properties: name: type: string description: Display name of the language in the locale requested via Accept-Language header. nativeName: type: string description: Display name of the language in the locale native for this language. dir: type: string description: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages. code: type: string description: Language code identifying the target language. required: - name - nativeName - dir - code DocumentError: type: object required: - id - error properties: id: type: string description: Document Id. error: type: object description: Document Error. $ref: '#/definitions/TextAnalyticsError' DocumentStatistics: type: object required: - charactersCount - transactionsCount properties: charactersCount: type: integer format: int32 description: Number of text elements recognized in the document. transactionsCount: type: integer format: int32 description: Number of transactions for the document. description: if showStats=true was specified in the request this field will contain information about the document payload. CommonScriptModel: type: object description: Common properties of language script properties: code: type: string description: Code identifying the script. name: type: string description: Display name of the script in the locale requested via Accept-Language header. nativeName: type: string description: Display name of the language in the locale native for the language. dir: type: string description: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages. required: - code - name - nativeName - dir ErrorResponse_2: type: object description: Representation of the Error Response from Translator Service. properties: error: $ref: '#/definitions/ErrorDetails' description: Error details. required: - error TextAnalyticsWarning: type: object required: - code - message properties: code: type: string enum: - LongWordsInDocument - DocumentTruncated x-ms-enum: name: WarningCodeValue modelAsString: true description: Error code. message: type: string description: Warning message. targetRef: type: string description: A JSON pointer reference indicating the target object. InnerError: type: object required: - code - message properties: code: type: string enum: - InvalidParameterValue - InvalidRequestBodyFormat - EmptyRequest - MissingInputRecords - InvalidDocument - ModelVersionIncorrect - InvalidDocumentBatch - UnsupportedLanguageCode - InvalidCountryHint x-ms-enum: name: InnerErrorCodeValue modelAsString: true description: Error code. message: type: string description: Error message. details: type: object additionalProperties: type: string description: Error details. target: type: string description: Error target. innererror: $ref: '#/definitions/InnerError' description: Inner error contains more specific information. LanguageBatchInput: type: object required: - documents properties: documents: type: array items: $ref: '#/definitions/LanguageInput' GetLanguagesResult: type: object description: Response for the languages API. properties: translation: type: object description: Languages that support translate API. additionalProperties: $ref: '#/definitions/TranslationLanguage' transliteration: type: object description: Languages that support transliteration API. additionalProperties: $ref: '#/definitions/TransliterationLanguage' dictionary: type: object description: Languages that support dictionary API. additionalProperties: $ref: '#/definitions/SourceDictionaryLanguage' LanguageResult: type: object required: - documents - errors - modelVersion properties: documents: type: array description: Response by document items: $ref: '#/definitions/DocumentLanguage' errors: type: array description: Errors by document id. items: $ref: '#/definitions/DocumentError' statistics: $ref: '#/definitions/RequestStatistics' modelVersion: type: string description: This field indicates which model is used for scoring. DetectedLanguage: type: object required: - name - iso6391Name - confidenceScore properties: name: type: string description: Long name of a detected language (e.g. English, French). iso6391Name: type: string description: A two letter representation of the detected language according to the ISO 639-1 standard (e.g. en, fr). confidenceScore: type: number format: double description: A confidence score between 0 and 1. Scores close to 1 indicate 100% certainty that the identified language is true. LanguageInput: type: object required: - id - text properties: id: type: string description: Unique, non-empty document identifier. text: type: string countryHint: type: string LanguagesResult: type: object description: Example of a successful languages request properties: translation: type: object properties: languageCode: type: object properties: name: type: string nativeName: type: string dir: type: string transliteration: type: object properties: languageCode: type: object properties: name: type: string nativeName: type: string scripts: type: array items: type: object properties: code: type: string name: type: string nativeName: type: string dir: type: string toScripts: type: array items: type: object properties: code: type: string name: type: string nativeName: type: string dir: type: string dictionary: type: object properties: languageCode: type: object properties: name: type: string nativeName: type: string dir: type: string translations: type: array items: type: object properties: name: type: string nativeName: type: string dir: type: string code: type: string TransliterableScript: type: object description: Script definition with list of script into which given script can be translitered. properties: toScripts: type: array description: List of scripts available to convert text to. items: $ref: '#/definitions/CommonScriptModel' x-ms-identifiers: [] required: - toScripts allOf: - $ref: '#/definitions/CommonScriptModel' ErrorResponse: type: object required: - error properties: error: type: object description: Document Error. $ref: '#/definitions/TextAnalyticsError' SourceDictionaryLanguage: type: object description: Properties ot the source dictionary language properties: name: type: string description: Display name of the language in the locale requested via Accept-Language header. nativeName: type: string description: Display name of the language in the locale native for this language. dir: type: string description: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages. translations: type: array description: List of languages with alterative translations and examples for the query expressed in the source language. items: $ref: '#/definitions/TargetDictionaryLanguage' x-ms-identifiers: [] required: - name - nativeName - dir - translations TranslationLanguage: type: object description: 'The value of the translation property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag. A key identifies a language for which text can be translated to or translated from.' properties: name: type: string description: Display name of the language in the locale requested via Accept-Language header. nativeName: type: string description: Display name of the language in the locale native for this language. dir: type: string description: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages. required: - name - nativeName - dir TransliterationLanguage: type: object description: "The value of the transliteration property is a dictionary of (key, value) pairs. \nEach key is a BCP 47 language tag. A key identifies a language for which text can be converted from one script \nto another script." properties: name: type: string description: Display name of the language in the locale requested via Accept-Language header. nativeName: type: string description: Display name of the language in the locale native for this language. scripts: type: array description: List of scripts to convert from. items: $ref: '#/definitions/TransliterableScript' x-ms-identifiers: [] required: - name - nativeName - scripts TextAnalyticsError: type: object required: - code - message properties: code: type: string enum: - InvalidRequest - InvalidArgument - InternalServerError - ServiceUnavailable - NotFound x-ms-enum: name: ErrorCodeValue modelAsString: false description: Error code. message: type: string description: Error message. target: type: string description: Error target. innererror: $ref: '#/definitions/InnerError' description: Inner error contains more specific information. details: type: array description: Details about specific errors that led to this reported error. items: $ref: '#/definitions/TextAnalyticsError' parameters: GetLanguageParameters.scope: name: scope in: query description: "A comma-separated list of names defining the group of languages to return.\nAllowed group names are: `translation`, `transliteration` and `dictionary`.\nIf no scope is given, then all groups are returned, which is equivalent to passing \n`scope=translation,transliteration,dictionary`. To decide which set of supported languages \nis appropriate for your scenario, see the description of the [response object](#response-body)." required: false type: string x-ms-parameter-location: method GetLanguageParameters.acceptLanguage: name: Accept-Language in: header description: "The language to use for user interface strings. Some of the fields in the response are names of languages or \nnames of regions. Use this parameter to define the language in which these names are returned. \nThe language is specified by providing a well-formed BCP 47 language tag. For instance, use the value `fr` \nto request names in French or use the value `zh-Hant` to request names in Chinese Traditional.\nNames are provided in the English language when a target language is not specified or when localization \nis not available." required: false type: string default: en x-ms-parameter-location: method x-ms-client-name: acceptLanguage LanguageInput: in: body name: input description: Collection of documents to analyze for language endpoint. required: true schema: $ref: '#/definitions/LanguageBatchInput' x-ms-parameter-location: method ModelVersion: name: model-version in: query description: '(Optional) This value indicates which model will be used for scoring. If a model-version is not specified, the API should default to the latest, non-preview version. ' type: string required: false x-ms-parameter-location: method ApiVersion: name: api-version description: Version of the API requested by the client. Value must be **3.0**. in: query required: true type: string default: '3.0' GetLanguageParameters.ifNoneMatch: name: If-None-Match in: header description: "Passing the value of the ETag response header in an If-None-Match field will allow the service to optimize the response. \nIf the resource has not been modified, the service will return status code 304 and an empty response body." required: false type: string x-ms-parameter-location: method x-ms-client-name: ifNoneMatch ShowStats: name: showStats in: query description: (Optional) if set to true, response will contain request and document level statistics. type: boolean required: false x-ms-parameter-location: method x-ms-parameterized-host: hostTemplate: '{endpoint}' useSchemePrefix: false parameters: - $ref: '#/parameters/Endpoint'