From 76ea7959103b5f0807394c1a31b8dd564a7d9a86 Mon Sep 17 00:00:00 2001
From: tiennm99 <tiennm99@outlook.com>
Date: Tue, 14 Apr 2026 23:28:55 +0700
Subject: [PATCH] docs: translate narrative prose to English in README and
 docs/

---
 2017/README.md                   |  8 ++++----
 2017/docs/data-pipeline.md       | 27 ++++++++++++++++++++-------
 2017/docs/system-architecture.md | 24 ++++++++++++------------
 3 files changed, 36 insertions(+), 23 deletions(-)

diff --git a/2017/README.md b/2017/README.md
index e43e864..d05ac27 100644
--- a/2017/README.md
+++ b/2017/README.md
@@ -1,4 +1,4 @@
-# Tra cứu điểm thi THPT Quốc gia 2017
+# Vietnam THPT 2017 Score Lookup
 
 Static React + SQLite site for looking up Vietnamese high school graduation exam scores (2017). The full database (~861k students, 63 provinces) ships to the browser as a compressed SQLite file and queries run client-side via `sql.js` — no backend.
 
@@ -16,8 +16,8 @@ Three deployments, one per dataset:
 
 - Diacritics-insensitive name search (`"nguyen"` matches `"Nguyễn"`)
 - Live debounced search with URL deep-link (`?q=49008235`)
-- Single-result detail card with per-subject TFT rarity-tiered scores (6 tiers, ≤1 → 9-10) and all 49 admission blocks (khối A00 – D15)
-- Share button: copies formatted summary + URL for Zalo/Messenger
+- Single-result detail card with per-subject TFT rarity-tiered scores (6 tiers, ≤1 → 9-10) and all 49 admission blocks (A00 – D15)
+- Share button: copies a formatted summary plus deep-link URL
 - SQL query tab with grouped presets (rankings, Long An filters, statistics, schema)
 - Light + dark mode (follows OS preference)
 - Keyboard shortcut `/` to focus search
@@ -77,7 +77,7 @@ npm run dev          # http://localhost:5173
 │   ├── App.css
 │   ├── components/{search-form, score-table, student-detail, custom-query}.jsx
 │   ├── hooks/use-sqlite.js
-│   └── lib/admission-blocks.js   # 49 khối definitions + score-tier helper
+│   └── lib/admission-blocks.js   # 49 admission-block definitions + score-tier helper
 ├── docs/              # see docs/README.md
 ├── index.html
 ├── vite.config.js
