Раздел “Локализация”¶

Работа с языками в системе¶

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

Имя колонки	Тип данных	Описание
ID	Int16 Not Null	Код языка в системе
Caption	String(256) Not Null	Название языка в системе. Именно оно отображается в настройках языка в карточке “Мои настройки”
Code	AsciiString(3) Not Null	Строковый код языка согласно стандарту `ISO 639`. Рекомендуется указывать код из `ISO 639-1` и лишь в случае его отсутствия для требуемой культуры использовать код из `ISO 639-2`
FallbackCode	AsciiString(3) Null	Строковый код резервного языка согласно стандарту `ISO 639`. Рекомендуется использовать код из `ISO 639-1`, если он отсутствует - из `ISO 639-2`. Резервный язык используется для подстановки переводов, отсутствующих в локализации текущего языка. Например, для белорусского языка можно задать русский в качестве резервного: при отсутствии перевода на белорусский будет использоваться русский. Рекомендуется использовать эту настройку только в продуктивном контуре. В процессе разработки целесообразно устанавливать значение в `NULL` для оперативного обнаружения строк, нуждающихся в локализации. Значение колонки должно совпадать с `Code` языка, выбранного в качестве резервного

Important

При использовании FallbackCode запрещены любые циклические зависимости — как прямые (язык ссылается сам на себя напрямую), так и косвенные (через цепочку других языков). Наличие такого цикла приведёт к сбою в работе системы.

Note

При локализации через хранимые функции (например, в представлениях) используется только один уровень резервного языка. Во всех остальных сценариях применяется многоуровневая локализация.

Как правило, в базовую поставку TESSA входят два языка: английский и русский.

Important

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

Библиотеки и строки¶

Раздел “Локализация” предназначен для управления библиотеками и строками локализации. Библиотеки содержат наборы логически сгруппированных строк, относящихся к одной предметной области, так, библиотека Common содержит строки общего назначения, Forums - строки, относящиеся к подсистеме обсуждений, и т.д.

Tip

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

У каждой библиотеки есть следующий набор свойств.

Название	Описание
Имя	Название библиотеки (идентификатор)
Приоритет	Приоритет (старшинство) библиотеки. Библиотеки с более высоким приоритетом переопределяют данные из библиотек с меньшим приоритетом. Это позволяет заменять стандартные строки системных библиотек в библиотеке проекта без их прямого изменения
Отсоединённые языки	Задаёт список кодов языков согласно стандарту `ISO 639-1`, разделённых точкой с запятой (`;`), данные которых должны храниться в файлах `.jculture`, отдельно от файла `.jlocalization` основной библиотеки локализации

Tip

Библиотеки локализации хранятся в файле ИмяБиблиотеки.jlocalization, в то время как файлы отсоединённых языков (или культур) хранятся в файлах ИмяБиблиотеки.КодЯзыка.jculture. Формат файла .jculture максимально прост и является ассоциативным списком (или словарём), хранящимся в виде json объекта, в котором каждое поле является именем (алиасом) строки локализации, а значение хранит перевод этой строки на целевой язык.

При выделении библиотеки отображается список локализованных строк этой библиотеки:

Над списком строк расположено поле для поиска по всем видимым колонкам. Кнопка Колонки таблицы управляет составом отображаемых данных, что может расширить или сузить область поиска.

Виртуальная библиотека All libraries (Все библиотеки) позволяет увидеть все локализованные строки из всех библиотек, а также осуществлять поиск по всему набору строк.

Каждая локализованная строка содержит глобальное имя (алиас), комментарий для пояснения контекста использования и набор переводов, как правило, на русский и английский языки.

Tip

При совпадении имён (алиасов) локализованных строк в разных библиотеках система выбирает значение из библиотеки с более высоким приоритетом. Это позволяет переопределять значения без изменения системных библиотек и сохраняет изменения при их обновлении до новых версий, предотвращая перезапись.

Управление библиотеками локализации¶

Ниже представлены основные операции, выполняемые с библиотеками.

