Setting National Language Dynamically at Runtime

Setting National Language Dynamically at Runtime

WebClient Multi-Language Support

OBJECTIVE

This document exemplifies the process to support multi-language in a WebClient dynamically via changes at run-time.

This process exemplifies the process to setup and configure an application that will support Multi-language with target languages English, Spanish, and French.

The end-user will be able to change the national language configuration at runtime and the web application will refresh the change to display fields’ labels and a button’s text in the target locale (language).

This document and example was prepared with PLEX 7.1, Java 7, Eclipse Luna Release (4.4.0), WebClient 1.8.2

A Local Model, WebTest, accompanies this document and a test function, impl name: TestGrid, is included to exemplify the development required for the dynamic change of language (locale).


CONFIGURE OBCLIENT.PROPERTIES TO ENABLE MULTI-LANGUAGE SUPPORT

To enable multi-language support add the following properties to the obclient.properties file:

webclient.localization.enabled=Y
webclient.localization.panelproperties=Text,BitmapFile

In addition, there is another setting in obclient.properties that defines the default locale:

locale.language=en

NOTE: In this example the default locale is English (en).

These settings will affect how WebClient generates elements such as labels and buttons’ text in the .wcli files therefore you will have to regenerate all your panel templates as described in the next steps.

SRC/RES FOLDER PER SUPPORTED LOCALE

To provide the resource files for each language (locale) supported by the application it is necessary to manually create a folder for each locale at the lowest level of your package.

For example, if the package name is “WebClientTest”, as in the accompanying Model for these instructions, this would be the location of the folders for each supported locale:

C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest

So the following folders have been created to support ENGLISH (en), SPANISH (es), and FRENC (fr) locales:



To generate the appropriate resource files it is necessary to change the PLEX configuration to the appropriate target language and then generate the source which is then copied to the corresponding src/res folder for each locale supported.

REGENERATE ALL PANEL TEMPLATES IN THE TARGET LOCALES TO SUPPORT

Perform the following process:

  1. For English set the FIELDS configuration to the BASE Language:
  2. Generate the function TestGrid. Don’t compile:
  3. Refresh the TestJava project to rebuild the templates:
  4. Then grab the .panelresource and .resource files just created and move to the appropriate RES folder for ENGLISH (Base) language: 
    Copy from:
    C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest
    to:
    C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest\en
  5. For French set the FIELDS configuration to the FRENCH Language:
  6. Generate the function TestGrid. Don’t compile.
  7. Refresh the TestJava project to rebuild the templates.
  8. Grab the .panelresource and .resource files just created and moved to the appropriate RES folder for FRENCH language:
    Copy from:
    C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest
    to:
    C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest\fr
  9. For Spanish the FIELDS configuration is set to the SPANISH Language:
  10. Generate the function TestGrid. Don’t compile.
  11. Refresh the TestJava project to rebuild the templates.
  12. Grab the .panelresource and .resource files just created and moved to the appropriate RES folder for FRENCH language:
    Copy from:
    C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest
    to:
    C:\Development\EclipseWorkspace\WebClientTest\PlexModel\Local\Gen\Src\Res\WebClientTest\es

LOCALE CHANGES

There are two alternatives for changing the locale:

  1. Static
  2. Dynamic

For a static local change you need to change the following property on the obclient.properties file:

locale.language=XX

Where:
XX = Locale indicator such as EN (English), FR (French), and ES (Spanish)

Example:
locale.language=es

Will switch the application’s local to Spanish.

For 2), dynamic changes, the above property can be switched via the use of the Source Code JAVAPI/SetRunOptionValue. The SetRunOptionValue Source Code is shipped with PLEX and allows chaning any runtime option at runtime.

To reflect the changes after a locale switch it is necessary to refresh the application’s page and the following source code can be used:

import com.adcaustin.webclient.*;
((IWebFunction) fnc).getWebPanel().setRefresh();

Example of an implementation with a dynamic locale change/page refresh can be found in the test function TestGrid, in the accompanying Test Model for this document, which includes a language radio-button field that triggers the ChangeLanguage logical event:



In the Action Diagram the functionality retrieves the language value which is assigned to the PropertyValue field.

This PropertyValue field and the PropertyKey = Locale.Language are used to set the WebClient run option value to set the locale, and finally the application’s page is refreshed with the suggested source code:



Another example, not found in the provided Model, can be found in the following image where the code to set the language takes place before the login process of an application. In this additional example, the language is obtained from the request (browser locale) then mapped to the Java Locale, and finally the runtime option (locale) is set.

Once the user has logged in the application knows his preferred language, from a User Database implemented on this system, so that the Locale can be switched to the one in the User Profile table:



DYNAMIC LOCALE CHANGE - RUNTIME TEST

To test the runtime use: http://localhost:8080/TestWeb/wc

Use the language radio control to set and change the locale

  1. By selecting English all labels and the button text are changed to English
  2. By selecting Spanish all labels and the button text are changed to Spanish:
  3. By selecting French all labels and the button text are changed to French:

