Init Space: HachimiMT zh-vi demo (CT2, chuẩn hóa xưng hô)

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+models/HachimiMT-60-zh-vi/ct2-int8_float32/source.spm filter=lfs diff=lfs merge=lfs -text
+models/HachimiMT-60-zh-vi/ct2-int8_float32/target.spm filter=lfs diff=lfs merge=lfs -text
+models/HachimiMT-60-zh-vi/source.spm filter=lfs diff=lfs merge=lfs -text
+models/HachimiMT-60-zh-vi/target.spm filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,36 @@
 ---
-title: HachimiMT Demo
-emoji: 😻
-colorFrom: green
-colorTo: gray
+title: HachimiMT — Dịch Trung Việt
+emoji: 📜
+colorFrom: red
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+sdk_version: 6.18.0
 app_file: app.py
 pinned: false
+short_description: Dịch truyện Trung → Việt, chuẩn hóa xưng hô Hán-Việt
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HachimiMT — Dịch Trung → Việt
+
+Công cụ dịch truyện tiếng Trung sang tiếng Việt bằng các model MarianMT (CTranslate2 INT8):
+
+- [HachimiMT-60-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi) (mặc định)
+- [HachimiMT-30-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-30-zh-vi) (nhẹ ~35 MB)
+- [MoxhiMT-60](https://huggingface.co/DanVP/MoxhiMT-60) · [MoxhiMT-30](https://huggingface.co/DanVP/MoxhiMT-30)
+
+## Tính năng
+
+- Dịch văn bản trực tiếp + **đối chiếu song song** theo từng câu/đoạn, hoặc dịch file `.txt`.
+- **Chọn model** (HachimiMT / MoxhiMT, bản 60 hoặc 30) — model tự tải từ Hugging Face khi
+  chọn lần đầu (lazy), chạy CPU.
+- **Chuẩn hóa chữ Hán** phồn → giản trước khi dịch (model train trên giản thể).
+- **Tuỳ chọn chuẩn hóa xưng hô** (mục nâng cao, mặc định tắt) — ép xưng hô về Hán-Việt theo
+  từ tường minh trong nguồn:
+  - **Thân tộc**: `chị → tỷ`, `anh trai → ca ca`, `chị em → tỷ muội`… khi nguồn có 姐姐/哥哥/姐妹…
+  - **Đại từ**: `cậu → ngươi`, `cô ấy → nàng`, `tôi → ta` — chỉ áp ở văn cổ trang/tu tiên.
+  - **Ổn định ngôi hiện đại**: chỉnh ngôi theo ngữ cảnh (thầy/em, mẹ/con…) cho truyện hiện đại.
+
+> Space chạy **CPU** (CTranslate2 INT8). Văn bản dài sẽ chậm hơn máy có GPU; chia **theo câu**
+> giúp giảm trôi tên riêng.
+
+Mã nguồn: <https://github.com/ngocdang8311/qt2>

app.py

@@ -0,0 +1,17 @@
+"""Entrypoint cho HF Space — gọi app trong src/.
+
+HF Space chạy file app.py ở root. App thật nằm trong src/ (dùng import phẳng
+như `import translator`), nên thêm src/ vào sys.path rồi gọi main().
+Phát hiện Space qua SPACE_ID (đã xử lý trong src/app.py: ẩn nút GPU/torch, bỏ
+PID file, để HF tự lo host/port).
+"""
+import sys
+from pathlib import Path
+
+SRC = Path(__file__).resolve().parent / "src"
+sys.path.insert(0, str(SRC))
+
+import app as _app  # noqa: E402
+
+if __name__ == "__main__":
+    _app.main()

exports/hachimimt_vi_20260618_182426.txt

@@ -0,0 +1 @@
+Tỷ tỷ nói với ngươi, các nàng là tỷ muội.

models/HachimiMT-60-zh-vi/config.json

@@ -0,0 +1,36 @@
+{
+  "activation_dropout": 0.0,
+  "activation_function": "swish",
+  "architectures": [
+    "MarianMTModel"
+  ],
+  "attention_dropout": 0.1,
+  "bos_token_id": 1,
+  "d_model": 512,
+  "decoder_attention_heads": 8,
+  "decoder_ffn_dim": 3072,
+  "decoder_layerdrop": 0.0,
+  "decoder_layers": 2,
+  "decoder_start_token_id": 0,
+  "decoder_vocab_size": 24000,
+  "dropout": 0.1,
+  "dtype": "float32",
+  "encoder_attention_heads": 8,
+  "encoder_ffn_dim": 3072,
+  "encoder_layerdrop": 0.0,
+  "encoder_layers": 8,
+  "eos_token_id": 2,
+  "forced_eos_token_id": 2,
+  "init_std": 0.02,
+  "is_decoder": false,
+  "is_encoder_decoder": true,
+  "max_position_embeddings": 512,
+  "model_type": "marian",
+  "pad_token_id": 0,
+  "scale_embedding": true,
+  "share_encoder_decoder_embeddings": true,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.9.0",
+  "use_cache": true,
+  "vocab_size": 24000
+}

models/HachimiMT-60-zh-vi/ct2-int8_float32/config.json

@@ -0,0 +1,10 @@
+{
+  "add_source_bos": false,
+  "add_source_eos": false,
+  "bos_token": "<s>",
+  "decoder_start_token": "<pad>",
+  "eos_token": "</s>",
+  "layer_norm_epsilon": null,
+  "multi_query_attention": false,
+  "unk_token": "<unk>"
+}

models/HachimiMT-60-zh-vi/ct2-int8_float32/generation_config.json

@@ -0,0 +1,12 @@
+{
+  "_from_model_config": true,
+  "bos_token_id": 1,
+  "decoder_start_token_id": 0,
+  "eos_token_id": 2,
+  "forced_eos_token_id": 2,
+  "output_attentions": false,
+  "output_hidden_states": false,
+  "pad_token_id": 0,
+  "transformers_version": "5.9.0",
+  "use_cache": true
+}

models/HachimiMT-60-zh-vi/ct2-int8_float32/model.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed9e9ec52051916be15ebedd9aff71bcb7a30300ee8d2fc2ec818670d222a881
+size 58057231

models/HachimiMT-60-zh-vi/ct2-int8_float32/source.spm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1557335c5892d2f33c6a4864f3ae598b235f705a713e32ca020b9fadb99a99e
+size 606202

models/HachimiMT-60-zh-vi/ct2-int8_float32/target.spm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1557335c5892d2f33c6a4864f3ae598b235f705a713e32ca020b9fadb99a99e
+size 606202

models/HachimiMT-60-zh-vi/ct2-int8_float32/tokenizer_config.json

@@ -0,0 +1,50 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "<pad>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "1": {
+      "content": "<s>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "2": {
+      "content": "</s>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "3": {
+      "content": "<unk>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "backend": "custom",
+  "bos_token": "<s>",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "</s>",
+  "is_local": true,
+  "local_files_only": false,
+  "model_max_length": 512,
+  "pad_token": "<pad>",
+  "separate_vocabs": false,
+  "source_lang": null,
+  "sp_model_kwargs": {},
+  "target_lang": null,
+  "tokenizer_class": "MarianTokenizer",
+  "unk_token": "<unk>"
+}

models/HachimiMT-60-zh-vi/source.spm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1557335c5892d2f33c6a4864f3ae598b235f705a713e32ca020b9fadb99a99e
+size 606202

models/HachimiMT-60-zh-vi/target.spm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d1557335c5892d2f33c6a4864f3ae598b235f705a713e32ca020b9fadb99a99e
+size 606202

models/HachimiMT-60-zh-vi/tokenizer_config.json

@@ -0,0 +1,50 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "<pad>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "1": {
+      "content": "<s>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "2": {
+      "content": "</s>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "3": {
+      "content": "<unk>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "backend": "custom",
+  "bos_token": "<s>",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "</s>",
+  "is_local": true,
+  "local_files_only": false,
+  "model_max_length": 512,
+  "pad_token": "<pad>",
+  "separate_vocabs": false,
+  "source_lang": null,
+  "sp_model_kwargs": {},
+  "target_lang": null,
+  "tokenizer_class": "MarianTokenizer",
+  "unk_token": "<unk>"
+}

requirements.txt

@@ -0,0 +1,5 @@
+sentencepiece>=0.2.0
+gradio>=6.0.0,<7
+ctranslate2>=4.0.0
+huggingface_hub>=0.23.0
+opencc-python-reimplemented>=0.1.7

src/app.py

