Multi-Game Localization Tool

Công cụ desktop hỗ trợ Việt hóa nhiều game bằng một lõi Gemini/API key dùng chung, với màn hình và quy trình riêng cho từng game.

• Sid Meier's Civilization VII: xuất, kiểm tra, đồng bộ, dịch và triển khai localization .xml/.vtt.
• Legend of Heroes Three Kingdoms: dịch file XUnity AutoTranslator từ tiếng Trung sang tiếng Việt theo bối cảnh lịch sử Tam Quốc; JSON Pipeline quét JSON game chỉ đọc, dịch incremental vào SQLite rồi Preview + Apply vào file chính.

Ứng dụng luôn xem trước thay đổi trước khi ghi file, backup tự động, chạy nhiều API key Gemini song song (1 request/key; key thừa làm dự phòng khi hết quota) và tách cache theo profile game.

Tính năng chính

• Pipeline 5 bước — Export → Kiểm tra & Thống kê → Đồng bộ → Dịch → Deploy, có gate logic giữa các bước
• Dry-run / Apply — Xem trước thay đổi trước khi ghi vào mod hoặc thư mục game
• Dịch AI (Gemini) — Nhiều API key chạy song song (luồng = min(key, batch)), key thừa dự phòng khi hết quota, fallback model, cache dịch
• Glossary — Chuẩn hóa thuật ngữ EN → VN trong prompt dịch
• Tra cứu — Tìm tag/file trong dữ liệu localization
• Báo cáo & Backup Center — Lịch sử job, QA issues, khôi phục backup
• An toàn dữ liệu — Backup trước khi ghi, ghi atomic, invalidate bước phía sau khi restore
• Bảo mật credential — API key lưu trong Windows Credential Manager, không nằm trong file cấu hình
• Cập nhật trong app — Kiểm tra GitHub Releases, xác nhận rồi cài installer (kèm engine dịch); không cài khi đang có job
• Đa game — Sidebar, prompt, parser và cache tách theo profile; lõi gọi Gemini được dùng chung
• Tam Quốc Trung → Việt — Dịch lại toàn bộ cặp source=target, giữ cú pháp XUnity, duyệt diff rồi mới backup và áp dụng
• JSON Pipeline (Tam Quốc) — Quét JSON chỉ đọc, dịch incremental vào SQLite, Preview + Apply vào AutoGeneratedTranslations.txt, backup/restore trên trang JSON; một job toàn app

Legend of Heroes Three Kingdoms

Mở nhóm game tương ứng trong sidebar và chọn Dịch:

1. Chọn file bản dịch XUnity của game.
2. Kiểm tra encoding, số dòng, entry và cảnh báo cú pháp.
3. Quản lý Glossary Tam Quốc; có thể merge/replace, thao tác hàng loạt và export schema v2 hoặc map phẳng. Mọi lần lưu active glossary làm QA preview hiện tại thành stale.
4. Chạy dịch (chỉ câu Trung mới gọi API), rồi duyệt diff từng trang: chọn/bỏ chọn, sửa, hoặc dịch lại từng câu / các dòng đã chọn.
5. Xử lý lỗi QA blocking (token/regex/cấu trúc/glossary khóa); cảnh báo chất lượng vẫn cho phép tiếp tục.
6. Bấm Áp dụng để xác thực revision/fingerprint, backup và ghi file atomic.
7. Dùng Báo cáo (tab Backup Center) để restore; phải chọn/inspect đúng file nguồn của backup và ứng dụng luôn tạo safety backup trước khi khôi phục.

File gốc không bị sửa trong lúc gọi API. Comment, dòng trống, regex, escape \=, BOM và kiểu xuống dòng được bảo toàn.

Artifact preview Legend dùng schema v2. Preview v1 vẫn đọc được nhưng phải chạy lại QA trước khi Apply. Apply luôn đối chiếu semantic glossary hash và chạy fresh QA trên output hiệu lực, kể cả các dòng bị bỏ chọn.

Luồng pipeline

Export → Inspect → Sync (dry-run → apply) → Translate → Deploy (dry-run → apply)

Bước	Mô tả ngắn
Export	Trích xuất file localization từ bản game EN
Inspect	Thống kê, so sánh EN vs mod VN (english-only, vietnamese-only, …)
Sync	Đồng bộ cấu trúc mod VN theo bản export (dry-run rồi apply + backup)
Translate	Dịch chuỗi còn thiếu qua Gemini API (có cache & QA)
Deploy	Copy bản dịch từ mod sang thư mục game (dry-run rồi apply)

Lần đầu mở app, Thiết lập nhanh sẽ yêu cầu cấu hình:

• Thư mục game Civilization VII
• Thư mục export (bản EN)
• Thư mục mod tiếng Việt
• Ít nhất một API key Gemini (cho bước Dịch)

Kiến trúc

Thành phần	Công nghệ
Giao diện	React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui
Shell desktop	Tauri 2 (Rust) — orchestrator, IPC, credential, job lifecycle
Engine xử lý	Python (engine/translate_tool/) — sidecar localization-engine
Giao tiếp	JSONL protocol v1 giữa Rust orchestrator và Python engine

Yêu cầu hệ thống

Chạy bản cài đặt (end user)

• Windows 10/11 x64
• Civilization VII đã cài đặt
• API key Google Gemini (cho bước dịch)

Phát triển / build từ source

• Node.js 22+ (CI dùng 24)
• Rust (stable) + MSVC toolchain
• Python 3.10+ (khuyến nghị 3.13 cho build sidecar)
• PowerShell

Bảo mật

• Credential Gemini được lưu qua Windows Credential Manager
• CSP chặt trong Tauri config — app không load script ngoài

Liên hệ & đóng góp

Mã nguồn: https://github.com/nguyentung164/Multi-Game-Localization-Tool

Báo lỗi hoặc đề xuất tính năng qua GitHub Issues.

---

Dự án cộng đồng, tối ưu cho quy trình Việt hóa nhiều game.