SETUP CONSIDERATIONS

  • In case you experience issues with Tomcat web server launch please see the section “WebClient Multi-Tomcat Installation Issues” on the WebClient Manual Website
  • Ensure you are using the appropriate Java Version for your version of Eclipse. For example, if you are using Eclipse Luna (4.4.0) you might be needing to use Java 7 which is installed on C:\Program Files\Java\jdk1.7.0_71\bin. NOTE: The version of Java used is specified with the full path to the Javaw.exe on Eclipse.INI

Invalid Java version to use with this workspace would display an error with Exit Code = 13 upon launching the workspace:



To specify the Javaw on Eclipse.INI:

  • The -vm option and its value (the path) must be on separate lines.
  • The value must be the full absolute path to the Java executable, not just to the Java home directory.
  • The -vm option must occur before the -vmargs option, since everything after -vmargs is passed directly to the JVM

Example of an Eclipse.ini modified to specify the Java executable:

-startup
plugins/org.eclipse.equinox.launcher_1.3.0.v20140415-2008.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20140603-1326
-product
org.eclipse.epp.package.jee.product
--launcher.defaultAction
openFile
--launcher.XXMaxPermSize
256M
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
--launcher.appendVmargs

-vm
C:\Program Files\Java\jdk1.7.0_71\bin\javaw.exe

-vmargs
-Dosgi.requiredJavaVersion=1.6
-Xms40m
-Xmx512m

  • There are limitations to the multi-language capabilities for the Dojo Presentation Language. Dojo has its own configuration to control the localization of controls, for example the one for DatePicker. The Dojo Locale setting defaults to the Browser Locale which is not the one expected when managing multi-language support as such browser locale would be different from the User Locale. A mechanism to get the current PLEX Java Locale, defined by the SetRunOption value, into the WebClient Javascript code would be needed to set the Dojo Configuration correctly. Such mechanism is beyond the scope of this document.
  • UTF-8 Format Support. UTF-8 is UTF-8 is a character encoding capable of encoding all possible characters, or code points, in Unicode and is needed in certain environment such as Linux to support foreign language encoding.
    It is important to note that there is a known limitation with PLEX where it cannot generate UTF-8 files, despite the specification on Gen&Bld > Options > System Definitions > Java Build > Java Encoding, therefore a conversion process needs to take place after the files are generated.
    In Eclipse, for setting the charset or file encoding in the whole project you can make use of the Java Project Properties > Resource tab

Note that this configuration would only work for the development environment.

Specify the target web server, for example Tomcat, just select export to WAR file on the Web Project and specify such option:



In addition, you can also try the following setting on:

/root/.bashrc

In such file include the following:

export CATALINA_OPTS=-Dfile.encoding=CP1252

To enable UTF-8 although this has not worked consistently therefore an alternative is to convert the entire RES folder where the .panelresource files are located massively to UTF-8 before the Eclipse Build to have the final files in UTF-8 before releasing to Linux. This can be achieved with a utility like TextCrawler (http://www.digitalvolcano.co.uk/tcdownloads.html) or ICONV (http://www.php.net/iconv). The SRC folder includes the RES folder and also the java sources. The reason for converting all is that captions are stored as part of the java code, not the panelresources, so they need to be converted too.

Also, to change the encoding for Tomcat in general, in your production environment, you can do the following: On Windows Edit the file $TOMCAT_HOME\bin\startup.bat and insert or alter the following line, substituting for the desired values: set CATALINA_OPTS=-Dfile.encoding=CP1252. The problem might be that this setting would be global and could affect other applications using Tomcat so use it just if you are certain this global setting is appropriate.

Finally, in WebClient the filenames can be encoded to prevent issues saving files with unsupported characters such as with foreign languages. Check the Additional Notes on https://support.cmfirstgroup.com/portal/en/kb/articles/cm-webclient-file-upload-setup-15-8-2019.



    • Related Articles

    • Deployment Configurations (Runtime)

      Configuration settings between Components CM evolveIT installation and configuration process set up all required components automatically but all in one in single server. From scalability and performance reasons, multi-Server Deployment is ...

    • WebClient Manual

      Here you can find the articles of the CM WebClient user manual, just click on the name and it will take you directly to the article. Introduction Installation Requirements Plex Model Configuration Overview of Workspace Setup Calling WebClient from an ...

    • Embedded SQL Language Support (All Languages)

      HLL scanners will emit 3 XML element types: SqlTable, SqlColElem, and SqlColumn. SqlTable is equivalent to the ARZOS TABLE entity. It will be identified by SERVER_NAME, CREATOR, and TB_NAME. SqlColumn will be emitted for any reference to a column ...

    • How To...

      1. Group Model Q: How do I change WebClient group model from licensed version to non-licensed version? A: a. Login to your group model and remove the old WebClient group model and add the new WebClient group model from your library list. b. Extract a ...

    • Patch Build to CM WebClient 1.8.8

      Latest Version: Date 10 /25/2024 WebClient-1.8.9-13546 NOTE : If the hightail link doesn't open correctly the first time, please just reload the screen, we recommend using the Chrome browser to open it. Current GA Release CM WebClient 1.8.7 WebClient ...