Azure 翻译 TypeScript 技能
帮助 TypeScript 开发者快速构建文本、转写、语言检测和文档翻译应用。
文档说明了API密钥、区域、托管身份和有限时效SAS URL，并建议使用只读或读写权限；因此主要数据流和认证方式可见。扣分原因是未要求用户确认外部翻译、云端上传或目标容器写入，也未说明敏感文本、密钥日志、SAS泄露、撤销和失败回滚处理。
包含文本翻译、语言检测、转写、文档批处理、状态查询和错误判断示例，且建议检查isUnexpected。扣分原因是技能文件没有可执行测试、版本锁定、输入边界、重试/超时、HTTP异常反馈或对响应头缺失等异常的处理；静态评估上限也限制了得分。
名称和描述明确面向TypeScript/JavaScript Azure Translation应用，覆盖文本、转写、检测及单文档/批量文档翻译。扣分原因是未明确不适用场景、输入输出契约、地区可达性、成本限制或中文用户环境；功能依赖Azure服务，文档未讨论中国大陆网络和区域端点可用性。
有前置安装、环境变量、认证分支、按主题组织的代码示例、关键类型和最佳实践；MIT许可证、作者和1.0.0版本元数据明确。扣分原因是没有变更日志、维护责任和更新路径、兼容的SDK版本、FAQ、故障排查或已知限制；安装说明也未覆盖文档批处理所需的存储依赖。
示例覆盖主要翻译任务，包含可直接改用的客户端调用、错误检查、分页和SAS权限设置，能够支持核心开发工作。扣分原因是未提供完整可运行项目、配置前提、验证输出或替代方案比较，部分片段依赖未展示的客户端上下文；静态评估不授予超过7分。
技能包含具体包名、环境变量、API路径、代码模式和错误检查，仓库还提供通用评估工作流与测试工具。扣分原因是给定材料未显示该技能对应的提交测试、真实执行结果、第三方交叉验证或版本化API证据，因此只能给有限静态可审计分数。
- 不要将订阅密钥或翻译文本写入日志；应使用密钥保管机制并确认数据驻留、合规和第三方处理要求。
- 批量文档示例会通过SAS URL授予源容器读取和目标容器读写权限；应限制权限、有效期和网络范围，并在调用前确认上传及写入影响。
- 示例未说明Azure端点在中国大陆网络中的可达性、区域服务差异、配额、费用和API版本兼容性。
- 应补充失败重试、超时、取消、缺失operation-location、部分成功和输出文件回滚处理。
它能做什么 & 适用场景
该技能为 Azure Translation 的 TypeScript REST 风格客户端提供可直接参考的实现模式。它覆盖文本翻译、转写、语言检测、支持语言查询，以及单文档和批量文档翻译。示例同时展示 API 密钥、区域凭据和 Azure 身份凭据的使用方式。适合正在使用 Azure Translator 并希望让编码代理生成符合 SDK 模式代码的 TypeScript 项目。
安装并配置 Azure Translation TypeScript 包，读取 Translator 端点、订阅密钥和区域等环境变量，创建文本或文档翻译客户端，调用 /translate、/languages、/transliterate、/detect、/document:translate、/document/batches 和相关状态及格式接口，检查 isUnexpected 响应，并输出翻译文本、语言置信度、批处理状态、文档状态或支持的文件格式。批量文档翻译还会使用 Azure Blob Storage 容器 SAS URL，并从响应头提取操作 ID。
- TypeScript 开发者需要把英语文本翻译成西班牙语、法语或其他目标语言时。
- 应用需要在用户输入语言未知时自动检测源语言时。
- 需要在不同文字系统之间进行转写，例如将简体中文汉字转为拉丁字母时。
- 团队需要通过 Azure 身份凭据或 API 密钥实现文档翻译时。
- 后端需要使用 Blob Storage SAS URL 启动并跟踪批量文档翻译任务时。
优缺点一览
- 覆盖文本翻译、转写、语言检测和文档翻译等明确场景。
- 提供 API 密钥、区域凭据、DefaultAzureCredential 和托管身份示例。
- 包含错误检查、分页、SAS URL 和批处理状态跟踪模式。
- 示例直接对应 Azure REST 客户端包，便于生成 TypeScript 代码。
- 必须配置 Azure Translator 端点及凭据，批量文档翻译还需要 Blob Storage SAS URL。
- 源码只提供 SDK 使用模式，没有说明价格、配额或部署架构。
- 未提供该单项技能独立测试结果或完整项目模板。
如何安装
在项目中运行 npx skills add microsoft/skills，并在安装向导中选择 azure-ai-translation-ts。该技能的 SDK 依赖包括 @azure-rest/ai-translation-text、@azure-rest/ai-translation-document、@azure/identity 和批量文档示例使用的 @azure/storage-blob。具体依赖应按使用的功能安装：文本翻译使用 npm install @azure-rest/ai-translation-text @azure/identity；文档翻译使用 npm install @azure-rest/ai-translation-document @azure/identity。
如何使用
将技能安装到所选编码代理的技能目录后，可在 TypeScript 翻译任务中触发它，例如："使用 Azure Translation TypeScript SDK 实现文本翻译、语言检测和批量文档翻译，并处理 isUnexpected 错误。" 配置 TRANSLATOR_ENDPOINT、TRANSLATOR_SUBSCRIPTION_KEY、TRANSLATOR_REGION；使用 DefaultAzureCredential 时还需设置 AZURE_TOKEN_CREDENTIALS。随后按示例创建客户端、调用对应接口，并检查响应状态。