The Trinity Beast – Translation Service

1. Service Overview

1.1 The Problem We Solved

Technical documentation is hard to translate. Generic translation services — including AWS Translate — don't understand the boundary between human language and machine language. They translate code blocks, corrupt variable names, localize version numbers, and hallucinate brand names.

We learned this the hard way. AWS Translate cost us over $800 in worthless translations before we caught it corrupting technical content across 11 languages. Silent failures. No warnings. No way to know without reading every translated document.

So we built our own translation engine. It uses Amazon Bedrock with sentinel preprocessing and multi-layer validation. You choose the AI agent — from fast and affordable to the highest quality available. The agent never sees protected content — it can't corrupt what it never touches. Every translation is validated before it ships.

1.2 Choose Your Agent

1.3 The Pitch

1.3.1 See It In Action

1.3 What We Translate

Supported languages (300+):

The translation engine supports any language that Claude can translate — over 300 languages and dialects. The table below shows our validated tier (languages tested in production with full sentinel and validator coverage). Any other language Claude supports can be requested — it will use the same engine with default settings.

2. Pricing

2.1 Pricing Model

Simple, transparent, usage-based pricing. No monthly fees. No commitments. Pay only for what you translate — priced per token, per language.

Cost is determined by the actual token usage of your document's translatable content. Code blocks, diagrams, and protected elements are excluded from the token count — you only pay for what the AI agent actually translates. A 100 KB document that's 60% code blocks costs far less than a 100 KB document that's all prose.

Live Pricing (from Aurora/Valkey — always current)

Rates are stored in Aurora (translation_parameters) and cached in Valkey. The GET /translate/models endpoint returns input_rate_per_1m, output_rate_per_1m, speed_factor, and estimated_cost_per_pair for each agent — use these to build real-time cost estimates in your integration.

2.2 Volume Discounts

Volume pricing is available for high-usage customers. Contact us for custom rates if you're translating more than 1,000 chunks per month.

2.3 Cost Comparison

How we compare to alternatives for a typical 50 KB technical document translated into 11 languages (Sonnet agent, ~6 chunks):

2.5 Service Limits

Each quote and acceptance has a clear ceiling. Need more? Submit additional quotes — there is no limit on how many quotes you can create.

The math: A single acceptance can process up to 9 quotes of 60 documents each — 540 documents per acceptance, each translated into up to 11 target languages. Orders producing 100 or more translated documents (for example, 10 documents into 10 languages) automatically receive Batch pricing — 30% off, delivered within 12–24 hours. These ceilings are sized to keep quality consistent and delivery fast; they will scale up as the service registers with OpenAPI directories and we expand capacity.

3. API Reference

3.1 Authentication

All API requests require authentication via API key. Include your key in the X-API-Key header:

curl -H "X-API-Key: your-api-key-here" \
     https://api.cpmp-site.org/translate/languages

API keys are managed through your Trinity Beast Account Dashboard. Create an account at cpmp-site.org/dashboard — translation-only customers are first-class citizens. If your email is also tied to a Price API subscription, you'll see those options too. The dashboard adapts to what you have.

Response Format — Unified Messaging Envelope (UME)

Every response — success or error — follows the Unified Messaging Envelope format. All 12 fields are always present. No exceptions.

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/translate] [202]",
  "status_code": 202,
  "endpoint": "/translate",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-18T22:30:00Z",
  "data": { ... },
  "error": ""
}

The language field reflects the customer's api_lang preference (set in Account Dashboard). Error messages are translated into that language. The envelope metadata (brackets, identifiers) stays English always.

3.2 Submit Translation Job

POST /translate

Request Body

{
  "source_url": "https://example.com/docs/api-reference.html",
  "source_lang": "auto",
  "target_langs": ["es", "ja", "zh"],
  "agent": "claude-sonnet-4.6",
  "protected_terms": ["MyProduct", "DataSync API"],
  "callback_url": "https://example.com/webhook/translate-done",
  "idempotency_key": "api-ref-2026-05"
}

Response (202 Accepted)

Returns the standard UME envelope (see section 3.1) with this data payload:

"data": {
  "job_id": "019e3d489ea4-15d9082769939137",
  "job_status": "queued",
  "source_doc": "api-reference.html",
  "source_size_kb": 52,
  "target_langs": ["es", "ja", "zh"],
  "chunks": 6,
  "estimated_cost": "$0.77",
  "estimated_time_seconds": 180
}

Error Response (400 Bad Request)

The error field contains a localized message in the customer's api_lang:

"error": "🛑 [LPO] [us-east-2] [BeastMirror] [/translate] [400] El campo target_langs es obligatorio. Use \"all\" o un array como [\"es\", \"ja\"]"

