HealthShare Personal Community Localization Setup Guide

1. Overview

There are three forms of text content that be can localized:

i18n files - Text, typically one line or shorter in length, that appears as a matter of course in the user interface for the public application, such as tab and category labels. By default, Personal Community provides i18n files for the following languages:
- English (United States: en-us.json and United Kingdom: en-gb.json)
- Spanish (Spain: es-es.json and Chile: es-cl.json)
- French (fr-fr.json)
- German (de-de.json)
- Italian (it-it.json)
- Arabic (ar-ar.json)
- Portuguese (Brazil: pt-br.json)
Page content files - Content of public application pages, help files, and email and text (SMS) messages. By default, Personal Community provides content files for the following languages:
- English (en)
- Spanish (Spain: es and Chile: es_cl)
- French (fr)
- German (de)
- Italian (it)
- Arabic (ar)
System event messages - Messages that are triggered by events such as account lockout. By default, Personal Community provides system event messages for the following languages:
- English (United States and United Kingdom)
- Spanish (Spain and Chile)
- French
- German
- Italian
- Arabic
- Portuguese (Brazil)

Customization can include:

Modifying existing text
Creating and registering new locales for your application

2. Default Locale Options

The default locale is the language that Personal Community will load for screen text and notifications.

2.1. Specifying a Default Locale for Screen Text and Notifications

To specify a default locale other than US English for screen text and notifications:

Log in to the Workbench as a user with the Configuration Manager role.
Navigate to Setup > Site Configuration .
In Content Settings > Default locale for Personal Community screen text and notifications , choose the desired default locale.
Select Apply to save the changes.

The language for the chosen locale will now be the default for screen text and notifications for all accounts. Members can choose another preferred locale in their account settings or in the locale drop-down list on each page of Personal Community.

IMPORTANT

If the default locale chosen is configured not to be available for screen text or for notifications, US English will be the default locale for that purpose.

3. Creating a New Locale

IMPORTANT

Personal Community uses DayJS to localize all dates within the application. Prior to adding a new locale, please review the supported locales in the DayJS documentation.

Sites may add locales that are not present in this list to Personal Community. In that case, the date format for that locale will be presented in US English.

3.1. Create the Locale i18n File

You must create the i18n (.json) file for your locale:

Navigate to <install-dir>/csp/public/assets/i18n
Create a file named <UI Locale Code>.json (for example, en-us.json, de.json, nl-nl.json, etc.) by copying the existing en-us.json. This ensures that all the same i18n keys exist in the new file. You can do so by performing the following command in the Terminal:
sudo cp en-us.json <UI Locale Code>.json
Edit your copied file and update the values of the i18n keys.

3.2. Creating the Locale Directory

If it does not already exist, create a new <hspc-home> /custom/content/ <locale> / directory, where <locale> is made up of:
- A required <language> parameter, which is a two-letter code for a language, such as es or zh .
- An underscore (_) character only if you are creating a locale for a country's variant of a language as described below.
- An optional <locale> parameter, which represents a lowercase two-letter country code for a national variant of the language OR a string that identifies the file as unique to your organization. For example, an appropriate directory name for Swedish would be <hspc-home> /custom/content/sv/ , while a correct directory name for Mexican Spanish would be <hspc-home> /custom/content/es_mx / . Custom English language content could be stored in a directory called <hspc-home> /custom/content/en_customtext/ .
Copy the content files from <hspc-home>/base/content/en/ to <hspc-home> /custom/content/<locale>/.
Translate the text.
Note
1. If this is a right to left language, the files should contain:
<html dir= "rtl" ></html>

The customer would then put their content within the tags.
Translate the values of the alt attributes for any <img src> tags in the content files. For example, by default, content-home-splash.html contains a reference to an image.

3.3. Refresh Content in the Workbench

To display your organization's combination of default and custom content, refresh the content for your organization's site.

To refresh content:

Log into the Workbench as a user who has the Configuration Manager role.
Go to the Content tab.
On the activity pane, select Content Updates . This displays the Content Updates page.
On the Content Updates page, choose Refresh Content .

This updates every aspect of each application to display the custom content, including text, images, and so on.

If changes are not visible after you refresh content, you may need to clear your browser cache.

3.4. Register the Locale in the Workbench

To add or update a locale registration:

Log in to the Workbench as a user with the Configuration Manager role.
Navigate to Setup > Locales .
Select Add Locale . This displays an empty Locale Details page.
Enter the following information:
- Name - The name of the locale as it will be displayed in the Workbench.
- Name displayed to Personal Community members — The name of the locale as it will appear in Personal Community. This is where you should enter the name of the locale in the appropriate language: for example, the name displayed to Personal Community members for Mexican Spanish could be “Español – México”.
- Locale code — The name of the directory you created for this new locale.
- UI locale code — This will match the entry for Locale code . For instance, if the locale code is "en_us", the UI Locale Code will be "en-us".
- Available for communication — If your project team wants the this locale to be available for event notifications, select Yes ; otherwise, select No .
- Available for display — If your project team wants this locale to be available for screen text and help display within Personal Community, select Yes ; otherwise, select No .
- Language Direction – Personal Community displays this language from right to left must be checked for this language to be displayed from right to left.
- Buddhist Era - Personal Community displays dates with Buddhist Era year must be checked if for this language to display dates using the Buddhist Era year.
Select Save to complete your locale registration.

