Instruction.md

Инструкция по работе с базой данных перевода на компьютере

0. Назначение инструкции

Данная инструкция предназначена для обучения обслуживанию репозитория. Это НЕ инструкция по переводу. Под обслуживанием репозитория подразумевается:

• сборка мода
• обновление английских текстов в репозитории согласно текущей версии игры
• исправление переводов после обновления
• извлечение переведённых текстов из мода

Для перевода используется специальный web-интерфейс: https://sbt-community.github.io/

1. Требования

Для работы с базой нужны следущие программы: git (чтобы синхронизировать базу с репозиторием на github, качать тут: https://git-scm.com/), интерпретатор python выше 3 версии (на питоне написаны все основные скрипты обслуживания базы, скачивать питон тут: https://www.python.org/downloads/, не стоит забывать про версию, нужна именно 3 или выше) Кроме непосредственно программ нужны базовые навыки работы с git (в тексте будут употребляться слова "клонировать", "коммитить", "пушить" и т. д., нужно понимать их смысл и уметь делать то, что они значат). Навыки работы с git можно приобрести на том же сайте где скачивался сам git клиент или где либо еще, инструкций полно в интернете.

2. Перед началом работы с базой

Чтобы начать работать с базой переводов достаточно клонировать репозиторий с github.com в пустую папку. Адрес репозитория: https://github.com/SBT-community/Starbound_RU.git Если база уже склонирована то обязательно перед работой обновить локальную ее версию в папке до актуального состояния. Перед любыми изменениями в базе следует переключиться в ветку web-interface и коммитить изменения в нее. Ветка master служит только для сборки готовой к релизу версии аддона, слияние ветки web-interface с веткой master крайне желательно проводить исключительно через пул-реквест на github, даже если есть права на непосредственную запись в master.

3. Структура базы

После клонирования репозитория с базой перевода в пустую папку можно обнаружить в последней три видимые подпапки: translations, tools и patches, а также 2 файла: README.md и .travis.yml. Папка tools содержит все основные инструменты управления базой. Подробный разбор инструментов приведен в пункте 4 настоящего руководства. Папка patches содержит патчи к оригинальным ресурсам игры. некоторые из патчей уже устарели, потому их применение под вопросом. Лучше просто игнорировать эту папку. Файл README.md задает описание репозитория на github. Вряд ли потребуется его менять. Файл .travis.yml указывает параметры автоматической сборки мода в режиме онлайн. Не стоит туда лезть без понимания работы систем непрерывной интеграции, в частности travis Папка translations содержит непосредственно базу с переводами, на ней стоит остановиться чуть подробнее. Базу с переводами можно условно разделить на 2 части: текстовые поля (translations/texts) и прочие переводы, т.е. картинки, скрипты и т. д. (translations/others) Кроме частей непосредственно ответственных за хранение переводов имеются 3 вспомогательных файла:

• translations/substitutions.json - содержит информацию о том, в каком файле базы искать поля из того или иного ресурса игры.

• translations/totallabels.json и translations/translatedlabels.json - содержат информацию об общем количестве полей в каждом из файлов базы и о количестве переведенных полей соответственно. нужны для отображения прогресса перевода (чтобы каждый раз не пересчитывать поля)

Папка translations/others повторяет структуру ресурсов игры. Её содержимое будет просто скопированно в мод при экспорте. В папке translations/texts находятся json файлы с текстовыми полями и метаданными к ним. Их редактирование вручную нежелательно, а ручное добавление или удаление, а также изменение их структуры или расположения может повлечь за собой поломку базы.

4. Утилиты

В папке tools находятся основные утилиты для работы с базой. Прежде чем начать с ними работу нужно условиться, что запускаться эти утилиты должны из <корневого каталога базы>. <Корневым каталогом базы> в данном случае является корень репозитория, т.е. та папка в которой лежат подпапки tools,translations и т. д. Все утилиты должны запускаться исключительно из консоли, будь то консоль GNU/Linux, Android/Linux, OSX, Windows или еще чего поэкзотичнее. При этом рабочей папкой при запуске утилит дожен быть <корневой каталог базы>, иначе утилиты не смогут найти базу (да, мне лень делать все настраиваемым, я просто приколотил гвоздями все пути). Теперь перейдем к самим утилитам.

4.1 Извлечение текстовых полей из ресурсов игры

Самая первая из утилит, которая создает и обновляет базу сообразно изменениям в ресурсах игры(далее будем называть ее парсер). Для ее работы потребуются эти самые ресурсы заранее заботливо распакованные в каталог <корневой каталог базы>/assets. ВНИМАНИЕ: после распаковки ресурсов игры нужно перейти в папку с ними и применить все патчи из папки <корневой каталог базы>/patches. Команда для применения патчей: patch -p1 -i ../patches/<имя файла патча>. Она должа выполняться из каталога с распакованными ресурсами, а не из корневого каталога базы! Файл который следует выполнить с помощью python: tools/extract_labels.py, т.е. комманда для командной строки будет выглядеть как:

python tools/extract_labels.py

Поскольку ресурсы игры, содержащие текстовые поля, представляют собой json файлы, можно работать с иерархией внутри каждого json файла и присваивать каждому значению внутри файла своеобразный путь вида корень/подраздел/2/подраздел-в-массиве. В данном примере подраздел содержит массив, а "2" - номер элемента в массиве. Таким образом структура json файла для описанного выше пути и значения "искомое значение" находящегося по нему будет выглядеть так:

{
  "корень": {
    "подраздел": [
      {},
      {},
      {
        "подраздел-в-массиве": "искомое значение"
      }
    ]
  }
}

Такой подход к локализации значений внутри файлов ресурсов игры используется при настройке парсера для программы извлечения текстовых полей. Файлы из которых будут извлечены текстовые поля можно задать в конфигурационном файле(на самом деле просто исходнике) tools/parser_settings.py. Его не нужно запускать, нужно просто отредактировать. Открыв этот файл можно заметить словарь (в терминах питона), где сопоставляются окончания имен файлов с регулярными выражениями для поиска текстовых полей в этих самых файлах. Регулярное выражение применяется к пути каждого из полей внутри каждого файла ресурсов игры, чье окончание является ключем словаря. Первое поле "*" относится ко всем перечисленным ниже окончаниям имен файлов. Массив напротив каждого из окончаний содержит специфические для этого окончания регулярные выражения. Он может быть пустым, тогда к файлам с таким окончаниям будут применены только регулярные выражения из общего массива "*". Таким образом, если в ресурсах игры появился новый файл, с новым окончанием, скажем, .сurrency, а текстовые поля для перевода в нем находятся по путям, совпадающим с одним из регулярных выражений массива "*", для добавления его в обработку парсером нужно добавить в словарь новую запись с ключем ".сurrency", и пустым массивом в качестве значения:

foi = {
...
  ".currency": [],
...
}

Особое внимание следует уделить отступам. для всех элементов словаря отступ равен двум пробелам. Если же для в файлах с окончанием .currency есть текстовые поля расположенные по путям, не совпадающим ни с одним из регулярных выражений для "*", следует добавить специфическое регулярное выражение для данного пути в массив напротив ".currency". Например, если путь нашего текстового поля внутри файлов c окончанием .currency выглядит как dollars/some-specific-text, то новая запись будет выглядеть так:

foi =
...
  ".currency": ["^dollars/some-specific-text$"],
...
}

