Azure Translation SDKs for TypeScript Text and document translation with REST-style clients. Installation
Text translation
npm install @azure-rest/ai-translation-text @azure/identity
Document translation
npm install @azure-rest/ai-translation-document @azure/identity Environment Variables TRANSLATOR_ENDPOINT = https://api.cognitive.microsofttranslator.com TRANSLATOR_SUBSCRIPTION_KEY = < your-api-key
TRANSLATOR_REGION
< your-region
e.g., westus, eastus
Text Translation Client
Authentication
import
TextTranslationClient
,
{
TranslatorCredential
}
from
"@azure-rest/ai-translation-text"
;
// API Key + Region
const
credential
:
TranslatorCredential
=
{
key
:
process
.
env
.
TRANSLATOR_SUBSCRIPTION_KEY
!
,
region
:
process
.
env
.
TRANSLATOR_REGION
!
,
}
;
const
client
=
TextTranslationClient
(
process
.
env
.
TRANSLATOR_ENDPOINT
!
,
credential
)
;
// Or just credential (uses global endpoint)
const
client2
=
TextTranslationClient
(
credential
)
;
Translate Text
import
TextTranslationClient
,
{
isUnexpected
}
from
"@azure-rest/ai-translation-text"
;
const
response
=
await
client
.
path
(
"/translate"
)
.
post
(
{
body
:
{
inputs
:
[
{
text
:
"Hello, how are you?"
,
language
:
"en"
,
// source (optional, auto-detect)
targets
:
[
{
language
:
"es"
}
,
{
language
:
"fr"
}
,
]
,
}
,
]
,
}
,
}
)
;
if
(
isUnexpected
(
response
)
)
{
throw
response
.
body
.
error
;
}
for
(
const
result
of
response
.
body
.
value
)
{
for
(
const
translation
of
result
.
translations
)
{
console
.
log
(
${
translation
.
language
}
:
${
translation
.
text
}
)
;
}
}
Translate with Options
const
response
=
await
client
.
path
(
"/translate"
)
.
post
(
{
body
:
{
inputs
:
[
{
text
:
"Hello world"
,
language
:
"en"
,
textType
:
"Plain"
,
// or "Html"
targets
:
[
{
language
:
"de"
,
profanityAction
:
"NoAction"
,
// "Marked" | "Deleted"
tone
:
"formal"
,
// LLM-specific
}
,
]
,
}
,
]
,
}
,
}
)
;
Get Supported Languages
const
response
=
await
client
.
path
(
"/languages"
)
.
get
(
)
;
if
(
isUnexpected
(
response
)
)
{
throw
response
.
body
.
error
;
}
// Translation languages
for
(
const
[
code
,
lang
]
of
Object
.
entries
(
response
.
body
.
translation
||
{
}
)
)
{
console
.
log
(
${
code
}
:
${
lang
.
name
}
(
${
lang
.
nativeName
}
)
)
;
}
Transliterate
const
response
=
await
client
.
path
(
"/transliterate"
)
.
post
(
{
body
:
{
inputs
:
[
{
text
:
"这是个测试"
}
]
}
,
queryParameters
:
{
language
:
"zh-Hans"
,
fromScript
:
"Hans"
,
toScript
:
"Latn"
,
}
,
}
)
;
if
(
!
isUnexpected
(
response
)
)
{
for
(
const
t
of
response
.
body
.
value
)
{
console
.
log
(
${
t
.
script
}
:
${
t
.
text
}
)
;
// Latn: zhè shì gè cè shì
}
}
Detect Language
const
response
=
await
client
.
path
(
"/detect"
)
.
post
(
{
body
:
{
inputs
:
[
{
text
:
"Bonjour le monde"
}
]
}
,
}
)
;
if
(
!
isUnexpected
(
response
)
)
{
for
(
const
result
of
response
.
body
.
value
)
{
console
.
log
(
Language:
${
result
.
language
}
, Score:
${
result
.
score
}
)
;
}
}
Document Translation Client
Authentication
import
DocumentTranslationClient
from
"@azure-rest/ai-translation-document"
;
import
{
DefaultAzureCredential
}
from
"@azure/identity"
;
const
endpoint
=
"https://Status:
${
status
.
status
}
)
;
console
.
log
(
Total:
${
status
.
summary
.
total
}
)
;
console
.
log
(
Success:
${
status
.
summary
.
success
}
)
;
}
// List documents with pagination
const
docsResponse
=
await
client
.
path
(
"/document/batches/{id}/documents"
,
operationId
)
.
get
(
)
;
const
documents
=
paginate
(
client
,
docsResponse
)
;
for
await
(
const
doc
of
documents
)
{
console
.
log
(
${
doc
.
id
}
:
${
doc
.
status
}
)
;
}
Get Supported Formats
const
response
=
await
client
.
path
(
"/document/formats"
)
.
get
(
)
;
if
(
!
isUnexpected
(
response
)
)
{
for
(
const
format
of
response
.
body
.
value
)
{
console
.
log
(
${
format
.
format
}
:
${
format
.
fileExtensions
.
join
(
", "
)
}
)
;
}
}
Key Types
// Text Translation
import
type
{
TranslatorCredential
,
TranslatorTokenCredential
,
}
from
"@azure-rest/ai-translation-text"
;
// Document Translation
import
type
{
DocumentTranslateParameters
,
StartTranslationDetails
,
TranslationStatus
,
}
from
"@azure-rest/ai-translation-document"
;
Best Practices
Auto-detect source
- Omit
language
parameter to auto-detect
Batch requests
- Translate multiple texts in one call for efficiency
Use SAS tokens
- For document translation, use time-limited SAS URLs
Handle errors
- Always check
isUnexpected(response)
before accessing body
Regional endpoints
- Use regional endpoints for lower latency
When to Use
This skill is applicable to execute the workflow or actions described in the overview.