Khoppenworth: New Page

2023-11-15T17:36:07Z

New Page

New page

The Pharmadex 2 provides true multi-language features. It means that:

1. The user interface (UI) may be represented in the language selected by a user

2. A user may use the selected language to fill out on-screen data forms as well as to get documents, reports, etc.

The Pharmadex 2 distribution software allows US English and a national language.

This manual intends for IT experts to help replace the national language provided in the distribution software with the language of a particular country.

To perform this job following IT skills will be needed:

1. Operation Systems – start and stop Pharmadex 2 service

2. MySQL database:

3. Ability to use MySQL Workbench, relation database, and SQL knowledge

4. MS Excel – ability to use

The roadmap chapter contains a particular example to replace the Nepali language with the Portuguese language. It is possible to define many languages, however, the reasonable choice is two languages. Many languages will slow down Pharmadex 2 and hard to maintain.

Refer to Annex 1 for the troubleshooting.

Annex 2 contains technical data that may be useful to understand how it works “under the stage”.

Annex 3 contains directions on how to maintain labels and messages in the actual state

= 1 Pre-request =
· Direct access to Pharmadex 2 server computer console with administrative privileges

· Supervisor’s access rights to Pharmadex 2

· The MySQL Workbench is installed and a connection to the Pharmadex 2 database is defined. The rights should be at least query/update

· The MS Excel released after 2017 is installed

· The MySQL for Excel plugin is installed, see <nowiki>https://downloads.mysql.com/archives/excel/</nowiki>[1]

= 2 The roadmap =
1. Stop Pharmadex 2 server

2. Create a backup copy of the database

3. Determine languages that are in use

4. Upload to MS Excel messages for English US language and translate them

5. Add a new language:

5.1. Register a new language in the database

5.2. Remove an excess language

5.3. Insert messages in the new language into the database

5.4. Replace the language tag in the demo examples

6. Start Pharmadex 2 and test the new language

7. Replace logos

8. Fine-tune tiles

== 2.1 Stop Pharmadex 2 server ==
For MS Windows installation stop the Pharmadex 2 service using the Services tool. Refer to MS Windows documentation for details. The most used tool is “services.msc”.

For Linux installation stop the Pharmadex 2 service. Refer to the appropriate Linux documentation for details. The most used tool is “systemctl”.

== 2.2 Create a backup copy of the database ==
Use MySQL Workbench to create a backup copy of the database. Refer to the MySQL workbench manual for details.

Figure 1 Backup dump creation

== 2.3 Determine languages that are in use ==
Use MySQL Workbench connection to Pharmadex 2 database to execute a query

SELECT ID, `locale`, `displayname` FROM pdx2.resource_bundle;

Figure 2 Nepali and English US are in use

'''In this particular example, the Nepali language should be removed. The Portuguese language should be added.'''

== 2.4 Upload to MS Excel messages in English US and translate them ==
As we determine above (3), the English US language ID is 3. Use MySQL Workbench connection to Pharmadex 2 database to select all messages in English

Query is SELECT * FROM pdx2.resource_message where key_bundle=3

Figure 3 Select all messages in English US (key_bundle=3)

Figure 4 Select all records from the result

Figure 5. Insert records to MS Excel sheet

Figure 6 Translate them (e.g., to Portuguese)

== 2.5 Add a new language ==

=== 2.5.1 Register a new language in the database ===
Prepare image of countries flag as SVG file.

Use MySQL Workbench to add a new record into table pdx2.resource_bundle. Fields NmraLogo, and UsaidLogo should be filled with space, not NULL

Figure 7 The Portuguese language has been registered

=== 2.5.2 Remove an excess language ===
Use MySQL Workbench to remove the Nepali language registration record from the database. All messages in the Nepali language will be removed as well.

Figure 8 Nepali language bundle is going to be removed

=== 2.5.3 Insert messages in the new language into the database ===
Open the Excel file prepared in 4 and fill out the rightmost column (D) by the ID of the new registered language - 4

Figure 9 Fill out the column D for key_bundle with the key bundle for a new language (4)

Figure 10 Use MySQL for Excel plugin to insert messages, refer to the plugin’s manual

Figure 11 Define column mapping

Figure 12 Append them

=== 2.5.4 Replace language tag in existing workflow configurations ===
The distribution database contains demonstration workflows. Their configurations are defined in the old language. Use MySQL workbench to replace language tags in the configuration.

The script below will replace the language tag “ne_NP” with “pt_BR”. Modify it for the actual languages

UPDATE `pdx2`.`concept` c SET `Identifier` = 'pt_BR'

where c.Identifier='ne_NP'

= 3 Start Pharmadex 2 and test the new language =
For MS Windows installation start the Pharmadex 2 service using the Services tool. Refer to MS Windows documentation for details. The most used tool is “services.msc”.

For Linux installation start the Pharmadex 2 service. Refer to appropriative Linux documentation for details. The most used tool is “systemctl”.

Figure 13 New language is available

= 4 Replace logos =
Figure 14 Feature Administrate-Configurations-Resources allows uploading logos. Use language switch to upload logos for any given language separately.

= 5 Fine-tune tiles =
Figure 15 Administrate, Configuration, Tiles, tick-up on the tile group in the table

Figure 16 Administrate page tiles as an example. Click on “Administrate” in the left table for the next screen

Figure 17 Elements available for internationalization

1. Select the language using the language switch

