基于 AAS 仓库实践 Azure AI Translation TypeScript SDK：文本与文档翻译完整指南-港品优选

基于 AAS 仓库实践 Azure AI Translation TypeScript SDK：文本与文档翻译完整指南

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills

Azure AI Translation 提供基于 REST 风格的 TypeScript SDK，用于文本实时翻译与文档批量翻译。本指南以 AAS（agentic-awesome-skills）仓库中 azure-ai-translation-ts 技能文档为核心骨架，结合仓库目录结构、目录元数据与同类技能，完整讲解两种 SDK 的安装、认证、核心 API 调用（翻译、音译、语言检测、单文档与批量文档翻译、状态查询、格式查询）、关键类型与最佳实践。读完本文，你可以直接上手在 TypeScript 项目中集成 Azure 文本翻译与文档翻译能力，并能理解这套 REST 风格客户端（RLC）的底层调用范式与错误处理约定。

技能定位与仓库组织

在 AAS 仓库中，azure-ai-translation-ts被归类为cloud分类下的技能，风险等级为critical，来源为community，日期为 2026-02-27。其目录元数据记录了标签（azure、ai、translation、ts）与触发词（含text、document、rest、style、clients），用于 Agent 在检索时自动匹配任务。

该技能在仓库中存在两份镜像：

主技能目录：skills/azure-ai-translation-ts/SKILL.md
Claude 插件分发目录：plugins/agentic-awesome-skills-claude/skills/azure-ai-translation-ts/SKILL.md

此外，仓库还收录了同主题的 Python 变体 skills/azure-ai-translation-text-py/SKILL.md 与 skills/azure-ai-translation-document-py/SKILL.md，以及 Java 等语言的 Azure AI 技能（如 skills/azure-ai-vision-imageanalysis-java），说明该主题覆盖多语言 SDK，TypeScript 版本专注于"REST 风格客户端"的使用方式。

本技能对应 Azure 官方两个 npm 包，二者职责不同：

包名	职责
`@azure-rest/ai-translation-text`	文本翻译、音译、语言检测等实时能力
`@azure-rest/ai-translation-document`	文档批量翻译，保留源文件格式

安装与环境变量

安装依赖

按需安装对应 SDK 包，文本与文档翻译是相互独立的两个包：

# 文本翻译 npm install @azure-rest/ai-translation-text @azure/identity # 文档翻译 npm install @azure-rest/ai-translation-document @azure/identity

其中@azure/identity提供DefaultAzureCredential等统一认证能力，文档翻译的TokenCredential认证方式依赖它；@azure/storage-blob（批量文档翻译生成 SAS URL 时需要）可按需单独安装。

环境变量

文本翻译客户端通过环境变量注入端点、密钥与区域：

TRANSLATOR_ENDPOINT=https://api.cognitive.microsofttranslator.com TRANSLATOR_SUBSCRIPTION_KEY=<your-api-key> TRANSLATOR_REGION=<your-region> # e.g., westus, eastus

参数说明：

TRANSLATOR_ENDPOINT：文本翻译服务端点，全局端点为https://api.cognitive.microsofttranslator.com；若使用区域化资源，可指向形如https://<translator>.cognitiveservices.azure.com的区域端点；
TRANSLATOR_SUBSCRIPTION_KEY：Azure 门户中 Translator 资源的密钥；
TRANSLATOR_REGION：创建资源时指定的区域（如westus、eastus），API Key 认证模式下必须提供。

从源码结构看，客户端采用工厂函数形态，直接调用包导出的工厂即可创建实例，无需new，这是 Azure REST 风格客户端（Rest Level Client，RLC）的通用约定。

文本翻译客户端

认证：API Key + Region

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);

要点：

TranslatorCredential由key与region两个字段组成；
传入完整端点时会使用该端点；只传 credential 时客户端自动使用全局端点，便于简化本地开发配置；
包还导出TranslatorTokenCredential（见下文"关键类型"），用于以TokenCredential方式接入@azure/identity的认证链路，如托管身份。

翻译文本（基础）

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}`); } }

参数语义：

inputs：一次可提交多条待翻译文本，每条内targets可声明多个目标语言，一次调用即可得到多语言结果，这是"批量请求"效率优势的体现；
language：源语言，可省略，省略时服务端自动检测；
调用路径：/translate（POST），对应服务端文本翻译 API；
错误处理：RLC 客户端不抛异常，而是通过isUnexpected(response)判断 HTTP 状态码是否在 2xx 之外，失败时response.body.error携带错误详情。这是使用本 SDK 时必须养成的习惯。

翻译文本（带选项）

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 }, ], }, ], }, });

选项说明：

textType："Plain"表示纯文本，"Html"表示按 HTML 处理（保留标签结构、不翻译标签名）；
profanityAction（目标语言级）："NoAction"不处理不雅内容，"Marked"标记不雅内容（默认Marked），"Deleted"直接删除；
tone：面向 LLM 场景的语域选项，示例中使用"formal"，可用于让译文更正式。

获取支持的语言

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})`); }

/languages返回服务支持的语言集，响应体包含translation、transliteration、dictionary等多个分组，本示例遍历translation分组并输出语言代码、英文名（name）与本地名（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ì } }

音译把一种书写系统映射到另一种（如简体中文汉字 → 拉丁字母拼音）。参数含义：

language：目标语言代码（如zh-Hans）；
fromScript：源书写系统（Hans简体中文）；
toScript：目标书写系统（Latn拉丁字母）。

