Тема: Локализация (Localization)

Локализация
Автор: DK
Мейкер: MV
Версия: 5.4.2
Тип: Добавляющий возможности

Описание:
Локализация игры. Перевод игры на несколько языков.

Зависимости:
Наличие включенного плагина DKTools версии 9.0.0 или выше

Условия использования/лицензия:
Актуальная информация о правилах использования: https://dk-plugins.ru/terms-of-use

Справка:

Спойлер Справка:

###=============================================== ============================
## Поддержка
###=============================================== ============================
Поддержать: https://dk-plugins.ru/donate
Стать патроном: https://www.patreon.com/dkplugins

###=============================================== ============================
## Требования и зависимости
###=============================================== ============================
Наличие включенного плагина DKTools версии 9.0.0 или выше

###=============================================== ============================
## Демоверсия
###=============================================== ============================
https://dk-plugins.ru/mv/system/localization/

###=============================================== ============================
## Специальная совместимость с другими плагинами
###=============================================== ============================
Плагин совместим с большинством других плагинов, но все же могут попасться плагины,
которые не работают с локализацией. Я добавляю совместимость этих плагинов.
Чтобы совместимость работала правильно,
плагины из следующего списка необходимо разместить ВЫШЕ плагина локализации:
YEP_MessageCore.js
YEP_OptionsCore.js
YEP_QuestJournal.js

## Внимание! ##
Если вы считаете, что какой-то плагин несовместим с локализацией сообщите мне об этом.

###=============================================== ============================
## Инструкции
###=============================================== ============================

### 1 ### Установка ###
1. Добавить хотя бы один язык в параметре "Языки игры".
2. Если вы меняли стандартный шрифт в игре, то его также нужно изменить в параметре "Стандартный шрифт".

## Неполный список рекомендованных локалей ##
Russian - ru
Ukrainian - uk
Belarusian - be
English - en
Chinese - zh
Japanese - ja
Korean - ko
French - fe
German - de
Spanish - es
Czech - cs
Italian - it

Если вы не нашли в этом списке локаль, то можете найти ее в интернете, например,
здесь: https://www.science.co.il/language/Locale-codes.php

### 2 ### Использование ###
1. При первом запуске игры плагин создаст папки для переводов и json файлы для каждого языка.
2. Для локализации текста используйте теги: {}.
3. Для использования переменной внутри текста используйте тег \VAR[ID],
где ID - номер переменной. Используйте только для глубины перевода (см. ниже).

### Добавление нового перевода на примере события с сообщением ###
1. Создайте новое событие, добавьте отображение сообщения.
2. В сообщении напишите {text}. Сохраните событие и проект.
3. Откройте json файлы для каждого языка.
4. Первый символ файла должна быть {, а последний - }.
Эти символы нельзя удалять. Внутри этих скобок пишется перевод игры.
6. Добавьте в один из файлов следующий текст и сохраните его: "text": "Текст".
7. Запустите игру и созданное событие.

### Внимание! ###
Кодировка в файлах перевода должна быть UTF-8 без BOM.

###=============================================== ============================
## Использование массивов
###=============================================== ============================
Массивы загружаются в данные локализации по названию файла.

## Использование массивов на примере файла "quests.json" ##
1. Файл имеет следующую структуру:
[null, { "name": "Quest 1" }, { "name": "Quest 2" }]
2. Чтобы вывести в сообщении текст "Quest 1", необходимо прописать тег
{quests[1].name}
Чтобы обратиться к массиву сначала необходимо написать название файла,
в котором он хранится, затем необходимо указать в квадратных скобках
номер элемента и поле, которое должно быть использовано.

###=============================================== ============================
## Локализованные ресурсы
## Использование разных файлов (аудио, изображения, видео) для каждого языка
###=============================================== ============================
Данная функция поможет использовать специальные файлы для разных языков.
Например, если на них есть текст, то можно сделать разные изображения для каждого языка,
и плагин сам будет выбирать нужное изображение.
Данная функция работает только с аудио, видео и изображениями.

## Внимание! ##
Для работы данной функции на мобильных устройствах и в браузерах
необходимо выставить режим работы файловой системы Nwjs + Stamp в плагине DKTools!

1. Создайте новую папку в необходимой папке
2. В качестве имени папки используйте необходимую локаль игры
3. Переместите файлы в созданную папку
Пример:
Необходимо использовать разные файлы Loading.png для разных языков
Основной файл находится в папке "img/system".
Создаем папку "ru" в "img/system" и перемещаем туда Loading.png для русского языка.
Например, для английского языка будет использоваться основной файл из "img/system",
а для русского языка из созданной нами "img/system/ru".

###=============================================== ============================
## Использование неограниченного количества файлов перевода
###=============================================== ============================
## Внимание! ##
Для работы данной функции на мобильных устройствах и в браузерах
необходимо выставить режим работы файловой системы Nwjs + Stamp в плагине DKTools!
Данная инструкция предназначена для папки, которая имеет название по умолчанию (locales)
Если Вы переименовали папку в параметрах плагина, то используйте новое название папки!

