Web UI Framework localization - bundle collector utility

On the client side, you can index localization bundle files from different directories of the application using the JavaScript bundle collector and collator utility.

This tool does the following:
  • Collects, into an index file, bundles defined in multiple JavaScript files (ending with _bundle.js). The index file's format is the standard Java™ properties file format. The contents of the bundle files, including comments, are included in the generated bundle index file. In case, there are duplicate key entries in the given bundle file, only the last such key is added to the bundle index file. For example, consider the following bundle file with duplicate key entries:
    Ext.override(sc.plat.ui.Screen, {
        key1: "value1",
        key1: "value2"
    });

    In the above scenario, the generated bundle index file will only contain the last duplicate entry for key1:

    repository/eardata/<app>/war/<folder structure>/<full _bundle.js file name>/
    sc.plat.ui.Screen/key1:value2
  • Generates JavaScript bundle files, given a localized bundle index file.

    Once the bundle index file is localized, the corresponding localized JavaScript file must be regenerated.

The following shows examples of a bundle file (the _bundle.js file) and its corresponding entries in the bundle-index file.

JavaScript bundle file:

Ext.override(sc.plat.ui.Screen, {
    b_First_Name: "First Name",
    b_Last_Name: 'Last Name',
    // {1} - last name, {0} - first name
    b_Name: '{1}, {0}',
    // a context insensitive comment
    b_Search_View: "Search View"
});

Index file:

repository/eardata/<app>/war/<folder structure>/<full _bundle.js file name>/sc.plat.
ui.Screen/b_First_Name:First Name repository/eardata/<app>/war/<folder structure>/<full _bundle.js file name>/sc.plat.
ui.Screen/b_Last_Name:Last Name #//{1} - last name, {0} - first name repository/eardata/<app>/war/<folder structure>/<full _bundle.js file name>/sc.plat.
ui.Screen/b_Name:{1}, {0} #//a context insensitive comment repository/eardata/<app>/war/<folder structure>/<full _bundle.js file name>/sc.plat.
ui.Screen/b_Search_View:Search View
The keys on the left side are in the following format:
<relativeFilePath>/<className>/<bundleKey>

where:

  • <relativeFilePath> — The path relative to the installation directory.
  • / : Separator used to separate the relative file path, class name, and key name.
  • <className> — Name of the js class. For example, from the _bundle.js sample code: sc.plat.ui.Screen.
  • <bundleKey> — Key whose value is to be localized. For example, from the _bundle.js sample code: b_First_Name.

The bundle utility uses the following utility class:

com.sterlingcommerce.ui.web.framework.build.utils.SCJSBundleUtil

This class can run in the following modes, depending on what task you want to perform:
  • index

    Generates an index of JavaScript bundle files.

    This mode generates the following files:
    1. bundle-index — Contains the entries from all _bundle.js files in the standard Java properties file format (refer to the sample contents provided above).
    2. warnings_indexMode.log — Warnings encountered when the tool is run in index mode.
  • map

    Generates localized JavaScript source files from the localized bundle index file.

    Running the tool in map mode generates the following files:

    1. warnings_mapMode.log — Any warnings encountered during map mode.
    2. All localized js bundle files.
  • update
    This mode should be used only if the localized bundle-index.properties file (for example, bundle-index_fr_FR.properties) is present in an old format:
    1:First Name
    2:Last Name
    3:Search View
    #// (1) - last name.  (0) - first name (should be picked up by collector)
    4:(1), (0)
    Running this mode generates the following files:
    1. bundle-index.properties files — Updates the contents of the original (non-localized) and localized bundle-index.properties files with new contents. New files are not added.
    2. duplicate-keys-map file — Contains entries for all keys that have the same values. This file is required for map mode.
    3. update<locale code>.log — Generated for each localized bundle-index.properties file updated. it contains information about the old and new keys.
    4. update.log — Generated for the bundle-index.properties file (non-localized) updated. It contains information about the old and new keys.
    5. update_warnings.log — Generated for the bundle-index.properties file (non-localized) updated. It contains information about the old and new keys.
    6. warnings_indexMode.log — Contains warnings logged during index mode such as missing comments or duplicate keys.
    7. keys_updated — Contains the old numerical keys and the corresponding new keys in a properties file format.

The following tables show the arguments for the modes:

index
Arguments Example
  • -index

    The mode name.

  • -sourcedir

    The JavaScript source directory. It could be your webcontent directory or any of its parent directories.

  • -indexdir

    The directory to contain the generated index metadata. It is required when you are mapping the bundle back to the JavaScript source files.

  • -Dprefix

    (Optional) Used to determine the relative directory structure from the path specified in sourcedir. It defaults to the installation directory if not provided.

  • -webcontentdepth

    (Optional) The depth of the webcontent directory. This defaults to 0.

  • -ignorefilter

    (Optional) Indicates what folders to exclude from the index. This defaults to `.*/localization/.*`

  • -debug

    (Optional) Indicates whether to run with the debug log enabled. This defaults to N (do not run with debug log enabled).

