Add mod documentation in seven languages

docs/en.md

@@ -0,0 +1,69 @@
+# 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.