3.3 Check Job Status

GET /translate/{job_id}

Response — Job In Progress

"data": {
  "job_id": "019e3d489ea4-15d9082769939137",
  "job_status": "translating",
  "source_doc": "api-reference.html",
  "progress": {
    "total_pairs": 3,
    "completed": 1,
    "failed": 0,
    "in_progress": 2
  },
  "started_at": "2026-05-18T22:30:00Z",
  "elapsed_seconds": 45
}

Response — Job Complete

"data": {
  "job_id": "019e3d489ea4-15d9082769939137",
  "job_status": "succeeded",
  "source_doc": "api-reference.html",
  "completed_at": "2026-05-18T22:33:07Z",
  "duration_seconds": 187,
  "pairs_succeeded": 3,
  "pairs_failed": 0,
  "chunks_per_lang": 6,
  "cost": "$0.77",
  "outputs": {
    "es": "https://api.cpmp-site.org/translate/download/019e3d489ea4/es/api-reference.html",
    "ja": "https://api.cpmp-site.org/translate/download/019e3d489ea4/ja/api-reference.html",
    "zh": "https://api.cpmp-site.org/translate/download/019e3d489ea4/zh/api-reference.html"
  }
}

Job statuses: queued → translating → deploying → succeeded | partial | failed

3.4 Cancel Job

DELETE /translate/{job_id}

Cancels a running job. Already-completed pairs are still available for download. You are not charged for cancelled pairs.

Response (200 OK)

"data": {
  "job_id": "019e3d489ea4-15d9082769939137",
  "job_status": "cancelled",
  "pairs_completed_before_cancel": 1,
  "pairs_cancelled": 2,
  "outputs": {
    "es": "https://api.cpmp-site.org/translate/download/019e3d489ea4/es/api-reference.html"
  }
}

Returns 409 Conflict if the job is already complete.

3.5 List Languages

GET /translate/languages (public, no auth required)

Response

Returns all supported languages with metadata:

"data": {
  "language_count": 21,
  "validated_languages": [
    {"code": "es", "name": "Spanish", "native_name": "Español", "script": "Latin", "direction": "ltr"},
    {"code": "ja", "name": "Japanese", "native_name": "日本語", "script": "Kanji/Kana", "direction": "ltr"},
    {"code": "ar", "name": "Arabic", "native_name": "العربية", "script": "Arabic", "direction": "rtl"}
  ],
  "additional_languages": "300+ supported via Claude — specify any valid language code",
  "pricing": {
    "model": "per-token",
    "see_endpoint": "/translate/models"
  },
  "limits": {
    "max_file_size_kb": 500,
    "max_languages_per_quote": 12,
    "max_quotes_per_acceptance": 9
  }
}

The 21 validated languages have production-tested sentinel configurations and per-language chunk tuning. Any other language Claude supports can be requested using its ISO 639-1 code — the engine applies intelligent defaults.

3.6 List Agents

GET /translate/models (public, no auth required)

Response

Returns the available AI agents with token-based pricing, speed, and quality metadata:

"data": {
  "models": [
    {
      "id": "claude-haiku-3.5",
      "name": "Claude Haiku 3.5",
      "tier": "Good",
      "input_rate_per_1m": 1.0,
      "output_rate_per_1m": 5.0,
      "estimated_cost_per_pair": 0.03,
      "speed": "fast",
      "quality": "good",
      "description": "Fast and affordable. Best for Latin-script languages and straightforward documents."
    },
    {
      "id": "claude-sonnet-4.6",
      "name": "Claude Sonnet 4.6",
      "tier": "Better",
      "input_rate_per_1m": 3.0,
      "output_rate_per_1m": 15.0,
      "estimated_cost_per_pair": 0.08,
      "speed": "moderate",
      "quality": "excellent",
      "description": "Balanced speed and quality. Handles complex scripts and technical documents well. Default choice."
    },
    {
      "id": "claude-opus-4",
      "name": "Claude Opus 4",
      "tier": "Best",
      "input_rate_per_1m": 5.0,
      "output_rate_per_1m": 25.0,
      "estimated_cost_per_pair": 0.05,
      "speed": "slow",
      "quality": "exceptional",
      "description": "Highest quality translations. Best for critical documents and complex grammar."
    }
  ],
  "default": "claude-sonnet-4.6",
  "pricing_note": "Rates are per 1M tokens. estimated_cost_per_pair is for a typical 50KB document (one language). Actual cost depends on document size and content density."
}

