revernomad17/arma-modlist-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Vietnamese localization to GUI

Browse Source 
Introduces a two-language (EN/VI) i18n system with hot-swap support.
All ~160 user-facing strings are centralised in gui/locales.py; views
retranslate in-place on language switch without restarting the app.

- gui/locales.py: new file — _EN/_VI dicts, t() lookup, set_language(),
  get_language(); assert guard ensures EN/VI key parity
- gui/app.py: switch_language(), _apply_startup_language(),
  _save_language_pref(), _rebuild_nav_labels(); language stored in
  config.json under ui.language; pipeline step headers and run_tool
  status lines translated
- gui/views/settings.py: Language dropdown card (English / Tiếng Việt)
- gui/views/dashboard.py: all strings via t(); static header widgets
  stored and retranslated in refresh()
- gui/views/mods.py: all strings via t(); _STATUS dict built at call
  time so server status labels update on language switch
- gui/views/tools.py: all strings via _translatable registry; tab names
  and segmented-button values kept in English (CTkTabview constraint)
- gui/views/logs.py: title + Copy/Clear buttons stored, retranslated
- gui/wizard.py: all 3 pages fully translated
- docs/huong-dan-su-dung.md: full Vietnamese user guide
- CLAUDE.md: documents localization architecture and constraints
This commit is contained in:
Tran G. (Revernomad) Khoa
2026-04-08 16:58:41 +07:00
parent 4478ec3cab
commit 903cd366e2
10 changed files with 1226 additions and 230 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
docs/huong-dan-su-dung.md Normal file
View File