Создание новой библиотеки осуществляется с помощью кнопки на панели инструментов. В открывшемся контекстном меню необходимо выбрать пункт Библиотека локализации.
Удаление библиотеки производится через пункт Удалить контекстного меню, либо нажатием на кнопку , которая появляется при наведении курсора на строку.
Редактирование параметров библиотеки выполняется с помощью кнопки , появляющейся при наведении курсора на строку. После нажатия открывается диалог редактирования параметров библиотеки: имени (алиаса), приоритета (при использовании строк локализации) и отсоединённых языков. Для сохранения изменений используется кнопка , для отмены изменений используется кнопка .
Массовое создание строк для целевого языка позволяет быстро создать основу для перевода строк на требуемый язык, основываясь на заданном языке. Для этого необходимо:
- выбрать интересующую библиотеку и нажать на кнопку на панели инструментов;
- выбрать пункт Добавить строки контекстного меню и определить целевой язык, для которого необходимо создать перевод;
- в открывшемся диалоге необходимо указать базовый язык, из которого будут скопированы строки в целевой язык;
- после того, как в библиотеку будут добавлены строки целевого языка, необходимо сохранить изменения.
Tip

Данная команда является основой для создания перевода библиотеки на новый язык, поддержка которого добавляется в систему.

Important

Добавить поддержку нового языка во все имеющиеся библиотеки локализации можно, выполнив описанную операцию для виртуальной библиотеки Все библиотеки (All libraries).

Tip

Добавить новый язык локализации на основе существующего можно также при помощи специальной команды tadmin.
Сохранение всех изменений, сделанных в библиотеках, выполняется нажатием на кнопку Сохранить всё или при помощи комбинации клавиш Ctrl+S.

Important

Важно помнить, что сохранение, выполняемое таким образом, происходит в базу данных. Для сохранения в файлы на диск необходимо использовать команды экспорта.
Обновление библиотеки локализации (загрузка данных из базы) может использоваться для отмены несохраненных изменений и выполняется при помощи кнопки или нажатием клавиши F5.
Экспорт библиотеки используется для её сохранения во внешний файл .jlocalization, при этом все отсоединённые языки будут помещены в отдельных файлах .jculture. Экспорт можно выполнить, нажав кнопку Экспорт и выбрав пункт Экспорт в файл…, либо с помощью клавиш Ctrl+E.

Tip

Для экспорта всех библиотек необходимо выбрать библиотеку Все библиотеки (All libraries). В этом случае вместо диалога сохранения файла будет отображён диалог выбора директории, в которую требуется сохранить все библиотеки. Рекомендуется сохранять библиотеки в директории Configuration -> Localization.

Tip

Данный режим полезен для хранения библиотек локализации в репозитории и отслеживания изменений.
Экспорт библиотеки в файл формата .xlsx может быть использован для передачи данных переводчику. В файле будут содержаться строки локализации для всех языков и комментарии к ним. Экспорт в файл формата .xlsx можно выполнить, нажав кнопку Экспорт и выбрав пункт Экспорт в Excel….

Tip

Для экспорта всех библиотек необходимо выбрать библиотеку Все библиотеки (All libraries). В этом случае вместо диалога сохранения файла будет отображён диалог выбора директории, в которую требуется сохранить все библиотеки.

Tip

Экспортировать данные библиотеки локализации .jlocalization в .xlsx файл можно также при помощи специальной команды tadmin.
Импорт библиотеки локализации из файла .jlocalization с учётом отсоединённых языков в файлах .jculture можно выполнить, нажав кнопку Импорт и выбрав пункт Импорт из файла, либо с помощью клавиш Ctrl+I. После импорта необходимо сохранить изменения, чтобы они вступили в силу.
Импорт библиотеки локализации из файла .xlsx можно выполнить, нажав кнопку Импорт и выбрав пункт Импорт из Excel…. После импорта необходимо сохранить изменения, чтобы они вступили в силу.

Управление строками локализации¶

Основные свойства строк локализации:

Название	Описание
Название	Имя или алиас строки, по которому она может быть найдена в системе
Комментарий	Описание назначения строки, иногда с вариантами её использования. Рекомендуется всегда заполнять это поле
Список переводов	Список переводов строки на разные языки, состоящий из пар: код языка и перевод
Код языка	Символьный код языка в соответствии со стандартом `ISO 639-1`. Иногда вместо него используется термин культура
Перевод	Перевод строки на заданный язык

