Microsoft Azure Translate API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Translate API
schemes:
- https
tags:
- name: Translate
paths:
  /translate:
    post:
      operationId: microsoftAzureTranslate
      summary: Microsoft Azure Translate Text
      description: Translate Text
      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/TranslateParameters.to'
      - $ref: '#/parameters/TranslateParameters.from'
      - $ref: '#/parameters/TranslateParameters.textType'
      - $ref: '#/parameters/TranslateParameters.category'
      - $ref: '#/parameters/TranslateParameters.profanityAction'
      - $ref: '#/parameters/TranslateParameters.profanityMarker'
      - $ref: '#/parameters/TranslateParameters.includeAlignment'
      - $ref: '#/parameters/TranslateParameters.includeSentenceLength'
      - $ref: '#/parameters/TranslateParameters.suggestedFrom'
      - $ref: '#/parameters/TranslateParameters.fromScript'
      - $ref: '#/parameters/TranslateParameters.toScript'
      - $ref: '#/parameters/TranslateParameters.allowFallback'
      - name: api-version
        in: query
        description: Mandatory API version parameter
        required: true
        type: string
        x-ms-client-name: apiVersion
      - name: requestBody
        in: body
        description: Defines the content of the request
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/InputTextItem'
          x-ms-identifiers: []
      responses:
        '200':
          description: Response for the translation API.
          schema:
            type: array
            items:
              $ref: '#/definitions/TranslatedTextItem'
            x-ms-identifiers: []
          headers:
            X-RequestId:
              type: string
              description: Value generated by the service to identify the request. It is used for troubleshooting purposes.
            x-metered-usage:
              type: integer
              format: int32
              description: "Specifies consumption (the number of characters for which the user will be charged) for the translation \njob request. For example, if the word \"Hello\" is translated from English (en) to French (fr), \nthis field will return the value '5'."
            x-mt-system:
              type: string
              description: "Specifies the system type that was used for translation for each 'to' language requested for translation. \nThe value is a comma-separated list of strings. Each string indicates a type:\n\n* Custom - Request includes a custom system and at least one custom system was used during translation.\n* Team - All other requests"
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/ErrorResponse'
          headers:
            X-RequestId:
              type: string
              description: Value generated by the service to identify the request. It is used for troubleshooting purposes.
      x-ms-examples:
        Translate Text:
          $ref: ./examples/Translate_MaximumSet_Gen.json
        Translate Text with minimum properties:
          $ref: ./examples/Translate_MinimumSet_Gen.json
      tags:
      - Translate
definitions:
  Translation:
    type: object
    description: Translation result
    properties:
      to:
        type: string
        description: A string representing the language code of the target language.
      text:
        type: string
        description: A string giving the translated text.
      transliteration:
        $ref: '#/definitions/TransliteratedText'
        description: An object giving the translated text in the script specified by the toScript parameter.
      alignment:
        $ref: '#/definitions/TranslatedTextAlignment'
        description: Alignment information.
      sentLen:
        $ref: '#/definitions/SentenceLength'
        description: Sentence boundaries in the input and output texts.
    required:
    - to
    - text
  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
  InputTextItem:
    type: object
    description: Element containing the text for translation.
    properties:
      text:
        type: string
        description: Text to translate.
    required:
    - text
  TranslatedTextItem:
    type: object
    description: Element containing the translated text
    properties:
      detectedLanguage:
        $ref: '#/definitions/DetectedLanguage'
        description: The detectedLanguage property is only present in the result object when language auto-detection is requested.
      translations:
        type: array
        description: "An array of translation results. The size of the array matches the number of target \nlanguages specified through the to query parameter."
        items:
          $ref: '#/definitions/Translation'
        x-ms-identifiers: []
      sourceText:
        $ref: '#/definitions/SourceText'
        description: "Input text in the default script of the source language. sourceText property is present only when \nthe input is expressed in a script that's not the usual script for the language. For example, \nif the input were Arabic written in Latin script, then sourceText.text would be the same Arabic text \nconverted into Arab script."
    required:
    - translations
  SentenceLength:
    type: object
    description: An object returning sentence boundaries in the input and output texts.
    properties:
      srcSentLen:
        type: array
        description: "An integer array representing the lengths of the sentences in the input text. \nThe length of the array is the number of sentences, and the values are the length of each sentence."
        items:
          type: integer
          format: int32
      transSentLen:
        type: array
        description: "An integer array representing the lengths of the sentences in the translated text. \nThe length of the array is the number of sentences, and the values are the length of each sentence."
        items:
          type: integer
          format: int32
    required:
    - srcSentLen
    - transSentLen
  SourceText:
    type: object
    description: 'Input text in the default script of the source language. '
    properties:
      text:
        type: string
        description: Input text in the default script of the source language.
    required:
    - text
  TransliteratedText:
    type: object
    description: Transliterated text element.
    properties:
      text:
        type: string
        description: A string which is the result of converting the input string to the output script.
      script:
        type: string
        description: A string specifying the script used in the output.
    required:
    - text
    - script
  DetectedLanguage:
    type: object
    description: An object describing the detected language.
    properties:
      language:
        type: string
        description: A string representing the code of the detected language.
      score:
        type: number
        format: float
        description: 'A float value indicating the confidence in the result.

          The score is between zero and one and a low score indicates a low confidence.'
    required:
    - language
    - score
  TranslatedTextAlignment:
    type: object
    description: Alignment information object.
    properties:
      proj:
        type: string
        description: "Maps input text to translated text. The alignment information is only provided when the request \nparameter includeAlignment is true. Alignment is returned as a string value of the following \nformat: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. \nThe colon separates start and end index, the dash separates the languages, and space separates the words. \nOne word may align with zero, one, or multiple words in the other language, and the aligned words may \nbe non-contiguous. When no alignment information is available, the alignment element will be empty."
    required:
    - proj
  ErrorResponse:
    type: object
    description: Representation of the Error Response from Translator Service.
    properties:
      error:
        $ref: '#/definitions/ErrorDetails'
        description: Error details.
    required:
    - error
