feat: add document translation + voice streaming examples, update CLAUDE.md

- TranslateDocument.cs: upload-poll-download workflow example
- VoiceStreaming.cs: REST setup endpoint for real-time WebSocket translation
- CLAUDE.md: document voice API findings (not ISpeechToTextClient compatible)
  and document translation workflow notes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: HavenDV

CLAUDE.md

@@ -48,3 +48,19 @@ DeepL API has tagged operations generating sub-clients:
 - `client.StyleRules.*` — Style rule management (v3)
 - `client.VoiceAPI.*` — Voice streaming (v3)
 - `client.AdminApi.*` — Developer key management
+
+## Voice API Notes
+
+The Voice API provides **real-time speech translation** via WebSocket:
+1. REST endpoint (`GetVoiceStreamingUrlAsync`) returns an ephemeral `wss://` URL + token
+2. Client connects to WebSocket and streams audio bytes
+3. Server returns transcription + multi-language translations in real-time
+
+**Not ISpeechToTextClient compatible** — the bi-directional WebSocket streaming pattern doesn't map to MEAI's single-request transcription model. Use the SDK's native `client.VoiceAPI.GetVoiceStreamingUrlAsync()` + a WebSocket client.
+
+## Document Translation Workflow
+
+Three-step async pattern:
+1. **Upload:** `client.TranslateDocuments.TranslateDocumentAsync(targetLang, fileBytes, filename)` → returns `DocumentId` + `DocumentKey`
+2. **Poll:** `client.TranslateDocuments.GetDocumentStatusAsync(docId, docKey)` → check `Status` (Queued → Translating → Done)
+3. **Download:** `client.TranslateDocuments.DownloadDocumentAsync(docId, docKey)` → returns `byte[]` (one-time download)

src/tests/IntegrationTests/Examples/TranslateDocument.cs

@@ -0,0 +1,56 @@
+/*
+order: 50
+title: Translate Document
+slug: translate-document
+
+Shows how to translate a document using the upload-poll-download workflow.
+*/
+
+namespace DeepL.IntegrationTests;
+
+public partial class Tests
+{
+    [TestMethod]
+    public async Task TranslateDocument()
+    {
+        using var client = GetAuthenticatedClient();
+
+        //// DeepL's document translation follows a three-step workflow:
+        //// 1. Upload the document and specify the target language
+        //// 2. Poll for translation status until complete
+        //// 3. Download the translated document
+
+        //// Step 1: Upload a text file for translation.
+        var content = "Hello, world! This is a test document for translation."u8.ToArray();
+        var uploadResponse = await client.TranslateDocuments.TranslateDocumentAsync(
+            targetLang: TargetLanguage.De,
+            file: content,
+            filename: "test.txt");
+
+        uploadResponse.DocumentId.Should().NotBeNullOrEmpty();
+        uploadResponse.DocumentKey.Should().NotBeNullOrEmpty();
+
+        //// Step 2: Poll until the document translation is complete.
+        GetDocumentStatusResponse status;
+        do
+        {
+            await Task.Delay(1000);
+            status = await client.TranslateDocuments.GetDocumentStatusAsync(
+                documentId: uploadResponse.DocumentId!,
+                documentKey1: uploadResponse.DocumentKey!);
+        }
+        while (status.Status is GetDocumentStatusResponseStatus.Queued
+            or GetDocumentStatusResponseStatus.Translating);
+
+        status.Status.Should().Be(GetDocumentStatusResponseStatus.Done);
+
+        //// Step 3: Download the translated document (one-time download).
+        var translatedBytes = await client.TranslateDocuments.DownloadDocumentAsync(
+            documentId: uploadResponse.DocumentId!,
+            documentKey1: uploadResponse.DocumentKey!);
+
+        translatedBytes.Should().NotBeEmpty();
+        var translatedText = System.Text.Encoding.UTF8.GetString(translatedBytes);
+        translatedText.Should().NotBeNullOrEmpty();
+    }
+}

src/tests/IntegrationTests/Examples/VoiceStreaming.cs

@@ -0,0 +1,36 @@
+/*
+order: 60
+title: Voice Streaming
+slug: voice-streaming
+
+Shows how to initiate a voice streaming session for real-time translation.
+*/
+
+namespace DeepL.IntegrationTests;
+
+public partial class Tests
+{
+    [TestMethod]
+    public async Task VoiceStreaming()
+    {
+        using var client = GetAuthenticatedClient();
+
+        //// The DeepL Voice API provides real-time speech translation via WebSocket.
+        //// Step 1: Call the REST endpoint to get an ephemeral WebSocket URL and token.
+        var response = await client.VoiceAPI.GetVoiceStreamingUrlAsync(
+            request: new GetVoiceStreamingUrlRequest
+            {
+                SourceMediaContentType = VoiceMediaContentType.AudioPcm_Encoding_s16le_Rate_16000,
+                SourceLanguage = VoiceSourceLanguage.En,
+                TargetLanguages = ["de"],
+            });
+
+        response.StreamingUrl.Should().NotBeNullOrEmpty();
+        response.Token.Should().NotBeNullOrEmpty();
+
+        //// Step 2: Connect to the WebSocket URL (`response.StreamingUrl`)
+        //// and stream audio bytes for real-time transcription and translation.
+        //// This example only verifies the REST setup endpoint;
+        //// actual WebSocket streaming requires a separate WebSocket client.
+    }
+}