Microsoft Azure Languages API

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.<br>**Authentication is not required to get language resources.**<br><br># Response Body<br>A client uses the `scope` query parameter to define which groups of languages it is interested in.<br>* `scope=translation` provides languages supported to translate text from one language to another language.<br>* `scope=transliteration` provides capabilities for converting text in one language from one script to another script.<br>* `scope=dictionary` provides language pairs for which `Dictionary` operations return data.<br><br>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.<br><br>A successful response is a JSON object with one property for each requested group.<br>The value for each property is as follows.<br><br>* `translation` property<br>  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<br>  * `name-` Display name of the language in the locale requested via `Accept-Language` header.<br>  * `nativeName-` Display name of the language in the locale native for this language.<br>  * `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.<br>```json<br>{<br>  "translation": {<br>  ...<br>  "fr": {<br>  "name": "French",<br>  "nativeName": "Français",<br>  "dir": "ltr"<br>  },<br>...<br> }<br>}<br>```<br>* `transliteration` property<br>  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<br>  * `name-` Display name of the language in the locale requested via `Accept-Language` header.<br>  * `nativeName-` Display name of the language in the locale native for this language.<br>  * `scripts-` List of scripts to convert from. Each element of the `scripts` list has properties-<br>    * `code-` Code identifying the script.<br>    * `name-` Display name of the script in the locale requested via `Accept-Language` header.<br>    * `nativeName-` Display name of the language in the locale native for the language.<br>    * `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.<br>    * `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.<br><br>```json<br>{<br>  "transliteration": {<br>    ...<br>    "ja": {<br>      "name": "Japanese",<br>      "nativeName": "日本語",<br>      "scripts": [<br>        {<br>          "code": "Jpan",<br>          "name": "Japanese",<br>          "nativeName": "日本語",<br>          "dir": "ltr",<br>          "toScripts": [<br>            {<br>              "code": "Latn",<br>              "name": "Latin",<br>              "nativeName": "ラテン語",<br>              "dir": "ltr"<br>            }<br>          ]<br>        },<br>        {<br>          "code": "Latn",<br>          "name": "Latin",<br>          "nativeName": "ラテン語",<br>          "dir": "ltr",<br>          "toScripts": [<br>          {<br>            "code": "Jpan",<br>            "name": "Japanese",<br>            "nativeName": "日本語",<br>            "dir": "ltr"<br>          }<br>          ]<br>        }<br>      ]<br>    },<br>  ...<br>  }<br>}<br><br>```<br>* `dictionary` property<br>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.<br>  * `name-` Display name of the source language in the locale requested via `Accept-Language` header.<br>  * `nativeName-` Display name of the language in the locale native for this language.<br>  * `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.<br>  * `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<br>    * `name-` Display name of the target language in the locale requested via `Accept-Language` header.<br>    * `nativeName-` Display name of the target language in the locale native for the target language.<br>    * `dir-` Directionality, which is `rtl` for right-to-left languages or `ltr` for left-to-right languages.<br>    * `code-` Language code identifying the target language.<br><br>```json<br><br>"es": {<br>  "name": "Spanish",<br>  "nativeName": "Español",<br>  "dir": "ltr",<br>  "translations": [<br>    {<br>      "name": "English",<br>      "nativeName": "English",<br>      "dir": "ltr",<br>      "code": "en"<br>    }<br>  ]<br>},<br><br>```<br><br>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.<br><br>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.<br> <br># Response Header<br>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.<br><br>X-RequestId - Value generated by the service to identify the request. It is used for troubleshooting purposes. <br>  <br>  <br>'
      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'