Основные операции, выполняемые со строками локализации в рамках выбранной библиотеки:

Создание новой строки локализации. Для создания новой строки необходимо щёлкнуть правой клавишей мыши в области просмотра строк библиотеки и в появившемся контекстном меню выбрать пункт Добавить, после чего строка локализации будет создана и откроется окно её редактирования.

Tip

Рекомендуется называть строки локализации начиная с префикса, используемого для библиотеки.
Редактирование строки локализации. Для открытия окна редактирования необходимо дважды щёлкнуть по строке левой клавишей мыши. Добавить перевод строки для нового языка можно, нажав на кнопку Добавить и выбрав нужный язык - в списке переводов добавится новая строка для выбранного языка, которую необходимо заполнить. Удалить перевод строки можно с помощью кнопки с изображением крестика в правом углу блока перевода. Для подтверждения изменений следует нажать Сохранить, для их отмены - Отменить изменения.
Удаление строки локализации. Для удаления необходимо щёлкнуть по строке правой клавишей мыши и выбрать в контекстном меню пункт Удалить, либо использовать клавишу Delete.

Управление локализацией при помощи команд `tadmin`¶

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

Important

Все рассматриваемые далее команды работают с файлами .jocalization и .jculture.

Рассмотрим работу с дополнительными языками на примере словенского. Сначала нужно добавить поддержку этого языка в систему, для этого следует в разделе Схема приложения Tessa Admin перейти по пути Platform -> System -> Languages, выбрать в дереве узел Записи и нажать кнопку Добавить строку. Поддержка языка таким образом будет добавлена, однако для него отсутствуют записи в библиотеках локализации, соответственно, при переключении на этот язык все надписи системы будут отсутствовать.

Important

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

Добавление локализации для нового языка¶

Добавление перевода данных системы на новый язык выполняется при помощи следующих команд tadmin:

CopyCulture - выполняет копирование строк локализации с заданного языка на целевой язык, тем самым обеспечивая базовые данные для работы пользователя;
ExportDiffCulture - готовит файл в формате .xlsx для предоставления переводчику. Файл содержит название строки локализации, комментарий к ней, позволяющий переводчику лучше понять контекст перевода, строку на базовом языке и строку на целевом языке (как правило, является копией строки на базовом языке, реже, строкой машинного перевода);
ImportDiffCulture - выполняет перенос данных из файла .xlsx, содержащего необходимый перевод, в соответствующую библиотеку локализации.

Создание нового языка при помощи команды `CopyCulture`¶

Команда CopyCulture предоставляет множество возможностей для использования, но здесь будут рассмотрены те из них, что относятся к созданию полной копии языка.

Наиболее простой вариант команды:

tadmin.exe CopyCulture "C:\workspace\tessa\Configuration\Localization" -from:en -to:sl -nologo

Команда выполняет добавление локализации для словенского языка как копии с английского языка для всех библиотек локализации. При этом новый язык добавляется в основную библиотеку локализации не как отсоединённый.

Note

Аналогичного результата можно достичь с помощью операции массового создания строк целевого языка в приложении Tessa Admin.

Второй вариант команды позволяет добавить новый язык в библиотеки локализации в качестве отсоединённого, т.е. добавляется не в основной файл .jlocalization, а в файл .jculture:

tadmin.exe CopyCulture "C:\workspace\tessa\Configuration\Localization" -from:en -to:sl -detached -nologo

Tip

Рекомендуется добавлять новые языки в систему в качестве отсоединённых.

Note

Данную операцию нельзя выполнить средствами Tessa Admin.

Третий вариант команды позволяет сохранить существующие переводы строк на целевой язык, если они есть:

tadmin.exe CopyCulture "C:\workspace\tessa\Configuration\Localization" -from:en -to:sl -detached -empty -nologo

Tip

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

Note

Аналогичного результата можно достичь с помощью операции массового создания строк целевого языка в Tessa Admin, добавив словенский язык в качестве отсоединённого.

