diff --git a/Furious/Externals/AGENTS.md b/Furious/Externals/AGENTS.md new file mode 100644 index 00000000..9dbd80dc --- /dev/null +++ b/Furious/Externals/AGENTS.md @@ -0,0 +1,56 @@ +# Translation catalog guidance + +These instructions apply to `Furious/Externals/` and refine the repository-level generated-artifact and translation +rules. + +## Generated catalog ownership + +- `GenTranslation.py` is generated by the repository-root `Translation.py`; do not hand-maintain catalog entries for + routine source changes. +- Add or change extracted source strings at their call sites, run the translation generator for every supported + language, review the translations, and regenerate the catalog. +- If generated record structure or key ordering needs correction, fix `Translation.py` rather than applying a one-off + rewrite to `GenTranslation.py`. + +## Translation record structure + +- `TRANSLATION` maps each exact English source string to one record. +- `source` is the generator-maintained list of fully qualified modules where that string is extracted. +- Each supported non-English language has one abbreviation key, such as `RU` or `ZH`, whose value is the reviewed + user-facing translation. +- `isReviewed` is the string `"True"` or `"False"`, not a JSON/Python boolean. Mark it `"True"` only after every + language value in the record has been reviewed. +- Preserve this preferred serialized key sequence in every record: `source`, language 1, language 2, ..., `isReviewed`. + Keep `source` first and `isReviewed` last; use the catalog's stable language order between them. +- Do not add ad-hoc metadata fields that the generator and runtime do not understand. + +For example: + +```python +"Delete": { + "source": [ + "Furious.Backends...", + "Furious.Backends...", + ], + "RU": "Удалить", + "ZH": "删除", + "isReviewed": "True" +} +``` + +## Extraction and review rules + +- Keep translation source keys as literal strings discoverable by the existing `_()` extractor. Do not pass formatted + strings, f-strings, or `.format(...)` results to `_()`. +- Braces in extracted strings are reserved for application-constant substitution by `Translation.py`; they are not + general runtime-format placeholders. +- Let the generator derive `source`; do not fabricate or retain stale module names manually. +- Review natural terminology and meaning in every supported language, not only literal word correspondence. Do not + approve source-language placeholders as completed translations. + +## Code review rules + +- Flag direct catalog edits that should have been made through source extraction and regeneration. +- Flag records whose key sequence is not `source`, language keys, then `isReviewed`. +- Flag `"isReviewed": "True"` when any language is missing or unreviewed. +- Flag dynamic formatting inside `_()` and changes that treat braces as ordinary formatting syntax.