Если у Вас большое количество текста в игре, и Вам неудобно пользоваться одним json файлом,
то Вы можете разбить его на несколько json файлов и поместить в отдельную папку.
Пример для английской локали (en):
1. В папке locales создайте папку en.
2. Перенесите в новую папку свой старый файл en.json из папки locales.
3. Создайте несколько json файлов с любыми именами.
4. В каждом файле пропишите необходимые теги и сохраните изменения.
## Внимание! ##
Все теги во всех файлах должны иметь уникальное название!
В случае совпадения имен тегов будет загружен первый из них (порядок не гарантируется)!

### 3 ### Параметры плагина ###
1. Игнорируемые файлы - Файлы, которые игнорируются командой плагина UpdateLocalizationTags.
2. Глубина перевода - Количество операций перевода текста.
В переведенном тексте Вы можете указать другой тег,
и он будет переведен, если глубина перевода больше 1.
Пример:
"text": "Текст {text2}",
"text2" "2"
При глубине перевода больше 1 в итоге получится "Текст 2".
3. Длина текста - Длина текста, при которой он сохраняется в кэш.
Это нужно, чтобы сократить необходимые вычислительные ресурсы для перевода.
Кэш автоматически очищается при переходе между картами.

### 4 ### Специальные символы сообщений ###
1. \language - Вывести название текущего языка

### 5 ### Команды плагина ###
1. UpdateLocalizationTags
Обновить теги в файлах перевода.
Команда плагина проверяет json файлы из папки "data/" (кроме игнорируемых файлов,
заданных в параметрах плагина), а также все параметры всех плагинов.
Найденные теги сохраняются в новые файлы в папке локализации с префиксом "new".

2. ClearLocalizationCache
Очистить кэш локализации.

### 6 ### Вызовы скриптов ###
1. DKTools.Localization.locale - Получить текущую локаль
2. DKTools.Localization.locales - Получить массив локалей
3. DKTools.Localization.language - Получить текущий язык
4. DKTools.Localization.languages - Получить массив языков
5. DKTools.Localization.getText(text) - Получить локализованный текст
6. DKTools.Localization.getPrevLocale() - Получить предыдущую локаль
7. DKTools.Localization.getNextLocale() - Получить следующую локаль
8. DKTools.Localization.getPrevLanguage() - Получить предыдущий язык
9. DKTools.Localization.getNextLanguage() - Получить следующий язык
10. DKTools.Localization.selectLocale(locale) - Установить локаль (асинхронная операция, возвращает Promise)
11. DKTools.Localization.selectPrevLocale() - Выбрать предыдущую локаль (асинхронная операция, возвращает Promise)
12. DKTools.Localization.selectNextLocale() - Выбрать следующую локаль (асинхронная операция, возвращает Promise)
13. DKTools.Localization.addChangeLocaleListener(funct ion) - Добавить слушателя изменения локали (синхронная/асинхронная функция)
14. DKTools.Localization.getPrimaryLocale() - Получить основную локаль
15. DKTools.Localization.getPrimaryLanguage() - Получить основной язык

### 7 ### Как добавить опцию в YEP_OptionsCore.js ###
1. Поместите плагин YEP_OptionsCore ВЫШЕ в списке плагинов
2. Включите параметр "Показывать команду" в плагине локализации
3. Добавьте новую опцию в YEP_OptionsCore.js со следующими параметрами:
Symbol: locale
Show/Hide:
show = LocalizationParam.get('Show Options Command');
Draw Option Code:
var rect = this.itemRectForText(index);
var statusWidth = this.statusWidth();
var titleWidth = rect.width - statusWidth;
this.resetTextColor();
this.changePaintOpacity(this.isCommandEnabled(inde x));
this.drawOptionsName(index);
this.drawText(this.statusText(index), titleWidth, rect.y, statusWidth, 'center');

Обзоры:

Спойлер Обзоры:

Скачать с сайта DK Plugins: https://dk-plugins.ru/mv/system/localization/

Поддержать DK: Поддержать

Версия 3.1

1. Совместимость с DKTools 6.1+
2. Исправлена ошибка в функции DKTools.Localization.addChangeLocaleListener

UPD

Версия 3.11

1. Исправлена проблема некорректной загрузки локали

Версия 4.0

Что нового:
1. Добавлена функция разделения перевода на несколько json файлов.
2. Если json файл имеет неправильную структуру, то игра теперь не виснет, а выдает ошибку, и показывает где она была совершена.
3. Удалил настройку использования новых файлов для обновления тэгов локализации. Теперь новые тэги всегда сохраняются в новые файлы.
4. Функция обновления тэгов вышла из стадии бэта версии. Добавлена поддержка парсинга всех активных плагинов. То есть команда плагина выдергивает тэги из настроек всех плагинов.
5. Больше совместимости с другими плагинами.
6. Добавлен 1 спец символ для сообщений. Теперь можно вывести название текущего языка в сообщении.
7. Обновил файл помощи.
8. Обновлена демоверсия. Добавлены новые примеры.

P.S. Обращаю ваше внимание, что для работы новой версии плагина необходима последняя (на текущий момент) версия плагина DKTools - 7.0.0.