Microsoft Azure Languages API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Languages API
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
      parameters:
      - $ref: '#/components/parameters/ModelVersion'
      - $ref: '#/components/parameters/ShowStats'
      - $ref: '#/components/parameters/LanguageInput'
      responses:
        '200':
          description: A successful call results in the detected language with the highest probability for each valid document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageResult'
            text/json:
              schema:
                $ref: '#/components/schemas/LanguageResult'
        '400':
          description: Bad Request.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error response
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      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
        x-ms-client-name: clientTraceId
        schema:
          type: string
      - $ref: '#/components/parameters/GetLanguageParameters.scope'
      - $ref: '#/components/parameters/GetLanguageParameters.acceptLanguage'
      - $ref: '#/components/parameters/GetLanguageParameters.ifNoneMatch'
      - name: api-version
        in: query
        description: Mandatory API version parameter
        required: true
        x-ms-client-name: apiVersion
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          headers:
            ETag:
              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."
              schema:
                type: string
            X-RequestId:
              description: Value generated by the service to identify the request. It is used for troubleshooting purposes.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLanguagesResult'
        default:
          description: An unexpected error response.
          headers:
            X-RequestId:
              description: Value generated by the service to identify the request. It is used for troubleshooting purposes.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse_2'
      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
      parameters:
      - $ref: '#/components/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
        schema:
          type: array
          items:
            type: string
            enum:
            - translation
            - transliteration
            - dictionary
          maxItems: 3
          minItems: 0
      - 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
        required: false
        schema:
          type: string
      - 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
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguagesResult'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      x-ms-examples:
        Languages success example:
          $ref: ./examples/languagesSuccess.json
      deprecated: false
      summary: Microsoft Azure Get Languages
components:
  schemas:
    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: '#/components/schemas/CommonScriptModel'
          x-ms-identifiers: []
      required:
      - toScripts
      allOf:
      - $ref: '#/components/schemas/CommonScriptModel'
    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: '#/components/schemas/InnerError'
          description: Inner error contains more specific information.
        details:
          type: array
          description: Details about specific errors that led to this reported error.
          items:
            $ref: '#/components/schemas/TextAnalyticsError'
    ErrorMessage:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    LanguageBatchInput:
      type: object
      required:
      - documents
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/LanguageInput'
    GetLanguagesResult:
      type: object
      description: Response for the languages API.
      properties:
        translation:
          type: object
          description: Languages that support translate API.
          additionalProperties:
            $ref: '#/components/schemas/TranslationLanguage'
        transliteration:
          type: object
          description: Languages that support transliteration API.
          additionalProperties:
            $ref: '#/components/schemas/TransliterationLanguage'
        dictionary:
          type: object
          description: Languages that support dictionary API.
          additionalProperties:
            $ref: '#/components/schemas/SourceDictionaryLanguage'
    ErrorResponse_2:
      type: object
      description: Representation of the Error Response from Translator Service.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
          description: Error details.
      required:
      - error
    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
    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: '#/components/schemas/TransliterableScript'
          x-ms-identifiers: []
      required:
      - name
      - nativeName
      - scripts
    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
    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: '#/components/schemas/InnerError'
          description: Inner error contains more specific information.
    DocumentError:
      type: object
      required:
      - id
      - error
      properties:
        id:
          type: string
          description: Document Id.
        error:
          type: object
          description: Document Error.
          $ref: '#/components/schemas/TextAnalyticsError'
    DocumentLanguage:
      type: object
      required:
      - id
      - detectedLanguage
      - warnings
      properties:
        id:
          type: string
          description: Unique, non-empty document identifier.
        detectedLanguage:
          description: Detected Language.
          $ref: '#/components/schemas/DetectedLanguage'
        warnings:
          type: array
          description: Warnings encountered while processing document.
          items:
            $ref: '#/components/schemas/TextAnalyticsWarning'
        statistics:
          description: if showStats=true was specified in the request this field will contain information about the document payload.
          $ref: '#/components/schemas/DocumentStatistics'
    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
    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.
    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
    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: '#/components/schemas/TargetDictionaryLanguage'
          x-ms-identifiers: []
      required:
      - name
      - nativeName
      - dir
      - translations
    LanguageResult:
      type: object
      required:
      - documents
      - errors
      - modelVersion
      properties:
        documents:
          type: array
          description: Response by document
          items:
            $ref: '#/components/schemas/DocumentLanguage'
        errors:
          type: array
          description: Errors by document id.
          items:
            $ref: '#/components/schemas/DocumentError'
        statistics:
          $ref: '#/components/schemas/RequestStatistics'
        modelVersion:
          type: string
          description: This field indicates which model is used for scoring.
    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.
    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.
    LanguageInput:
      type: object
      required:
      - id
      - text
      properties:
        id:
          type: string
          description: Unique, non-empty document identifier.
        text:
          type: string
        countryHint:
          type: string
    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:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Document Error.
          $ref: '#/components/schemas/TextAnalyticsError'
    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.
  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
      x-ms-parameter-location: method
      schema:
        type: string
    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
      x-ms-parameter-location: method
      x-ms-client-name: acceptLanguage
      schema:
        type: string
        default: en
    LanguageInput:
      in: body
      name: input
      description: Collection of documents to analyze for language endpoint.
      required: true
      schema:
        $ref: '#/components/schemas/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. '
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    ShowStats:
      name: showStats
      in: query
      description: (Optional) if set to true, response will contain request and document level statistics.
      required: false
      x-ms-parameter-location: method
      schema:
        type: boolean
    ApiVersion:
      name: api-version
      description: Version of the API requested by the client. Value must be **3.0**.
      in: query
      required: true
      schema:
        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
      x-ms-parameter-location: method
      x-ms-client-name: ifNoneMatch
      schema:
        type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'