translations

app.py

@@ -32,15 +32,17 @@ try:
 except ImportError:
     logger.warning("python-dotenv not installed, skipping .env loading")
 
+from comic_gen.text_utils import UI_TRANSLATIONS
 
 LANGUAGE_OPTIONS = {
     "English": "en",
+    "Portuguese": "pt",
     "Espanol": "es",
     "Francais": "fr",
     "Deutsch": "de",
 }
 
-_VERSION = 0.13
+_VERSION = 0.14
 STYLE_OPTIONS = ["minimal", "newspaper", "watercolor", "retro"]
 READING_LEVEL_OPTIONS = ["A1", "A2", "B1", "B2"]
 MAX_SEED = 2**31 - 1
@@ -59,25 +61,75 @@ def _select_image_model(use_serverless_api: bool) -> str:
     return SPACES_IMAGE_MODEL_ID
 
 
+def _language_code_for_label(language_label: str) -> str:
+    """Return the app language code for a dropdown label."""
+    return LANGUAGE_OPTIONS.get(language_label, "en")
+
+
+def _ui_text(language_code: str, key: str) -> str:
+    """Return localized UI text with English fallback."""
+    language = language_code if language_code in UI_TRANSLATIONS else "en"
+    return UI_TRANSLATIONS.get(language, {}).get(
+        key,
+        UI_TRANSLATIONS["en"].get(key, key),
+    )
+
+
+def _localized_ui_updates(language_label: str) -> tuple[Any, ...]:
+    """Build Gradio updates for static UI text."""
+    language = _language_code_for_label(language_label)
+    return (
+        gr.update(value=f"{_ui_text(language, 'app_subtitle')} {_VERSION}"),
+        gr.update(label=_ui_text(language, "language")),
+        gr.update(label=_ui_text(language, "art_style")),
+        gr.update(label=_ui_text(language, "reading_level")),
+        gr.update(label=_ui_text(language, "panel_count")),
+        gr.update(label=_ui_text(language, "live_feed")),
+        gr.update(label=_ui_text(language, "serverless")),
+        gr.update(label=_ui_text(language, "debug")),
+        gr.update(
+            label=_ui_text(language, "negative_prompt"),
+            placeholder=_ui_text(language, "negative_prompt_placeholder"),
+        ),
+        gr.update(label=_ui_text(language, "seed")),
+        gr.update(label=_ui_text(language, "randomize_seed")),
+        gr.update(label=_ui_text(language, "width")),
+        gr.update(label=_ui_text(language, "height")),
+        gr.update(label=_ui_text(language, "guidance_scale")),
+        gr.update(label=_ui_text(language, "inference_steps")),
+        gr.update(value=_ui_text(language, "generate")),
+        gr.update(value=_ui_text(language, "exercises_heading")),
+        gr.update(label=_ui_text(language, "select_panel")),
+        gr.update(value=_ui_text(language, "unlock_exercises")),
+        gr.update(
+            label=_ui_text(language, "answer_label"),
+            placeholder=_ui_text(language, "answer_placeholder"),
+        ),
+        gr.update(value=_ui_text(language, "submit")),
+    )
+
+
 def _render_source(document: dict[str, Any]) -> str:
+    language = str(document.get("language", "en"))
     source = document["source"]
     article = document["article"]
     return (
-        f"### Source\n"
-        f"- Publisher: {source['publisher']}\n"
-        f"- Title: {article['title']}\n"
-        f"- Link: {source['link']}\n"
-        f"- Published: {source['published_at']}"
+        f"### {_ui_text(language, 'source')}\n"
+        f"- {_ui_text(language, 'publisher')}: {source['publisher']}\n"
+        f"- {_ui_text(language, 'title')}: {article['title']}\n"
+        f"- {_ui_text(language, 'link')}: {source['link']}\n"
+        f"- {_ui_text(language, 'published')}: {source['published_at']}"
     )
 
 
 def _render_summary(document: dict[str, Any]) -> str:
+    language = str(document.get("language", "en"))
     simplified = document["simplified"]
     keywords = ", ".join(simplified.get("keywords", []))
     return (
-        f"### Simplified Summary ({simplified['level']})\n"
+        f"### {_ui_text(language, 'summary')} ({simplified['level']})\n"
         f"{simplified['summary']}\n\n"
-        f"Keywords: {keywords}"
+        f"{_ui_text(language, 'keywords')}: {keywords}"
     )
 
 
@@ -164,8 +216,8 @@ def _overlay_bubbles_html(
             "width:max-content;height:auto;"
             "box-sizing:border-box;z-index:5;pointer-events:none;"
             "display:flex;align-items:center;justify-content:center;"
-            "padding:3px 6px;border:1px solid rgba(17,24,39,0.92);"
-            "border-radius:10px;background:rgba(255,255,255,0.94);"
+            "padding:2px 5px;border:1px solid rgba(17,24,39,0.92);"
+            "border-radius:8px;background:rgba(255,255,255,0.94);"
             "box-shadow:0 2px 8px rgba(17,24,39,0.18);"
             "overflow:hidden;"
         )
