README: English default + README_vi.md (match family structure)

README.md

@@ -19,71 +19,82 @@ datasets:
 - chi-vi/hirashiba-mt-zh2vi-b-filtered
 ---
 
-# HachimiMT-60-QT: dịch truyện Trung→Việt, văn phong convert thuần nhất
+# HachimiMT-60-QT: Chinese→Vietnamese translation with a perfectly consistent "convert" voice
 
-Bản "giọng cổ trang" của [HachimiMT-60](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi):
-dịch tiếng Trung sang tiếng Việt theo **văn phong truyện convert** — *ta, ngươi, hắn,
-nàng, tỷ tỷ, ca ca…* — và **giữ đúng một giọng từ đầu đến cuối chương**.
+> 🇻🇳 [Đọc bản tiếng Việt](./README_vi.md)
 
-## Khác gì bản thường?
+The "classical register" edition of
+[HachimiMT-60](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi): it translates
+Chinese web novels into Vietnamese using the **truyện convert** pronoun register —
+*ta, ngươi, hắn, nàng, tỷ tỷ, ca ca…* (the archaic Sino-Vietnamese address style
+that Vietnamese web-novel readers know by heart) — and **keeps that voice perfectly
+stable from the first line of a chapter to the last**.
 
-Model dịch máy bình thường (kể cả bản HachimiMT-60 gốc) có một tật khó chịu với
-người đọc truyện: **đang dịch thì đổi cách xưng hô giữa chừng** — cùng một nhân vật,
-câu trước gọi "ngươi", câu sau thành "cậu"; đoạn trước xưng "ta", đoạn sau thành "tôi".
+## What's different from the base model?
 
-Bản QT được huấn luyện trên dữ liệu đã chuẩn hóa toàn bộ hệ xưng hô, nên **không còn
-đổi giọng nữa**. Ví dụ thật, cùng một chương truyện, cùng một cuộc phỏng vấn
-(HachimiMT-60 thường vs bản QT này):
+Ordinary MT models (including base HachimiMT-60) have a habit that drives novel
+readers crazy: **they switch address style mid-chapter**. The same character is
+"ngươi" (archaic *you*) in one line and suddenly "cậu" (modern *you*) in the next;
+the narrator says "ta" (*I*, archaic) in one paragraph and "tôi" (*I*, modern) in
+another.
 
-| Nguyên văn | Bản thường | **Bản QT** |
+This QT edition was trained on data whose entire pronoun system was normalized, so
+**the voice never flips**. Real output, same chapter, same interview scene
+(base HachimiMT-60 vs this model):
+
+| Source | Base model | **QT model** |
 |---|---|---|
 | 你为什么要报考我们的学校？ | Tại sao **ngươi** lại muốn thi vào trường của chúng ta? | Tại sao **ngươi** phải thi vào trường của chúng ta? |
-| 你成绩没有问题…… (câu ngay sau) | Thành tích của **cậu** không thành vấn đề… ← *đổi giọng!* | Thành tích của **ngươi** không có vấn đề gì… |
-| 我来给你介绍介绍这里的福利吧 | Để **tôi** giới thiệu phúc lợi ở đây cho **cậu** nhé, **chúng tôi**… | Để **ta** giới thiệu phúc lợi ở đây cho **ngươi** nhé, **chúng ta**… |
-| 张羽……他感觉…… (lời kể) | Trương Vũ… **cậu** cảm thấy… ← *"cậu" cho lời kể* | Trương Vũ… **hắn** cảm thấy… |
+| 你成绩没有问题…… (very next line) | Thành tích của **cậu** không thành vấn đề… ← *voice flips!* | Thành tích của **ngươi** không có vấn đề gì… |
+| 我来给你介绍介绍这里的福利吧 | Để **tôi** giới thiệu … cho **cậu** nhé, **chúng tôi**… | Để **ta** giới thiệu … cho **ngươi** nhé, **chúng ta**… |
+| 张羽……他感觉…… (narration) | Trương Vũ… **cậu** cảm thấy… ← *modern "cậu" in narration* | Trương Vũ… **hắn** cảm thấy… |
 