2. Fill out this information using the language selected

3. It is possible to select another picture from a tile

4. This label should be in the language selected

= 6 Annex 1 Troubleshooting =

== 6.1 The new language doesn’t appear in the language selector ==
Check table resource_bundle. If the new language is present, restart Pharmadex 2 server. Otherwise, add new language exactly as described in the Roadmap chapter.

== 6.2 The labels in new languages appear improperly ==
The messages on the selected language appears improperly like 'new_chemical_entity', or 'UserType.TIPC'.

The messages for the language selected are not defined. Suppose it is Portuguese. To check it:

Execute SELECT * FROM pdx2.resource_bundle;

Figure 18 The Portuguese language is registered. ID is 4

Execute SELECT * FROM pdx2.resource_message where key_bundle=4

Figure 19 For the Portuguese language messages are not defined

Insert messages from MS Excel as described in 4.3

== 6.3 The labels for the new language appear in the old language ==
The ID field in table resource_bundle does not match the ID in resource_message.

To check it, execute SQL queries from 8.2. The resource_message table should contain messages in the wrong language

Figure 20 Messages in English, despite the Portuguese language

To fix it restore the database from backup and repeat the new language definition. Step, described in chapter 4, may be omitted.

== 6.4 The SVG logo or flag in the language selector doesn’t appear ==
Open the SVG file locally by browser or lnkscape (<nowiki>https://inkscape.org/</nowiki>). If the file is consistent, re-import it to the database using the “value editor” feature.

Figure 21 Right-click and Open Value in Editor

Figure 22 The SVG file is a text. Insert it into the Value Editor

= 7 Annex 2 Technical implementation =
The internationalization of the user interfaces is grounded on Java i18N approach[2].

Textual labels and messages are available directly in the database tables:

1. resource_bundle – keeps languages definitions.

2. resource_message – keeps textual labels and messages

Each row in the resource_bundle represents a language. Columns are:
{| class="wikitable"
|'''Column'''
|'''Purpose'''
|'''Example'''
|-
|Id
|Unique key for a language definition
|1
|-
|sortOrder
|Order to use in the user interface. The 0 is the highest priority, the rest are the lowest. For more details see chapter “Language by default” below
|0 – the default language
|-
|basename
|For compatibility with the previous release. Should be unique for a language
|English
|-
|locale
|Locale ID for a language. Please, put attention to _ (underscore), instead of – (dash) usage. It is to be compatible with java.util.Locale.toString[3]
|en_US
|-
|displayName
|Human-readable name of the language
|לשון עבר
|-
|svgFlag
|Flag to represent the language in the user interface. Must be defined.
|<?XML version="1.0" encoding="iso-8859-1"?>

<!-- Generator: Adobe Illustrator…
|-
|updatedDate
|Not used in Pharmadex 2
|
|-
|createdDate
|Not used in Pharmadex 2
|
|-
|UsaidLogo
|Not used in Pharmadex 2
|
|-
|NmraLogo
|Not used in Pharmadex 2
|
|}

Each row in resource_message table represents a text on the language as key-value pair:
{| class="wikitable"
|'''Column'''
|'''Purpose'''
|'''Example'''
|-
|id
|Unique key for a text in a language
|5376
|-
|message_key
|Unique language - independent key for a text
|global_cancel
|-
|message_value
|Value in a language
|Cancel
|-
|key_bundle
|Id in resource_bundle to link to the language
|3
|}

The Pharmadex 2 database allows defining multi-language classifiers (dictionaries) as well as files to upload (resources). When a user selects a language, the Pharmadex 2 switches the language of the user interface, dictionaries, and resources. Thus, a user can fill out the application electronic form in the language selected.

When a user fills application electronic form, Pharmadex 2 stores user input for each language separately. Suppose the form in Portuguese

'''Fator de forma''': [Caixa Cinza]

When a user will switch to English it will be:

'''Form factor:''' [Caixa Cinza]

It is possible to change the data in the English form

'''Form factor:''' [Gray Box]

The Portuguese form will still keep

'''Fator de forma''': [Caixa Cinza]

The English form will keep:

'''Form factor:''' [Gray Box]

The true multi-language is a powerful, however costly feature:

· The database should keep and process more data.

· The data in the database is complex, because of the necessity to keep language for any data element

· The initial input and maintenance of multi-language dictionaries and resources are costly

The two languages are the optimal choice.

= 8 Annex 3 Maintenance and language by default =
Figure 23 Feature Administrate-Configurations-Messages allows changing initial uploaded labels and messages as well as adding missed ones

When a user enters Pharmadex first time, the system proposed a language that is defined in the file “application.properties” under the key spring.web.locale, e.g., “spring.web.locale=en_US”. It is recommended not re-define this key to the local language because some browsers will not accept the local language, thus Pharmadex 2 will be inaccessible.

When a user selects a language, this selection will be stored in the file cookie on the user’s computer. All follow-up calls will set the selected language. The time to live the selection is a year or until a user will switch to another language.

----[1] This plugin is out of support for now. Despite this it is available yet. The MS Excel export-import features will be implemented in Pharmadex 2 ASAP.

[2] <nowiki>https://docs.oracle.com/javase/8/docs/technotes/guides/intl/index.html</nowiki>

[3] <nowiki>https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString()</nowiki>

OpenRIMS-RPM - Base Configuration Part 1 - Revision history

Khoppenworth: New Page