Описание пользователя

Глава 4. Перевод интерфейса пользователя RDS

§4.2. Формат файлов описания интерфейса пользователя

Рассматиривается формат файлов, описывающих тексты, отображаемые на элементах интерфейса пользователя RDS. эти файлы используются при создании переводов текстов интерфейса.

Файлы описания интерфейса пользователя главной программы («Rds.exe»/«Rds64.exe») и стандартных моделей блоков (библиотек в папке «Dll\») хранятся в папке «Description\» внутри папки установки RDS. Эти файлы создаются разработчиками соответствующих программ и должны поддерживаться ими в актуальном состоянии при изменении этих программ – например, при добавлении новых окон, сообщений или пунктов меню. Работают с этими файлами только разработчики программ, обычным пользователям внутренняя структура этих файлов не важна, даже если эти пользователи сами переводят интерфейс на новый язык. Пользователь-переводчик может, при желании, посмотреть комментарии в файле описания, если их предусмотрел разработчик.

Каждый текст интерфейса пользователя адресуется в файле описания тремя именами: именем группы, именем объекта и именем параметра. Эти имена не должны содержать знака доллара, знака равенства, точки, запятой, двоеточия, точки с запятой и квадратных скобок, в остальном они выбираются разработчиком программы произвольно. В качестве имени группы обычно используется имя окна или крупного раздела интерфейса пользователя – двоичные файлы перевода, формируемые на основе файла описания, устроены так, что данные одной группы можно достаточно быстро найти по содержанию файла. Имя объекта обычно описывает конкретный объект интерфейса (кнопку, пункт меню и т.п.), а имя параметра – конкретный параметр этого объекта (текст, всплывающую подсказку, список вариантов для выбора и т.п.). Все имена групп и параметров вместе с идентификаторами этих параметров придумываются разработчиком. При этом желательно давать им более-менее осмысленные имена, чтобы переводчик мог понять, к чему относится тот или иной текст.

Для всех имен параметров в начале файла должны быть указаны типы (на данный момент поддерживаются только «строка» и «целое число») и целочисленные идентификаторы, по которым к ним будут обращаться программы для загрузки текстов.

В целом, файл описания интерфейса имеет формат обычного INI-файла Windows. Начинается он всегда со служебной секции «$Types» (в файле имена секций всегда заключаются в квадратные скобки), в которой после «Language=») через запятую указывается список имен параметров, которые могут использоваться в этом файле. Например, файл «rds.dat» начинается следующим образом:

  [$Types]
  Language=Caption,Text,Hint,Filter,Title,String,List

Эта запись означает, что для переводов на другие языки («Language») используются параметры «Caption», «Text», «Hint», «Filter», «Title», «String» и «List».

За секцией «$Types» должна следовать секция «$Params», в которой указываются типы и целые идентификаторы для всех использованных в файле имен параметров. В строках секции слева от знака равенства ставится имя параметра, справа – символ «S» (строка) или «I» (целое число) и, после запятой, целый идентификатор. В «rds.dat» эта секция выглядит так:

  [$Params]
  Caption=S,1
  Text=S,2
  Hint=S,3
  Filter=S,4
  Title=S,5
  String=S,6
  List=S,7

Эта запись означает, что все параметры имеют тип «строка» (символ «S»), параметр «Caption» имеет идентификатор 1, параметр «Text» – идентификатор 2 и т.д.

Далее следует произвольное количество секций следующего формата:

  [имя_группы]
  имя_объекта1.параметр1=значение
  имя_объекта1.параметр2=значение
  …
  имя_объекта2.параметр1=значение
  …

Каждая секция соответствует одной группе объектов (например, окну), имя группы является именем секции. Далее в строках секции перечисляются все объекты с их параметрами (имя параметра отделено от имени объекта точкой), и, после знака равенства, значение данного параметра данного объекта по умолчанию. Это значение будет попадать в экспортируемый файл перевода, если для него еще нет перевода в двоичном файле.

В «rds.dat» начало секции описания интерфейса пользователя главного окна RDS выглядит так:

  [TMainForm]
  M_File1.Caption=Файл
  M_NewSystem.Caption=Новый
  M_Templates.Caption=По шаблону
  M_LoadSystem.Caption=Загрузить...
  M_LoadInCopy.Caption=Загрузить, не закрывая...
  M_SaveSystem.Caption=Сохранить
  …

Здесь «TMainForm» – имя группы, использующееся для описания главного окна. Строка «M_File1.Caption=Файл» означает, что параметр «Caption» (заголовок) объекта «M_File1» (в данном случае это пункт главного меню «Файл») имеет значение по умолчанию «Файл».

