openapi: 3.1.0
info:
  title: Google Cloud Translation API
  description: >-
    The Google Cloud Translation API provides programmatic access to Google's
    neural machine translation technology. It enables developers to dynamically
    translate text between thousands of language pairs, detect the language of
    source text, and retrieve a list of supported languages. The API supports
    both basic (v2) and advanced (v3) translation capabilities including batch
    translation, custom models, and glossaries.
  version: 3.0.0
  contact:
    name: Google Cloud
    url: https://cloud.google.com/translate
  license:
    name: Google APIs Terms of Service
    url: https://developers.google.com/terms
externalDocs:
  description: Google Cloud Translation API Documentation
  url: https://cloud.google.com/translate/docs
servers:
  - url: https://translation.googleapis.com
    description: Google Cloud Translation API v2 Server
  - url: https://translate.googleapis.com
    description: Google Cloud Translation API v3 Server
tags:
  - name: Detections
    description: Detect language of text
  - name: Languages
    description: List supported languages
  - name: Translations
    description: Translate text between languages
paths:
  /language/translate/v2:
    post:
      operationId: translateText
      summary: Google Cloud Translation API Translate Text
      description: Translates input text from one language to another.
      tags:
        - Translations
      parameters:
        - name: key
          in: query
          description: API key for authentication
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateTextRequest'
      responses:
        '200':
          description: Successful translation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateTextResponse'
  /language/translate/v2/detect:
    post:
      operationId: detectLanguage
      summary: Google Cloud Translation API Detect Language
      description: Detects the language of the provided text.
      tags:
        - Detections
      parameters:
        - name: key
          in: query
          description: API key for authentication
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetectLanguageRequest'
      responses:
        '200':
          description: Successful detection response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectLanguageResponse'
  /language/translate/v2/languages:
    get:
      operationId: listLanguages
      summary: Google Cloud Translation API List Supported Languages
      description: Returns a list of supported languages for translation.
      tags:
        - Languages
      parameters:
        - name: key
          in: query
          description: API key for authentication
          required: true
          schema:
            type: string
        - name: target
          in: query
          description: >-
            The language to use to return localized, human readable names of
            supported languages.
          schema:
            type: string
        - name: model
          in: query
          description: >-
            The translation model. Can be either base for the Phrase-Based
            Machine Translation model, or nmt for the Neural Machine Translation
            model.
          schema:
            type: string
            enum:
              - base
              - nmt
      responses:
        '200':
          description: Successful response with list of languages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLanguagesResponse'
components:
  schemas:
    TranslateTextRequest:
      type: object
      required:
        - q
        - target
      properties:
        q:
          type: array
          items:
            type: string
          description: The text to translate.
        target:
          type: string
          description: The target language code (ISO 639-1).
        source:
          type: string
          description: The source language code (ISO 639-1). If not specified, the API will attempt to detect the source language.
        format:
          type: string
          enum:
            - text
            - html
          description: The format of the source text.
        model:
          type: string
          description: The translation model (base or nmt).
    TranslateTextResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            translations:
              type: array
              items:
                $ref: '#/components/schemas/Translation'
    Translation:
      type: object
      properties:
        translatedText:
          type: string
          description: The translated text.
        detectedSourceLanguage:
          type: string
          description: The detected source language code.
        model:
          type: string
          description: The translation model used.
    DetectLanguageRequest:
      type: object
      required:
        - q
      properties:
        q:
          type: array
          items:
            type: string
          description: The text to detect the language of.
    DetectLanguageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            detections:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Detection'
    Detection:
      type: object
      properties:
        language:
          type: string
          description: The detected language code.
        confidence:
          type: number
          description: The confidence of the detection.
        isReliable:
          type: boolean
          description: Whether the detection is reliable.
    ListLanguagesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            languages:
              type: array
              items:
                $ref: '#/components/schemas/Language'
    Language:
      type: object
      properties:
        language:
          type: string
          description: The language code (ISO 639-1).
        name:
          type: string
          description: The human-readable name of the language.