Translate documents  |  Cloud Translation  |  Google Cloud (2024)

Cloud Translation - Advanced provides a Document Translation API fordirectly translating formatted documents such as PDF and DOCX. Compared toplain text translations, Document Translation preserves the originalformatting and layout in your translated documents, helping you retain much ofthe original context like paragraph breaks.

The following sections describe how to translate documents and useDocument Translation with other Cloud Translation - Advanced features likeglossaries and AutoML Translation models. Document Translationsupports both online and batch translation requests.

For plain text and HTML translations, see Translatingtext.

Supported file formats

Document Translation support the following input file types and theirassociated output file types.

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

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

If you have PDF content in the DOCX or PPTX format, we recommend that youtranslate content by using those formats before converting them to PDFs. Ingeneral, Document Translation preserves a document's layout and styleof DOCX and PPTX files better than PDF files. After a document translation, youcan 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 toDOCX conversions is available for batch document translations on nativePDF files only. Also, Document Translation preserves hyperlinks, fontsize, and font color for native PDF files only (for both synchronous and batchtranslations).

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

Before you begin

Before you can start using the Cloud Translation API, you must have a project that hasthe Cloud Translation API enabled, and you must have the appropriate credentials. You canalso install client libraries for common programming languages to help you makecalls to the API. For more information, see the Setup page.

Required permissions

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

Translate documents (online)

Online translation provides real-time processing (synchronous processing) of asingle 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 theenableShadowRemovalNativePdf field, the limit is 20 pages. Forscanned 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 andoutputs the result to a Cloud Storage bucket. The response also returns abyte 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 Translationdetects the language for you. The detected language is included in the output inthe 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 libraryconst {TranslationServiceClient} = require('@google-cloud/translate').v3beta1;// Instantiates a clientconst translationClient = new TranslationServiceClient();const documentInputConfig = { gcsSource: { inputUri: inputUri, },};async function translateDocument() { // Construct request const request = { parent: translationClient.locationPath(projectId, location), documentInputConfig: documentInputConfig, sourceLanguageCode: 'en-US', targetLanguageCode: 'sr-Latn', }; // Run request const [response] = await translationClient.translateDocument(request); console.log( `Response: Mime Type - ${response.documentTranslation.mimeType}` );}translateDocument();

Translate a document inline

The following example sends a document inline as part of the request. You mustinclude the MIME type for inline document translations.

If you don't specify a source language code, Document Translationdetects the language for you. The detected language is included in the output inthe 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": { "mimeType": "MIME_TYPE", "content": "INPUT_BYTE_STREAM" }, "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"}

from google.cloud import translate_v3beta1 as translatedef translate_document( project_id: str, file_path: str,) -> translate.TranslationServiceClient: """Translates a document. Args: project_id: The GCP project ID. file_path: The path to the file to be translated. Returns: The translated document. """ client = translate.TranslationServiceClient() location = "us-central1" parent = f"projects/{project_id}/locations/{location}" # Supported file types: https://cloud.google.com/translate/docs/supported-formats with open(file_path, "rb") as document: document_content = document.read() document_input_config = { "content": document_content, "mime_type": "application/pdf", } response = client.translate_document( request={ "parent": parent, "target_language_code": "fr-FR", "document_input_config": document_input_config, } ) # To output the translated document, uncomment the code below. # f = open('/tmp/output', 'wb') # f.write(response.document_translation.byte_stream_outputs[0]) # f.close() # If not provided in the TranslationRequest, the translated file will only be returned through a byte-stream # and its output mime type will be the same as the input file's mime type print( f"Response: Detected Language Code - {response.document_translation.detected_language_code}" ) return response

Use an AutoML model or a glossary

