Операции с локализуемыми ресурсами

Руководство
Сложный

Инструменты, которые позволяют выполнять операции с локализуемыми ресурсами:

  • Creatio IDE.
  • База данных.
  • Система контроля версий SVN.
  • Файловая система.

Использовать Creatio IDE для выполнения операций с локализуемыми ресурсами 

Использование Creatio IDE позволяет выполнять следующие операции с локализуемыми ресурсами:

  • Добавить локализуемую колонку.
  • Добавить локализуемую строку.

Добавить локализуемую колонку 

Назначение локализуемой колонки — возможность отображения в интерфейсе приложения данных объекта на нескольких языках (т. н. мультиязычие). Значение локализуемой колонки зависит от выбранного в профиле пользователя языка. Локализуемая колонка настраивается в дизайнере объекта, а ее значение хранится в базе данных.

Чтобы добавить локализуемую колонку:

  1. Добавьте колонку, которую необходимо локализовать.

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

    2. На панели инструментов реестра раздела нажмите Добавить (Add) и выберите вид схемы (Объект (Object) или Замещающий объект (Replacing object)).

    3. В дизайнере объектов заполните свойства схемы.
    4. При необходимости добавьте колонки, которые требуется локализовать, или выберите существующую колонку объекта.

    5. В блоке свойств Общие (General) соответствующей колонки установите признак Локализуемый текст (Localizable text).

      На заметку. Типы колонок, которые можно локализовать:

      • Строка (50 символов) (Text (50 characters)).
      • Строка (250 символов) (Text (250 characters)).
      • Строка (500 символов) (Text (500 characters)).
      • Строка неограниченной длины (Unlimited length text).
    6. На панели инструментов дизайнера объектов нажмите Сохранить (Save), а затем Опубликовать (Publish).
  2. Выполните перевод значения локализуемой колонки. Для этого воспользуйтесь инструкцией статьи Перевести элементы интерфейса в разделе Переводы.

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

Добавить локализуемую строку 

Назначение локализуемой строки — возможность отображения в интерфейсе приложения данных модуля на нескольких языках (т. н. мультиязычие). Значение локализуемой строки зависит от выбранного в профиле пользователя языка. Локализуемая строка настраивается в дизайнере модуля и в дизайнере исходного кода, а ее значение хранится в базе данных.

Чтобы добавить локализуемую строку:

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

  2. На панели инструментов реестра раздела нажмите Добавить (Add) и выберите вид схемы.

    • Если необходимо локализовать строку клиентского модуля, то выберите один из вариантов:

      • Модуль (Module).
      • Модель представления страницы (Page view model).
      • Модель представления раздела (Section view model).
      • Модель представления детали с реестром (Detail (list) view model).
      • Модель представления детали с полями (Detail (fields) view model).
      • Замещающая модель представления (Replacing view model).

    • Если необходимо локализовать строку исходного кода, то выберите Исходный код (Source code).

  3. В дизайнере заполните свойства схемы.

  4. Добавьте строку, которую требуется локализовать.

    1. В контекстном меню узла Локализуемые строки (Localizable strings) нажмите кнопку scr_add_button.png.

    2. Заполните свойства локализуемой строки:

      • Код (Code) — название локализуемой строки (обязательное свойство). Должно содержать префикс (по умолчанию Usr), указанный в системной настройке Префикс названия объекта (код SchemaNamePrefix).
      • Значение (Value) — значение локализуемой строки. По умолчанию введенное значение сохраняется для выбранного в профиле пользователя языка. Чтобы задать значения локализуемой строки на других языках, нажмите кнопку scr_multilanguage_button.png.
    3. Для добавления локализуемой строки нажмите Добавить (Add).
  5. На панели инструментов дизайнера нажмите Сохранить (Save), а затем Опубликовать (Publish).

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

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

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

  • Получить локализуемые ресурсы из базы данных.
  • Обновить локализуемые ресурсы в базе данных.
  • Сохранить локализуемые ресурсы в базе данных.
  • Отключить локализуемые ресурсы в базе данных.

Получить локализуемые ресурсы из базы данных 

Классы, которые реализуют логику получения локализуемых ресурсов из базы данных:

  • Terrasoft.Core.Entities.EntitySchemaQuery — получение данных из базы данных через ORM-модель. Класс по умолчанию поддерживает работу с мультиязычными данными.
  • Terrasoft.Core.Entities.Entity — работа с сущностью базы данных.

Подробнее о получении данных из базы данных с помощью классов Terrasoft.Core.Entities.EntitySchemaQuery и Terrasoft.Core.Entities.Entity читайте в статье Доступ к данным через ORM.

