71 lines
6.4 KiB
Markdown
71 lines
6.4 KiB
Markdown
# Locale Atlas — каждый ключ перевода каждого мода
|
||
|
||
Карта локализации раскладывает локализацию всех установленных модов: какие ключи каждый мод объявляет на каждом языке, где ключи используются — в сценариях, коде C#, данных JSON, коллекциях, сценах, манифестах — и что не так. Она разделяет два вида проблем:
|
||
|
||
- **ошибки** — сломанный текст: ключ, который используется, но нигде не объявлен; пустое значение; один ключ с двумя разными значениями в одном моде; файл, который загрузчик не прочтёт; испорченная кодировка;
|
||
- **предупреждения** — пробелы в переводе: ключ, отсутствующий на каком-то языке. Игра тогда откатывается к языку, где текст есть, так что ничего не ломается; в предупреждении сказано, какую строку добавить.
|
||
|
||
## Как запустить
|
||
|
||
```text
|
||
godot --path . -- --locale-atlas --locale-out=res://tests/artifacts/locale_atlas --with-test-suites
|
||
```
|
||
|
||
Она читает каждый установленный мод, пишет `report.md` и `report.json` в папку `--locale-out`, выводит в лог итоговую строку и завершается с кодом 1, если есть ошибки. В тест-раннере это тест `locale_atlas`. Текст `report.md` написан по-русски; описания проблем — на английском.
|
||
|
||
Чистый запуск текущих модов:
|
||
|
||
```text
|
||
locale atlas: 2284 key(s), 156 need attention, 0 error(s), 801 warning(s)
|
||
```
|
||
|
||
## Пробел и поломка бок о бок
|
||
|
||
Чтобы показать оба вида, для одного запуска в мод шаблона новеллы внесли две правки.
|
||
|
||
**Отсутствующий перевод.** Из `locale/scenarios_es.properties` убрали испанскую строку вопроса города. Атлас сообщает предупреждение со строкой, которую надо добавить:
|
||
|
||
```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?` |
|
||
```
|
||
|
||
Испанский игрок всё же видит вопрос — на другом языке, — так что это пробел, а не поломка.
|
||
|
||
**Сломанная ссылка.** В сценарии города в ключе одного из ответов сделали опечатку:
|
||
|
||
```scenario
|
||
option "Go into the bar" key=my_novel/town/opt_baar -> :bar
|
||
```
|
||
|
||
Теперь ключ используется, но не объявлен ни в одном файле, и атлас сообщает **ошибку** для каждого языка, указывая на строку сценария:
|
||
|
||
```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 = …` |
|
||
```
|
||
|
||
Запуск кончился `7 error(s)` и провалился. Стоило снова написать ключ `opt_bar` и вернуть испанскую строку, как всё стало чисто.
|
||
|
||
## Что внутри отчёта
|
||
|
||
- **Кодировки** — каждый файл локализации с его кодировкой, переводами строк и числом ключей; проблемы вроде не-UTF-8, U+FFFD, управляющих символов, mojibake или переводов строк только с CR — это ошибки.
|
||
- **Ключи, требующие внимания** — по строке на ключ: отметка на каждый язык (`✓` объявлен, `∅` пуст, `—` отсутствует), где он объявлен, кто на него ссылается и что не так.
|
||
- **Проблемы** — ошибки и предупреждения с модом, ключом, языком, местом правки и точной строкой, которую надо добавить.
|
||
|
||
Другие предупреждения: BOM, смешанные переводы строк, один и тот же ключ дважды с одним значением, мод, переопределяющий ключ только на части языков, несовпадающие между языками заполнители `{0}`, кириллица в английском тексте, `???` в значении, мод без своих `mod_<id>_name` и `mod_<id>_desc`.
|
||
|
||
## Откуда берутся ключи
|
||
|
||
- строки `.scenario` с `key=`; переводы текста сценария идут в `locale/scenarios_<lang>.properties`;
|
||
- `Translate("…")`, `Tr("…")` и `Locale = "…"` в C#;
|
||
- текстовые поля данных JSON (`Name`, `Description`, `title`…), `"@key"` в коллекциях;
|
||
- автопереведённые `text` и `tooltip_text` в сценах `.tscn`;
|
||
- `mod_<id>_name` и `mod_<id>_desc` из манифеста.
|
||
|
||
Файлы локализации должны лежать прямо в папке `locale/` мода; файл во вложенной папке игра не читает, и это ошибка.
|
||
|
||
## Если что-то пошло не так
|
||
|
||
1. **Ошибка для ключа, который по-английски работает.** Строка сценария несёт собственный текст, поэтому на одном языке всё может выглядеть правильно, тогда как переводы опечатанного ключа не находятся нигде.
|
||
2. **Сотни предупреждений.** Это пробелы перевода; каждая строка даёт файл и строку, которую надо добавить.
|
||
|