用途
本技能围绕 Azure AI 翻译在 TypeScript 中的使用,说明如何通过 REST 风格客户端完成文本翻译与文档翻译两类任务。它提供安装命令、环境变量配置、客户端初始化以及各主要接口的调用示例。
主要能力
文本翻译(@azure-rest/ai-translation-text):
- 翻译文本,可指定源语言(省略则自动检测),并在一次请求中翻译到多个目标语言;
- 翻译选项:textType 可选 Plain 或 Html,targets 中可设置 profanityAction(NoAction、Marked、Deleted)与 tone(示例标注为 LLM 相关);
- 获取支持的语言列表(translation 等);
- 音译:指定 language、fromScript、toScript 进行脚本转换;
- 语言检测:返回检测到的语言及置信分数。
文档翻译(@azure-rest/ai-translation-document):
- 单文档翻译:以 multipart/form-data 提交文件内容,按流式响应保存译文;
- 批量文档翻译:通过源与目标容器的 SAS URL 发起批次任务,并从 operation-location 响应头获取 operationId;
- 查询批次状态与汇总(总数、成功数等);
- 分页列出批次内文档及其状态;
- 查询支持的文档格式与文件扩展名。
使用方式
安装:
npm install @azure-rest/ai-translation-text @azure/identity
npm install @azure-rest/ai-translation-document @azure/identity
环境变量示例:
TRANSLATOR_ENDPOINT=https://api.cognitive.microsofttranslator.com
TRANSLATOR_SUBSCRIPTION_KEY=<your-api-key>
TRANSLATOR_REGION=<your-region>
文本翻译客户端支持两种初始化:传入端点与 TranslatorCredential(key + region),或仅传 credential 使用全局端点。文档翻译客户端支持 TokenCredential(如 DefaultAzureCredential)或 API Key 两种认证,端点为 https://<translator>.cognitiveservices.azure.com 形式。
调用时通过 client.path("/translate").post(...)、client.path("/languages").get()、client.path("/transliterate").post(...)、client.path("/detect").post(...)、client.path("/document:translate").post(...)、client.path("/document/batches").post(...)、client.path("/document/batches/{id}", operationId).get() 等路径方法组织请求。批量文档翻译需先用 @azure/storage-blob 的 generateSasUrl 为源容器(rl 权限)和目标容器(rwl 权限)生成带过期时间的 SAS URL。
适用场景
需要在 TypeScript/Node.js 应用中集成多语言文本翻译、语言检测、音译,或对单个文档、Blob 存储中的批量文档进行翻译并跟踪任务状态的开发场景。
限制与注意事项
- 示例仅展示调用方式,实际可用语言、文档格式、配额与计费取决于 Azure 翻译服务配置,资料未提供相关细节。
- 文档翻译依赖 Azure Blob 存储及 SAS 权限配置;批量任务为异步,需轮询状态接口。
- 每次请求后应先以 isUnexpected(response) 判断异常再访问 body。
- 资料建议使用区域端点以降低延迟、批量请求提升效率、省略源语言实现自动检测。
- 技能说明指出其输出不能替代针对具体环境的验证、测试或专家审查;当输入、权限、安全边界或成功标准缺失时应停止并请求澄清。
- 该技能是否收费、支持的平台范围等资料暂未提供。