@@ -0,0 +1,1404 @@
+"""Gradio UI for HachimiMT zh→vi translation."""
+
+from __future__ import annotations
+
+import atexit
+import html
+import os
+import tempfile
+import time
+import unicodedata
+from datetime import datetime
+from pathlib import Path
+
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+import gradio as gr
+
+import hardware
+from hardware import detect_hardware_profile
+from progress_tracker import finish_progress, reset_progress, set_progress, snapshot
+from text_preprocess import (
+    NORMALIZE_AUTO,
+    NORMALIZE_NONE,
+    NORMALIZE_T2S,
+    normalization_message,
+    normalize_chinese_text,
+)
+from honorific_normalize import normalize_honorifics
+from postprocess_policy import classify_genre, v9_route_for_decision
+from pronoun_harmonizer_v9 import harmonize_pronouns_v9
+from translator import MODELS, Backend, HachimiTranslator, is_model_downloaded
+
+
+def _env_float(name: str, default: float, *, min_value: float = 0.0, max_value: float = 60.0) -> float:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        return max(min_value, min(max_value, float(raw)))
+    except ValueError:
+        return default
+
+
+ROOT = Path(__file__).resolve().parent.parent
+EXPORTS_DIR = ROOT / "exports"
+PID_FILE = ROOT / ".hachimimt.pid"
+APP_PORT = 7860
+# HF Space tự set SPACE_ID. Khi ở Space: CPU-only (ẩn nút cài GPU/torch), process
+# do HF quản (bỏ PID file), HF tự lo host/port (không ép 127.0.0.1). App chạy
+# local KHÔNG đổi gì.
+IS_HF_SPACE = bool(os.environ.get("SPACE_ID") or os.environ.get("SPACE_HOST"))
+MAX_TABLE_ROWS = 300
+# Số ký tự tối đa hiển thị trong ô "Bản dịch đầy đủ" (file xuất .txt vẫn đầy đủ).
+FULL_OUTPUT_DISPLAY_LIMIT = 50_000
+PROGRESS_UPDATE_SECONDS = _env_float("HACHIMIMT_PROGRESS_SECONDS", 0.5, max_value=10.0)
+TEXT_ENCODINGS = ("utf-8-sig", "utf-8", "gb18030", "gbk", "big5")
+LEGACY_TEXT_ENCODINGS = ("gb18030", "gbk", "big5")
+
+HW_PROFILE = detect_hardware_profile()
+translator = HachimiTranslator(HW_PROFILE)
+EXPORTS_DIR.mkdir(exist_ok=True)
+
+
+def gpu_available_but_idle() -> bool:
+    """Máy CÓ GPU NVIDIA vật lý nhưng app đang chạy CPU (thiếu torch-CUDA).
+
+    Đây là nhóm nên được mời cài torch để bật GPU (nhanh hơn nhiều lần).
+    Trên HF Space: CPU-only, KHÔNG cho pip install runtime → luôn False (ẩn nút
+    cài GPU + khối gpu-hint; mọi chỗ dùng hàm này tự đúng theo).
+    """
+    if IS_HF_SPACE:
+        return False
+    return bool(hardware.PHYSICAL_NVIDIA_GPU) and not HW_PROFILE.has_cuda
+
+
+def render_gpu_hint_html() -> str:
+    if not gpu_available_but_idle():
+        return ""
+    gpu = html.escape(hardware.PHYSICAL_GPU_NAME or "GPU NVIDIA")
+    return (
+        '<div class="gpu-hint">'
+        f"⚡ Phát hiện <b>{gpu}</b> nhưng app đang chạy bằng <b>CPU</b> "
+        "(thiếu thư viện CUDA). Bật GPU sẽ dịch nhanh hơn nhiều lần. "
+        "Bấm nút bên dưới để cài tự động (tải ~2–3 GB, cần ~5 GB ổ trống, một lần)."
+        "</div>"
+    )
+
+# App khoá ở light mode hoàn toàn bằng CSS: khối ":root, .dark" bên dưới
+# ánh xạ mọi biến theme sang palette "giấy cũ", nên giao diện đúng bất kể
+# trình duyệt đang ở light hay dark (system-theme-proof). Không dùng JS ép
+# theme vì Gradio bỏ qua nó ở đây và CSS đã đủ.
+
+# Preload font trong <head> để giảm nhấp nháy khi tải.
+HEAD_HTML = """
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+"""
+
+CUSTOM_CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,400;0,9..144,600;0,9..144,700;1,9..144,500&family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,500;0,7..72,600;1,7..72,400&family=Noto+Serif+SC:wght@400;600&display=swap');
+
+/* ── Palette "giấy cũ / thư phòng" ─────────────────────────────────── */
+:root, .dark {
+    --paper:      #f4ecdc;   /* nền giấy */
+    --paper-deep: #e7dac2;   /* giấy đậm (đáy gradient) */
+    --card:       #fbf6ea;   /* mặt thẻ */
+    --card-soft:  #f7efe0;   /* thẻ phụ */
+    --ink:        #221b12;   /* mực chính */
+    --ink-soft:   #514537;   /* mực nhạt */
+    --muted:      #8a7a64;   /* chú thích */
+    --accent:     #b03a26;   /* son / chu sa */
+    --accent-2:   #c8553a;   /* son sáng */
+    --gold:       #9c7b3f;   /* nhũ vàng cũ */
+    --border:     #d8cbb1;   /* viền giấy */
+    --border-soft:#e6dcc8;
+    --shadow:     rgba(60, 44, 24, 0.10);
+
+    /* Ánh xạ vào biến chuẩn của Gradio để mọi widget theo theme này
+       (đây là gốc rễ của bug cũ: dark-mode còn sót làm chữ trắng/nền tối). */
+    --body-background-fill: transparent;
+    --body-text-color: var(--ink);
+    --body-text-color-subdued: var(--muted);
+    --background-fill-primary: var(--card);
+    --background-fill-secondary: var(--card-soft);
+    --block-background-fill: var(--card);
+    --block-label-background-fill: transparent;
+    --block-border-color: var(--border);
+    --block-label-text-color: var(--ink-soft);
+    --block-title-text-color: var(--ink-soft);
+    --border-color-primary: var(--border);
+    --border-color-accent: var(--accent);
+    --input-background-fill: #fffdf7;
+    --input-background-fill-focus: #fffefb;
+    --input-border-color: var(--border);
+    --input-border-color-focus: var(--accent);
+    --input-placeholder-color: #b6a88f;
+    --neutral-950: var(--ink);
+    --color-accent: var(--accent);
+    --color-accent-soft: #efd9c9;
+    --link-text-color: var(--accent);
+    --table-border-color: var(--border);
+    --table-even-background-fill: var(--card);
+    --table-odd-background-fill: var(--card-soft);
+    --button-secondary-background-fill: #efe6d3;
+    --button-secondary-background-fill-hover: #e7dcc4;
+    --button-secondary-text-color: var(--ink);
+    --button-secondary-border-color: var(--border);
+    /* Toast lỗi: dark-mode Gradio đặt nền #0f0e0d (đen) — ép về giấy. */
+    --error-background-fill: var(--card);
+    --error-border-color: var(--accent);
+    --error-text-color: var(--accent);
+    --color-red-50: #f7e7e2;
+}
+
+/* ── Nền & khung tổng thể ──────────────────────────────────────────── */
+/* Phủ nền lên html + body + gradio-app: <gradio-app> rộng hết khung và ở
+   dark-mode có nền đen — nếu bỏ sót, hai bên (ngoài container 1180px) và
+   vùng overscroll sẽ lộ màu đen. Đây là nguồn gốc các "dải đen" còn lại. */
+html { background: #ecdfc9 !important; }
+html, body, gradio-app, .gradio-container {
+    background:
+        radial-gradient(1200px 600px at 12% -8%, #fbf4e6 0%, transparent 60%),
+        radial-gradient(1000px 700px at 110% 0%, #efe2cb 0%, transparent 55%),
+        linear-gradient(168deg, #f4ecdc 0%, #ecdfc9 55%, #e4d6bd 100%) !important;
+    color: var(--ink) !important;
+}
+gradio-app { display: block; min-height: 100vh; }
+/* Lớp grain giấy rất nhẹ để bớt phẳng */
+.gradio-container::before {
+    content: "";
+    position: fixed; inset: 0; z-index: 0; pointer-events: none;
+    opacity: 0.5;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.035'/%3E%3C/svg%3E");
+}
+.gradio-container > * { position: relative; z-index: 1; }
+.gradio-container { max-width: 1180px !important; margin: 0 auto !important; }
+
+/* ── Typography ────────────────────────────────────────────────────── */
+body, .gradio-container, .prose, button, input, textarea, select, .gr-button {
+    font-family: 'Literata', Georgia, 'Times New Roman', serif !important;
+}
+h1, h2, h3, h4, .prose h1, .prose h2, .prose h3 {
+    font-family: 'Fraunces', Georgia, serif !important;
+    color: var(--ink) !important;
+    letter-spacing: -0.01em;
+}
+
+/* ── Header (tiêu đề + triện) ──────────────────────────────────────── */
+/* Quan trọng: ép overflow visible + bỏ giới hạn cao của khối Markdown,
+   nếu không Gradio sinh scrollbar con ngay cạnh logo (chữ cao hơn khối
+   vài px → overflow:auto). user-select:none để bỏ select nền xanh chướng. */
+#app-header, #app-title {
+    overflow: visible !important;
+    max-height: none !important;
+    user-select: none;
+    background: transparent !important;
+    border: none !important;
+}
+#app-header { text-align: center; margin: 0.6rem 0 0.2rem; }
+#app-title h1 {
+    font-size: clamp(2.4rem, 5vw, 3.4rem) !important;
+    font-weight: 600 !important;
+    margin: 0 !important;
+    line-height: 1.18;
+    padding: 0.08em 0;
+    background: linear-gradient(180deg, #2a2014 0%, #6a3a26 120%);
+    -webkit-background-clip: text; background-clip: text;
+    -webkit-text-fill-color: transparent;
+}
+#app-title h1::after {
+    content: "譯";                /* "Dịch" — con triện đỏ cạnh tiêu đề */
+    -webkit-text-fill-color: #fff;
+    font-family: 'Noto Serif SC', serif;
+    font-size: 0.42em;
+    font-weight: 600;
+    vertical-align: 0.5em;
+    margin-left: 0.45rem;
+    background: var(--accent);
+    padding: 0.12em 0.18em 0.04em;
+    border-radius: 6px;
+    box-shadow: 0 2px 6px rgba(176,58,38,0.35);
+}
+#app-rule {
+    width: 90px; height: 2px; margin: 0.7rem auto 1.3rem;
+    background: linear-gradient(90deg, transparent, var(--gold), transparent);
+}
+
+/* ── Khối / thẻ ────────────────────────────────────────────────────── */
+.gr-group, .block, .gr-box {
+    border-radius: 14px !important;
+    border-color: var(--border) !important;
+}
+#settings-card {
+    background: var(--card) !important;
+    border: 1px solid var(--border) !important;
+    border-radius: 16px !important;
+    box-shadow: 0 1px 2px var(--shadow), 0 10px 30px -22px var(--shadow);
+    padding: 6px 16px 14px !important;
+}
+.section-label, .section-label p {
+    font-family: 'Fraunces', Georgia, serif !important;
+    font-size: 0.78rem !important;
+    font-weight: 600 !important;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--gold) !important;
+    margin: 0.2rem 0 0.1rem !important;
+}
+
+/* Nhãn các control: bỏ kiểu "pill cam" nặng nề của Gradio,
+   chuyển thành nhãn chữ nhỏ thanh thoát. */
+.block > label > span,
+span[data-testid="block-info"],
+.gr-form > div > label > span {
+    background: transparent !important;
+    color: var(--ink-soft) !important;
+    font-family: 'Literata', serif !important;
+    font-weight: 600 !important;
+    font-size: 0.86rem !important;
+    letter-spacing: 0.01em;
+    padding: 0 0 2px 0 !important;
+}
+
+/* ── Input / textarea ──────────────────────────────────────────────── */
+input, textarea, .gr-input, .wrap.svelte-1ipelgc {
+    background: #fffdf7 !important;
+    color: var(--ink) !important;
+    border-color: var(--border) !important;
+}
+textarea::placeholder, input::placeholder { color: #b6a88f !important; }
+textarea:focus, input:focus { border-color: var(--accent) !important; }
+
+.source-input textarea, .file-preview textarea, #full-output textarea {
+    font-family: 'Literata', Georgia, serif !important;
+    font-size: 1.02rem !important;
+    line-height: 1.75 !important;
+}
+
+/* ── Nút ───────────────────────────────────────────────────────────── */
+button.primary, .gr-button-primary, button[variant="primary"] {
+    background: linear-gradient(180deg, var(--accent-2), var(--accent)) !important;
+    border: 1px solid #93311f !important;
+    color: #fff7ef !important;
+    font-weight: 600 !important;
+    letter-spacing: 0.01em;
+    box-shadow: 0 2px 8px -2px rgba(176,58,38,0.5) !important;
+    transition: transform 0.12s ease, box-shadow 0.12s ease, filter 0.12s ease !important;
+}
+button.primary:hover, .gr-button-primary:hover {
+    filter: brightness(1.05);
+    transform: translateY(-1px);
+    box-shadow: 0 6px 16px -4px rgba(176,58,38,0.55) !important;
+}
+button.secondary, .gr-button-secondary {
+    background: #efe6d3 !important;
+    border: 1px solid var(--border) !important;
+    color: var(--ink) !important;
+    font-weight: 600 !important;
+}
+button.secondary:hover, .gr-button-secondary:hover { background: #e7dcc4 !important; }
+
+/* ── Tabs ──────────────────────────────────────────────────────────── */
+/* Bỏ nền/viền/padding thừa của khối bao Tabs để thanh tab liền mạch
+   với nền giấy thay vì nằm trong một thẻ riêng. */
+.tabs, .tab-wrapper, .tabitem {
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding-top: 0 !important;
+}
+.tab-nav { border-bottom: 1px solid var(--border) !important; }
+.tab-nav button {
+    font-family: 'Fraunces', Georgia, serif !important;
+    font-size: 1rem !important;
+    color: var(--muted) !important;
+}
+.tab-nav button.selected {
+    color: var(--accent) !important;
+    border-bottom: 2px solid var(--accent) !important;
+}
+
+/* ── Radio / Checkbox ──────────────────────────────────────────────── */
+/* Mặc định (chưa chọn): nền giấy, chữ mực — ghi đè màu tối còn sót của
+   dark-mode Gradio (đây là chỗ widget bị "đen" trên nền sáng). */
+.gr-check-radio label,
+fieldset label:has(input[type="radio"]),
+fieldset label:has(input[type="checkbox"]) {
+    background: #f1e7d4 !important;
+    color: var(--ink) !important;
+    border: 1px solid var(--border) !important;
+    border-radius: 9px !important;
+    transition: background 0.12s ease, border-color 0.12s ease !important;
+}
+.gr-check-radio label:hover,
+fieldset label:has(input[type="radio"]):hover,
+fieldset label:has(input[type="checkbox"]):hover {
+    background: #ebe0ca !important;
+    border-color: var(--gold) !important;
+}
+/* Đang chọn: nền son nhạt, viền son */
+.gr-check-radio label.selected, label.selected,
+fieldset label:has(input:checked) {
+    background: var(--color-accent-soft) !important;
+    border-color: var(--accent) !important;
+    color: var(--ink) !important;
+}
+/* Chấm radio / ô checkbox khi tick */
+input[type="radio"]:checked, input[type="checkbox"]:checked {
+    background-color: var(--accent) !important;
+    border-color: var(--accent) !important;
+}
+
+/* ── Accordion "Tuỳ chọn chuẩn hóa xưng hô" (collapse, mặc định đóng) ───
+   3 checkbox cùng chủ đề, tách hẳn khỏi card cấu hình dịch. Label gọn 1 dòng,
+   bỏ info dài của Gradio (gây ngộp) → 1 dòng hint chung bên dưới. */
+#honorific-accordion label { font-weight: 500 !important; white-space: nowrap; }
+#honorific-accordion .gr-check-radio span,
+#honorific-accordion label > span:not(:first-child) { font-size: 0.92rem !important; }
+/* Gradio render info trong block-info/.info — ẩn để khỏi chiếm 3-4 dòng/ô */
+#honorific-accordion div[data-testid="block-info"],
+#honorific-accordion .info { display: none !important; }
+/* dòng hint chung: nhỏ, italic, mực nhạt */
+#honorific-accordion .honorific-hint, #honorific-accordion .honorific-hint p {
+    font-size: 0.82rem !important;
+    font-style: italic;
+    color: var(--muted) !important;
+    margin: 10px 2px 2px !important;
+    line-height: 1.45 !important;
+}
+
+/* ── Slider ────────────────────────────────────────────────────────── */
+input[type="range"]::-webkit-slider-thumb { background: var(--accent) !important; }
+.gr-slider .head, .slider_input_container .slider { accent-color: var(--accent) !important; }
+
+/* ── Thanh tiến trình tuỳ biến ─────────────────────────────────────── */
+.progress-wrap {
+    border: 1px solid var(--border);
+    background: var(--card);
+    border-radius: 14px;
+    padding: 14px 18px;
+    box-shadow: 0 1px 2px var(--shadow);
+}
+.progress-head {
+    display: flex; justify-content: space-between; align-items: baseline;
+    margin-bottom: 9px;
+}
+.progress-pct {
+    font-family: 'Fraunces', Georgia, serif;
+    font-size: 1.15rem; font-weight: 600; color: var(--accent);
+}
+.progress-state {
+    font-size: 0.85rem; color: var(--muted); font-style: italic;
+}
+.progress-track {
+    height: 9px; border-radius: 999px;
+    background: #e6dac2; overflow: hidden;
+    box-shadow: inset 0 1px 2px rgba(90,66,30,0.18);
+}
+.progress-fill {
+    height: 100%; border-radius: 999px;
+    background: linear-gradient(90deg, var(--accent), var(--accent-2), var(--gold));
+    background-size: 200% 100%;
+    transition: width 0.3s ease;
+}
+.progress-fill.is-running { animation: progress-shine 1.6s linear infinite; }
+@keyframes progress-shine { to { background-position: 200% 0; } }
+.progress-msg { margin-top: 8px; font-size: 0.92rem; color: var(--ink-soft); }
+
+/* ── Khung đối chiếu song song (xen kẽ câu Trung · Việt) ────────────── */
+#compare-view { max-height: 560px; overflow-y: auto; padding-right: 6px; }
+/* Thanh cuộn mảnh hợp tông giấy */
+#compare-view::-webkit-scrollbar { width: 9px; }
+#compare-view::-webkit-scrollbar-thumb { background: #d2c3a6; border-radius: 999px; }
+#compare-view::-webkit-scrollbar-track { background: transparent; }
+
+.compare-list { display: flex; flex-direction: column; }
+/* Lưới 3 cột: số thứ tự · câu Trung · câu Việt. Cột 1fr/1fr tự wrap nên
+   không tràn ngang (lỗi cũ của Dataframe). */
+.cmp-head, .cmp-row {
+    display: grid;
+    grid-template-columns: 2rem 1fr 1fr;
+    gap: 16px;
+    align-items: start;
+}
+.cmp-head {
+    position: sticky; top: 0; z-index: 2;
+    padding: 4px 8px 8px;
+    background: linear-gradient(180deg, var(--card) 70%, rgba(251,246,234,0));
+    border-bottom: 1px solid var(--border);
+}
+.cmp-col {
+    font-family: 'Fraunces', Georgia, serif;
+    font-size: 0.82rem; font-weight: 600; letter-spacing: 0.04em;
+    color: var(--gold);
+    text-transform: uppercase;
+}
+.cmp-row {
+    padding: 13px 8px 14px;
+    border-bottom: 1px solid var(--border-soft);
+    border-radius: 10px;
+    transition: background 0.12s ease;
+}
+.cmp-row:last-child { border-bottom: none; }
+/* Linked highlight: rê vào hàng → cả ô Trung và ô Việt cùng sáng */
+.cmp-row:hover { background: #f4e8d2; }
+.cmp-num {
+    grid-column: 1;
+    min-width: 1.8rem; height: 1.8rem;
+    display: inline-flex; align-items: center; justify-content: center;
+    font-family: 'Fraunces', Georgia, serif;
+    font-size: 0.82rem; font-weight: 600;
+    color: var(--accent);
+    background: #f3e7d3;
+    border: 1px solid var(--border);
+    border-radius: 999px;
+}
+.cmp-row:hover .cmp-num { background: var(--accent); color: #fff7ef; border-color: var(--accent); }
+.cmp-zh {
+    grid-column: 2; min-width: 0;
+    font-family: 'Noto Serif SC', serif;
+    font-size: 1.0rem; line-height: 1.7;
+    color: var(--ink-soft);
+    margin: 0;
+}
+.cmp-vi {
+    grid-column: 3; min-width: 0;
+    font-family: 'Literata', Georgia, serif;
+    font-size: 1.02rem; line-height: 1.7;
+    color: var(--ink);
+    margin: 0;
+}
+.cmp-note {
+    padding: 12px 6px 2px; font-size: 0.88rem; font-style: italic;
+    color: var(--muted);
+}
+.compare-empty {
+    padding: 22px 8px; text-align: center;
+    color: var(--muted); font-style: italic; font-size: 0.95rem;
+}
+
+/* ── Accordion ─────────────────────────────────────────────────────── */
+/* Header accordion mặc định lấy --body-text-color (trắng ở dark-mode) →
+   gần như vô hình trên nền giấy. Ép chữ mực + nền giấy cho rõ. */
+.gr-accordion {
+    background: var(--card) !important;
+    border: 1px solid var(--border) !important;
+    border-radius: 12px !important;
+}
+.gr-accordion .label-wrap, .gr-accordion .label-wrap span, .gr-accordion button.label-wrap {
+    color: var(--ink-soft) !important;
+    font-family: 'Fraunces', Georgia, serif !important;
+    font-weight: 600 !important;
+}
+.gr-accordion .label-wrap:hover, .gr-accordion .label-wrap:hover span {
+    color: var(--accent) !important;
+}
+.gr-accordion .label-wrap .icon, .gr-accordion .label-wrap svg { color: var(--accent) !important; }
+
+/* ── Khối thông tin máy / engine ───────────────────────────────────── */
+.info-card {
+    background: var(--card-soft) !important;
+    border: 1px solid var(--border-soft) !important;
+    border-radius: 12px !important;
+    padding: 10px 16px !important;
+    font-size: 0.9rem;
+    color: var(--ink-soft) !important;
+}
+.info-card p { margin: 0.2rem 0 !important; color: var(--ink-soft) !important; }
+.info-card strong, .info-card code { color: var(--ink) !important; }
+code, .prose code {
+    background: #efe4cf !important;
+    color: var(--accent) !important;
+    border-radius: 5px;
+    padding: 0.05em 0.4em;
+}
+
+/* ── Toast thông báo / lỗi ─────────────────────────────────────────── */
+/* Ghi đè trực tiếp (biến cấp .dark của Gradio thắng được khai báo :root),
+   đảm bảo toast luôn nền giấy + chữ son, không bị nền đen của dark-mode. */
+.toast-body {
+    background: var(--card) !important;
+    border: 1px solid var(--border) !important;
+    color: var(--ink) !important;
+    box-shadow: 0 8px 28px -8px var(--shadow) !important;
+}
+.toast-body.error, .toast-body.warning, .toast-body.info {
+    border-left: 4px solid var(--accent) !important;
+}
+.toast-title, .toast-text, .toast-body * { color: var(--ink) !important; }
+.toast-icon, .toast-body svg { color: var(--accent) !important; fill: var(--accent) !important; }
+.toast-close { color: var(--muted) !important; }
+/* Thanh đếm ngược của toast */
+.timer { background: var(--accent) !important; }
+
+/* ── Banner kết quả ────────────────────────────────────────────────── */
+/* Rỗng (chưa dịch) → ẩn hẳn, tránh thẻ kem trống chiếm chỗ. */
+#result-summary:not(:has(p)):not(:has(li)) { display: none !important; }
+#result-summary:has(p), #result-summary:has(li) {
+    background: linear-gradient(180deg, #f7ece0, #f2e3d2) !important;
+    border: 1px solid var(--border) !important;
+    border-left: 4px solid var(--accent) !important;
+    border-radius: 12px !important;
+    padding: 12px 18px !important;
+    margin: 4px 0 6px !important;
+}
+#result-summary p { margin: 0.15rem 0 !important; color: var(--ink) !important; }
+
+/* ── Badge trạng thái tải model ────────────────────────────────────── */
+#model-badge { margin: -0.2rem 0 0.1rem; }
+.model-meta {
+    display: flex;
+    align-items: center;
+    gap: 0.6rem;
+    flex-wrap: wrap;
+}
+.model-hf-link {
+    font-size: 0.8rem;
+    color: var(--accent) !important;
+    text-decoration: none;
+    border-bottom: 1px solid transparent;
+    transition: border-color 0.15s;
+}
+.model-hf-link:hover { border-bottom-color: var(--accent); }
+.model-badge {
+    display: inline-block;
+    font-size: 0.82rem;
+    font-weight: 500;
+    padding: 0.18em 0.7em;
+    border-radius: 999px;
+    border: 1px solid var(--border);
+    letter-spacing: 0.01em;
+}
+.model-badge.ready {
+    background: #e8efe0;
+    color: #3f5a32;
+    border-color: #c2d2b0;
+}
+.model-badge.pending {
+    background: #f6ecd6;
+    color: var(--gold);
+    border-color: #ddcaa5;
+}
+
+/* ── Gợi ý bật GPU (chỉ hiện khi có GPU NVIDIA nhưng đang chạy CPU) ──── */
+#gpu-hint-box {
+    background: linear-gradient(180deg, #f3ece2, #efe6d4) !important;
+    border: 1px solid var(--border) !important;
+    border-left: 4px solid var(--gold) !important;
+    border-radius: 12px !important;
+    padding: 12px 16px !important;
+    margin: 4px 0 2px !important;
+}
+.gpu-hint {
+    color: var(--ink-soft);
+    font-size: 0.9rem;
+    line-height: 1.5;
+    margin-bottom: 0.5rem;
+}
+.gpu-hint b { color: var(--ink); }
+
+footer { display: none !important; }
+"""
+
+
+def write_pid_file() -> None:
+    PID_FILE.write_text(str(os.getpid()), encoding="utf-8")
+
+
+def remove_pid_file() -> None:
+    PID_FILE.unlink(missing_ok=True)
+
+
+def resolve_batch_size(auto_batch: bool, manual_batch: float) -> int:
+    if auto_batch:
+        profile = detect_hardware_profile()
+        translator.apply_hardware_profile(profile)
+        return profile.batch_size
+    batch = int(manual_batch)
+    translator.set_batch_size(batch)
+    return batch
+
+
+def ensure_model(model_key: str, backend: str, beam_size: float) -> str:
+    status = translator.load(model_key, backend=backend)
+    beam = HachimiTranslator.clamp_beam(beam_size)
+    return f"{status} · beam={beam} · batch={translator.batch_size}"
+
+
+def on_auto_batch_toggle(auto_batch: bool) -> dict:
+    profile = detect_hardware_profile()
+    return gr.update(value=profile.batch_size, interactive=not auto_batch)
+
+
+def _model_hf_link(config) -> str:
+    url = html.escape(f"https://huggingface.co/{config.model_id}", quote=True)
+    return (
+        f'<a class="model-hf-link" href="{url}" target="_blank" rel="noopener">'
+        "↗ Trang Hugging Face</a>"
+    )
+
+
+def render_model_badge(model_key: str, backend: str) -> str:
+    """Badge cho biết model (theo engine đang chọn) đã tải sẵn hay sẽ phải tải,
+    kèm link tới trang Hugging Face của model."""
+    if model_key not in MODELS:
+        return ""
+    config = MODELS[model_key]
+    link = _model_hf_link(config)
+
+    if is_model_downloaded(model_key, backend):
+        badge = '<span class="model-badge ready">✓ Đã tải — dịch được ngay</span>'
+        return f'<div class="model-meta">{badge}{link}</div>'
+
+    if backend == Backend.CT2.value and config.ct2_size_mb:
+        size = f" (~{config.ct2_size_mb} MB)"
+    elif backend != Backend.CT2.value:
+        size = " (bản PyTorch, nặng hơn)"
+    else:
+        size = ""
+    badge = (
+        f'<span class="model-badge pending">⬇ Chưa có{size} — '
+        "sẽ tự tải từ Hugging Face ở lần dịch đầu</span>"
+    )
+    return f'<div class="model-meta">{badge}{link}</div>'
+
+
+def on_model_change(model_key: str, backend: str) -> tuple[float, str]:
+    return float(MODELS[model_key].default_beam), render_model_badge(model_key, backend)
+
+
+def install_gpu_torch_ui():
+    """Handler nút 'Cài torch để bật GPU'. Stream log pip realtime vào textbox.
+
+    Yield TỪNG dòng pip ngay khi có, nên người dùng thấy tiến trình tải/cài liên
+    tục (không bị 'đứng hình' như khi gọi hàm blocking rồi mới in một lần)."""
+    if not gpu_available_but_idle():
+        yield gr.update(), "Không cần cài: máy không có GPU NVIDIA đang rảnh."
+        return
+
+    from gpu_setup import _stream_pip, choose_cuda_channel, torch_install_command, verify_torch_cuda
+
+    channel = choose_cuda_channel(hardware.DRIVER_CUDA_VERSION)
+    if channel is None:
+        yield gr.update(), (
+            "Driver NVIDIA quá cũ so với các bản torch CUDA hiện có. "
+            "Hãy cập nhật driver rồi thử lại."
+        )
+        return
+
+    logs = [
+        f"Cài torch CUDA ({channel}) — tải ~2–3 GB, cần ~5 GB ổ trống. "
+        "Vui lòng đợi và ĐỪNG tắt app…",
+    ]
+    yield gr.update(interactive=False, value="Đang cài… đừng tắt app"), "\n".join(logs)
+
+    exit_code = None
+    for line in _stream_pip(torch_install_command(channel)):
+        if line.startswith("__EXIT__:"):
+            exit_code = int(line.split(":", 1)[1])
+            continue
+        if line:
+            logs.append(line)
+            # Giữ textbox gọn: chỉ hiện 200 dòng cuối.
+            yield gr.update(interactive=False), "\n".join(logs[-200:])
+
+    if exit_code != 0:
+        logs.append("")
+        logs.append(f"❌ Cài thất bại (mã {exit_code}). Kiểm tra mạng/đĩa hoặc cài thủ công (README).")
+        yield (
+            gr.update(interactive=True, value="Thử cài lại"),
+            "\n".join(logs[-200:]),
+        )
+        return
+
+    # pip exit 0 chưa chắc có CUDA (vd đã có torch-CPU). Xác minh thật.
+    logs.append("")
+    logs.append("Đang kiểm tra torch có nhận GPU không…")
+    yield gr.update(interactive=False), "\n".join(logs[-200:])
+
+    ok, verify_msg = verify_torch_cuda()
+    logs.append(("✅ " if ok else "❌ ") + verify_msg)
+    if ok:
+        logs.append("Hãy TẮT và MỞ LẠI app (stop.bat rồi start.bat) để bật GPU.")
+    yield (
+        gr.update(
+            interactive=not ok,
+            value="Cài xong — khởi động lại app" if ok else "Thử cài lại",
+        ),
+        "\n".join(logs[-200:]),
+    )
+
+
+def _engine_hint_text(backend: str) -> str:
+    if backend == Backend.CT2.value:
+        return "**Engine:** CTranslate2 — khuyên dùng, tận dụng GPU + batch tốt, nhanh nhất."
+    return (
+        "**Engine:** PyTorch — đã hỗ trợ batch GPU, nhưng vẫn chậm hơn CT2. "
+        "GPU % thấp là bình thường với model ~60M."
+    )
+
+
+def on_backend_change(backend: str, model_key: str) -> tuple[str, str]:
+    """Đổi engine → cập nhật cả gợi ý engine lẫn badge trạng thái tải của model."""
+    return _engine_hint_text(backend), render_model_badge(model_key, backend)
+
+
+def render_progress_html(pct: float, message: str, running: bool) -> str:
+    status = "Đang dịch…" if running else "Sẵn sàng"
+    safe_message = html.escape(message, quote=True)
+    safe_status = html.escape(status, quote=True)
+    running_cls = " is-running" if running else ""
+    return f"""
+    <div class="progress-wrap">
+        <div class="progress-head">
+            <span class="progress-pct">{pct:.0f}%</span>
+            <span class="progress-state">{safe_status}</span>
+        </div>
+        <div class="progress-track">
+            <div class="progress-fill{running_cls}" style="width: {pct:.1f}%;"></div>
+        </div>
+        <div class="progress-msg">{safe_message}</div>
+    </div>
+    """
+
+
+def poll_progress_ui() -> str:
+    state = snapshot()
+    return render_progress_html(state.pct, state.message, state.running)
+
+
+EMPTY_COMPARE_HTML = (
+    '<div class="compare-empty">Dịch xong, câu gốc và bản dịch sẽ hiện đối chiếu ở đây '
+    "— từng câu một, cuộn dọc để đọc soát.</div>"
+)
+
+
+def render_compare_html(rows: list[tuple[int, str, str]]) -> str:
+    """Render đối chiếu song song 2 cột (Trung | Việt), mỗi chunk một hàng.
+
+    Mỗi hàng là một cặp câu đã khớp sẵn từ backend → rê chuột vào một hàng
+    thì cả ô Trung lẫn ô Việt cùng sáng (linked highlight kiểu Google Dịch),
+    chỉ bằng CSS :hover vì đây là markup của ta trong gr.HTML."""
+    if not rows:
+        return EMPTY_COMPARE_HTML
+
+    display = rows[:MAX_TABLE_ROWS]
+    items = [
+        '<div class="cmp-head">'
+        '<span class="cmp-num"></span>'
+        '<div class="cmp-col">Tiếng Trung</div>'
+        '<div class="cmp-col">Tiếng Việt</div>'
+        "</div>"
+    ]
+    for idx, zh, vi in display:
+        safe_zh = html.escape(zh, quote=True)
+        safe_vi = html.escape(vi, quote=True)
+        items.append(
+            f'<div class="cmp-row">'
+            f'<span class="cmp-num">{idx}</span>'
+            f'<p class="cmp-zh">{safe_zh}</p>'
+            f'<p class="cmp-vi">{safe_vi}</p>'
+            f"</div>"
+        )
+
+    note = ""
+    if len(rows) > MAX_TABLE_ROWS:
+        note = (
+            f'<div class="cmp-note">Hiển thị {MAX_TABLE_ROWS}/{len(rows)} câu đầu. '
+            "Xem bản dịch đầy đủ ở khối bên dưới.</div>"
+        )
+    return f'<div class="compare-list">{"".join(items)}{note}</div>'
+
+
+def _decoded_text_score(text: str) -> int:
+    """Lower is better. Helps avoid Big5 bytes decoded as valid GB18030 junk."""
+    score = 0
+    for char in text:
+        if char == "\ufffd":
+            score += 100
+            continue
+        if char in "\n\r\t":
+            continue
+        category = unicodedata.category(char)
+        if category.startswith("C"):
+            score += 20
+            continue
+        name = unicodedata.name(char, "")
+        if (
+            "HIRAGANA" in name
+            or "KATAKANA" in name
+            or "BOPOMOFO" in name
+            or "HANGUL" in name
+        ):
+            score += 6
+    return score
+
+
+def _decode_text_bytes(data: bytes) -> str:
+    for encoding in ("utf-8-sig", "utf-8"):
+        try:
+            return data.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+
+    candidates: list[tuple[int, int, str]] = []
+    for index, encoding in enumerate(LEGACY_TEXT_ENCODINGS):
+        try:
+            decoded = data.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+        candidates.append((_decoded_text_score(decoded), index, decoded))
+
+    if candidates:
+        return min(candidates, key=lambda item: (item[0], item[1]))[2]
+    return data.decode("utf-8", errors="replace")
+
+
+def read_text_file(path: Path, *, max_chars: int | None = None) -> str:
+    text = _decode_text_bytes(path.read_bytes())
+    return text[:max_chars] if max_chars is not None else text
+
+
+def _exception_message(exc: Exception) -> str:
+    return str(exc).strip() or exc.__class__.__name__
+
+
+def export_translation(full_text: str, filename_stem: str) -> str | None:
+    if not full_text.strip():
+        raise gr.Error("Chưa có bản dịch để xuất.")
+
+    safe_stem = "".join(c if c.isalnum() or c in "-_" else "_" for c in filename_stem) or "translation"
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    out_path = EXPORTS_DIR / f"{safe_stem}_vi_{timestamp}.txt"
+    out_path.write_text(full_text, encoding="utf-8")
+    return str(out_path)
+
+
+def _format_duration(seconds: float) -> str:
+    """Định dạng thời gian gọn: '12,3 giây' hoặc '2 phút 5 giây'."""
+    if seconds < 60:
+        return f"{seconds:.1f} giây".replace(".", ",")
+    minutes = int(seconds // 60)
+    rem = int(round(seconds - minutes * 60))
+    if rem == 0:
+        return f"{minutes} phút"
+    return f"{minutes} phút {rem} giây"
+
+
+def _clamp_full_text(full_text: str) -> str:
+    """Giới hạn text hiển thị trong ô 'Bản dịch đầy đủ' để tránh lag với file lớn.
+
+    Textbox chứa vài MB (truyện hàng chục nghìn câu) làm trình duyệt giật khi
+    render/cuộn. File xuất .txt vẫn ĐẦY ĐỦ — đây chỉ cắt phần HIỂN THỊ. User đọc
+    trọn bộ bằng nút tải file bên dưới.
+    """
+    if len(full_text) <= FULL_OUTPUT_DISPLAY_LIMIT:
+        return full_text
+    head = full_text[:FULL_OUTPUT_DISPLAY_LIMIT].rsplit("\n", 1)[0]
+    omitted = len(full_text) - len(head)
+    return (
+        f"{head}\n\n"
+        f"────────────────────\n"
+        f"[Đã ẩn ~{omitted:,} ký tự còn lại để tránh lag. "
+        f"Bản dịch ĐẦY ĐỦ đã lưu — bấm “Xuất bản dịch .txt” / tải file bên dưới.]"
+    ).replace(",", ".")
+
+
+def _build_results(
+    rows: list[tuple[int, str, str]],
+    full_text: str,
+    status: str,
+    summary: str,
+    download_path: str | None,
+) -> tuple:
+    return (
+        render_compare_html(rows),
+        _clamp_full_text(full_text),
+        status,
+        download_path,
+        summary,
+        full_text,  # bản đầy đủ → gr.State cho nút Xuất .txt
+    )
+
+
+def apply_postprocess_rows(
+    rows: list[tuple[int, str, str]],
+    *,
+    honorific_kinship: bool,
+    honorific_pronouns: bool,
+    pronoun_harmonizer_v9: bool,
+) -> tuple[list[tuple[int, str, str]], str, dict]:
+    genre_decision = classify_genre(rows) if rows else None
+    honorific_changed = 0
+    pronoun_report = {}
+
+    honorific_pronouns_effective = bool(honorific_pronouns and genre_decision and genre_decision.is_classical)
+    honorific_kinship_effective = bool(honorific_kinship)
+    honorific_on_effective = honorific_kinship_effective or honorific_pronouns_effective
+
+    if honorific_on_effective and rows:
+        new_rows = []
+        for index, chunk_zh, translated_vi in rows:
+            fixed = normalize_honorifics(
+                chunk_zh, translated_vi,
+                apply_kinship=honorific_kinship_effective,
+                apply_pronouns=honorific_pronouns_effective,
+                classical_context=genre_decision.is_classical if genre_decision else None,
+            )
+            if fixed != translated_vi:
+                honorific_changed += 1
+            new_rows.append((index, chunk_zh, fixed))
+        rows = new_rows
+
+    if pronoun_harmonizer_v9 and rows:
+        rows, pronoun_report = harmonize_pronouns_v9(
+            rows,
+            route=v9_route_for_decision(genre_decision) if genre_decision else "unknown_copy_guard",
+        )
+
+    full_text = "\n".join(vi for _, _, vi in rows)
+    return rows, full_text, {
+        "genre_decision": genre_decision,
+        "honorific_changed": honorific_changed,
+        "honorific_pronouns_effective": honorific_pronouns_effective,
+        "honorific_kinship_effective": honorific_kinship_effective,
+        "pronoun_report": pronoun_report,
+    }
+
+
+def _translate_run(
+    source: str,
+    model_key: str,
+    backend: str,
+    beam_size: float,
+    chunk_mode: str,
+    normalize_mode: str,
+    honorific_kinship: bool,
+    honorific_pronouns: bool,
+    pronoun_harmonizer_v9: bool,
+    auto_batch: bool,
+    manual_batch: float,
+    *,
+    filename_stem: str,
+    summary_prefix: str,
+    progress: gr.Progress = gr.Progress(),
+) -> tuple:
+    try:
+        original_source = source
+        source = normalize_chinese_text(source, normalize_mode)
+        normalize_msg = normalization_message(original_source, source, normalize_mode)
+        honorific_kinship = bool(honorific_kinship)
+        honorific_pronouns = bool(honorific_pronouns)
+        honorific_on = honorific_kinship or honorific_pronouns
+        pronoun_harmonizer_v9 = bool(pronoun_harmonizer_v9)
+
+        if is_model_downloaded(model_key, backend):
+            load_msg = "Đang nạp model..."
+        else:
+            label = MODELS[model_key].label if model_key in MODELS else model_key
+            load_msg = f"Đang tải model {label} từ Hugging Face (lần đầu, vui lòng đợi)..."
+        set_progress(0, load_msg)
+        progress(0, desc=load_msg)
+
+        resolve_batch_size(auto_batch, manual_batch)
+        status = ensure_model(model_key, backend, beam_size)
+
+        set_progress(2, f"{normalize_msg} Đang chia chunk...")
+        progress(0.02, desc="Đang chia chunk...")
+
+        rows: list[tuple[int, str, str]] = []
+        full_text = ""
+        last_progress_update = 0.0
+        translate_start = time.perf_counter()
+
+        for done, total, message, result_rows, result_text in translator.translate_text_iter(
+            source,
+            chunk_mode=chunk_mode,
+            beam_size=int(beam_size),
+        ):
+            if result_rows is not None and result_text is not None:
+                rows = result_rows
+                full_text = result_text
+                continue
+
+            now = time.perf_counter()
+            should_update_progress = (
+                done == 0
+                or done == total
+                or now - last_progress_update >= PROGRESS_UPDATE_SECONDS
+            )
+            if not should_update_progress:
+                continue
+
+            pct = round(done / max(total, 1) * 100, 1)
+            detail = f"{message} ({pct}%)"
+            set_progress(pct, detail)
+            progress(done / max(total, 1), desc=message)
+            last_progress_update = now
+
+        translate_seconds = time.perf_counter() - translate_start
+
+        rows, full_text, postprocess_report = apply_postprocess_rows(
+            rows,
+            honorific_kinship=honorific_kinship,
+            honorific_pronouns=honorific_pronouns,
+            pronoun_harmonizer_v9=pronoun_harmonizer_v9,
+        )
+        genre_decision = postprocess_report.get("genre_decision")
+        honorific_changed = int(postprocess_report.get("honorific_changed") or 0)
+        honorific_pronouns_effective = bool(postprocess_report.get("honorific_pronouns_effective"))
+        pronoun_report = postprocess_report.get("pronoun_report") or {}
+
+        set_progress(98, "Đang lưu file xuất...")
+        progress(0.98, desc="Đang lưu file xuất...")
+
+        download_path = export_translation(full_text, filename_stem)
+        duration = _format_duration(translate_seconds)
+        rate = len(rows) / translate_seconds if translate_seconds > 0 else 0.0
+        time_note = f"⏱ {duration}"
+        if rate >= 1:
+            time_note += f" ({rate:.0f} chunk/giây)"
+        honorific_note = ""
+        if honorific_on:
+            parts = []
+            if honorific_kinship:
+                parts.append("thân tộc")
+            if honorific_pronouns:
+                parts.append("đại từ" if honorific_pronouns_effective else "đại từ bỏ qua")
+            honorific_note = (f" Đã chuẩn hóa xưng hô ({' + '.join(parts)}): "
+                              f"{honorific_changed} chunk chỉnh.")
+        pronoun_note = ""
+        if pronoun_harmonizer_v9:
+            pronoun_note = (
+                " Ổn định ngôi xưng V9: "
+                f"{pronoun_report.get('changed_rows', 0)} chunk chỉnh, "
+                f"route `{pronoun_report.get('route', 'n/a')}`."
+            )
+        route_note = f" Route hậu kỳ `{genre_decision.route}`." if genre_decision and (honorific_on or pronoun_harmonizer_v9) else ""
+        summary = f"{summary_prefix} **{len(rows)}** chunk · {time_note}. {normalize_msg}{route_note}{honorific_note}{pronoun_note}"
+        status = f"{status} · {time_note}"
+        finish_progress(f"Hoàn tất — {len(rows)} chunk trong {duration} (100%)")
+        progress(1.0, desc="Hoàn tất")
+
+        return _build_results(rows, full_text, status, summary, download_path)
+    except Exception as exc:
+        reset_progress(f"Lỗi: {_exception_message(exc)}")
+        raise
+
+
+def translate_text_ui(
+    source: str,
+    model_key: str,
+    backend: str,
+    beam_size: float,
+    chunk_mode: str,
+    normalize_mode: str,
+    honorific_kinship: bool,
+    honorific_pronouns: bool,
+    pronoun_harmonizer_v9: bool,
+    auto_batch: bool,
+    manual_batch: float,
+    progress: gr.Progress = gr.Progress(),
+) -> tuple:
+    if not source.strip():
+        raise gr.Error("Nhập văn bản tiếng Trung cần dịch.")
+
+    return _translate_run(
+        source,
+        model_key,
+        backend,
+        beam_size,
+        chunk_mode,
+        normalize_mode,
+        honorific_kinship,
+        honorific_pronouns,
+        pronoun_harmonizer_v9,
+        auto_batch,
+        manual_batch,
+        filename_stem="hachimimt",
+        summary_prefix="Đã dịch",
+        progress=progress,
+    )
+
+
+def translate_file_ui(
+    file_obj,
+    model_key: str,
+    backend: str,
+    beam_size: float,
+    chunk_mode: str,
+    normalize_mode: str,
+    honorific_kinship: bool,
+    honorific_pronouns: bool,
+    pronoun_harmonizer_v9: bool,
+    auto_batch: bool,
+    manual_batch: float,
+    progress: gr.Progress = gr.Progress(),
+) -> tuple:
+    if file_obj is None:
+        raise gr.Error("Chọn file .txt cần dịch.")
+
+    path = Path(file_obj)
+    if path.suffix.lower() != ".txt":
+        raise gr.Error("Chỉ hỗ tr��� file .txt")
+
+    source = read_text_file(path)
+    if not source.strip():
+        raise gr.Error("File trống.")
+
+    return _translate_run(
+        source,
+        model_key,
+        backend,
+        beam_size,
+        chunk_mode,
+        normalize_mode,
+        honorific_kinship,
+        honorific_pronouns,
+        pronoun_harmonizer_v9,
+        auto_batch,
+        manual_batch,
+        filename_stem=path.stem,
+        summary_prefix=f"Đã dịch từ `{path.name}` —",
+        progress=progress,
+    )
+
+
+def build_ui() -> gr.Blocks:
+    model_choices = [(cfg.label, key) for key, cfg in MODELS.items()]
+
+    with gr.Blocks(title="HachimiMT — Dịch Trung Việt") as demo:
+        # ── Header ────────────────────────────────────────────────────
+        with gr.Column(elem_id="app-header"):
+            gr.Markdown("# HachimiMT", elem_id="app-title")
+        gr.HTML('<div id="app-rule"></div>')
+
+        # ── Khu cấu hình ──────────────────────────────────────────────
+        with gr.Group(elem_id="settings-card"):
+            gr.Markdown("Cấu hình dịch", elem_classes=["section-label"])
+            with gr.Row():
+                model_select = gr.Dropdown(
+                    choices=model_choices, value="HachimiMT-60", label="Model dịch", scale=3,
+                )
+                backend_select = gr.Radio(
+                    [("CTranslate2 — nhanh", Backend.CT2.value), ("PyTorch", Backend.TRANSFORMERS.value)],
+                    value=Backend.CT2.value,
+                    label="Engine",
+                    scale=3,
+                )
+                beam_size = gr.Slider(1, 4, value=2, step=1, label="Beam (1–4)", scale=2)
+                chunk_mode = gr.Radio(
+                    [("Theo câu", "sentence"), ("Theo đoạn", "paragraph")],
+                    value="sentence",
+                    label="Chia chunk",
+                    scale=2,
+                )
+                normalize_mode = gr.Dropdown(
+                    [
+                        ("Tự động phồn → giản", NORMALIZE_AUTO),
+                        ("Ép phồn → giản", NORMALIZE_T2S),
+                        ("Giữ nguyên", NORMALIZE_NONE),
+                    ],
+                    value=NORMALIZE_AUTO,
+                    label="Chuẩn hóa chữ Hán",
+                    scale=2,
+                )
+            with gr.Row():
+                auto_batch = gr.Checkbox(value=True, label="Tự động batch theo CPU/GPU", scale=2)
+                manual_batch = gr.Slider(
+                    4, 128, value=HW_PROFILE.batch_size, step=4,
+                    label="Batch size (chunk/lần)", interactive=False, scale=3,
+                )
+
+            model_badge = gr.HTML(
+                render_model_badge("HachimiMT-60", Backend.CT2.value),
+                elem_id="model-badge",
+            )
+            engine_hint = gr.Markdown(_engine_hint_text(Backend.CT2.value))
+            status = gr.Textbox(
+                label="Trạng thái", value="Sẵn sàng — chọn cấu hình rồi bắt đầu dịch.",
+                interactive=False, elem_classes=["status-box"],
+            )
+
+            _gpu_idle = gpu_available_but_idle()
+            with gr.Group(visible=_gpu_idle, elem_id="gpu-hint-box") as gpu_hint_group:
+                gpu_hint = gr.HTML(render_gpu_hint_html())
+                gpu_install_btn = gr.Button(
+                    "⚡ Cài torch để bật GPU (tải ~2–3 GB, cần ~5 GB trống)",
+                    variant="primary",
+                )
+                gpu_install_log = gr.Textbox(
+                    label="Tiến trình cài đặt",
+                    value="",
+                    interactive=False,
+                    lines=6,
+                    visible=False,
+                    elem_classes=["status-box"],
+                )
+
+        with gr.Accordion("Tuỳ chọn chuẩn hóa xưng hô (nâng cao)", open=False,
+                          elem_id="honorific-accordion"):
+            with gr.Row():
+                honorific_kinship = gr.Checkbox(
+                    value=False, label="Thân tộc (tỷ / muội / ca ca…)", scale=1,
+                )
+                honorific_pronouns = gr.Checkbox(
+                    value=False, label="Đại từ (ngươi / hắn / nàng / ta)", scale=1,
+                )
+                pronoun_harmonizer_v9 = gr.Checkbox(
+                    value=False, label="Ổn định ngôi hiện đại", scale=1,
+                )
+            gr.Markdown(
+                "Ép xưng hô về Hán-Việt khi nguồn có từ tương ứng · **Đại từ** chỉ áp "
+                "khi route cấp chương là văn cổ trang · **Ổn định ngôi hiện đại** chỉ "
+                "rewrite khi route hiện đại, ví dụ thầy/em, mẹ/con, anh/em. Mixed/unknown "
+                "sẽ guard để tránh sửa quá tay.",
+                elem_classes=["honorific-hint"],
+            )
+
+        with gr.Accordion("Thông tin máy & hướng dẫn", open=False):
+            gr.Markdown(
+                f"**Cấu hình tự động:** {HW_PROFILE.summary}\n\n"
+                f"**GPU inference:** {HW_PROFILE.gpu_name or 'CPU'}\n\n"
+                f"**Khởi động / tắt:** `start.bat` / `stop.bat` · http://127.0.0.1:{APP_PORT}",
+                elem_classes=["info-card"],
+            )
+
+        model_select.change(
+            on_model_change,
+            inputs=[model_select, backend_select],
+            outputs=[beam_size, model_badge],
+        )
+        backend_select.change(
+            on_backend_change,
+            inputs=[backend_select, model_select],
+            outputs=[engine_hint, model_badge],
+        )
+        auto_batch.change(on_auto_batch_toggle, inputs=[auto_batch], outputs=[manual_batch])
+
+        gpu_install_btn.click(
+            lambda: gr.update(visible=True),
+            outputs=[gpu_install_log],
+        ).then(
+            install_gpu_torch_ui,
+            outputs=[gpu_install_btn, gpu_install_log],
+        )
+
+        # ── Nhập liệu (văn bản / file) ────────────────────────────────
+        with gr.Tabs():
+            with gr.Tab("📝 Dịch văn bản"):
+                source = gr.Textbox(
+                    label="Văn bản gốc (Tiếng Trung)",
+                    placeholder="粘贴中文原文…",
+                    lines=10,
+                    elem_classes=["source-input"],
+                )
+                text_btn = gr.Button("Dịch văn bản", variant="primary", size="lg")
+
+            with gr.Tab("📄 Dịch file .txt"):
+                gr.Markdown("Upload file `.txt` tiếng Trung → dịch toàn bộ → tải file `.txt` tiếng Việt.")
+                file_input = gr.File(label="Chọn file .txt đầu vào", file_types=[".txt"], type="filepath")
+                file_preview = gr.Textbox(
+                    label="Xem trước nội dung file", lines=8, interactive=False, elem_classes=["file-preview"],
+                )
+                file_btn = gr.Button("Dịch file & xuất .txt", variant="primary", size="lg")
+
+                def preview_file(file_obj) -> str:
+                    if not file_obj:
+                        return ""
+                    return read_text_file(Path(file_obj), max_chars=8000)
+
+                file_input.change(preview_file, inputs=[file_input], outputs=[file_preview])
+
+        # ── Tiến trình (một thanh duy nhất) ───────────────────────────
+        progress_html = gr.HTML(render_progress_html(0, "Sẵn sàng.", False))
+
+        # ── Kết quả ───────────────────────────────────────────────────
+        result_summary = gr.Markdown(elem_id="result-summary")
+
+        with gr.Accordion("Đối chiếu song song (câu gốc · bản dịch)", open=True):
+            compare_view = gr.HTML(render_compare_html([]), elem_id="compare-view")
+
+        with gr.Accordion("Bản dịch đầy đủ & xuất file", open=True):
+            full_output = gr.Textbox(
+                label="Bản dịch đầy đủ", lines=10, interactive=False,
+                elem_id="full-output",
+            )
+            # Giữ bản dịch ĐẦY ĐỦ (không bị cap hiển thị) để nút Xuất .txt dùng.
+            full_text_state = gr.State("")
+            with gr.Row():
+                export_btn = gr.Button("💾 Xuất bản dịch .txt", variant="secondary")
+                download_file = gr.File(label="Tải file bản dịch (.txt)")
+
+        result_outputs = [
+            compare_view,
+            full_output,
+            status,
+            download_file,
+            result_summary,
+            full_text_state,
+        ]
+
+        translate_inputs = [
+            model_select, backend_select, beam_size, chunk_mode, normalize_mode,
+            honorific_kinship, honorific_pronouns, pronoun_harmonizer_v9,
+            auto_batch, manual_batch,
+        ]
+
+        text_btn.click(
+            translate_text_ui,
+            inputs=[source, *translate_inputs],
+            outputs=result_outputs,
+            concurrency_limit=1,
+            concurrency_id="translate",
+        )
+
+        file_btn.click(
+            translate_file_ui,
+            inputs=[file_input, *translate_inputs],
+            outputs=result_outputs,
+            concurrency_limit=1,
+            concurrency_id="translate",
+        )
+
+        export_btn.click(
+            lambda text: export_translation(text, "hachimimt"),
+            inputs=[full_text_state], outputs=[download_file],
+        )
+
+        progress_timer = gr.Timer(0.3, active=True)
+        progress_timer.tick(
+            poll_progress_ui,
+            outputs=[progress_html],
+            show_progress=False,
+        )
+
+    return demo
+
+
+def main() -> None:
+    if not IS_HF_SPACE:           # Space: process do HF quản, không cần PID
+        write_pid_file()
+        atexit.register(remove_pid_file)
+    reset_progress()
+
+    demo = build_ui()
+    demo.queue(default_concurrency_limit=8)
+    # Gradio 6: theme/css/head truyền ở launch() (không còn ở Blocks()).
+    favicon = Path(__file__).resolve().parent / "assets" / "favicon.svg"
+    launch_kwargs = dict(
+        theme=gr.themes.Soft(primary_hue="orange", neutral_hue="stone"),
+        css=CUSTOM_CSS,
+        head=HEAD_HTML,
+        favicon_path=str(favicon) if favicon.exists() else None,
+        allowed_paths=[str(EXPORTS_DIR), tempfile.gettempdir()],
+    )
+    if not IS_HF_SPACE:           # local: bind localhost cố định; Space: HF tự lo
+        launch_kwargs["server_name"] = "127.0.0.1"
+        launch_kwargs["server_port"] = APP_PORT
+    demo.launch(**launch_kwargs)
+
+
+if __name__ == "__main__":
+    main()

src/chunker.py

@@ -0,0 +1,27 @@
+"""Split Chinese source text into translation chunks."""
+
+from __future__ import annotations
+
+import re
+
+SENTENCE_END = re.compile(r"(?<=[。！？!?；;…])")
+PARAGRAPH_BREAK = re.compile(r"\n\s*\n+")
+
+
+def split_chunks(text: str, mode: str = "sentence") -> list[str]:
+    """Split *text* into non-empty chunks for independent translation."""
+    text = text.strip()
+    if not text:
+        return []
+
+    if mode == "paragraph":
+        parts = PARAGRAPH_BREAK.split(text)
+    else:
+        parts: list[str] = []
+        for paragraph in text.splitlines():
+            paragraph = paragraph.strip()
+            if not paragraph:
+                continue
+            parts.extend(SENTENCE_END.split(paragraph))
+
+    return [chunk.strip() for chunk in parts if chunk.strip()]

src/gpu_setup.py

@@ -0,0 +1,162 @@
+"""Cài torch bản CUDA phù hợp để bật GPU cho CTranslate2.
+
+Engine mặc định (CT2) cần thư viện cuBLAS/cuDNN để chạy GPU; cách đơn giản nhất
+là cài bản torch CUDA (đã đóng gói sẵn các DLL đó). Module này:
+  - chọn channel cu1xx cao nhất mà driver hỗ trợ,
+  - chạy `pip install torch --index-url ...` vào CHÍNH python đang chạy (sys.executable),
+  - stream log để UI hiển thị tiến trình.
+
+Sau khi cài xong PHẢI khởi động lại app: torch phải có mặt TRƯỚC khi import
+ctranslate2 (xem hardware._guard_ct2_cuda_before_import) thì GPU mới được bật.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import os
+import sys
+from typing import Callable, Iterator
+
+# Các channel CUDA mà PyTorch stable phát hành (cao → thấp). Xác minh tại
+# https://pytorch.org/get-started/locally/ (hiện: cu118, cu126, cu128).
+# (major, minor, "cuXXX")
+_TORCH_CUDA_CHANNELS = [
+    (12, 8, "cu128"),
+    (12, 6, "cu126"),
+    (11, 8, "cu118"),
+]
+
+
+def choose_cuda_channel(driver_cuda: str | None) -> str | None:
+    """Chọn channel torch cao nhất mà driver còn hỗ trợ (driver_cuda dạng '13.2').
+
+    NVIDIA backward-compatible: driver hỗ trợ tới CUDA X chạy được mọi wheel <= X.
+    Trả None nếu driver quá cũ hơn cả bản thấp nhất (cu118).
+    """
+    if not driver_cuda:
+        # Không biết driver → chọn bản phổ biến tương thích rộng nhất.
+        return "cu118"
+    try:
+        major, minor = (int(part) for part in driver_cuda.split(".")[:2])
+    except (ValueError, TypeError):
+        return "cu118"
+    for ch_major, ch_minor, channel in _TORCH_CUDA_CHANNELS:
+        if (major, minor) >= (ch_major, ch_minor):
+            return channel
+    return None
+
+
+def torch_install_command(channel: str) -> list[str]:
+    # --upgrade --force-reinstall: BẮT BUỘC. Nếu user đã có torch-CPU (vd từ setup
+    # cũ / requirements-pytorch), `pip install torch` thường báo "already satisfied"
+    # và KHÔNG ghi đè → cài xong vẫn là CPU. Force-reinstall đảm bảo lấy bản CUDA.
+    return [
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--upgrade",
+        "--force-reinstall",
+        "torch",
+        "--index-url",
+        f"https://download.pytorch.org/whl/{channel}",
+    ]
+
+
+def verify_torch_cuda() -> tuple[bool, str]:
+    """Sau khi cài, kiểm tra torch có thật sự thấy CUDA không (subprocess sạch).
+
+    Chạy trong tiến trình con KHÔNG bị mask CUDA_VISIBLE_DEVICES=-1 (guard của app
+    có thể đã set ở tiến trình hiện tại). Bắt trường hợp 'cài xong nhưng vẫn CPU'.
+    """
+    code = (
+        "import torch,sys;"
+        "print('TORCH_VERSION='+torch.__version__);"
+        "print('CUDA_OK='+str(torch.cuda.is_available()))"
+    )
+    env = dict(os.environ)
+    env.pop("CUDA_VISIBLE_DEVICES", None)  # bỏ mask để torch nhìn thấy GPU thật
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            timeout=120,
+            env=env,
+        )
+    except Exception as exc:
+        return False, f"Không kiểm tra được torch sau cài: {exc}"
+    out = result.stdout
+    version = ""
+    for line in out.splitlines():
+        if line.startswith("TORCH_VERSION="):
+            version = line.split("=", 1)[1]
+    cuda_ok = "CUDA_OK=True" in out
+    if cuda_ok:
+        return True, f"torch {version} đã nhận GPU."
+    return False, (
+        f"Đã cài torch {version or '(?)'} nhưng torch.cuda vẫn = False — "
+        "có thể driver chưa phù hợp hoặc bản torch không khớp. Xem README."
+    )
+
+
+def _stream_pip(cmd: list[str]) -> Iterator[str]:
+    """Chạy pip, yield từng dòng output (cả stdout/stderr gộp)."""
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        yield line.rstrip()
+    proc.wait()
+    yield f"__EXIT__:{proc.returncode}"
+
+
+def install_torch_cuda(
+    driver_cuda: str | None,
+    on_log: Callable[[str], None] | None = None,
+) -> tuple[bool, str]:
+    """Cài torch CUDA vào env hiện tại. Trả (thành công, thông điệp cuối).
+
+    on_log nhận từng dòng log (để UI cập nhật). Đây là hàm blocking — gọi trong
+    thread/generator của Gradio, đừng gọi thẳng trên event loop chính.
+    """
+    channel = choose_cuda_channel(driver_cuda)
+    if channel is None:
+        return False, (
+            "Driver NVIDIA quá cũ so với các bản torch CUDA hiện có. "
+            "Hãy cập nhật driver rồi thử lại, hoặc cài torch thủ công."
+        )
+
+    cmd = torch_install_command(channel)
+    if on_log:
+        on_log(f"Cài torch CUDA ({channel}) — tải ~2–3 GB, cần ~5 GB ổ trống, vui lòng đợi…")
+        on_log(" ".join(cmd))
+
+    exit_code: int | None = None
+    for line in _stream_pip(cmd):
+        if line.startswith("__EXIT__:"):
+            exit_code = int(line.split(":", 1)[1])
+            continue
+        if on_log and line:
+            on_log(line)
+
+    if exit_code != 0:
+        return False, (
+            f"Cài torch thất bại (mã lỗi {exit_code}). "
+            "Kiểm tra mạng/dung lượng đĩa, hoặc cài thủ công theo README."
+        )
+
+    # Cài xong chưa đủ — xác minh torch THẬT SỰ thấy CUDA (bắt 'already satisfied'
+    # hoặc bản không khớp driver).
+    ok, verify_msg = verify_torch_cuda()
+    if ok:
+        return True, (
+            f"Đã cài torch CUDA ({channel}) — {verify_msg} "
+            "Hãy TẮT và MỞ LẠI app (stop rồi start) để bật GPU."
+        )
+    return False, verify_msg

src/hardware.py

@@ -0,0 +1,237 @@
+"""Auto-detect CPU/GPU and recommend CT2 batch + thread settings."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from functools import lru_cache
+
+# Phát hiện GPU NVIDIA vật lý qua nvidia-smi TRƯỚC khi (có thể) mask CUDA.
+# Cần làm trước vì sau khi set CUDA_VISIBLE_DEVICES=-1 thì cả ct2 lẫn torch đều
+# không thấy GPU nữa — UI sẽ không biết "máy có GPU nhưng đang chạy CPU".
+PHYSICAL_NVIDIA_GPU = False      # máy có card NVIDIA thật?
+PHYSICAL_GPU_NAME: str | None = None
+DRIVER_CUDA_VERSION: str | None = None  # CUDA tối đa driver hỗ trợ, vd "13.2"
+
+
+def _detect_nvidia_gpu() -> None:
+    """Chạy nvidia-smi để biết có GPU NVIDIA + CUDA version tối đa của driver."""
+    global PHYSICAL_NVIDIA_GPU, PHYSICAL_GPU_NAME, DRIVER_CUDA_VERSION
+    if shutil.which("nvidia-smi") is None:
+        return
+    try:
+        # Bảng nvidia-smi chứa "CUDA Version: X.Y" ở header.
+        header = subprocess.run(
+            ["nvidia-smi"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        name = subprocess.run(
+            ["nvidia-smi", "--query-gpu=name", "--format=csv,noheader"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except Exception:
+        return
+    if name.returncode == 0 and name.stdout.strip():
+        PHYSICAL_NVIDIA_GPU = True
+        PHYSICAL_GPU_NAME = name.stdout.strip().splitlines()[0].strip()
+    if header.returncode == 0:
+        match = re.search(r"CUDA Version:\s*([0-9]+\.[0-9]+)", header.stdout)
+        if match:
+            DRIVER_CUDA_VERSION = match.group(1)
+
+
+def _torch_cuda_usable() -> bool:
+    try:
+        import torch
+
+        return bool(torch.cuda.is_available())
+    except Exception:
+        return False
+
+
+def _guard_ct2_cuda_before_import() -> None:
+    """Chặn CTranslate2 dò CUDA khi máy có GPU NVIDIA nhưng KHÔNG có torch-CUDA.
+
+    CTranslate2 (wheel pip) tự phát hiện CUDA độc lập với torch. Nếu máy có GPU
+    NVIDIA, nó sẽ cố nạp cuBLAS lúc translate_batch — nhưng cuBLAS DLL thường do
+    bản torch-CUDA cung cấp. Engine mặc định của app KHÔNG cài torch, nên nhóm
+    "có GPU + không torch-CUDA" sẽ crash 'cublas64_12.dll not found'.
+
+    CTranslate2 đọc CUDA_VISIBLE_DEVICES MỘT LẦN lúc init, nên phải set TRƯỚC khi
+    `import ctranslate2`. Chỉ ép CPU khi không có torch-CUDA khả dụng; người dùng
+    torch-CUDA giữ nguyên GPU (cuBLAS của họ do torch cấp).
+    """
+    if os.environ.get("CUDA_VISIBLE_DEVICES") is not None:
+        return  # tôn trọng lựa chọn của người dùng
+    if os.environ.get("HACHIMIMT_FORCE_CT2_CUDA", "").strip() == "1":
+        return  # cho phép tự chịu trách nhiệm bật CUDA cho CT2
+    if not _torch_cuda_usable():
+        os.environ["CUDA_VISIBLE_DEVICES"] = "-1"
+
+
+_detect_nvidia_gpu()
+_guard_ct2_cuda_before_import()
+
+import ctranslate2
+
+BATCH_MIN = 4
+BATCH_MAX = 128
+THREAD_MIN = 1
+THREAD_MAX = 16
+TOKENIZE_WORKERS_MAX = 16
+TOKENIZE_WORKERS_MIN = 1
+
+
+@dataclass(frozen=True)
+class HardwareProfile:
+    cpu_logical: int
+    has_cuda: bool
+    gpu_name: str | None
+    vram_gb: float | None
+    batch_size: int
+    ct2_threads: int
+    tokenize_workers: int
+
+    @property
+    def summary(self) -> str:
+        cpu_part = f"CPU {self.cpu_logical} luồng"
+        if self.has_cuda and self.gpu_name:
+            vram = f"{self.vram_gb:.1f} GB" if self.vram_gb else "?"
+            device_part = f"GPU {self.gpu_name} ({vram})"
+        else:
+            device_part = "GPU không có — chạy CPU"
+        return (
+            f"{cpu_part} · {device_part} · "
+            f"batch={self.batch_size} · threads={self.ct2_threads} · "
+            f"tokenize_workers={self.tokenize_workers}"
+        )
+
+
+def _env_int(name: str) -> int | None:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return None
+    try:
+        return max(1, int(raw))
+    except ValueError:
+        return None
+
+
+def _clamp_batch(value: int) -> int:
+    return max(BATCH_MIN, min(BATCH_MAX, int(value)))
+
+
+def _clamp_threads(value: int) -> int:
+    return max(THREAD_MIN, min(THREAD_MAX, int(value)))
+
+
+def _clamp_tokenize_workers(value: int) -> int:
+    return max(TOKENIZE_WORKERS_MIN, min(TOKENIZE_WORKERS_MAX, int(value)))
+
+
+def _round_batch(value: int) -> int:
+    """Làm tròn batch về bội số 4 để ổn định hơn trên GPU."""
+    rounded = max(BATCH_MIN, round(value / 4) * 4)
+    return _clamp_batch(rounded)
+
+
+def recommend_tokenize_workers(cpu_logical: int) -> int:
+    return max(4, min(cpu_logical, TOKENIZE_WORKERS_MAX))
+
+
+def recommend_batch_size(cpu_logical: int, *, has_cuda: bool, vram_gb: float | None) -> int:
+    if has_cuda:
+        # GPU: model ~60M INT8 — VRAM 12GB c�� thể batch lớn; CPU mạnh tokenize song song.
+        if vram_gb:
+            vram_batch = int(vram_gb * 8)
+        else:
+            # Khi không cài torch CUDA, CT2 vẫn detect được CUDA nhưng không biết VRAM.
+            # Chọn mức vừa phải để chạy ổn trên nhiều máy, người dùng mạnh có thể override.
+            vram_batch = 64
+        cpu_batch = max(16, cpu_logical * 3)
+        return _round_batch(min(vram_batch, cpu_batch, BATCH_MAX))
+
+    # CPU-only: scale tuyến tính theo số luồng.
+    return _round_batch(max(4, cpu_logical))
+
+
+def recommend_ct2_threads(cpu_logical: int, *, has_cuda: bool) -> int:
+    if has_cuda:
+        # GPU inference: tăng thread CT2 để CPU xử lý song song hơn.
+        return _clamp_threads(min(cpu_logical, 12))
+
+    # CPU inference: dùng nhiều luồng hơn.
+    return _clamp_threads(cpu_logical)
+
+
+@lru_cache(maxsize=1)
+def _optional_torch():
+    try:
+        import torch
+    except Exception:
+        return None
+    return torch
+
+
+def _ct2_has_cuda() -> bool:
+    try:
+        return ctranslate2.get_cuda_device_count() > 0
+    except Exception:
+        return False
+
+
+def detect_hardware_profile() -> HardwareProfile:
+    cpu_logical = os.cpu_count() or 4
+    has_cuda = _ct2_has_cuda()
+    gpu_name: str | None = None
+    vram_gb: float | None = None
+
+    if has_cuda:
+        torch = _optional_torch()
+        if torch is not None:
+            try:
+                if torch.cuda.is_available():
+                    props = torch.cuda.get_device_properties(0)
+                    gpu_name = props.name
+                    vram_gb = props.total_memory / (1024**3)
+            except Exception:
+                pass
+        if gpu_name is None:
+            gpu_name = "CUDA GPU"
+
+    env_batch = _env_int("HACHIMIMT_BATCH_SIZE")
+    env_threads = _env_int("HACHIMIMT_THREADS")
+    env_tokenize_workers = _env_int("HACHIMIMT_TOKENIZE_WORKERS")
+
+    batch_size = (
+        _clamp_batch(env_batch)
+        if env_batch is not None
+        else recommend_batch_size(cpu_logical, has_cuda=has_cuda, vram_gb=vram_gb)
+    )
+    ct2_threads = (
+        _clamp_threads(env_threads)
+        if env_threads is not None
+        else recommend_ct2_threads(cpu_logical, has_cuda=has_cuda)
+    )
+    tokenize_workers = (
+        _clamp_tokenize_workers(env_tokenize_workers)
+        if env_tokenize_workers is not None
+        else recommend_tokenize_workers(cpu_logical)
+    )
+
+    return HardwareProfile(
+        cpu_logical=cpu_logical,
+        has_cuda=has_cuda,
+        gpu_name=gpu_name,
+        vram_gb=vram_gb,
+        batch_size=batch_size,
+        ct2_threads=ct2_threads,
+        tokenize_workers=tokenize_workers,
+    )

src/honorific_normalize.py

@@ -0,0 +1,321 @@
+"""Chuẩn hóa xưng hô Hán-Việt cho bản dịch (hậu kỳ, neo nguồn ZH).
+
+Người đọc muốn xưng hô nhất quán Hán-Việt (tỷ/muội/ca ca/sư huynh/hắn/nàng/ta),
+không nhảy "chị em" ↔ "tỷ muội" trong một chương.
+
+Nguyên lý: CHỈ đổi khi NGUỒN tiếng Trung có từ xưng hô tường minh (neo nguồn ZH).
+Chỗ nguồn không có từ → không đụng. KHÔNG suy luận quan hệ. Thuần hậu kỳ, không
+cần model. Áp per-row (mỗi câu/đoạn có cặp zh-vi riêng → neo chính xác).
+
+API (khớp phong cách text_preprocess.py):
+  normalize_honorifics(zh, vi, mode="off", kinship_mode="always") -> str
+  honorific_message(mode) -> str
+  HONORIFIC_MODES = {off, safe, xianxia_strict}
+
+Port từ MT-zhvi-medium-train/scripts/pronoun/honorific_normalizer.py (qua TDD,
+68 test). Đại từ chỉ bật ở mode xianxia_strict + gate cổ trang (tránh phá văn
+hiện đại); thân tộc đơn (哥/姐 1 ký tự) TẮT vì hay trùng tên riêng/loanword.
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections import Counter
+
+HONORIFIC_OFF = "off"
+HONORIFIC_SAFE = "safe"
+HONORIFIC_STRICT = "xianxia_strict"
+HONORIFIC_MODES = {HONORIFIC_OFF, HONORIFIC_SAFE, HONORIFIC_STRICT}
+
+# ---------------------------------------------------------------------------
+# Bảng tra: ZH-term → {hv (đích Hán-Việt), drift (biến thể VI cần thay), tier}
+#   tier "kinship" = thân tộc/cặp/đồng môn/title (áp ở safe)
+#   tier "kinship_single" = thân tộc 1 ký tự (TẮT — hay trùng proper-noun)
+#   tier "pronoun" = đại từ (chỉ xianxia_strict + gate cổ trang)
+# hv=None = cụm KHÔNG phải xưng hô (chiếm span longest-match, chặn term ngắn lọt).
+# ---------------------------------------------------------------------------
+_RAW = {
+    # cụm không phải xưng hô (blacklist)
+    "哥们": {"hv": None}, "哥们儿": {"hv": None}, "哥儿们": {"hv": None},
+    "大哥大": {"hv": None}, "弟媳": {"hv": None}, "弟妹": {"hv": None},
+    "小姐": {"hv": None}, "大嫂": {"hv": None}, "嫂子": {"hv": None}, "嫂": {"hv": None},
+    # ngoài scope đại từ số nhiều / compound sở hữu: chặn term số ít lọt vào
+    "我们": {"hv": None}, "咱们": {"hv": None}, "你们": {"hv": None},
+    "他们": {"hv": None}, "她们": {"hv": None},
+    "我校": {"hv": None}, "我司": {"hv": None}, "我国": {"hv": None},
+    "我方": {"hv": None}, "我院": {"hv": None},
+    # đồng môn tu tiên
+    "师兄": {"hv": "sư huynh", "drift": ["sư ca", "sư anh"], "tier": "kinship"},
+    "师弟": {"hv": "sư đệ", "drift": ["sư em"], "tier": "kinship"},
+    "师姐": {"hv": "sư tỷ", "drift": ["sư chị"], "tier": "kinship"},
+    "师妹": {"hv": "sư muội", "drift": ["sư em"], "tier": "kinship"},
+    "师叔": {"hv": "sư thúc", "drift": [], "tier": "kinship"},
+    "师伯": {"hv": "sư bá", "drift": [], "tier": "kinship"},
+    "师祖": {"hv": "sư tổ", "drift": [], "tier": "kinship"},
+    "徒儿": {"hv": "đồ nhi", "drift": [], "tier": "kinship"},
+    # cặp collective
+    "姐妹": {"hv": "tỷ muội", "drift": ["chị em"], "tier": "kinship"},
+    "兄弟": {"hv": "huynh đệ", "drift": ["anh em"], "tier": "kinship"},
+    "兄妹": {"hv": "huynh muội", "drift": ["anh em"], "tier": "kinship"},
+    "姐弟": {"hv": "tỷ đệ", "drift": ["chị em"], "tier": "kinship"},
+    "师徒": {"hv": "sư đồ", "drift": [], "tier": "kinship"},
+    # thân tộc đôi
+    "姐姐": {"hv": "tỷ tỷ", "drift": ["chị gái", "chị"], "tier": "kinship"},
+    "妹妹": {"hv": "muội muội", "drift": ["em gái"], "tier": "kinship"},
+    "哥哥": {"hv": "ca ca", "drift": ["anh trai", "anh"], "tier": "kinship"},
+    "弟弟": {"hv": "đệ đệ", "drift": ["em trai"], "tier": "kinship"},
+    # titles
+    "大哥": {"hv": "đại ca", "drift": ["anh cả", "anh lớn", "anh hai"], "tier": "kinship"},
+    "公子": {"hv": "công tử", "drift": [], "tier": "kinship"},
+    "姑娘": {"hv": "cô nương", "drift": [], "tier": "kinship"},
+    "师尊": {"hv": "sư tôn", "drift": [], "tier": "kinship"},
+    "师父": {"hv": "sư phụ", "drift": [], "tier": "kinship"},
+    "前辈": {"hv": "tiền bối", "drift": [], "tier": "kinship"},
+    "晚辈": {"hv": "vãn bối", "drift": [], "tier": "kinship"},
+    "本座": {"hv": "bản tọa", "drift": [], "tier": "kinship"},
+    # thân tộc ĐƠN (TẮT mặc định — 1 ký tự hay trùng proper-noun 哥伦比亚/空姐)
+    "姐": {"hv": "tỷ", "drift": ["chị"], "tier": "kinship_single"},
+    "妹": {"hv": "muội", "drift": [], "tier": "kinship_single"},
+    "哥": {"hv": "ca", "drift": ["anh"], "tier": "kinship_single"},
+    "弟": {"hv": "đệ", "drift": [], "tier": "kinship_single"},
+    # đại từ (pronoun) — drift đã loại từ trùng tên riêng (anh/chị) + "mình"
+    "你": {"hv": "ngươi", "drift": ["cậu", "bạn", "m��y"], "tier": "pronoun"},
+    "您": {"hv": "ngài", "drift": ["ông", "bác"], "tier": "pronoun"},
+    "他": {"hv": "hắn", "drift": ["anh ấy", "anh ta", "cậu ấy", "cậu ta", "gã"], "tier": "pronoun"},
+    "她": {"hv": "nàng", "drift": ["cô ấy", "cô ta", "ả"], "tier": "pronoun"},
+    "我": {"hv": "ta", "drift": ["tôi", "tớ"], "tier": "pronoun"},
+}
+
+HONORIFIC_MAP: dict[str, dict] = {}
+for _k, _v in _RAW.items():
+    _e = dict(_v)
+    if _e.get("drift"):
+        _e["drift"] = sorted(_e["drift"], key=len, reverse=True)  # phrase dài trước
+    HONORIFIC_MAP[_k] = _e
+
+_TERMS_BY_LEN = sorted(HONORIFIC_MAP.keys(), key=len, reverse=True)
+_TARGET_LONG_PHRASES = tuple(
+    sorted(
+        {
+            drift
+            for entry in HONORIFIC_MAP.values()
+            for drift in entry.get("drift", [])
+            if " " in drift
+        },
+        key=len,
+        reverse=True,
+    )
+)
+_GENERIC_KINSHIP_SINGLE_DRIFTS = {"anh", "chị", "em"}
+
+WUXIA_SIGNALS = [
+    "修士", "修真", "修仙", "元婴", "金丹", "筑基", "真君", "法宝", "丹药", "灵气",
+    "仙人", "仙子", "剑修", "渡劫", "结丹", "化神", "真人", "道君", "宗门", "灵根",
+    "本座", "贫道", "道友", "天劫", "神识", "真元", "灵石", "符箓", "阵法", "飞剑",
+]
+MODERN_SIGNALS = [
+    "公司", "大学", "电话", "手机", "电脑", "网络", "汽车", "老板", "经理", "项目",
+    "咖啡", "地铁", "飞机", "酒店", "警察", "医院", "护士", "短信", "微信", "视频",
+    "直播", "电视", "银行", "信用卡", "互联网", "程序", "软件", "总裁", "董事长",
+]
+
+
+def genre_score(zh: str) -> tuple[int, int]:
+    c = sum(1 for s in WUXIA_SIGNALS if s in zh)
+    m = sum(1 for s in MODERN_SIGNALS if s in zh)
+    return c, m
+
+
+def is_classical(zh: str) -> bool:
+    """Có signal cổ trang VÀ không lẫn hiện đại → coi là cổ trang (bảo thủ).
+    Nếu có signal hiện đại thì cần cổ trang áp đảo (chặn 'hiện đại tu tiên')."""
+    c, m = genre_score(zh)
+    if m == 0:
+        return c >= 1
+    return c >= 2 and c > m
+
+
+def longest_match_mentions(zh: str) -> list[str]:
+    """Quét nguồn trái→phải, tại mỗi vị trí chọn term dài nhất.
+
+    Cách này giữ đúng thứ tự mention trong nguồn và vẫn chặn term ngắn lọt vào
+    span term dài (哥哥 chặn 哥; 我们 chặn 我).
+    """
+    mentions: list[str] = []
+    i = 0
+    while i < len(zh):
+        matched = ""
+        for term in _TERMS_BY_LEN:
+            if zh.startswith(term, i):
+                matched = term
+                break
+        if matched:
+            mentions.append(matched)
+            i += len(matched)
+        else:
+            i += 1
+    return mentions
+
+
+def longest_match_terms(zh: str) -> dict[str, int]:
+    return dict(Counter(longest_match_mentions(zh)))
+
+
+def _match_case(new: str, old: str) -> str:
+    return new[:1].upper() + new[1:] if old[:1].isupper() else new
+
+
+def _target_spans(text: str, phrase: str) -> list[tuple[int, int]]:
+    pat = r"(?<![A-Za-zÀ-ỹ])" + re.escape(phrase) + r"(?![A-Za-zÀ-ỹ])"
+    return [(m.start(), m.end()) for m in re.finditer(pat, text, flags=re.IGNORECASE)]
+
+
+def _inside_any_span(start: int, end: int, spans: list[tuple[int, int]]) -> bool:
+    return any(span_start <= start and end <= span_end for span_start, span_end in spans)
+
+
+def _protected_target_spans(vi: str, current_variant: str) -> list[tuple[int, int]]:
+    """Các phrase dài không được để drift một từ ăn vào giữa."""
+    spans: list[tuple[int, int]] = []
+    for phrase in _TARGET_LONG_PHRASES:
+        if phrase == current_variant:
+            continue
+        if f" {current_variant.casefold()}" not in f" {phrase.casefold()}":
+            continue
+        spans.extend(_target_spans(vi, phrase))
+    return spans
+
+
+def _has_pronoun_competition(variant: str, source_mentions: list[str]) -> bool:
+    variant = variant.casefold()
+    if variant == "anh":
+        return "他" in source_mentions
+    if variant == "em":
+        return "你" in source_mentions
+    return False
+
+
+def _replace_one_drift(
+    vi: str,
+    variants: list[str],
+    target: str,
+    *,
+    tier: str,
+    source_mentions: list[str],
+) -> str:
+    """Thay một mention theo thứ tự nguồn.
+
+    Nếu chỉ còn drift một từ mơ hồ (`anh/chị/em`) trong dòng có đại từ nguồn
+    cạnh tranh, bỏ qua để tránh kiểu `Anh ấy` → `Ca ca ấy`.
+    """
+    done = 0
+    for v in variants:
+        if tier.startswith("kinship") and v.casefold() in _GENERIC_KINSHIP_SINGLE_DRIFTS:
+            if _has_pronoun_competition(v, source_mentions):
+                continue
+        pat = r"(?<![A-Za-zÀ-ỹ])(" + re.escape(v) + r")(?![A-Za-zÀ-ỹ])"
+        protected_spans = _protected_target_spans(vi, v)
+
+        def repl(m):
+            nonlocal done
+            if done >= 1 or _inside_any_span(m.start(), m.end(), protected_spans):
+                return m.group(0)
+            done += 1
+            return _match_case(target, m.group(0))
+
+        vi = re.sub(pat, repl, vi, flags=re.IGNORECASE)
+        if done:
+            break
+    return vi
+
+
+def _skip(tier: str, classical: bool, apply_kinship: bool, apply_pronouns: bool,
+          kinship_mode: str, enable_single: bool) -> bool:
+    """True = bỏ qua term. 2 cờ độc lập: apply_kinship (thân tộc/cặp/title) +
+    apply_pronouns (đại từ). Đại từ luôn còn gate cổ trang."""
+    if tier == "pronoun":
+        return (not apply_pronouns) or (not classical)
+    if tier == "kinship_single":
+        if not apply_kinship or not enable_single:
+            return True
+        return kinship_mode == "classical_only" and not classical
+    if tier == "kinship":
+        if not apply_kinship:
+            return True
+        return kinship_mode == "classical_only" and not classical
+    return False
+
+
+def honorific_mode(mode: str | None) -> str:
+    mode = (mode or HONORIFIC_OFF).strip().lower()
+    return mode if mode in HONORIFIC_MODES else HONORIFIC_OFF
+
+
+def _mode_to_flags(mode: str) -> tuple[bool, bool]:
+    """map mode lũy tiến (tương thích ngược) → (apply_kinship, apply_pronouns)."""
+    mode = honorific_mode(mode)
+    if mode == HONORIFIC_SAFE:
+        return True, False
+    if mode == HONORIFIC_STRICT:
+        return True, True
+    return False, False  # off
+
+
+def normalize_honorifics(zh: str, vi: str, mode: str | None = None,
+                         *, apply_kinship: bool | None = None,
+                         apply_pronouns: bool | None = None,
+                         kinship_mode: str = "always",
+                         enable_single: bool = False,
+                         classical_context: bool | None = None) -> str:
+    """Chuẩn hóa xưng hô VI theo neo nguồn ZH.
+
+    2 cờ ĐỘC LẬP (ưu tiên nếu truyền): apply_kinship (thân tộc tỷ/muội/ca ca...) +
+    apply_pronouns (đại từ ngươi/hắn/nàng/ta, vẫn gate cổ trang). Cho phép mọi tổ hợp,
+    gồm 'chỉ đại từ'. `mode` (off/safe/xianxia_strict) = tương thích ngược, map sang
+    2 cờ khi 2 cờ không được truyền."""
+    if apply_kinship is None and apply_pronouns is None:
+        apply_kinship, apply_pronouns = _mode_to_flags(mode)
+    else:
+        apply_kinship = bool(apply_kinship)
+        apply_pronouns = bool(apply_pronouns)
+
+    if (not apply_kinship and not apply_pronouns) or not vi or not zh:
+        return vi
+    vi = unicodedata.normalize("NFC", vi)
+    zh = unicodedata.normalize("NFC", zh)
+    mentions = longest_match_mentions(zh)
+    if not mentions:
+        return vi
+    classical = bool(classical_context) if classical_context is not None else is_classical(zh)
+    for term in mentions:
+        entry = HONORIFIC_MAP[term]
+        hv = entry.get("hv")
+        if hv is None:
+            continue
+        if _skip(entry["tier"], classical, apply_kinship, apply_pronouns,
+                 kinship_mode, enable_single):
+            continue
+        drift = entry.get("drift", [])
+        if not drift:
+            continue
+        vi = _replace_one_drift(
+            vi,
+            drift,
+            hv,
+            tier=entry["tier"],
+            source_mentions=mentions,
+        )
+    return vi
+
+
+# alias để test suite port (dùng tên `normalize`) chạy được
+normalize = normalize_honorifics
+
+
+def honorific_message(mode: str | None) -> str:
+    mode = honorific_mode(mode)
+    if mode == HONORIFIC_OFF:
+        return "Giữ nguyên xưng hô theo bản dịch."
+    if mode == HONORIFIC_SAFE:
+        return "Đã chuẩn hóa xưng hô thân tộc sang Hán-Việt (tỷ/muội/ca ca...)."
+    return "Đã chuẩn hóa xưng hô Hán-Việt gồm cả đại từ (ngươi/hắn/nàng/ta)."

src/postprocess_policy.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+
+GENRE_MODERN = "modern"
+GENRE_CLASSICAL = "classical"
+GENRE_MIXED_GUARD = "mixed_guard"
+GENRE_UNKNOWN_GUARD = "unknown_guard"
+
+
+@dataclass(frozen=True)
+class GenreDecision:
+    route: str
+    classical_score: int
+    modern_score: int
+    evidence: tuple[str, ...]
+    reason: str
+
+    @property
+    def is_modern(self) -> bool:
+        return self.route == GENRE_MODERN
+
+    @property
+    def is_classical(self) -> bool:
+        return self.route == GENRE_CLASSICAL
+
+
+BOOK_MODERN_HINTS = ("没钱修什么仙",)
+
+HARD_CLASSICAL_SIGNALS = (
+    "修士", "修真", "修仙", "元婴", "金丹", "筑基", "真君", "法宝", "丹药", "灵气",
+    "仙人", "仙子", "剑修", "渡劫", "结丹", "化神", "真人", "道君", "宗门", "灵根",
+    "本座", "贫道", "道友", "天劫", "神识", "真元", "灵石", "符箓", "阵法", "飞剑",
+    "皇帝", "王爷", "陛下", "皇后", "太后", "公主", "太子", "侯爷", "世子",
+    "江湖", "武林", "内力", "剑客", "掌门", "少侠", "师尊", "师父", "前辈",
+)
+
+HARD_MODERN_SIGNALS = (
+    "公司", "大学", "高中", "初中", "小学", "学校", "老师", "班主任", "同学", "学生",
+    "课堂", "上课", "课程", "高一", "高二", "高三", "面试", "招生", "学费", "补习班",
+    "电话", "手机", "电脑", "网络", "汽车", "地铁", "飞机", "酒店", "警察", "医院",
+    "护士", "短信", "微信", "视频", "直播", "电视", "银行", "信用卡", "互联网",
+    "程序", "软件", "老板", "经理", "项目", "咖啡", "贷款", "借款", "逾期",
+    "财务公司", "平台", "总裁", "董事长", "办公室",
+)
+
+
+def _joined_sources(rows_or_text: Iterable[tuple[int, str, str]] | str) -> str:
+    if isinstance(rows_or_text, str):
+        return rows_or_text
+    return "\n".join(str(source) for _, source, _ in rows_or_text)
+
+
+def _hits(text: str, terms: tuple[str, ...]) -> tuple[str, ...]:
+    return tuple(term for term in terms if term in text)
+
+
+def classify_genre(rows_or_text: Iterable[tuple[int, str, str]] | str) -> GenreDecision:
+    text = _joined_sources(rows_or_text)
+    book_hits = _hits(text, BOOK_MODERN_HINTS)
+    if book_hits:
+        return GenreDecision(
+            route=GENRE_MODERN,
+            classical_score=0,
+            modern_score=len(book_hits),
+            evidence=book_hits,
+            reason="book_modern_hint",
+        )
+
+    classical_hits = _hits(text, HARD_CLASSICAL_SIGNALS)
+    modern_hits = _hits(text, HARD_MODERN_SIGNALS)
+    classical_score = len(classical_hits)
+    modern_score = len(modern_hits)
+    evidence = (*classical_hits[:8], *modern_hits[:8])
+
+    if classical_score and not modern_score:
+        return GenreDecision(GENRE_CLASSICAL, classical_score, modern_score, evidence, "classical_signal")
+    if modern_score and not classical_score:
+        return GenreDecision(GENRE_MODERN, classical_score, modern_score, evidence, "modern_signal")
+    if classical_score and modern_score:
+        return GenreDecision(GENRE_MIXED_GUARD, classical_score, modern_score, evidence, "mixed_signal")
+    return GenreDecision(GENRE_UNKNOWN_GUARD, classical_score, modern_score, evidence, "no_signal")
+
+
+def v9_route_for_decision(decision: GenreDecision) -> str:
+    if decision.route == GENRE_MODERN:
+        return "modern_school"
+    if decision.route == GENRE_UNKNOWN_GUARD:
+        return "unknown_copy_guard"
+    return "xianxia_copy_guard"
+

src/progress_tracker.py

@@ -0,0 +1,47 @@
+"""Shared progress state — polled by UI timer during long translation."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+
+
+@dataclass
+class ProgressState:
+    pct: float = 0.0
+    message: str = "Sẵn sàng."
+    running: bool = False
+
+
+_lock = threading.Lock()
+_state = ProgressState()
+
+
+def set_progress(pct: float, message: str, *, running: bool = True) -> None:
+    with _lock:
+        _state.pct = max(0.0, min(100.0, float(pct)))
+        _state.message = message
+        _state.running = running
+
+
+def finish_progress(message: str) -> None:
+    with _lock:
+        _state.pct = 100.0
+        _state.message = message
+        _state.running = False
+
+
+def reset_progress(message: str = "Sẵn sàng.") -> None:
+    with _lock:
+        _state.pct = 0.0
+        _state.message = message
+        _state.running = False
+
+
+def snapshot() -> ProgressState:
+    with _lock:
+        return ProgressState(
+            pct=_state.pct,
+            message=_state.message,
+            running=_state.running,
+        )

src/pronoun_harmonizer_v9.py

@@ -0,0 +1,906 @@
+"""Runtime V9 pronoun stabilizer for HachimiMT UI rows.
+
+This is a self-contained port of the promoted vp-mt-train V9 runtime layer.
+It targets modern relation pronoun stability (teacher/student, mother/child,
+peer, inner monologue guards) and leaves xianxia/cổ trang text untouched by
+default through a copy-guard route.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from typing import Any
+
+from postprocess_policy import classify_genre, v9_route_for_decision
+
+ROUTES = ("auto", "modern_school", "xianxia_copy_guard", "unknown_copy_guard")
+POLICY_MODES = ("stability_first",)
+
+WORD_CHARS = r"\wÀ-ỹ"
+ALLOWED_PREVIOUS_TA = {"người", "anh", "chị", "cô", "ông", "bà", "hắn", "cậu", "chúng", "trường"}
+ALLOWED_PREVIOUS_TOI = {"chúng", "tụi", "bọn", "mẹ", "bố", "cha"}
+
+SCHOOL_EXCLUSIVE_SOURCE_TERMS = ("本校", "我校", "学校", "校方", "校长", "招生", "入学", "全校")
+SCHOOL_CONTEXT_SOURCE_TERMS = ("老师", "教师", "班主任", "同学", "学生", "课堂", "上课", "课程")
+TEACHER_SOURCE_TERMS = ("老师", "教师", "班主任")
+TEACHER_STUDENT_SOURCE_TERMS = (
+    "卷子", "办公室", "高一", "高二", "高三", "月考", "示范班", "学生", "基础",
+)
+MOTHER_SOURCE_TERMS = ("母亲", "妈妈", "老妈", "妈")
+TEACHER_SPEAKER_SOURCE_TERMS = ("王海", "体育老师")
+NON_TEACHER_SPEAKER_SOURCE_TERMS = ("白真真", "周天翊", "少年", "少女")
+INNER_MONOLOGUE_SOURCE_TERMS = ("心中", "心道", "暗道", "心想")
+TEACHER_WINDOW_TAGS = {"teacher_student_window", "student_teacher_window"}
+FORMAL_DEBT_SOURCE_TERMS = ("借款", "逾期", "平台", "贷款", "财务公司", "家属")
+INSTITUTION_WE_SOURCE_TERMS = (
+    "我们的学校", "我们学校", "我校", "我们为", "我们推出", "我们了解到", "我们平台",
+    "我们公司", "我们知道", "我们这", "我们补习班", "我们在饮用水",
+    "我们指定",
+)
+INSTITUTION_APPLICANT_SOURCE_TERMS = ("面试官", "报考")
+PEER_CLASSMATE_SOURCE_TERMS = ("白真真", "帮我还了债")
+SCHOOL_APPLICATION_SOURCE_TERMS = ("我能报考", "我可以报考", "我能报名", "我可以报名")
+CHILD_TO_MOTHER_SOURCE_TERMS = ("妈，", "妈,", "妈妈，", "妈妈,")
+DIRECT_MOTHER_SPEAKER_MARKERS = ("母亲：", "母亲:", "妈妈：", "妈妈:", "妈：", "妈:")
+MOTHER_MESSAGE_CONTEXT_TERMS = ("母亲发来的消息", "母亲发来")
+APPLICANT_CONTEXT_SOURCE_TERMS = (
+    "面试", "面试官", "考生", "报考", "入学", "招生", "学费", "学校", "高中",
+    "录取率", "入学标准", "推荐生", "贫困生", "特长生", "补习班",
+)
+APPLICANT_SELF_SOURCE_TERMS = ("张羽", "考生", "同学")
+GENERIC_MODERN_DIALOGUE_GUARD_TERMS = (
+    "老者", "少年", "师尊", "前辈", "天庭", "传功", "功力", "法力贷", "本尊",
+)
+OLDER_BROTHER_SOURCE_TERMS = ("哥哥", "你哥", "哥")
+YOUNGER_SISTER_SOURCE_TERMS = ("妹妹", "妹")
+SIBLING_CONTEXT_SOURCE_TERMS = (
+    "哥哥", "妹妹", "弟弟", "姐姐", "兄妹", "姐妹", "姐弟", "兄弟",
+    "你哥", "你哥哥", "你姐", "你姐姐", "你弟", "你妹妹",
+)
+STABILITY_GENERIC_FLAG_PREFIXES = (
+    "forbidden:modern_you:",
+    "forbidden:modern_self:",
+    "watch:inclusive_we:",
+)
+ACTIONABLE_POLICY_TAGS = {
+    "teacher_student",
+    "student_teacher",
+    "family_mother_child",
+    "formal_debt_call",
+    "family_brother_to_sister",
+    "family_sister_to_brother_context",
+    "family_child_to_mother",
+    "school_application_self",
+    "institution_we_exclusive",
+    "institution_applicant",
+    "applicant_self",
+    "generic_modern_dialogue",
+    "sibling_older_brother_to_younger",
+    "sibling_younger_to_older_brother",
+}
+SUPERNATURAL_GUARD_TERMS = (
+    "布娃娃", "苍老", "神识", "戒指", "因果", "请神", "仪式", "愿望", "反噬", "魂飞魄散",
+)
+SUPERNATURAL_CONTEXT_TERMS = (
+    "布娃娃", "邪神", "苍老", "神识", "戒指", "因果", "请神", "仪式", "愿望", "反噬", "魂飞魄散",
+)
+WUXIA_ROUTE_TERMS = (
+    "修士", "修真", "修仙", "元婴", "金丹", "筑基", "真君", "法宝", "丹药", "灵气",
+    "仙人", "仙子", "剑修", "渡劫", "结丹", "化神", "真人", "道君", "宗门", "灵根",
+    "本座", "贫道", "道友", "天劫", "神识", "真元", "灵石", "符箓", "阵法", "飞剑",
+)
+MODERN_ROUTE_TERMS = (
+    "学校", "老师", "班主任", "同学", "学生", "高一", "高二", "高三", "公司", "电话",
+    "手机", "电脑", "网络", "老板", "经理", "项目", "咖啡", "银行", "贷款", "财务公司",
+    "母亲", "妈妈", "老妈", "妈", "哥哥", "妹妹", "姐姐", "弟弟", "总裁", "董事长", "办公室",
+)
+MODERN_BOOK_HINT_TERMS = ("没钱修什么仙",)
+
+
+def cap_like(source: str, replacement: str) -> str:
+    return replacement[:1].upper() + replacement[1:] if source and source[0].isupper() else replacement
+
+
+def replace_word(text: str, source: str, replacement: str) -> tuple[str, int]:
+    pattern = re.compile(rf"(?<![{WORD_CHARS}]){re.escape(source)}(?![{WORD_CHARS}])", re.IGNORECASE)
+    count = 0
+
+    def repl(match: re.Match[str]) -> str:
+        nonlocal count
+        count += 1
+        return cap_like(match.group(0), replacement)
+
+    return pattern.sub(repl, text), count
+
+
+def apply_replacement(text: str, source: str, replacement: str, applied: Counter[str], rule_name: str) -> str:
+    new_text, count = replace_word(text, source, replacement)
+    if count:
+        applied[rule_name] += count
+    return new_text
+
+
+def contains_source_any(source: str, terms: tuple[str, ...]) -> bool:
+    return any(term in source for term in terms)
+
+
+def source_has_all(source: str, terms: tuple[str, ...]) -> bool:
+    return all(term in source for term in terms)
+
+
+def has_speech_marker(source: str) -> bool:
+    return "“" in source or "”" in source or '"' in source or "：" in source or ":" in source
+
+
+def dialogue_prefix(source: str) -> str:
+    positions = [source.find(marker) for marker in ("“", '"', "：", ":") if source.find(marker) >= 0]
+    return source[: min(positions)] if positions else source
+
+
+def dialogue_suffix(source: str) -> str:
+    positions = [source.rfind(marker) for marker in ("”", '"') if source.rfind(marker) >= 0]
+    return source[max(positions) + 1 :] if positions else ""
+
+
+def prefix_has_non_teacher_speaker(prefix: str) -> bool:
+    return contains_source_any(prefix, NON_TEACHER_SPEAKER_SOURCE_TERMS)
+
+
+def is_clear_non_teacher_speaker_source(source: str) -> bool:
+    if not has_speech_marker(source):
+        return False
+    prefix = dialogue_prefix(source)
+    if not prefix_has_non_teacher_speaker(prefix):
+        return False
+    return contains_source_any(prefix, ("道", "说", "问", "开口", "哀叹", "凑到", "嘀咕"))
+
+
+def is_inner_monologue_source(source: str) -> bool:
+    return contains_source_any(dialogue_prefix(source), INNER_MONOLOGUE_SOURCE_TERMS)
+
+
+def is_teacher_speaker_source(source: str) -> bool:
+    if "你" not in source:
+        return False
+    prefix = dialogue_prefix(source)
+    if prefix_has_non_teacher_speaker(prefix):
+        return False
+    return contains_source_any(prefix, (*TEACHER_SOURCE_TERMS, *TEACHER_SPEAKER_SOURCE_TERMS))
+
+
+def standalone_pronoun_matches(text: str, term: str, excluded_previous: set[str]) -> list[re.Match[str]]:
+    matches: list[re.Match[str]] = []
+    pattern = re.compile(rf"(?<![{WORD_CHARS}]){re.escape(term)}(?![{WORD_CHARS}])", re.IGNORECASE)
+    for match in pattern.finditer(text):
+        before = text[: match.start()].rstrip()
+        previous = before.rsplit(" ", 1)[-1].casefold() if before else ""
+        if previous in excluded_previous:
+            continue
+        matches.append(match)
+    return matches
+
+
+def standalone_ta_matches(text: str) -> list[re.Match[str]]:
+    return standalone_pronoun_matches(text, "ta", ALLOWED_PREVIOUS_TA)
+
+
+def contains_word(text: str, term: str) -> bool:
+    if term == "ta":
+        return bool(standalone_ta_matches(text))
+    pattern = re.compile(rf"(?<![{WORD_CHARS}]){re.escape(term)}(?![{WORD_CHARS}])", re.IGNORECASE)
+    return bool(pattern.search(text))
+
+
+def school_we_is_exclusive(source: str, text: str) -> bool:
+    lowered = text.casefold()
+    if "trường ta" in lowered or "trường chúng ta" in lowered:
+        return True
+    return contains_word(text, "chúng ta") and contains_source_any(source, SCHOOL_EXCLUSIVE_SOURCE_TERMS)
+
+
+def detect_flags(source: str, text: str) -> list[str]:
+    flags: list[str] = []
+    if contains_word(text, "ngươi"):
+        flags.append("forbidden:modern_you:ngươi")
+    if contains_word(text, "ta"):
+        flags.append("forbidden:modern_self:ta")
+    if school_we_is_exclusive(source, text):
+        lowered = text.casefold()
+        if "trường ta" in lowered:
+            flags.append("forbidden:school_we_exclusive:trường ta")
+        if "trường chúng ta" in lowered:
+            flags.append("forbidden:school_we_exclusive:trường chúng ta")
+        if contains_word(text, "chúng ta"):
+            flags.append("forbidden:school_we_exclusive:chúng ta")
+    elif contains_word(text, "chúng ta"):
+        flags.append("watch:inclusive_we:chúng ta")
+    if contains_source_any(source, MOTHER_SOURCE_TERMS):
+        for phrase in ("nàng", "cô ấy", "cô ta"):
+            if contains_word(text, phrase):
+                flags.append(f"forbidden:mother_third_person_modern:{phrase}")
+    elif contains_word(text, "nàng"):
+        flags.append("forbidden:female_third_person_modern:nàng")
+    return flags
+
+
+def forbidden_flags(flags: list[str]) -> list[str]:
+    return [flag for flag in flags if flag.startswith("forbidden:")]
+
+
+def actionable_flags(flags: list[str]) -> list[str]:
+    return [
+        flag
+        for flag in flags
+        if not any(flag.startswith(prefix) for prefix in STABILITY_GENERIC_FLAG_PREFIXES)
+    ]
+
+
+def has_actionable_policy_tags(policy_tags: list[str]) -> bool:
+    return bool(set(policy_tags) & ACTIONABLE_POLICY_TAGS)
+
+
+def is_teacher_peer_source(source: str) -> bool:
+    return "老师" in source and source.count("老师") >= 2
+
+
+def is_teacher_to_student_source(source: str) -> bool:
+    if is_teacher_peer_source(source):
+        return False
+    if "你" not in source and "你们" not in source:
+        return False
+    if contains_source_any(source, TEACHER_SOURCE_TERMS):
+        return True
+    if "大学同学" in source:
+        return False
+    return contains_source_any(source, TEACHER_STUDENT_SOURCE_TERMS)
+
+
+def is_mother_to_child_source(source: str) -> bool:
+    if "你" not in source:
+        return False
+    if "妈，" in source or "妈," in source or "您" in source:
+        return False
+    return contains_source_any(source, ("妈", "妈妈", "母亲", "老妈"))
+
+
+def is_formal_debt_source(source: str) -> bool:
+    if ("您" in source or "先生" in source) and contains_source_any(source, FORMAL_DEBT_SOURCE_TERMS):
+        return True
+    return (
+        source_has_all(source, ("财务公司", "贷款"))
+        or source_has_all(source, ("家属", "贷款"))
+        or (contains_source_any(source, ("借款", "逾期")) and contains_source_any(source, ("母亲", "电话", "儿子")))
+    )
+
+
+def is_direct_mother_speaker(source: str) -> bool:
+    return contains_source_any(source, DIRECT_MOTHER_SPEAKER_MARKERS)
+
+
+def is_child_to_mother_source(source: str) -> bool:
+    return contains_source_any(source, CHILD_TO_MOTHER_SOURCE_TERMS)
+
+
+def has_sibling_context_source(source: str) -> bool:
+    return contains_source_any(source, SIBLING_CONTEXT_SOURCE_TERMS)
+
+
+def dialogue_suffix_has(source: str, terms: tuple[str, ...]) -> bool:
+    return contains_source_any(dialogue_suffix(source), terms)
+
+
+def is_older_brother_to_younger_source(source: str) -> bool:
+    prefix = dialogue_prefix(source)
+    if ("我是你哥" in source) or ("我是你哥哥" in source):
+        return True
+    if contains_source_any(prefix, OLDER_BROTHER_SOURCE_TERMS) and contains_source_any(source, YOUNGER_SISTER_SOURCE_TERMS):
+        return True
+    return False
+
+
+def is_younger_to_older_brother_source(source: str) -> bool:
+    prefix = dialogue_prefix(source)
+    if contains_source_any(prefix, YOUNGER_SISTER_SOURCE_TERMS) and contains_source_any(source, OLDER_BROTHER_SOURCE_TERMS):
+        return True
+    return False
+
+
+def sibling_reply_tag_from_source(source: str, fallback: str | None = None) -> str | None:
+    if is_older_brother_to_younger_source(source):
+        return "sibling_older_brother_to_younger"
+    if is_younger_to_older_brother_source(source):
+        return "sibling_younger_to_older_brother"
+    if dialogue_suffix_has(source, ("她", "妹妹")):
+        return "sibling_younger_to_older_brother"
+    if dialogue_suffix_has(source, ("他", "哥哥")):
+        return "sibling_older_brother_to_younger"
+    return fallback
+
+
+def is_brother_to_sister_source(source: str, text: str) -> bool:
+    return "姐" in source or contains_word(text, "chị")
+
+
+def is_peer_classmate_source(source: str) -> bool:
+    return contains_source_any(source, PEER_CLASSMATE_SOURCE_TERMS)
+
+
+def is_school_application_source(source: str) -> bool:
+    return contains_source_any(source, SCHOOL_APPLICATION_SOURCE_TERMS)
+
+
+def is_exclusive_institution_we_source(source: str) -> bool:
+    return contains_source_any(source, INSTITUTION_WE_SOURCE_TERMS)
+
+
+def is_institution_applicant_source(source: str) -> bool:
+    return "你" in source and contains_source_any(source, INSTITUTION_APPLICANT_SOURCE_TERMS)
+
+
+def is_institution_applicant_context_source(source: str) -> bool:
+    if is_institution_applicant_source(source):
+        return True
+    if source_has_all(source, ("张羽同学", "学费")):
+        return True
+    if source_has_all(source, ("同学", "适合", "高中")):
+        return True
+    return contains_source_any(source, APPLICANT_CONTEXT_SOURCE_TERMS) and has_speech_marker(source)
+
+
+def is_applicant_self_source(source: str) -> bool:
+    if "我" not in source:
+        return False
+    prefix = dialogue_prefix(source)
+    if contains_source_any(prefix, ("面试官", "老师", "主任", "母亲", "妈妈", "老者")):
+        return False
+    if contains_source_any(prefix, APPLICANT_SELF_SOURCE_TERMS):
+        return True
+    return contains_source_any(source, ("我想考上", "我会努力", "我已经自学", "我一定会"))
+
+
+def is_generic_modern_dialogue_source(source: str) -> bool:
+    if not has_speech_marker(source) or is_inner_monologue_source(source):
+        return False
+    if contains_source_any(source, (*SUPERNATURAL_GUARD_TERMS, *GENERIC_MODERN_DIALOGUE_GUARD_TERMS)):
+        return False
+    prefix = dialogue_prefix(source)
+    if not prefix.strip():
+        return False
+    if contains_source_any(source, (*MODERN_ROUTE_TERMS, *MODERN_BOOK_HINT_TERMS, *APPLICANT_CONTEXT_SOURCE_TERMS)):
+        return True
+    return contains_source_any(prefix, ("说", "道", "问", "答", "笑", "叹", "喊", "叫", "面试官", "张羽"))
+
+
+def is_likely_mother_message_source(source: str) -> bool:
+    stripped = source.lstrip()
+    if not (stripped.startswith("“") or stripped.startswith('"')):
+        return False
+    if contains_source_any(source, (*SUPERNATURAL_GUARD_TERMS, *GENERIC_MODERN_DIALOGUE_GUARD_TERMS)):
+        return False
+    if contains_source_any(source, ("面试官", "老师", "张羽", "老者", "少年")):
+        return False
+    return "你" in source or "我" in source
+
+
+def infer_policy_tags(source: str, text: str, flags: list[str]) -> tuple[list[str], list[str]]:
+    tags: list[str] = []
+    guard_reasons: list[str] = []
+    forbidden = forbidden_flags(flags)
+    has_context_signal = bool(
+        forbidden
+        or contains_word(text, "cậu")
+        or contains_word(text, "chúng ta")
+        or school_we_is_exclusive(source, text)
+        or is_school_application_source(source)
+        or is_exclusive_institution_we_source(source)
+        or is_institution_applicant_source(source)
+        or is_peer_classmate_source(source)
+        or is_child_to_mother_source(source)
+    )
+    if not has_context_signal:
+        return tags, guard_reasons
+
+    if forbidden and contains_source_any(source, SUPERNATURAL_GUARD_TERMS):
+        return ["supernatural_entity"], ["supernatural_or_entity_context"]
+
+    peer_classmate = is_peer_classmate_source(source)
+    if peer_classmate:
+        tags.append("peer_classmate")
+
+    sibling_tag = sibling_reply_tag_from_source(source)
+    if sibling_tag:
+        tags.append(sibling_tag)
+
+    if is_teacher_peer_source(source):
+        tags.append("teacher_peer")
+    elif not peer_classmate and not sibling_tag and is_teacher_to_student_source(source):
+        tags.append("teacher_student")
+
+    source_has_teacher = contains_source_any(source, TEACHER_SOURCE_TERMS)
+    source_has_school_context = contains_source_any(source, SCHOOL_CONTEXT_SOURCE_TERMS) and "大学同学" not in source
+    if source_has_teacher and "我" in source and contains_word(text, "ta") and "teacher_student" not in tags:
+        tags.append("student_teacher")
+    elif (
+        source_has_school_context
+        and any("modern_you" in flag for flag in forbidden)
+        and "teacher_student" not in tags
+        and "teacher_peer" not in tags
+        and "peer_classmate" not in tags
+        and not sibling_tag
+    ):
+        tags.append("teacher_student")
+
+    if is_mother_to_child_source(source):
+        tags.append("family_mother_child")
+    if is_child_to_mother_source(source):
+        tags.append("family_child_to_mother")
+    if is_formal_debt_source(source):
+        tags.append("formal_debt_call")
+    if is_brother_to_sister_source(source, text):
+        tags.append("family_brother_to_sister")
+    if is_school_application_source(source):
+        tags.append("school_application_self")
+    if is_exclusive_institution_we_source(source):
+        tags.append("institution_we_exclusive")
+    if is_institution_applicant_source(source):
+        tags.append("institution_applicant")
+    if is_applicant_self_source(source) and contains_source_any(source, APPLICANT_CONTEXT_SOURCE_TERMS):
+        tags.append("applicant_self")
+    return tags, guard_reasons
+
+
+def replace_pronoun_matches(
+    text: str,
+    matches: list[re.Match[str]],
+    replacement: str,
+    applied: Counter[str],
+    rule_name: str,
+) -> str:
+    if not matches:
+        return text
+    out = text
+    for match in reversed(matches):
+        out = out[: match.start()] + cap_like(match.group(0), replacement) + out[match.end() :]
+    applied[rule_name] += len(matches)
+    return out
+
+
+def add_ta_replacement(text: str, replacement: str, applied: Counter[str], rule_name: str) -> str:
+    return replace_pronoun_matches(text, standalone_ta_matches(text), replacement, applied, rule_name)
+
+
+def add_toi_replacement(text: str, replacement: str, applied: Counter[str], rule_name: str) -> str:
+    matches = standalone_pronoun_matches(text, "tôi", ALLOWED_PREVIOUS_TOI)
+    return replace_pronoun_matches(text, matches, replacement, applied, rule_name)
+
+
+def apply_many_words(text: str, sources: tuple[str, ...], replacement: str, applied: Counter[str], rule_name: str) -> str:
+    for source in sources:
+        text = apply_replacement(text, source, replacement, applied, rule_name)
+    return text
+
+
+def apply_third_person_flags(text: str, flags_before: list[str], applied: Counter[str]) -> str:
+    if any("mother_third_person_modern" in flag for flag in flags_before):
+        return apply_replacement(text, "nàng", "bà", applied, "mother_third_person")
+    if any("female_third_person_modern" in flag for flag in flags_before):
+        return apply_replacement(text, "nàng", "cô ấy", applied, "female_third_person")
+    return text
+
+
+def harmonize_stability_row(
+    *,
+    source: str,
+    input_vi: str,
+    flags_before: list[str],
+    policy_tags: list[str],
+    guard_reasons: list[str],
+) -> tuple[str, dict[str, int]]:
+    text = input_vi
+    applied: Counter[str] = Counter()
+    tags = set(policy_tags)
+
+    if "route:xianxia_copy_guard" in guard_reasons or "route:unknown_copy_guard" in guard_reasons:
+        return text, {}
+
+    guarded = bool(guard_reasons)
+    if not guarded:
+        if "mother_narration_context" in tags and any("female_third_person_modern" in flag for flag in flags_before):
+            text = apply_replacement(text, "nàng", "bà", applied, "mother_third_person")
+        else:
+            text = apply_third_person_flags(text, flags_before, applied)
+
+    if "school_application_self" in tags:
+        text = apply_replacement(text, "trường chúng tôi", "trường tôi", applied, "school_application_self_school")
+        text = apply_replacement(text, "trường ta", "trường tôi", applied, "school_application_self_school")
+        text = add_ta_replacement(text, "tôi", applied, "school_application_self")
+
+    if "institution_we_exclusive" in tags:
+        text = apply_replacement(text, "trường chúng ta", "trường chúng tôi", applied, "institution_school_we")
+        text = apply_replacement(text, "trường ta", "trường chúng tôi", applied, "institution_school_we")
+        text = apply_replacement(text, "chúng ta", "chúng tôi", applied, "institution_we_exclusive")
+        if not tags & {"teacher_student", "family_mother_child", "family_sister_to_brother_context", "family_child_to_mother"}:
+            text = add_ta_replacement(text, "tôi", applied, "institution_self_as_toi")
+
+    if "formal_debt_call" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các anh", applied, "formal_debt_you")
+        text = apply_many_words(text, ("ngươi", "cậu"), "ngài", applied, "formal_debt_you")
+        text = apply_replacement(text, "chúng ta", "chúng tôi", applied, "formal_debt_we")
+        text = add_ta_replacement(text, "tôi", applied, "formal_debt_self")
+        text = add_toi_replacement(text, "tôi", applied, "formal_debt_self")
+        return text, dict(applied)
+
+    if guarded:
+        return text, dict(applied)
+
+    if "sibling_older_brother_to_younger" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các em", applied, "older_brother_you_as_em")
+        text = apply_many_words(text, ("ngươi", "cậu"), "em", applied, "older_brother_you_as_em")
+        text = add_ta_replacement(text, "anh", applied, "older_brother_self_as_anh")
+        text = add_toi_replacement(text, "anh", applied, "older_brother_self_as_anh")
+        return text, dict(applied)
+
+    if "sibling_younger_to_older_brother" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các anh", applied, "younger_sibling_you_as_anh")
+        text = apply_many_words(text, ("ngươi", "cậu"), "anh", applied, "younger_sibling_you_as_anh")
+        text = add_ta_replacement(text, "em", applied, "younger_sibling_self_as_em")
+        text = add_toi_replacement(text, "em", applied, "younger_sibling_self_as_em")
+        return text, dict(applied)
+
+    if "peer_classmate" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các cậu", applied, "peer_you_as_cau")
+        text = apply_many_words(text, ("ngươi", "cậu"), "cậu", applied, "peer_you_as_cau")
+        text = add_ta_replacement(text, "tớ", applied, "peer_self_as_to")
+        if "我欠二十多万的人" in source:
+            text = apply_replacement(text, "người ta nợ hơn hai mươi vạn", "người như tớ nợ hơn hai mươi vạn", applied, "peer_debt_self_phrase")
+            text = apply_replacement(text, "tớ nợ hơn hai mươi vạn người", "người như tớ nợ hơn hai mươi vạn", applied, "peer_debt_self_phrase")
+        return text, dict(applied)
+
+    if "family_mother_child" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các con", applied, "mother_you_as_con")
+        text = apply_many_words(text, ("ngươi", "cậu"), "con", applied, "mother_you_as_con")
+        text = add_ta_replacement(text, "mẹ", applied, "mother_self_as_me")
+        text = add_toi_replacement(text, "mẹ", applied, "mother_self_as_me")
+        return text, dict(applied)
+
+    if "family_child_to_mother" in tags:
+        text = apply_many_words(text, ("Mẹ, em yên tâm", "Mẹ, ngươi yên tâm", "Mẹ, cậu yên tâm"), "Mẹ, mẹ yên tâm", applied, "child_you_as_mother")
+        text = apply_many_words(text, ("ngươi", "cậu", "ngài"), "mẹ", applied, "child_you_as_mother")
+        text = apply_many_words(text, ("chúng ta", "chúng tôi"), "chúng con", applied, "child_we_as_chung_con")
+        if "你" not in source or "Mẹ, mẹ yên tâm" in text:
+            text = apply_replacement(text, "em", "con", applied, "child_self_as_con")
+        text = add_ta_replacement(text, "con", applied, "child_self_as_con")
+        text = add_toi_replacement(text, "con", applied, "child_self_as_con")
+        return text, dict(applied)
+
+    if "applicant_self" in tags:
+        text = add_ta_replacement(text, "em", applied, "applicant_self_as_em")
+        text = add_toi_replacement(text, "em", applied, "applicant_self_as_em")
+
+    if "institution_applicant" in tags and "teacher_student" not in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các em", applied, "institution_applicant_you")
+        text = apply_many_words(text, ("ngươi", "cậu"), "em", applied, "institution_applicant_you")
+        return text, dict(applied)
+
+    if "applicant_self" in tags and "teacher_student" not in tags:
+        return text, dict(applied)
+
+    if "family_brother_to_sister" in tags:
+        text = add_ta_replacement(text, "em", applied, "brother_self_as_em")
+        text = add_toi_replacement(text, "em", applied, "brother_self_as_em")
+        return text, dict(applied)
+
+    if "family_sister_to_brother_context" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các em", applied, "sister_you_as_em")
+        text = apply_many_words(text, ("ngươi", "cậu"), "em", applied, "sister_you_as_em")
+        text = add_ta_replacement(text, "chị", applied, "sister_self_as_chi")
+        text = add_toi_replacement(text, "chị", applied, "sister_self_as_chi")
+        return text, dict(applied)
+
+    if "teacher_student" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các em", applied, "teacher_you_as_student")
+        text = apply_many_words(text, ("ngươi", "cậu"), "em", applied, "teacher_you_as_student")
+        text = add_ta_replacement(text, "thầy", applied, "teacher_self_as_thay")
+        text = add_toi_replacement(text, "thầy", applied, "teacher_self_as_thay")
+        text = apply_replacement(text, "lão sư", "giáo viên", applied, "teacher_context_lao_su")
+        return text, dict(applied)
+
+    if "student_teacher" in tags:
+        text = add_ta_replacement(text, "em", applied, "student_self_as_em")
+        text = add_toi_replacement(text, "em", applied, "student_self_as_em")
+        text = apply_many_words(text, ("ngươi", "cậu"), "thầy", applied, "student_you_as_teacher")
+        return text, dict(applied)
+
+    if "generic_modern_dialogue" in tags:
+        text = apply_many_words(text, ("các ngươi", "các cậu"), "các cậu", applied, "generic_modern_you")
+        text = apply_many_words(text, ("ngươi", "cậu"), "cậu", applied, "generic_modern_you")
+        text = add_ta_replacement(text, "tôi", applied, "generic_modern_self")
+        return text, dict(applied)
+
+    return text, dict(applied)
+
+
+def apply_runtime_row(
+    chapter: str,
+    system: str,
+    row: dict[str, Any],
+    route: str,
+    route_reason: str,
+    context_guard_reasons: list[str] | None = None,
+    context_policy_tags: list[str] | None = None,
+) -> dict[str, Any]:
+    source = str(row["source_zh"])
+    input_vi = str(row["input_vi"])
+    flags_before = detect_flags(source, input_vi)
+    policy_tags, guard_reasons = infer_policy_tags(source, input_vi, flags_before)
+    if context_policy_tags:
+        policy_tags = [*policy_tags, *context_policy_tags]
+    teacher_window_active = any(tag in TEACHER_WINDOW_TAGS for tag in policy_tags)
+    policy_tags = [tag for tag in policy_tags if tag not in TEACHER_WINDOW_TAGS]
+    if is_inner_monologue_source(source):
+        policy_tags = [tag for tag in policy_tags if tag != "peer_classmate"]
+    sibling_policy_tags = {"sibling_older_brother_to_younger", "sibling_younger_to_older_brother"}
+    if set(policy_tags) & sibling_policy_tags:
+        policy_tags = [
+            tag for tag in policy_tags
+            if tag not in {"teacher_student", "student_teacher", "teacher_peer", "peer_classmate"}
+        ]
+    if "teacher_student" in policy_tags and (
+        "peer_classmate" not in policy_tags or teacher_window_active or is_teacher_speaker_source(source)
+    ):
+        policy_tags = [tag for tag in policy_tags if tag not in {"peer_classmate", "student_teacher"}]
+    elif "peer_classmate" in policy_tags:
+        policy_tags = [tag for tag in policy_tags if tag not in {"teacher_student", "student_teacher"}]
+    if "family_sister_to_brother_context" in policy_tags and not is_direct_mother_speaker(source):
+        policy_tags = [tag for tag in policy_tags if tag != "family_mother_child"]
+    policy_tags = list(dict.fromkeys(policy_tags))
+
+    if context_guard_reasons and forbidden_flags(flags_before):
+        guard_reasons = [*guard_reasons, *context_guard_reasons]
+    if route.endswith("_copy_guard") and flags_before:
+        guard_reasons = [*guard_reasons, f"route:{route}"]
+    if (
+        route == "modern_school"
+        and not policy_tags
+        and not guard_reasons
+        and forbidden_flags(flags_before)
+        and is_generic_modern_dialogue_source(source)
+    ):
+        policy_tags.append("generic_modern_dialogue")
+
+    if route.endswith("_copy_guard"):
+        prediction = input_vi
+        applied: dict[str, int] = {}
+    else:
+        prediction, applied = harmonize_stability_row(
+            source=source,
+            input_vi=input_vi,
+            flags_before=flags_before,
+            policy_tags=policy_tags,
+            guard_reasons=guard_reasons,
+        )
+
+    flags_after = detect_flags(source, prediction)
+    actionable_before = actionable_flags(flags_before)
+    actionable_after = actionable_flags(flags_after)
+    changed = prediction != input_vi
+    actionable_policy_tags = not route.endswith("_copy_guard") and has_actionable_policy_tags(policy_tags)
+    return {
+        "id": f"{chapter}:{system}:{int(row['row_index']):04d}",
+        "chapter": chapter,
+        "system": system,
+        "route": route,
+        "route_reason": route_reason,
+        "row_index": row["row_index"],
+        "source_zh": source,
+        "input_vi": input_vi,
+        "prediction_vi": prediction,
+        "changed": changed,
+        "flags_before": flags_before,
+        "flags_after": flags_after,
+        "actionable_flags_before": actionable_before,
+        "actionable_flags_after": actionable_after,
+        "policy_tags": policy_tags,
+        "guard_reasons": guard_reasons,
+        "applied_rules": applied,
+        "needs_review": bool(changed or actionable_before or actionable_after or guard_reasons or actionable_policy_tags),
+    }
+
+
+def apply_runtime_spec_rows(
+    chapter: str,
+    system: str,
+    rows: list[dict[str, Any]],
+    route: str,
+    route_reason: str,
+) -> tuple[list[dict[str, Any]], int]:
+    predictions: list[dict[str, Any]] = []
+    missing_inputs = 0
+    context_guard_remaining = 0
+    sister_to_brother_remaining = 0
+    child_to_mother_remaining = 0
+    mother_narration_remaining = 0
+    peer_classmate_remaining = 0
+    teacher_to_student_remaining = 0
+    inner_monologue_remaining = 0
+    institution_applicant_remaining = 0
+    sibling_dialogue_remaining = 0
+    sibling_next_policy_tag: str | None = None
+    pre_context_policy_tags: list[list[str]] = [[] for _ in rows]
+
+    for row_pos, row in enumerate(rows):
+        source_text = str(row["source_zh"])
+        if route != "modern_school" or not contains_source_any(source_text, MOTHER_MESSAGE_CONTEXT_TERMS):
+            continue
+        for previous_pos in range(max(0, row_pos - 4), row_pos):
+            previous_source = str(rows[previous_pos]["source_zh"])
+            if is_likely_mother_message_source(previous_source):
+                pre_context_policy_tags[previous_pos].append("family_mother_child")
+
+    for row_pos, row in enumerate(rows):
+        source_text = str(row["source_zh"])
+        if not str(row["input_vi"]).strip():
+            missing_inputs += 1
+        context_guard_reasons: list[str] = []
+        context_policy_tags: list[str] = [*pre_context_policy_tags[row_pos]]
+        explicit_sibling_tag = sibling_reply_tag_from_source(source_text)
+        if route == "modern_school" and explicit_sibling_tag:
+            context_policy_tags.append(explicit_sibling_tag)
+        elif (
+            route == "modern_school"
+            and sibling_dialogue_remaining > 0
+            and sibling_next_policy_tag
+            and has_speech_marker(source_text)
+            and ("你" in source_text or "我" in source_text)
+        ):
+            context_policy_tags.append(sibling_reply_tag_from_source(source_text, sibling_next_policy_tag) or sibling_next_policy_tag)
+            sibling_dialogue_remaining -= 1
+        if route == "modern_school" and (
+            is_child_to_mother_source(source_text)
+            or is_teacher_speaker_source(source_text)
+            or is_clear_non_teacher_speaker_source(source_text)
+        ):
+            inner_monologue_remaining = 0
+        if route == "modern_school" and institution_applicant_remaining > 0:
+            if "你" in source_text or "你们" in source_text:
+                context_policy_tags.append("institution_applicant")
+            if has_speech_marker(source_text) and is_applicant_self_source(source_text):
+                context_policy_tags.append("applicant_self")
+            institution_applicant_remaining -= 1
+        if route == "modern_school" and context_guard_remaining > 0:
+            context_guard_reasons.append("context:supernatural_entity_window")
+            context_guard_remaining -= 1
+        if route == "modern_school" and inner_monologue_remaining > 0:
+            if has_speech_marker(source_text):
+                context_guard_reasons.append("context:inner_monologue_window")
+            inner_monologue_remaining -= 1
+        if route == "modern_school" and sister_to_brother_remaining > 0:
+            if "你" in source_text or "我" in source_text:
+                context_policy_tags.append("family_sister_to_brother_context")
+            sister_to_brother_remaining -= 1
+        if route == "modern_school" and child_to_mother_remaining > 0:
+            if "你" in source_text or "我" in source_text:
+                context_policy_tags.append("family_child_to_mother")
+            child_to_mother_remaining -= 1
+        if route == "modern_school" and mother_narration_remaining > 0:
+            if "她" in source_text:
+                context_policy_tags.append("mother_narration_context")
+            mother_narration_remaining -= 1
+        if route == "modern_school" and peer_classmate_remaining > 0:
+            if ("你" in source_text or "我" in source_text) and has_speech_marker(source_text):
+                context_policy_tags.append("peer_classmate")
+            peer_classmate_remaining -= 1
+        if route == "modern_school" and teacher_to_student_remaining > 0:
+            if is_clear_non_teacher_speaker_source(source_text):
+                teacher_to_student_remaining = 0
+            else:
+                if has_speech_marker(source_text):
+                    if "你" in source_text:
+                        context_policy_tags.extend(["teacher_student", "teacher_student_window"])
+                    elif "我" in source_text:
+                        context_policy_tags.extend(["student_teacher", "student_teacher_window"])
+                teacher_to_student_remaining -= 1
+
+        predictions.append(
+            apply_runtime_row(
+                chapter,
+                system,
+                row,
+                route,
+                route_reason,
+                context_guard_reasons,
+                context_policy_tags,
+            )
+        )
+
+        if route == "modern_school" and contains_source_any(source_text, SUPERNATURAL_CONTEXT_TERMS):
+            context_guard_remaining = max(context_guard_remaining, 2)
+        if route == "modern_school" and is_inner_monologue_source(source_text):
+            inner_monologue_remaining = max(inner_monologue_remaining, 2)
+        if route == "modern_school" and "姐" in source_text:
+            sister_to_brother_remaining = max(sister_to_brother_remaining, 4)
+        if route == "modern_school" and is_child_to_mother_source(source_text):
+            child_to_mother_remaining = max(child_to_mother_remaining, 4)
+        if route == "modern_school" and contains_source_any(source_text, MOTHER_SOURCE_TERMS):
+            mother_narration_remaining = max(mother_narration_remaining, 18)
+        if route == "modern_school" and is_teacher_speaker_source(source_text):
+            teacher_to_student_remaining = max(teacher_to_student_remaining, 12)
+        if route == "modern_school" and is_peer_classmate_source(source_text) and has_speech_marker(source_text):
+            peer_classmate_remaining = max(peer_classmate_remaining, 10)
+        if route == "modern_school" and is_institution_applicant_context_source(source_text):
+            institution_applicant_remaining = max(institution_applicant_remaining, 12)
+        if route == "modern_school":
+            row_policy_tags = set(predictions[-1].get("policy_tags") or [])
+            if "sibling_older_brother_to_younger" in row_policy_tags:
+                sibling_next_policy_tag = "sibling_younger_to_older_brother"
+                sibling_dialogue_remaining = max(sibling_dialogue_remaining, 4)
+            elif "sibling_younger_to_older_brother" in row_policy_tags:
+                sibling_next_policy_tag = "sibling_older_brother_to_younger"
+                sibling_dialogue_remaining = max(sibling_dialogue_remaining, 4)
+    return predictions, missing_inputs
+
+
+def classify_route_for_rows(rows: list[tuple[int, str, str]], forced_route: str = "auto") -> tuple[str, str]:
+    if forced_route != "auto":
+        if forced_route not in ROUTES:
+            raise ValueError(f"unknown route: {forced_route}")
+        return forced_route, f"forced:{forced_route}"
+    decision = classify_genre(rows)
+    return v9_route_for_decision(decision), f"auto:{decision.reason}"
+
+
+def summarize_predictions(predictions: list[dict[str, Any]], missing_input_rows: int) -> dict[str, Any]:
+    route_counts = Counter(str(row.get("route") or "") for row in predictions)
+    applied = Counter()
+    policy_tags = Counter()
+    guard_reasons = Counter()
+    for row in predictions:
+        applied.update(row.get("applied_rules") or {})
+        policy_tags.update(row.get("policy_tags") or [])
+        guard_reasons.update(row.get("guard_reasons") or [])
+    return {
+        "candidate_id": "pronoun-harmonizer-runtime-v9",
+        "rows": len(predictions),
+        "missing_input_rows": missing_input_rows,
+        "changed_rows": sum(1 for row in predictions if row.get("changed")),
+        "needs_review_rows": sum(1 for row in predictions if row.get("needs_review")),
+        "guarded_rows": sum(1 for row in predictions if row.get("guard_reasons")),
+        "actionable_after_rows": sum(1 for row in predictions if row.get("actionable_flags_after")),
+        "route_counts": dict(route_counts),
+        "applied_rule_counts": dict(applied),
+        "policy_tag_counts": dict(policy_tags),
+        "guard_counts": dict(guard_reasons),
+    }
+
+
+def harmonize_pronouns_v9(
+    rows: list[tuple[int, str, str]],
+    *,
+    route: str = "auto",
+) -> tuple[list[tuple[int, str, str]], dict[str, Any]]:
+    """Apply V9 to UI translation rows.
+
+    Input/output row shape is `(index, source_zh, translation_vi)`.
+    """
+    if not rows:
+        return rows, summarize_predictions([], 0)
+    selected_route, route_reason = classify_route_for_rows(rows, route)
+    runtime_rows = [
+        {"id": f"qt2_{index:04d}", "row_index": index, "source_zh": source, "input_vi": vi}
+        for index, source, vi in rows
+    ]
+    predictions, missing = apply_runtime_spec_rows(
+        "qt2",
+        "ui",
+        runtime_rows,
+        selected_route,
+        route_reason,
+    )
+    out_rows = [
+        (index, source, str(prediction.get("prediction_vi") or vi))
+        for (index, source, vi), prediction in zip(rows, predictions)
+    ]
+    report = summarize_predictions(predictions, missing)
+    report.update({"enabled": True, "route": selected_route, "route_reason": route_reason})
+    return out_rows, report

src/text_preprocess.py

@@ -0,0 +1,38 @@
+"""Chinese text normalization before translation."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+NORMALIZE_AUTO = "auto"
+NORMALIZE_T2S = "t2s"
+NORMALIZE_NONE = "none"
+NORMALIZE_MODES = {NORMALIZE_AUTO, NORMALIZE_T2S, NORMALIZE_NONE}
+
+
+@lru_cache(maxsize=1)
+def _t2s_converter():
+    from opencc import OpenCC
+
+    return OpenCC("t2s")
+
+
+def normalize_mode(mode: str | None) -> str:
+    mode = (mode or NORMALIZE_AUTO).strip().lower()
+    return mode if mode in NORMALIZE_MODES else NORMALIZE_AUTO
+
+
+def normalize_chinese_text(text: str, mode: str | None = NORMALIZE_AUTO) -> str:
+    mode = normalize_mode(mode)
+    if mode == NORMALIZE_NONE or not text:
+        return text
+    return _t2s_converter().convert(text)
+
+
+def normalization_message(original: str, normalized: str, mode: str | None) -> str:
+    mode = normalize_mode(mode)
+    if mode == NORMALIZE_NONE:
+        return "Giữ nguyên chữ Hán gốc."
+    if original == normalized:
+        return "Đã kiểm tra chữ Hán: không cần chuyển phồn thể."
+    return "Đã chuyển phồn thể sang giản thể trước khi dịch."

src/token_chunker.py

@@ -0,0 +1,133 @@
+"""Token-aware chunking for Marian models (ported from HachimiMT HF Space)."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from transformers import PreTrainedTokenizerBase
+
+SENTENCE_RE = re.compile(r"[^。！？!?；;]+[。！？!?；;]*")
+
+
+def source_token_ids(
+    tokenizer: PreTrainedTokenizerBase,
+    text: str,
+    *,
+    max_length: int,
+    truncation: bool,
+) -> list[int]:
+    token_ids = tokenizer(
+        text,
+        truncation=truncation,
+        max_length=max_length,
+    )["input_ids"]
+    if tokenizer.pad_token_id is not None:
+        token_ids = [tid for tid in token_ids if tid != tokenizer.pad_token_id]
+    return token_ids
+
+
+def source_token_count(
+    tokenizer: PreTrainedTokenizerBase,
+    text: str,
+    *,
+    max_length: int,
+) -> int:
+    return len(source_token_ids(tokenizer, text, max_length=max_length, truncation=False))
+
+
+def char_chunks(
+    tokenizer: PreTrainedTokenizerBase,
+    text: str,
+    *,
+    max_tokens: int,
+) -> list[str]:
+    chunks: list[str] = []
+    remaining = text
+    while remaining:
+        if source_token_count(tokenizer, remaining, max_length=max_tokens) <= max_tokens:
+            chunks.append(remaining)
+            break
+
+        low, high = 1, len(remaining)
+        best = 1
+        while low <= high:
+            middle = (low + high) // 2
+            candidate = remaining[:middle]
+            if source_token_count(tokenizer, candidate, max_length=max_tokens) <= max_tokens:
+                best = middle
+                low = middle + 1
+            else:
+                high = middle - 1
+
+        chunks.append(remaining[:best])
+        remaining = remaining[best:]
+    return chunks
+
+
+def sentence_chunks(
+    tokenizer: PreTrainedTokenizerBase,
+    line: str,
+    *,
+    max_tokens: int,
+) -> list[str]:
+    if source_token_count(tokenizer, line, max_length=max_tokens) <= max_tokens:
+        return [line]
+
+    pieces = [match.group(0) for match in SENTENCE_RE.finditer(line)]
+    if not pieces:
+        return char_chunks(tokenizer, line, max_tokens=max_tokens)
+
+    chunks: list[str] = []
+    current = ""
+    for piece in pieces:
+        if source_token_count(tokenizer, piece, max_length=max_tokens) > max_tokens:
+            if current:
+                chunks.append(current)
+                current = ""
+            chunks.extend(char_chunks(tokenizer, piece, max_tokens=max_tokens))
+            continue
+
+        candidate = current + piece
+        if current and source_token_count(tokenizer, candidate, max_length=max_tokens) > max_tokens:
+            chunks.append(current)
+            current = piece
+        else:
+            current = candidate
+
+    if current:
+        chunks.append(current)
+    return chunks
+
+
+def split_for_translation(
+    tokenizer: PreTrainedTokenizerBase,
+    text: str,
+    *,
+    max_tokens: int,
+    chunk_mode: str = "sentence",
+) -> list[str]:
+    """Split *text* into chunks that fit within *max_tokens*."""
+    text = text.strip()
+    if not text:
+        return []
+
+    if chunk_mode == "paragraph":
+        paragraphs = [p.strip() for p in re.split(r"\n\s*\n+", text) if p.strip()]
+        chunks: list[str] = []
+        for paragraph in paragraphs:
+            for line in paragraph.splitlines():
+                line = line.strip()
+                if not line:
+                    continue
+                chunks.extend(sentence_chunks(tokenizer, line, max_tokens=max_tokens))
+        return chunks
+
+    chunks = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        chunks.extend(sentence_chunks(tokenizer, line, max_tokens=max_tokens))
+    return chunks

src/translator.py

@@ -0,0 +1,833 @@
+"""HachimiMT Marian translation backend."""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+from typing import Callable, Iterator
+
+import ctranslate2
+import sentencepiece as spm
+from huggingface_hub import snapshot_download
+
+from chunker import split_chunks
+from hardware import HardwareProfile, detect_hardware_profile
+from token_chunker import source_token_ids, split_for_translation
+
+ROOT = Path(__file__).resolve().parent.parent
+MODELS_DIR = Path(os.environ.get("HACHIMIMT_MODELS_DIR", ROOT / "models"))
+SPECIAL_ID_TO_TOKEN = {0: "<pad>", 1: "<s>", 2: "</s>", 3: "<unk>"}
+SPECIAL_TOKEN_TO_ID = {token: token_id for token_id, token in SPECIAL_ID_TO_TOKEN.items()}
+EOS_TOKEN_ID = 2
+
+
+class Backend(str, Enum):
+    CT2 = "ct2"
+    TRANSFORMERS = "transformers"
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    label: str
+    model_id: str
+    use_marian_class: bool
+    generate_kwargs: dict
+    ct2_max_input_tokens: int
+    ct2_max_output_tokens: int
+    ct2_max_batch_size: int = 8
+    default_beam: int = 2
+    # Dung lượng xấp xỉ bản CT2 INT8 (MB) — chỉ để hiển thị badge "sẽ tải ~XMB".
+    # Khai khi thêm model mới; để None thì badge chỉ hiện "chưa tải" không kèm số.
+    ct2_size_mb: int | None = None
+    # Tên thư mục con chứa bản CT2 trên repo HF. Mặc định "ct2-int8_float32";
+    # một số repo dùng tên khác (vd "ct2-int8"), khai lại ở đây cho từng model.
+    ct2_subdir: str = "ct2-int8_float32"
+
+
+MODELS: dict[str, ModelConfig] = {
+    "HachimiMT-60": ModelConfig(
+        label="HachimiMT-60",
+        model_id="ngocdang83/HachimiMT-60-zh-vi",
+        use_marian_class=True,
+        generate_kwargs={
+            "max_new_tokens": 300,
+            "no_repeat_ngram_size": 2,
+            "repetition_penalty": 1.2,
+        },
+        ct2_max_input_tokens=256,
+        ct2_max_output_tokens=300,
+        default_beam=2,
+        ct2_size_mb=57,
+    ),
+    "HachimiMT-30": ModelConfig(
+        label="HachimiMT-30",
+        model_id="ngocdang83/HachimiMT-30-zh-vi",
+        use_marian_class=False,
+        generate_kwargs={
+            "max_length": 512,
+        },
+        ct2_max_input_tokens=512,
+        ct2_max_output_tokens=512,
+        default_beam=1,
+        ct2_size_mb=35,
+    ),
+    "MoxhiMT-60": ModelConfig(
+        label="MoxhiMT-60",
+        model_id="DanVP/MoxhiMT-60",
+        use_marian_class=True,
+        generate_kwargs={
+            "max_new_tokens": 300,
+            "no_repeat_ngram_size": 2,
+            "repetition_penalty": 1.2,
+        },
+        ct2_max_input_tokens=256,
+        ct2_max_output_tokens=300,
+        default_beam=2,
+        ct2_size_mb=58,
+        ct2_subdir="ct2-int8",  # repo này dùng tên thư mục CT2 khác
+    ),
+    "MoxhiMT-30": ModelConfig(
+        label="MoxhiMT-30",
+        model_id="DanVP/MoxhiMT-30",
+        use_marian_class=True,
+        generate_kwargs={
+            "max_new_tokens": 300,
+            "no_repeat_ngram_size": 2,
+            "repetition_penalty": 1.2,
+        },
+        ct2_max_input_tokens=512,
+        ct2_max_output_tokens=512,
+        default_beam=1,
+        ct2_size_mb=38,
+    ),
+}
+
+# Model tải sẵn khi chạy setup (dùng được ngay); các model khác lazy-download.
+DEFAULT_MODEL_KEY = "HachimiMT-60"
+
+# Thư mục CT2 mặc định; model nào khác thì khai ModelConfig.ct2_subdir.
+DEFAULT_CT2_SUBDIR = "ct2-int8_float32"
+
+
+def _ct2_download_patterns(config: ModelConfig) -> list[str]:
+    return [
+        "config.json",
+        "source.spm",
+        "target.spm",
+        "vocab.json",
+        "tokenizer_config.json",
+        f"{config.ct2_subdir}/*",
+    ]
+
+
+SourceTokenJobs = list[Future[list[list[str]]]]
+
+
+def _env_int(name: str, default: int, *, min_value: int = 1, max_value: int = 1024) -> int:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        return max(min_value, min(max_value, int(raw)))
+    except ValueError:
+        return default
+
+
+def _batched(items: list[str], size: int) -> Iterator[list[str]]:
+    for start in range(0, len(items), size):
+        yield items[start : start + size]
+
+
+def default_ct2_compute_type(device: str) -> str:
+    env_compute_type = os.environ.get("HACHIMIMT_COMPUTE_TYPE", "").strip()
+    if env_compute_type:
+        return env_compute_type
+    return "int8_float16" if device == "cuda" else "int8_float32"
+
+
+@lru_cache(maxsize=1)
+def _optional_torch():
+    try:
+        import torch
+    except Exception:
+        return None
+    return torch
+
+
+def _require_torch():
+    torch = _optional_torch()
+    if torch is None:
+        raise RuntimeError(
+            "Backend PyTorch cần cài torch. Engine mặc định CTranslate2 không cần torch. "
+            "Nếu muốn dùng PyTorch, cài torch rồi cài: pip install -r requirements-pytorch.txt"
+        )
+    return torch
+
+
+def _torch_cuda_available() -> bool:
+    torch = _optional_torch()
+    if torch is None:
+        return False
+    try:
+        return bool(torch.cuda.is_available())
+    except Exception:
+        return False
+
+
+def _torch_cuda_device_name() -> str | None:
+    torch = _optional_torch()
+    if torch is None:
+        return None
+    try:
+        if torch.cuda.is_available():
+            return str(torch.cuda.get_device_name(0))
+    except Exception:
+        return None
+    return None
+
+
+def _torch_empty_cuda_cache() -> None:
+    torch = _optional_torch()
+    if torch is None:
+        return
+    try:
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+    except Exception:
+        return
+
+
+class CT2SentencePieceTokenizer:
+    """Minimal Marian SentencePiece tokenizer for CTranslate2 inference."""
+
+    pad_token_id = 0
+
+    def __init__(self, model_path: Path) -> None:
+        self._source_sp = spm.SentencePieceProcessor(model_file=str(model_path / "source.spm"))
+        self._target_sp = spm.SentencePieceProcessor(model_file=str(model_path / "target.spm"))
+
+    def _encode_one(
+        self,
+        text: str,
+        *,
+        truncation: bool = False,
+        max_length: int | None = None,
+    ) -> list[int]:
+        token_ids = list(self._source_sp.encode(text, out_type=int))
+        token_ids.append(EOS_TOKEN_ID)
+        if truncation and max_length is not None and len(token_ids) > max_length:
+            token_ids = token_ids[:max_length]
+            if token_ids:
+                token_ids[-1] = EOS_TOKEN_ID
+        return token_ids
+
+    def __call__(
+        self,
+        text_or_texts: str | list[str],
+        *,
+        truncation: bool = False,
+        max_length: int | None = None,
+        padding: bool = False,
+    ) -> dict[str, list[int] | list[list[int]]]:
+        del padding
+        if isinstance(text_or_texts, str):
+            return {
+                "input_ids": self._encode_one(
+                    text_or_texts,
+                    truncation=truncation,
+                    max_length=max_length,
+                )
+            }
+        return {
+            "input_ids": [
+                self._encode_one(text, truncation=truncation, max_length=max_length)
+                for text in text_or_texts
+            ]
+        }
+
+    def convert_ids_to_tokens(self, token_ids: list[int]) -> list[str]:
+        tokens: list[str] = []
+        for token_id in token_ids:
+            if token_id in SPECIAL_ID_TO_TOKEN:
+                tokens.append(SPECIAL_ID_TO_TOKEN[token_id])
+            else:
+                tokens.append(self._source_sp.id_to_piece(int(token_id)))
+        return tokens
+
+    def convert_tokens_to_ids(self, tokens: list[str]) -> list[int]:
+        token_ids: list[int] = []
+        for token in tokens:
+            if token in SPECIAL_TOKEN_TO_ID:
+                token_ids.append(SPECIAL_TOKEN_TO_ID[token])
+            else:
+                token_ids.append(int(self._target_sp.piece_to_id(token)))
+        return token_ids
+
+    def decode(self, token_ids: list[int], *, skip_special_tokens: bool = True) -> str:
+        return self.batch_decode([token_ids], skip_special_tokens=skip_special_tokens)[0]
+
+    def batch_decode(
+        self,
+        token_ids_batch: list[list[int]],
+        *,
+        skip_special_tokens: bool = True,
+    ) -> list[str]:
+        decoded: list[str] = []
+        for token_ids in token_ids_batch:
+            if skip_special_tokens:
+                token_ids = [
+                    token_id
+                    for token_id in token_ids
+                    if token_id not in SPECIAL_ID_TO_TOKEN
+                ]
+            pieces = [self._target_sp.id_to_piece(int(token_id)) for token_id in token_ids]
+            decoded.append(self._target_sp.decode(pieces))
+        return decoded
+
+
+def model_local_dir(config: ModelConfig) -> Path:
+    return MODELS_DIR / config.model_id.split("/")[-1]
+
+
+def _ct2_ready(path: Path, ct2_subdir: str = DEFAULT_CT2_SUBDIR) -> bool:
+    ct2_path = path / ct2_subdir
+    return ct2_path.is_dir() and any(ct2_path.iterdir())
+
+
+def _pytorch_ready(path: Path) -> bool:
+    return any(path.glob("*.safetensors")) or any(path.glob("pytorch_model*.bin"))
+
+
+def _tokenizer_ready(path: Path) -> bool:
+    return (path / "source.spm").exists() or (path / "tokenizer_config.json").exists()
+
+
+def is_model_downloaded(model_key: str, backend: Backend | str = Backend.CT2) -> bool:
+    """Model (theo backend) đã có sẵn trong MODELS_DIR chưa — để UI hiện badge.
+
+    Dùng đúng điều kiện mà ensure_model_files() kiểm tra, nên kết quả khớp với
+    việc bấm Dịch có phải tải hay không.
+    """
+    if isinstance(backend, str):
+        backend = Backend(backend)
+    if model_key not in MODELS:
+        return False
+    config = MODELS[model_key]
+    path = model_local_dir(config)
+    if backend == Backend.CT2:
+        weights_ready = _ct2_ready(path, config.ct2_subdir)
+    else:
+        weights_ready = _pytorch_ready(path)
+    return weights_ready and _tokenizer_ready(path)
+
+
+def ensure_model_files(config: ModelConfig, backend: Backend) -> Path:
+    """Download model vào MODELS_DIR nếu chưa có."""
+    local_dir = model_local_dir(config)
+    local_dir.mkdir(parents=True, exist_ok=True)
+
+    if backend == Backend.CT2:
+        if _ct2_ready(local_dir, config.ct2_subdir) and _tokenizer_ready(local_dir):
+            return local_dir
+        patterns = _ct2_download_patterns(config)
+    else:
+        if _pytorch_ready(local_dir) and _tokenizer_ready(local_dir):
+            return local_dir
+        patterns = None
+
+    snapshot_download(
+        config.model_id,
+        local_dir=str(local_dir),
+        allow_patterns=patterns,
+    )
+    return local_dir
+
+
+def download_all_models(*, include_pytorch_weights: bool = False) -> list[Path]:
+    """Tải trước tất cả model vào MODELS_DIR (dùng cho setup.bat).
+
+    Mặc định chỉ tải bản CT2 INT8 (~95 MB tổng) vì đó là engine mặc định.
+    PyTorch weights (~nặng gấp ~4 lần) chỉ tải khi include_pytorch_weights=True
+    hoặc tự động khi người dùng đổi sang engine PyTorch lần đầu (ensure_model_files).
+    """
+    saved: list[Path] = []
+    for config in MODELS.values():
+        ensure_model_files(config, Backend.CT2)
+        saved.append(model_local_dir(config))
+        if include_pytorch_weights:
+            ensure_model_files(config, Backend.TRANSFORMERS)
+    return saved
+
+
+class HachimiTranslator:
+    def __init__(self, profile: HardwareProfile | None = None) -> None:
+        self._profile = profile or detect_hardware_profile()
+        self._torch_device = "cuda" if _torch_cuda_available() else "cpu"
+        self._model_key: str | None = None
+        self._backend: Backend | None = None
+        self._tokenizer = None
+        self._torch_model = None
+        self._ct2_model = None
+        self._model_path: Path | None = None
+        self._ct2_threads = self._profile.ct2_threads
+        self._ct2_inter_threads = _env_int("HACHIMIMT_INTER_THREADS", 1, max_value=8)
+        self._ct2_window_multiplier = _env_int("HACHIMIMT_CT2_WINDOW_MULTIPLIER", 4, max_value=16)
+        self._tokenize_job_size = _env_int("HACHIMIMT_TOKENIZE_JOB_SIZE", 32, max_value=256)
+        batch_type = os.environ.get("HACHIMIMT_CT2_BATCH_TYPE", "tokens").strip().lower()
+        self._ct2_batch_type = batch_type if batch_type in {"examples", "tokens"} else "tokens"
+        self._ct2_compute_type: str | None = None
+        self._batch_size = self._profile.batch_size
+        self._tokenize_workers = self._profile.tokenize_workers
+        self._tokenize_pool: ThreadPoolExecutor | None = None
+
+    @property
+    def hardware_profile(self) -> HardwareProfile:
+        return self._profile
+
+    @property
+    def batch_size(self) -> int:
+        return self._batch_size
+
+    def set_batch_size(self, batch_size: int) -> None:
+        self._batch_size = max(4, min(128, int(batch_size)))
+
+    def apply_hardware_profile(self, profile: HardwareProfile | None = None) -> None:
+        profile = profile or detect_hardware_profile()
+        threads_changed = profile.ct2_threads != self._ct2_threads
+        workers_changed = profile.tokenize_workers != self._tokenize_workers
+        self._profile = profile
+        self._ct2_threads = profile.ct2_threads
+        self._batch_size = profile.batch_size
+        self._tokenize_workers = profile.tokenize_workers
+        if workers_changed and self._tokenize_pool is not None:
+            self._tokenize_pool.shutdown(wait=False, cancel_futures=True)
+            self._tokenize_pool = None
+
+        if threads_changed and self._backend == Backend.CT2 and self._model_key:
+            model_key = self._model_key
+            self._unload_models()
+            self._load_ct2(MODELS[model_key])
+            self._model_key = model_key
+            self._backend = Backend.CT2
+
+    @property
+    def device(self) -> str:
+        if self._backend == Backend.CT2 and self._ct2_model is not None:
+            return self._ct2_model.device
+        return self._torch_device
+
+    def device_label(self) -> str:
+        """Tên thiết bị inference thực tế (để phân biệt iGPU vs NVIDIA)."""
+        if self.device == "cuda":
+            return _torch_cuda_device_name() or self._profile.gpu_name or "CUDA GPU"
+        return "CPU"
+
+    @property
+    def backend(self) -> Backend | None:
+        return self._backend
+
+    def load(self, model_key: str, backend: Backend | str = Backend.CT2) -> str:
+        if isinstance(backend, str):
+            backend = Backend(backend)
+
+        if model_key not in MODELS:
+            raise ValueError(f"Unknown model: {model_key}")
+
+        if (
+            self._model_key == model_key
+            and self._backend == backend
+            and self._tokenizer is not None
+            and (self._ct2_model is not None or self._torch_model is not None)
+        ):
+            return self._status_message(model_key, backend, cached=True)
+
+        config = MODELS[model_key]
+        self._unload_models()
+
+        if backend == Backend.CT2:
+            self._load_ct2(config)
+        else:
+            self._load_transformers(config)
+
+        self._model_key = model_key
+        self._backend = backend
+        return self._status_message(model_key, backend, cached=False)
+
+    def _status_message(
+        self,
+        model_key: str,
+        backend: Backend,
+        *,
+        cached: bool,
+        beam_size: int | None = None,
+    ) -> str:
+        prefix = "Model" if cached else "Đã tải"
+        config = MODELS[model_key]
+        engine = "CTranslate2 INT8" if backend == Backend.CT2 else "PyTorch"
+        msg = f"{prefix} {config.label} · {engine} · {self.device_label()}"
+        if backend == Backend.CT2 and self._ct2_compute_type:
+            msg += f" · compute={self._ct2_compute_type}"
+            msg += (
+                f" · batch_type={self._ct2_batch_type}"
+                f" · window={self._ct2_window_multiplier}x"
+                f" · inter={self._ct2_inter_threads}"
+            )
+        if beam_size is not None:
+            msg += f" · beam={beam_size}"
+        return msg
+
+    @staticmethod
+    def clamp_beam(beam_size: int) -> int:
+        return max(1, min(4, int(beam_size)))
+
+    def _unload_models(self) -> None:
+        self._torch_model = None
+        self._ct2_model = None
+        self._tokenizer = None
+        self._model_path = None
+        self._ct2_compute_type = None
+        if self._tokenize_pool is not None:
+            self._tokenize_pool.shutdown(wait=False, cancel_futures=True)
+            self._tokenize_pool = None
+        if self._torch_device == "cuda":
+            _torch_empty_cuda_cache()
+
+    def _get_tokenize_pool(self) -> ThreadPoolExecutor:
+        if self._tokenize_pool is None:
+            self._tokenize_pool = ThreadPoolExecutor(
+                max_workers=self._tokenize_workers,
+                thread_name_prefix="hachimi-tokenize",
+            )
+        return self._tokenize_pool
+
+    def _tokenize_chunks_parallel(self, chunks: list[str]) -> list[list[str]]:
+        if not chunks:
+            return []
+        if len(chunks) <= self._tokenize_job_size or self._tokenize_workers <= 1:
+            return self._source_tokens_batch(chunks)
+        pool = self._get_tokenize_pool()
+        groups = list(_batched(chunks, self._tokenize_job_size))
+        nested = pool.map(self._source_tokens_batch, groups)
+        return [tokens for group in nested for tokens in group]
+
+    def _submit_tokenize_jobs(self, chunks: list[str]) -> SourceTokenJobs:
+        pool = self._get_tokenize_pool()
+        return [
+            pool.submit(self._source_tokens_batch, group)
+            for group in _batched(chunks, self._tokenize_job_size)
+        ]
+
+    @staticmethod
+    def _collect_tokenize_jobs(jobs: SourceTokenJobs) -> list[list[str]]:
+        return [tokens for job in jobs for tokens in job.result()]
+
+    def _decode_ct2_results(self, results) -> list[str]:
+        hypotheses = [result.hypotheses[0] for result in results]
+        token_ids = [self._tokenizer.convert_tokens_to_ids(tokens) for tokens in hypotheses]
+        return [
+            text.strip()
+            for text in self._tokenizer.batch_decode(token_ids, skip_special_tokens=True)
+        ]
+
+    def _load_ct2(self, config: ModelConfig) -> None:
+        model_path = ensure_model_files(config, Backend.CT2)
+        tokenizer = CT2SentencePieceTokenizer(model_path)
+
+        env_compute_type = os.environ.get("HACHIMIMT_COMPUTE_TYPE", "").strip()
+        ct2_device = "cuda" if self._profile.has_cuda else "cpu"
+        attempts = [(ct2_device, default_ct2_compute_type(ct2_device))]
+        if not env_compute_type and ct2_device == "cuda":
+            attempts.extend([("cuda", "int8_float32"), ("cpu", "int8_float32")])
+        elif env_compute_type and ct2_device == "cuda":
+            attempts.append(("cpu", "int8_float32"))
+
+        translator = None
+        last_error: Exception | None = None
+        for device, compute_type in attempts:
+            try:
+                translator = ctranslate2.Translator(
+                    str(model_path / config.ct2_subdir),
+                    device=device,
+                    compute_type=compute_type,
+                    intra_threads=self._ct2_threads,
+                    inter_threads=self._ct2_inter_threads,
+                )
+                self._ct2_compute_type = compute_type
+                break
+            except Exception as exc:
+                last_error = exc
+
+        if translator is None:
+            raise RuntimeError("Không tải được CTranslate2 backend.") from last_error
+
+        self._tokenizer = tokenizer
+        self._ct2_model = translator
+        self._model_path = model_path
+
+    def _load_transformers(self, config: ModelConfig) -> None:
+        _require_torch()
+        try:
+            from transformers import AutoModelForSeq2SeqLM, AutoTokenizer, MarianMTModel
+        except Exception as exc:
+            raise RuntimeError(
+                "Backend PyTorch cần transformers/sacremoses/safetensors. "
+                "Cài thêm: pip install -r requirements-pytorch.txt"
+            ) from exc
+
+        model_path = ensure_model_files(config, Backend.TRANSFORMERS)
+        tokenizer = AutoTokenizer.from_pretrained(model_path)
+        if config.use_marian_class:
+            model = MarianMTModel.from_pretrained(model_path)
+        else:
+            model = AutoModelForSeq2SeqLM.from_pretrained(model_path)
+
+        model = model.to(self._torch_device).eval()
+        self._tokenizer = tokenizer
+        self._torch_model = model
+
+    def _chunk_text(self, text: str, chunk_mode: str) -> list[str]:
+        config = MODELS[self._model_key]
+        if self._backend == Backend.CT2 and self._tokenizer is not None:
+            return split_for_translation(
+                self._tokenizer,
+                text,
+                max_tokens=config.ct2_max_input_tokens,
+                chunk_mode=chunk_mode,
+            )
+        return split_chunks(text, mode=chunk_mode)
+
+    def _source_tokens(self, text: str) -> list[str]:
+        config = MODELS[self._model_key]
+        token_ids = source_token_ids(
+            self._tokenizer,
+            text,
+            max_length=config.ct2_max_input_tokens,
+            truncation=True,
+        )
+        return self._tokenizer.convert_ids_to_tokens(token_ids)
+
+    def _source_tokens_batch(self, chunks: list[str]) -> list[list[str]]:
+        config = MODELS[self._model_key]
+        encoded = self._tokenizer(
+            chunks,
+            truncation=True,
+            max_length=config.ct2_max_input_tokens,
+            padding=False,
+        )["input_ids"]
+        pad_id = self._tokenizer.pad_token_id
+        if pad_id is not None:
+            encoded = [
+                [token_id for token_id in token_ids if token_id != pad_id]
+                for token_ids in encoded
+            ]
+        return [self._tokenizer.convert_ids_to_tokens(token_ids) for token_ids in encoded]
+
+    def _decode_tokens(self, tokens: list[str]) -> str:
+        token_ids = self._tokenizer.convert_tokens_to_ids(tokens)
+        return self._tokenizer.decode(token_ids, skip_special_tokens=True).strip()
+
+    def _torch_generate_kwargs(self, beam_size: int) -> dict:
+        config = MODELS[self._model_key]
+        kwargs = dict(config.generate_kwargs)
+        kwargs["num_beams"] = beam_size
+        if config.use_marian_class:
+            kwargs["early_stopping"] = beam_size > 1
+        return kwargs
+
+    def _runtime_batch_size(self, beam_size: int) -> int:
+        """PyTorch tốn VRAM hơn theo beam — giảm batch để tránh OOM."""
+        if self._backend == Backend.CT2:
+            return self._batch_size
+        beam_size = self.clamp_beam(beam_size)
+        vram_factor = max(1, beam_size * 2)
+        return max(4, min(self._batch_size, 48 // vram_factor))
+
+    def _runtime_window_size(self, beam_size: int) -> int:
+        batch_size = self._runtime_batch_size(beam_size)
+        if self._backend == Backend.CT2:
+            return max(batch_size, batch_size * self._ct2_window_multiplier)
+        return batch_size
+
+    def _ct2_max_batch_size(self, config: ModelConfig) -> int:
+        if self._ct2_batch_type == "tokens":
+            return self._batch_size * config.ct2_max_input_tokens
+        return self._batch_size
+
+    def _translate_torch_batch(self, chunks: list[str], *, beam_size: int) -> list[str]:
+        if not chunks:
+            return []
+
+        torch = _require_torch()
+        config = MODELS[self._model_key]
+        max_length = 256 if config.use_marian_class else 512
+        inputs = self._tokenizer(
+            chunks,
+            return_tensors="pt",
+            padding=True,
+            truncation=True,
+            max_length=max_length,
+        ).to(self._torch_device)
+
+        with torch.inference_mode():
+            outputs = self._torch_model.generate(
+                **inputs,
+                **self._torch_generate_kwargs(beam_size),
+            )
+
+        return [
+            self._tokenizer.decode(output, skip_special_tokens=True).strip()
+            for output in outputs
+        ]
+
+    def translate_chunk(self, text: str, *, beam_size: int = 2) -> str:
+        if self._tokenizer is None:
+            raise RuntimeError("Chưa tải model. Gọi load() trước.")
+
+        beam_size = self.clamp_beam(beam_size)
+
+        if self._backend == Backend.CT2:
+            return self._translate_chunks_ct2([text], beam_size=beam_size)[0]
+
+        return self._translate_torch_batch([text], beam_size=beam_size)[0]
+
+    def count_chunks(self, text: str, chunk_mode: str = "sentence") -> int:
+        if not self._model_key:
+            raise RuntimeError("Chưa tải model. Gọi load() trước.")
+        return len(self._chunk_text(text, chunk_mode))
+
+    def _translate_ct2_batch(
+        self,
+        chunks: list[str],
+        *,
+        beam_size: int,
+        source_batches: list[list[str]] | None = None,
+    ) -> list[str]:
+        config = MODELS[self._model_key]
+        if source_batches is None:
+            source_batches = self._tokenize_chunks_parallel(chunks)
+        results = self._ct2_model.translate_batch(
+            source_batches,
+            max_batch_size=self._ct2_max_batch_size(config),
+            batch_type=self._ct2_batch_type,
+            beam_size=beam_size,
+            max_decoding_length=config.ct2_max_output_tokens,
+        )
+        return self._decode_ct2_results(results)
+
+    def _translate_ct2_batch_pipelined(
+        self,
+        chunks: list[str],
+        *,
+        beam_size: int,
+        prefetched_tokens: SourceTokenJobs | None,
+    ) -> list[str]:
+        if prefetched_tokens is not None:
+            source_batches = self._collect_tokenize_jobs(prefetched_tokens)
+        else:
+            source_batches = None
+        return self._translate_ct2_batch(
+            chunks,
+            beam_size=beam_size,
+            source_batches=source_batches,
+        )
+
+    def _translate_chunks_ct2(self, chunks: list[str], *, beam_size: int) -> list[str]:
+        if self._ct2_model is None:
+            raise RuntimeError("CTranslate2 chưa được tải.")
+
+        beam_size = self.clamp_beam(beam_size)
+        if not chunks:
+            return []
+        return self._translate_ct2_batch(chunks, beam_size=beam_size)
+
+    def translate_text_iter(
+        self,
+        text: str,
+        *,
+        chunk_mode: str = "sentence",
+        beam_size: int = 2,
+    ) -> Iterator[tuple[int, int, str, list[tuple[int, str, str]] | None, str | None]]:
+        """Yield (done, total, message, rows_or_none, full_text_or_none) sau mỗi batch."""
+        beam_size = self.clamp_beam(beam_size)
+        chunks = self._chunk_text(text, chunk_mode)
+        total = len(chunks)
+
+        yield 0, total, f"Đã chia {total} chunk, chuẩn bị dịch...", None, None
+
+        translations: list[str] = []
+        batch_size = self._runtime_batch_size(beam_size)
+        window_size = self._runtime_window_size(beam_size)
+        next_tokens: SourceTokenJobs | None = None
+        if self._backend == Backend.CT2 and total:
+            first_end = min(window_size, total)
+            next_tokens = self._submit_tokenize_jobs(chunks[:first_end])
+
+        for start in range(0, total, window_size):
+            end = min(start + window_size, total)
+            batch_label = (
+                f"window {window_size}, batch {batch_size}, {self._ct2_batch_type}"
+                if self._backend == Backend.CT2
+                else f"batch {batch_size}"
+            )
+            yield (
+                start,
+                total,
+                f"Đang dịch chunk {start + 1}–{end}/{total} ({batch_label})...",
+                None,
+                None,
+            )
+
+            batch = chunks[start:end]
+            if self._backend == Backend.CT2:
+                current_tokens = next_tokens
+                next_tokens = None
+                next_start = start + window_size
+                next_end = min(next_start + window_size, total)
+                if next_start < total:
+                    next_batch = chunks[next_start:next_end]
+                    next_tokens = self._submit_tokenize_jobs(next_batch)
+
+                translations.extend(
+                    self._translate_ct2_batch_pipelined(
+                        batch,
+                        beam_size=beam_size,
+                        prefetched_tokens=current_tokens,
+                    )
+                )
+            else:
+                translations.extend(self._translate_torch_batch(batch, beam_size=beam_size))
+
+            yield end, total, f"Đã xong {end}/{total} chunk", None, None
+
+        rows = [
+            (index, chunk, translated)
+            for index, (chunk, translated) in enumerate(zip(chunks, translations), start=1)
+        ]
+        full_text = "\n".join(translations)
+        yield total, total, "Hoàn tất dịch.", rows, full_text
+
+    def translate_text(
+        self,
+        text: str,
+        *,
+        chunk_mode: str = "sentence",
+        beam_size: int = 2,
+        on_progress: Callable[[int, int, str], None] | None = None,
+    ) -> tuple[list[tuple[int, str, str]], str]:
+        rows: list[tuple[int, str, str]] = []
+        full_text = ""
+        for done, total, message, result_rows, result_text in self.translate_text_iter(
+            text,
+            chunk_mode=chunk_mode,
+            beam_size=beam_size,
+        ):
+            if on_progress:
+                on_progress(done, total, message)
+            if result_rows is not None and result_text is not None:
+                rows = result_rows
+                full_text = result_text
+        return rows, full_text