Правила формирования выборки мультиязычных данных:

  • Если в профиле пользователя выбран основной язык, то выборка данных формируется из основной таблицы базы данных.
  • Если в профиле пользователя выбран дополнительный язык и в таблице [SysLocalizableValue] присутствует значение локализуемого ресурса, то выборка данных формируется из таблицы [SysLocalizableValue] базы данных.
  • Если в профиле пользователя выбран дополнительный язык и в таблице [SysLocalizableValue] отсутствует значение локализуемого ресурса, то выборка данных формируется из основной таблицы базы данных.

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

Чтобы настроить локализуемые представления:

  1. Создайте схему объекта для представления. Шаблон названия схемы: UsrVwИмяСхемыОбъекта.

    Обязательные составляющие названия схемы:

    • Префикс (по умолчанию Usr), указанный в системной настройке Префикс названия объекта (код SchemaNamePrefix).
    • Префикс Vw (сокращение от View) который указывает, что схема является представлением в базе данных.
  2. Настройте локализуемую колонку. Настройка локализуемых колонок описана в пункте Добавить локализуемую колонку.
  3. Добавьте новое представление локализации в базе данных.

Обновить локализуемые ресурсы в базе данных 

При изменении значения локализуемого ресурса в таблице [SysLocalizableValue] необходимо выполнить обновление локализуемых ресурсов в базе данных.

Чтобы для соответствующей схемы обновить локализуемые ресурсы в базе данных, необходимо с помощью SQL-запроса изменить значение колонки [IsChanged] таблицы [SysPackageResourceChecksum]. В другом случае при обновлении пакета в приложении возникнет конфликт локализуемых ресурсов. Он не будет обнаружен, что приведен к потере значения локализуемого ресурса.

Важно. Запрещено добавлять данные в таблицу [SysLocalizableValue] с использованием прямого SQL-запроса, поскольку в метаданных соответствующей схемы будет отсутствовать информация о добавленных локализуемых ресурсах. Чтобы добавить локализуемые ресурсы, необходимо использовать Creatio IDE, систему контроля версий SVN или файловую систему.

Сохранить локализуемые ресурсы в базе данных 

Чтобы сохранить локализуемые ресурсы, необходимо использовать метод Entity.SetColumnValue(), который может принимать параметры типа string и параметры типа LocalizableString.

Сохранить локализуемые ресурсы с использованием параметров типа string 

Особенности сохранения локализуемых ресурсов при использовании параметров типа string:

  • Если запись добавляется пользователем с дополнительным языком, то данные сохраняются и в основную таблицу объекта Entity, и в таблицу локализации объекта Entity.
  • Если запись изменяется пользователем с дополнительным языком, то данные сохраняются в таблицу локализации объекта Entity.
  • Если запись добавляется или изменяется пользователем с основным языком, то данные сохраняются в основную таблицу объекта Entity.

Шаблон формирования имени таблицы локализации: [SysИмяОсновнойТаблицыLcz].

Ниже приведен пример сохранения локализуемых ресурсов с использованием параметра типа string для пользователя с основным языком (русский).

Пример сохранения локализуемых ресурсов с использованием параметра типа string
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");
Entity entity = schema.CreateEntity(userConnection);

/* Установка для колонок значений по умолчанию. */
entity.SetDefColumnValues();

/* Установка значения для колонки [Название]. */
entity.SetColumnValue("Name", "Новый клиент");

/* Сохранение. */
entity.Save();
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

При выполнении этого кода пользователем с основным языком (русский) будет выполнен SQL-запрос к основной таблице [AccountType] базы данных. В параметре @P2 указано значение "Новый клиент".

SQL-запрос
exec sp_executesql N'
INSERT INTO [dbo].[AccountType]([Id], [Name], [CreatedOn], [CreatedById], [ModifiedOn], [ModifiedById], [ProcessListeners], [Description])
VALUES(@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8)',N'@P1 uniqueidentifier,@P2 nvarchar(12),@P3 datetime2(7),@P4 uniqueidentifier,@P5 datetime2(7),@P6 uniqueidentifier,@P7 int,@P8 nvarchar(4000)',@P1='3A820BC8-006D-42B7-A472-E331FBD73E20',@P2=N'Новый клиент',@P3='2021-09-20 09:40:23.0909251',@P4='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P5='2021-09-20 09:40:23.0929256',@P6='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P7=0,@P8=N''

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

Пример сохранения локализуемых ресурсов с использованием параметра типа string
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");
Entity entity = schema.CreateEntity(userConnection);
entity.SetDefColumnValues();
entity.SetColumnValue("Name", "New Customer");
entity.Save();
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

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

  1. SQL-запрос к основной таблице [AccountType] базы данных. SQL-запрос такой же, как и для основной локализации, но в параметре @P2 указано значение "New Customer".

    SQL-запрос
    exec sp_executesql N'
