Локализация файлового контента

Общие сведения

Начиная с версии 7.11.3 в bpm'online появилась возможность добавлять файловый контент (*.js-, *.css-файлы, изображения и др.) в пользовательские пакеты.

Файловый контент пакетов — любые файлы, используемые приложением. Файловый контент не обрабатывается web-сервером и является статическим (см. "Статический клиентский контент в файловой системе"), что повышает скорость работы приложения.

Подробнее о файловом контенте можно узнать из статьи "Использование файлового контента в пакетах".

Локализация с использованием конфигурационных ресурсов

Для перевода ресурсов на разные языки рекомендуется использовать отдельный модуль с локализуемыми ресурсами, созданный встроенными средствами разработки bpm'online в разделе [Конфигурация]. Пример исходного кода такого модуля приведен ниже:

define("Module1", ["Module1Resources"], function(res) {
  return res;
});

Для подключения локализуемых ресурсов в модуль, который определяется в файловом контенте пакета, достаточно сослаться на модуль с ресурсами. Например:

define("MyPackage-MyModule", ["Module1"], function(module1) {
  console.log(module1.localizableStrings.MyString);
});

Локализация с использованием плагина i18n

i18n — это плагин для AMD-загрузчика (например, RequireJS), предназначенный для загрузки локализуемых строковых ресурсов. Исходный код плагина можно найти в репозитории https://github.com/requirejs/i18n. Документация доступна по ссылке http://requirejs.org/docs/api.html#i18n.

Чтобы выполнить локализацию файлового контента с помощью плагина RequireJS i18n, выполните следующие действия.

1. Поместите плагин в директорию с *.js-файлами исходных кодов ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\MyPackage1\content\js\i18n.js.

Здесь MyPackage1 — рабочий каталог пакета MyPackage1 (см. "Использование файлового контента в пакетах").

2. Создайте каталог ..\MyPackage1\content\nls и поместите в него один или несколько *.js-файлов с локализуемыми ресурсами. Имена файлов могут быть произвольными. Содержимое файлов — AMD модули, объекты которых имеют следующую структуру:

• Поле "root", содержащее коллекцию ключ-значение, где ключ — это название локализуемой строки, а значение — локализуемая строка на языке по умолчанию. Значение будет использоваться, если запрашиваемый язык не поддерживается.
• Поля, имена которых являются стандартными кодами поддерживаемых культур (например "en-US", "ru-RU"), а значение имеет логический тип. Может быть true, если поддерживаемая культура включена, и false — если отключена.

Например, добавлен файл ..\MyPackage1\content\js\nls\ContactSectionV2Resources.js со следующим содержимым:

define({
    "root": {
        "FileContentActionDescr": "File content first action (Default)",
        "FileContentActionDescr2": "File content second action (Default)"
    },
    "en-US": true,
    "ru-RU": true
});

3. В каталоге ..\MyPackage1\content\nls создайте папки, названия которых соответствуют коду той культуры, локализация которой будет в них размещена (например "en-US", "ru-RU"). Например, если поддерживаются только русская и английская культуры, то структура каталогов будет следующей:

content
    nls
        en-US
        ru-RU

4. В каждый созданный каталог локализации поместите такой же набор файлов *.js-файлов с локализуемыми ресурсами, как и в корневой папке ..\MyPackage1\content\nls. Содержимое файлов — AMD модули, объекты которых являются коллекциями ключ-значение, где ключ — это наименование локализуемой строки, а значение — строка на языке, соответствующем названию папки (коду культуры).

Например, если поддерживаются только русская и английская культуры, то необходимо создать два файла ContactSectionV2Resources.js. Содержимое файла ..\MyPackage1\content\js\nls\en-US\ContactSectionV2Resources.js, соответствующее английской культуре:

define({
    "FileContentActionDescr": "File content first action",
    "FileContentActionDescr2": "File content second action"
});

Содержимое файла ..\MyPackage1\content\js\nls\ru-RU\ContactSectionV2Resources.js, соответствующее русской культуре:

define({
    "FileContentActionDescr": "Первое действие файлового контента"    
});

5. Отредактируйте содержимое файла bootstrap.js.

• Подключите плагин i18n, указав его название в виде псевдонима "i18n" в конфигурации путей RequireJS и прописав соответствующий путь к нему в свойстве paths.
• Укажите плагину культуру, которая является текущей для пользователя. Для этого свойству config объекта конфигурации библиотеки RequireJS присвойте объект со свойством i18n, которому, в свою очередь, присвойте объект со свойством locale и значением, полученным из глобальной переменной Terrasoft.currentUserCultureName (код текущей культуры).
• Для каждого файла с ресурсами локализации укажите соответствующие псевдонимы и пути в конфигурации путей RequireJS. При этом псевдоним должен являться URL-путем относительно директории nls.

Пример содержимого файла ..\MyPackage1\content\js\bootstrap.js:

(function() {
    require.config({
        paths: {            
            "MyPackage1-Utilities": Terrasoft.getFileContentUrl("MyPackage1", "content/js/Utilities.js"),
            "MyPackage1-ContactSectionV2": Terrasoft.getFileContentUrl("MyPackage1", "content/js/ContactSectionV2.js"),
            "MyPackage1-CSS": Terrasoft.getFileContentUrl("MyPackage1", "content/css/MyPackage.css"),
            "MyPackage1-LESS": Terrasoft.getFileContentUrl("MyPackage1", "content/less/MyPackage.less"),
            "i18n": Terrasoft.getFileContentUrl("MyPackage1", "content/js/i18n.js"),
            "nls/ContactSectionV2Resources": Terrasoft.getFileContentUrl("MyPackage1", "content/js/nls/ContactSectionV2Resources.js"),
            "nls/ru-RU/ContactSectionV2Resources": Terrasoft.getFileContentUrl("MyPackage1", "content/js/nls/ru-RU/ContactSectionV2Resources.js"),
            "nls/en-US/ContactSectionV2Resources":  Terrasoft.getFileContentUrl("MyPackage1", "content/js/nls/en-US/ContactSectionV2Resources.js")
        },
        config: {
            i18n: {
                locale: Terrasoft.currentUserCultureName
            }
        }
    });
})();

6. Используйте ресурсы в нужном модуле, указав в массиве зависимостей требуемый модуль с ресурсами с префиксом "i18n!". Например, если необходимо использовать локализуемую строку FileContentActionDescr (см. шаги 2, 4) как заголовок для нового действия в разделе [Контакты], то в файл ..\MyPackage1\content\js\ContactSectionV2.js нужно добавить следующее содержимое:

define("MyPackage1-ContactSectionV2", ["i18n!nls/ContactSectionV2Resources", 
    "css!MyPackage1-CSS", "less!MyPackage1-LESS"], function(resources) {
    return {
        methods: {
            getSectionActions: function() {
                var actionMenuItems = this.callParent(arguments);
                actionMenuItems.addItem(this.getButtonMenuItem({"Type": "Terrasoft.MenuSeparator"}));
                actionMenuItems.addItem(this.getButtonMenuItem({
                    "Click": {"bindTo": "onFileContentActionClick"},
                    "Caption": resources.FileContentActionDescr
                }));
                return actionMenuItems;
            },
            onFileContentActionClick: function() {
                console.log("File content clicked!")
            }
        },
        diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/
    }
});