Translate documents

Cloud Translation - Advanced provides a Document Translation API for directly translating formatted documents such as PDF and DOCX. Compared to plain text translations, Document Translation preserves the original formatting and layout in your translated documents, helping you retain much of the original context like paragraph breaks.

The following sections describe how to translate documents and use Document Translation with other Cloud Translation - Advanced features like glossaries and AutoML Translation models. Document Translation supports both online and batch translation requests.

For plain text and HTML translations, see Translating text.

Supported file formats

Document Translation support the following input file types and their associated output file types.

^*Content inside text boxes aren't translated and remain in the source language.

^†Document Translation supports both native and scanned PDF documents with some differences. For optimal format handling, use native PDF files when possible. Translating scanned PDF files results in some formatting loss. Complex PDF layouts can also result in some formatting loss, which can include data tables, multi-column layouts, and graphs with labels or legends.

If you have PDF content in the DOCX or PPTX format, we recommend that you translate content by using those formats before converting them to PDFs. In general, Document Translation preserves a document's layout and style of DOCX and PPTX files better than PDF files. After a document translation, you can then convert the results to PDF files.

Native and scanned PDF document translations

Document Translation supports both native and scanned PDF files, including translations to or from right-to-left languages. Support for PDF to DOCX conversions is available for batch document translations on native PDF files only. Also, Document Translation preserves hyperlinks, font size, and font color for native PDF files only (for both synchronous and batch translations).

If you translate a PDF file with a mix of scanned and native PDF content, the scanned content isn't translated.

Before you begin

Before you can start using the Cloud Translation API, you should complete the Cloud Translation setup page, which includes creating a project, enabling the Cloud Translation API, and setting up authentication. The setup page also provides instructions for installing client libraries for common programming languages, which is optional.

Required permissions

For requests that require Cloud Storage access, such as batch Document Translation, you might require Cloud Storage permissions to read input files or send output files to a bucket. For example, to read input files from a bucket, you must have at least read object permissions (provided by the role roles/storage.objectViewer) on the bucket. For more information about Cloud Storage roles, see the Cloud Storage documentation.

Translate documents (online)

Online translation provides real-time processing (synchronous processing) of a single file.

For PDFs, the file size can be up to 20 MB and up to 300 pages for native PDFs (requires the isTranslateNativePdfOnly field to be true). If you enable the enableShadowRemovalNativePdf field, the limit is 20 pages. For scanned PDFs, the limit is 20 pages.

For other document types, the file sizes can be up to 20 MB with no page limits.

Translate a document from Cloud Storage

The following example translates a file from a Cloud Storage bucket and outputs the result to a Cloud Storage bucket. The response also returns a byte stream. You can specify the MIME type; if you don't, Document Translation determines it by using the input file's extension.

If you don't specify a source language code, Document Translation detects the language for you. The detected language is included in the output in the detectedLanguageCode field.

POST https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID/locations/LOCATION:translateDocument

{
  "source_language_code": "SOURCE_LANGUAGE",
  "target_language_code": "TARGET_LANGUAGE",
  "document_input_config": {
    "gcsSource": {
      "inputUri": "gs://INPUT_FILE_PATH"
    }
  },
  "document_output_config": {
    "gcsDestination": {
      "outputUriPrefix": "gs://OUTPUT_FILE_PREFIX"
    }
  },
  "isTranslateNativePdfOnly": IS_NATIVE
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_NUMBER_OR_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID/locations/LOCATION:translateDocument"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER_OR_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/v3/projects/PROJECT_NUMBER_OR_ID/locations/LOCATION:translateDocument" | Select-Object -Expand Content

{
  "documentTranslation": {
    "byteStreamOutputs": ["BYTE_STREAM"],
    "mimeType": "MIME_TYPE"
  },
  "model": "projects/PROJECT_NUMBER/locations/LOCATION/models/general/nmt"
}

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const location = 'global';
// const inputUri = 'path_to_your_file';

// Imports the Google Cloud Translation library
const {TranslationServiceClient} = require('@google-cloud/translate').v3beta1;

// Instantiates a client
const translationClient = new TranslationServiceClient();

const documentInputConfig = {
  gcsSource: {
    inputUri: inputUri,
  },
};

async function translateDocument() {
  // Construct request
  const request = {
    parent: translationClient