注意音译参数放在queryParameters中，与翻译时放在 body 内不同——这是各 API 的既定契约，编码时需区分。

语言检测

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}`); } }

/detect返回每段文本的检测语言language与置信度score（0～1，越接近 1 越可信）。可用于：先检测再翻译的显式流程、多语言输入的自动路由、以及翻译结果的前置校验。

文档翻译客户端

认证：TokenCredential 与 API Key

import DocumentTranslationClient from "@azure-rest/ai-translation-document"; import { DefaultAzureCredential } from "@azure/identity"; const endpoint = "https://<translator>.cognitiveservices.azure.com"; // TokenCredential const client = DocumentTranslationClient(endpoint, new DefaultAzureCredential()); // API Key const client2 = DocumentTranslationClient(endpoint, { key: "<api-key>" });

与文本翻译不同，文档翻译客户端必须提供资源端点（https://<translator>.cognitiveservices.azure.com），并支持两种认证：

TokenCredential：传入@azure/identity的DefaultAzureCredential，适用于托管身份、Azure CLI 登录等无需硬编码密钥的生产场景；
API Key：直接传{ key: "<api-key>" }对象，适合快速验证。

单文档翻译

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); }

单文档翻译的要点：

路径为/document:translate，以multipart/form-data提交；
targetLanguage必填，sourceLanguage可选（省略时自动检测）；
body 为表单字段数组，name为字段名（此处为document），body为文件内容，filename为文件名，contentType为文件 MIME 类型；
调用链末端使用.asNodeStream()，使响应以 Node.js 流形式返回，便于大文件直接writeFile落盘；
状态判断这里使用response.status === "200"（文本客户端用isUnexpected，二者风格等价，可根据偏好选择）。

批量文档翻译（SAS URL + 异步任务）

批量翻译以"任务（batch）"为单位异步执行，输入输出均为 Azure Blob 容器，需要生成带时限的 SAS URL：

import { ContainerSASPermissions, BlobServiceClient } from "@azure/storage-blob"; // Generate SAS URLs for source and target containers const 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 translation const response = await client.path("/document/batches").post({ body: { inputs: [ { source: { sourceUrl: sourceSas }, targets: [ { targetUrl: targetSas, language: "fr" }, ], }, ], }, }); // Get operation ID from header const operationId = new URL(response.headers["operation-location"]) .pathname.split("/").pop();

流程拆解：

生成 SAS：源容器只需读取权限（"rl"），目标容器需要读写列权限（"rwl"），expiresOn设为 24 小时后，遵循最小权限与短期有效原则；
提交任务：POST/document/batches，inputs中source.sourceUrl指向源容器，targets声明目标容器与语言，可声明多个目标语言形成多份译稿；
获取任务 ID：响应头operation-location指向任务状态资源，从 URL pathname 中取出末尾段即为operationId，供后续轮询使用。

查询翻译状态与分页列举

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 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/document/batches/{id}返回status（如NotStarted、Running、Succeeded、Failed）与summary（total、success、failed等统计），实现任务级进度监控；
文档列表：GET/document/batches/{id}/documents返回该任务下每个文档的处理状态；
分页：RLC 客户端默认返回第一页，包提供的paginate(client, response)辅助函数自动跟踪下一页标记，配合for await遍历全部结果——这是本 SDK 处理大结果集的标准姿势。

查询支持的文档格式

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(", ")}`); } }

/document/formats返回文档翻译支持的文件格式清单，每项含格式名与fileExtensions（如.docx、.pdf、.xlsx、.pptx等）。在批量任务前调用此接口校验源文件格式，可避免任务因不支持格式而失败。

关键类型速查

SDK 导出的核心类型如下，供类型注解与自定义封装时引用：

// 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";

TranslatorCredential：API Key + 区域型凭证；
TranslatorTokenCredential：TokenCredential 型凭证；
DocumentTranslateParameters：单文档翻译请求参数类型；
StartTranslationDetails：批量任务提交体类型；
TranslationStatus：任务状态响应类型。

在封装通用翻译服务层时，建议直接以这些类型为输入输出契约，保持与 SDK 演进同步。

最佳实践

综合原文档与 SDK 特性，推荐遵循以下实践：

源语言自动检测：省略language参数交由服务自动检测，减少人工指定错误，特别适合多语言用户输入；
批量请求：多条文本合并到一次inputs调用中，多目标语言也一次性声明，显著降低请求数与延迟；
使用 SAS 令牌：文档翻译的输入输出容器使用限时SAS URL，且按需最小化权限（源容器只读、目标容器读写），避免长期有效凭据泄露风险；
统一错误处理：访问response.body前始终用isUnexpected(response)校验（或等价的状态码判断），这是 RLC 客户端的安全访问约定；
区域端点：面向生产环境时使用区域化端点（https://<translator>.cognitiveservices.azure.com）以降低延迟、提升就近可用性。

适用边界与限制

适用场景：本技能用于在 TypeScript/Node.js 应用中接入 Azure AI 文本翻译与文档翻译的工作流，涵盖实时文本翻译、音译、语言检测、单文档与批量文档翻译、任务状态监控与格式校验；
不适用场景：当任务明显超出上述范围（如需要自定义翻译模型训练、离线翻译、其他云厂商翻译服务）时，不应强行套用本技能；
验证责任：技能输出不能替代环境特定的验证、测试或专家评审——生产环境务必用真实资源做端到端验证；
澄清优先：若所需输入、权限、安全边界或成功标准缺失，应先澄清再执行，避免在凭据或范围不明的情况下发起翻译任务。

企业官网建设流程全解析