INSERT INTO [dbo].[AccountType]([Id], [Name], [CreatedOn], [CreatedById], [ModifiedOn], [ModifiedById], [ProcessListeners], [Description])
VALUES(@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8)',N'@P1 uniqueidentifier,@P2 nvarchar(12),@P3 datetime2(7),@P4 uniqueidentifier,@P5 datetime2(7),@P6 uniqueidentifier,@P7 int,@P8 nvarchar(4000)',@P1='94052A88-499D-4072-A28A-6771815446FD',@P2=N'New Customer',@P3='2021-09-20 10:07:00.3454424',@P4='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P5='2021-09-20 10:07:00.3454424',@P6='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P7=0,@P8=N''

  2. SQL-запрос в таблицу локализации [SysAccountTypeLcz]. В параметре @P5 указано значение "New Customer".

    SQL-запрос
    exec sp_executesql N'
INSERT INTO [dbo].[SysAccountTypeLcz]([Id], [ModifiedOn], [RecordId], [SysCultureId], [Name])
VALUES(@P1, @P2, @P3, @P4, @P5)',N'@P1 uniqueidentifier,@P2 datetime2(7),@P3 uniqueidentifier,@P4 uniqueidentifier,@P5 nvarchar(12)',@P1='911A721A-0E5A-4CC3-B6D9-9E5FE85FEC64',@P2='2021-09-20 10:07:00.3664442',@P3='94052A88-499D-4072-A28A-6771815446FD',@P4='A5420246-0A8E-E111-84A3-00155D054C03',@P5=N'New Customer'

Таким образом, в основную таблицу [AccountType] будет помещено значение, которое не соответствует основной локализации. Чтобы этого избежать, необходимо выполнять сохранение локализуемых ресурсов с использованием параметров типа LocalizableString.

Сохранить локализуемые ресурсы с использованием параметров типа LocalizableString 

Ниже приведен пример сохранения данных с использованием параметра типа LocalizableString.

Пример сохранения локализуемых ресурсов с использованием параметра типа LocalizableString
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");
Entity entity = schema.CreateEntity(userConnection);
entity.SetDefColumnValues();

/* Создание локализуемой строки с локализованными значениями для разных языковых культур. */
var localizableString = new LocalizableString();
localizableString.SetCultureValue(new CultureInfo("ru-RU"), "Новый клиент ru-RU");
localizableString.SetCultureValue(new CultureInfo("en-US"), "New Customer en-US");

/* Установка значения колонки с помощью локализуемой строки. */
entity.SetColumnValue("Name", localizableString);
entity.Save();

/* Результат будет выведен в текущей языковой культуре пользователя. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

При выполнении этого кода, независимо от выбранного в профиле пользователя языка, будут выполнены:

  1. SQL-запрос в основную таблицу [AccountType]. В параметре @P2 указано значение "Новый клиент ru-RU".

    SQL-запрос
    exec sp_executesql N'
INSERT INTO [dbo].[AccountType]([Id], [Name], [CreatedOn], [CreatedById], [ModifiedOn], [ModifiedById], [ProcessListeners], [Description])
VALUES(@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8)',N'@P1 uniqueidentifier,@P2 nvarchar(18),@P3 datetime2(7),@P4 uniqueidentifier,@P5 datetime2(7),@P6 uniqueidentifier,@P7 int,@P8 nvarchar(4000)',@P1='5AC81E4A-FCB2-4019-AE5B-0C485A5F65BD',@P2=N'Новый клиент ru-RU',@P3='2021-09-20 10:47:21.7471581',@P4='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P5='2021-09-20 10:47:21.7511578',@P6='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P7=0,@P8=N''

  2. SQL-запрос в таблицу локализации [SysAccountTypeLcz]. В параметре @P5 указано значение "New Customer en-US".

    SQL-запрос
    exec sp_executesql N'
INSERT INTO [dbo].[SysAccountTypeLcz]([Id], [ModifiedOn], [RecordId], [SysCultureId], [Name])
VALUES(@P1, @P2, @P3, @P4, @P5)',N'@P1 uniqueidentifier,@P2 datetime2(7),@P3 uniqueidentifier,@P4 uniqueidentifier,@P5 nvarchar(18)',@P1='6EC9C205-7F8B-455E-BC68-3D9AA6D7B7C0',@P2='2021-09-20 10:47:21.9272674',@P3='5AC81E4A-FCB2-4019-AE5B-0C485A5F65BD',@P4='A5420246-0A8E-E111-84A3-00155D054C03',@P5=N'New Customer en-US'

При выполнении этого кода пользователем с дополнительным языком и отсутствии значения локализуемой строки на основном языке, в основную таблицу [AccountType] будет добавлена запись со значением для дополнительного языка.

Отключить локализуемые ресурсы в базе данных 

Чтобы отключить локализуемые ресурсы, необходимо для свойства UseLocalization экземпляра класса EntitySchemaQuery установить значение false. Отключение локализуемых ресурсов не приводит к удалению локализуемых ресурсов из таблиц базы данных и не зависит от выбранного в профиле пользователя языка.

Пример отключения получения локализуемых ресурсов
/* Пользовательское подключение. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Формирование запроса. */
var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "City");