parameters:
  TranslateParameters.category:
    name: category
    in: query
    description: "A string specifying the category (domain) of the translation. This parameter is used to get translations \nfrom a customized system built with Custom Translator. Add the Category ID from your Custom Translator \nproject details to this parameter to use your deployed customized system. Default value is: general."
    required: false
    type: string
    default: general
    x-ms-parameter-location: method
  TranslateParameters.includeAlignment:
    name: includeAlignment
    in: query
    description: 'Specifies whether to include alignment projection from source text to translated text.

      Possible values are: true or false (default).'
    required: false
    type: boolean
    default: false
    x-ms-parameter-location: method
  TranslateParameters.toScript:
    name: toScript
    in: query
    description: Specifies the script of the translated text.
    required: false
    type: string
    x-ms-parameter-location: method
  TranslateParameters.to:
    name: to
    in: query
    description: "Specifies the language of the output text. The target language must be one of the supported languages included \nin the translation scope. For example, use to=de to translate to German.\nIt's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. \nFor example, use to=de&to=it to translate to German and Italian."
    required: true
    type: array
    items:
      type: string
    collectionFormat: multi
    x-ms-parameter-location: method
  TranslateParameters.from:
    name: from
    in: query
    description: "Specifies the language of the input text. Find which languages are available to translate from by \nlooking up supported languages using the translation scope. If the from parameter isn't specified, \nautomatic language detection is applied to determine the source language.\n\nYou must use the from parameter rather than autodetection when using the dynamic dictionary feature. \nNote: the dynamic dictionary feature is case-sensitive."
    required: false
    type: string
    x-ms-parameter-location: method
  TranslateParameters.suggestedFrom:
    name: suggestedFrom
    in: query
    description: "Specifies a fallback language if the language of the input text can't be identified. \nLanguage autodetection is applied when the from parameter is omitted. If detection fails, \nthe suggestedFrom language will be assumed."
    required: false
    type: string
    x-ms-parameter-location: method
  TranslateParameters.includeSentenceLength:
    name: includeSentenceLength
    in: query
    description: 'Specifies whether to include sentence boundaries for the input text and the translated text.

      Possible values are: true or false (default).'
    required: false
    type: boolean
    default: false
    x-ms-parameter-location: method
  TranslateParameters.profanityMarker:
    name: profanityMarker
    in: query
    description: 'Specifies how profanities should be marked in translations.

      Possible values are: Asterisk (default) or Tag. '
    required: false
    type: string
    default: Asterisk
    enum:
    - Asterisk
    - Tag
    x-ms-enum:
      name: ProfanityMarker
      modelAsString: true
      values:
      - name: Asterisk
        value: Asterisk
      - name: Tag
        value: Tag
    x-ms-parameter-location: method
  TranslateParameters.allowFallback:
    name: allowFallback
    in: query
    description: "Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. \nPossible values are: true (default) or false.\n\nallowFallback=false specifies that the translation should only use systems trained for the category specified \nby the request. If a translation for language X to language Y requires chaining through a pivot language E, \nthen all the systems in the chain (X → E and E → Y) will need to be custom and have the same category. \nIf no system is found with the specific category, the request will return a 400 status code. allowFallback=true \nspecifies that the service is allowed to fall back to a general system when a custom system doesn't exist."
    required: false
    type: boolean
    default: true
    x-ms-parameter-location: method
  TranslateParameters.textType:
    name: textType
    in: query
    description: "Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, \ncomplete element. Possible values are: plain (default) or html."
    required: false
    type: string
    default: Plain
    enum:
    - Plain
    - Html
    x-ms-enum:
      name: TextType
      modelAsString: true
      values:
      - name: Plain
        value: Plain
      - name: Html
        value: Html
    x-ms-parameter-location: method
  TranslateParameters.profanityAction:
    name: profanityAction
    in: query
    description: 'Specifies how profanities should be treated in translations.

      Possible values are: NoAction (default), Marked or Deleted.'
    required: false
    type: string
    default: NoAction
    enum:
    - NoAction
    - Marked
    - Deleted
    x-ms-enum:
      name: ProfanityAction
      modelAsString: true
      values:
      - name: NoAction
        value: NoAction
      - name: Marked
        value: Marked
      - name: Deleted
        value: Deleted
    x-ms-parameter-location: method
  TranslateParameters.fromScript:
    name: fromScript
    in: query
    description: Specifies the script of the input text.
    required: false
    type: string
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'