<< All versions
Skill v1.0.0
currentAutomated scan100/100huytran1120/vietnam-agentic-skills/azure-ai-translation-ts
──Details
PublishedNovember 20, 2026 at 10:53 AM
Content Hashsha256:26c2aa0ae0ffa6b1...
Git SHAa7efb3065732
──Files
Files (1 file, 7.7 KB)
SKILL.md7.7 KBactive
SKILL.md · 301 lines · 7.7 KB
name: azure-ai-translation-ts description: "Text and document translation with REST-style clients." risk: critical source: community date_added: "2026-02-27" metadata: version: "1.0.0"
Azure Translation SDKs for TypeScript
Text and document translation with REST-style clients.
Installation
bash
# Text translationnpm install @azure-rest/ai-translation-text @azure/identity# Document translationnpm install @azure-rest/ai-translation-document @azure/identity
Environment Variables
bash
TRANSLATOR_ENDPOINT=https://api.cognitive.microsofttranslator.comTRANSLATOR_SUBSCRIPTION_KEY=<your-api-key>TRANSLATOR_REGION=<your-region> # e.g., westus, eastus
Text Translation Client
Authentication
typescript
import TextTranslationClient, { TranslatorCredential } from "@azure-rest/ai-translation-text";// API Key + Regionconst 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
typescript
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
typescript
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
typescript
const response = await client.path("/languages").get();if (isUnexpected(response)) {throw response.body.error;}// Translation languagesfor (const [code, lang] of Object.entries(response.body.translation || {})) {console.log(`${code}: ${lang.name} (${lang.nativeName})`);}
Transliterate
typescript
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
typescript
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
typescript
import DocumentTranslationClient from "@azure-rest/ai-translation-document";import { DefaultAzureCredential } from "@azure/identity";const endpoint = "https://<translator>.cognitiveservices.azure.com";// TokenCredentialconst client = DocumentTranslationClient(endpoint, new DefaultAzureCredential());// API Keyconst client2 = DocumentTranslationClient(endpoint, { key: "<api-key>" });
Single Document Translation
typescript
import DocumentTranslationClient from "@azure-rest/ai-translation-document";import { writeFile } from "node:fs/promises";const response = await client.path("/document:translate").post({queryParameters: {targetLanguage: "es",sourceLanguage: "en", // optional},contentType: "multipart/form-data",body: [{name: "document",body: "Hello, this is a test document.",filename: "test.txt",contentType: "text/plain",},],}).asNodeStream();if (response.status === "200") {await writeFile("translated.txt", response.body);}
Batch Document Translation
typescript
import { ContainerSASPermissions, BlobServiceClient } from "@azure/storage-blob";// Generate SAS URLs for source and target containersconst sourceSas = await sourceContainer.generateSasUrl({permissions: ContainerSASPermissions.parse("rl"),expiresOn: new Date(Date.now() + 24 * 60 * 60 * 1000),});const targetSas = await targetContainer.generateSasUrl({permissions: ContainerSASPermissions.parse("rwl"),expiresOn: new Date(Date.now() + 24 * 60 * 60 * 1000),});// Start batch translationconst response = await client.path("/document/batches").post({body: {inputs: [{source: { sourceUrl: sourceSas },targets: [{ targetUrl: targetSas, language: "fr" },],},],},});// Get operation ID from headerconst operationId = new URL(response.headers["operation-location"]).pathname.split("/").pop();
Get Translation Status
typescript
import { isUnexpected, paginate } from "@azure-rest/ai-translation-document";const statusResponse = await client.path("/document/batches/{id}", operationId).get();if (!isUnexpected(statusResponse)) {const status = statusResponse.body;console.log(`Status: ${status.status}`);console.log(`Total: ${status.summary.total}`);console.log(`Success: ${status.summary.success}`);}// List documents with paginationconst 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
typescript
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
typescript
// Text Translationimport type {TranslatorCredential,TranslatorTokenCredential,} from "@azure-rest/ai-translation-text";// Document Translationimport type {DocumentTranslateParameters,StartTranslationDetails,TranslationStatus,} from "@azure-rest/ai-translation-document";
Best Practices
- Auto-detect source - Omit
languageparameter 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.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
These fragments must match the installed Translator package/API version and the selected resource endpoint. Check response status and the presence/validity of operation-location before polling document operations; bound polling and handle failed/cancelled states. Text/documents and SAS URLs leave the local environment: authorize that transfer, use narrowly scoped short-lived SAS grants and keep them out of logs.