Method: projects.locations.translateDocument

Translates documents in synchronous mode.

HTTP request

POST https://{TRANSLATION_GDC_ENDPOINT}/v3/{parent}:translateDocument

Path parameters

Parameters
parent

string

Required. Location to make a regional call.

Format: projects/{project-number-or-id}/locations/{location-id}.

For global calls, use projects/{project-number-or-id}/locations/global or projects/{project-number-or-id}.

Non-global location is required for requests using AutoML models or custom glossaries.

Models and glossaries must be within the same region (have the same location-id), otherwise an INVALID_ARGUMENT (400) error is returned.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "sourceLanguageCode": string,
  "targetLanguageCode": string,
  "documentInputConfig": {
    object (DocumentInputConfig)
  },
  "glossaryConfig": {
    object (TranslateTextGlossaryConfig)
  }
}
Fields
sourceLanguageCode

string

Optional. The ISO-639 language code of the input document if known, for example, "en-US" or "sr-Latn". Supported language codes are listed in Language Support. If the source language isn't specified, the API attempts to identify the source language automatically and returns the source language within the response. Source language must be specified if the request contains a glossary or a custom model.
targetLanguageCode

string

Required. The ISO-639 language code to use for translation of the input document, set to one of the language codes listed in Language Support.
documentInputConfig

object (DocumentInputConfig)

Required. Input configurations.
glossaryConfig

object (TranslateTextGlossaryConfig)

Optional. Glossary to be applied. The glossary must be within the same region (have the same location-id) as the model, otherwise an INVALID_ARGUMENT (400) error is returned.

Authorization requires the following IAM permission on the specified resource glossaryConfig:

  • cloudtranslate.glossaries.docPredict

Response body

A translated document response message.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "documentTranslation": {
    object (DocumentTranslation)
  },
  "glossaryDocumentTranslation": {
    object (DocumentTranslation)
  },
  "glossaryConfig": {
    object (TranslateTextGlossaryConfig)
  }
}
Fields
documentTranslation

object (DocumentTranslation)

Translated document.
glossaryDocumentTranslation

object (DocumentTranslation)

The document's translation output if a glossary is provided in the request. This can be the same as [TranslateDocumentResponse.document_translation] if no glossary terms apply.
glossaryConfig

object (TranslateTextGlossaryConfig)

The glossaryConfig used for this translation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-translation
  • https://www.googleapis.com/auth/cloud-platform

DocumentInputConfig

A document translation request input config.

JSON representation 
{
  "mimeType": string,
  "content": string,
  "S3Source": {
    object (S3Source)
  }
}
Fields
mimeType

string

Specifies the input document's mimeType.

If not specified it will be determined using the file extension for S3Source provided files. For a file provided through bytes content the mimeType must be provided.

Currently supported mime types are:

  • application/pdf
  • application/msword
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.ms-powerpoint
  • application/vnd.openxmlformats-officedocument.presentationml.presentation
  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Supported file formats are:

  • PDF
  • DOC
  • DOCX
  • PPT
  • PPTX
  • XLS
  • XLSX
content

string (bytes format)

Document's content represented as a stream of bytes.

A base64-encoded string.
S3Source

object (S3Source)

The storage location for the input content.

DocumentTranslation

A translated document message.

JSON representation 
{
  "byteStreamOutputs": [
    string
  ],
  "mimeType": string,
  "detectedLanguageCode": string
}
Fields
byteStreamOutputs[]

string (bytes format)

The array of translated documents. It is expected to be size 1 for now. We may produce multiple translated documents in the future for other type of file formats.

A base64-encoded string.
mimeType

string

The translated document's mime type.
detectedLanguageCode

string

The detected language for the input document. If the user did not provide the source language for the input document, this field will have the language code automatically detected. If the source language was passed, auto-detection of the language does not occur and this field is empty.