feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Add /ultraresearch-local for structured research combining local codebase analysis with external knowledge via parallel agent swarms. Produces research briefs with triangulation, confidence ratings, and source quality assessment. New command: /ultraresearch-local with modes --quick, --local, --external, --fg. New agents: research-orchestrator (opus), docs-researcher, community-researcher, security-researcher, contrarian-researcher, gemini-bridge (all sonnet). New template: research-brief-template.md. Integration: --research flag in /ultraplan-local accepts pre-built research briefs (up to 3), enriches the interview and exploration phases. Planning orchestrator cross-references brief findings during synthesis. Design principle: Context Engineering — right information to right agent at right time. Research briefs are structured artifacts in the pipeline: ultraresearch → brief → ultraplan --research → plan → ultraexecute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-08 08:58:35 +02:00 · 2026-04-08 08:58:35 +02:00 · baa2d0220b
commit baa2d0220b
488 changed files with 213221 additions and 0 deletions
--- a/skills/ms-ai-engineering/references/azure-ai-services/translator-document-translation.md
+++ b/skills/ms-ai-engineering/references/azure-ai-services/translator-document-translation.md
@ -0,0 +1,389 @@
+# Translator Service - Document Translation and Multi-language Support
+
+**Last updated:** 2026-02
+**Status:** GA (General Availability) + Preview features
+**Category:** Azure AI Services (Foundry Tools)
+
+---
+
+## Introduksjon
+
+Azure Translator er en sky-basert neural maskinoversettelsestjeneste som tilbyr både tekst- og dokumentoversettelse på tvers av over 135 språk og dialekter. Tjenesten kombinerer sanntids tekstoversettelse med avansert dokumentoversettelse som bevarer opprinnelig formatering, layout og struktur.
+
+Document Translation-funksjonen støtter to arbeidsmåter: asynkron batch-oversettelse for store volumer og komplekse dokumenter, samt synkron single-file-oversettelse for raske enkeltdokumenter. Begge metodene bygger på samme neural machine translation (NMT)-teknologi som brukes i tusenvis av Microsoft-produkter og -tjenester globalt.
+
+En særlig nyhet (desember 2025) er støtte for bildefilformater i batch-oversettelse — tjenesten kan nå oversette tekst inni bilder (.jpeg, .png, .bmp, .webp) samtidig som den beholder originalens design og layout. Dette eliminerer behovet for forprosessering av bilder til PDF før oversettelse.
+
+## Kjernekomponenter / Nøkkelegenskaper
+
+### Oversettelsesmodi
+
+| Modus | Beskrivelse | Krav | Bruksområde |
+|-------|-------------|------|-------------|
+| **Asynchronous Batch** | Oversetter flere dokumenter og store filer asynkront | Azure Blob Storage (source + target containers) | Bulk-oversettelse, komplekse dokumenter, arkivering |
+| **Synchronous Single-file** | Oversetter én fil og returnerer umiddelbart | Kun Translator-ressurs | Raske oversettelser, sanntidsscenarier |
+
+### Støttede dokumentformater (Batch)
+
+**Produksjonsklare formater:**
+- **Office:** `.docx`, `.xlsx`, `.pptx`, `.msg` (Outlook)
+- **PDF:** `.pdf` (bruker OCR for scannede dokumenter)
+- **Web/Data:** `.html`, `.htm`, `.csv`, `.tsv`, `.mhtml`
+- **Markup:** `.md`, `.xlf` (XLIFF — translation standard)
+- **Open Source:** `.odt`, `.ods`, `.odp`
+- **Bilder (2025-12-01-preview):** `.jpeg`, `.png`, `.bmp`, `.webp` 🆕
+
+**Legacy-konvertering:**
+`.doc`, `.xls`, `.ppt` konverteres automatisk til moderne Office-formater (`.docx`, `.xlsx`, `.pptx`) ved oversettelse.
+
+### Nøkkelfunksjoner
+
+| Funksjon | Batch | Sync | Beskrivelse |
+|----------|-------|------|-------------|
+| **Multi-file translation** | ✅ | ❌ | Oversett hundrevis av filer i én operasjon |
+| **Large file support** | ✅ | ❌ | Ingen praktisk størrelsesbegrensning for batch |
+| **Preserve layout** | ✅ | ✅ | Bevarer formatering, layout, fonter |
+| **Image text translation** | ✅ | ❌ | Oversetter tekst inni bilder (preview) |
+| **Custom glossaries** | ✅ | ✅ | Egendefinerte termlister (.csv, .tsv, .xlf) |
+| **Custom models** | ✅ | ✅ | Custom Translator-modeller for domener/bransjer |
+| **Auto language detect** | ✅ | ✅ | Automatisk språkdeteksjon |
+| **Multi-language docs** | ✅ | ❌ | Oversett dokumenter med flere språk i én operasjon |
+| **Immediate response** | ❌ | ✅ | Translated dokument returneres direkte i svar |
+
+### Oversettelse av bilder i Word-dokumenter (.docx)
+
+En spesialisert funksjon (API-versjon 2024-11-01-preview) som krever:
+- Azure AI Services **multi-service resource** (ikke standalone Translator)
+- Enable parameter: `"translateTextWithinImage": true` i `options`-feltet
+- Tilleggskostnad basert på Azure Vision-prising
+
+Response inkluderer `totalImageScansSucceeded` og `totalImageScansFailed` for monitorering.
+
+## Arkitekturmønstre
+
+### 1. Batch Translation Pipeline (Anbefalt for volum)
+
+**Arkitektur:**
+```
+Source Blob Container → Document Translation API → Target Blob Container(s)
+         ↓                        ↓                           ↓
+    SAS token             Job Monitoring API         Translated files
+    (read/list)            (status polling)          (write/list)
+```
+
+**Fordeler:**
+- Skalerer automatisk for store volumer
+- Parallell prosessering av flere dokumenter
+- Støtter flere målspråk i én batch-jobb
+- Asynkron — blokkerer ikke applikasjonen
+
+**Ulemper:**
+- Krever Azure Blob Storage (ekstra infrastruktur)
+- Mer kompleks autentisering (SAS tokens eller managed identity)
+- Lengre tid før resultater er klare
+
+**Bruk når:**
+- Du oversetter > 10 dokumenter om gangen
+- Filstørrelse > 40 MB
+- Batch-prosessering er akseptabelt (ikke sanntid)
+- Du trenger å oversette til flere språk samtidig
+
+### 2. Synchronous Single-File Translation (Anbefalt for sanntid)
+
+**Arkitektur:**
+```
+Client App → POST /translator/document:translate → Translated Document
+    ↓                                                        ↓
+Document bytes                                    Inline response
+ Target language
+```
+
+**Fordeler:**
+- Ingen Azure Blob Storage nødvendig
+- Enkel integrering (ett API-kall)
+- Umiddelbart resultat
+- Lavere kompleksitet
+
+**Ulemper:**
+- Kun én fil om gangen
+- Kun ett målspråk per request
+- Ikke egnet for store filer (timeout-risiko)
+
+**Bruk når:**
+- Sanntidsoversettelse i webapp/chatbot
+- Enkeltstående dokumenter < 40 MB
+- Du trenger rask respons (sekunder, ikke minutter)
+- Enkel workflow uten lagring
+
+### 3. Hybrid Pattern: Custom Glossaries + Neural Translation
+
+**Arkitektur:**
+```
+Neural MT Model + Custom Glossary → Hybrid Output
+      ↓                  ↓
+General translation  Domain-specific terms
+```
+
+**Fordeler:**
+- Best of both worlds: NMT-kvalitet + terminologikontroll
+- Konsistent bruk av fagtermer
+- Reduserer post-editing-behov
+
+**Ulemper:**
+- Krever vedlikehold av glossary-filer
+- Glossary må lastes opp for hver batch-jobb (eller hver target container)
+
+**Bruk når:**
+- Juridiske/medisinske/tekniske dokumenter
+- Branding/produktnavn må være konsistente
+- Compliance krever spesifikke termer
+
+## Beslutningsveiledning
+
+### Hvilken modus skal du velge?
+
+| Kriterium | Batch Translation | Single-file Translation |
+|-----------|-------------------|-------------------------|
+| **Antall filer** | > 10 samtidig | 1 om gangen |
+| **Filstørrelse** | Ubegrenset (praktisk) | < 40 MB |
+| **Responstid** | Minutter til timer | Sekunder |
+| **Målspråk** | Flere samtidig | Ett om gangen |
+| **Infrastruktur** | Blob Storage kreves | Ingen ekstra infrastruktur |
+| **Kostnad** | Lavere per tegn ved volum | Høyere per tegn (men enklere) |
+
+### Vanlige feil og røde flagg
+
+| Problem | Årsak | Løsning |
+|---------|-------|---------|
+| **Job fails: "Can't read source"** | SAS token mangler `read`/`list`-tillatelser | Regenerer SAS med korrekte permissions |
+| **Translated file not in target** | SAS token mangler `write`/`list` | Sjekk target container permissions |
+| **Translation quality poor** | Feil språkpar, mangler custom model | Spesifiser source language eksplisitt, bruk Custom Translator |
+| **Scanned PDF loses formatting** | OCR-teknologien har begrensninger | Bruk digitale PDFs når mulig, ikke scannede |
+| **Job stuck in "Running"** | Fil låst med passord/kryptert | Fjern passord/kryptering før opplasting |
+| **Image text not translated** | Preview-feature ikke aktivert | Sett `"translateTextWithinImage": true` (kun batch) |
+| **Cost higher than expected** | Image translation eller Vision API-kall | Disable image features hvis ikke nødvendig |
+
+### Når skal du IKKE bruke Document Translation?
+
+| Scenario | Hvorfor ikke? | Alternativ |
+|----------|---------------|------------|
+| **Sanntids chat-oversettelse** | Document Translation er for tekst-blokker, ikke korte meldinger | Text Translation API v3 |
+| **Live lydoversettelse** | Ikke for tale | Azure Speech Service Translator |
+| **Kun OCR (ingen oversettelse)** | Overkill hvis du bare skal ekstrahere tekst | Azure AI Vision (OCR) |
+| **Real-time collaboration (Google Docs-style)** | Document Translation er batch/single-file, ikke live | Bygg custom med Text Translation API |
+
+## Integrasjon med Microsoft-stakken
+
+### Azure AI Foundry
+
+- Document Translation tilgjengelig via **Foundry (classic)** portal — no-code playground
+- **Foundry (new)** støtter kun forhåndsdefinerte språk med sample-dokumenter (ikke egne filer)
+- Bruk Foundry for prototyping, deretter API for produksjon
+
+### Azure Blob Storage
+
+- **Obligatorisk for batch translation**
+- Autentisering via SAS tokens eller Managed Identity
+- Lifecycle policies kan automatisk slette gamle oversatte filer (kostnadsoptimalisering)
+
+### Custom Translator
+
+- Tren egne NMT-modeller med parallelle korpus (parallel documents)
+- Deploy via Custom Translator-portalen
+- Refereres i Document Translation API via `category`-parameter
+
+### Power Automate
+
+- **Translator v3 connector** tilgjengelig for no-code workflows
+- Støtter både text og document translation
+- Integrer med SharePoint, OneDrive, Outlook for dokumentflyt
+
+### Azure Functions / Logic Apps
+
+- REST API kan wrappes i serverless functions
+- Bruk for event-driven oversettelse (f.eks. ny fil i Blob → trigger oversettelse)
+
+### Azure AI Search
+
+- Bruk Document Translation som pre-processing for multilingual search
+- Oversett dokumenter før indexing → én index, mange språk
+
+## Offentlig sektor (Norge)
+
+### GDPR og Schrems II
+
+| Aspekt | Implikasjon | Anbefaling |
+|--------|-------------|------------|
+| **Data residency** | Oversettelse prosesseres i nærmeste Azure-region (Global) eller spesifisert region (Americas, Asia Pacific, Europe) | Velg **Europa**-region for Translator-ressurs (France Central, West Europe) |
+| **Data retention** | Microsoft lagrer IKKE brukerdata etter oversettelse | Dokumentert i Transparency Note — trygt for sensitiv data |
+| **GDPR Article 28** | Microsoft er data processor | Bruk DPA (Data Processing Agreement) i Azure-kontrakten |
+| **Schrems II compliance** | EU Standard Contractual Clauses (SCCs) | Velg EU-region, verifiser SCCs i Azure-avtalen |
+
+### AI Act (EU)
+
+| Krav | Status for Translator | Handling |
+|------|----------------------|----------|
+| **Transparency** | Brukere må vite at tekst er maskinoversatt | Legg til disclaimer i UI/dokumenter |
+| **Human oversight** | High-risk AI krever human-in-the-loop | Implementer post-editing for kritiske dokumenter |
+| **Accuracy requirements** | Ikke klassifisert som high-risk (men avhenger av bruksområde) | Valider kvalitet manuelt for juridiske/medisinske dokumenter |
+
+### Forvaltningsloven og offentlig kommunikasjon
+
+- **Språkkrav:** Samisk, kvensk, norsk (bokmål/nynorsk) støttes ikke alle optimalt i Translator
+- **Juridisk binding:** Maskinoversatte dokumenter kan ikke erstatte autoriserte oversettelser i rettsprosesser
+- **Tilgjengelighetskrav (UU):** Oversatte dokumenter må bevare WCAG 2.1-kompatibilitet — test at PDF/HTML-output er tilgjengelig
+
+### Datasuverenitet
+
+- **Norway-region** finnes ikke for Translator (kun Foundry-hub) — bruk **West Europe** eller **North Europe** for geografisk nærhet
+- For ekstra høy sensitivitet: Vurder **Translator Container** (disconnected deployment) for air-gapped miljøer
+
+## Kostnad og lisensiering
+
+### Prismodell (per 2026-02)
+
+| Komponent | Enhet | Prisindikasjon (NOK/USD) |
+|-----------|-------|--------------------------|
+| **Text Translation** | Per million tegn | ~$10 USD (varierer med region) |
+| **Document Translation** | Per million tegn | ~$10 USD (samme som tekst) |
+| **Image Translation (preview)** | Per bilde | Beregnes separat (ikke per tegn) |
+| **Image text in Word (preview)** | Per bilde-scan | Azure Vision-prising i tillegg |
+| **Custom Translator** | Per million tegn (trening + inference) | ~$10-40 USD (avhenger av modell) |
+
+**Volume Discount Plans:** C2, C3, C4, D3 tilgjengelig for store volumer (commitment-basert).
+
+### Optimaliseringstips
+
+1. **Batch over single-file:** Lavere overhead (ett API-kall for mange filer)
+2. **Disable image translation hvis ubrukt:** Spar Vision API-kostnader
+3. **Cache oversettelser:** Lagre target-dokumenter i Blob Storage, gjenbruk ved duplikater
+4. **Filter med prefix/suffix:** Bruk `prefix`-parameteren for å unngå å oversette unødvendige filer
+5. **Language auto-detect kun ved nødvendighet:** Spesifiser source language for raskere prosessering og lavere feilrate
+6. **Bruk glossaries for konsistens:** Reduserer behov for custom models (dyrere å trene)
+
+### Total Cost of Ownership (TCO)
+
+| Komponent | Batch Translation | Single-file Translation |
+|-----------|-------------------|-------------------------|
+| **Translator API** | $10/M chars | $10/M chars |
+| **Azure Blob Storage** | $0.02/GB/måned + egress | N/A |
+| **Compute (hvis Azure Functions)** | ~$0.20/million executions | ~$0.20/million executions |
+| **Vision API (images)** | $1-3/1000 images (preview pricing) | N/A |
+| **Total for 100M chars** | ~$1000 + Blob (~$5) + Compute (~$50) = **~$1055** | ~$1000 + Compute (~$50) = **~$1050** |
+
+**Menneskelig oversettelse til sammenligning:** $0.10-0.25 per ord = **$10 000-25 000 USD** for samme volum (100M chars ≈ 15M ord).
+
+**ROI:** Translator er ~10-25x billigere enn menneskelig oversettelse for bulk-volum.
+
+## For arkitekten (Cosmo)
+
+### Spørsmål å stille i arkitekturdialog
+
+1. **Volum og frekvens:**
+   "Hvor mange dokumenter per dag/uke? Er det batch-basert eller kontinuerlig?"
+   → Avgjør batch vs. single-file strategi.
+
+2. **Sensitivitet og compliance:**
+   "Inneholder dokumentene personopplysninger (GDPR), helseopplysninger (HIPAA-ekvivalent), eller klassifisert informasjon?"
+   → Vurder EU-region, Translator Container (disconnected), eller on-prem løsning.
+
+3. **Responstidskrav:**
+   "Må oversettelsen være klar innen sekunder, eller er minutter/timer akseptabelt?"
+   → Sanntid → Sync, batch → Async.
+
+4. **Dokumenttyper:**
+   "Er det strukturerte filer (Word/Excel/PDF) eller ustrukturerte (bilder, scannede PDFs)?"
+   → Scannede PDFs krever OCR (lavere kvalitet), bilder krever preview-feature.
+
+5. **Terminologi og domene:**
+   "Har dere branchespesifikke termer som må oversettes konsistent?"
+   → Custom glossaries (enklere) eller Custom Translator (dyrere, bedre kvalitet).
+
+6. **Målspråk:**
+   "Hvilke språk skal støttes? Er det pivot-språk involvert (f.eks. Swahili → English → Hindi)?"
+   → Sjekk [language support matrix](https://learn.microsoft.com/azure/ai-services/translator/language-support) for kvalitet.
+
+7. **Eksisterende infrastruktur:**
+   "Bruker dere allerede Azure Blob Storage? Har dere managed identities satt opp?"
+   → Påvirker autentiseringsstrategi og deployment-hastighet.
+
+8. **Post-editing workflow:**
+   "Skal oversettelsene gjennomgås av mennesker før publisering?"
+   → Planlegg for human-in-the-loop (HITL) — Azure AI Foundry + Custom Translator har review-funksjoner.
+
+### Fallgruver å unngå
+
+| Fallgruve | Konsekvens | Unngå ved å |
+|-----------|------------|-------------|
+| **Hard-code SAS tokens i kode** | Security breach | Bruk Azure Key Vault + managed identity |
+| **Glemme SAS token expiry** | Jobs feiler etter 24 timer | Sett expiry = 7 dager minimum, eller bruk managed identity |
+| **Overstyre source language når multi-language** | Dårligere kvalitet | La auto-detect gjøre jobben for mixed-language docs |
+| **Bruke Batch for én fil (< 1 MB)** | Overhead med Blob Storage | Bruk Single-file API |
+| **Forvente perfekt layout for scannede PDFs** | OCR-teknologien har begrensninger | Bruk digitale PDFs, eller aksepter lavere layout-kvalitet |
+| **Ikke teste custom glossaries før prod** | Termer oversettes feil | Test med sample-dokumenter først |
+| **Overse rate limits** | 429 Too Many Requests | Implementer exponential backoff retry-logikk |
+
+### Anbefalinger per modenhetsnivå
+
+**Begynner (ingen Translator-erfaring):**
+- Start med **Foundry (classic) portal** for manuell testing
+- Bruk **Single-file API** for prototyping (enklere enn Blob Storage)
+- Test med maksimalt 3 språkpar først
+- Les [Transparency Note](https://learn.microsoft.com/azure/ai-foundry/responsible-ai/translator/transparency-note) for å forstå begrensninger
+
+**Middels (har brukt Text Translation API):**
+- Migrer til **Batch Translation** for volum > 50 filer/dag
+- Implementer **custom glossaries** for domene-termer
+- Sett opp **monitoring** med Application Insights (track job failures)
+- Bruk **managed identity** i stedet for SAS tokens (bedre security)
+
+**Avansert (produksjon med tusenvis av dokumenter/dag):**
+- Tren **Custom Translator-modeller** for spesialiserte domener
+- Implementer **Azure Functions event-driven pipeline** (Blob trigger → oversettelse → output)
+- Aktiver **image translation** kun for dokumenter som faktisk har bilder (kostnadsoptimalisering)
+- Sett opp **geo-replication** av Blob Storage for disaster recovery
+- Overvåk **totalCharacterCharged** i response headers for cost tracking
+
+## Kilder og verifisering
+
+### Microsoft Learn-dokumentasjon (Verified via MCP)
+
+1. **Document Translation Overview**
+   https://learn.microsoft.com/azure/ai-services/translator/document-translation/overview
+   *Confidence: Verified (2026-02)* — Kjernefeatures, formater, data residency
+
+2. **Use Document Translation APIs Programmatically**
+   https://learn.microsoft.com/azure/ai-services/translator/document-translation/how-to-guides/use-rest-api-programmatically
+   *Confidence: Verified (2026-02)* — REST API, batch-oversettelse, SAS tokens, kodeeksempler
+
+3. **Azure Translator Overview**
+   https://learn.microsoft.com/azure/ai-services/translator/overview
+   *Confidence: Verified (2026-02)* — Comparison matrix (text vs. document), feature roadmap
+
+4. **Image Translation Preview (December 2025)**
+   https://learn.microsoft.com/azure/ai-services/translator/document-translation/reference/start-batch-translation#translate-image-files
+   *Confidence: Verified (2026-02)* — Ny funksjonalitet for bildeformater
+
+5. **Service Limits**
+   https://learn.microsoft.com/azure/ai-services/translator/service-limits#document-translation
+   *Confidence: Verified (2026-02)* — Rate limits, request size limits
+
+6. **Translator Transparency Note**
+   https://learn.microsoft.com/azure/ai-foundry/responsible-ai/translator/transparency-note
+   *Confidence: Verified (2026-02)* — AI-begrensninger, data privacy, responsible AI
+
+### Konfidensnivå per seksjon
+
+| Seksjon | Konfidens | Kilde |
+|---------|-----------|-------|
+| Introduksjon | Verified | MCP docs fetch (overview) |
+| Kjernekomponenter | Verified | MCP docs fetch (overview + API reference) |
+| Arkitekturmønstre | Baseline | Best practices fra MCP docs + modellkunnskap |
+| Beslutningsveiledning | Baseline | FAQ + troubleshooting fra MCP docs |
+| Integrasjon med Microsoft-stakken | Baseline | Modellkunnskap + MCP docs (connectors) |
+| Offentlig sektor | Baseline | GDPR/AI Act-kunnskap + Azure compliance docs (ikke spesifikt i MCP-søk) |
+| Kostnad og lisensiering | Baseline | Azure pricing calculator (ikke i MCP-søk, men offentlig info) |
+| For arkitekten | Baseline | Syntetisk veiledning basert på features fra MCP docs |
+
+**Total MCP calls:** 4 (docs_search) + 3 (docs_fetch) = **7**
+**Unique Microsoft Learn URLs:** 6