Microsoft Azure Text Translation is a cloud-based service that utilizes advanced machine learning algorithms to accurately and efficiently translate text content from one language to another. This powerful tool enables users to easily and seamlessly convert written content into multiple languages, breaking down communication barriers and enabling global collaboration.
swagger: '2.0'
info:
title: Microsoft Azure Text Translation
version: '3.0'
description: >-
Text translation is a cloud-based REST API feature of the Translator service
that uses neural
machine translation technology to enable quick and accurate source-to-target
text translation
in real time across all supported languages.
The following methods are supported by the Text Translation feature:
Languages. Returns a list of languages supported by Translate,
Transliterate, and Dictionary Lookup operations.
Translate. Renders single source-language text to multiple target-language
texts with a single request.
Transliterate. Converts characters or letters of a source language to the
corresponding characters or letters of a target language.
Detect. Returns the source code language code and a boolean variable
denoting whether the detected language is supported for text translation and
transliteration.
Dictionary lookup. Returns equivalent words for the source term in the
target language.
Dictionary example Returns grammatical structure and context examples for
the source term and target term pair.
x-typespec-generated:
- emitter: '@azure-tools/typespec-autorest'
schemes:
- https
x-ms-parameterized-host:
hostTemplate: '{Endpoint}'
useSchemePrefix: false
parameters:
- name: Endpoint
in: path
description: >-
Supported Text Translation endpoints (protocol and hostname, for
example:
https://api.cognitive.microsofttranslator.com).
required: true
type: string
format: uri
x-ms-skip-url-encoding: true
produces:
- application/json
consumes:
- application/json
tags:
- name: Breaksentence
- name: Dictionary
- name: Languages
- name: Translate
- name: Transliterate
paths:
/breaksentence:
post:
operationId: microsoftAzureFindsentenceboundaries
summary: Microsoft Azure Find Sentence Boundaries
description: Find Sentence Boundaries
parameters:
- name: X-ClientTraceId
in: header
description: A client-generated GUID to uniquely identify the request.
required: false
type: string
x-ms-client-name: clientTraceId
- $ref: '#/parameters/BreakSentenceParameters.language'
- $ref: '#/parameters/BreakSentenceParameters.script'
- name: api-version
in: query
description: Mandatory API version parameter
required: true
type: string
x-ms-client-name: apiVersion
- name: requestBody
in: body
description: Defines the content of the request
required: true
schema:
type: array
items:
$ref: '#/definitions/InputTextItem'
x-ms-identifiers: []
responses:
'200':
description: Response for the Break SEntence API.
schema:
type: array
items:
$ref: '#/definitions/BreakSentenceItem'
x-ms-identifiers: []
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/ErrorResponse'
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-ms-examples:
Find Sentence Boundaries:
$ref: ./examples/FindSentenceBoundaries_MaximumSet_Gen.json
Find Sentence Boundaries with minimum properties:
$ref: ./examples/FindSentenceBoundaries_MinimumSet_Gen.json
tags:
- Breaksentence
/dictionary/examples:
post:
operationId: microsoftAzureLookupdictionaryexamples
summary: Microsoft Azure Lookup Dictionary Examples
description: Lookup Dictionary Examples
parameters:
- name: X-ClientTraceId
in: header
description: A client-generated GUID to uniquely identify the request.
required: false
type: string
x-ms-client-name: clientTraceId
- name: from
in: query
description: >-
Specifies the language of the input text.
The source language must be one of the supported languages included
in the dictionary scope.
required: true
type: string
- name: to
in: query
description: >-
Specifies the language of the output text.
The target language must be one of the supported languages included
in the dictionary scope.
required: true
type: string
- name: api-version
in: query
description: Mandatory API version parameter
required: true
type: string
x-ms-client-name: apiVersion
- name: requestBody
in: body
description: Defines the content of the request
required: true
schema:
type: array
items:
$ref: '#/definitions/DictionaryExampleTextItem'
x-ms-identifiers: []
responses:
'200':
description: Response for the dictionary examples API.
schema:
type: array
items:
$ref: '#/definitions/DictionaryExampleItem'
x-ms-identifiers: []
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/ErrorResponse'
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-ms-examples:
Lookup Dictionary Examples:
$ref: ./examples/LookupDictionaryExamples_MaximumSet_Gen.json
Lookup Dictionary Examples with minimum properties:
$ref: ./examples/LookupDictionaryExamples_MinimumSet_Gen.json
tags:
- Dictionary
/dictionary/lookup:
post:
operationId: microsoftAzureLookupdictionaryentries
summary: Microsoft Azure Lookup Dictionary Entries
description: Lookup Dictionary Entries
parameters:
- name: X-ClientTraceId
in: header
description: A client-generated GUID to uniquely identify the request.
required: false
type: string
x-ms-client-name: clientTraceId
- name: from
in: query
description: >-
Specifies the language of the input text.
The source language must be one of the supported languages included
in the dictionary scope.
required: true
type: string
- name: to
in: query
description: >-
Specifies the language of the output text.
The target language must be one of the supported languages included
in the dictionary scope.
required: true
type: string
- name: api-version
in: query
description: Mandatory API version parameter
required: true
type: string
x-ms-client-name: apiVersion
- name: requestBody
in: body
description: Defines the content of the request
required: true
schema:
type: array
items:
$ref: '#/definitions/InputTextItem'
x-ms-identifiers: []
responses:
'200':
description: Response for the dictionary lookup API.
schema:
type: array
items:
$ref: '#/definitions/DictionaryLookupItem'
x-ms-identifiers: []
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/ErrorResponse'
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-ms-examples:
Lookup Dictionary Entries:
$ref: ./examples/LookupDictionaryEntries_MaximumSet_Gen.json
Lookup Dictionary Entries with minimum properties:
$ref: ./examples/LookupDictionaryEntries_MinimumSet_Gen.json
tags:
- Dictionary
/languages:
get:
operationId: microsoftAzureGetlanguages
summary: >-
Microsoft Azure Gets The Set Of Languages Currently Supported By Other Operations Of The Translator
description: >-
Gets the set of languages currently supported by other operations of the
Translator.
parameters:
- name: X-ClientTraceId
in: header
description: A client-generated GUID to uniquely identify the request.
required: false
type: string
x-ms-client-name: clientTraceId
- $ref: '#/parameters/GetLanguageParameters.scope'
- $ref: '#/parameters/GetLanguageParameters.acceptLanguage'
- $ref: '#/parameters/GetLanguageParameters.ifNoneMatch'
- name: api-version
in: query
description: Mandatory API version parameter
required: true
type: string
x-ms-client-name: apiVersion
responses:
'200':
description: The request has succeeded.
schema:
$ref: '#/definitions/GetLanguagesResult'
headers:
ETag:
type: string
description: >-
Current value of the entity tag for the requested groups of
supported languages.
To make subsequent requests more efficient, the client may send
the `ETag` value in an
`If-None-Match` header field.
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/ErrorResponse'
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-ms-examples:
Gets the set of languages currently supported by other operations of the Translator with minimum properties.:
$ref: ./examples/GetLanguages_MinimumSet_Gen.json
Gets the set of languages currently supported by other operations of the Translator.:
$ref: ./examples/GetLanguages_MaximumSet_Gen.json
tags:
- Languages
/translate:
post:
operationId: microsoftAzureTranslate
summary: Microsoft Azure Translate Text
description: Translate Text
parameters:
- name: X-ClientTraceId
in: header
description: A client-generated GUID to uniquely identify the request.
required: false
type: string
x-ms-client-name: clientTraceId
- $ref: '#/parameters/TranslateParameters.to'
- $ref: '#/parameters/TranslateParameters.from'
- $ref: '#/parameters/TranslateParameters.textType'
- $ref: '#/parameters/TranslateParameters.category'
- $ref: '#/parameters/TranslateParameters.profanityAction'
- $ref: '#/parameters/TranslateParameters.profanityMarker'
- $ref: '#/parameters/TranslateParameters.includeAlignment'
- $ref: '#/parameters/TranslateParameters.includeSentenceLength'
- $ref: '#/parameters/TranslateParameters.suggestedFrom'
- $ref: '#/parameters/TranslateParameters.fromScript'
- $ref: '#/parameters/TranslateParameters.toScript'
- $ref: '#/parameters/TranslateParameters.allowFallback'
- name: api-version
in: query
description: Mandatory API version parameter
required: true
type: string
x-ms-client-name: apiVersion
- name: requestBody
in: body
description: Defines the content of the request
required: true
schema:
type: array
items:
$ref: '#/definitions/InputTextItem'
x-ms-identifiers: []
responses:
'200':
description: Response for the translation API.
schema:
type: array
items:
$ref: '#/definitions/TranslatedTextItem'
x-ms-identifiers: []
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-metered-usage:
type: integer
format: int32
description: >-
Specifies consumption (the number of characters for which the
user will be charged) for the translation
job request. For example, if the word "Hello" is translated from
English (en) to French (fr),
this field will return the value '5'.
x-mt-system:
type: string
description: >-
Specifies the system type that was used for translation for each
'to' language requested for translation.
The value is a comma-separated list of strings. Each string
indicates a type:
* Custom - Request includes a custom system and at least one
custom system was used during translation.
* Team - All other requests
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/ErrorResponse'
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-ms-examples:
Translate Text:
$ref: ./examples/Translate_MaximumSet_Gen.json
Translate Text with minimum properties:
$ref: ./examples/Translate_MinimumSet_Gen.json
tags:
- Translate
/transliterate:
post:
operationId: microsoftAzureTransliterate
summary: Microsoft Azure Transliterate Text
description: Transliterate Text
parameters:
- name: X-ClientTraceId
in: header
description: A client-generated GUID to uniquely identify the request.
required: false
type: string
x-ms-client-name: clientTraceId
- $ref: '#/parameters/TransliterateParameters.language'
- $ref: '#/parameters/TransliterateParameters.fromScript'
- $ref: '#/parameters/TransliterateParameters.toScript'
- name: api-version
in: query
description: Mandatory API version parameter
required: true
type: string
x-ms-client-name: apiVersion
- name: requestBody
in: body
description: Defines the content of the request
required: true
schema:
type: array
items:
$ref: '#/definitions/InputTextItem'
x-ms-identifiers: []
responses:
'200':
description: Response for the transliteration API.
schema:
type: array
items:
$ref: '#/definitions/TransliteratedText'
x-ms-identifiers: []
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/ErrorResponse'
headers:
X-RequestId:
type: string
description: >-
Value generated by the service to identify the request. It is
used for troubleshooting purposes.
x-ms-examples:
Transliterate Text:
$ref: ./examples/Transliterate_MaximumSet_Gen.json
Transliterate Text with minimum properties:
$ref: ./examples/Transliterate_MinimumSet_Gen.json
tags:
- Transliterate
definitions:
APIVersion:
type: string
description: Text Translation supported versions
enum:
- '3.0'
x-ms-enum:
name: APIVersion
modelAsString: true
values:
- name: v3_0
value: '3.0'
BackTranslation:
type: object
description: Back Translation
properties:
normalizedText:
type: string
description: >-
A string giving the normalized form of the source term that is a
back-translation of the target.
This value should be used as input to lookup examples.
displayText:
type: string
description: >-
A string giving the source term that is a back-translation of the
target in a form best
suited for end-user display.
numExamples:
type: integer
format: int32
description: >-
An integer representing the number of examples that are available for
this translation pair.
Actual examples must be retrieved with a separate call to lookup
examples. The number is mostly
intended to facilitate display in a UX. For example, a user interface
may add a hyperlink
to the back-translation if the number of examples is greater than zero
and show the back-translation
as plain text if there are no examples. Note that the actual number of
examples returned
by a call to lookup examples may be less than numExamples, because
additional filtering may be
applied on the fly to remove "bad" examples.
frequencyCount:
type: integer
format: int32
description: >-
An integer representing the frequency of this translation pair in the
data. The main purpose of this
field is to provide a user interface with a means to sort
back-translations so the most frequent terms are first.
required:
- normalizedText
- displayText
- numExamples
- frequencyCount
BreakSentenceItem:
type: object
description: Item containing break sentence result.
properties:
detectedLanguage:
$ref: '#/definitions/DetectedLanguage'
description: >-
The detectedLanguage property is only present in the result object
when language auto-detection is requested.
sentLen:
type: array
description: >-
An integer array representing the lengths of the sentences in the
input text.
The length of the array is the number of sentences, and the values are
the length of each sentence.
items:
type: integer
format: int32
required:
- sentLen
BreakSentenceResult:
type: object
description: Response for the Break SEntence API.
properties:
result:
type: array
description: Array of the break sentence elements.
items:
$ref: '#/definitions/BreakSentenceItem'
x-ms-identifiers: []
required:
- result
CommonScriptModel:
type: object
description: Common properties of language script
properties:
code:
type: string
description: Code identifying the script.
name:
type: string
description: >-
Display name of the script in the locale requested via Accept-Language
header.
nativeName:
type: string
description: Display name of the language in the locale native for the language.
dir:
type: string
description: >-
Directionality, which is rtl for right-to-left languages or ltr for
left-to-right languages.
required:
- code
- name
- nativeName
- dir
DetectedLanguage:
type: object
description: An object describing the detected language.
properties:
language:
type: string
description: A string representing the code of the detected language.
score:
type: number
format: float
description: >-
A float value indicating the confidence in the result.
The score is between zero and one and a low score indicates a low
confidence.
required:
- language
- score
DictionaryExample:
type: object
description: Dictionary Example
properties:
sourcePrefix:
type: string
description: >-
The string to concatenate before the value of sourceTerm to form a
complete example.
Do not add a space character, since it is already there when it should
be.
This value may be an empty string.
sourceTerm:
type: string
description: >-
A string equal to the actual term looked up. The string is added with
sourcePrefix
and sourceSuffix to form the complete example. Its value is separated
so it can be
marked in a user interface, e.g., by bolding it.
sourceSuffix:
type: string
description: >-
The string to concatenate after the value of sourceTerm to form a
complete example.
Do not add a space character, since it is already there when it should
be.
This value may be an empty string.
targetPrefix:
type: string
description: A string similar to sourcePrefix but for the target.
targetTerm:
type: string
description: A string similar to sourceTerm but for the target.
targetSuffix:
type: string
description: A string similar to sourceSuffix but for the target.
required:
- sourcePrefix
- sourceTerm
- sourceSuffix
- targetPrefix
- targetTerm
- targetSuffix
DictionaryExampleItem:
type: object
description: Dictionary Example element
properties:
normalizedSource:
type: string
description: >-
A string giving the normalized form of the source term. Generally,
this should be identical
to the value of the Text field at the matching list index in the body
of the request.
normalizedTarget:
type: string
description: >-
A string giving the normalized form of the target term. Generally,
this should be identical
to the value of the Translation field at the matching list index in
the body of the request.
examples:
type: array
description: A list of examples for the (source term, target term) pair.
items:
$ref: '#/definitions/DictionaryExample'
x-ms-identifiers: []
required:
- normalizedSource
- normalizedTarget
- examples
DictionaryExampleTextItem:
type: object
description: Element containing the text with translation.
properties:
translation:
type: string
description: >-
A string specifying the translated text previously returned by the
Dictionary lookup operation.
This should be the value from the normalizedTarget field in the
translations list of the Dictionary
lookup response. The service will return examples for the specific
source-target word-pair.
required:
- translation
allOf:
- $ref: '#/definitions/InputTextItem'
DictionaryExamplesParameters:
type: object
description: Request parameters for the dictionary examples API.
properties:
from:
type: string
description: >-
Specifies the language of the input text.
The source language must be one of the supported languages included in
the dictionary scope.
to:
type: string
description: >-
Specifies the language of the output text.
The target language must be one of the supported languages included in
the dictionary scope.
required:
- from
- to
DictionaryExamplesResult:
type: object
description: Response for the dictionary examples API.
properties:
result:
type: array
description: Array of the dictionary examples elements.
items:
$ref: '#/definitions/DictionaryExampleItem'
x-ms-identifiers: []
required:
- result
DictionaryLookupItem:
type: object
description: Dictionary Lookup Element
properties:
normalizedSource:
type: string
description: >-
A string giving the normalized form of the source term.
For example, if the request is "JOHN", the normalized form will be
"john".
The content of this field becomes the input to lookup examples.
displaySource:
type: string
description: >-
A string giving the source term in a form best suited for end-user
display.
For example, if the input is "JOHN", the display form will reflect the
usual
spelling of the name: "John".
translations:
type: array
description: A list of translations for the source term.
items:
$ref: '#/definitions/DictionaryTranslation'
x-ms-identifiers: []
required:
- normalizedSource
- displaySource
- translations
DictionaryLookupParameters:
type: object
description: Request parameters for the dictionary lookup API.
properties:
from:
type: string
description: >-
Specifies the language of the input text.
The source language must be one of the supported languages included in
the dictionary scope.
to:
type: string
description: >-
Specifies the language of the output text.
The target language must be one of the supported languages included in
the dictionary scope.
required:
- from
- to
DictionaryLookupResult:
type: object
description: Response for the dictionary lookup API.
properties:
result:
type: array
description: Array of the dictionary lookup elements.
items:
$ref: '#/definitions/DictionaryLookupItem'
x-ms-identifiers: []
required:
- result
DictionaryTranslation:
type: object
description: Translation source term.
properties:
normalizedTarget:
type: string
description: >-
A string giving the normalized form of this term in the target
language.
This value should be used as input to lookup examples.
displayTarget:
type: string
description: >-
A string giving the term in the target language and in a form best
suited
for end-user display. Generally, this will only differ from the
normalizedTarget
in terms of capitalization. For example, a proper noun like "Juan"
will have
normalizedTarget = "juan" and displayTarget = "Juan".
posTag:
type: string
description: A string associating this term with a part-of-speech tag.
confidence:
type: number
format: float
description: >-
A value between 0.0 and 1.0 which represents the "confidence"
(or perhaps more accurately, "probability in the training data") of
that translation pair.
The sum of confidence scores for one source word may or may not sum to
1.0.
prefixWord:
type: string
description: >-
A string giving the word to display as a prefix of the translation.
Currently,
this is the gendered determiner of nouns, in languages that have
gendered determiners.
For example, the prefix of the Spanish word "mosca" is "la", since
"mosca" is a feminine noun in Spanish.
This is only dependent on the translation, and not on the source.
If there is no prefix, it will be the empty string.
backTranslations:
type: array
description: >-
A list of "back translations" of the target. For example, source words
that the target can translate to.
The list is guaranteed to contain the source word that was requested
(e.g., if the source word being
looked up is "fly", then it is guaranteed that "fly" will be in the
backTranslations list).
However, it is not guaranteed to be in the first position, and often
will not be.
items:
$ref: '#/definitions/BackTranslation'
x-ms-identifiers: []
required:
- normalizedTarget
- displayTarget
- posTag
- confidence
- prefixWord
- backTranslations
ErrorDetails:
type: object
description: Error details as returned by Translator Service.
properties:
code:
type: integer
format: int32
description: Number identifier of the error.
message:
type: string
description: Human readable error description.
required:
- code
- message
ErrorResponse:
type: object
description: Representation of the Error Response from Translator Service.
properties:
error:
$ref: '#/definitions/ErrorDetails'
description: Error details.
required:
- error
GetLanguagesResult:
type: object
description: Response for the languages API.
properties:
translation:
type: object
description: Languages that support translate API.
additionalProperties:
$ref: '#/definitions/TranslationLanguage'
transliteration:
type: object
description: Languages that support transliteration API.
additionalProperties:
$ref: '#/definitions/TransliterationLanguage'
dictionary:
type: object
description: Languages that support dictionary API.
additionalProperties:
$ref: '#/definitions/SourceDictionaryLanguage'
InputTextItem:
type: object
description: Element containing the text for translation.
properties:
text:
type: string
description: Text to translate.
required:
- text
ProfanityAction:
type: string
description: Translator profanity actions
enum:
- NoAction
- Marked
- Deleted
x-ms-enum:
name: ProfanityAction
modelAsString: true
values:
- name: NoAction
value: NoAction
- name: Marked
value: Marked
- name: Deleted
value: Deleted
ProfanityMarker:
type: string
description: Translator profanity markers
enum:
- Asterisk
- Tag
x-ms-enum:
name: ProfanityMarker
modelAsString: true
values:
- name: Asterisk
value: Asterisk
- name: Tag
value: Tag
SentenceLength:
type: object
description: An object returning sentence boundaries in the input and output texts.
properties:
srcSentLen:
type: array
description: >-
An integer array representing t
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/text-translation-openapi-original.yml