-index
-Dsourcedir=
<install>/repository/eardata/
<app_dir>/war
-Dindexdir=
<install>/repository/eardata/
<app_dir>/localization_index
-Dprefix=<install>
-webcontentdepth=1
-debug

map
Arguments Example
  • -map

    The mode name.

  • -sourcedir

    The JavaScript source directory.

  • -indexdir

    The original index metadata directory which was localized.

  • -indexfile

    One or more localized index files. For example, a localized file could be named bundle-index_en_US.properties.

  • -localizationdir

    (Optional) The localization output directory where the localized JavaScript source files will be generated. If it is not provided, then the <webcontent directory>/localization directory will be used.

    The index file will be generated at <outputdir>/ localization/ <LOCALE_DIRECTORIES>/ <originalfilepath>

    LOCALE_DIRECTORIES refers to the locale. For example, for locale fr_FR, it is /fr/FR.

  • -webcontentdepth

    (Optional) The depth of the webcontent directory. This defaults to 0. The localized files will be generated in the webcontent directory.

  • -ignorefilter

    (Optional) Indicates what folders to exclude from the index. This defaults to `.*/localization/.*`

  • -debug

    (Optional) Indicates whether to run with the debug log enabled. This defaults to N (do not run with debug log enabled).

-map
-Dsourcedir=<install>/repository/
eardata/<app_dir>/war
-Dindexdir=<install>/repository/
eardata/<app_dir>/localization_index
-Dindexfiles=<install>/repository/eardata/appdir/
localization_index/bundle-index_fr_FR.properties
-webcontentdepth=1
-debug

update


Arguments Example
  • -update

    The mode name.

  • -sourcedir

    The JavaScript source directory.

  • -indexdir

    The original index metadata directory that was localized.

  • -prefix

    (Optional) Used to determine the relative directory structure from the path specified in sourcedir. It defaults to the installation directory if not provided.

  • -webcontentdepth

    (Optional) The depth of the webcontent directory. This defaults to 0. The localized files will be generated in the webcontent directory.

  • -ignorefilter

    (Optional) Indicates what folders to exclude from the index. This defaults to `.*/localization/.*`

  • -debug

    (Optional) Indicates whether to run with the debug log enabled. This defaults to N (do not run with debug log enabled).

-update
-Dsourcedir=
<install>/repository/eardata/
<app_dir>/war
-Dindexdir=
<install>/repository/eardata/
<app_dir>/localization_index
-webcontentdepth=1
-debug

You also can use an ant XML utility (jsUtil.xml) to invoke the utility class com.sterlingcommerce.ui.web.framework.build.utils.SCJSBundleUtil. This ant utility can be used to test and run the utility classes. This utility does not expose everything that is supported by the class, but the supported items that it does expose can be used in most cases. If you need to invoke the actual class with custom arguments, this XML file can be used as a sample source file.

The jsUtil.xml file is located in the <INSTALL_DIR>/bin folder after the Web UI Framework is installed. Sample code for invoking the ant utility in the two different modes is shown below:

  • index mode
    ./sci_ant.sh -f jsUtil.xml bundle.index
    -Dsourcedir=<INSTALL_DIR>/repository/eardata/<app_dir>/war 
    -Dindexdir=<INSTALL_DIR>/repository/eardata/<app_dir>/localization_index
  • map mode
    ./sci_ant.sh -f jsUtil.xml bundle.map 
    -Dsourcedir=<INSTALL_DIR>/repository/eardata/<app_dir>/war
    -Dindexdir=<INSTALL_DIR>/repository/eardata/<app_dir>/localization_index
    -Dindexfile=<INSTALL_DIR>/repository/eardata/<app_dir>/localization_index/
    bundle-index_en_US.properties
  • update mode
    Note: Run this mode only if you have localized the bundle-index.properties file in the format described previously.
    ./sci_ant.sh -f jsUtil.xml bundle.update
    -Dsourcedir=<INSTALL_DIR>/repository/eardata/<app_dir>/war
    -Dindexdir=<INSTALL_DIR>/repository/eardata/<app_dir>/localization_index
    -Dindexfile=<INSTALL_DIR>/repository/eardata/<app_dir>/localization_index/
    bundle-index_en_US.properties
    -Dprefix=<INSTALL_DIR>
    
    (-Dprefix is optional.)

Running the bundle collector utility to localize Sterling Application Platform files

You can also use the bundle collector utility to generate index and bundle files for some platform_uifwk files like the dashboard bundle files.

The procedure is the same as above, except the directory structure would change to the following:

In <install>/repository/eardata/platform_uifwk/<version>/war/<directory containing required files>, <version> is the platform Sterling Application Platform being consumed by the application.