Use the id value in the agent field when submitting a translation job. If omitted, the engine uses claude-sonnet-4.6 automatically.

3.7 Check Usage

GET /translate/usage

Response

"data": {
  "period": "2026-05",
  "chunks_translated": 847,
  "chunks_failed": 12,
  "total_cost": "$36.17",
  "our_cost": "$36.17",
  "default_agent": "claude-sonnet-4.6",
  "jobs_submitted": 18,
  "jobs_succeeded": 15,
  "jobs_partial": 2,
  "jobs_failed": 1
}

4. Architecture

4.1 Request Flow

The translation service is built on the same infrastructure that powers our internal documentation translation. It's battle-tested on 440 document-language pairs.

sequenceDiagram
    participant C as Customer
    participant L as LPO Server (Go)
    participant St as Stripe
    participant Q as SQS Queue
    participant W as BeastTranslate (Bedrock)
    participant S3 as S3 (Output)

    C->>L: POST /translate (API key auth)
    L->>L: Validate + Analyze chunks
    L-->>C: Quote (chunks, cost, languages)
    C->>St: Pay quote (Stripe Checkout)
    St-->>L: Payment confirmed (webhook)
    L->>Q: Enqueue job
    L-->>C: 202 Accepted (job_id)
    Q->>W: Worker polls SQS directly
    W->>W: Parallel language processing (×11)
    W->>S3: Write translated docs
    W->>L: Update Aurora (job record)
    C->>L: GET /translate/:id
    L-->>C: Status + Download URLs
        

Key components:

• LPO Server (Go) — validates requests, meters usage, enqueues jobs
• SQS Queue — decouples submission from execution
• BeastTranslate (Persistent Worker) — unified orchestrator that polls the queue directly, processes all languages, handles both realtime and batch inference
• Source Validator — catches structural defects before burning tokens (size, encoding, Mermaid syntax, unclosed tags). Auto-repairs what it can, rejects early with actionable reports when it can't.
• Language Detector — auto-detects source language via Unicode script analysis + word frequency heuristics (300+ languages, <10ms, no API calls). Enables any-to-any translation without specifying source language.
• Worker (Python/Bedrock) — sentinel preprocessing, smart splitting (24 KB max), translation, validation, integrity check with diagram auto-stitch
• Aurora — job records, event log, billing data
• S3 — output storage (30-day retention)

4.2 Validator System

Every translated chunk passes through 5 validation checks before it's accepted:

4.3 Output Storage

Translated documents are stored in S3 under your customer folder:

s3://trinity-beast-translations/
  {customer_id}/
    {job_id}/
      source.html           (original, for reference)
      es/document.html      (Spanish output)
      ja/document.html      (Japanese output)
      zh/document.html      (Chinese output)
      manifest.json         (job metadata)

Retention: 30 days. Download URLs are presigned and valid for 72 hours (3 days). You can re-request download URLs anytime within the 30-day window.

4.4 Source Validation & Document Analysis

Before any translation work begins, your document passes through a validation gate and structural analysis. This catches defects that would cause translation failures, and determines the optimal way to split your document for translation — rejecting early saves you money and prevents corrupted output.

What Gets Checked

• Size — documents over 500 KB are rejected (chunking becomes unreliable)
• Encoding — BOM markers and null bytes are auto-stripped; mixed encodings flagged
• HTML structure — unclosed tags auto-repaired (up to 5); deeper issues rejected with location
• Mermaid diagrams — empty blocks, missing type declarations, mismatched brackets caught before translation

If your document has repairable issues, they're fixed silently — you never know. If it has unrecoverable issues, you get an actionable rejection report with exact locations and fix suggestions. Zero Bedrock tokens burned on broken documents.

Customer Prescan (Opt-In)

For documents without translate="no" annotations, enable the customer prescan to auto-detect protected zones:

{
  "docs": ["my-technical-doc.html"],
  "langs": ["es", "ja", "de"],
  "options": {
    "customer_prescan": true
  }
}

The prescan identifies code blocks, inline code, technical identifiers, and brand terms in your document — then protects them automatically during translation. Your document doesn't need any special markup. The engine figures out what's code and what's prose.

Document Analysis & Chunk Planning

When you request a translation quote, the engine performs a structural analysis of your document — automatically determining the optimal way to split it for translation. This is done on your behalf; no preparation is required from you.

What the analysis does:

• Identifies section boundaries — headings, semantic sections, table boundaries, code blocks
• Classifies content type per region — prose (translatable), protected (code/diagrams), mixed (tables with both)
• Calculates optimal split points — targets ~15 KB for prose-heavy sections, allows up to 20 KB for sections that are predominantly protected content (code blocks, diagrams, technical tables)
• Stores the chunk plan — the exact split strategy is saved with your quote so the translation worker follows the same plan at execution time