/* Добавление колонки в запрос. */
esqResult.AddColumn("Name");

/* Отключение механизма выборки локализованных данных. */
esqResult.UseLocalization = false;

/* Выполнение запроса к базе данных и получение всей результирующей коллекции объектов. */
var entities = esqResult.GetEntityCollection(userConnection);

/* Получение текста запроса. */
var s = esqResult.GetSelectQuery(userConnection).GetSqlText();

/* Возврат результата. */
return s;

При выполнении этого кода, независимо от выбранного в профиле пользователя языка, будет выполнен SQL-запрос к основной таблице [City] базы данных.

SQL-запрос
SELECT
    [City].[Name] [Name]
FROM
    [dbo].[City] [City] WITH(NOLOCK)

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

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

  • Обновить локализуемые ресурсы из хранилища SVN.
  • Фиксировать локализуемые ресурсы в хранилище SVN.

Описание работы с SVN содержится в статье Контроль версий в Subversion.

Обновить локализуемые ресурсы из хранилища SVN 

Чтобы обновить локализуемые ресурсы из хранилища SVN, необходимо выполнить обновление пакета из хранилища SVN. Обновление пакета подробно описано в статье Контроль версий в Creatio IDE.

Возможные состояния локализуемых ресурсов:

  • Изменено (Modified) — локализуемый ресурс изменен.
  • Добавлено (Added) — локализуемый ресурс добавлен.
  • Удалено (Deleted) — локализуемый ресурс удален.
  • Конфликт (Conflicted) — работа с локализуемым ресурсом выполнялась одновременно двумя разработчиками, один с которых зафиксировал изменения локализуемого ресурса в хранилище SVN.

Фиксировать локализуемые ресурсы в хранилище SVN 

Чтобы фиксировать локализуемые ресурсы в хранилище SVN, необходимо выполнить фиксацию пакета в хранилище SVN. Фиксация пакета подробно описана в статье Контроль версий в Creatio IDE.

Используя Creatio IDE, можно заблокировать пакет в хранилище SVN. Блокирование пакета позволяет избежать возникновения состояния Конфликт (Conflicted) локализуемого ресурса, поскольку отключена опция одновременной работы с пакетом. Например, один разработчик вносит изменения в локализуемые ресурсы пакета без его предварительной блокировки. При фиксации пакета в хранилище SVN может возникнуть ситуация, когда в текущем пакете другим разработчиком были изменены и зафиксированы в хранилище SVN эти же локализуемые ресурсы. В этом случае при обновлении пакета в Creatio IDE будет отображен перечень локализуемых ресурсов в состоянии Конфликт (Conflicted). Это означает, что версия и содержимое измененных локализуемых ресурсов не совпадают с версией и содержимым локализуемых ресурсов, зафиксированных в хранилище SVN. При выполнении фиксации изменений локализуемых ресурсов будут утеряны изменения, зафиксированные в хранилище SVN. Такие конфликтные ситуации необходимо решать вручную, используя SVN-клиенты, например, TortoiseSVN.

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

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

Чтобы редактировать локализуемые ресурсы из файловой системы:

  1. Настройте Creatio для работы в файловой системе. Подробнее читайте в статье Внешние IDE.
  2. Используя SVN-клиент, экспортируйте локализуемые ресурсы в файловую систему.
  3. Измените локализуемые ресурсы.
  4. Зафиксируйте изменения в хранилище SVN.

Важно. Значению локализуемого ресурса соответствует одна запись в таблице [SysLocalizableValue] базы данных. Эта запись содержит ссылки на соответствующие идентификаторы ([SysPackageId], [SysSchemaId], [SysCultureId]) и ключ ([Key]). Поэтому при фиксации ресурса с состоянием Конфликт (Conflicted) в таблицу будет записано последнее значение.

Смотрите также
Принципы разработки в Creatio IDE
Общие принципы работы с пакетами
Контроль версий в Subversion
Контроль версий в Creatio IDE
Внешние IDE
Перевести элементы интерфейса в разделе [Переводы]
Доступ к данным через ORM
Ресурсы
Официальный сайт TortoiseSVN
Получить локализуемые ресурсы из базы данных
Сложный

