Skip to main content
Translates a list of short strings — field values, addresses, notes, line-item descriptions — into a target language with the deployment’s translation engines. Display name “Translate Text”. Off by default. It is the text half of document translation. The review viewer’s Show Translation overlay translates a document page (OCR, geometry, cache); this tool translates the strings you hand it, with no document, no cache and no geometry. Use it to show extracted values in the reviewer’s language, not to translate a file.

​
Authentication and enablement

No integration. Two gates, both must pass:
  • The tool is enabled on the agent (off by default).
  • The agent’s document translation setting (document_translation_enabled) is on. Off is reported as a tool error, never as a silent pass-through. The agent’s document_translation_model override picks the engine, exactly as it does for the page overlay.
Available to an agent step, to the Platform MCP, and to an App Tool bundle through /run (declare {"op": "…", "tool": "translate_text", "params": ["texts", "target_language"]} in the binding’s tools; no configured instance is needed because there is nothing to configure).

​
Inputs

  • texts — strings to translate, in the order you want them back. At most 200 strings and 20,000 characters per call (characters, not bytes).
  • target_language — BCP-47 code (en, fr, de, …). Defaults to en.

​
Output

translations is index-aligned with texts. translated: false means the engine handed the source back (already in the target language, or empty), so render it as untranslated rather than as a translation.

​
Billing

One unit per string actually translated (translated_count), at the translate_text rate. Strings returned unchanged cost nothing. From an agent step the units land on that step; from an App Tool bundle they land on the app_tool_run step the call records, priced from the same rate.

​
Limits and side effects

  • Read-only; no data is stored. Identical strings in one call are deduplicated by the engine.
  • Bounded per call as above; split larger sets across calls. From a bundle, batch: one call carrying every field of a form is one run (and, with "record": false on the op, no feed card), where one call per field is one run each.
  • Engine selection and failover (Cloud Translation ↔ LLM) follow the deployment’s DOCUMENT_TRANSLATION_BACKEND configuration.

​
Expected errors

  • Empty texts, more than 200 strings, or more than 20,000 characters — tool error naming the bound.
  • Document translation not enabled for the agent — tool error (not enabled).
  • Engine refused (quota, transport) — tool error carrying the engine’s reason.
  • No translation engine configured on the deployment — the step fails with document translation is not configured; from a bundle, /run answers 501.