В любом месте файла может находиться строка комментария, начинающаяся с символа «;» (точка с запятой). При разборе файла описания интерфейса такие строки игнорируются, разработчик может использовать их для того, чтобы оставить в файле какие-то пояснения для переводчика.

Следует учитывать, что для многострочных текстов коды перевода строк заменяются на принятые в языке программирования C сочетания «\n» или «\r\n» (какое именно из этих двух сочетаний использовать решает разработчик, составляющий файл описания). Многострочные тексты чаще всего встречаются в сообщениях пользователю и в описании выпадающих списков. Если с текстами сообщений пользователю все очевидно, то описания выпадающих списков имеют специальный формат и их нужно рассмотреть отдельно.

Рассмотрим выпадающий список выравнивания в параметрах строки текста для картинки блока, описанных в §2.10.5 (рис. 505).

Список содержит три варианта: «Влево», «По центру» и «Вправо». Соответствующая этому списку запись в файле описания интерфейса пользователя будет выглядеть следующим образом:

  CB_Alignment.List=0=Влево\n1=По центру\n2=Вправо

Здесь «CB_Alignment» – имя объекта, «List» – имя параметра, а многострочный текст после самого левого знака равенства описывает три варианта списка.

Текст «0=Влево\n1=По центру\n2=Вправо» состоит из трех строк: «0=Влево», «1=По центру» и «2=Вправо» (в качестве разделителя строк в общем тексте используется «\n»). Каждая строка имеет формат «индекс=значение», где индекс – начинающийся с нуля номер варианта в списке, а значение – текст этого варианта, видимый пользователю. При переводе этого текста формат строк должен быть сохранен: в качестве переведенного содержимого выпадающего списка в импортируемом файле перевода должен быть записан текст из трех строк формата «индекс=значение», описывающий варианты с индексами 0, 1 и 2 в любом порядке. RDS поддерживает два формата файлов экспорта/импорта перевода (см. §4.5 и §4.6), но, независимо от формата файла, сам текст выпадающего списка должен содержать эти три строки с указанием индексов элементов списка. Любые индексы, отличные от заложенных разработчиком в программу, будут игнорироваться: например, если в переведенном тексте будет содержаться строка «3=Other», в списке не появится дополнительный четвертый пункт.

Если в файле описания необходимо привести очень длинный текст, его для удобства можно разбить на несколько записей. Начало текста, как обычно, записывается после знака равенства в строку «имя_объекта.параметр=…», после которой добавляется новая строка «имя_объекта.параметр.1=…» с продолжением текста, затем «имя_объекта.параметр.2=…» и т.д пока текст не закончится. В продолжениях описания номера после имени параметра должны идти строго последовательно, их перестановка или вставка между ними других записей не допускается.

Пусть, например, необходимо описать в файле сообщение пользователю со следующим текстом: «Для данного блока была создана картинка. Задание прямоугольника с текстом в качестве внешнего вида блока приведет к удалению этой картинки. Задать прямоугольник с текстом?».

Это текст настоящего сообщения RDS, выводимого пользователю при переключении внешнего вида блока в окне его параметров. В файле описания «rds.dat» он записан как параметр «Text» объекта «PictureToTextBox» в секции «Messages». Если записать весь этот текст в одну строку, она будет очень длинной, и с ней неудобно будет работать. Поэтому описание этого сообщения может выглядеть следующим образом:

  PictureToTextBox.Text=Для данного блока была создана картинка.\x20
  PictureToTextBox.Text.1=Задание прямоугольника с текстом в качестве\x20
  PictureToTextBox.Text.2=внешнего вида блока приведет к удалению этой\x20
  PictureToTextBox.Text.3=картинки. Задать прямоугольник с текстом?

Здесь длинный текст разбит на четыре отдельных описания: начальное и три продолжения с дополнительными номерами «.1», «.2» и «.3». Следует учитывать, что начальные и конечные пробелы в каждой строке выбрасываются, поэтому, чтобы сохранить пробел в месте разбиения текста на отдельные строки, к концу каждой из строк добавлен код пробела «\x20». Если разбивать текст не по пробелу, то никаких кодов добавлять не нужно. Например, это же описание с тем же самым текстом сообщения может выглядеть и так:

  PictureToTextBox.Text=Для данного блока была создана картинка
  PictureToTextBox.Text.1=. Задание прямоугольника с текстом в качестве в
  PictureToTextBox.Text.2=нешнего вида блока приведет к удалению эт
  PictureToTextBox.Text.3=ой картинки. Задать прямоугольник с текстом?

Однако такое описание труднее читать человеку.