How I Translated a Technical Ebook from Spanish to English with Semantic QA in Python

import re
from dataclasses import dataclass
from typing import List

@dataclass
class Segment:
    content: str
    is_code: bool

def split_segments(text: str) -> List[Segment]:
    """
    Split markdown text into alternating prose and fenced code segments.
    Fence patterns: ```

lang ...

 ``` or ~~~ ... ~~~
    """
    pattern = re.compile(
        r'(```

[\w]*\n[\s\S]*?

```|~~~[\w]*\n[\s\S]*?~~~)',
        re.MULTILINE
    )
    segments: List[Segment] = []
    last_end = 0

    for match in pattern.finditer(text):
        # prose before this code block
        prose = text[last_end:match.start()]
        if prose.strip():
            segments.append(Segment(content=prose, is_code=False))
        # the code block itself
        segments.append(Segment(content=match.group(), is_code=True))
        last_end = match.end()

    # any trailing prose
    remainder = text[last_end:]
    if remainder.strip():
        segments.append(Segment(content=remainder, is_code=False))

    return segments

import httpx
import os

TRANSLATE_URL = "https://api.your-provider.com/translate"
API_KEY = os.environ["TRANSLATION_API_KEY"]

def translate_text(text: str, source_lang: str = "es", target_lang: str = "en") -> str:
    """
    Send a single prose segment to the translation API.
    Returns the translated string.
    """
    response = httpx.post(
        TRANSLATE_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "text": text,
            "source": source_lang,
            "target": target_lang,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["translated_text"]

import os
import math

def qa_segment(original: str, translated: str) -> dict:
    """
    Returns {"mode": str, "score": float, "passed": bool}.
    Mode is "cosine" when OPENAI_API_KEY is set, "word_ratio" otherwise.
    """
    if os.getenv("OPENAI_API_KEY"):
        return _cosine_qa(original, translated)
    return _word_ratio_qa(original, translated)


def _cosine_qa(original: str, translated: str) -> dict:
    """
    Embed both strings and compute cosine similarity.
    Requires: pip install openai
    Threshold: 0.75 (cross-lingual embeddings stay high for equivalent content).
    """
    from openai import OpenAI
    client = OpenAI()

    def embed(text: str):
        resp = client.embeddings.create(
            model="text-embedding-3-small",
            input=text[:8000],  # truncate to model limit
        )
        return resp.data[0].embedding

    vec_a = embed(original)
    vec_b = embed(translated)

    dot = sum(a * b for a, b in zip(vec_a, vec_b))
    mag_a = math.sqrt(sum(a ** 2 for a in vec_a))
    mag_b = math.sqrt(sum(b ** 2 for b in vec_b))
    similarity = dot / (mag_a * mag_b)

    return {"mode": "cosine", "score": round(similarity, 4), "passed": similarity >= 0.75}


def _word_ratio_qa(original: str, translated: str) -> dict:
    """
    Fallback: compare word counts. A good translation of ES→EN prose
    typically expands by 0–25%. Flag anything outside 0.6–1.5x.
    """
    orig_words = len(original.split())
    trans_words = len(translated.split())
    ratio = trans_words / orig_words if orig_words else 0
    passed = 0.6 <= ratio <= 1.5
    return {"mode": "word_ratio", "score": round(ratio, 4), "passed": passed}

def translate_chapter(text: str) -> str:
    segments = split_segments(text)
    output_parts = []
    failures = []

    for i, seg in enumerate(segments):
        if seg.is_code:
            output_parts.append(seg.content)
            continue

        translated = translate_text(seg.content)
        qa_result = qa_segment(seg.content, translated)

        if not qa_result["passed"]:
            failures.append({
                "segment_index": i,
                "mode": qa_result["mode"],
                "score": qa_result["score"],
                "original_preview": seg.content[:120],
            })

        output_parts.append(translated)

    if failures:
        print(f"[WARN] {len(failures)} segment(s) failed QA:")
        for f in failures:
            print(f"  [{f['mode']}] segment {f['segment_index']} "
                  f"score={f['score']}: {f['original_preview']!r}")

    return "\n".join(output_parts)