-Đo trên 7 chương thuộc 7 thể loại khác nhau (538 câu): ở lớp xưng hô "ngươi/cậu",
-bản thường **đổi giọng ở ~24% chỗ chuyển câu**; bản QT: **0%**. Các lớp
-ta/tôi, chúng ta/chúng tôi, hắn/nàng cũng về 0 tương tự.
+Measured on 7 chapters across 7 genres (538 lines): in the *you*-register class the
+base model **flips voice at ~24% of line transitions**; this model: **0%**. The
+*I*, *we* and third-person classes also drop to zero.
 
-## Câu khó (stress test)
+## Stress tests
 
-**Một câu chứa 4 ngôi** — không lẫn ai với ai:
+**Four pronouns in one sentence** — nothing gets mixed up:
 
 > 他说你不懂她的心思，我们都别插手了。
 > → *Hắn nói ngươi không hiểu tâm tư của nàng, chúng ta đều đừng nhúng tay vào.*
+> (he→hắn, you→ngươi, she→nàng, we→chúng ta)
 
-**Đoạn dài nhiều lượt xưng hô** — chỗ bản thường dễ "đổi giọng ngay giữa đoạn":
+**A long multi-clause paragraph** — where the base model mixes two voices inside a
+single paragraph:
 
 > 张羽同学，我们了解到你的家庭情况恐怕不足以负担这边的学费。不过我们为贫困生提供了优惠的贷款服务，只要你愿意抵押一些不重要的器官就行……
 
-| | Dịch |
+| | Translation |
 |---|---|
-| Bản thường | Bạn học Trương Vũ, **chúng tôi** hiểu được tình hình gia đình của **bạn**… Tuy nhiên, **chúng ta** đã cung cấp dịch vụ vay… chỉ cần **bạn**… ← *trộn 2 giọng trong 1 đoạn* |
-| **Bản QT** | Bạn học Trương Vũ, **chúng ta** biết được tình hình gia đình của **ngươi**… Nhưng **chúng ta** đã cung cấp dịch vụ vay vốn ưu đãi… chỉ cần **ngươi** chịu thế chấp một số nội tạng không quan trọng là được... |
+| Base | Bạn học Trương Vũ, **chúng tôi** hiểu được tình hình gia đình của **bạn**… Tuy nhiên, **chúng ta** đã cung cấp dịch vụ vay… chỉ cần **bạn**… ← *two registers in one paragraph* |
+| **QT** | Bạn học Trương Vũ, **chúng ta** biết được tình hình gia đình của **ngươi**… Nhưng **chúng ta** đã cung cấp dịch vụ vay vốn ưu đãi… chỉ cần **ngươi** chịu thế chấp một số nội tạng không quan trọng là được... |
 
-## Giới hạn đã biết (ví dụ thật, không giấu)
+## When to use it
 