@@ -227,7 +279,8 @@ def _render_panels_html(
 
 
 def _render_transcript(document: dict[str, Any]) -> str:
-    lines: list[str] = ["### Transcript"]
+    language = str(document.get("language", "en"))
+    lines: list[str] = [f"### {_ui_text(language, 'transcript')}"]
 
     # Use enumerate to track if we are on the first panel or a later one
     for i, panel in enumerate(document.get("panels", [])):
@@ -235,7 +288,9 @@ def _render_transcript(document: dict[str, Any]) -> str:
         if i > 0:
             lines.append("")
 
-        lines.append(f"PANEL {panel['frame_index']}")
+        lines.append(
+            f"{_ui_text(language, 'panel').upper()} {panel['frame_index']}"
+        )
         for line in panel.get("dialogue", []):
             lines.append(f"- {line['character_id']}: {line['text']}")
 
@@ -243,8 +298,9 @@ def _render_transcript(document: dict[str, Any]) -> str:
 
 
 def _panel_choices(document: dict[str, Any]) -> list[tuple[str, str]]:
+    language = str(document.get("language", "en"))
     return [
-        (f"Panel {p['frame_index']}", p["panel_id"])
+        (f"{_ui_text(language, 'panel')} {p['frame_index']}", p["panel_id"])
         for p in document.get("panels", [])
     ]
 
@@ -417,8 +473,9 @@ def load_exercise(
     document: dict[str, Any],
 ) -> tuple[str, str]:
     if not document:
-        return "Generate a strip first.", ""
+        return _ui_text("en", "generate_first"), ""
 
+    language = str(document.get("language", "en"))
     panel_id = _panel_id_for_selection(selected_panel, document)
     exercise_item = next(
         (
@@ -429,9 +486,9 @@ def load_exercise(
         None,
     )
     if not exercise_item:
-        return "No exercise available for this panel.", ""
+        return _ui_text(language, "no_exercise"), ""
 
-    return f"### Exercise\n{exercise_item['prompt']}", ""
+    return f"### {_ui_text(language, 'exercise')}\n{exercise_item['prompt']}", ""
 
 
 def submit_answer(
@@ -440,7 +497,7 @@ def submit_answer(
     document: dict[str, Any],
 ) -> str:
     if not document:
-        return "Generate a strip first."
+        return _ui_text("en", "generate_first")
     panel_id = _panel_id_for_selection(selected_panel, document)
     ok, feedback = exercise.evaluate_answer(document, panel_id, answer)
     status = "ok" if ok else "retry"
@@ -455,7 +512,7 @@ with gr.Blocks() as demo:
         if APP_CSS:
             gr.HTML(f"<style>{APP_CSS}</style>")
         gr.Markdown("# Anti-Ill Comix")
-        gr.Markdown(
+        subtitle_md = gr.Markdown(
             (
                 "Turn international news into simple comic practice "
                 f"for adult reading and writing. {_VERSION}"
@@ -553,7 +610,7 @@ with gr.Blocks() as demo:
         panel_html = gr.HTML()
         transcript_md = gr.Markdown(elem_id="transcript_md")
 
-        gr.Markdown("### Writing Exercises")
+        exercises_heading = gr.Markdown("### Writing Exercises")
         panel_selector = gr.Dropdown(
             choices=[],
             label="Select panel",
@@ -601,6 +658,34 @@ with gr.Blocks() as demo:
         ],
     )
 
+    language_input.change(
+        fn=_localized_ui_updates,
+        inputs=language_input,
+        outputs=[
+            subtitle_md,
+            language_input,
+            style_input,
+            reading_level_input,
+            panel_count,
+            live_feed_input,
+            use_serverless_api_input,
+            debug_mode_input,
+            negative_prompt_input,
+            seed_input,
+            randomize_seed_input,
+            width_input,
+            height_input,
+            guidance_scale_input,
+            num_steps_input,
+            generate_button,
+            exercises_heading,
+            panel_selector,
+            exercise_md,
+            answer_input,
+            submit_button,
+        ],
+    )
+
     panel_selector.change(
         fn=load_exercise,
         inputs=[panel_selector, session_state],

comic_gen/__init__.py

@@ -7,6 +7,7 @@ from . import (
     session,
     text_backend,
     trace,
+    translation_backend,
 )
 from .models import ValidationError, validate_session_document
 
@@ -19,6 +20,7 @@ __all__ = [
     "session",
     "text_backend",
     "trace",
+    "translation_backend",
     "ValidationError",
     "validate_session_document",
 ]

comic_gen/comics.py

@@ -11,6 +11,7 @@ from .text_backend import (
 )
 from .text_utils import _normalize_model_fields
 from .backends import deterministic_pipeline
+from .translation_backend import translate_session_content
 from .trace import add_trace
 from .errors import ModelPipelineError
 
@@ -94,11 +95,12 @@ def generate_story_pipeline(
 ) -> None:
     options = _normalized_image_options(image_options)
     options["enable_live_images"] = True
+    target_language = str(document.get("language", "en"))
     logger.info("Running unified model pipeline (text + image)")
 
     try:
         generated = generate_text_content_from_article(
-            language=str(document.get("language", "en")),
+            language="en",
             style_id=str(document.get("style_id", "minimal")),
             reading_level=reading_level,
             article=document.get("article", {}),
@@ -124,6 +126,19 @@ def generate_story_pipeline(
         document["characters"] = characters
         document["panels"] = panels
         document["exercises"] = exercises_data
+        try:
+            translate_session_content(
+                document,
+                target_language,
+                source_language="en",
+            )
+        except Exception as exc:
+            add_trace(
+                document,
+                "translation",
+                "fallback",
+                f"Translation failed, keeping canonical content: {exc}",
+            )
         add_trace(
             document,
             "model_pipeline",
@@ -163,3 +178,16 @@ def generate_story_pipeline(
             document,
         )
         document.setdefault("simplified", {})["level"] = reading_level
+        try:
+            translate_session_content(
+                document,
+                target_language,
+                source_language=str(document.get("language", target_language)),
+            )
+        except Exception as translate_exc:
+            add_trace(
+                document,
+                "translation",
+                "fallback",
+                f"Translation failed after deterministic fallback: {translate_exc}",
+            )

comic_gen/exercise.py

@@ -5,6 +5,43 @@ from typing import Any
 
 from .trace import add_trace
 
+FEEDBACK_TRANSLATIONS = {
+    "en": {
+        "missing": "Exercise not found for the selected panel.",
+        "correct": "Correct. Great writing practice.",
+        "retry": "Not yet. Try again with a central word from the panel (expected: {expected}).",
+    },
+    "pt": {
+        "missing": "Exercicio nao encontrado para o quadro selecionado.",
+        "correct": "Correto. Otima pratica de escrita.",
+        "retry": "Ainda nao. Tente outra vez com uma palavra central do quadro (esperado: {expected}).",
+    },
+    "es": {
+        "missing": "No se encontro ejercicio para la vineta seleccionada.",
+        "correct": "Correcto. Buena practica de escritura.",
+        "retry": "Todavia no. Intenta otra vez con una palabra central de la vineta (esperado: {expected}).",
+    },
+    "fr": {
+        "missing": "Aucun exercice trouve pour la case choisie.",
+        "correct": "Correct. Bonne pratique d'ecriture.",
+        "retry": "Pas encore. Reessayez avec un mot central de la case (attendu: {expected}).",
+    },
+    "de": {
+        "missing": "Keine Uebung fuer das ausgewaehlte Bild gefunden.",
+        "correct": "Richtig. Gute Schreibuebung.",
+        "retry": "Noch nicht. Versuche es mit einem wichtigen Wort aus dem Bild (erwartet: {expected}).",
+    },
+}
+
+
+def _feedback_text(language: str, key: str, **kwargs: str) -> str:
+    """Return localized exercise feedback text."""
+    template = FEEDBACK_TRANSLATIONS.get(language, FEEDBACK_TRANSLATIONS["en"]).get(
+        key,
+        FEEDBACK_TRANSLATIONS["en"][key],
+    )
+    return template.format(**kwargs)
+
 
 def _pick_keyword(document: dict[str, Any], fallback: str) -> str:
     keywords = document.get("simplified", {}).get("keywords", [])
@@ -77,19 +114,20 @@ def evaluate_answer(
         None,
     )
     if not exercise:
-        return False, "Exercise not found for the selected panel."
+        return False, _feedback_text(
+            str(document.get("language", "en")),
+            "missing",
+        )
 
     expected = exercise["answer_key"][0]
     normalized_user = user_answer.strip().lower()
     normalized_expected = expected.strip().lower()
     ok = normalized_user == normalized_expected
+    language = str(document.get("language", "en"))
     if ok:
-        return True, "Correct. Great writing practice."
+        return True, _feedback_text(language, "correct")
 
     return (
         False,
-        (
-            "Not yet. Try again with a central word from the panel "
-            f"(expected: {expected})."
-        ),
+        _feedback_text(language, "retry", expected=expected),
     )

comic_gen/image_backend.py

@@ -43,11 +43,11 @@ def build_image_prompt(document: dict[str, Any], panel: dict[str, Any]) -> str:
     scene = _compact_text(panel.get("scene_description", ""), 70)
     style_id = _compact_text(document.get("style_id", "minimal"), 32)
     parts = [
-        # "Plain comic scene only.",
+        "Plain comic scene only.",
         "Characters and background only.",
         f"Scene: {scene}.",
         f"Keep strict {style_id} style.",
-        # "Empty margins for later overlay.",
+        "Empty margins for later overlay.",
     ]
     return " ".join(part for part in parts if part and not part.endswith(": "))
 
@@ -281,11 +281,13 @@ def _generate_panel_image(
     num_inference_steps: int,
     use_serverless_api: bool,
 ) -> tuple[str, int, str]:
+    if isinstance(model_repo_id, (list, tuple)):
+        model_repo_id = str(model_repo_id[0] if model_repo_id else "")
     chosen_seed = random.randint(0, MAX_SEED) if randomize_seed else seed
     logger.info(f'\n\nIMAGE gen prompt:\n {prompt}\n\n')
 
     last_error: BaseException | None = None
-    for attempt in range(1, 3):
+    for attempt in range(1, 4):
         started = perf_counter()
         try:
             if use_serverless_api:

comic_gen/prompts.py

@@ -19,13 +19,15 @@ UNIFIED_SESSION_PROMPT = (
     "- Do NOT output any conversational text before or after the JSON structure.\n"
     "- Use strict double quotes (\") for all keys and string values.\n"
     "- Generate exactly {panel_count} panels.\n"
+    "- Each must have at least one dialogue line and one bubble.\n"
+    "- Generate canonical learner content in English for stable parsing.\n"
     "- Set simplified.level exactly to {reading_level}.\n"
     "- Length of the 'panels' list must match the length of the 'exercises' list.\n"
     "- For each panel_id, there needs to be exactly one exercise in the 'exercises' list.\n"
     "- There can be 1-3 characters.\n\n"
     
     "### Context Parameters\n"
-    "- Target Language Code: {language}\n"
+    "- Canonical Generation Language Code: {language}\n"
     "- Comic Style ID: {style_id}\n\n"
     "- Reading Level: {reading_level}\n\n"
 

comic_gen/text_utils.py

@@ -78,6 +78,205 @@ class ComicResponse(BaseModel):
     exercises: List[Exercise]
 
 
+UI_TRANSLATIONS = {
+    "en": {
+        "app_subtitle": "Turn international news into simple comic practice for adult reading and writing.",
+        "language": "Language",
+        "art_style": "Art style",
+        "reading_level": "Reading level",
+        "panel_count": "Panel count",
+        "live_feed": "Use live RSS article",
+        "advanced_options": "Advanced Options",
+        "serverless": "Use HF serverless API for text + image generation",
+        "debug": "Debug panel rendering",
+        "negative_prompt": "Negative prompt",
+        "negative_prompt_placeholder": "Optional quality or style exclusions",
+        "seed": "Seed",
+        "randomize_seed": "Randomize seed",
+        "width": "Width",
+        "height": "Height",
+        "guidance_scale": "Guidance scale",
+        "inference_steps": "Inference steps",
+        "generate": "Generate Comic Strip",
+        "source": "Source",
+        "publisher": "Publisher",
+        "title": "Title",
+        "link": "Link",
+        "published": "Published",
+        "summary": "Simplified Summary",
+        "keywords": "Keywords",
+        "transcript": "Transcript",
+        "panel": "Panel",
+        "exercises_heading": "### Writing Exercises",
+        "select_panel": "Select panel",
+        "exercise": "Exercise",
+        "generate_first": "Generate a strip first.",
+        "unlock_exercises": "Generate a strip to unlock exercises.",
+        "no_exercise": "No exercise available for this panel.",
+        "answer_label": "Your answer",
+        "answer_placeholder": "Type the missing word",
+        "submit": "Submit Answer",
+        "trace": "Trace / Debug",
+    },
+    "pt": {
+        "app_subtitle": "Transforme noticias internacionais em pratica simples de leitura e escrita com quadrinhos.",
+        "language": "Idioma",
+        "art_style": "Estilo de arte",
+        "reading_level": "Nivel de leitura",
+        "panel_count": "Numero de quadros",
+        "live_feed": "Usar noticia RSS ao vivo",
+        "advanced_options": "Opcoes avancadas",
+        "serverless": "Usar API serverless HF para texto + imagem",
+        "debug": "Depurar quadros",
+        "negative_prompt": "Prompt negativo",
+        "negative_prompt_placeholder": "Exclusoes opcionais de qualidade ou estilo",
+        "seed": "Semente",
+        "randomize_seed": "Semente aleatoria",
+        "width": "Largura",
+        "height": "Altura",
+        "guidance_scale": "Escala de orientacao",
+        "inference_steps": "Passos de inferencia",
+        "generate": "Gerar quadrinhos",
+        "source": "Fonte",
+        "publisher": "Publicador",
+        "title": "Titulo",
+        "link": "Link",
+        "published": "Publicado",
+        "summary": "Resumo simplificado",
+        "keywords": "Palavras-chave",
+        "transcript": "Transcricao",
+        "panel": "Quadro",
+        "exercises_heading": "### Exercicios de escrita",
+        "select_panel": "Selecionar quadro",
+        "exercise": "Exercicio",
+        "generate_first": "Gere uma tira primeiro.",
+        "unlock_exercises": "Gere uma tira para liberar os exercicios.",
+        "no_exercise": "Nao ha exercicio para este quadro.",
+        "answer_label": "Sua resposta",
+        "answer_placeholder": "Digite a palavra que falta",
+        "submit": "Enviar resposta",
+        "trace": "Rastro / Debug",
+    },
+    "es": {
+        "app_subtitle": "Convierte noticias internacionales en practica simple de lectura y escritura con comics.",
+        "language": "Idioma",
+        "art_style": "Estilo artistico",
+        "reading_level": "Nivel de lectura",
+        "panel_count": "Numero de vinetas",
+        "live_feed": "Usar noticia RSS en vivo",
+        "advanced_options": "Opciones avanzadas",
+        "serverless": "Usar API serverless HF para texto + imagen",
+        "debug": "Depurar vinetas",
+        "negative_prompt": "Prompt negativo",
+        "negative_prompt_placeholder": "Exclusiones opcionales de calidad o estilo",
+        "seed": "Semilla",
+        "randomize_seed": "Semilla aleatoria",
+        "width": "Ancho",
+        "height": "Alto",
+        "guidance_scale": "Escala de guia",
+        "inference_steps": "Pasos de inferencia",
+        "generate": "Generar comic",
+        "source": "Fuente",
+        "publisher": "Editor",
+        "title": "Titulo",
+        "link": "Enlace",
+        "published": "Publicado",
+        "summary": "Resumen simplificado",
+        "keywords": "Palabras clave",
+        "transcript": "Transcripcion",
+        "panel": "Vineta",
+        "exercises_heading": "### Ejercicios de escritura",
+        "select_panel": "Seleccionar vineta",
+        "exercise": "Ejercicio",
+        "generate_first": "Primero genera una tira.",
+        "unlock_exercises": "Genera una tira para desbloquear ejercicios.",
+        "no_exercise": "No hay ejercicio para esta vineta.",
+        "answer_label": "Tu respuesta",
+        "answer_placeholder": "Escribe la palabra que falta",
+        "submit": "Enviar respuesta",
+        "trace": "Traza / Debug",
+    },
+    "fr": {
+        "app_subtitle": "Transformez des nouvelles internationales en pratique simple de lecture et d'ecriture avec BD.",
+        "language": "Langue",
+        "art_style": "Style artistique",
+        "reading_level": "Niveau de lecture",
+        "panel_count": "Nombre de cases",
+        "live_feed": "Utiliser une nouvelle RSS en direct",
+        "advanced_options": "Options avancees",
+        "serverless": "Utiliser l'API HF serverless pour texte + image",
+        "debug": "Debug des cases",
+        "negative_prompt": "Prompt negatif",
+        "negative_prompt_placeholder": "Exclusions optionnelles de qualite ou de style",
+        "seed": "Graine",
+        "randomize_seed": "Graine aleatoire",
+        "width": "Largeur",
+        "height": "Hauteur",
+        "guidance_scale": "Echelle de guidage",
+        "inference_steps": "Etapes d'inference",
+        "generate": "Generer la BD",
+        "source": "Source",
+        "publisher": "Editeur",
+        "title": "Titre",
+        "link": "Lien",
+        "published": "Publie",
+        "summary": "Resume simplifie",
+        "keywords": "Mots cles",
+        "transcript": "Transcription",
+        "panel": "Case",
+        "exercises_heading": "### Exercices d'ecriture",
+        "select_panel": "Choisir une case",
+        "exercise": "Exercice",
+        "generate_first": "Generez d'abord une BD.",
+        "unlock_exercises": "Generez une BD pour ouvrir les exercices.",
+        "no_exercise": "Aucun exercice pour cette case.",
+        "answer_label": "Votre reponse",
+        "answer_placeholder": "Tapez le mot manquant",
+        "submit": "Envoyer la reponse",
+        "trace": "Trace / Debug",
+    },
+    "de": {
+        "app_subtitle": "Verwandle internationale Nachrichten in einfache Lese- und Schreibuebung mit Comics.",
+        "language": "Sprache",
+        "art_style": "Kunststil",
+        "reading_level": "Leseniveau",
+        "panel_count": "Anzahl der Bilder",
+        "live_feed": "Live-RSS-Nachricht verwenden",
+        "advanced_options": "Erweiterte Optionen",
+        "serverless": "HF Serverless API fuer Text + Bild verwenden",
+        "debug": "Bilder debuggen",
+        "negative_prompt": "Negativer Prompt",
+        "negative_prompt_placeholder": "Optionale Qualitaets- oder Stil-Ausschluesse",
+        "seed": "Seed",
+        "randomize_seed": "Zufaelliger Seed",
+        "width": "Breite",
+        "height": "Hoehe",
+        "guidance_scale": "Fuehrungsstaerke",
+        "inference_steps": "Inferenzschritte",
+        "generate": "Comic erzeugen",
+        "source": "Quelle",
+        "publisher": "Herausgeber",
+        "title": "Titel",
+        "link": "Link",
+        "published": "Veroeffentlicht",
+        "summary": "Vereinfachte Zusammenfassung",
+        "keywords": "Schluesselwoerter",
+        "transcript": "Transkript",
+        "panel": "Bild",
+        "exercises_heading": "### Schreibuebungen",
+        "select_panel": "Bild auswaehlen",
+        "exercise": "Uebung",
+        "generate_first": "Erzeuge zuerst einen Comic.",
+        "unlock_exercises": "Erzeuge einen Comic, um Uebungen zu oeffnen.",
+        "no_exercise": "Keine Uebung fuer dieses Bild.",
+        "answer_label": "Deine Antwort",
+        "answer_placeholder": "Gib das fehlende Wort ein",
+        "submit": "Antwort senden",
+        "trace": "Trace / Debug",
+    },
+}
+
+
 def load_json_article(language: str) -> dict[str, str]:
     repo_root = Path(__file__).resolve().parents[1]
     example_path = repo_root / "examples" / f"{language}_demo.json"
@@ -346,8 +545,8 @@ def _box_overlap_ratio(first: list[int], second: list[int]) -> float:
 
 def _normalize_bbox(
     raw: Any,
-    min_width: int = 90,
-    min_height: int = 30,
+    min_width: int = 82,
+    min_height: int = 24,
 ) -> tuple[list[int], bool]:
     """Normalize one bubble box and report whether it needed repair."""
     if not isinstance(raw, list) or len(raw) != 4:
@@ -460,89 +659,3 @@ def extract_json_object(raw_text: str) -> dict[str, Any]:
         return json_dict
         
     raise UnifiedGenerationError("model output is not valid JSON")
-
-
-# def extract_json_object(raw_text: str) -> dict[str, Any]:
-#     start = raw_text.find("{")
-#     end = raw_text.rfind("}")
-#     if start == -1 or end == -1 or end <= start:
-#         raise UnifiedGenerationError("model output missing JSON object")
-#     try:
-#         parsed = json.loads(raw_text[start:end + 1])
-#     except json.JSONDecodeError as exc:
-#         logger.info("INPUT to parse JSON: %s", raw_text[start:end + 1])
-#         raise UnifiedGenerationError("model output is not valid JSON") from exc
-#     if not isinstance(parsed, dict):
-#         raise UnifiedGenerationError("model output root must be object")
-#     return parsed 
-
-# def extract_json_object(raw_text: str) -> dict[str, Any]:
-#     def _balanced_json_objects(text: str) -> list[str]:
-#         objects: list[str] = []
-#         start_idx = -1
-#         depth = 0
-#         in_string = False
-#         escaped = False
-
-#         for idx, char in enumerate(text):
-#             if in_string:
-#                 if escaped:
-#                     escaped = False
-#                     continue
-#                 if char == "\\":
-#                     escaped = True
-#                 elif char == '"':
-#                     in_string = False
-#                 continue
-
-#             if char == '"':
-#                 in_string = True
-#             elif char == "{":
-#                 if depth == 0:
-#                     start_idx = idx
-#                 depth += 1
-#             elif char == "}" and depth > 0:
-#                 depth -= 1
-#                 if depth == 0 and start_idx != -1:
-#                     objects.append(text[start_idx: idx + 1])
-#                     start_idx = -1
-
-#         return objects
-
-#     candidates: list[str] = []
-#     fenced_matches = re.findall(r"```(?:json)?\\s*([\\s\\S]*?)```", raw_text)
-#     candidates.extend(
-#         match.strip()
-#         for match in fenced_matches
-#         if match.strip()
-#     )
-#     candidates.append(raw_text)
-
-#     decoder = json.JSONDecoder()
-#     parse_errors: list[str] = []
-
-#     for candidate in candidates:
-#         for blob in _balanced_json_objects(candidate):
-#             try:
-#                 parsed, end_idx = decoder.raw_decode(blob)
-#                 if blob[end_idx:].strip():
-#                     parse_errors.append("trailing_non_json_content")
-#                     continue
-#                 if not isinstance(parsed, dict):
-#                     parse_errors.append("root_not_object")
-#                     continue
-#                 return parsed
-#             except json.JSONDecodeError as exc:
-#                 context_start = max(0, exc.pos - 40)
-#                 context_end = min(len(blob), exc.pos + 40)
-#                 context = blob[context_start:context_end]
-#                 parse_errors.append(
-#                     f"{exc.msg} at line {exc.lineno}, col {exc.colno}, "
-#                     f"pos {exc.pos}; context={context!r}"
-#                 )
-
-#     if "{" not in raw_text or "}" not in raw_text:
-#         raise UnifiedGenerationError("model output missing JSON object")
-
-#     logger.info("Failed JSON parse details: %s", " | ".join(parse_errors))
-#     raise UnifiedGenerationError("model output is not valid JSON")

comic_gen/translation_backend.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .trace import add_trace
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TRANSLATION_MODEL_ID = "facebook/nllb-200-distilled-600M"
+NLLB_LANGUAGE_CODES = {
+    "en": "eng_Latn",
+    "pt": "por_Latn",
+    "es": "spa_Latn",
+    "fr": "fra_Latn",
+    "de": "deu_Latn",
+}
+PLACEHOLDER_TOKEN = "__BLANK_PLACEHOLDER__"
+_PIPELINES: dict[tuple[str, str, str], Any] = {}
+
+
+def _get_translation_pipeline(
+    model_id: str,
+    source_language: str,
+    target_language: str,
+) -> Any:
+    """Load and cache a translation pipeline.
+
+    Args:
+        model_id: Hugging Face model id.
+        source_language: NLLB source language code.
+        target_language: NLLB target language code.
+
+    Returns:
+        A callable Transformers translation pipeline.
+    """
+    cache_key = (model_id, source_language, target_language)
+    if cache_key in _PIPELINES:
+        return _PIPELINES[cache_key]
+
+    from transformers import pipeline
+
+    translator = pipeline(
+        "translation",
+        model=model_id,
+        src_lang=source_language,
+        tgt_lang=target_language,
+    )
+    _PIPELINES[cache_key] = translator
+    return translator
+
+
+def _translation_result_text(result: Any) -> str:
+    """Extract text from a Transformers translation result."""
+    if isinstance(result, list) and result:
+        first = result[0]
+        if isinstance(first, dict):
+            return str(first.get("translation_text", "")).strip()
+    if isinstance(result, dict):
+        return str(result.get("translation_text", "")).strip()
+    return str(result or "").strip()
+
+
+def translate_text(
+    text: Any,
+    target_language: str,
+    *,
+    source_language: str = "en",
+    model_id: str = DEFAULT_TRANSLATION_MODEL_ID,
+    preserve_blanks: bool = False,
+) -> str:
+    """Translate text to the target language.
+
+    Args:
+        text: Source text.
+        target_language: App language code.
+        source_language: App source language code.
+        model_id: Hugging Face translation model id.
+        preserve_blanks: Whether to protect blank placeholders.
+
+    Returns:
+        Translated text, or the source text for English/no-op cases.
+    """
+    value = str(text or "").strip()
+    if not value:
+        return value
+
+    source_code = NLLB_LANGUAGE_CODES.get(source_language, "eng_Latn")
+    target_code = NLLB_LANGUAGE_CODES.get(target_language, "eng_Latn")
+    if source_code == target_code:
+        return value
+
+    protected = value
+    if preserve_blanks:
+        protected = protected.replace("_______", PLACEHOLDER_TOKEN)
+        protected = protected.replace("____", PLACEHOLDER_TOKEN)
+
+    translator = _get_translation_pipeline(model_id, source_code, target_code)
+    translated = _translation_result_text(translator(protected))
+    translated = translated or value
+    if preserve_blanks:
+        translated = translated.replace(PLACEHOLDER_TOKEN, "____")
+        if "____" not in translated and "____" in value:
+            translated = f"{translated} ____"
+    return translated
+
+
+def translate_session_content(
+    document: dict[str, Any],
+    target_language: str,
+    *,
+    source_language: str = "en",
+    model_id: str = DEFAULT_TRANSLATION_MODEL_ID,
+) -> bool:
+    """Translate learner-facing session fields in place.
+
+    Args:
+        document: Session document to mutate.
+        target_language: App target language code.
+        source_language: App source language code.
+        model_id: Hugging Face translation model id.
+
+    Returns:
+        True when translation was applied, False for no-op English.
+    """
+    if NLLB_LANGUAGE_CODES.get(source_language) == NLLB_LANGUAGE_CODES.get(
+        target_language
+    ):
+        return False
+
+    add_trace(
+        document,
+        "translation",
+        "start",
+        f"Translating learner content to {target_language}",
+    )
+
+    simplified = document.get("simplified", {})
+    if isinstance(simplified, dict):
+        simplified["summary"] = translate_text(
+            simplified.get("summary", ""),
+            target_language,
+            source_language=source_language,
+            model_id=model_id,
+        )
+        keywords = simplified.get("keywords", [])
+        if isinstance(keywords, list):
+            simplified["keywords"] = [
+                translate_text(
+                    keyword,
+                    target_language,
+                    source_language=source_language,
+                    model_id=model_id,
+                )
+                for keyword in keywords
+            ]
+
+    for character in document.get("characters", []):
+        if not isinstance(character, dict):
+            continue
+        character["description"] = translate_text(
+            character.get("description", ""),
+            target_language,
+            source_language=source_language,
+            model_id=model_id,
+        )
+
+    for panel in document.get("panels", []):
+        if not isinstance(panel, dict):
+            continue
+        panel["scene_description"] = translate_text(
+            panel.get("scene_description", ""),
+            target_language,
+            source_language=source_language,
+            model_id=model_id,
+        )
+        for line in panel.get("dialogue", []):
+            if not isinstance(line, dict):
+                continue
+            line["text"] = translate_text(
+                line.get("text", ""),
+                target_language,
+                source_language=source_language,
+                model_id=model_id,
+            )
+
+    for item in document.get("exercises", []):
+        if not isinstance(item, dict):
+            continue
+        item["prompt"] = translate_text(
+            item.get("prompt", ""),
+            target_language,
+            source_language=source_language,
+            model_id=model_id,
+            preserve_blanks=True,
+        )
+
+    add_trace(
+        document,
+        "translation",
+        "ok",
+        f"Translated learner content to {target_language}",
+    )
+    return True

examples/de_demo.json

@@ -0,0 +1,158 @@
+{
+  "schema_version": "1.0.0",
+  "session_id": "sess-demo-de-001",
+  "language": "de",
+  "style_id": "minimal",
+  "source": {
+    "link": "https://www.theguardian.com/technology/2026/jun/08/anti-slop-ai-art",
+    "publisher": "The Guardian",
+    "published_at": "Mon, 08 Jun 2026 13:00:25 GMT"
+  },
+  "article": {
+    "title": "Kuenstler machen 'Anti-Muell'-Kunst als Protest gegen KI: 'Es wurde uns aufgezwungen'",
+    "fulltext": "Als Reaktion auf den Hyperrealismus der KI wenden sich Kuenstler und Kreative dem Selbstgemachten und Unvollkommenen zu. Anfang dieses Jahres traf sich in New York eine Gruppe von Filmemachern, Werberegisseuren und Einflussnehmern der KI-Branche zum Runway AI Summit, einer eintagigen Veranstaltung, die das Potenzial dieser neuen Technologie stark hervorhob. In einem Vortrag sprach Rob Wrubel, Mitgruender und geschaeftsfuehrender Partner der Werbefirma Silverside in San Francisco, ueber seine Arbeit an der KI-generierten Coca-Cola-Werbung Holiday Caravan 2025. Wrubel sagte, das Unglaubliche an KI sei, dass man in nur zwei Wochen vom Drehbuch zur Produktion kommen koenne. Was er nicht erwaehnte: Die Werbung mit computergenerierten Eisbaeren und unecht wirkenden Lieferwagen wurde von fast allen, die sie sahen, stark abgelehnt. Die oeffentliche Ablehnung wurde zu einer eigenen Nachricht. Sie wurde vielleicht schnell entworfen, und genau so sah sie aus. Auf die Reaktion angesprochen, gab Wrubel zu, dass das Gespraech ueber die Werbung fast so wichtig wurde wie die Werbung selbst, weil es Fragen sichtbar machte, mit denen sich die ganze Kreativbranche derzeit beschaeftigt."
+  },
+  "simplified": {
+    "summary": "Erwachsene nutzen das Gartenprogramm, um Lesen und Schreiben in einfachen Schritten zu ueben.",
+    "level": "A2",
+    "keywords": ["Erwachsene", "Garten", "Lesen", "Schreiben"]
+  },
+  "characters": [
+    {
+      "id": "char_guide",
+      "name": "Anleiter",
+      "description": "Mentor mit einfacher Sprache."
+    },
+    {
+      "id": "char_learner",
+      "name": "Lernende",
+      "description": "Erwachsene Person, die Lesen und Schreiben uebt."
+    }
+  ],
+  "panels": [
+    {
+      "panel_id": "panel_1",
+      "frame_index": 1,
+      "scene_description": "Zwei Erwachsene lesen eine kurze Anweisungskarte in einem Garten.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Wir lesen zusammen eine kurze Anweisung."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Jetzt kann ich sie mit eigenen Worten erklaeren."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_1.png",
+        "overlay_applied": true
+      }
+    },
+    {
+      "panel_id": "panel_2",
+      "frame_index": 2,
+      "scene_description": "Die Lernende schreibt einen kurzen Satz ueber die Aktivitaet.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Schreibe eine wichtige Idee aus dem Artikel."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Der Garten hilft mir jede Woche beim Lesenueben."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_2.png",
+        "overlay_applied": true
+      }
+    },
+    {
+      "panel_id": "panel_3",
+      "frame_index": 3,
+      "scene_description": "Die Gruppe teilt, was sie gelernt hat.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Du hast dein Schreiben mit klaren Worten verbessert."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Ich fuehle mich jetzt sicherer beim Lesen von Nachrichten."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_3.png",
+        "overlay_applied": true
+      }
+    }
+  ],
+  "exercises": [
+    {
+      "exercise_id": "ex_panel_1",
+      "panel_id": "panel_1",
+      "prompt": "Wir lesen zusammen eine kurze ____.",
+      "blanks": ["____"],
+      "answer_key": ["Anweisung"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    },
+    {
+      "exercise_id": "ex_panel_2",
+      "panel_id": "panel_2",
+      "prompt": "Schreibe eine wichtige Idee aus dem ____.",
+      "blanks": ["____"],
+      "answer_key": ["Artikel"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    },
+    {
+      "exercise_id": "ex_panel_3",
+      "panel_id": "panel_3",
+      "prompt": "Ich fuehle mich jetzt sicherer beim Lesen von ____.",
+      "blanks": ["____"],
+      "answer_key": ["Nachrichten"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    }
+  ],
+  "trace": [
+    {
+      "ts": "2026-06-07T00:00:00+00:00",
+      "step": "demo",
+      "status": "ok",
+      "message": "Deterministisches Beispiel"
+    }
+  ]
+}

examples/es_demo.json

@@ -2,26 +2,26 @@
   "schema_version": "1.0.0",
   "session_id": "sess-demo-es-001",
   "language": "es",
-  "style_id": "watercolor",
+  "style_id": "minimal",
   "source": {
-    "link": "https://example.org/es/biblioteca-barrio",
-    "publisher": "Ejemplo Noticias",
-    "published_at": "2026-06-07T00:00:00+00:00"
+    "link": "https://www.theguardian.com/technology/2026/jun/08/anti-slop-ai-art",
+    "publisher": "The Guardian",
+    "published_at": "Mon, 08 Jun 2026 13:00:25 GMT"
   },
   "article": {
-    "title": "Una biblioteca de barrio impulsa la lectura adulta",
-    "fulltext": "Una biblioteca local inicio talleres semanales para personas adultas. Los participantes leen noticias breves y escriben resumenes con ayuda de un tutor."
+    "title": "Los artistas crean arte 'anti-basura' para rebelarse contra la IA: 'Nos lo han impuesto a la fuerza'",
+    "fulltext": "En respuesta al hiperrealismo de la IA, artistas y creativos se acercan a lo casero y lo imperfecto. A comienzos de este ano, un grupo de cineastas, directores comerciales e influyentes de la industria de la IA se reunio en Nueva York para la Runway AI Summit, un evento de un dia que exageraba el potencial de esta nueva tecnologia. Durante una charla, Rob Wrubel, cofundador y socio director de la agencia de publicidad Silverside de San Francisco, hablo de su trabajo en el anuncio Holiday Caravan 2025 de Coca-Cola, generado con IA. Wrubel dijo que lo increible de la IA es que permite pasar del guion a la produccion en solo dos semanas. Lo que no menciono fue que el anuncio, con osos polares computarizados y camiones de reparto falsos, fue muy rechazado por casi todos los que lo vieron. El rechazo publico se convirtio en una noticia propia. Aunque pudo crearse rapido, tambien se veia asi. Al comentar la reaccion, Wrubel admitio que la conversacion sobre el anuncio llego a ser casi tan importante como el anuncio mismo, porque saco a la luz preguntas que toda la industria creativa esta enfrentando ahora."
   },
   "simplified": {
-    "summary": "Las personas adultas practican lectura y escritura con noticias cortas.",
+    "summary": "Las personas adultas usan el programa del jardin para practicar lectura y escritura con pasos simples.",
     "level": "A2",
-    "keywords": ["adultas", "lectura", "escritura", "noticias"]
+    "keywords": ["adultos", "jardin", "lectura", "escritura"]
   },
   "characters": [
     {
       "id": "char_guide",
       "name": "Guia",
-      "description": "Mentora que explica con lenguaje claro."
+      "description": "Mentor que usa lenguaje claro."
     },
     {
       "id": "char_learner",
@@ -33,15 +33,15 @@
     {
       "panel_id": "panel_1",
       "frame_index": 1,
-      "scene_description": "Dos personas leen una noticia corta en la biblioteca.",
+      "scene_description": "Dos personas adultas leen una tarjeta breve de instrucciones en un jardin.",
       "dialogue": [
         {
           "character_id": "char_guide",
-          "text": "Leemos una noticia breve con palabras simples."
+          "text": "Leemos juntos una instruccion corta."
         },
         {
           "character_id": "char_learner",
-          "text": "Ahora entiendo mejor la idea principal."
+          "text": "Ahora puedo explicarla con mis propias palabras."
         }
       ],
       "bubbles": [
@@ -60,15 +60,15 @@
     {
       "panel_id": "panel_2",
       "frame_index": 2,
-      "scene_description": "La estudiante escribe un resumen corto.",
+      "scene_description": "La estudiante escribe una frase corta sobre la actividad.",
       "dialogue": [
         {
           "character_id": "char_guide",
-          "text": "Escribe una frase con la palabra clave."
+          "text": "Escribe una idea clave del articulo."
         },
         {
           "character_id": "char_learner",
-          "text": "La lectura me ayuda a escribir mejor."
+          "text": "El jardin me ayuda a practicar lectura cada semana."
         }
       ],
       "bubbles": [
@@ -87,15 +87,15 @@
     {
       "panel_id": "panel_3",
       "frame_index": 3,
-      "scene_description": "El grupo comparte lo aprendido.",
+      "scene_description": "El grupo comparte lo que aprendio.",
       "dialogue": [
         {
           "character_id": "char_guide",
-          "text": "Tu comprension mejora cada semana."
+          "text": "Mejoraste tu escritura con palabras claras."
         },
         {
           "character_id": "char_learner",
-          "text": "Tengo mas confianza para leer noticias."
+          "text": "Ahora tengo mas confianza para leer noticias."
         }
       ],
       "bubbles": [
@@ -116,9 +116,9 @@
     {
       "exercise_id": "ex_panel_1",
       "panel_id": "panel_1",
-      "prompt": "Leemos una noticia ____ con palabras simples.",
+      "prompt": "Leemos juntos una ____ corta.",
       "blanks": ["____"],
-      "answer_key": ["breve"],
+      "answer_key": ["instruccion"],
       "feedback_rules": {
         "case_sensitive": false,
         "allow_trim_spaces": true
@@ -127,9 +127,9 @@
     {
       "exercise_id": "ex_panel_2",
       "panel_id": "panel_2",
-      "prompt": "La lectura me ayuda a ____ mejor.",
+      "prompt": "Escribe una idea clave del ____.",
       "blanks": ["____"],
-      "answer_key": ["escribir"],
+      "answer_key": ["articulo"],
       "feedback_rules": {
         "case_sensitive": false,
         "allow_trim_spaces": true
@@ -138,9 +138,9 @@
     {
       "exercise_id": "ex_panel_3",
       "panel_id": "panel_3",
-      "prompt": "Tengo mas ____ para leer noticias.",
+      "prompt": "Ahora tengo mas confianza para leer ____.",
       "blanks": ["____"],
-      "answer_key": ["confianza"],
+      "answer_key": ["noticias"],
       "feedback_rules": {
         "case_sensitive": false,
         "allow_trim_spaces": true

examples/fr_demo.json

@@ -0,0 +1,158 @@
+{
+  "schema_version": "1.0.0",
+  "session_id": "sess-demo-fr-001",
+  "language": "fr",
+  "style_id": "minimal",
+  "source": {
+    "link": "https://www.theguardian.com/technology/2026/jun/08/anti-slop-ai-art",
+    "publisher": "The Guardian",
+    "published_at": "Mon, 08 Jun 2026 13:00:25 GMT"
+  },
+  "article": {
+    "title": "Des artistes creent de l'art 'anti-boue' pour se rebeller contre l'IA : 'On nous l'a impose'",
+    "fulltext": "En reaction a l'hyperrealisme de l'IA, des artistes et des creatifs se tournent vers le fait maison et l'imparfait. Au debut de cette annee, un groupe de cineastes, de realisateurs publicitaires et d'influenceurs de l'industrie de l'IA s'est reuni a New York pour le Runway AI Summit, un evenement d'une journee qui vantait le potentiel de cette nouvelle technologie. Pendant une intervention, Rob Wrubel, cofondateur et associe directeur de l'agence de publicite Silverside a San Francisco, a parle de son travail sur la publicite Holiday Caravan 2025 de Coca-Cola, generee par IA. Wrubel a dit que ce qui est incroyable avec l'IA, c'est que l'on peut passer du script a la production en seulement deux semaines. Ce qu'il n'a pas mentionne, c'est que la publicite, avec ses ours polaires informatises et ses camions de livraison peu credibles, a ete largement detestee par presque tous ceux qui l'ont vue. Le rejet public est devenu une information en soi. Elle a peut-etre ete concue rapidement, et cela se voyait. Interroge sur la reaction, Wrubel a admis que la conversation autour de la publicite etait devenue presque aussi importante que la publicite elle-meme, car elle a souleve des questions que toute l'industrie creative se pose actuellement."
+  },
+  "simplified": {
+    "summary": "Des adultes utilisent le programme du jardin pour pratiquer la lecture et l'ecriture avec des etapes simples.",
+    "level": "A2",
+    "keywords": ["adultes", "jardin", "lecture", "ecriture"]
+  },
+  "characters": [
+    {
+      "id": "char_guide",
+      "name": "Guide",
+      "description": "Mentor qui utilise un langage clair."
+    },
+    {
+      "id": "char_learner",
+      "name": "Apprenant",
+      "description": "Adulte qui pratique l'alphabetisation."
+    }
+  ],
+  "panels": [
+    {
+      "panel_id": "panel_1",
+      "frame_index": 1,
+      "scene_description": "Deux adultes lisent une courte carte d'instructions dans un jardin.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Nous lisons ensemble une courte consigne."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Maintenant je peux l'expliquer avec mes propres mots."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_1.png",
+        "overlay_applied": true
+      }
+    },
+    {
+      "panel_id": "panel_2",
+      "frame_index": 2,
+      "scene_description": "L'apprenant ecrit une courte phrase sur l'activite.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Ecris une idee importante de l'article."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Le jardin m'aide a pratiquer la lecture chaque semaine."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_2.png",
+        "overlay_applied": true
+      }
+    },
+    {
+      "panel_id": "panel_3",
+      "frame_index": 3,
+      "scene_description": "Le groupe partage ce qu'il a appris.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Tu as ameliore ton ecriture avec des mots clairs."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Je me sens plus confiant pour lire les nouvelles maintenant."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_3.png",
+        "overlay_applied": true
+      }
+    }
+  ],
+  "exercises": [
+    {
+      "exercise_id": "ex_panel_1",
+      "panel_id": "panel_1",
+      "prompt": "Nous lisons ensemble une courte ____.",
+      "blanks": ["____"],
+      "answer_key": ["consigne"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    },
+    {
+      "exercise_id": "ex_panel_2",
+      "panel_id": "panel_2",
+      "prompt": "Ecris une idee importante de l'____.",
+      "blanks": ["____"],
+      "answer_key": ["article"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    },
+    {
+      "exercise_id": "ex_panel_3",
+      "panel_id": "panel_3",
+      "prompt": "Je me sens plus confiant pour lire les ____ maintenant.",
+      "blanks": ["____"],
+      "answer_key": ["nouvelles"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    }
+  ],
+  "trace": [
+    {
+      "ts": "2026-06-07T00:00:00+00:00",
+      "step": "demo",
+      "status": "ok",
+      "message": "Exemple deterministe"
+    }
+  ]
+}

examples/pt_demo.json

@@ -0,0 +1,158 @@
+{
+  "schema_version": "1.0.0",
+  "session_id": "sess-demo-pt-001",
+  "language": "pt",
+  "style_id": "minimal",
+  "source": {
+    "link": "https://www.theguardian.com/technology/2026/jun/08/anti-slop-ai-art",
+    "publisher": "The Guardian",
+    "published_at": "Mon, 08 Jun 2026 13:00:25 GMT"
+  },
+  "article": {
+    "title": "Artistas fazem arte 'anti-lixo' para se rebelar contra a IA: 'Foi empurrado garganta abaixo'",
+    "fulltext": "Em resposta ao hiper-realismo da IA, artistas e criativos estao se aproximando do caseiro e do imperfeito. No inicio deste ano, um grupo de cineastas, diretores comerciais e influenciadores da industria de IA se reuniu em Nova York para o Runway AI Summit, um evento de um dia que exaltava o potencial dessa nova tecnologia. Durante uma palestra, Rob Wrubel, cofundador e socio-diretor da agencia de publicidade Silverside, em Sao Francisco, falou sobre seu trabalho no anuncio Holiday Caravan 2025 da Coca-Cola, gerado por IA. Wrubel disse que o incrivel da IA e que ela permite ir do roteiro a producao em apenas duas semanas. O que ele nao mencionou foi que o anuncio, com ursos polares computadorizados e caminhoes de entrega falsos, foi muito rejeitado por quase todos que o viram. A rejeicao publica virou uma noticia propria. Talvez tenha sido criado rapidamente, e parecia mesmo. Ao comentar a reacao, Wrubel admitiu que a conversa sobre o anuncio ficou quase tao importante quanto o proprio anuncio, porque mostrou perguntas que toda a industria criativa enfrenta agora."
+  },
+  "simplified": {
+    "summary": "Pessoas adultas usam o programa do jardim para praticar leitura e escrita em passos simples.",
+    "level": "A2",
+    "keywords": ["adultos", "jardim", "leitura", "escrita"]
+  },
+  "characters": [
+    {
+      "id": "char_guide",
+      "name": "Guia",
+      "description": "Mentor que usa linguagem simples."
+    },
+    {
+      "id": "char_learner",
+      "name": "Aprendiz",
+      "description": "Pessoa adulta que pratica alfabetizacao."
+    }
+  ],
+  "panels": [
+    {
+      "panel_id": "panel_1",
+      "frame_index": 1,
+      "scene_description": "Duas pessoas adultas leem um cartao curto de instrucao em um jardim.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Lemos juntos uma instrucao curta."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Agora posso explicar com minhas proprias palavras."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_1.png",
+        "overlay_applied": true
+      }
+    },
+    {
+      "panel_id": "panel_2",
+      "frame_index": 2,
+      "scene_description": "A aprendiz escreve uma frase curta sobre a atividade.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Escreva uma ideia principal do artigo."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "O jardim me ajuda a praticar leitura toda semana."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_2.png",
+        "overlay_applied": true
+      }
+    },
+    {
+      "panel_id": "panel_3",
+      "frame_index": 3,
+      "scene_description": "O grupo compartilha o que aprendeu.",
+      "dialogue": [
+        {
+          "character_id": "char_guide",
+          "text": "Voce melhorou sua escrita com palavras claras."
+        },
+        {
+          "character_id": "char_learner",
+          "text": "Agora me sinto mais confiante para ler noticias."
+        }
+      ],
+      "bubbles": [
+        {
+          "bbox_px": [30, 30, 300, 90]
+        },
+        {
+          "bbox_px": [30, 140, 300, 90]
+        }
+      ],
+      "render": {
+        "image_path": "assets/panel_3.png",
+        "overlay_applied": true
+      }
+    }
+  ],
+  "exercises": [
+    {
+      "exercise_id": "ex_panel_1",
+      "panel_id": "panel_1",
+      "prompt": "Lemos juntos uma ____ curta.",
+      "blanks": ["____"],
+      "answer_key": ["instrucao"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    },
+    {
+      "exercise_id": "ex_panel_2",
+      "panel_id": "panel_2",
+      "prompt": "Escreva uma ideia principal do ____.",
+      "blanks": ["____"],
+      "answer_key": ["artigo"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    },
+    {
+      "exercise_id": "ex_panel_3",
+      "panel_id": "panel_3",
+      "prompt": "Agora me sinto mais confiante para ler ____.",
+      "blanks": ["____"],
+      "answer_key": ["noticias"],
+      "feedback_rules": {
+        "case_sensitive": false,
+        "allow_trim_spaces": true
+      }
+    }
+  ],
+  "trace": [
+    {
+      "ts": "2026-06-07T00:00:00+00:00",
+      "step": "demo",
+      "status": "ok",
+      "message": "Exemplo deterministico"
+    }
+  ]
+}

test/test_app_ui_helpers.py

@@ -2,15 +2,20 @@ from __future__ import annotations
 
 from app import (
     READING_LEVEL_OPTIONS,
+    _language_code_for_label,
     _overlay_bubbles_html,
     _panel_choices,
     _panel_image_html,
+    _render_transcript,
+    _ui_text,
     load_exercise,
 )
+from comic_gen.exercise import evaluate_answer
 
 
 def _document() -> dict:
     return {
+        "language": "en",
         "panels": [
             {
                 "panel_id": "P1",
@@ -50,10 +55,26 @@ def test_panel_choices_use_canonical_panel_ids():
     ]
 
 
+def test_panel_choices_use_localized_panel_label():
+    document = _document()
+    document["language"] = "es"
+
+    assert _panel_choices(document) == [
+        ("Vineta 1", "P1"),
+        ("Vineta 2", "P2"),
+    ]
+
+
 def test_reading_level_options_are_a1_to_b2():
     assert READING_LEVEL_OPTIONS == ["A1", "A2", "B1", "B2"]
 
 
+def test_ui_text_falls_back_to_english():
+    assert _language_code_for_label("Deutsch") == "de"
+    assert _ui_text("es", "generate") == "Generar comic"
+    assert _ui_text("xx", "generate") == "Generate Comic Strip"
+
+
 def test_load_exercise_uses_canonical_panel_id():
     prompt, answer = load_exercise("P1", _document())
 
@@ -68,6 +89,40 @@ def test_load_exercise_supports_legacy_frame_panel_id():
     assert answer == ""
 
 
+def test_load_exercise_uses_localized_heading_and_empty_state():
+    document = _document()
+    document["language"] = "es"
+
+    prompt, _ = load_exercise("P1", document)
+    missing, _ = load_exercise("P2", document)
+
+    assert prompt.startswith("### Ejercicio")
+    assert missing == "No hay ejercicio para esta vineta."
+
+
+def test_render_transcript_uses_localized_heading():
+    document = _document()
+    document["language"] = "de"
+
+    transcript = _render_transcript(document)
+
+    assert transcript.startswith("### Transkript")
+    assert "BILD 1" in transcript
+
+
+def test_exercise_feedback_uses_document_language():
+    document = _document()
+    document["language"] = "es"
+
+    ok, correct = evaluate_answer(document, "P1", "two")
+    retry_ok, retry = evaluate_answer(document, "P1", "wrong")
+
+    assert ok is True
+    assert correct == "Correcto. Buena practica de escritura."
+    assert retry_ok is False
+    assert "Todavia no." in retry
+
+
 def test_overlay_bubbles_html_uses_inline_styles_and_escapes_text():
     panel = {
         "panel_id": "P1",

test/test_comics_pipeline.py

@@ -76,6 +76,7 @@ def test_generate_story_pipeline_passes_reading_level(monkeypatch):
 
     def _fake_text(**kwargs):
         captured["reading_level"] = kwargs["reading_level"]
+        captured["language"] = kwargs["language"]
         return _generated(level=kwargs["reading_level"])
 
     monkeypatch.setattr(
@@ -97,9 +98,84 @@ def test_generate_story_pipeline_passes_reading_level(monkeypatch):
     )
 
     assert captured["reading_level"] == "B2"
+    assert captured["language"] == "en"
     assert document["simplified"]["level"] == "B2"
 
 
+def test_generate_story_pipeline_translates_before_images(monkeypatch):
+    captured = {}
+
+    monkeypatch.setattr(
+        "comic_gen.comics.generate_text_content_from_article",
+        lambda **kwargs: _generated(level=kwargs["reading_level"]),
+    )
+
+    def _fake_translate(document, target_language, **kwargs):
+        captured["target_language"] = target_language
+        document["panels"][0]["dialogue"][0]["text"] = "ES:Linea"
+        document["exercises"][0]["prompt"] = "ES:Linea ____"
+        return True
+
+    def _fake_images(document, panels, options, strict_mode=False):
+        captured["dialogue_for_image"] = panels[0]["dialogue"][0]["text"]
+        captured["exercise_for_image"] = document["exercises"][0]["prompt"]
+        return {"deterministic": 3}
+
+    monkeypatch.setattr(
+        "comic_gen.comics.translate_session_content",
+        _fake_translate,
+    )
+    monkeypatch.setattr(
+        "comic_gen.comics.generate_image_panels",
+        _fake_images,
+    )
+
+    document = _document()
+    document["language"] = "es"
+    comics.generate_story_pipeline(
+        document,
+        panel_count=3,
+        text_model_repo_id="test-model",
+        reading_level="A2",
+        image_options={"enable_live_images": False},
+    )
+
+    assert captured["target_language"] == "es"
+    assert captured["dialogue_for_image"] == "ES:Linea"
+    assert captured["exercise_for_image"] == "ES:Linea ____"
+
+
+def test_generate_story_pipeline_translation_failure_keeps_content(monkeypatch):
+    monkeypatch.setattr(
+        "comic_gen.comics.generate_text_content_from_article",
+        lambda **kwargs: _generated(level=kwargs["reading_level"]),
+    )
+    monkeypatch.setattr(
+        "comic_gen.comics.translate_session_content",
+        lambda *args, **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),
+    )
+    monkeypatch.setattr(
+        "comic_gen.comics.generate_image_panels",
+        lambda *args, **kwargs: {"deterministic": 3},
+    )
+
+    document = _document()
+    document["language"] = "fr"
+    comics.generate_story_pipeline(
+        document,
+        panel_count=3,
+        text_model_repo_id="test-model",
+        reading_level="A2",
+        image_options={"enable_live_images": False},
+    )
+
+    assert document["panels"][0]["dialogue"][0]["text"] == "Line"
+    assert any(
+        item["step"] == "translation" and item["status"] == "fallback"
+        for item in document["trace"]
+    )
+
+
 def test_generate_story_pipeline_fallback_preserves_reading_level(monkeypatch):
     def _fake_text(**kwargs):
         raise UnifiedGenerationError("text failed")

test/test_text_backend.py

@@ -246,7 +246,8 @@ def test_generate_text_prompt_honors_panel_count_and_article(monkeypatch):
     )
 
     assert "- Generate exactly 4 panels." in captured["prompt"]
-    assert "Target Language Code: en" in captured["prompt"]
+    assert "Canonical Generation Language Code: en" in captured["prompt"]
+    assert "Generate canonical learner content in English" in captured["prompt"]
     assert "Comic Style ID: retro" in captured["prompt"]
     assert "Reading Level: B1" in captured["prompt"]
     assert "Set simplified.level exactly to B1." in captured["prompt"]

test/test_translation_backend.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from comic_gen.translation_backend import (
+    NLLB_LANGUAGE_CODES,
+    translate_session_content,
+    translate_text,
+)
+
+
+def test_translate_text_noops_for_english():
+    assert translate_text("Hello", "en") == "Hello"
+
+
+def test_translate_text_uses_nllb_codes(monkeypatch):
+    captured = {}
+
+    def _fake_get_pipeline(model_id, source_language, target_language):
+        captured["model_id"] = model_id
+        captured["source_language"] = source_language
+        captured["target_language"] = target_language
+        return lambda text: [{"translation_text": f"ES:{text}"}]
+
+    monkeypatch.setattr(
+        "comic_gen.translation_backend._get_translation_pipeline",
+        _fake_get_pipeline,
+    )
+
+    translated = translate_text("Hello", "es")
+
+    assert translated == "ES:Hello"
+    assert captured["source_language"] == NLLB_LANGUAGE_CODES["en"]
+    assert captured["target_language"] == NLLB_LANGUAGE_CODES["es"]
+
+
+def test_translate_text_preserves_blank_placeholder(monkeypatch):
+    monkeypatch.setattr(
+        "comic_gen.translation_backend._get_translation_pipeline",
+        lambda *args, **kwargs: (
+            lambda text: [{"translation_text": text.replace("Read", "Leer")}]
+        ),
+    )
+
+    assert translate_text("Read ____ today", "es", preserve_blanks=True) == (
+        "Leer ____ today"
+    )
+
+
+def test_translate_session_content_translates_learner_fields(monkeypatch):
+    monkeypatch.setattr(
+        "comic_gen.translation_backend.translate_text",
+        lambda text, target_language, **kwargs: f"{target_language}:{text}",
+    )
+    document = {
+        "simplified": {"summary": "Summary", "keywords": ["word"]},
+        "characters": [{"description": "A guide"}],
+        "panels": [
+            {
+                "scene_description": "A scene",
+                "dialogue": [{"text": "Hello"}],
+            }
+        ],
+        "exercises": [{"prompt": "Hello ____"}],
+        "trace": [],
+    }
+
+    applied = translate_session_content(document, "fr")
+
+    assert applied is True
+    assert document["simplified"]["summary"] == "fr:Summary"
+    assert document["simplified"]["keywords"] == ["fr:word"]
+    assert document["characters"][0]["description"] == "fr:A guide"
+    assert document["panels"][0]["scene_description"] == "fr:A scene"
+    assert document["panels"][0]["dialogue"][0]["text"] == "fr:Hello"
+    assert document["exercises"][0]["prompt"] == "fr:Hello ____"
+    assert document["trace"][-1]["status"] == "ok"