canonical: https://jentic.com/apis/microsofttranslator.com/microsofttranslator

# Microsofttranslator Azure Translator

Jentic publishes the only available OpenAPI specification for Azure Translator, keeping it validated and agent-ready. Azure Translator is Microsoft's cloud machine translation service exposing a JSON-based v3 Web API for text translation across 100+ languages, language detection, transliteration between scripts, sentence boundary detection, and bilingual dictionary lookup. It authenticates with an Azure subscription key passed in the Ocp-Apim-Subscription-Key header and is billed through the customer's Azure Cognitive Services Translator resource. The seven endpoints cover the full v3 surface used by translation, localisation, and content classification agents.

## For AI agents

Translate text between 100+ languages, detect input language, transliterate scripts, and look up bilingual dictionary entries via Azure's machine translation service.

## Scope

Does not handle speech translation, document translation jobs, or custom-trained model management - use for synchronous text translation, detection, transliteration, and dictionary lookup only.

## Capabilities

- Translate text between any of 100+ supported languages with optional profanity and HTML handling
- Detect the language and script of an arbitrary input string before downstream processing
- Transliterate text from one script to another (for example Cyrillic to Latin)
- Break text into sentence-bounded segments for downstream NLP pipelines
- Look up bilingual dictionary entries with back-translations for higher quality glossary work
- Retrieve example sentences for a translated word pair to ground translation choices
- List the languages supported by the translation, transliteration, and dictionary surfaces

## Use cases

### Multilingual Customer Support

An agent receives an inbound message in any language, calls /detect to identify the source, then calls /translate to produce English (or any agent-side language) so the support assistant can respond. The reply is translated back to the customer's language before sending.

Example prompt: Detect the language of an incoming support ticket and translate it to English using POST /translate with from inferred from /detect.

### Content Localisation Pipeline

Marketing or documentation content is translated into multiple target languages in a single call by passing several to-language codes. The same workflow can transliterate brand names into target scripts and pull dictionary examples to vet ambiguous terms.

Example prompt: Translate a 500-word product description into Japanese, German, and Brazilian Portuguese in one POST /translate call with to=ja&to=de&to=pt-br.

### Search and Indexing Across Languages

Before indexing user-generated content, an agent uses /detect to record the language and /breaksentence to chunk long documents into searchable units. This produces clean multilingual embeddings for downstream retrieval.

Example prompt: For a batch of 50 forum posts, call POST /detect to tag each with a language code, then POST /breaksentence on posts longer than 200 characters.

### Agent Translation via Jentic

Through Jentic, an agent searches for translation operations by intent and receives the schema for /translate without parsing docs. The Azure subscription key is stored in your Jentic One instance and injected at execution time so the agent never handles the secret.

Example prompt: Use Jentic search 'translate text from english to japanese', load schema for POST /translate, and execute with body=[{"Text":"Hello world"}] and to=ja.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/translate` | Translate text into one or more target languages |
| POST | `/detect` | Detect the language of input text |
| GET | `/languages` | List supported languages |
| POST | `/transliterate` | Transliterate text between scripts |
| POST | `/breaksentence` | Break text into sentences |
| POST | `/dictionary/lookup` | Look up bilingual dictionary entries |
| POST | `/dictionary/examples` | Get example sentences for a dictionary entry |

## Key resources

- **Translation** — Translate text between supported language pairs
- **Detection** — Detect input language and script
- **Transliteration** — Convert text between scripts within the same language
- **Dictionary** — Look up bilingual dictionary entries and example sentences
- **Languages** — Enumerate supported languages for each operation

## Why Jentic

- **Setup:** Wiring Azure Translator by hand means reading its Ocp-Apim-Subscription-Key header scheme, picking the right global, nam, eur, or apc host, and handling errors yourself. Through Jentic you install once, import Azure Translator from the API Directory, store the subscription key once, and your agent calls it.
- **Permission scoping:** Azure Translator carries the text and languages in the request body rather than a fixed URL path resource, so limit the agent to the operations it needs, such as translate or detect. You choose which operations it may call, so transliteration or dictionary lookups are not included unless you add them.
- **Credential handling:** Your Azure Translator subscription key is stored once, encrypted, by your own Jentic One instance and injected into the Ocp-Apim-Subscription-Key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'translate text from English to Japanese' or 'detect a language', and Jentic returns the matching Translator operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Cloud Translation API** — Google's machine translation service with neural models across 100+ languages.
- **OpenAI API** — General LLM API that can perform translation as one of many text generation tasks.
- **Google Tasks API** — Pair translation with task creation for cross-language workflow automation.

## FAQ

### Why is there no official OpenAPI spec for Azure Translator?

Microsoft does not publish a dedicated OpenAPI specification for the Translator v3 Text API. Jentic generates and maintains this spec so that AI agents and developers can call Azure Translator via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Azure Translator API use?

The API uses an Azure subscription key passed in the Ocp-Apim-Subscription-Key header. The key is provisioned with the Translator resource in the Azure portal. Through Jentic, the subscription key sits in the encrypted vault and is injected on each call without entering the agent's context.

### Can I translate to multiple target languages in one call?

Yes. POST /translate accepts the to query parameter multiple times (e.g. to=ja&to=de&to=fr) and returns translations for each in a single response, which keeps batch localisation work to one network round trip.

### What are the rate limits for Azure Translator?

Azure Translator throttles by characters per hour and by request rate, with limits depending on the pricing tier (F0 free, S1+ standard) selected on the Translator resource. Limits are documented in the Azure Translator service documentation; expect a 429 with a Retry-After header when exceeded.

### How do I translate text through Jentic?

Run pip install jentic, then search for 'translate text', load the schema for POST /translate, and execute with the body array of texts and the to language code. Jentic injects your stored Ocp-Apim-Subscription-Key at execution time.

### Does Azure Translator support speech translation?

No. The endpoints in this spec cover the v3 Text Translation surface only. Speech-to-speech translation is provided by a separate Azure Speech service and is not part of this API.

### Can I limit what my agent is allowed to do with the Azure Translator API?

Yes. Because you self-host Jentic One, your own rules decide which Azure Translator operations the agent may call, so you can allow just POST /translate and POST /detect while withholding /transliterate, `/dictionary/lookup`, and `/dictionary/examples.` Azure Translator carries the text and target languages in the request body rather than in a fixed URL path, so scoping is done per operation rather than per resource path. Your Azure subscription key is stored once by your Jentic One instance and injected into the Ocp-Apim-Subscription-Key header at execution time, so the agent can only reach the operations you have granted and never handles the credential itself.