Translator Document Translation and glossary preflight
For Azure AI Translator Document Translation (async batch and sync single-file),
glossary validation and Blob storage authorization. Do not use for Microsoft
Foundry project connections (microsoft-foundry).
Workflow
Confirm mode (
asyncbatch vssyncsingle-file vs Text API), tier (S1orC2-C4/D3required for Document Translation;F0is Text API only) and auth (Managed Identity vs SAS). Never ask for keys/SAS or echo document/glossary text.Check
node --version(Node.js 22+). If missing/older, follow validation without Node. Otherwise run the local validator:node "<skill-directory>/scripts/validate-document-translation.mjs" --mode async --dir "<source-folder>" --glossary "<glossary.tsv>" --target-count 2& node "<skill-directory>\scripts\validate-document-translation.mjs" --mode async --dir "<source-folder>" --glossary "<glossary.tsv>" --target-count 2Or pass
--document "<file>". Bash and PowerShell launchers use exit codes0report/--help,1file error,2usage error,3Node 22+ missing.Verify documented limits and authorization rules:
| Area | Public contract |
|---|---|
| Async batch | Document <= 40 MB (preview image .jpeg/.png/.bmp/.webp <= 5 MB on 2025-12-01-preview), <= 1,000 files, <= 250 MB batch total, <= 10 target languages, glossary <= 10 MB. Secured documents (password-encrypted or copy-restricted) can't be translated. |
| Sync single-file | Document <= 10 MB, 1 file, 1 target language, glossary <= 1 MB. Formats: txt, tsv/tab, csv, html/htm, mhtml/mht, docx, xlsx, pptx, msg, xlf. |
| Formats | GET /translator/document/formats (?type=glossary) is authoritative; validator list misses only warn. |
| Text API | <= 50,000 chars/request across all target languages, <= 1,000 elements; sliding hourly quota (F0 2M/hr ≈ 33.3K/min, S1 40M/hr, Custom 3,600 chars/sec/model). |
| Glossary | .tsv/.tab/.csv or .xlf. Partial-sentence matching is case-sensitive; full-sentence matching is case-insensitive. |
| Endpoint | Requires custom domain https://<custom>.cognitiveservices.azure.com. |
| Managed Identity | Translator must be in a geographic region (not Global) with a system-assigned identity. Assign Storage Blob Data Contributor at storage scope, omit SAS query strings, and on firewalled storage allow trusted Azure services plus a Microsoft.CognitiveServices/accounts resource-instance rule (up to 5 min to propagate). |
| SAS fallback | Source rl, target wl, glossary rl, valid expiry. |
- For permitted live checks, inspect
az cognitiveservices account show(location,sku.name,properties.customSubdomainName,identity.type) and storage RBAC/firewall without listing keys.
Report and sources
Separate observed defects (row numbers, byte sizes, HTTP error codes), bounded interpretation, and unknown items. Passing local validation does not guarantee server translation accuracy.