Why this matters for cost:

Translation is priced per token — the translatable content in your document determines the token count. The analysis ensures your document is split at natural boundaries — never mid-paragraph, never mid-table, never mid-code-block. Smarter splitting means better context for the AI agent, which means higher quality output. A 100 KB document with large code blocks has far fewer translatable tokens than a 100 KB prose document, because the engine recognizes that protected content doesn't consume translation tokens.

The chunk plan is included in your quote response:

{
  "quote_id": "019e4f...",
  "document": "my-api-docs.html",
  "analysis": {
    "total_size_kb": 98.4,
    "translatable_chunks": 6,
    "protected_ratio": 0.42,
    "estimated_translatable_content_kb": 57.1
  },
  "estimated_input_tokens": 36544,
  "estimated_output_tokens": 27773,
  "cost_per_language": 0.36,
  "languages": 11,
  "total_cost": 3.96
}

You see exactly how the engine will process your document before you commit. No surprises.

Any-to-Any Translation

Source language is auto-detected — no need to specify it. The engine uses Unicode script analysis and word frequency heuristics to identify the source language (300+ languages supported, <10ms, no API calls). Submit a Japanese document and translate it to Spanish without specifying source_lang. No pivot through English required.

{
  "docs": ["japanese-guide.html"],
  "langs": ["es", "fr", "de"],
  "source_lang": "auto"
}

4.5 Observability & Control — Better Than AWS

We built this to be observable and controllable in ways that AWS Translate isn't. Every job, every pair, every event — tracked and actionable.

Real-Time Progress

Poll GET /translate/{job_id} for live progress. You see exactly which languages are done, which are in progress, and which failed — not just "processing" for 10 minutes.

"data": {
  "job_id": "019e3d489ea4-15d9082769939137",
  "job_status": "translating",
  "progress": {
    "total_pairs": 11,
    "completed": 7,
    "failed": 0,
    "in_progress": 4,
    "details": {
      "es": "succeeded", "pt": "succeeded", "fr": "succeeded",
      "de": "succeeded", "ru": "succeeded", "ja": "succeeded",
      "zh": "succeeded", "hi": "in_progress", "ar": "in_progress",
      "ur": "in_progress", "it": "in_progress"
    }
  }
}

Cancel Mid-Job

DELETE /translate/{job_id} cancels the job immediately. Already-completed pairs are still available. You're not charged for cancelled pairs. AWS Translate batch jobs? Once submitted, you wait.

Retry Failed Pairs

POST /translate/{job_id}/retry — if a job completes with partial status (some pairs failed), retry just the failed ones. No need to re-translate the whole document.

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/translate/019e3d489ea4-15d9082769939137/retry] [202]",
  "status_code": 202,
  "endpoint": "/translate/019e3d489ea4-15d9082769939137/retry",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-05-18T23:00:00Z",
  "data": {
    "original_job_id": "019e3d489ea4-15d9082769939137",
    "retry_job_id": "019e3d5a1b2c-retry001",
    "pairs_retrying": ["ko", "ur"],
    "estimated_cost": "$0.51"
  },
  "error": ""
}

Full Audit Trail

Every event is logged in Aurora with millisecond timestamps:

You can query your job history via GET /translate/history — last 50 jobs with full event logs.

Spend Controls

• Per-job estimate — see cost before you submit
• Daily spend cap — default $100/day, adjustable in dashboard
• Monthly usage tracking — real-time via /translate/usage
• Volume tier visibility — know when you're approaching a discount threshold

Health Endpoint

GET /translate/health — public endpoint showing service status:

{
  "status": "✅ [LPO] [us-east-2] [BeastMirror] [/translate/health] [200]",
  "status_code": 200,
  "endpoint": "/translate/health",
  "cluster_node": "BeastMirror",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-05-18T23:15:00Z",
  "data": {
    "service_status": "operational",
    "queue_depth": 3,
    "active_jobs": 2,
    "avg_completion_time_seconds": 145,
    "last_successful_job": "2026-05-18T23:12:00Z",
    "bedrock_status": "available",
    "daily_spend": "$127.35",
    "daily_limit": "$600.00"
  },
  "error": ""
}

4.6 Internal Efficiency — Delta Translation

We maintain a 40-document technical library translated into 11 languages. These documents change daily as we ship new features. Rather than re-translating entire documents on every update, our engine uses an internal delta system that identifies exactly which sections changed and only processes those.

