canonical: https://jentic.com/apis/googleapis.com/translate

# Google Cloud Translation API

Cloud Translation v3 (Advanced) translates text and documents between more than 130 languages using Google's neural machine translation models. Beyond basic string translation it supports glossaries (consistent terminology), AutoML and adaptive custom models, batch translation jobs that read source files from Cloud Storage and write results back, language detection, and document translation that preserves layout for DOCX, PDF, PPTX, and XLSX files. The v3 surface also exposes datasets and model resources for training custom translation models on parallel corpora.

## For AI agents

Translate text and documents between 130+ languages, detect source language, and run batch and adaptive custom translation models with glossary support.

## Scope

Does not handle speech transcription, voice synthesis, or human translation review - use for machine translation of text and documents only.

## Capabilities

- Translate text between any pair of 130+ supported languages
- Translate office documents preserving layout (DOCX, PDF, PPTX, XLSX)
- Run batch translation jobs reading from and writing to Cloud Storage
- Detect the source language of supplied text
- Apply glossaries to enforce consistent terminology in translations
- Train and run AutoML and adaptive custom translation models from parallel corpora

## Use cases

### Localised Web Content at Publish Time

CMS publishing pipelines call Cloud Translation as part of the publish step, translating each new article into the site's supported languages and storing the output alongside the source. Glossaries pin brand and product names so 'Acme Cloud' is never localised to 'Acme Nube'. Results are cached so re-publish only translates changed paragraphs.

Example prompt: POST /v3/{parent}:translateText with contents=[article body], targetLanguageCode='es', and a glossaryConfig referencing the brand glossary.

### Document Translation Preserving Format

Legal and HR teams translate contracts, policies, and benefits documents between languages while preserving the original DOCX or PDF layout. The translateDocument operation accepts the source document inline or via Cloud Storage, runs neural translation across the body text, and emits the translated document with formatting, tables, and images intact. This replaces a manual copy-paste-into-Word-then-reformat workflow.

Example prompt: POST /v3/{parent}:translateDocument with documentInputConfig pointing at the GCS PDF URI and outputConfig writing the translated PDF back to a target prefix.

### Batch Translation of a Content Library

Publishers with thousands of source files (product descriptions, support articles) submit a batch translation job that reads source files from a Cloud Storage prefix and writes translations into target-language prefixes. The long-running job parallelises across files and supports multiple target languages per submission, completing what used to take days of synchronous calls in a single overnight run.

Example prompt: POST /v3/{parent}:batchTranslateText with inputConfigs pointing at gs://source-bucket/articles/, outputConfig at gs://target-bucket/, and targetLanguageCodes=['es','fr','de'].

### Agent-Driven Localisation via Jentic

An AI agent receiving a help-desk ticket in any language detects the source language and translates the ticket body into the support agent's language. Through Jentic the agent calls detectLanguage and translateText as two tool calls; Jentic isolates the GCP credential and caches glossary lookups across requests.

Example prompt: Through Jentic, search 'detect language and translate text', call /v3/{parent}:detectLanguage on the inbound message, then /v3/{parent}:translateText with targetLanguageCode set to the agent's locale.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v3/{+name}/locations | List locations supporting Cloud Translation in a project |
| GET | /v3/{+name}/operations | List long-running translation operations |
| POST | /v3/{+name}:cancel | Cancel a long-running translation operation |
| POST | /v3/{+dataset}:exportData | Export a translation dataset to Cloud Storage |
| POST | /v3/{+dataset}:importData | Import parallel corpus data into a translation dataset |

## Key resources

- **TranslateText** — Synchronous string translation between source and target language codes
- **TranslateDocument** — Document-level translation preserving DOCX/PDF/PPTX/XLSX formatting
- **Glossary** — Vocabulary file enforcing consistent translations of named terms
- **BatchTranslateText** — Long-running job translating Cloud Storage source files into target prefixes
- **Dataset** — Parallel corpus used to train an AutoML or adaptive custom model
- **Model** — Trained AutoML or adaptive translation model invoked by name

## Why Jentic

- **Setup:** Wiring the Cloud Translation API by hand means setting up a Google service account, granting the cloud-platform or cloud-translation scope, building the project and location parent names, and assembling the translate and glossary config yourself. Through Jentic you install once, import the Cloud Translation API from the API Directory, store the service-account credential once, and your agent calls it.
- **Permission scoping:** The text to translate travels in the request body, so scope by operation: limit the agent to the operations it needs, such as translateText and detectLanguage. You choose the operations it may call, so dataset importData and exportData are not included unless you add them.
- **Credential handling:** Your Cloud Translation service-account credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'translate text' or 'detect language', and Jentic returns the matching Translation v3 operation with its input schema, including contents, sourceLanguageCode, targetLanguageCode, and glossaryConfig, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Cloud Text-to-Speech API** — Synthesize the translated text into spoken audio in the target language
- **Cloud Speech-to-Text API** — Transcribe spoken audio before translating the resulting text
- **Google Cloud Storage API** — Holds source documents and translated outputs for batch translation jobs

## FAQ

### What authentication does the Cloud Translation API use?

OAuth 2.0 with the cloud-platform or cloud-translation scope. Service-account credentials with the cloudtranslate.user role are typical for production workloads. Through Jentic, the service-account JSON is held in the encrypted vault and short-lived tokens are minted per request.

### Can I translate documents while preserving formatting with the Cloud Translation API?

Yes. The translateDocument operation accepts DOCX, PDF, PPTX, and XLSX inputs either inline or via a Cloud Storage URI and returns the translated document with original formatting, tables, and images intact. This is the standard path for translating contracts, decks, and spreadsheets without breaking layout.

### What are the rate limits for the Cloud Translation API?

The synchronous translateText endpoint allows several thousand requests per minute per project with a per-character throughput cap that varies by region. Batch translation has separate concurrency limits - typically tens of concurrent long-running jobs. Quota increases are available through the Cloud Console.

### How do I translate text through Jentic?

Search Jentic for 'translate text', load POST /v3/{parent}:translateText, and execute it with parent=projects/PROJECT/locations/global, contents (an array of strings), sourceLanguageCode (optional - auto-detect if omitted), and targetLanguageCode. Get started with Jentic One, the self-hosted execution layer.

### Does the Cloud Translation API support custom models?

Yes. v3 (Advanced) supports AutoML Translation custom models trained from parallel corpora and adaptive translation models that fine-tune on a glossary. Reference a custom model by passing model='projects/{p}/locations/{l}/models/{m}' on translateText. Datasets and models are managed under the same v3 surface.

### Is the Cloud Translation API free?

Pricing is per-character with a free monthly tier (typically 500,000 characters across the basic tier). Advanced features (translateDocument, glossaries, batch, AutoML) are billed at higher per-character rates. See cloud.google.com/translate/pricing for current rates.

### Can I limit what my agent is allowed to do with the Cloud Translation API?

Yes. Because you run Jentic One yourself, your own rules decide which Cloud Translation operations and credentials the agent may use. You can allow it only the operations it needs, such as translateText and detectLanguage, while withholding others like dataset importData and exportData unless you explicitly add them. The service-account credential is injected at execution time under your control, so the agent can only call the operations you have scoped it to.