feat: Support never_translate phrases

docs/API.md

@@ -408,6 +408,7 @@ Translates existing captions from one language to another and optionally adds th
   - `maxConcurrentTranslations?: number` - Max number of concurrent translation requests when chunking (default: `4`)
   - `maxCuesPerChunk?: number` - Hard cap for cues included in a single AI translation chunk (default: `80`)
   - `maxCueTextTokensPerChunk?: number` - Approximate cap for cue text tokens included in a single AI translation chunk (default: `2000`)
+- `neverTranslate?: string[]` - Terms (brand names, proper nouns) to preserve verbatim in the translated output; max 100 terms of 100 characters each, `<` and `>` not allowed. Compliance is verified and reported on `result.neverTranslate`, not guaranteed.
 
 **Returns:**
 
@@ -424,6 +425,16 @@ interface TranslationResult {
   uploadedTrackId?: string; // Mux track ID (if uploaded)
   presignedUrl?: string; // S3 presigned URL (default expiry: 24 hours)
   usage?: TokenUsage; // Token usage from the AI provider
+  neverTranslate?: NeverTranslateReport; // Present when neverTranslate terms were supplied
+}
+
+interface NeverTranslateReport {
+  terms: string[]; // Validated terms sent with the request
+  violations: Array<{
+    term: string;
+    expectedCount: number; // Occurrences in the source cue text (case-insensitive)
+    foundCount: number; // Verbatim occurrences in the translated cue text
+  }>;
 }
 ```
 

docs/SECURITY.md

@@ -155,6 +155,10 @@ Partly trusted (validated at the library boundary):
 - `askQuestions` `questions[].answerOptions[]` — max 150 chars each by
   default (overridable via the `maxAnswerOptionLength` option for
   domain-specific category labels that legitimately run longer).
+- `translateCaptions` `neverTranslate[]` — max 100 terms, 100 chars
+  each, and `<` / `>` are rejected, so a term cannot close the
+  `<never_translate>` prompt section and forge instructions outside it.
+  The text itself still reaches the model as content.
 
 If you expose any of the "partly trusted" options to end-users, your
 application boundary should still sanitise and rate-limit — the

docs/WORKFLOWS.md

@@ -521,6 +521,24 @@ const result = await translateCaptions("your-mux-asset-id", "your-track-id", "es
 
 Set `chunking.enabled` to `false` if you want to force a single structured translation request for the full caption file.
 
+Use `neverTranslate` to keep brand names, product names, or other proper nouns verbatim in the translated output:
+
+```typescript
+const result = await translateCaptions("your-mux-asset-id", "your-track-id", "es", {
+  provider: "openai",
+  neverTranslate: ["Mux", "GIF"],
+});
+
+// Compliance is verified after translation and reported on the result
+if (result.neverTranslate?.violations.length) {
+  for (const { term, expectedCount, foundCount } of result.neverTranslate.violations) {
+    console.warn(`"${term}" survived ${foundCount}/${expectedCount} occurrences`);
+  }
+}
+```
+
+Enforcement is prompt-based: the terms are passed to the model with an instruction to preserve them verbatim, then each term's occurrence count in the source is compared against the translated output. Shortfalls are reported as `violations` — the library never rewrites the translation to repair them.
+
 ### S3-Compatible Storage Requirements
 
 Caption translation requires S3-compatible storage to host VTT files for Mux ingestion.