Instead of the Google-managed model, you can use your own AutoMLTranslation models to translate documents. In addition to specifying a model,you can also include a glossary to handle domain-specific terminology. If youspecify a model or a glossary, you must specify the source language. Thefollowing example uses an AutoML model and a glossary. If the model orglossary are in a different project, you must have the corresponding IAMpermission to access those resources.

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" } }, "model": "projects/MODEL_PROJECT_ID/locations/MODEL_LOCATION/models/MODEL_ID", "glossary_config": { "glossary": "projects/GLOSSARY_PROJECT_ID/locations/MODEL_LOCATION/glossaries/GLOSSARY_ID" }}

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" }, "glossary_document_translation": { "byteStreamOutputs": ["BYTE_STREAM_USING_GLOSSARY"], "mimeType": "MIME_TYPE" }, "model": "projects/MODEL_PROJECT_ID/locations/MODEL_LOCATION/models/MODEL_ID", "glossaryConfig": { "glossary": "projects/GLOSSARY_PROJECT_ID/locations/MODEL_LOCATION/glossaries/GLOSSARY_ID" }}

Translate documents (batch)

Batch translation allows you to translate multiple files into multiple languagesin a single request. For each request, you can send up to 100 files with a totalcontent size of up to 1 GB or 100 million Unicode codepoints, whichever limit ish*t first. You can specify a particular translation model for each language.

Translate multiple documents

The following example includes multiple input configurations. Each inputconfiguration is a pointer to a file in a Cloud Storage bucket.

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

{ "source_language_code": "SOURCE_LANGUAGE", "target_language_codes": ["TARGET_LANGUAGE", ...], "input_configs": [ { "gcsSource": { "inputUri": "gs://INPUT_FILE_PATH_1" } }, { "gcsSource": { "inputUri": "gs://INPUT_FILE_PATH_2" } }, ... ], "output_config": { "gcsDestination": { "outputUriPrefix": "gs://OUTPUT_FILE_PREFIX" } }}

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:batchTranslateDocument"

$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:batchTranslateDocument" | Select-Object -Expand Content

