galeon committed
1 parent
1943996608
commit
f10b654953
34 files changed
+2099
-4576
No files matched your search
+103
-94
@@ -1,17 +1,15 @@
|
||||
# Localization
|
||||
|
||||
`localization.h` / `localization.cpp`
|
||||
`localization.h`, `localization.cpp`
|
||||
|
||||
Единственный источник всех текстов интерфейса. Каталог — [`i18n/translations.json`](#каталог),
|
||||
он лежит в ресурсах и правится руками. Штатных `.ts`/`.qm` в проекте нет намеренно: `lupdate`,
|
||||
`lrelease` и Linguist не нужны, а все переводы видны в одном файле.
|
||||
Все тексты интерфейса на всех языках лежат в одном файле, `i18n/translations.json`, и читаются
|
||||
через этот класс. Стандартные `.ts`/`.qm`, `lupdate`, `lrelease` и Linguist в проекте не
|
||||
используются. Язык переключается без перезапуска.
|
||||
|
||||
Язык переключается на лету: при смене все привязки QML перевычисляются, перезапуск не требуется.
|
||||
## Из QML
|
||||
|
||||
## Доступ из QML
|
||||
|
||||
Синглтон зарегистрирован декларативно (`QML_NAMED_ELEMENT(Loc)` + `QML_SINGLETON`) и доступен
|
||||
в любом файле модуля без импорта.
|
||||
Синглтон `Loc` (`QML_NAMED_ELEMENT(Loc)` + `QML_SINGLETON`) доступен в любом файле модуля без
|
||||
импорта.
|
||||
|
||||
```qml
|
||||
Text { text: Loc.t.settings.title }
|
||||
@@ -19,31 +17,22 @@ Text { text: Loc.t.java.progress.downloading.arg(label) }
|
||||
DarkCombo { model: Loc.t.profile.authTypes }
|
||||
```
|
||||
|
||||
Точечный путь `Loc.t.a.b.c` — это обращение к вложенным объектам дерева, которое строится из
|
||||
плоских ключей каталога разбиением по точке.
|
||||
`Loc.t` — дерево JS-объектов, собранное из плоских ключей каталога разбиением по точке.
|
||||
|
||||
**Почему свойство, а не метод.** Вызов `Q_INVOKABLE` не регистрирует зависимость привязки, и
|
||||
`text: Loc.t("ключ")` никогда бы не обновился при смене языка. Чтение `Q_PROPERTY` с сигналом
|
||||
`NOTIFY` зависимость регистрирует: `languageChanged` перевычисляет все привязки, которые читали
|
||||
`Loc.t`. Сегменты после `t` — обычные обращения к членам JS-объекта, отслеживать их не нужно,
|
||||
потому что при смене языка дерево заменяется целиком.
|
||||
Почему `t` сделано свойством, а не методом `Loc.t("ключ")`. Вызов `Q_INVOKABLE` не регистрирует
|
||||
зависимость привязки, и текст не обновился бы при смене языка. Чтение `Q_PROPERTY` с `NOTIFY`
|
||||
регистрирует, поэтому `languageChanged` перевычисляет все привязки, где читали `Loc.t`. Дальнейшие
|
||||
`.settings.title` — обычные обращения к полям JS-объекта. Следить за ними не нужно, потому что при
|
||||
смене языка дерево заменяется целиком.
|
||||
|
||||
Тип свойства — `QJSValue`, а не `QVariantMap`: `QVariantMap` пересобирался бы в новый JS-объект
|
||||
при каждом чтении, а привязок в проекте полторы сотни. `QJSValue` строится один раз на смену
|
||||
языка.
|
||||
Тип свойства — `QJSValue`. С `QVariantMap` движок собирал бы новый JS-объект при каждом чтении, а
|
||||
привязок в проекте около полутора сотен. `QJSValue` строится один раз на каждую смену языка.
|
||||
|
||||
Из тела JS-функции `Loc.t` читается так же — это просто чтение свойства:
|
||||
Кроме `t` есть `language` (что выбрано: `system`, `ru`, `en`), `resolvedLanguage` (во что это
|
||||
превратилось, всегда `ru` или `en`) и `availableLanguages()`. Последний сейчас не используется:
|
||||
список языков в настройках [Main.qml](../qml/Main.md) задан руками (`stLanguage`).
|
||||
|
||||
```qml
|
||||
onLaunched: (profileName, buildName) =>
|
||||
window.showToast(Loc.t.launch.status.started.arg(profileName).arg(buildName), "#4b7a1f")
|
||||
```
|
||||
|
||||
## Доступ из C++
|
||||
|
||||
Свободные функции, а не методы: их вызывают и из namespace-обёрток
|
||||
([LauncherPaths](launcherpaths.md), [JavaLocator](javalocator.md),
|
||||
[ZlibReference](zlibreference.md)), где никакого `QObject` нет.
|
||||
## Из C++
|
||||
|
||||
```cpp
|
||||
#include "localization.h"
|
||||
@@ -53,29 +42,34 @@ emit launchProgress(Loc::text("java.progress.downloading").arg(label));
|
||||
const QStringList kinds = Loc::list("profile.authTypes");
|
||||
```
|
||||
|
||||
Ключа нет — возвращается сам ключ, а в отладочной сборке ещё и `qWarning`: строка вида
|
||||
`launch.error.noProfile` в интерфейсе сразу бросается в глаза.
|
||||
Это свободные функции, потому что их вызывают и из пространств имён без `QObject`
|
||||
([launcherpaths.h](launcherpaths.md), [javalocator.h](javalocator.md),
|
||||
[zlibreference.h](zlibreference.md)).
|
||||
|
||||
Если ключа нет, возвращается сам ключ, а в отладочной сборке ещё пишется `qWarning`. В интерфейсе
|
||||
такую строку легко заметить.
|
||||
|
||||
### Потоки
|
||||
|
||||
`Loc::text()` и `Loc::list()` можно звать из любого потока. Каталог заполняется ровно один раз
|
||||
в `load()`, который отрабатывает в `main()` до того, как [BuildSwitcher](BuildSwitcher.md)
|
||||
создаст свой поток; дальше он только читается, а копирование `QString` из хэша безопасно само по
|
||||
себе. Единственное, что меняется на ходу, — индекс текущего языка, и он `QAtomicInt`. В худшем
|
||||
случае сообщение, которое собиралось в момент переключения, уедет на прежнем языке.
|
||||
`Loc::text()` и `Loc::list()` можно вызывать из любого потока. Каталог заполняется один раз в
|
||||
`load()`, до того как [BuildSwitcher](BuildSwitcher.md) запустит свой поток, и дальше только
|
||||
читается. На ходу меняется лишь индекс текущего языка, а он `QAtomicInt`. В худшем случае строка,
|
||||
собранная в момент переключения, окажется на прежнем языке.
|
||||
|
||||
`setLanguage()` и рассылка `languageChanged` — только поток GUI; это проверяется `Q_ASSERT`.
|
||||
`setLanguage()` вызывается только из GUI-потока, это проверяет `Q_ASSERT`.
|
||||
|
||||
## Каталог
|
||||
|
||||
`i18n/translations.json` попадает в ресурсы через список `RESOURCES` в `qt_add_qml_module`,
|
||||
поэтому читается по пути `:/qt/qml/Minecraft_launcher/i18n/translations.json`.
|
||||
Файл попадает в ресурсы через `RESOURCES` в `qt_add_qml_module` и читается из
|
||||
`:/qt/qml/BiLauncher/i18n/translations.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"_meta": {
|
||||
"languages": ["ru", "en"],
|
||||
"displayNames": { "ru": "Русский", "en": "English" }
|
||||
"displayNames": { "ru": "Русский", "en": "English" },
|
||||
"_readme": ["..."],
|
||||
"_glossary": { "сборка": "build", "...": "..." }
|
||||
},
|
||||
"strings": {
|
||||
"settings.title": { "ru": "Настройки запуска", "en": "Launch settings" },
|
||||
@@ -88,77 +82,92 @@ const QStringList kinds = Loc::list("profile.authTypes");
|
||||
}
|
||||
```
|
||||
|
||||
Ключи плоские, языки рядом: забытый перевод виден на соседней строке, правка пары — один участок
|
||||
файла, а третий язык добавляется колонкой без правок загрузчика.
|
||||
Ключи плоские, языки записаны рядом. Так сразу видно, если перевод забыли, а новый язык
|
||||
добавляется ещё одним полем без правок загрузчика. `_readme` и `_glossary` — подсказки для тех, кто
|
||||
правит файл. Загрузчик их не читает.
|
||||
|
||||
**Имя ключа — `<домен>.<вид>.<имя>`**, сегменты в lowerCamelCase.
|
||||
Значение — либо строка, либо список строк (для моделей выпадающих списков). Тип определяется по
|
||||
первому языку.
|
||||
|
||||
- **Домен** — область, а не имя файла: `app`, `common`, `settings`, `profile`, `build`,
|
||||
`seasonal`, `version`, `java`, `loader`, `auth` (с `auth.ely.*`, `auth.msa.*`), `launch`,
|
||||
`game`, `switch`, `storage`, `zlib`.
|
||||
- **Вид** — `title`, `label`, `button`, `placeholder`, `hint`, `header`; для сообщений `error`,
|
||||
`progress`, `status`, `warning`.
|
||||
- **Имя** описывает условие, а не формулировку, чтобы перевод не переименовывал ключ:
|
||||
`gameRunning`, `downloadFailed`, `checksumMismatch`.
|
||||
### Имена ключей
|
||||
|
||||
Литерал, который нужен в двух и более файлах, живёт в `common.*`.
|
||||
`<домен>.<вид>.<имя>`, сегменты в lowerCamelCase.
|
||||
|
||||
Подстановки `%1`/`%2` сохраняются дословно: их одинаково понимают `QString::arg()` и
|
||||
QML-овский `String.arg()`. **Набор `%N` в `ru` и `en` обязан совпадать** — порядок слов может
|
||||
отличаться, состав нет. Множественного числа формат не поддерживает; в коде сейчас нет ни одной
|
||||
строки, которой оно требуется.
|
||||
- **Домен** — область интерфейса, а не файл: `app`, `common`, `settings`, `profile`, `build`,
|
||||
`seasonal`, `version`, `java`, `loader`, `auth` (`auth.ely.*`, `auth.msa.*`), `launch`, `game`,
|
||||
`switch`, `storage`, `zlib`.
|
||||
- **Вид**: `title`, `label`, `button`, `placeholder`, `hint`, `header`, `tooltip`; для сообщений
|
||||
`error`, `progress`, `status`, `warning`.
|
||||
- **Имя** описывает ситуацию, а не формулировку: `gameRunning`, `downloadFailed`,
|
||||
`checksumMismatch`. Тогда при правке перевода ключ не придётся переименовывать.
|
||||
|
||||
## Как добавить строку
|
||||
Строка, которая нужна в двух и более местах, кладётся в `common.*`.
|
||||
|
||||
1. Добавить запись в `strings` файла `i18n/translations.json` — сразу с `ru` и `en`.
|
||||
2. Сослаться на неё: `Loc.t.домен.вид.имя` в QML или `Loc::text("домен.вид.имя")` в C++.
|
||||
3. Прогнать `python3 tools/check_translations.py`.
|
||||
`%1`, `%2` пишутся как есть: их одинаково понимают `QString::arg()` и `String.arg()` в QML. Набор
|
||||
`%N` в `ru` и `en` должен совпадать, порядок может быть разным. Множественного числа формат не
|
||||
поддерживает, и пока ни одна строка его не требует.
|
||||
|
||||
## Как добавить язык
|
||||
## Добавить строку
|
||||
|
||||
1. Дописать код в `_meta.languages` и название в `_meta.displayNames`.
|
||||
2. Добавить колонку с этим кодом в каждую запись `strings`.
|
||||
3. Добавить код в `stLanguage.codes` и пункт в модель комбобокса в [Main.qml](../qml/Main.md),
|
||||
а также ключ `settings.language.<код>` с эндонимом (название языка не переводится — оно
|
||||
одинаково во всех колонках).
|
||||
4. При необходимости поправить `systemLanguage()` в `localization.cpp`: сейчас он выбирает
|
||||
русский для русской системной локали и английский во всех остальных случаях.
|
||||
1. Запись в `strings` сразу с `ru` и `en`.
|
||||
2. `Loc.t.домен.вид.имя` в QML или `Loc::text("домен.вид.имя")` в C++.
|
||||
3. `python3 tools/check_translations.py`.
|
||||
|
||||
## Выбор языка и его хранение
|
||||
## Добавить язык
|
||||
|
||||
Ключ настройки — `language`, значения `"system"`, `"ru"`, `"en"`, по умолчанию `"system"`.
|
||||
Хранится в `settings.json` рядом с остальными настройками; в интерфейсе — первым пунктом
|
||||
диалога «Настройки запуска», применяется по кнопке «Сохранить».
|
||||
1. Код в `_meta.languages`, название в `_meta.displayNames`.
|
||||
2. Значение для этого кода в каждой записи `strings`.
|
||||
3. Ключ `settings.language.<код>` с названием языка на нём самом, одинаковым во всех колонках.
|
||||
4. Пункт в модели `stLanguage` и код в `stLanguage.codes` в [Main.qml](../qml/Main.md).
|
||||
5. Если нужно, поправить `systemLanguage()`: сейчас при русской системной локали выбирается
|
||||
русский, при любой другой — английский.
|
||||
|
||||
Круг замкнут в одну сторону, циклической зависимости нет:
|
||||
## Где хранится выбранный язык
|
||||
|
||||
Ключ `language` в `settings.json`, по умолчанию `system`. Меняется в окне настроек и применяется
|
||||
по кнопке «Сохранить».
|
||||
|
||||
```
|
||||
main.cpp ──► Localization::load() ──► LauncherPaths::settingsFile() (только чтение, один раз)
|
||||
LauncherBackend::updateSettings() ──► Localization::setLanguage() (в одну сторону)
|
||||
main.cpp ──► Localization::load() ──► читает settings.json (один раз)
|
||||
LauncherBackend::updateSettings() ──► Localization::setLanguage()
|
||||
```
|
||||
|
||||
`Localization` ничего не знает про [LauncherBackend](LauncherBackend.md) — писать `settings.json`
|
||||
по-прежнему может только он. Читать настройки самому приходится потому, что язык нужен раньше,
|
||||
чем QML вычислит первую привязку, а бэкенд появляется только вместе с движком.
|
||||
`settings.json` записывает только [LauncherBackend](LauncherBackend.md). Localization его только
|
||||
читает, и только при старте: язык нужен раньше первой привязки QML, а бэкенд создаётся вместе с
|
||||
движком. Обратной зависимости от бэкенда у Localization нет.
|
||||
|
||||
Неизвестное значение (файл правили руками) откатывается на `"system"` с предупреждением.
|
||||
Отсутствующий или испорченный каталог — ошибка на старте: `main()` пишет причину и возвращает
|
||||
`-1`. Файл вкомпилирован в бинарник, так что это может быть только ошибка сборки, а лаунчер,
|
||||
у которого все подписи выглядят как точечные ключи, хуже, чем лаунчер, который сказал, почему
|
||||
не запустился.
|
||||
Неизвестный язык в файле (если его правили руками) заменяется на `system` с предупреждением.
|
||||
|
||||
**Известное ограничение.** Уже сложенные в поля C++ строки не перепереводятся:
|
||||
Если каталог не найден или не разбирается, это ошибка сборки, потому что файл вкомпилирован в
|
||||
бинарник. `main()` пишет причину в `qCritical` и возвращает `-1`.
|
||||
|
||||
### Что не переводится при смене языка
|
||||
|
||||
Строки, которые уже собраны и лежат в полях C++, остаются на старом языке:
|
||||
`LauncherBackend::m_storageIssues` собирается при старте, а `stage()`/`status()` у
|
||||
[BuildSwitcher](BuildSwitcher.md) заменяются на следующем тике прогресса. Все они
|
||||
диагностические и короткоживущие.
|
||||
[BuildSwitcher](BuildSwitcher.md) обновятся только на следующем шаге. Всё это короткоживущие
|
||||
диагностические сообщения.
|
||||
|
||||
## Проверка
|
||||
Отдельно: `GameLauncher` прячет токен в строке запуска за `<скрыт>`, и эта строка не берётся из
|
||||
каталога.
|
||||
|
||||
`tools/check_translations.py` — только чтение, ненулевой код возврата при любой ошибке:
|
||||
## Проверка каталога
|
||||
|
||||
- каждый `Loc::text("…")` и `Loc::list("…")` из C++ есть в каталоге и совпадает по типу значения;
|
||||
- каждый путь `Loc.t.a.b.c` из QML разворачивается в существующий ключ;
|
||||
- наборы ключей у всех языков совпадают, пустых значений нет, типы одинаковы;
|
||||
- наборы `%N` совпадают по языкам, длины списков равны;
|
||||
- не осталось ни одного `tr(`, `qsTr(` или `QCoreApplication::translate`;
|
||||
- ключи, на которые никто не ссылается, — предупреждением.
|
||||
`tools/check_translations.py` ничего не меняет и возвращает ненулевой код при любой ошибке.
|
||||
Проверяет:
|
||||
|
||||
- у всех языков одинаковый набор ключей и типы, пустых значений нет, длины списков равны;
|
||||
- набор `%N` совпадает по языкам;
|
||||
- каждый `Loc::text("…")` и `Loc::list("…")` в C++ есть в каталоге с нужным типом;
|
||||
- каждый `Loc.t.a.b.c` в QML ведёт к существующему ключу (последний сегмент может быть методом
|
||||
JS, например `.arg`);
|
||||
- нигде не осталось `tr(`, `qsTr(`, `QCoreApplication::translate`.
|
||||
|
||||
Ключи, на которые никто не ссылается, выводятся предупреждением.
|
||||
|
||||
Скрипт смотрит только файлы в корне репозитория. Если исходники разложат по подпапкам, его нужно
|
||||
будет поправить.
|
||||
|
||||
---
|
||||
|
||||
При создании этого документа использовался ИИ.
|
||||
Reference in new issue
Block a user