Подробнее о регулярных выражениях, а также массивах и словарях python можно узнать в соответствующих учебниках, коих полно в интернете.

В парсере имеется механизм обработки специальных случаев перевода. Например когда одно и то же слово в разных контекстах переводится по разному на русский, но выглядит одинаково на английском. Чтобы парсер не смешал такие случаи в одну запись базы, существует файл tools/special_cases.py. Работать с ним нужно также как и с файлом tools/parser_settings.py, т.е. только редактировать, а не запускать. Данный файл содержит массив specialSections:

specialSections = [
...
]

В нем можно создать объекты SpecialSection, следущим образом:

specialSections = [
...
  SpecialSection("Комментарий с описанием специального случая", ["регулярное выражение для путей к полям внутри файлов ресурсов игры, попадающих под специальный случай", "тут может быть еще одно"], ["регулярное выражение для имен файлов, попадающих под специальный случай"]),
  # И еще одна секция
  SpecialSection("Тоже самое что и в предыдущей", [...], [...], True), # В данном случае в специальный случай будут помещены только те поля, для которых И имя файла, И путь к полю внутри файла соответствуют одному из регулярных выражений .
...
]

Примеры использования можно найти внутри самого файла tools/special_cases.py.

4.2 Экспорт мода

Для экспорта базы перевода в мод существует утилита tools/export_mod.py. Для её запуска нужно ввести, соответственно

python tools/export_mod.py

После завершения своей работы данная утилита создаст папку new_mod в <корневом каталоге базы>, содержащую мод, готовый к использованию или упаковке. Перед повторным запуском экспорта необходимо избавиться от старой папки new_mod. (переименовать там... или удалить) Кроме этого, программа обновит файлы translations/translatedlabels.json и translations/totallabels.json согласно текущему статусу перевода и выведет на экран статистику по переведенным полям.

4.3 Слияние мода с базой

В процессе работы с базой могут возникнуть ситуации, при которых нужно извлечь переводы полей из уже собранного мода и поместить их в базу. Для этого создана утилита tools/merge_from_mod.py. Для корректной работы данной утилиты необходимо поместить распакованный мод в папку <корневой каталог базы>/mod, затем запустить утилиту.

python tools/merge_from_mod.py

В процессе слияния могут возникнуть конфликты, разрешить которые будет предложено пользователю в интерактивном режиме.