mod_locale_atlas/docs/en.md

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

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:

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:

| 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:

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:

| 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.