@@ -0,0 +1,379 @@
# Hướng dẫn sử dụng Arma Mod Manager
Tài liệu này dành cho người dùng **chưa biết gì** về dự án. Bạn không cần kiến thức lập trình để sử dụng ứng dụng này.
---
## Mục lục
1. [Arma Mod Manager là gì?](#1-arma-mod-manager-là-gì)
2. [Yêu cầu hệ thống](#2-yêu-cầu-hệ-thống)
3. [Khởi động lần đầu — Trình thiết lập](#3-khởi-động-lần-đầu--trình-thiết-lập)
4. [Giao diện chính](#4-giao-diện-chính)
5. [Tổng quan (Dashboard) — Quy trình cơ bản](#5-tổng-quan-dashboard--quy-trình-cơ-bản)
6. [Danh sách Mod](#6-danh-sách-mod)
7. [Công cụ nâng cao](#7-công-cụ-nâng-cao)
8. [Nhật ký (Logs)](#8-nhật-ký-logs)
9. [Cài đặt](#9-cài-đặt)
10. [Đổi sang giao diện tiếng Việt](#10-đổi-sang-giao-diện-tiếng-việt)
11. [Xử lý sự cố thường gặp](#11-xử-lý-sự-cố-thường-gặp)
12. [Bảng thuật ngữ](#12-bảng-thuật-ngữ)
---
## 1. Arma Mod Manager là gì?
**Arma Mod Manager** là công cụ giúp bạn tải về và quản lý các mod cho **Arma 3 Server** từ một máy chủ lưu trữ riêng (Caddy server). Thay vì tải từng mod thủ công, bạn chỉ cần:
1. Xuất danh sách mod từ Arma 3 Launcher dưới dạng tệp HTML (gọi là **preset**)
2. Chọn preset trong ứng dụng
3. Nhấn nút **Chạy toàn bộ quy trình**
Ứng dụng sẽ tự động:
- Đọc danh sách mod từ các preset
- So sánh, tìm mod dùng chung và mod riêng giữa các preset
- Tải mod từ máy chủ về máy tính của bạn
- Tạo liên kết (junction/symlink) để Arma 3 Server nhận ra các mod
---
## 2. Yêu cầu hệ thống
| Yêu cầu | Thông tin |
|---------|-----------|
| Hệ điều hành | Windows 10/11 (64-bit) |
| Python | 3.9 trở lên |
| Arma 3 Server | Đã cài đặt trên máy |
| Kết nối mạng | Cần thiết để tải mod từ máy chủ |
**Cài đặt thư viện cần thiết** (chỉ cần làm một lần):
Mở Command Prompt, điều hướng tới thư mục ứng dụng, chạy:
```
pip install -r requirements.txt
```
---
## 3. Khởi động lần đầu — Trình thiết lập
Khi khởi động ứng dụng lần đầu (chưa có tệp `config.json`), cửa sổ **Thiết lập** sẽ tự động hiện ra gồm 3 bước:
### Bước 1 / 3 — Kết nối máy chủ
![Bước 1](placeholder)
| Trường | Mô tả |
|--------|-------|
| **URL máy chủ** | Địa chỉ đầy đủ của máy chủ Caddy lưu mod, ví dụ: `https://mods.example.com/` |
| **Tên đăng nhập** | Tài khoản được cấp bởi người quản trị máy chủ |
| **Mật khẩu** | Mật khẩu tương ứng |
- Nhấn **Kiểm tra kết nối** để xác nhận thông tin trước khi tiếp tục.
- `✓ Đã kết nối` — thành công, nhấn **Tiếp theo →**
- `✗ HTTP 401` — sai tên đăng nhập hoặc mật khẩu
- `✗ ...` — lỗi mạng hoặc URL sai
### Bước 2 / 3 — Thư mục Arma 3 Server
Nhấn **Duyệt** để chọn thư mục gốc của Arma 3 Server trên máy tính (thư mục chứa `arma3server.exe`).
> Ví dụ: `C:\servers\arma3`
Các thư mục khác (downloads, presets) sẽ tự động được tạo bên cạnh ứng dụng.
### Bước 3 / 3 — Xem lại & Lưu
Kiểm tra thông tin đã nhập rồi nhấn **Lưu & Mở**. Ứng dụng sẽ lưu cấu hình và mở giao diện chính.
> **Mẹo:** Để mở lại trình thiết lập bất cứ lúc nào, vào **Cài đặt → Mở trình thiết lập**.
---
## 4. Giao diện chính
Giao diện gồm thanh điều hướng bên trái và khu vực nội dung bên phải.
```
┌─────────────────┬──────────────────────────────────┐
│ Arma Mod │ │
│ Manager │ Khu vực nội dung │
│─────────────────│ (thay đổi theo mục chọn) │
│ Tổng quan │ │
│ Danh sách Mod │ │
│ Công cụ │ │
│ Nhật ký │ │
│ Cài đặt │ │
└─────────────────┴──────────────────────────────────┘
```
| Mục | Chức năng |
|-----|-----------|
| **Tổng quan** | Chọn preset, xem trạng thái pipeline, chạy quy trình tải mod |
| **Danh sách Mod** | Xem tất cả mod theo nhóm, trạng thái tải/liên kết/máy chủ |
| **Công cụ** | Các tác vụ bảo trì nâng cao |
| **Nhật ký** | Xem toàn bộ output của pipeline và công cụ |
| **Cài đặt** | Cấu hình giao diện, ngôn ngữ, mở lại trình thiết lập |
---
## 5. Tổng quan (Dashboard) — Quy trình cơ bản
Đây là trang chính bạn sẽ dùng thường xuyên nhất.
### 5.1 Thêm tệp preset
**Preset** là tệp HTML xuất từ Arma 3 Launcher chứa danh sách mod bạn đang dùng.
**Cách xuất preset từ Arma 3 Launcher:**
1. Mở Arma 3 Launcher
2. Vào tab **Mods**
3. Nhấn **Preset** → **Export to HTML**
4. Lưu tệp vào máy tính
**Thêm preset vào ứng dụng:**
1. Ở mục **Tệp Preset**, nhấn **+ Thêm tệp Preset**
2. Chọn tệp `.html` vừa xuất
3. Tệp sẽ xuất hiện trong danh sách với ô tick
### 5.2 Chọn preset để xử lý
- **Tick** vào các preset bạn muốn so sánh (cần ít nhất **2 preset**)
- Nhấn **Tất cả** để chọn tất cả, hoặc **Bỏ chọn** để bỏ hết
- Nhãn `Đã chọn X / Y` cho biết số lượng đã chọn:
- Màu xanh: đã chọn đủ (≥ 2)
- Màu vàng: mới chọn 1
- Màu đỏ: chưa chọn
### 5.3 Trạng thái Pipeline
Cột bên phải hiển thị 4 bước của quy trình:
| Bước | Mô tả | Dấu hiệu hoàn thành |
|------|-------|-------------------|
| Phân tích preset | Đọc danh sách mod từ tệp HTML | Có ≥ 2 preset được chọn |
| So sánh preset | Tìm mod chung và riêng | Tệp `comparison.json` tồn tại |
| Tải mod | Tải tệp mod từ máy chủ | Có thư mục mod trong `downloads/` |
| Liên kết với Arma | Tạo junction tới thư mục Arma 3 | Thư mục Arma 3 Server tồn tại |
Biểu tượng `✓` (xanh) = đã xong, `○` (xám) = chưa xong.
### 5.4 Chạy toàn bộ quy trình
1. Đảm bảo đã chọn ít nhất 2 preset
2. Nhấn **▶ Chạy toàn bộ quy trình**
3. Ứng dụng tự động chuyển sang tab **Nhật ký** và hiển thị tiến trình
4. Chờ cho đến khi thấy dòng `✓ Pipeline complete.` (hoặc tiếng Việt: `✓ Hoàn thành`)
> **Lưu ý:** Quá trình này có thể mất vài phút đến hàng giờ tùy số lượng và kích thước mod.
---
## 6. Danh sách Mod
Trang này hiển thị tất cả mod được nhóm theo preset (tab).
### Các tab nhóm
- **shared (X)** — Mod có mặt trong **tất cả** preset đã chọn
- **[tên preset] (X)** — Mod chỉ có trong preset đó
Nhấn vào tên tab để chuyển nhóm.
### Các cột thông tin
| Cột | Ý nghĩa |
|-----|---------|
| **Tên Mod** | Tên mod theo danh sách preset |
| **Đã tải** | `✓` = đã có trong thư mục downloads · `✗` = chưa tải |
| **Đã liên kết** | `✓` = đã tạo junction tới Arma 3 · `✗` = chưa · `—` = chưa tải nên không liên kết được |
| **Trạng thái máy chủ** | Xem bên dưới |
### Trạng thái máy chủ
Nhấn nút **☁ Kiểm tra cập nhật** để kiểm tra từng mod với máy chủ:
| Trạng thái | Ý nghĩa |
|-----------|---------|
| `✓ Đã cập nhật` | Tệp local khớp với máy chủ |
| `⚠ X tệp cũ` | Có X tệp cần cập nhật, nhấn **Cập nhật** ở cuối hàng |
| `Không có trên máy chủ` | Mod này không tồn tại trên máy chủ |
| `—` | Mod chưa được tải về |
| `✗ Lỗi` | Không thể kiểm tra (lỗi mạng) |
### Tìm kiếm mod
Gõ vào ô **Tìm kiếm:** để lọc mod theo tên trong tab đang xem.
---
## 7. Công cụ nâng cao
Trang **Công cụ** có 5 tab phụ cho các tác vụ bảo trì. Mỗi tab đều có nút chạy ở góc phải phía dưới, output hiển thị trong **Nhật ký**.
### Tab "Check Names" — Kiểm tra tên thư mục
Quét thư mục mod trên máy tính và so sánh với máy chủ. Báo cáo các vấn đề:
| Vấn đề | Ý nghĩa |
|--------|---------|
| `MISMATCH` | Tên thư mục local khác với tên trên máy chủ |
| `NOT_ON_SERVER` | Thư mục local không tìm thấy trên máy chủ |
| `ID_COLLISION` | Tệp `meta.cpp` chứa Steam ID sai |
**Tùy chọn:**
- `--fix`: Tự động đổi tên thư mục sai → Dùng cẩn thận, sẽ di chuyển tệp
- `--fix-ids`: Tự động sửa Steam ID trong `meta.cpp` → Dùng cẩn thận, sẽ ghi đè tệp
### Tab "Update Mods" — Cập nhật mod
Tải lại các tệp mod có kích thước khác với bản trên máy chủ.
- **Nhóm**: Chọn `Tất cả nhóm` hoặc một nhóm cụ thể
- **Thư mục mod**: Nhập tên thư mục cụ thể (ví dụ `@ace`) nếu muốn cập nhật một mod
- **--force**: Tải lại **tất cả** tệp bất kể kích thước — cẩn thận với mod nặng
### Tab "Link Mods" — Quản lý liên kết
Tạo hoặc xóa junction giữa thư mục `downloads/` và thư mục Arma 3.
| Lệnh | Chức năng |
|------|-----------|
| **Status** | Hiển thị trạng thái liên kết hiện tại |
| **Link** | Tạo junction còn thiếu |
| **Unlink** | Xóa junction (tệp mod **KHÔNG** bị xóa) |
> **Lưu ý:** Phải chọn một nhóm cụ thể trước khi chạy Unlink.
### Tab "Sync Missing" — Đồng bộ mod thiếu
Thử tải lại các mod bị thiếu từ lần chạy pipeline trước. Hữu ích khi máy chủ vừa bổ sung mod mới sau khi bạn đã chạy pipeline.
### Tab "Report Missing" — Báo cáo mod thiếu
Kiểm tra mod nào trong `comparison.json` chưa có trên máy chủ và lưu báo cáo vào `missing_report.json`. Dùng để theo dõi mod cần yêu cầu admin bổ sung.
---
## 8. Nhật ký (Logs)
Trang này hiển thị toàn bộ output khi chạy pipeline hoặc công cụ.
- **Sao chép**: Copy toàn bộ nội dung nhật ký vào clipboard
- **Xóa**: Xóa sạch nội dung nhật ký
Output được giữ nguyên khi bạn chuyển sang trang khác và quay lại.
**Ký hiệu trong log:**
- `✓` — bước hoàn thành thành công
- `✗` — có lỗi xảy ra
- `SKIP` — bỏ qua (ví dụ preset không được chọn)
---
## 9. Cài đặt
### Cấu hình máy chủ & đường dẫn
Nhấn **Mở trình thiết lập** để thay đổi URL máy chủ, tài khoản, hoặc thư mục Arma 3.
### Giao diện
Chọn chế độ hiển thị: **Dark** (tối), **Light** (sáng), hoặc **System** (theo hệ thống).
### Ngôn ngữ
Xem phần [10. Đổi sang giao diện tiếng Việt](#10-đổi-sang-giao-diện-tiếng-việt).
### Cấu hình hiện tại
Hiển thị các đường dẫn đang dùng: URL máy chủ, thư mục Arma, thư mục downloads, thư mục presets.
---
## 10. Đổi sang giao diện tiếng Việt
1. Nhấn **Cài đặt** ở thanh bên trái
2. Cuộn xuống đến mục **Ngôn ngữ**
3. Chọn **Tiếng Việt** từ danh sách thả xuống
4. Giao diện sẽ chuyển sang tiếng Việt ngay lập tức — không cần khởi động lại
Để chuyển lại tiếng Anh, chọn **English** trong cùng mục đó.
> Lựa chọn ngôn ngữ được lưu vào `config.json` và sẽ được ghi nhớ cho lần khởi động tiếp theo.
---
## 11. Xử lý sự cố thường gặp
### Không kết nối được máy chủ
**Triệu chứng:** Wizard hiển thị `✗ HTTP 401` hoặc `✗ [lỗi kết nối]`
**Kiểm tra:**
- URL có bắt đầu bằng `https://` không?
- URL có dấu `/` ở cuối không? (ví dụ `https://mods.example.com/`)
- Tên đăng nhập và mật khẩu có đúng không? (kiểm tra phân biệt hoa thường)
- Máy tính có kết nối internet không?
- Máy chủ có đang hoạt động không? (hỏi admin)
### Pipeline chạy xong nhưng không tải được mod
**Triệu chứng:** Log hiển thị `missing from server` hoặc `NOT_ON_SERVER`
**Giải thích:** Mod tồn tại trong preset nhưng chưa có trên máy chủ.
**Xử lý:**
- Vào **Công cụ → Report Missing** để tạo báo cáo
- Gửi báo cáo cho admin để bổ sung mod
- Sau khi mod được thêm, vào **Công cụ → Sync Missing** để tải về
### Mod tải về rồi nhưng không liên kết được
**Triệu chứng:** Cột "Đã tải" là `✓` nhưng "Đã liên kết" là `✗`
**Xử lý:**
- Vào **Công cụ → Link Mods**, chọn lệnh **Link**, chọn nhóm tương ứng, nhấn **Tạo liên kết**
- Nếu vẫn lỗi, kiểm tra quyền ghi vào thư mục Arma 3 (có thể cần chạy ứng dụng với quyền Administrator)
### Tên thư mục mod bị sai
**Triệu chứng:** Arma 3 Server không nhận ra mod dù đã tạo junction
**Xử lý:**
- Vào **Công cụ → Check Names**, nhấn **Chạy kiểm tra tên**
- Xem log để tìm dòng `MISMATCH`
- Nếu muốn tự động sửa, tick vào **Tự động sửa tên thư mục** rồi chạy lại
### Ứng dụng không khởi động / lỗi Python
**Triệu chứng:** Màn hình đen nháy tắt ngay
**Xử lý:**
- Mở Command Prompt, chạy `python gui.py` để xem thông báo lỗi
- Đảm bảo đã cài đủ thư viện: `pip install -r requirements.txt`
- Kiểm tra phiên bản Python: `python --version` (cần ≥ 3.9)
---
## 12. Bảng thuật ngữ
| Thuật ngữ | Giải thích |
|-----------|------------|
| **Preset** | Tệp HTML xuất từ Arma 3 Launcher chứa danh sách mod |
| **Pipeline** | Chuỗi 4 bước tự động: phân tích → so sánh → tải → liên kết |
| **Junction / Symlink** | Liên kết thư mục ảo — Arma 3 thấy mod trong thư mục của mình nhưng tệp thực sự nằm ở `downloads/` |
| **Shared mods** | Mod xuất hiện trong tất cả preset đã chọn |
| **Unique mods** | Mod chỉ có trong một preset cụ thể |
| **Caddy server** | Phần mềm máy chủ lưu trữ tệp mod (HTTP file server) |
| **meta.cpp** | Tệp metadata của mỗi mod, chứa `publishedid` (Steam Workshop ID) |
| **Steam ID / publishedid** | Mã định danh mod trên Steam Workshop |
| **comparison.json** | Tệp kết quả so sánh preset, lưu danh sách mod theo nhóm |
| **missing_report.json** | Báo cáo mod có trong preset nhưng chưa có trên máy chủ |
| **downloads/** | Thư mục chứa tệp mod đã tải về |
| **config.json** | Tệp cấu hình lưu thông tin máy chủ và đường dẫn |
---
*Phiên bản tài liệu: 2026-04. Nếu có vấn đề, liên hệ người quản trị máy chủ.*