This is not a customer-facing feature — it is an internal optimization that keeps our operational costs low, which in turn keeps your translation prices competitive. You always submit fresh documents and receive complete translations. Behind the scenes, we apply the same engineering discipline to our own documentation pipeline.

Why This Matters to You

• Lower prices: Our internal efficiency means we can offer translation at competitive rates without cutting corners on quality
• Battle-tested engine: We run hundreds of incremental translations per week on our own docs — the same engine that processes your documents is continuously exercised and hardened
• Fast iteration: When we ship a new feature (like batch quote acceptance or per-language cost breakdowns), the documentation is updated and re-translated within hours, not weeks

5. Customer Experience

5.1 Account Dashboard — The Entry Point

The Trinity Beast Account Dashboard is where customers create accounts, manage services, and track usage. Translation-only customers are first-class citizens — you don't need a Price API subscription to use translation.

Dashboard URL: cpmp-site.org/dashboard

What You See Depends on What You Have

Translations Tab

• Submit new job — upload a file or paste a URL, select languages, see cost estimate, submit
• Job history — all jobs with status, progress, cost, and download links
• Real-time progress — watch jobs translate live (auto-refresh every 5 seconds)
• Download center — one-click download for any language, bulk download as ZIP
• Retry failed pairs — if a job partially failed, retry just the failed languages

Usage Tab (Translation Section)

• This month — pairs translated, total spend, current volume tier
• Spend cap — daily limit (default $100, adjustable)
• History — month-by-month usage and spend
• Volume tier progress — "47 more pairs to reach $2.50/pair tier"

5.2 Webhooks

When a job completes, we POST to your callback_url (if provided). Webhook payloads use the full UME envelope — same 12 fields as every API response:

POST https://your-server.com/webhook/translate-done
Content-Type: application/json
X-Trinity-Signature: sha256=abc123...

{
  "status": "✅ [LPO] [us-east-2] [BeastWebhook] [webhook/translation.completed] [200]",
  "status_code": 200,
  "endpoint": "webhook/translation.completed",
  "cluster_node": "BeastWebhook",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/webhook-engine/v1",
  "timestamp": "2026-05-18T22:35:00Z",
  "data": {
    "event": "translation.completed",
    "job_id": "019e3d489ea4-15d9082769939137",
    "job_status": "succeeded",
    "source_doc": "api-reference.html",
    "pairs_succeeded": 3,
    "pairs_failed": 0,
    "cost": "$0.77",
    "duration_seconds": 187,
    "outputs": {
      "es": "https://api.cpmp-site.org/translate/download/019e3d489ea4/es/api-reference.html",
      "ja": "https://api.cpmp-site.org/translate/download/019e3d489ea4/ja/api-reference.html",
      "zh": "https://api.cpmp-site.org/translate/download/019e3d489ea4/zh/api-reference.html"
    }
  },
  "error": ""
}

The X-Trinity-Signature header contains an HMAC-SHA256 signature of the request body using your API key as the secret. Verify this to ensure the webhook is authentic.

Webhook Events

Webhook Failure Example

If a job fails, the webhook still uses UME — but with the error field populated:

{
  "status": "🛑 [LPO] [us-east-2] [BeastWebhook] [webhook/translation.completed] [200]",
  "status_code": 200,
  "endpoint": "webhook/translation.completed",
  "cluster_node": "BeastWebhook",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/webhook-engine/v1",
  "timestamp": "2026-05-18T22:40:00Z",
  "data": {
    "event": "translation.completed",
    "job_id": "019e3d489ea4-15d9082769939137",
    "job_status": "partial",
    "source_doc": "api-reference.html",
    "pairs_succeeded": 9,
    "pairs_failed": 2,
    "cost": "$2.35",
    "duration_seconds": 312,
    "outputs": {
      "es": "https://api.cpmp-site.org/translate/download/019e3d489ea4/es/api-reference.html",
      "pt": "https://api.cpmp-site.org/translate/download/019e3d489ea4/pt/api-reference.html",
      "fr": "https://api.cpmp-site.org/translate/download/019e3d489ea4/fr/api-reference.html",
      "de": "https://api.cpmp-site.org/translate/download/019e3d489ea4/de/api-reference.html",
      "ru": "https://api.cpmp-site.org/translate/download/019e3d489ea4/ru/api-reference.html",
      "ja": "https://api.cpmp-site.org/translate/download/019e3d489ea4/ja/api-reference.html",
      "zh": "https://api.cpmp-site.org/translate/download/019e3d489ea4/zh/api-reference.html",
      "hi": "https://api.cpmp-site.org/translate/download/019e3d489ea4/hi/api-reference.html",
      "ar": "https://api.cpmp-site.org/translate/download/019e3d489ea4/ar/api-reference.html"
    },
    "failed_pairs": {
      "ur": "Validator failed: tag count mismatch after 3 retries",
      "ko": "Bedrock timeout after 15 minutes"
    }
  },
  "error": ""
}

