Localization Of Helical Insight

This guide explains how to enable and use localization (language translation) in Helical Insight using a simple patch.

The goal is to make the application support multiple languages in a way that’s easy for both developers and end users.

1. Installation Steps

1. Download the LocalizationPatch.zip file and unzip it.
2. Inside the extracted folder, you’ll find a folder also named LocalizationPatch. Copy this folder and paste it into the following directory:

   …/hi/apache-tomcat-9/webapps/hi-ee/js

3. Open the file loginBody.jsp in edit mode. It is located at:

   …/hi/apache-tomcat-9/webapps/hi-ee/WEB-INF/jsp/login

4. Add the following script tag to the file:

   <script src="${baseURL}/js/LocalizationPatch/home.js"></script>
   This script connects the localization functionality to your application.

2. Folder Structure

The LocalizationPatch folder contains:

• A folder named langs:
  • en-US.json
  • fr.json
  • es.json
• A JavaScript file: home.js

Explanation:
– The langs folder contains JSON files for different languages. Each file has key-value pairs — where the key is the English text and the value is the translated text.
– The home.js file is responsible for translating the application’s text based on the selected language.

3. How It Works

Language Detection and Translation

• When you pass a language (locale) in the URL, the app uses that language for translation across all pages — even if the URL doesn’t continue to show the locale.
• If no locale is passed in the URL, the application automatically checks the browser’s preferred language and translates the text accordingly (if a corresponding JSON file exists).

Example:
If a user’s browser is set to French, the application will automatically use the fr.json file for translation.

4. Language JSON Files

• These files contain key-value pairs (e.g., "Hello": "Bonjour").
• The structure is the same for all language files.
• To add a new language:
  • Create a new JSON file with the same structure.
  • Name the file using the appropriate locale code (e.g., de.json for German).

5. Code Overview

Single File Used: home.js

This file contains two main functions:

1. getParams()
   – Extracts the locale and timezone from the URL.
   – If nothing is passed, it falls back to the browser’s preferred language.
2. textTranslator()
   – This is the main function responsible for translating the UI.
   – It:
   • Loads the correct language JSON file based on the locale.
   • Traverses each HTML element and replaces the English text with the translated version.
   • Uses MutationObserver to detect and translate new elements added dynamically to the page.

⚠️ Important: A sentence may appear as a single line in the UI but be made of several HTML elements (like <div> and <span>). Each part must have a separate translation entry in the JSON file.

6. Updating Existing Language Files

If a word or sentence isn’t translated:

1. Use the browser’s Inspect Tool to find the exact English text.
2. Get the correct translation for your language.
3. Add the new key-value pair to the relevant JSON file (e.g., add to fr.json for French).
4. Save the file and refresh the page — the new text will now be translated.

7. Adding a New Language

To add support for another language:

1. Create a new JSON file in the langs folder.
2. Follow the same format as the other JSON files.
3. Use the locale code as the filename (e.g., it.json for Italian).

🔴 Note: The translation function is case-sensitive. Ensure the keys in the JSON file exactly match the text in the UI.

For example:
– If the UI says Hello, then the key must also be Hello, not hello.