Подготовленную базу для перевода можно загрузить в систему при помощи Tessa Admin, выполнив импорт из файла, выбрав все библиотеки и сохранив изменения. После этого в пользовательском интерфейсе для словенского появятся строки базового языка, в данном случае, английского. С системой уже можно работать, но это всё ещё не целевой язык.

Подготовка данных для первичного перевода при помощи команды `ExportDiffCulture`¶

Подготовка данных для предоставления переводчику может быть осуществлена при помощи команды ExportDiffCulture:

tadmin.exe ExportDiffCulture "C:\workspace\tessa\Configuration\Localization" -base:en -target:sl "-o:C:\workspace\tessa\Configuration\Localization\translate" -nologo

Каждый файл содержит название строки в системе, комментарий, позволяющий лучше понять контекст использования строки, строку на базовом языке и строку на целевом языке (как правило, являющуюся копией строки на базовом языке):

Note

Данную операцию нельзя выполнить средствами Tessa Admin, поскольку в нём выгружаются строки для всех языков в системе.

Импорт первичного перевода при помощи команды `ImportDiffCulture`¶

Команда ImportDiffCulture выполняет перенос данных, подготовленных переводчиком, из файла .xlsx в файл .jlocalization или в .jculture- случае, если язык хранится в библиотеке как отсоединённый:

tadmin.exe ImportDiffCulture "C:\workspace\tessa\Configuration\Localization\translate" "-o:C:\workspace\tessa\Configuration\Localization" -target:sl -nologo

Note

Данную операцию нельзя выполнить средствами Tessa Admin, поскольку в нём выгружаются строки для всех языков в системе.

Загрузка подготовленного перевода выполняется через Tessa Admin путём импорта файла с выбором всех библиотек. После сохранения изменений перевод отображается в пользовательском интерфейсе для словенского языка.

Поддержание локализации для языка в актуальном состоянии¶

Со временем в библиотеках локализации возможны добавление, удаление и изменение строк. Актуализация перевода на целевом языке выполняется с помощью команд CopyCulture, ExportDiffCulture и ImportDiffCulture, описанных выше, а также команды ValidateLocalization, выполняющей проверку библиотек на внутреннюю согласованность и сохранение согласованных данных.

Important

Все рассматриваемые операции нельзя выполнить средствами Tessa Admin.

Добавление перевода новых строк на целевой язык при помощи команды `CopyCulture`¶

Команда CopyCulture может использоваться не только для полного копирования данных с одного языка на другой, но и для их частичного переноса.

Example

Пусть в системе появилась новая строка локализации для базового языка, но она не была добавлена для целевого языка. Создадим базовый перевод при помощи команды CopyCulture:

tadmin.exe CopyCulture "C:\workspace\tessa\Configuration\Localization" -from:en -to:sl -empty -nologo

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

Note

Команда CopyCulture допускает использование флага -detached наряду с -empty для перевода языка в состояние отсоединённого с сохранением данных в файл .jculture.

Подготовка данных для перевода при помощи команды `ExportDiffCulture`¶

Команда ExportDiffCulture может использоваться для сравнения разных версий библиотек локализации.

Example

Получение набора модифицированных данных для передачи переводчику осуществляется путём сравнения текущего набора библиотек локализации (базовый набор) с библиотеками более ранних версий (сравниваемый набор) при помощи команды ExportDiffCulture:

tadmin.exe ExportDiffCulture "C:\workspace\tessa\Configuration\Localization" "C:\workspace\tessa\Configuration\old\Localization" -base:en -target:sl "-o:C:\workspace\tessa\Configuration\Localization\translate" -nologo

Таким образом будут подготовлены файлы .xlsx для библиотек, отличающихся от более ранних версий.

Tip

Получить более ранние версии библиотек проще всего с помощью системы хранения версий (репозитория).

Important

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

Импорт перевода при помощи команды `ImportDiffCulture`¶

Команда ImportDiffCulture выполняет перенос данных из файла .xlsx в файл .jlocalization или в .jculture - случае, если язык хранится в библиотеке как отсоединённый.

Example

Сделаем перевод строки на целевой язык:

Импортировать эти данные в соответствующие библиотеки локализации можно командой ImportDiffCulture:

