info:
  version: '1.0.0'
  title: Global Transform API
  description: Global Transform API
  termsofservice: https://github.com/wikimedia/restbase
  license:
    name: Apache licence, v2
    url: https://www.apache.org/licenses/LICENSE-2.0
paths:
  /html/from/{from_lang}/to/{to_lang}{/provider}:
    post:
      tags: ['Transform']
      summary: Machine-translate content
      description: |
        Fetches the machine translation for the posted content from the source
        to the destination language.

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - name: from_lang
          in: path
          description: The source language code
          type: string
          required: true
        - name: to_lang
          in: path
          description: The target language code
          type: string
          required: true
        - name: provider
          in: path
          description: The machine translation provider id
          type: string
          required: false
          enum:
           - Apertium
           - Yandex
           - Youdao
        - name: html
          in: formData
          description: The HTML content to translate
          type: string
          required: true
          x-textarea: true
      responses:
        '200':
          description: The translated content
          schema:
            $ref: '#/definitions/cx_mt'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: false
      x-request-handler:
        - get_from_cx:
            request:
              method: post
              uri: '{{options.cx_host}}/v1/mt/{from_lang}/{to_lang}/{provider}'
              body:
                html: '{{html}}'
  /word/from/{from_lang}/to/{to_lang}/{word}{/provider}:
    get:
      tags: ['Transform']
      summary: Fetch the dictionary meaning of a word
      description: |
        Fetches the dictionary meaning of a word from a language and displays
        it in the target language.

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - application/json
      parameters:
        - name: from_lang
          in: path
          description: The source language code
          type: string
          required: true
        - name: to_lang
          in: path
          description: The target language code
          type: string
          required: true
        - name: word
          in: path
          description: The word to lookup
          type: string
          required: true
        - name: provider
          in: path
          description: The dictionary provider id
          type: string
          required: false
          enum:
           - JsonDict
           - Dictd
      responses:
        '200':
          description: the dictionary translation for the given word
          schema:
            $ref: '#/definitions/cx_dict'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: false
      x-request-handler:
        - get_from_cx:
            request:
              uri: '{{options.cx_host}}/v1/dictionary/{word}/{from_lang}/{to_lang}/{provider}'
  /list/pair/{from}/{to}/:
    get:
      tags: ['Transform']
      summary: Lists the tools available for a language pair
      description: |
        Fetches the list of tools that are available for the given pair of languages.

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - application/json
      parameters:
        - name: from
          in: path
          description: The source language code
          type: string
          required: true
        - name: to
          in: path
          description: The target language code
          type: string
          required: true
      responses:
        '200':
          description: the list of tools available for the language pair
          schema:
            $ref: '#/definitions/cx_list_tools'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: false
      x-request-handler:
        - get_from_cx:
            request:
              uri: '{{options.cx_host}}/v1/list/pair/{from}/{to}'
  /list/tool/{tool}/:
    get:
      tags: ['Transform']
      summary: Lists the tools and language pairs available for the given tool category
      description: |
        Fetches the list of tools and all of the language pairs it can translate

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - application/json
      parameters:
        - name: tool
          in: path
          description: The tool category to list tools and language pairs for
          type: string
          required: true
          enum:
            - mt
            - dictionary
      responses:
        '200':
          description: the list of language pairs available for a given translation tool
          schema:
            $ref: '#/definitions/cx_list_pairs_for_tool'
        default:
          description: Error
          schema:
            $ref: '#/definitions/problem'
      x-monitor: false
      x-request-handler:
        - get_from_cx:
            request:
              uri: '{{options.cx_host}}/v1/list/tool/{tool}'
  /list/languagepairs/:
    get:
      tags: ['Transform']
      summary: Lists the language pairs supported by the back-end
      description: |
        Fetches the list of language pairs the back-end service can translate

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - application/json
      responses:
        '200':
          description: the list of source and target languages supported by the API
          schema:
            $ref: '#/definitions/cx_languagepairs'
      x-monitor: false
      x-request-handler:
        - get_from_cx:
            request:
              uri: '{{options.cx_host}}/v1/list/languagepairs'

definitions:
  cx_list_tools:
    type: object
    properties:
      tools:
        type: array
        description: the list of tools available for the given language pair
        items:
          type: string
          description: the tool available
  cx_list_pairs_for_tool:
    type: object
  cx_languagepairs:
    type: object
    properties:
      source:
        type: array
        description: the list of available source languages
        items:
          type: string
          description: one source language
      target:
        type: array
        description: the list of available destination languages
        items:
          type: string
          description: one destination language