71 lines
5.1 KiB
Markdown
71 lines
5.1 KiB
Markdown
# Locale Atlas — mọi khóa dịch của mọi mod
|
||
|
||
Locale Atlas vẽ ra phần bản địa hóa của mọi mod đã cài: mỗi mod khai báo những khóa nào ở mỗi ngôn ngữ, các khóa được dùng ở đâu — kịch bản, mã C#, dữ liệu JSON, bộ sưu tập, cảnh, manifest — và cái gì không ổn. Nó tách thành hai loại vấn đề:
|
||
|
||
- **lỗi** — văn bản hỏng: một khóa được dùng nhưng không khai báo ở đâu cả, một giá trị rỗng, một khóa có hai giá trị khác nhau trong cùng một mod, một tệp mà bộ nạp không đọc được, mã hóa hỏng;
|
||
- **cảnh báo** — chỗ thiếu bản dịch: một khóa còn thiếu ở ngôn ngữ nào đó. Khi đó game sẽ quay về một ngôn ngữ có sẵn đoạn chữ, nên chẳng có gì vỡ; cảnh báo cho biết cần thêm dòng nào.
|
||
|
||
## Cách chạy
|
||
|
||
```text
|
||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||
```
|
||
|
||
Nó đọc mọi mod đã cài, ghi `report.md` và `report.json` vào thư mục `--locale-out`, ghi một dòng tổng kết vào log và thoát với mã 1 nếu có lỗi. Trong test runner, nó là phép kiểm thử `locale_atlas`. Phần chữ của `report.md` viết bằng tiếng Nga; phần mô tả vấn đề viết bằng tiếng Anh.
|
||
|
||
Một lần chạy sạch với các mod hiện có:
|
||
|
||
```text
|
||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||
```
|
||
|
||
## Một chỗ thiếu và một chỗ hỏng, đặt cạnh nhau
|
||
|
||
Để thấy cả hai loại, người ta sửa hai chỗ trong mod của bản mẫu tiểu thuyết cho đúng một lần chạy.
|
||
|
||
**Một bản dịch bị thiếu.** Dòng tiếng Tây Ban Nha của câu hỏi thị trấn đã bị xóa khỏi `locale/scenarios_es.properties`. Atlas báo một cảnh báo kèm dòng cần thêm:
|
||
|
||
```text
|
||
| warning | `my_novel_game` | `my_novel/town/prompt` | es | `locale/scenarios_en.properties:2` | declared in en, ja, ko, ru, vi, zh but not in 'es' | `locale/scenarios_es.properties: my_novel/town/prompt = Where to go?` |
|
||
```
|
||
|
||
Người chơi tiếng Tây Ban Nha vẫn thấy một câu hỏi — bằng một ngôn ngữ khác — nên đây là chỗ thiếu, không phải chỗ hỏng.
|
||
|
||
**Một tham chiếu bị hỏng.** Trong kịch bản của thị trấn, khóa của một câu trả lời bị gõ nhầm chính tả:
|
||
|
||
```scenario
|
||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||
```
|
||
|
||
Giờ khóa này được dùng nhưng không được khai báo trong tệp nào, và Atlas báo một **lỗi** cho mỗi ngôn ngữ, chỉ thẳng vào dòng kịch bản:
|
||
|
||
```text
|
||
| error | `my_novel_game` | `my_novel/town/opt_baar` | ru | `scenarios/my_novel_town.scenario:7` | referenced (scenario, 1×) but declared in no locale file | `locale/scenarios_ru.properties: my_novel/town/opt_baar = …` |
|
||
```
|
||
|
||
Lần chạy ấy kết thúc với `7 error(s)` và thất bại. Gõ lại khóa là `opt_bar` và trả lại dòng tiếng Tây Ban Nha thì mọi thứ sạch sẽ trở lại.
|
||
|
||
## Báo cáo chứa gì
|
||
|
||
- **Mã hóa** — mỗi tệp bản địa hóa kèm mã hóa, kiểu xuống dòng và số khóa; các vấn đề như không phải UTF-8, U+FFFD, ký tự điều khiển, mojibake hoặc xuống dòng chỉ có CR đều là lỗi.
|
||
- **Các khóa cần chú ý** — mỗi khóa một dòng: một dấu cho mỗi ngôn ngữ (`✓` đã khai báo, `∅` rỗng, `—` thiếu), khai báo ở đâu, ai tham chiếu đến nó, và cái gì không ổn.
|
||
- **Vấn đề** — lỗi và cảnh báo kèm mod, khóa, ngôn ngữ, chỗ cần sửa và dòng chính xác cần thêm.
|
||
|
||
Các cảnh báo khác: BOM, kiểu xuống dòng trộn lẫn, cùng một khóa xuất hiện hai lần với cùng một giá trị, một mod chỉ ghi đè khóa ở một số ngôn ngữ, trình giữ chỗ `{0}` không khớp giữa các ngôn ngữ, chữ Cyrillic trong văn bản tiếng Anh, `???` trong một giá trị, một mod thiếu `mod_<id>_name` và `mod_<id>_desc` của nó.
|
||
|
||
## Khóa đến từ đâu
|
||
|
||
- các dòng `.scenario` có `key=`; bản dịch của văn bản kịch bản đi vào `locale/scenarios_<lang>.properties`;
|
||
- `Translate("…")`, `Tr("…")` và `Locale = "…"` trong C#;
|
||
- các trường văn bản của dữ liệu JSON (`Name`, `Description`, `title`…), `"@key"` trong bộ sưu tập;
|
||
- `text` và `tooltip_text` được tự động dịch trong các cảnh `.tscn`;
|
||
- `mod_<id>_name` và `mod_<id>_desc` của manifest.
|
||
|
||
Tệp bản địa hóa phải nằm ngay trong thư mục `locale/` của mod; tệp trong thư mục con không được game đọc và được tính là lỗi.
|
||
|
||
## Nếu có gì đó không ổn
|
||
|
||
1. **Một lỗi cho khóa mà bạn thấy chạy tốt trong tiếng Anh.** Dòng kịch bản tự mang văn bản của nó, nên nó vẫn có thể đọc đúng ở một ngôn ngữ trong khi bản dịch của khóa gõ nhầm không tìm thấy ở đâu cả.
|
||
2. **Hàng trăm cảnh báo.** Đó là những chỗ thiếu bản dịch; mỗi dòng đều cho biết tệp và dòng cần thêm.
|
||
|