70 lines
4.1 KiB
Markdown
70 lines
4.1 KiB
Markdown
# Locale Atlas — every translation key of every mod
|
||
|
||
The Locale Atlas maps the localization of all installed mods: which keys each mod declares in each language, where the keys are used — scenarios, C# code, JSON data, collections, scenes, manifests — and what is wrong. It separates two kinds of problems:
|
||
|
||
- **errors** — broken text: a key that is used but declared nowhere, an empty value, one key with two different values in one mod, a file the loader will not read, a broken encoding;
|
||
- **warnings** — translation gaps: a key missing in some language. The game then falls back to a language that has the text, so nothing breaks; the warning says which line to add.
|
||
|
||
## Running it
|
||
|
||
```text
|
||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||
```
|
||
|
||
It reads every installed mod, writes `report.md` and `report.json` into the `--locale-out` folder, logs a summary line and exits with 1 if there are errors. The test runner has it as the `locale_atlas` test. The text of `report.md` is written in Russian; the problem descriptions are in English.
|
||
|
||
A clean run of the current mods:
|
||
|
||
```text
|
||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||
```
|
||
|
||
## A gap and a break, side by side
|
||
|
||
To show both kinds, two changes were made to the novel template's mod for one run.
|
||
|
||
**A missing translation.** The Spanish line of the town's question was removed from `locale/scenarios_es.properties`. The atlas reports a warning with the line to add:
|
||
|
||
```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?` |
|
||
```
|
||
|
||
A Spanish player still sees a question — in another language — so this is a gap, not a breakage.
|
||
|
||
**A broken reference.** In the town's scenario the key of an answer was misspelt:
|
||
|
||
```scenario
|
||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||
```
|
||
|
||
Now the key is used but declared in no file, and the atlas reports an **error** for each language, pointing at the scenario line:
|
||
|
||
```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 = …` |
|
||
```
|
||
|
||
The run ended with `7 error(s)` and failed. With the key spelt `opt_bar` again and the Spanish line back, it is clean.
|
||
|
||
## What the report contains
|
||
|
||
- **Encodings** — every locale file with its encoding, line endings and number of keys; problems such as non-UTF-8, U+FFFD, control characters, mojibake or CR-only line breaks are errors.
|
||
- **Keys that need attention** — one row per key: a mark per language (`✓` declared, `∅` empty, `—` missing), where it is declared, who refers to it, and what is wrong.
|
||
- **Problems** — errors and warnings with the mod, key, language, the place to fix and the exact line to add.
|
||
|
||
Other warnings: a BOM, mixed line endings, the same key twice with the same value, a mod overriding a key only in some languages, `{0}` placeholders that differ between languages, Cyrillic in English text, `???` in a value, a mod without its `mod_<id>_name` and `mod_<id>_desc`.
|
||
|
||
## Where keys come from
|
||
|
||
- `.scenario` lines with `key=`; translations of scenario text go to `locale/scenarios_<lang>.properties`;
|
||
- `Translate("…")`, `Tr("…")` and `Locale = "…"` in C#;
|
||
- text fields of JSON data (`Name`, `Description`, `title`…), `"@key"` in collections;
|
||
- auto-translated `text` and `tooltip_text` in `.tscn` scenes;
|
||
- the manifest's `mod_<id>_name` and `mod_<id>_desc`.
|
||
|
||
Locale files must be directly in a mod's `locale/` folder; a file in a subfolder is not read by the game and is an error.
|
||
|
||
## If something goes wrong
|
||
|
||
1. **An error for a key you see working in English.** The scenario line carries its own text, so the line may still read correctly in one language while the translations of the misspelt key are found nowhere.
|
||
2. **Hundreds of warnings.** They are translation gaps; each row gives the file and the line to add.
|