Note: status_code is 200 because the webhook delivery succeeded. The job status (partial) and failed_pairs tell you what happened with the translation. The error field in the envelope is empty because this isn't an envelope-level error — it's a job-level partial failure.

5.3 Brand Terms Protection

Every account can configure up to 150 brand terms that are automatically protected during translation. These terms are never translated, transliterated, or modified in any way — they appear exactly as written in every target language.

Why This Matters

Generic translation services don't know your brand names. "Acme Corp" becomes "アクメ株式会社" in Japanese. "DataForge" becomes "DatenSchmiede" in German. Product names, person names, and technical identifiers get localized when they shouldn't be. Our sentinel preprocessing system prevents this entirely.

How to Set Up

1. Log in to your Account Dashboard at https://api.cpmp-site.org/dashboard
2. Navigate to the Translation Service panel
3. Open the Brand Terms section under Account Settings
4. Add your brand terms — product names, person names, company names, technical identifiers
5. Save — terms apply to all future translation jobs automatically

Limits

What's Already Protected (Without Brand Terms)

The sentinel preprocessing system automatically protects technical content regardless of your brand terms list:

• Code blocks (<pre> and <code> elements)
• Mermaid diagrams
• Inline code and CLI commands
• URLs, email addresses, and file paths
• HTML attributes and structure
• HTML elements inside JSON string values (links, styled spans — preserved via sentinel extraction)

Brand terms add protection for prose-level content — names and identifiers that appear in regular text paragraphs where the AI agent would otherwise translate or transliterate them.

API Access

GET /dashboard/api/protected-terms    → Returns current terms list
PUT /dashboard/api/protected-terms    → Replaces terms list
    Body: {"terms": ["Acme Corp", "DataForge", "CloudSync API"]}

5.4 Multi-Lingual API Messaging

Every API response speaks your language. When you set your api_lang preference in the Account Dashboard, all human-readable messages — errors, confirmations, validation feedback — are returned in that language. Data elements stay English always.

The Design Principle

What Gets Localized

Setting Your Language Preference

Two language settings control your experience:

• api_lang — Controls API response messages. Set in Account Dashboard → Settings → API Language. Default: en.
• preferred_lang — Controls emails (receipts, completion notifications, newsletters). Set in Account Dashboard → Settings → Communication Language. Default: en.

Supported Languages (12)

API messages and emails are available in all 12 core languages:

en · es · pt · fr · de · ru · hi · ur · it · ar · ja · zh

If your api_lang is set to a language not in this list, messages fall back to English.

Example: Same Error, Different Languages

A customer with api_lang: "ja" sees validation errors in Japanese:

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/translate/accept-batch] [409]",
  "status_code": 409,
  "endpoint": "/translate/accept-batch",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "ja",
  "api_key_id": "ed5ff412-4de1-4fb4-a96d-1f7053834f61",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-07-08T14:00:00Z",
  "data": {
    "status": "validation_failed",
    "message": "バッチ内の一部の見積もりが処理できませんでした。エラーを確認し、有効な見積もりのみで再送信してください。",
    "errors": [
      {
        "quote_id": "019f3a1b2c3d",
        "error": "見積もり 019f3a1b2c3d は有効期限が切れています。新しい見積もりをリクエストしてください。"
      }
    ],
    "valid": 2,
    "invalid": 1
  },
  "error": ""
}

The same request from a customer with api_lang: "es":

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/translate/accept-batch] [409]",
  "status_code": 409,
  "endpoint": "/translate/accept-batch",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "es",
  "api_key_id": "ed5ff412-4de1-4fb4-a96d-1f7053834f61",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-07-08T14:00:00Z",
  "data": {
    "status": "validation_failed",
    "message": "Algunas cotizaciones no pudieron procesarse. Revise los errores y reenvíe solo las cotizaciones válidas.",
    "errors": [
      {
        "quote_id": "019f3a1b2c3d",
        "error": "La cotización 019f3a1b2c3d ha expirado. Solicite una nueva."
      }
    ],
    "valid": 2,
    "invalid": 1
  },
  "error": ""
}

5.5 Error Handling & Pre-Validation

The batch acceptance endpoint validates every quote BEFORE charging your payment method. If any quote in your batch is invalid, the entire batch is rejected with structured errors — no partial charges, no guessing which ones failed.

Fail-Fast, Fix-Once Design

