Skip to main content
Version: 8.2

Localize the file content using the i18n plug-in

Level: advanced

i18n is a plug-in for an AMD loader (for example, RequireJS). Use it to load the localizable string resources. Download the plug-in source code from the GitHub repository.

1. Add the plug-in​

Place the plug-in in the ..\Terrasoft.WebApp\Terrasoft.Configuration\Pkg\MyPackage1\content\js\i18n.js directory with *.js source code files.

Where MyPackage1 is the development directory of the MyPackage1 package.

2. Create a directory with localizable resources​

Create the ..\MyPackage1\content\nls directory and place the *.js files with localizable resources there.

You can add one or more resource files. File names can be arbitrary. The files contain AMD modules, which, in turn, contain objects.

The structure of AMD module objects:

  • Root field.

    The "root" field contains the "key-value" collection, where the "key" is the name of a localizable string and the "value" is the localizable string in the default language. The value will be used if the requested language is not supported.

  • Culture fields.

    The field names must match the standard codes of supported cultures. For example, en-US, de-DE. The field values must be boolean: true means the culture is toggled on, false means the culture is toggled off.

View the ..\MyPackage1\content\js\nls\ContactSectionV2Resources.js file example below.

ContactSectionV2Resources.js file example
define({
    root: {
        FileContentActionDescr: "File content first action (Default)",
        FileContentActionDescr2: "File content second action (Default)",
    },
    "en-US": true,
    "de-DE": true,
});

3. Create the culture directories​

Create the culture directories in the ..\MyPackage1\content\nls directory. Set the code of the culture as the name of the directory where the relevant localization will be stored. For example, en-US, de-DE).

View the structure of the MyPackage1 directory with German and English cultures below.

Structure of the MyPackage1 directory
content;
nls;
en - US;
de - DE;

4. Add files with localizable resources​

Place the same set of *.js files with localizable resources in each localization directory as the set of files you placed in the ..\MyPackage1\content\nls root directory. The files contain AMD modules whose objects are "key-value" collections, where the "key" is the name of a localizable string and the "value" is a string in the language that matches the directory name (the culture code).

For example, if you support only German and English cultures, create two ContactSectionV2Resources.js files.

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

Since the translation of the "FileContentActionDescr2" string is not specified for the German culture, the "File content second action (Default)" default value will be used.

5. Modify the bootstrap.js file​

To modify the bootstrap.js file:

  1. Connect the i18n plug-in by specifying its name as the i18n alias in the RequireJS path configuration and specifying the corresponding path to the plug-in in the paths property.
  2. Specify the user's current culture for the plug-in. To do this, assign the object with the i18n property to the config property of the RequireJS library's configuration object. In turn, assign the object with the locale property and the value retrieved from the Terrasoft.currentUserCultureName global variable (the code of the current culture) to the object with the i18n property.
  3. Set the corresponding aliases and paths in the RequireJS path configuration for each file with the localization resources. The alias must be a URL path relative to the nls directory.
..\MyPackage1\content\js\bootstrap.js file example
(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/de-DE/ContactSectionV2Resources": Terrasoft.getFileContentUrl(
                "MyPackage1",
                "content/js/nls/de-DE/ContactSectionV2Resources.js"
            ),
            "nls/en-US/ContactSectionV2Resources": Terrasoft.getFileContentUrl(
                "MyPackage1",
                "content/js/nls/en-US/ContactSectionV2Resources.js"
            ),
        },
        config: {
            i18n: {
                locale: Terrasoft.currentUserCultureName,
            },
        },
    });
})();

6. Use the resources in a client module​

To use the resources in a client module, specify the resource module with the "i18n!" prefix in the dependency array.

View an example that uses the FileContentActionDescr localizable string as the heading for a new action in the Contacts section below.

..\MyPackage1\content\js\bootstrap.js file example
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*/
    }
});

Resources​

RequireJS API documentation