Azure AI Translation Ts

1---
2name: azure-ai-translation-ts
3description: Build translation applications using Azure Translation SDKs for JavaScript (@azure-rest/ai-translation-text, @azure-rest/ai-translation-document). Use when implementing text translation, transliteration, language detection, or batch document translation.
4package: "@azure-rest/ai-translation-text, @azure-rest/ai-translation-document"
5---
6 
7# Azure Translation SDKs for TypeScript
8 
9Text and document translation with REST-style clients.
10 
11## Installation
12 
13```bash
14# Text translation
15npm install @azure-rest/ai-translation-text @azure/identity
16 
17# Document translation
18npm install @azure-rest/ai-translation-document @azure/identity
19```
20 
21## Environment Variables
22 
23```bash
24TRANSLATOR_ENDPOINT=https://api.cognitive.microsofttranslator.com
25TRANSLATOR_SUBSCRIPTION_KEY=<your-api-key>
26TRANSLATOR_REGION=<your-region>  # e.g., westus, eastus
27```
28 
29## Text Translation Client
30 
31### Authentication
32 
33```typescript
34import TextTranslationClient, { TranslatorCredential } from "@azure-rest/ai-translation-text";
35 
36// API Key + Region
37const credential: TranslatorCredential = {
38  key: process.env.TRANSLATOR_SUBSCRIPTION_KEY!,
39  region: process.env.TRANSLATOR_REGION!,
40};
41const client = TextTranslationClient(process.env.TRANSLATOR_ENDPOINT!, credential);
42 
43// Or just credential (uses global endpoint)
44const client2 = TextTranslationClient(credential);
45```
46 
47### Translate Text
48 
49```typescript
50import TextTranslationClient, { isUnexpected } from "@azure-rest/ai-translation-text";
51 
52const response = await client.path("/translate").post({
53  body: {
54    inputs: [
55      {
56        text: "Hello, how are you?",
57        language: "en",  // source (optional, auto-detect)
58        targets: [
59          { language: "es" },
60          { language: "fr" },
61        ],
62      },
63    ],
64  },
65});
66 
67if (isUnexpected(response)) {
68  throw response.body.error;
69}
70 
71for (const result of response.body.value) {
72  for (const translation of result.translations) {
73    console.log(`${translation.language}: ${translation.text}`);
74  }
75}
76```
77 
78### Translate with Options
79 
80```typescript
81const response = await client.path("/translate").post({
82  body: {
83    inputs: [
84      {
85        text: "Hello world",
86        language: "en",
87        textType: "Plain",  // or "Html"
88        targets: [
89          {
90            language: "de",
91            profanityAction: "NoAction",  // "Marked" | "Deleted"
92            tone: "formal",  // LLM-specific
93          },
94        ],
95      },
96    ],
97  },
98});
99```
100 
101### Get Supported Languages
102 
103```typescript
104const response = await client.path("/languages").get();
105 
106if (isUnexpected(response)) {
107  throw response.body.error;
108}
109 
110// Translation languages
111for (const [code, lang] of Object.entries(response.body.translation || {})) {
112  console.log(`${code}: ${lang.name} (${lang.nativeName})`);
113}
114```
115 
116### Transliterate
117 
118```typescript
119const response = await client.path("/transliterate").post({
120  body: { inputs: [{ text: "这是个测试" }] },
121  queryParameters: {
122    language: "zh-Hans",
123    fromScript: "Hans",
124    toScript: "Latn",
125  },
126});
127 
128if (!isUnexpected(response)) {
129  for (const t of response.body.value) {
130    console.log(`${t.script}: ${t.text}`);  // Latn: zhè shì gè cè shì
131  }
132}
133```
134 
135### Detect Language
136 
137```typescript
138const response = await client.path("/detect").post({
139  body: { inputs: [{ text: "Bonjour le monde" }] },
140});
141 
142if (!isUnexpected(response)) {
143  for (const result of response.body.value) {
144    console.log(`Language: ${result.language}, Score: ${result.score}`);
145  }
146}
147```
148 
149## Document Translation Client
150 
151### Authentication
152 
153```typescript
154import DocumentTranslationClient from "@azure-rest/ai-translation-document";
155import { DefaultAzureCredential } from "@azure/identity";
156 
157const endpoint = "https://<translator>.cognitiveservices.azure.com";
158 
159// TokenCredential
160const client = DocumentTranslationClient(endpoint, new DefaultAzureCredential());
161 
162// API Key
163const client2 = DocumentTranslationClient(endpoint, { key: "<api-key>" });
164```
165 
166### Single Document Translation
167 
168```typescript
169import DocumentTranslationClient from "@azure-rest/ai-translation-document";
170import { writeFile } from "node:fs/promises";
171 
172const response = await client.path("/document:translate").post({
173  queryParameters: {
174    targetLanguage: "es",
175    sourceLanguage: "en",  // optional
176  },
177  contentType: "multipart/form-data",
178  body: [
179    {
180      name: "document",
181      body: "Hello, this is a test document.",
182      filename: "test.txt",
183      contentType: "text/plain",
184    },
185  ],
186}).asNodeStream();
187 
188if (response.status === "200") {
189  await writeFile("translated.txt", response.body);
190}
191```
192 
193### Batch Document Translation
194 
195```typescript
196import { ContainerSASPermissions, BlobServiceClient } from "@azure/storage-blob";
197 
198// Generate SAS URLs for source and target containers
199const sourceSas = await sourceContainer.generateSasUrl({
200  permissions: ContainerSASPermissions.parse("rl"),
201  expiresOn: new Date(Date.now() + 24 * 60 * 60 * 1000),
202});
203 
204const targetSas = await targetContainer.generateSasUrl({
205  permissions: ContainerSASPermissions.parse("rwl"),
206  expiresOn: new Date(Date.now() + 24 * 60 * 60 * 1000),
207});
208 
209// Start batch translation
210const response = await client.path("/document/batches").post({
211  body: {
212    inputs: [
213      {
214        source: { sourceUrl: sourceSas },
215        targets: [
216          { targetUrl: targetSas, language: "fr" },
217        ],
218      },
219    ],
220  },
221});
222 
223// Get operation ID from header
224const operationId = new URL(response.headers["operation-location"])
225  .pathname.split("/").pop();
226```
227 
228### Get Translation Status
229 
230```typescript
231import { isUnexpected, paginate } from "@azure-rest/ai-translation-document";
232 
233const statusResponse = await client.path("/document/batches/{id}", operationId).get();
234 
235if (!isUnexpected(statusResponse)) {
236  const status = statusResponse.body;
237  console.log(`Status: ${status.status}`);
238  console.log(`Total: ${status.summary.total}`);
239  console.log(`Success: ${status.summary.success}`);
240}
241 
242// List documents with pagination
243const docsResponse = await client.path("/document/batches/{id}/documents", operationId).get();
244const documents = paginate(client, docsResponse);
245 
246for await (const doc of documents) {
247  console.log(`${doc.id}: ${doc.status}`);
248}
249```
250 
251### Get Supported Formats
252 
253```typescript
254const response = await client.path("/document/formats").get();
255 
256if (!isUnexpected(response)) {
257  for (const format of response.body.value) {
258    console.log(`${format.format}: ${format.fileExtensions.join(", ")}`);
259  }
260}
261```
262 
263## Key Types
264 
265```typescript
266// Text Translation
267import type {
268  TranslatorCredential,
269  TranslatorTokenCredential,
270} from "@azure-rest/ai-translation-text";
271 
272// Document Translation
273import type {
274  DocumentTranslateParameters,
275  StartTranslationDetails,
276  TranslationStatus,
277} from "@azure-rest/ai-translation-document";
278```
279 
280## Best Practices
281 
2821. **Auto-detect source** - Omit `language` parameter to auto-detect
2832. **Batch requests** - Translate multiple texts in one call for efficiency
2843. **Use SAS tokens** - For document translation, use time-limited SAS URLs
2854. **Handle errors** - Always check `isUnexpected(response)` before accessing body
2865. **Regional endpoints** - Use regional endpoints for lower latency
287