Error Types

The pre-validation gate catches four categories of problems:

Response Structure (409 Conflict)

When pre-validation fails, the response uses HTTP 409 with structured error detail:

{
  "status": "🛑 [LPO] [us-east-2] [BeastMirror] [/translate/accept-batch] [409]",
  "status_code": 409,
  "endpoint": "/translate/accept-batch",
  "cluster_node": "BeastMirror",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ed5ff412-4de1-4fb4-a96d-1f7053834f61",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-07-08T14:30:00Z",
  "data": {
    "status": "validation_failed",
    "message": "Some quotes in your batch could not be processed. Please review the errors below and resubmit with valid quotes only.",
    "errors": [
      {
        "quote_id": "019f3a1b2c3d",
        "error": "Quote 019f3a1b2c3d has expired. Please request a new quote."
      },
      {
        "quote_id": "019f3a2e4f5g",
        "error": "Quote 019f3a2e4f5g has already been processed on July 7, 2026 at 2:15 PM EST. Please remove it from your batch."
      }
    ],
    "valid": 7,
    "invalid": 2
  },
  "error": ""
}

Handling Pre-Validation in Your Integration

// Pseudocode — handling the 409 pre-validation response
response = POST("/translate/accept-batch", { quote_ids: [...] })

if response.status_code == 409:
    // No charge was made. Fix the issues and retry.
    for error in response.data.errors:
        log(f"Quote {error.quote_id} failed: {error.error}")
    
    // Remove invalid quotes and resubmit
    valid_ids = [id for id in quote_ids if id not in failed_ids]
    retry_response = POST("/translate/accept-batch", { quote_ids: valid_ids })

elif response.status_code == 200:
    // All quotes valid, payment processed, jobs submitted.
    task_id = response.data.task_id
    // Poll task status for consolidated completion.

Successful Batch Response (200 OK)

When all quotes pass validation and payment succeeds:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/translate/accept-batch] [200]",
  "status_code": 200,
  "endpoint": "/translate/accept-batch",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ed5ff412-4de1-4fb4-a96d-1f7053834f61",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-07-08T14:30:00Z",
  "data": {
    "status": "accepted",
    "batch_size": 3,
    "quote_ids": ["019f3a1b2c3d", "019f3a2e4f5g", "019f3a3h6i7j"],
    "task_id": "019f3b4k8l9m",
    "jobs": [
      {"quote_id": "019f3a1b2c3d", "doc_name": "api-reference.html", "job_id": "019f3c5n0p1q"},
      {"quote_id": "019f3a2e4f5g", "doc_name": "user-guide.html", "job_id": "019f3c6r2s3t"},
      {"quote_id": "019f3a3h6i7j", "doc_name": "quick-start.html", "job_id": "019f3c7u4v5w"}
    ],
    "payment_id": "pi_3TgvABC123...",
    "amount_usd": 11.88,
    "eta": {
      "estimated_seconds": 180,
      "bottleneck_language": "ar",
      "estimated_completion": "2026-07-08T14:33:00Z"
    }
  },
  "error": ""
}

Notice the task_id — this is your handle for tracking the entire batch as a unit. The eta object shows estimated completion time based on the bottleneck language (the one that will take longest).

5.6 Task Organizer — Batch Orchestration

When you accept multiple quotes in a single batch, the engine creates a parent Task that tracks all resulting jobs as a unit. One acceptance = one Task = N jobs. One notification when everything finishes — not N individual emails.

The Problem It Solves

How It Works

1. Batch accepted — Payment processes, Task is created, N jobs are submitted to the translation queue
2. Jobs run in parallel — Each job translates its document into all requested languages simultaneously (one container per language)
3. Jobs complete independently — Some may succeed, some may partially fail — the Task tracks each one
4. All done → Single notification — When the last job finishes, the Task Organizer sends one consolidated email and (if configured) fires one webhook

Task Status

Track your batch with GET /translate/task/{task_id}:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/translate/task/019f3b4k8l9m] [200]",
  "status_code": 200,
  "endpoint": "/translate/task/019f3b4k8l9m",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ed5ff412-4de1-4fb4-a96d-1f7053834f61",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-07-08T14:35:00Z",
  "data": {
    "task_id": "019f3b4k8l9m",
    "state": "in_progress",
    "total_jobs": 3,
    "completed_jobs": 1,
    "failed_jobs": 0,
    "cancelled_jobs": 0,
    "notification_sent": false,
    "jobs": [
      {"job_id": "019f3c5n0p1q", "state": "succeeded", "completed_at": "2026-07-08T14:33:12Z", "succeeded_pairs": 11, "failed_pairs": 0, "bedrock_cost": 3.96},
      {"job_id": "019f3c6r2s3t", "state": "translating", "completed_at": "", "succeeded_pairs": 0, "failed_pairs": 0, "bedrock_cost": 0},
      {"job_id": "019f3c7u4v5w", "state": "queued", "completed_at": "", "succeeded_pairs": 0, "failed_pairs": 0, "bedrock_cost": 0}
    ]
  },
  "error": ""
}