{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.translation.v3.BatchTranslateDocumentMetadata", "state": "RUNNING" }}

/** * TODO(developer): Uncomment these variables before running the sample. */// const projectId = 'YOUR_PROJECT_ID';// const location = 'us-central1';// const inputUri = 'path_to_your_files';// const outputUri = 'path_to_your_output_bucket';// Imports the Google Cloud Translation libraryconst {TranslationServiceClient} = require('@google-cloud/translate').v3beta1;// Instantiates a clientconst translationClient = new TranslationServiceClient();const documentInputConfig = { gcsSource: { inputUri: inputUri, },};async function batchTranslateDocument() { // Construct request const request = { parent: translationClient.locationPath(projectId, location), documentInputConfig: documentInputConfig, sourceLanguageCode: 'en-US', targetLanguageCodes: ['sr-Latn'], inputConfigs: [ { gcsSource: { inputUri: inputUri, }, }, ], outputConfig: { gcsDestination: { outputUriPrefix: outputUri, }, }, }; // Batch translate documents using a long-running operation. // You can wait for now, or get results later. const [operation] = await translationClient.batchTranslateDocument(request); // Wait for operation to complete. const [response] = await operation.promise(); console.log(`Total Pages: ${response.totalPages}`);}batchTranslateDocument();

from google.cloud import translate_v3beta1 as translatedef batch_translate_document( input_uri: str, output_uri: str, project_id: str, timeout: int = 180,) -> translate.BatchTranslateDocumentResponse: """Batch translate documents. Args: input_uri: Google Cloud Storage location of the input document. output_uri: Google Cloud Storage location of the output document. project_id: The GCP project ID. timeout: The timeout for this request. Returns: Translated document response """ client = translate.TranslationServiceClient() # The ``global`` location is not supported for batch translation location = "us-central1" # Google Cloud Storage location for the source input. This can be a single file # (for example, ``gs://translation-test/input.docx``) or a wildcard # (for example, ``gs://translation-test/*``). # Supported file types: https://cloud.google.com/translate/docs/supported-formats gcs_source = {"input_uri": input_uri} batch_document_input_configs = { "gcs_source": gcs_source, } gcs_destination = {"output_uri_prefix": output_uri} batch_document_output_config = {"gcs_destination": gcs_destination} parent = f"projects/{project_id}/locations/{location}" # Supported language codes: https://cloud.google.com/translate/docs/language operation = client.batch_translate_document( request={ "parent": parent, "source_language_code": "en-US", "target_language_codes": ["fr-FR"], "input_configs": [batch_document_input_configs], "output_config": batch_document_output_config, } ) print("Waiting for operation to complete...") response = operation.result(timeout) print(f"Total Pages: {response.total_pages}") return response

Translate and convert a native PDF file

The following example translates and converts a native PDF file to a DOCX file.You can specify multiple inputs of various file types; they don't all have to benative PDF files. However, scanned PDF files cannot be included when including aconversion; the request is rejected and no translations are done. Only nativePDF files are translated and converted to DOCX files. For example, if youinclude PPTX files, they are translated and returned as PPTX files.

If you regularly translate a mix of scanned and native PDF files, we recommendthat you organize them into separate Cloud Storage buckets. That way,when you request a batch translation and conversion, you can easily exclude thebucket that contains scanned PDF files instead of having to exclude individualfiles.

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

{ "source_language_code": "SOURCE_LANGUAGE", "target_language_codes": ["TARGET_LANGUAGE", ...], "input_configs": [ { "gcsSource": { "inputUri": "gs://INPUT_FILE_PATH_1" } }, { "gcsSource": { "inputUri": "gs://INPUT_FILE_PATH_2" } }, ... ], "output_config": { "gcsDestination": { "outputUriPrefix": "gs://OUTPUT_FILE_PREFIX" } }, "format_conversions": { "application/pdf": "application/vnd.openxmlformats-officedocument.wordprocessingml.document" }}

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:batchTranslateDocument"

$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:batchTranslateDocument" | Select-Object -Expand Content

{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.translation.v3.BatchTranslateDocumentMetadata", "state": "RUNNING" }}

Use an AutoML model or a glossary

Instead of the Google-managed model, you can use your own AutoMLTranslation models to translate documents. In addition to specifying a model,you can also include a glossary to handle domain-specific terminology. If youspecify a model or a glossary, you must specify the source language. Thefollowing example uses an AutoML model and a glossary. You can specifyup to 10 target languages with their own model and glossary.

If you specify a model for some target languages and not others,Document Translation uses the Google-managed model for the unspecifiedlanguages. Similarly, if you specify a glossary for some target languages,Document Translation doesn't use any glossary for the unspecifiedlanguages.

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

{ "source_language_code": "SOURCE_LANGUAGE", "target_language_codes": "[TARGET_LANGUAGE, ...]", "input_configs": [ { "gcsSource": { "inputUri": "gs://INPUT_FILE_PATH" } } ], "output_config": { "gcsDestination": { "outputUriPrefix": "gs://OUTPUT_FILE_PREFIX" } }, "models": { "TARGET_LANGUAGE": "projects/MODEL_PROJECT_ID/locations/MODEL_LOCATION/models/MODEL_ID", ... }, "glossaries": { "TARGET_LANGUAGE": { "glossary": "projects/GLOSSARY_PROJECT_ID/locations/MODEL_LOCATION/glossaries/GLOSSARY_ID" }, ... }}

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

{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.translation.v3.BatchTranslateDocumentMetadata", "state": "RUNNING" }}

Overlapping text

In some cases, native PDF translations might include translated textoverlaid on the source text. This issue is referred to as shadow text.

In certain cases, you can remove shadow text by enabling theenableShadowRemovalNativePdfoption. If you enable this option, the response latency increases and, foronline document translations, the page limit is reduced to 20. You can only knowif your document requires shadow text removal only after it has been translated.

In other cases, if the enableShadowRemovalNativePdf option doesn'twork, convert the PDF to an image and then translate it. Typically, these casesinclude multiple layers text, like when selectable text is on top of abackground image that also includes text. Converting the PDF to an image enablesCloud Translation to process the document as a scanned PDF. To do the conversion,you can use Chrome (print as image) or other third-party tools.

Text orientation

For scanned PDF translations, the source text must be oriented horizontally.If, for example, a scanned document includes text that is sloping up or down,Cloud Translation might not correctly parse all the text, which results inincorrect or incomplete translations.

If your documents aren't consistently oriented, you can have Cloud Translationorient them for you. In your translation request, enable theenableRotationCorrectionoption so that text is correctly oriented before translation.

What's next

• Document Translation is priced per page. For more information, seePricing.