3.5. Localizing System Event Messages

Messages that are related to technical system events (such as account lockout) are generally stored in and handled by InterSystems IRIS for Health™. These messages can appear either in the public application or in Workbench, and they can be modified or localized.

Personal Community uses the localization tools that come with InterSystems IRIS for Health. For details on these tools, see the “ Overview ” chapter of the String Localization and Message Dictionaries document.

The localization tools organize items into related groups called domains . For each domain in which you are modifying or localizing messages:

Export the strings for the Acct or HSPortal domains to an XML message file with the %Library.MessageDictionary.ExportDomainList method. This method will create one XML message file per domain. If you will be executing the method yourself, see the section “ Exporting an XML Message File ” in the InterSystems IRIS documentation for details.
Modify or localize each of the XML files containing the exported strings. See below for details about this process.
Import each of the customized XML files into Personal Community using the %Library.MessageDictionary.Import method. See the section “ Importing an XML Message File ” in the InterSystems IRIS documentation for details.
For Workbench event-related messages, specify that your custom application class for the Workbench uses your custom locale. To do this, override the %OnNew method in your application class to set %session.Language to your locale, such as "en-mylang" :
```
Method %OnNew() As %Status 
{
               Set %session.Language = "en-mylang"
               Set %response.Language = "en-mylang"
               Quit $$$OK
}
```

Modifying the XML File Containing the Exported Strings

Within Personal Community, all the strings for both domains are in the ^IRIS.Msg global, where each subscript of the global is of the form:

^IRIS.Msg(Domain, Language, Hash) = "Text"

where:

Domain is either "Acct" or "HSPortal"
Language is the default language in use, which is initially "en"
Hash is a hash of the string in use, which also serves as the string's identifier in the exported XML file
Text is the string itself

such as

^IRIS.Msg("HSPortal","en",1478825)= "Create an account"

Once you have exported all the strings in a domain, they are in an XML file of the form:

<?xml version="1.0" encoding="UTF-8"?>
<MsgFile Language="en">
     <MsgDomain Domain = "DomainName">
        <Message ID="Hash">Text</Message>
        ...
    </MsgDomain>
</MsgFile>

To modify the strings for your organization, the steps are:

Change the value of Language to a locale name that matches one you used for localizing screen text.

If you do not specify a new value for Language , Personal Community will overwrite this list of strings during the next upgrade.
Change Text for all strings that your organization is modifying or localizing.
If your organization is not changing certain strings, you have the option of removing these from the export-import file. This can be helpful, since it clarifies what content your organization has and has not modified.

After you have changed the text of the strings, you can then import the file back into Personal Community.

IMPORTANT

InterSystems recommends that you keep a backup copy of the file containing the text of the strings.

4. Updating an Existing Locale

4.1. Modifying Strings and Labels for User-Interface Elements

To localize or create customized screen text, help, and notifications for the Personal Community public application:

Create a custom file: <install-dir>/csp/public/assets/i18n/ <locale> .json
where <locale> is made up of:
- A required <language> parameter, which is a two-letter code for a language, such as es or zh .
- A hyphen ( –) character only if you are creating a locale for a country's varient of a language
- An optional <locale> parameter, which represents the lowercase two-letter code for a national variant of that language OR a string that identifies the file as unique to your organization. The variant is appended to the language code with a hyphen.
  Valid filenames in this scheme are: sv.json (Swedish language, no need for national variant), en-gb.json (UK English), es-mx.json (Mexican Spanish), or en-customtext.json .
Customize the strings in the new file.
- To make the locale available for selection in Personal Community, add a key–value pair for it if it is not already present. For example, an entry for Mexican Spanish might be: CUSTOM_ES_MX: Español – México .
- Each key–value pair for a locale that a can choose in your UI should appear in each of the applicable locale files. For example, if you offer US English and Mexican Spanish, the key-value pairs CUSTOM_ES_MX: Español – México and ISC_ENGLISH: English should appear in both <install-dir>/csp/public/assets/i18n/ es-mx.json and <install-dir>/csp/public/assets/i18n/ /en-us.json .
  
  IMPORTANT
  
  Some strings contain the names of variables, which are enclosed in curly braces. You should not edit these under any circumstances. For example, in "Forms_Validation_MaxLength" : "Maximum length is {{MaxLength}}" , no part of {{MaxLength}} should be edited.
If online forms are used in Personal Community, it is likely that the forms developer will give you some keys, each of which must be added to each *.json file along with an appropriate (translated) value.

4.2. Modifying Content Files

Your organization can modify page content, which generally is text that is longer than a single line. See the following directories:

<hspc-home> /base/content/en/ — Default directory for page content.
<hspc-home> /custom/content/en/ — Custom directory for page content.

If you do not know the names of the content files you wish to change, complete the following steps first:

In the Workbench, enable the setting that displays the source file for each page’s content in the public application:
1. Log into the Workbench as a user with the Configuration Manager role.
2. Go to the Site Configuration Settings page ( Setup > Site Configuration ).
3. In the Debugging Controls section, select Highlight Personal Community content .
4. Select Apply .
This is also known as enabling content highlighting or enabling the debug flag .
In the public application, go to the page on which you wish to change the content. On that page, there is a string of the form:

public / content / <page-name>

where <page-name> has one of two forms:
- content- tab - page .html , where tab is the tab on which the page appears and page is a unique identifier for it, such as content-messages-refill3.html .
- content- page .html , where page is a unique identifier for a page that is not part of the application’s menu structure, such as the content-aboutus.html page.
If you are customizing security questions, use the directory listed above.

To modify page content:

In the Workbench, enable the setting that displays the source file for each page’s content in the public application:
1. Log into the Workbench as a user with the Configuration Manager role.
2. Go to the Site Configuration Settings page ( Setup > Site Configuration ).
3. In the Content Settings section, select Highlight Personal Community content .
4. Select Apply .
This is also known as enabling content highlighting or enabling the debug flag .
If there is not already a custom copy of the content file, copy the existing file from

<hspc-home>/base/content/en/

to

<hspc-home>/custom/content/en/

Note

If such a file already exists, do not create a new copy, as this may overwrite any customizations your organization has already made in it.
Edit the custom copy of the file as required for your organization.
Note
1. If this is a right to left language, the files should contain:
<html dir= "rtl" ></html>

The customer would then put their content within the tags.
Refresh the content for your organization's site.

4.3. Localizing System Event Messages

The localization tools organize items into related groups called domains . For each domain in which you are modifying or localizing messages:

Export the strings for the Acct or HSPortal domains to an XML message file with the %Library.MessageDictionary.ExportDomainList method. This method will create one XML message file per domain. If you will be executing the method yourself, see the section “ Exporting an XML Message File ” in the InterSystems IRIS documentation for details.
Modify or localize each of the XML files containing the exported strings. See below for details about this process.
Import each of the customized XML files into Personal Community using the %Library.MessageDictionary.Import method. See the section “ Importing an XML Message File ” in the InterSystems IRIS documentation for details.
For Workbench event-related messages, specify that your custom application class for the Workbench uses your custom locale. To do this, override the %OnNew method in your application class to set %session.Language to your locale, such as "en-mylang" :
```
Method %OnNew() As %Status 
{
               Set %session.Language = "en-mylang"
               Set %response.Language = "en-mylang"
               Quit $$$OK
}
```

Modifying the XML File Containing the Exported Strings

Within Personal Community, all the strings for both domains are in the ^IRIS.Msg global, where each subscript of the global is of the form:

^IRIS.Msg(Domain, Language, Hash) = "Text"

where:

Domain is either "Acct" or "HSPortal"
Language is the default language in use, which is initially "en"
Hash is a hash of the string in use, which also serves as the string's identifier in the exported XML file
Text is the string itself

such as

^IRIS.Msg("HSPortal","en",1478825)= "Create an account"

Once you have exported all the strings in a domain, they are in an XML file of the form:

<?xml version="1.0" encoding="UTF-8"?>
<MsgFile Language="en">
     <MsgDomain Domain = "DomainName">
        <Message ID="Hash">Text</Message>
        ...
    </MsgDomain>
</MsgFile>

To modify the strings for your organization, the steps are:

Change the value of Language to a locale name that matches one you used for localizing screen text.

If you do not specify a new value for Language , Personal Community will overwrite this list of strings during the next upgrade.
Change Text for all strings that your organization is modifying or localizing.
If your organization is not changing certain strings, you have the option of removing these from the export-import file. This can be helpful, since it clarifies what content your organization has and has not modified.

After you have changed the text of the strings, you can then import the file back into Personal Community.

IMPORTANT

InterSystems recommends that you keep a backup copy of the file containing the text of the strings.

4.4. Updating a Locale in the Workbench

To add or update a locale registration:

Log in to the Workbench as a user with the Configuration Manager role.
Navigate to Setup > Locales .
Search for and select the locale registration you want to change. This displays an empty Locale Details page.
Change any of the following information:
- Name - The name of the locale as it will be displayed in the Workbench.
- Name displayed to Personal Community members — The name of the locale as it will appear in Personal Community. This is where you should enter the name of the locale in the appropriate language: for example, the name displayed to Personal Community members for Mexican Spanish could be “Español – México”.
- Locale code — The name of the directory you created for this new locale.
- UI locale code — This will match the entry for Locale code . For instance, if the locale code is "en_us", the UI Locale Code will be "en-us".
- Available for communication — If your project team wants the this locale to be available for event notifications, select Yes ; otherwise, select No .
- Available for display — If your project team wants this locale to be available for screen text and help display within Personal Community, select Yes ; otherwise, select No .
- Language Direction – Personal Community displays this language from right to left must be checked if your project team wants the language to display as described.
Select Save to apply your changes.