Localization - tsgrp/HPI GitHub Wiki

HPI supports a number of ways to localize text, whether it be for a client need, a language need, or a code customization need. This article will cover explaining what the different methods are, and when to use them.

When adding a new localization, please...

1. Add the new localization to ALL six .json files (de.json, en.json, es.json, fr.json, it.json, ja.json). Also, please nesure that all files are still the same length after you update them.
2. Note the generic section. Please do not add a localization for any words or phrases that can be found in the generic section.

• This is an example of a bad key:

"modules.actions.advancedCombineToPDF.search": "Search"

• Here is an example of how that key should be done:

"modules.actions.advancedCombineToPDF.searchResults": "Search results will appear below the search box. Select all 
controlled documents"

"Search" is a already generic localization, but the second example is specific and doesn't appear more than once in the .json file.

3. Please put your new localization in alphabetical order.

The three primary methods of localization in HPI are as follows:

• Admin localization: when you want a module to show or behave differently via configuration by changing settings in the Admin.
• L10N localization: when you want to show something different on the screen for a different language, or when you want to customize just text.
• Module localization: when you want a module to show or behave differently via configuration, but can't/don't want to add the option to the HPI Admin.

Very common customizations should go in here where clients may want to update the values themselves. Admin updates have a heavier overhead of work that go into implementing them, however. See https://github.com/tsgrp/hpi/wiki/HPI-Administration-Guide to see what values can already be configured via the HPI Admin.

L10N allows us to configure text for different languages, as well as provide clients with customized text across the application. L10N uses string "keys" throughout the application to decide what string to output to the screen. By default, HPI uses the browser to determine what <language>.json file to define the output strings. For a client customization, you can override these files in your project. These files are located in assets\localizations\locales.

Once HPI determines the browser's language, a cookie is created containing the language. This cookie is removed when logging out of HPI. Currently, all labels used in configurations are automatically localized in HPI. This means that whatever is included in the label boxes within the Object Type Config will be passed through to your <language>.json file as a key to see if it exists, and if it does, it will use the localized value. If a key is not found, the key itself will be used in the display.

EG. - we need the attribute "Employee Address" localized to French for a search form. In the Object Type Config, the box for the label of the attribute reads "Employee Address", which will wholesale be passed into fr.json as a key by the localization service. To get this attribute localized we would need to add the following to the fr.json file:

    "Employee Address": "Adresse des Employés",

This will need to be repeated for any label in the Object Type Config we would expect to be localized. Remember that localization files must contain valid JSON syntax.

Localization Support
* English
* French
* German
* Spanish
* Japanese

The string values can be accessed in two ways. In our HTML partials, we can use a Handlebars helper:

{{localize "myModuleName.theSectionOfMyModule.theKey"}}

when rendered on the screen, the value displayed will come from the current language file. If the key is not found, the key itself will be displayed.

In Javascript code, we can use the "localize" function, placed on the window, like this:

    var myString = window.localize("myModuleName.theSectionOfMyModule.theKey");

to achieve the same results.

HPI allows us to configure values on a per project basis. These values may also be more complex than just a string - they can be JSON objects.

To configure a module localization for a project, go to your project's config-project.js and add lines like the following to the "config" object:

    'modules/stage/stageinfo': {
        linkText: "stageInfo.formInfo"
    }

Once the config-project.js is updated, import the "module" module in the stageinfo.js define block:

    define(["app","knockout","knockback","module"], ...

then in Javascript, you can access the configured values like so:

    var linkText = window.localize(module.config().linkText) || window.localize("stageInfo.folderInfo");
    // linkText is equal to the configured "linkText" value, or if not configured, defaults to "Folder Info".