Azure 文档翻译 Python 技能
帮助 Python 开发者批量翻译 Azure Blob Storage 中的文档，同时保留原始格式。
文档推荐 DefaultAzureCredential、生产环境限制凭据链，并要求 SAS 最小权限；同时披露了源/目标 Blob URL 和 API key 的配置方式。扣分原因是未明确翻译敏感文档的数据处理、跨境/第三方传输、用户确认、SAS 泄露防护或回滚策略，且取消操作示例没有说明影响范围。
主路径覆盖批量、单文档、状态和异步用法，且引用文件指出应核对当前 API。扣分原因是静态证据显示关键示例缺少完整上下文（如部分 import、endpoint 未定义），主文档错误地展示 DocumentTranslationClient.get_supported_languages()，虽在引用文件中纠正；也缺少明确异常、重试、超时和输入校验模式。
触发词、Python SDK、批量文档翻译、格式保留和主要格式范围较清楚。扣分原因是未充分说明不支持或不适合的场景、区域/网络要求、成本和配额；核心服务依赖 Azure，面向中国用户的可达性与数据驻留未说明，中文语言支持仅能从通用语言发现示例推断。
具有 YAML 元数据、安装命令、环境变量、认证生命周期、分层引用文件、示例、格式和存储要求，并声明 MIT 许可及版本 1.0.0。扣分原因是缺少变更记录、SDK 版本约束、维护责任/更新路径和系统化 FAQ；部分高级场景只给出简短代码，且主文档与引用文档存在内容不一致。
能够直接指导常见的批量、多语言、单文档翻译、状态查询和词汇表代码，核心任务价值明确。扣分原因是若直接复制，若干示例需要补齐 imports、变量和环境配置；错误的语言发现示例可能导致返工，生产级错误处理、结果校验和恢复流程不完整。
技能文件包含可审计的代码、环境变量、API 名称和引用文件；仓库还提供 CI、评估工作流和测试 harness。扣分原因是给定材料没有显示该技能的专属测试套件、真实执行结果或第三方交叉验证；CI 主要证明通用 harness/评估机制存在，不能静态证明本技能关键路径。
- 不要直接复制所有示例投入生产：先修正语言发现 API，并补齐 imports、endpoint、变量和依赖。
- 文档会把源文件和翻译结果通过 Azure Blob/SAS 传输；上线前确认敏感数据、区域、网络可达性、SAS 有效期/权限和组织合规要求。
- 取消任务、写入目标容器和多语言批处理都可能产生外部副作用；实施前应确认目标范围，并增加异常、轮询超时、部分失败和恢复处理。
它能做什么 & 适用场景
该技能面向 Azure AI Document Translation Python SDK，覆盖批量文档翻译和单文档翻译。它提供 DOCX、PDF、XLSX、PPTX 等格式的示例，并说明如何配置 Blob Storage 容器、身份验证和 SAS 权限。技能还涵盖多目标语言、翻译状态查询、文档级错误、取消任务、术语表、支持格式与语言查询，以及同步和异步客户端。它适合已经使用 Azure AI Translator 和 Azure Blob Storage 的 Python 项目。
指导开发者安装 azure-ai-translation-document，配置文档翻译终结点、源容器和目标容器 URL，并使用 DocumentTranslationClient 或 SingleDocumentTranslationClient 提交翻译任务。它展示如何翻译 Word、PDF、Excel、PowerPoint、HTML、TXT、RTF、CSV、TSV、JSON、XML、XLIFF、XLF 和 MHTML 等格式，等待批处理完成，读取任务及单个文档状态，处理失败文档，取消任务，使用术语表，并查询支持的格式和语言。
- 需要将 Azure Blob Storage 中的一批 DOCX、PDF 或 Excel 文件翻译成一种或多种目标语言的 Python 开发者。
- 需要保持文档格式并批量处理企业资料的应用团队。
- 需要对单个本地 DOCX 文件执行翻译并保存译文的开发者。
- 需要监控长时间运行的翻译任务、统计成功与失败文档数量的工程团队。
- 需要使用领域术语表提高批量翻译一致性的本地化团队。
优缺点一览
- 覆盖批量翻译、单文档翻译、多目标语言、术语表和任务管理。
- 明确建议使用 DefaultAzureCredential，并说明本地开发与生产环境的配置方式。
- 同时提供同步和异步客户端示例。
- 说明源端与目标端 Blob Storage 的 SAS 权限要求。
- 必须准备 Azure AI Document Translation 终结点以及 Azure Blob Storage 源、目标容器。
- 批量翻译依赖源容器和目标容器的 SAS URL，配置与权限管理会增加部署工作。
- 源材料没有提供定价、配额或服务限制信息。
- 引用的 references/capabilities.md 和 references/non-hero-scenarios.md 内容未提供，无法评估其中的额外覆盖范围。
如何安装
先将集合安装到所用编码代理：运行 npx skills add microsoft/skills，在向导中选择此技能；集合会安装到所选代理的技能目录。然后在 Python 环境中运行 pip install azure-ai-translation-document。源材料未说明具体的 Python 版本要求。
如何使用
向编码代理发出包含“document translation”“batch translation”“translate documents”或“DocumentTranslationClient”的请求，例如：Use the azure-ai-translation-document-py skill to create an async batch translation job from Azure Blob Storage to Spanish and French. 代码中设置 AZURE_DOCUMENT_TRANSLATION_ENDPOINT、AZURE_SOURCE_CONTAINER_URL 和 AZURE_TARGET_CONTAINER_URL，优先使用 DefaultAzureCredential，并用客户端上下文管理器提交任务、等待轮询结果和检查文档状态。