tadmin.exe ImportDiffCulture "C:\workspace\tessa\Configuration\Localization\translate" "-o:C:\workspace\tessa\Configuration\Localization" -target:sl -nologo

Подготовленный перевод можно загрузить в систему при помощи Tessa Admin, выполнив импорт из файла, выбрав все библиотеки и сохранив изменения.

Поддержание библиотек в согласованном состоянии при помощи команды `ValidateLocalization`¶

Со временем данные библиотек, особенно состоящих из отсоединённых языков, могут утратить согласованность. Например, строка локализации может быть удалена из основного файла библиотеки .jlocalization, но сохраниться в файлах отсоединённых языков .jculture. Привести данные в согласованное состояние можно при помощи команды ValidateLocalization.

Example

Удалим одну строку из основного файла библиотеки Acl.jlocalization. Таким образом, был модифицирован только один файл .jlocalization, библиотека сейчас находится в несогласованном состоянии, поскольку данные для строки остались в файле .jculture.

Приведём библиотеку к согласованному состоянию, выполнив команду ValidateLocalization:

tadmin.exe ValidateLocalization "C:\workspace\tessa\Configuration\Localization" -nologo

Команда удалит уже несуществующую строку из файла .jculture.

Переопределение строк локализации в web-сервисе без изменения содержимого библиотек¶

Переопределение отдельных строк локализации без изменения содержимого библиотек возможно через конфигурационный файл web-сервиса app.json, для этого в секции Settings нужно добавить секцию Localization и определить в ней нужные строки в формате ключ: значение. Ключ формируется как lang:stringName, где lang - код целевого языка согласно стандарту ISO 639, а stringName - имя строки локализации. Значение же задаёт текст, используемый для указанной строки и языка.

Note

Строки локализации, определяемые в данной секции, участвуют в механизме подстановки отсутствующих строк основного языка, если для него указан резервный язык.

Example

Например, чтобы переименовать рабочее место пользователя в “Моё место”, нужно в секции Settings добавить секцию Localization следующего вида:

{
  "Settings": {
    "Localization": {
      "ru:Workplaces_User": "Моё место",
      "en:Workplaces_User": "My place",
    }
  }
}

Note

Механизм предназначен для использования на этапе первичной настройки web-сервиса и не предполагает частого применения для изменения локализации. Для применения изменений на стороне клиентов web-сервиса требуется сброс локальных кэшей метаинформации с использованием команды tadmin IncrementVersion.

Использование локализации в настройке и разработке системы¶

Использование локализации в настройке и разработке системы подробно описано в руководстве разработчика.

Раздел “Локализация”¶

Работа с языками в системе¶

Библиотеки и строки¶

Управление библиотеками локализации¶

Управление строками локализации¶

Управление локализацией при помощи команд tadmin¶

Добавление локализации для нового языка¶

Создание нового языка при помощи команды CopyCulture¶

Подготовка данных для первичного перевода при помощи команды ExportDiffCulture¶

Импорт первичного перевода при помощи команды ImportDiffCulture¶

Поддержание локализации для языка в актуальном состоянии¶

Добавление перевода новых строк на целевой язык при помощи команды CopyCulture¶

Подготовка данных для перевода при помощи команды ExportDiffCulture¶

Импорт перевода при помощи команды ImportDiffCulture¶

Поддержание библиотек в согласованном состоянии при помощи команды ValidateLocalization¶

Переопределение строк локализации в web-сервисе без изменения содержимого библиотек¶

Использование локализации в настройке и разработке системы¶

Управление локализацией при помощи команд `tadmin`¶

Создание нового языка при помощи команды `CopyCulture`¶

Подготовка данных для первичного перевода при помощи команды `ExportDiffCulture`¶

Импорт первичного перевода при помощи команды `ImportDiffCulture`¶

Добавление перевода новых строк на целевой язык при помощи команды `CopyCulture`¶

Подготовка данных для перевода при помощи команды `ExportDiffCulture`¶

Импорт перевода при помощи команды `ImportDiffCulture`¶

Поддержание библиотек в согласованном состоянии при помощи команды `ValidateLocalization`¶