diff --git a/2017/docs/data-pipeline.md b/2017/docs/data-pipeline.md
index d000e92..f3c62ad 100644
--- a/2017/docs/data-pipeline.md
+++ b/2017/docs/data-pipeline.md
@@ -23,19 +23,32 @@ Every file is a single sheet (for `data-old/`) or up to 3 sheets (for `data/` .x
 | 0 | HO_TEN     | full name in Vietnamese |
 | 1 | NGAY_SINH  | `dd/mm/yyyy` |
 | 2 | SOBAODANH  | 8-digit string, first 2 digits = province |
-| 3 | DIEM_THI   | concatenated Vietnamese score string, e.g. `"Toán: 6.80 Ngữ văn: 5.25 … Tiếng Anh: 5.80"` |
+| 3 | DIEM_THI   | concatenated per-subject score string in the source language, e.g. `"Toan: 6.80 Van: 5.25 ... English: 5.80"` |
 
 Some files lack a header row. `isHeaderRow()` in `build-lib.js` detects and skips.
 
 ## Score text parsing
 
-`SCORE_PATTERNS` in `build-lib.js` defines one regex per subject:
+`SCORE_PATTERNS` in `build-lib.js` defines one regex per subject. The patterns must match the exact subject labels the source files use (Vietnamese).
 
-```js
-{ toan: /Toán:\s*(\d+(?:\.\d+)?)/, ngu_van: /Ngữ văn:…/, … }
-```
+Subjects supported (DB column / label in source text):
 
-Subjects supported: Toán, Ngữ văn, Vật lí, Hóa học, Sinh học, KHTN, Lịch sử, Địa lí, GDCD, KHXH, Tiếng Anh, Tiếng Pháp, Tiếng Nga, Tiếng Trung.
+| Column | Source label | English |
+|---|---|---|
+| toan        | Toán        | Math |
+| ngu_van     | Ngữ văn     | Literature |
+| vat_ly      | Vật lí      | Physics |
+| hoa_hoc     | Hóa học     | Chemistry |
+| sinh_hoc    | Sinh học    | Biology |
+| khtn        | KHTN        | Natural Sciences combined |
+| lich_su     | Lịch sử     | History |
+| dia_ly      | Địa lí      | Geography |
+| gdcd        | GDCD        | Civic Education |
+| khxh        | KHXH        | Social Sciences combined |
+| tieng_anh   | Tiếng Anh   | English |
+| tieng_phap  | Tiếng Pháp  | French |
+| tieng_nga   | Tiếng Nga   | Russian |
+| tieng_trung | Tiếng Trung | Chinese |
 
 Missing-in-string → `NULL` in DB (student didn't take that subject).
 
@@ -51,7 +64,7 @@ One shared lib + three thin parsers, not one parser with flags. Each dataset's q
 
 ## Overflow-sheet gotcha
 
-The old `.xls` binary format caps at 65,536 rows per sheet. Hà Nội and HCM exceed that in the baotintuc export, so Excel auto-splits the overflow into `Sheet2`. **Only reading `Sheet1` silently drops 13,720 students** (Hà Nội +7,275, HCM +6,445).
+The old `.xls` binary format caps at 65,536 rows per sheet. Hanoi and Ho Chi Minh City exceed that in the baotintuc export, so Excel auto-splits the overflow into `Sheet2`. **Only reading `Sheet1` silently drops 13,720 students** (Hanoi +7,275, HCM +6,445).
 
 The audit `node scripts/audit-row-counts.js` catches this by comparing source-row-count (across all sheets) to DB-row-count.
 
diff --git a/2017/docs/system-architecture.md b/2017/docs/system-architecture.md
index 5a5eb48..aa290cb 100644
--- a/2017/docs/system-architecture.md
+++ b/2017/docs/system-architecture.md
@@ -58,32 +58,32 @@ Each dataset had a different quirk. Rather than one mega-parser with mode flags,
 
 | Dataset | Quirk | Mitigation |
 |---|---|---|
-| data/ (baotintuc .xls) | Hà Nội + HCM overflow past the 65,536 row-per-sheet .xls limit | Iterate all `wb.SheetNames` |
+| data/ (baotintuc .xls) | Hanoi + HCM overflow past the 65,536 row-per-sheet .xls limit | Iterate all `wb.SheetNames` |
 | data-old/ (xlsx) | Single-sheet always; one bogus header row (`SOBAODANH`/`HO_TEN`) leaked into an earlier DB | Strict numeric-SBD guard rejects the leak |
 | data-old2/ (xlsx) | HCM overflow + many blank trailing rows | Multi-sheet walk + blank-row pre-filter |
 
 Shared concerns (regex, schema, `toAscii`, header detection) live in `scripts/build-lib.js`.
 
-## Admission blocks (khối thi)
+## Admission blocks
 
-`src/lib/admission-blocks.js` lists all 49 official 2017 blocks computable from our schema (A00–A11, B00–B08, C00–C20, D01–D15). Each entry is `{ code, subjects: [3 keys], label }`.
+Vietnamese universities admit students based on 3-subject combinations called "admission blocks" (khối thi). `src/lib/admission-blocks.js` lists all 49 official 2017 blocks computable from our schema (A00–A11, B00–B08, C00–C20, D01–D15). Each entry is `{ code, subjects: [3 keys], label }`.
 
 `computeBlocks(student)` returns only blocks where the student has all 3 subject scores, sorted by total desc. Used by the student detail card.
 
-The SQL preset "Top 10 điểm khối cao nhất – Long An" materialises all 49 blocks as a `UNION ALL` CTE, picks each student's best via `ROW_NUMBER() OVER (PARTITION BY so_bao_danh ORDER BY s DESC, k)`, then ranks across students.
+The SQL preset "Top 10 best-block in Long An" materialises all 49 blocks as a `UNION ALL` CTE, picks each student's best block via `ROW_NUMBER() OVER (PARTITION BY so_bao_danh ORDER BY s DESC, k)`, then ranks across students.
 
 ## Score tiers (UI coding)
 
 6-level TFT rarity ladder (white → green → blue → purple → gold → prismatic). Defined in `scoreTier()` in `src/lib/admission-blocks.js`.
 
-| Tier | Range | Label |
-|---|---|---|
-| common    | ≤ 1   | Điểm liệt |
-| uncommon  | < 5   | Chưa đạt |
-| rare      | 5–6.5 | Trung bình |
-| epic      | 6.5–8 | Khá |
-| legendary | 8–9   | Giỏi |
-| prismatic | 9–10  | Xuất sắc |
+| Tier | Range | UI label (Vietnamese) | English |
+|---|---|---|---|
+| common    | ≤ 1   | Điểm liệt  | Disqualifying |
+| uncommon  | < 5   | Chưa đạt   | Below passing |
+| rare      | 5–6.5 | Trung bình | Average |
+| epic      | 6.5–8 | Khá        | Good |
+| legendary | 8–9   | Giỏi       | Very good |
+| prismatic | 9–10  | Xuất sắc   | Excellent |
 
 Color + icon + text label — never color-only.