Task States

Consolidated Completion Email

When all jobs in a Task finish, the customer receives a single email summarizing the entire batch. The email renders in the customer's preferred_lang — subject line, title, all labels, download links, and footer.

What the email contains:

• Batch summary — total documents, total languages, success/failure counts
• Per-job breakdown — document name, languages, status, duration
• Download links — direct links for each translated document (72-hour expiry)
• Cost summary — total charged with per-job detail
• Retry guidance — if any pairs failed, instructions to retry just the failures

Webhook Notification (Batch-Level)

If you provided a callback_url on any quote in the batch, a single webhook fires when the Task completes:

POST https://your-server.com/webhook/translate-done
Content-Type: application/json
X-Trinity-Signature: sha256=...

{
  "status": "✅ [LPO] [us-east-2] [BeastWebhook] [webhook/task.completed] [200]",
  "status_code": 200,
  "endpoint": "webhook/task.completed",
  "cluster_node": "BeastWebhook",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ed5ff412-4de1-4fb4-a96d-1f7053834f61",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/webhook-engine/v1",
  "timestamp": "2026-07-08T14:38:00Z",
  "data": {
    "event": "task.completed",
    "task_id": "019f3b4k8l9m",
    "task_state": "succeeded",
    "total_jobs": 3,
    "completed_jobs": 3,
    "failed_jobs": 0,
    "total_pairs_succeeded": 33,
    "total_pairs_failed": 0,
    "total_cost": 11.88,
    "duration_seconds": 312,
    "jobs": [
      {"job_id": "019f3c5n0p1q", "doc_name": "api-reference.html", "state": "succeeded", "pairs": 11},
      {"job_id": "019f3c6r2s3t", "doc_name": "user-guide.html", "state": "succeeded", "pairs": 11},
      {"job_id": "019f3c7u4v5w", "doc_name": "quick-start.html", "state": "succeeded", "pairs": 11}
    ]
  },
  "error": ""
}

Cancel a Task

DELETE /translate/task/{task_id} cancels all remaining jobs in the batch. Already-completed jobs are unaffected — their translations remain available for download. You are not charged for cancelled pairs.

6. Implementation Plan

6.1 Phase 1: Core API

Timeline: 1-2 sessions

Deliverables:

• POST /translate — submit job (wraps internal translation engine)
• GET /translate/{job_id} — check status + get output URLs
• DELETE /translate/{job_id} — cancel running job
• GET /translate/languages — list supported languages (public)
• Customer API key authentication (reuse existing key system)
• Per-customer S3 output folders

6.2 Phase 2: Metering & Billing

Timeline: 1 session

Deliverables:

• GET /translate/usage — current month usage
• Usage counter in Valkey (usage:translate:{customer_id}:{month})
• Stripe product for translation (usage-based billing)
• Monthly invoice line item for translation usage
• Volume discount calculation

6.3 Phase 3: Customer Experience

Timeline: 1-2 sessions

Deliverables:

• Dashboard "Translations" tab
• Job submission form (upload or URL)
• Job history table with status and downloads
• Usage meter widget
• Webhook delivery + signature verification docs

6.4 Phase 4: Launch

Timeline: 1 session

Deliverables:

• Public documentation (this document, updated)
• Pricing page on website
• API Reference section in main docs
• Announcement to existing customers
• Soft launch — invite-only for first 2 weeks

7. Risks & Mitigations

Business Case Summary

What we're selling: AI-powered document translation that actually works for technical content.

Why it's viable:

• We already built the hard part — the translation engine is production-tested on 440+ doc-language pairs
• Infrastructure cost is near-zero (serverless, pay-per-use)
• Per-chunk pricing is transparent and driven from actual Bedrock costs stored in Valkey
• Reuses existing customer model, billing system, and dashboard
• Differentiator is real — validators catch what other services miss

Revenue potential:

• 10 customers × 500 chunks/month = ~$213/month (Sonnet)
• 50 customers × 1,000 chunks/month = ~$2,135/month (Sonnet)
• Covers infrastructure costs and contributes to the ministry's mission

Time to market: 4-6 sessions to MVP. Core API in 1-2 sessions.