-Tên riêng/thuật ngữ hiếm thỉnh thoảng lệch âm hoặc bị dịch nghĩa — hạn chế chung của
-cả họ model cỡ nhỏ, không riêng bản QT. Ví dụ tên linh thú 【异瞳金丝猴】
-(chuẩn: *Dị Đồng Kim Ty Hầu*): bản thường ra "Kim **Ti** Hầu", bản QT ra
-"Kim **Tơ** Hầu" (dịch nghĩa chữ 丝). Đọc truyện nhiều tên riêng lạ thì nên
-soát lại các tên xuất hiện lần đầu.
+- ✅ Xianxia, xuanhuan, historical, danmei — or **any** genre where you want the
+  convert voice all the way through.
+- ⚠️ Modern-setting stories also come out in the archaic voice ("Sao ngươi chưa
+  nghỉ ngơi?") — that is **by design**. If you want context-appropriate natural
+  register instead, use the
+  [base model](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi).
 
-## Dùng khi nào?
+Deliberate trade-offs (documented so nothing surprises you):
 
-- ✅ Đọc/convert truyện tiên hiệp, huyền huyễn, cổ trang, đam mỹ cổ phong — hoặc bất
-  kỳ thể loại nào bạn muốn **giọng convert xuyên suốt**.
-- ⚠️ Truyện hiện đại cũng sẽ ra giọng convert ("Sao ngươi chưa nghỉ ngơi?") — đây là
-  **chủ đích** của bản này. Muốn giọng tự nhiên theo ngữ cảnh, dùng
-  [bản thường](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi).
+- 我们/咱们 both become **"chúng ta"** (the inclusive/exclusive *we* distinction is dropped).
+- Modern intimate address (anh/em between lovers) mostly becomes ta/ngươi.
 
-Vài điều đánh đổi (chủ đích, ghi rõ để khỏi bất ngờ):
+## Known limitations (real example, not hidden)
 
-- 我们/咱们 đều thành **"chúng ta"** (không còn phân biệt "chúng tôi").
-- Xưng hô thân mật kiểu hiện đại (anh/em trong thoại yêu đương) phần lớn thành ta/ngươi.
+Rare proper nouns and coined terms can come out with a shifted syllable or a
+literal translation — a limitation of every model in this size class, not specific
+to the QT edition. Example, the spirit-beast name 【异瞳金丝猴】 (reference:
+*Dị Đồng Kim Ty Hầu*): the base model outputs "Kim **Ti** Hầu", this model outputs
+"Kim **Tơ** Hầu" (literal reading of 丝). If your novel is full of first-time rare
+names, spot-check them.
 
-## Dùng nhanh (Python)
+## Quick start (Python)
 
 ```python
 from transformers import AutoTokenizer, MarianMTModel
@@ -102,14 +113,14 @@ print(tokenizer.decode(out[0], skip_special_tokens=True))
 #  Tung Dương, chỉ dựa vào điểm thi trong trường là còn xa mới đủ."
 ```
 
-> 💡 **Mẹo decode**: đừng bật `no_repeat_ngram_size` với model này — nó ép máy
-> "né chữ lặp" nên hay bóp méo tên riêng (Lý Giáng Thiên → Lý Giáng Dương).
-> Cứ để mặc định như ví dụ trên.
+> 💡 **Decoding tip**: do **not** set `no_repeat_ngram_size` with this model — it
+> forces the decoder to avoid repeating n-grams and tends to mangle proper names
+> (Lý Giáng Thiên → Lý Giáng Dương). The defaults above are what we ship with.
 
-## Chạy nhanh trên CPU (CTranslate2)
+## Fast CPU inference (CTranslate2)
 
-Repo kèm sẵn bản nén INT8 trong thư mục `ct2-int8_float32/` — dịch nhanh gấp nhiều
-lần trên máy không có GPU:
+The repo ships an INT8 export under `ct2-int8_float32/` — several times faster on
+machines without a GPU:
 
 ```python
 import ctranslate2
@@ -134,13 +145,13 @@ print(tokenizer.decode(tokenizer.convert_tokens_to_ids(res[0].hypotheses[0]),
 # "Ngươi yên tâm đi, người ta là công ty lớn, sẽ không lừa người đâu."
 ```
 
-## Gia đình Hachimi
+## The Hachimi family
 
-| Model | Dùng khi |
+| Model | Use when |
 |---|---|
-| [HachimiMT-60-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi) | Giọng tự nhiên theo ngữ cảnh, đa thể loại |
-| **HachimiMT-60-QT** (bản này) | Giọng convert thuần nhất, không đổi xưng hô |
-| [Demo Space](https://huggingface.co/spaces/ngocdang83/HachimiMT-demo) | Dịch thử ngay trên trình duyệt |
+| [HachimiMT-60-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi) | Natural, context-dependent register |
+| **HachimiMT-60-QT** (this) | One perfectly stable convert voice |
+| [Demo Space](https://huggingface.co/spaces/ngocdang83/HachimiMT-demo) | Try it in the browser |
 
-Chi tiết kỹ thuật (56.96M tham số, Marian encoder-decoder, chạy tốt cả CPU lẫn GPU)
-xem `config.json`. Giấy phép CC-BY-4.0 — dùng thoải mái, ghi nguồn là được.
+Technical details (56.96M params, Marian encoder-decoder, runs fine on CPU or GPU)
+are in `config.json`. License CC-BY-4.0 — use freely with attribution.

README_vi.md

@@ -0,0 +1,127 @@
+> 🇬🇧 [English version](./README.md)
+
+# HachimiMT-60-QT: dịch truyện Trung→Việt, văn phong convert thuần nhất
+
+Bản "giọng cổ trang" của [HachimiMT-60](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi):
+dịch tiếng Trung sang tiếng Việt theo **văn phong truyện convert** — *ta, ngươi, hắn,
+nàng, tỷ tỷ, ca ca…* — và **giữ đúng một giọng từ đầu đến cuối chương**.
+
+## Khác gì bản thường?
+
+Model dịch máy bình thường (kể cả bản HachimiMT-60 gốc) có một tật khó chịu với
+người đọc truyện: **đang dịch thì đổi cách xưng hô giữa chừng** — cùng một nhân vật,
+câu trước gọi "ngươi", câu sau thành "cậu"; đoạn trước xưng "ta", đoạn sau thành "tôi".
+
+Bản QT được huấn luyện trên dữ liệu đã chuẩn hóa toàn bộ hệ xưng hô, nên **không còn
+đổi giọng nữa**. Ví dụ thật, cùng một chương truyện, cùng một cuộc phỏng vấn
+(HachimiMT-60 thường vs bản QT này):
+
+| Nguyên văn | Bản thường | **Bản QT** |
+|---|---|---|
+| 你为什么要报考我们的学校？ | Tại sao **ngươi** lại muốn thi vào trường của chúng ta? | Tại sao **ngươi** phải thi vào trường của chúng ta? |
+| 你成绩没有问题…… (câu ngay sau) | Thành tích của **cậu** không thành vấn đề… ← *đổi giọng!* | Thành tích của **ngươi** không có vấn đề gì… |
+| 我来给你介绍介绍这里的福利吧 | Để **tôi** giới thiệu phúc lợi ở đây cho **cậu** nhé, **chúng tôi**… | Để **ta** giới thiệu phúc lợi ở đây cho **ngươi** nhé, **chúng ta**… |
+| 张羽……他感觉…… (lời kể) | Trương Vũ… **cậu** cảm thấy… ← *"cậu" cho lời kể* | Trương Vũ… **hắn** cảm thấy… |
+
+Đo trên 7 chương thuộc 7 thể loại khác nhau (538 câu): ở lớp xưng hô "ngươi/cậu",
+bản thường **đổi giọng ở ~24% chỗ chuyển câu**; bản QT: **0%**. Các lớp
+ta/tôi, chúng ta/chúng tôi, hắn/nàng cũng về 0 tương tự.
+
+## Câu khó (stress test)
+
+**Một câu chứa 4 ngôi** — không lẫn ai với ai:
+
+> 他说你不懂她的心思，我们都别插手了。
+> → *Hắn nói ngươi không hiểu tâm tư của nàng, chúng ta đều đừng nhúng tay vào.*
+
+**Đoạn dài nhiều lượt xưng hô** — chỗ bản thường dễ "đổi giọng ngay giữa đoạn":
+
+> 张羽同学，我们了解到你的家庭情况恐怕不足以负担这边的学费。不过我们为贫困生提供了优惠的贷款服务，只要你愿意抵押一些不重要的器官就行……
+
+| | Dịch |
+|---|---|
+| Bản thường | Bạn học Trương Vũ, **chúng tôi** hiểu được tình hình gia đình của **bạn**… Tuy nhiên, **chúng ta** đã cung cấp dịch vụ vay… chỉ cần **bạn**… ← *trộn 2 giọng trong 1 đoạn* |
+| **Bản QT** | Bạn học Trương Vũ, **chúng ta** biết được tình hình gia đình của **ngươi**… Nhưng **chúng ta** đã cung cấp dịch vụ vay vốn ưu đãi… chỉ cần **ngươi** chịu thế chấp một số nội tạng không quan trọng là được... |
+
+## Giới hạn đã biết (ví dụ thật, không giấu)
+
+Tên riêng/thuật ngữ hiếm thỉnh thoảng lệch âm hoặc bị dịch nghĩa — hạn chế chung của
+cả họ model cỡ nhỏ, không riêng bản QT. Ví dụ tên linh thú 【异瞳金丝猴】
+(chuẩn: *Dị Đồng Kim Ty Hầu*): bản thường ra "Kim **Ti** Hầu", bản QT ra
+"Kim **Tơ** Hầu" (dịch nghĩa chữ 丝). Đọc truyện nhiều tên riêng lạ thì nên
+soát lại các tên xuất hiện lần đầu.
+
+## Dùng khi nào?
+
+- ✅ Đọc/convert truyện tiên hiệp, huyền huyễn, cổ trang, đam mỹ cổ phong — hoặc bất
+  kỳ thể loại nào bạn muốn **giọng convert xuyên suốt**.
+- ⚠️ Truyện hiện đại cũng sẽ ra giọng convert ("Sao ngươi chưa nghỉ ngơi?") — đây là
+  **chủ đích** của bản này. Muốn giọng tự nhiên theo ngữ cảnh, dùng
+  [bản thường](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi).
+
+Vài điều đánh đổi (chủ đích, ghi rõ để khỏi bất ngờ):
+
+- 我们/咱们 đều thành **"chúng ta"** (không còn phân biệt "chúng tôi").
+- Xưng hô thân mật kiểu hiện đại (anh/em trong thoại yêu đương) phần lớn thành ta/ngươi.
+
+## Dùng nhanh (Python)
+
+```python
+from transformers import AutoTokenizer, MarianMTModel
+import torch
+
+repo = "ngocdang83/HachimiMT-60-QT"
+tokenizer = AutoTokenizer.from_pretrained(repo)
+model = MarianMTModel.from_pretrained(repo).eval()
+
+src = "你成绩没有问题，但想要进嵩阳高中，光靠校内考试成绩是远远不够的。"
+inp = tokenizer(src, return_tensors="pt", truncation=True, max_length=256)
+with torch.inference_mode():
+    out = model.generate(**inp, max_new_tokens=300, num_beams=4, early_stopping=True)
+print(tokenizer.decode(out[0], skip_special_tokens=True))
+# "Thành tích của ngươi không có vấn đề gì, nhưng muốn vào trường trung học
+#  Tung Dương, chỉ dựa vào điểm thi trong trường là còn xa mới đủ."
+```
+
+> 💡 **Mẹo decode**: đừng bật `no_repeat_ngram_size` với model này — nó ép máy
+> "né chữ lặp" nên hay bóp méo tên riêng (Lý Giáng Thiên → Lý Giáng Dương).
+> Cứ để mặc định như ví dụ trên.
+
+## Chạy nhanh trên CPU (CTranslate2)
+
+Repo kèm sẵn bản nén INT8 trong thư mục `ct2-int8_float32/` — dịch nhanh gấp nhiều
+lần trên máy không có GPU:
+
+```python
+import ctranslate2
+from pathlib import Path
+from huggingface_hub import snapshot_download
+from transformers import AutoTokenizer
+
+repo = "ngocdang83/HachimiMT-60-QT"
+path = Path(snapshot_download(repo, allow_patterns=[
+    "config.json", "source.spm", "target.spm", "vocab.json",
+    "tokenizer_config.json", "ct2-int8_float32/*",
+]))
+tokenizer = AutoTokenizer.from_pretrained(path)
+translator = ctranslate2.Translator(str(path / "ct2-int8_float32"),
+                                    device="cpu", compute_type="int8_float32")
+
+src = "你放心吧，人家是大公司，不会骗人的。"
+toks = tokenizer.convert_ids_to_tokens(tokenizer(src).input_ids)
+res = translator.translate_batch([toks], beam_size=1, max_decoding_length=256)
+print(tokenizer.decode(tokenizer.convert_tokens_to_ids(res[0].hypotheses[0]),
+                       skip_special_tokens=True))
+# "Ngươi yên tâm đi, người ta là công ty lớn, sẽ không lừa người đâu."
+```
+
+## Gia đình Hachimi
+
+| Model | Dùng khi |
+|---|---|
+| [HachimiMT-60-zh-vi](https://huggingface.co/ngocdang83/HachimiMT-60-zh-vi) | Giọng tự nhiên theo ngữ cảnh, đa thể loại |
+| **HachimiMT-60-QT** (bản này) | Giọng convert thuần nhất, không đổi xưng hô |
+| [Demo Space](https://huggingface.co/spaces/ngocdang83/HachimiMT-demo) | Dịch thử ngay trên trình duyệt |
+
+Chi tiết kỹ thuật (56.96M tham số, Marian encoder-decoder, chạy tốt cả CPU lẫn GPU)
+xem `config.json`. Giấy phép CC-BY-4.0 — dùng thoải mái, ghi nguồn là được.