Пример 1 

Пример. С помощью класса Terrasoft.Core.Entities.EntitySchemaQuery получить локализуемые ресурсы для произвольной языковой культуры.

Класс Terrasoft.Core.Entities.EntitySchemaQuery позволяет выполнить выборку данных для произвольной языковой культуры (языковой культуры, которая отличается от дополнительной языковой культуры пользователя и основной языковой культуры приложения).

Чтобы получить локализуемые ресурсы для произвольной языковой культуры:

  1. Перед получением данных в экземпляре класса Terrasoft.Core.Entities.EntitySchemaQuery вызовите метод SetLocalizationCultureId(Guid cultureId).
  2. В метод SetLocalizationCultureId(Guid cultureId) передайте идентификатор языковой культуры, данные которой необходимо получить.
Выполнение выборки данных для произвольной языковой культуры
/* Пользовательское подключение. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Получение Id необходимой языковой культуры, например, итальянской. */
var sysCulture = new SysCulture(userConnection);
if (!sysCulture.FetchPrimaryInfoFromDB("Name", "it-IT"))
    {

    /* Ошибка, запись не найдена. */
    return "Культура не найдена";
}
Guid italianCultureId = sysCulture.Id;

/* Формирование запроса. */
var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "City");

/* Добавление колонки в запрос. */
esqResult.AddColumn("Name");

/* Установка необходимой локализации. */
esqResult.SetLocalizationCultureId(italianCultureId);

/* Выполнение запроса к базе данных и получение всей результирующей коллекции объектов. */
var entities = esqResult.GetEntityCollection(userConnection);

/* Получение текста запроса. */
var s = esqResult.GetSelectQuery(userConnection).GetSqlText();

/* Возврат результата. */
return s;

При выполнении этого кода будет выполнен SQL-запрос. Параметр @P1 принимает значение идентификатора записи ([Id]), которое хранится в переменной italianCultureId.

SQL-запрос
SELECT
    ISNULL([SysCityLcz].[Name], [City].[Name])[Name]
FROM
    [dbo].[City] [City] WITH(NOLOCK)
    LEFT OUTER JOIN [dbo].[SysCityLcz] [SysCityLcz] WITH(NOLOCK) ON ([SysCityLcz].[RecordId] = [City].[Id]
    AND [SysCityLcz].[SysCultureId] = @P1)

Пример 2 

Пример. С помощью метода FetchFromDB() класса Terrasoft.Core.Entities.Entity получить значение локализуемой колонки Название (Name) объекта схемы Тип контрагента (AccountType).

Методы FetchFromDB() класса Terrasoft.Core.Entities.Entity позволяют получить мультиязычные данные. Ниже приведен пример использования одной из перегрузок методов FetchFromDB() для пользователя с основной (русской) и дополнительной (например, английской) языковыми культурами. Эти методы можно использовать, например, в методах пользовательского веб-сервиса.

Пример использования метода FetchFromDB()
/* Пользовательское подключение. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Получение схемы [Тип контрагента]. */
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");

/* Создание экземпляра Entity (объекта). */
Entity entity = schema.CreateEntity(userConnection);

/* Коллекция имен колонок для выборки. */
List<string> columnNamesToFetch = new List<string> {
    "Name",
    "Description"
};
/* Получение данных для объекта, у которого значение колонки [Название] равно "Клиент". */
entity.FetchFromDB("Name", "Клиент", columnNamesToFetch);

/* Формирование и отправка ответа. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

При выполнении этого кода пользователем с основной языковой культурой (русской) будет выполнен SQL-запрос к основной таблице [AccountType] базы данных. В параметре @P1 указано значение "Клиент", которое определяет соответствующую запись основной таблицы [AccountType] базы данных.

SQL-запрос
exec sp_executesql N'
SELECT
    [AccountType].[Name] [Name],
    [AccountType].[Description] [Description]
FROM
    [dbo].[AccountType] [AccountType] WITH(NOLOCK)
WHERE
    [AccountType].[Name] = @P1',N'@P1 nvarchar(6)',@P1=N'Клиент'

При выполнении этого кода пользователем с дополнительной языковой культурой (например, английской) будет выполнен SQL-запрос к таблице локализации [SysAccountTypeLcz] базы данных. В параметре @P1 указано значение "Клиент", которое определяет соответствующую запись основной таблицы [AccountType] базы данных. В параметре @P2 указано значение идентификатора ([SysCultureId]) дополнительной языковой культуры из таблицы [SysCulture], которое определяет соответствующую запись таблицы локализации [SysAcountTypeLcz] базы данных.

SQL-запрос
exec sp_executesql N'
SELECT
    ISNULL([SysAccountTypeLcz].[Name], [AccountType].[Name]) [Name],
    ISNULL([SysAccountTypeLcz].[Description], [AccountType].[Description]) [Description]
FROM
    [dbo].[AccountType] [AccountType] WITH(NOLOCK)
    LEFT OUTER JOIN [dbo].[SysAccountTypeLcz] [SysAccountTypeLcz] WITH(NOLOCK) ON ([SysAccountTypeLcz].[RecordId] = [AccountType].[Id]
    AND [SysAccountTypeLcz].[SysCultureId] = @P2)
WHERE6
    [AccountType].[Name] = @P1',N'@P1 nvarchar(6),@P2 uniqueidentifier',@P1=N'Клиент',@P2='A5420246-0A8E-E111-84A3-00155D054C03'

В результате значению переменной Name для пользователя с русской языковой культурой соответствует значение "Клиент", а для пользователя с английской языковой культурой — "Customer".

Добавить локализуемую колонку
Средний

Пример. Добавить локализуемую колонку.

1. Создать объект 

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

  2. На панели инструментов реестра раздела нажмите Добавить —> Объект (Add —> Object).

    scr_add_entity_schema.png

  3. В дизайнере объекта заполните свойства схемы:

    • Код (Code) — "UsrLocalizableObject".
    • Заголовок (Title) — "LocalizableObject".
    • Родительский объект (Parent object) — выберите "BaseEntity".

2. Добавить локализуемую колонку 

  1. В контекстном меню узла Колонки (Columns) структуры объекта нажмите add_button.

  2. В выпадающем меню нажмите Строка —> Строка (50 символов) (Text —> Text (50 characters)).

  3. В дизайнере объекта заполните свойства добавляемой колонки:

    • Код (Code) — "UsrName".
    • Заголовок (Title) — "Name".
    • Установите признак Локализуемый текст (Localizable text).
  4. На панели инструментов дизайнера объектов нажмите Сохранить (Save), а затем Опубликовать (Publish).

Результат выполнения примера 

В результате выполнения примера в базе данных создана таблица локализации [SysUsrLocalizableObjectLcz], в которой будут храниться локализованные данные для всех локализуемых колонок.

Ресурсы
Пакет с реализацией примера
Локализовать представление в базе данных
Сложный

Пример. Создать представление, которое формирует выборку, состоящую из локализованных значений адресов контактов (колонка [Name] таблицы [AddressType] базы данных) и значений адресов контактов (колонка [Address] таблицы [ContactAddress] базы данных).

В Creatio реализована схема объекта Адрес контакта (ContactAddress). Колонка схемы ссылается на справочник Тип адреса (AddressType), который содержит локализуемую колонку Название (Name). Структура и связи таблиц представлены на рисунке ниже.

diagram.png
  • [ContactAddress] — таблица базы данных, которая содержит перечень значений адресов контактов. Связана с таблицей [AddressType] по колонке [AddressTypeId].
  • [AddressType] — таблица базы данных, которая содержит перечень типов адресов контактов. Колонка [Name] таблицы содержит перечень значений типов адресов на основном языке. Значения на дополнительных языках содержатся в таблице [SysAddressTypeLcz].
  • [SysAddressTypeLcz] — автоматически генерируемая системная таблица базы данных, которая содержит перечень локализованных значений типов адресов контактов. Связана с таблицей [AddressType] по колонке [RecordId] и с таблицей [SysCulture] по колонке [SysCultureId]. Колонка [Name] таблицы содержит перечень локализованных значений типов адресов контактов для языковой культуры, которая указана в колонке [SysCultureId] текущей таблицы.
  • [SysCulture] — системная таблица базы данных, которая содержит перечень языковых культур.

1. Создать схему объекта для представления 

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

  2. На панели инструментов реестра раздела нажмите Добавить —> Объект (Add —> Object).

    scr_add_entity_schema.png

  3. В дизайнере объекта заполните свойства схемы:

    • Код (Code) — "UsrVwContactAddress".
    • Заголовок (Title) — "ContactAddressView".
    • Родительский объект (Parent object) — выберите "BaseEntity".

  4. В блоке свойств Поведение (Behavior) установите признак Представление в базе данных (Represent Structure of Database View).

2. Добавить колонки 

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

    1. В контекстном меню узла Колонки (Columns) структуры объекта нажмите add_button.

    2. В выпадающем меню нажмите Строка —> Строка (50 символов) (Text —> Text (50 characters)).

    3. В дизайнере объекта заполните свойства добавляемой колонки:

      • Код (Code) — "UsrAddress".
      • Заголовок (Title) — "Address".

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

    1. В контекстном меню узла Колонки (Columns) структуры объекта нажмите add_button.

    2. В выпадающем меню нажмите Строка —> Строка (50 символов) (Text —> Text (50 characters)).

    3. В дизайнере объекта заполните свойства добавляемой колонки:

      • Код (Code) — "UsrAddressType".
      • Заголовок (Title) — "AddressType".
      • Установите признак Локализуемый текст (Localizable text).
    4. На панели инструментов дизайнера объектов нажмите Сохранить (Save), а затем Опубликовать (Publish).

3. Создать представления в базе данных 

  1. Создайте представление [UsrVwContactAddress] в базе данных. Для этого выполните SQL-запрос.

    SQL-запрос
    -- Название представления должно соответствовать названию таблицы.
CREATE VIEW dbo.UsrVwContactAddress
AS
SELECT
    ContactAddress.Id,
    -- Колонки представления должны соответствовать названиям колонок схемы.
    ContactAddress.Address AS UsrAddress,
    AddressType.Name AS UsrAddressType
FROM ContactAddress
INNER JOIN AddressType ON ContactAddress.AddressTypeId = AddressType.Id;

  2. Создайте локализуемое представление [SysUsrVwContactAddressLcz] в базе данных. Для этого выполните SQL-запрос.

    SQL-запрос
    -- Название представления должно соответствовать названию таблицы локализации.
CREATE VIEW dbo.SysUsrVwContactAddressLcz
AS
SELECT
    SysAddressTypeLcz.Id,
    ContactAddress.id AS RecordId,
    SysAddressTypeLcz.SysCultureId,
    -- Колонки представления должны соответствовать названиям колонок схемы.
    SysAddressTypeLcz.Name AS UsrAddressType    
FROM ContactAddress
INNER JOIN AddressType ON ContactAddress.AddressTypeId = AddressType.Id
INNER JOIN SysAddressTypeLcz ON AddressType.Id = SysAddressTypeLcz.RecordId;

В результате при чтении данных с помощью EntitySchemaQuery из колонки [UsrAddressType] представления [UsrVwContactAddress] будут отображены корректные значения для разных языков.

Результат выполнения примера 

Для проверки результата выполнения примера создайте пользовательский веб-сервис с аутентификацией на основе cookies.

1. Создать схему Исходный код 

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

  2. На панели инструментов реестра раздела нажмите Добавить —> Исходный код (Add —> Source code).

  3. В дизайнере схем заполните свойства схемы:

    • Код (Code) — "UsrViewLocalizationService".
    • Заголовок (Title) — "UsrViewLocalizationService".

    Для применения заданных свойств нажмите Применить (Apply).

2. Создать класс сервиса 

  1. В дизайнере схем добавьте пространство имен Terrasoft.Configuration.
  2. C помощью директивы using добавьте пространства имен, типы данных которых будут задействованы в классе.
  3. Добавьте название класса, которое соответствует названию схемы (свойство Код (Code)).
  4. В качестве родительского класса укажите System.Web.SessionState.IReadOnlySessionState.
  5. Для класса добавьте атрибуты [ServiceContract] и [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)].

3. Реализовать методы класса 

  1. Реализуйте метод, который вернет перечень типов адресов контактов и значений адресов контактов из созданного нелокализуемого представления [UsrVwContactAddress]. В дизайнере схем добавьте в класс метод public string GetNonLocalizableView(), который реализует конечную точку пользовательского веб-сервиса. С помощью EntitySchemaQuery метод отправит запрос к базе данных.

  2. Реализуйте метод, который вернет перечень типов адресов контактов и значений адресов контактов из созданного локализуемого представления [UsrVwContactAddress]. В дизайнере схем добавьте в класс метод public string GetLocalizableView(), который реализует конечную точку пользовательского веб-сервиса. С помощью EntitySchemaQuery метод отправит запрос к базе данных.

Исходный код пользовательского веб-сервиса UsrViewLocalizationService представлен ниже.

UsrViewLocalizationService
namespace Terrasoft.Configuration
{
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using System.Web;
    using Terrasoft.Core;
    using Terrasoft.Core.Entities;
    using System;
    using System.Collections.Generic;

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrViewLocalizationService : System.Web.SessionState.IReadOnlySessionState
    {

        [OperationContract]
        [WebInvoke(Method = "GET", UriTemplate = "GetNonLocalizableView")]
        public string GetNonLocalizableView()
        {
            var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
            var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "UsrVwContactAddress");
            esqResult.AddColumn("UsrAddress");
            esqResult.AddColumn("UsrAddressType");
            var entities = esqResult.GetEntityCollection(userConnection);
            var s = "";
            foreach (var item in entities)
            {
                s += item.GetTypedColumnValue<string>("UsrAddressType") + ": ";
                s += item.GetTypedColumnValue<string>("UsrAddress") + "; ";
            }
            return s;
        }

        [OperationContract]
        [WebInvoke(Method = "GET", UriTemplate = "GetLocalizableView")]
        public string GetLocalizableView()
        {
            var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
            var sysCulture = new SysCulture(userConnection);
            if (!sysCulture.FetchPrimaryInfoFromDB("Name", "ru-ru"))
            {
                return "Культура не найдена";
            }
            Guid CultureId = sysCulture.Id;

            var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "UsrVwContactAddress");
            esqResult.AddColumn("UsrAddress");
            esqResult.AddColumn("UsrAddressType");
            esqResult.SetLocalizationCultureId(CultureId);

            var entities = esqResult.GetEntityCollection(userConnection);
            var s = "";
            foreach (var item in entities)
            {
                s += item.GetTypedColumnValue<string>("UsrAddressType") + ": ";
                s += item.GetTypedColumnValue<string>("UsrAddress") + "; ";
            }
            return s;
        }
    }
}

На панели инструментов дизайнера нажмите Сохранить (Save), а затем Опубликовать (Publish).

Результат работы пользовательского веб-сервиса 

В результате выполнения примера в Creatio появится пользовательский веб-сервис UsrViewLocalizationService с конечными точками GetLocalizableView и GetNonLocalizableView.

Авторизуйтесь в приложении и из браузера обратитесь к конечной точке GetLocalizableView веб-сервиса.

Строка запроса
http://mycreatio.com/0/rest/UsrViewLocalizationService/GetLocalizableView

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

Из браузера обратитесь к конечной точке GetNonLocalizableView веб-сервиса.

Строка запроса
http://mycreatio.com/0/rest/UsrViewLocalizationService/GetNonLocalizableView

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

Ресурсы
Пакет с реализацией примера
Класс LocalizableValue<T>
Сложный

Пространство имен Terrasoft.Common.

Класс Terrasoft.Common.LocalizableValue<T> является базовым классом для классов Terrasoft.Common.LocalizableString (отвечает за отображение локализуемых строк) и Terrasoft.Common.LocalizableImage (отвечает за отображение локализуемых изображений), которые используются для работы с локализуемыми ресурсами.

Класс Terrasoft.Common.LocalizableValue<T> является шаблоном для локализуемых значений различных типов и предоставляет методы для работы с ними.

Note. Полный перечень свойств и методов класса LocalizableValue<T>, его родительских классов, а также реализуемых им интерфейсов, можно найти в документации Библиотеки .NET классов.

Свойства 

Value T

Возвращает и устанавливает локализуемое значение с учетом текущей языковой культуры.

HasValue bool

Возвращает признак, который определяет наличие локализуемого значения данного типа для текущей языковой культуры.

CultureValues IDictionary<CultureInfo,T>

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

Методы 

void ClearCultureValue(CultureInfo culture)

Удаляет локализуемое значение для поддерживаемых языковых культур.

Параметры
culture Языковая культура. 
T GetCultureValue(CultureInfo culture, bool throwIfNoManager)

Получает локализуемое значение указанного типа для поддерживаемых языковых культур. В зависимости от значения параметра throwIfNoManager, метод может сгенерировать исключение типа ItemNotFoundException, если для этого локализуемого значения не задан диспетчер ресурсов.

Параметры
culture Языковая культура.
throwIfNoManager Флаг, который указывает необходимость вызова исключения ItemNotFoundException. 
T GetCultureValueWithFallback(CultureInfo culture, bool throwIfNoManager)

Получает локализуемое значение указанного типа для поддерживаемых языковых культур. Если значение локализуемого ресурса для указанной языковой культуры не найдено, то возвращается значение на основной языковой культуре. В зависимости от значения параметра throwIfNoManager, метод может сгенерировать исключение типа ItemNotFoundException, если для этого локализуемого значения не задан диспетчер ресурсов.

Параметры
culture Языковая культура.
throwIfNoManager Флаг, который указывает необходимость вызова исключения ItemNotFoundException. 
bool HasCultureValue(CultureInfo culture)

Определяет, существует ли локализуемое значение для заданной языковой культуры.

Параметры
culture Языковая культура. 
void LoadCultureValues()

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

void SetCultureValue(CultureInfo culture, T value)

Устанавливает заданное локализуемое значение для заданной языковой культуры.

Параметры
culture Языковая культура.
value Локализуемое значение.