Skip to main content

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:

  1. Log in to the Workbench as a user with the   Configuration Manager   role.

  2. Navigate to   Setup >   Site Configuration .

  3. In   Content Settings >   Default locale for Personal Community screen text and notifications , choose the desired default locale.

  4. 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:

  1. Navigate to <install-dir>/csp/public/assets/i18n
  2. 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  
  3. Edit your copied file and update the values of the i18n keys.

3.2. Creating the Locale Directory

  1. 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/ .
  2. Copy the content files from <hspc-home>/base/content/en/ to <hspc-home> /custom/content/<locale>/.

  3. 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.

  4. 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:

  1. Log into the Workbench as a user who has the Configuration Manager role.

  2. Go to the Content tab.

  3. On the activity pane, select Content Updates . This displays the Content Updates page.

  4. 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:

  1. Log in to the Workbench as a user with the Configuration Manager role.
  2. Navigate to  Setup  >  Locales .
  3. Select Add Locale . This displays an empty Locale Details  page.
  4. 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.
    • InterSystems EHR Language Code — Leave empty; This setting is only relevant for InterSystems EHR integrations. 
  5. 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:

  1. 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.

  2. Modify or localize each of the XML files containing the exported strings. See below for details about this process.

  3. 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.

  4. 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:

  1. 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.

  2. Change  Text for all strings that your organization is modifying or localizing.

  3. 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:

  1. 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 .
  2. 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.

  3. 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.

For information on modifying the Welcome string on the home page, please see Modifying Welcome Message in the Personal Community Installation Setup Guide. 

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:

  1. 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 .

  2. 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:

  1. 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 .

  2. 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.

  3. Edit the custom copy of the file as required for your organization.

    1. Custom styling can be added to the custom file using HTML css style attributes . Ensure that any styling added to the custom file is present in Personal Community. If the styling specificity is not high enough, it may be overwritten by styles defined in Personal Community. 


      Note

      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.



  4. Refresh the content for your organization's site.

4.3. Localizing and Customizing Notification Content

Notifications can be triggered through 2 different functions:

  1. Personal Community System Event Notifications - Events that occur within Personal Community functionality that automatically notify the patient. This includes notifications surrounding account activation, proxy configuration, etc.
  2. Notifications from an External System - Events that occur in an another external system that can trigger sending notifications via the Notification API. 

Notifications are supported through 3 different delivery mechanisms:

  1. Email
  2. SMS messages
  3. Push notifications – This is only for mobile app deployments. Push notifications from external systems are only supported on the Notification REST API.  

    Push Notification Configuration

    Push notifications require additional configuration. Ensure the push notification configuration within Personal Community Mobile Application Guide has been completed.

4.3.1. Personal Community Event Notifications

Certain events that occur within Personal Community trigger event notifications. The names of the files are in the following forms:

Email:  email- topic - format .html

SMS: sms- topic - text.html

Push notifications are only triggered if enabled on the system. These files are in the following forms: push- topic -body.html and push- topic -title.html

where:

  • topic   — Specifies the subject of the messages

  • format   — For email, specifies the format of the email, which can be   html   (for emails in HTML) or   text   (for emails without any formatting). SMS files are by their nature text-only.

The topics are:

  • activationreminder

  • activationreminder-passphrase

  • completedregistration

  • deactivateaccount

  • deletenotification

  • denied-registration

  • minordeactivateaccount

  • minorreactivateaccount

  • new-message-notification

  • new-message-proxy-notification

  • password-change

  • password-reset

    Push Notification Information

    Note: The password-reset file is not supported for push notifications as it requires a contextual link. In the event this notification is triggered for a patient, an email or SMS will be used instead, depending on the patient's preferences.

  • proxyrelationship-notify-principal

  • proxyrelationship-notify-proxy

  • reactivateaccount

  • registration

  • registration-passphrase

  • selfenrollment-notification

  • username-reminder

  • username-reminder-multi

4.3.1.1. Variables for Use in Personal Community Event Notifications

The table below shows the variables that are available for use in the email content files for Personal Community system event notifications.
Message Filename Names and Values of Available Variables 
*-activationreminder-*.html




*-activationreminder-passphrase-*.html




*-completed-registration-*.html




*-deactivateaccount-*.html




*-deletenotification-*.html




*-denied-registration-*.html




*-minordeactivateaccount-*.html




*-minorreactivateaccount-*.html




*-reactivateaccount-*.html




*-registration-*.html




*-registration-passphrase-*.html

{USER{FirstName}}   — First name of the patient (current or pending).

{USER{MiddleName}}   — Patient’s middle name.

{USER{LastName}}   — Patient’s last name.

{USER{Address1}}   — First line of the patient's address.

{USER{Address2}}   — Second line of the patient's address.

{USER{City}   — Patient's city.

{USER{State}}   — Patient's state.

{USER{ZipCode}}   — Patient's zip code.

{USER{PreferredLanguage}}   — Patient's preferred language.

{USER{Email}}   — Patient's email address.

{USER{UserName}}   — Patient's Personal Community username.

{USER{Token}}   — Patient's temporary   access token , which allows them to authenticate prior to setting a permanent password.

{ENV{PortalPath}}   — Base URL for your organization’s instance of Personal Community, which is specified in the   Personal Community base URL   field on the   Site Configuration Settings   page in the Workbench ( Setup   >   Site Configuration   >   Application Settings   section). Typically, this URL ends with a trailing slash (“/”) and does not include a page within Personal Community, such as   http://hostmachine.yourorganization.org/public/.

{ENV{RegistrationLink}}   — URL for the   Activate Account   page for your organization’s instance.

{ENV{FullDate}}   — Today’s date in month-day-year format (March 22, 2018).

{ENV{ODBCDate}}   — Today’s date in ODBC format (2018-03-22).

{LOOP{USERS}}   — Instruction to begin creating a list of account names associated with the current email address. Used with   {USER{UserName}}   and   {ENDLOOP} . See   email-username-reminder-multi-*.html   for an example of use. 

*-new-message-notification-*.html




*-new-message-proxy-notification-*.html




*-proxyrelationship-notify-principal-*.html




*-proxyrelationship-notify-proxy-*.html




All files related to direct communications

{USER{FirstName}}   — Patient's first name.

{USER{LastName}}   — Patient's last name.

{USER{Email}}   — Patient's email address.

{ENV{PortalPath}}   — See definition in first row of table.

{ENV{Subject}}   — Subject of the email message.

{ENV{Reason}}   — Explanation of why an event has occurred for the current patient or pending patient, such as why an account has been deactivated.

{ENV{PrincipalName}}   — Current principal. Used when a distinction is required or useful between a proxy and a principal.

{ENV{ProxyName}}   — Current proxy. Used when a distinction is required or useful between a proxy and a principal.

{LOOP{USERS}}   — Instruction to begin creating a list of account names associated with the current email address. Used with   {USER{UserName}}   and   {ENDLOOP} . See   email-username-reminder-multi-*.html   for an example of use. 

*-password-change-*.html




*-password-reset-*.html




*-username-reminder-*.html




*-username-reminder-multi-*.html

{USER{FirstName}}   — Patient's first name.

{USER{LastName}}   — Patient's last name.

{USER{Email}}   — Patient's email address.

{USER{Token}}   — Patient's temporary access token.

{ENV{PortalPath}}   — See definition in first row of table.

{ENV{ResetLink}}   — URL for the   Reset Password   page for your organization’s instance.

{ENV{ExpiryTime}}   — Time at which a password reset link will expire.

{LOOP{USERS}}   — Instruction to begin creating a list of account names associated with the current email address. Used with   {USER{UserName}}   and   {ENDLOOP} . See   email-username-reminder-multi-*.html   for an example of use. 

*-selfenrollment-notification-*.html

{USER{FirstName}}   — Patient's first name.

{USER{LastName}}   — Patient's last name.

{USER{Email}}   — Patient's email address.

{USER{RequestID}}   — Unique identifier for a self-requested enrollment application.

{ENV{PortalPath}}   — See definition in first row of table.

{ENV{Subject}}   — Subject of the notification.

{LOOP{USERS}}   — Instruction to begin creating a list of account names associated with the current email address. Used with   {USER{UserName}}   and   {ENDLOOP} . See   email-username-reminder-multi-*.html   for an example of use.

4.3.1.2. Localizing the Date in Notifications

Email content triggered from event notifications often contains a date. The date configuration displayed in the email content is localized in a separate file, dateformat.json . By default, there is localized date configuration for the following locales: fr, it, es, de, pt_br, and ar. To change the date configuration, or create date configuration for a different language complete the following:
  1. If there is not already a custom copy of dateformat.json , copy the existing file from 

    <hspc-home> / base /content/ locale code / dateformat.json

    to

    <hspc-home> / custom /content/ locale code /

    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.

  2. Within the custom copy of dateformat.json , c ustomize the date format as required using the following 3 properties:
    1. format — Localized date pattern using the {D} (day), {M} (month name), and {Y} (year) placeholders. Static language-specific text and separators may be included between placeholders. Use "default" to apply the standard English format.
      1. Examples include:
        1. "{D} {M} {Y}" → 1 janvier 2026
        2. "{D} de {M} de {Y}" → 1 de enero de 2026
    2. months — Array of 12 localized month names following the target language capitalization rules.
    3. arabicDigits (optional) — Set to true to render day and year values using Arabic-Indic numerals.
    4. The following is an example of a non-Arabic language: 
      {
	"format":"{D} {M} {Y}"
	"months":["janvier", "février", "mars", "avril", "mai", "juin", "juillet", "août", "septembre", "octobre", "novembre", "décembre"]
}
    5. The following is an example of an Arabic language: 
      {
	"format":"{D} {M} {Y}"
	"months":["?????", "??????", "????", "?????", "????", "?????", "?????", "?????", "??????", "??????", "??????", "??????"],
    "arabicDigits": true
}
  3. Refresh Content in the Workbench

4.3.2.  External System Notifications

Notifications can be routed through Personal Community to patients’ external email addresses or mobile phones when certain events occur within external systems. The files that supply content for these notifications are distinct from those for Personal Community event notifications.

Personal Community ships with a set of files that can be used to notify members of new data in their external system health records. Depending on the needs of the external system, these notifications can be sent to the patients whose data is affected, their proxies, or both. These files are named as follows:

  • direct-communication-patient-newdata- text .html
  • direct-communication-patient-newdata- html .html
  • direct-communication-patient-newdata- sms .html
  • direct-communication-proxy-newdata- text .html
  • direct-communication-proxy-newdata- html .html
  • direct-communication-proxy-newdata- sms .html
  • Push Notification files:
    • direct-communication-patient-newdata-body-push.html
    • direct-communication-patient-newdata-title-push.html
    • direct-communication-proxy-newdata-body-push.html
    • direct-communication-proxy-newdata-title-push.html

4.3.3. Modifying Notification Content

Email content triggered from event notifications often contains a date. The date configuration displayed in the email content is localized in a separate file, dateformat.json . By default, there is localized date configuration for the following locales: fr, it, es, de, pt_br, and ar. To change the date configuration, or create date configuration for a different language complete the following:
  1. If there is not already a custom copy of dateformat.json , copy the existing file from 

    <hspc-home> / base /content/ locale code / dateformat.json

    to

    <hspc-home> / custom /content/ locale code /

    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.

  2. Within the custom copy of dateformat.json , c ustomize the date format as required using the following 3 properties:
    1. format — Localized date pattern using the {D} (day), {M} (month name), and {Y} (year) placeholders. Static language-specific text and separators may be included between placeholders. Use "default" to apply the standard English format.
      1. Examples include:
        1. "{D} {M} {Y}" → 1 janvier 2026
        2. "{D} de {M} de {Y}" → 1 de enero de 2026
    2. months — Array of 12 localized month names following the target language capitalization rules.
    3. arabicDigits (optional) — Set to true to render day and year values using Arabic-Indic numerals.
    4. The following is an example of a non-Arabic language: 
      {
	"format":"{D} {M} {Y}"
	"months":["janvier", "février", "mars", "avril", "mai", "juin", "juillet", "août", "septembre", "octobre", "novembre", "décembre"]
}
    5. The following is an example of an Arabic language: 
      {
	"format":"{D} {M} {Y}"
	"months":["?????", "??????", "????", "?????", "????", "?????", "?????", "?????", "??????", "??????", "??????", "??????"],
    "arabicDigits": true
}
  3. Refresh Content in the Workbench

4.3.4. Customizing the Appearance of HTML Email

Personal Community allows you to customize the appearance of HTML email through the use of a style template file. Enabling this feature allows your organization to use a single, uniform style for all its emails.

To customize the appearance of HTML emails, modify the style template file:

  1. The content file for the email style template is located in   email-template-html.htm . If there is not already a custom copy of the relevant content file, copy the existing file from

    <hspc-home> / base /content/ locale code /

    to

    <hspc-home> / custom /content/ locale code /

    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.

  2. Modify the style template according to your organization’s needs. When modifying the style template, you need to be aware of variables in it. These are:

    1. { IMAGE{assets/images/hspc-logo.png} }   — Specifies the relative path and file containing your organization’s logo. Replace   /images/hspc-logo.png   with your organization’s logo.

    2. { ENV{Subject} }   — Specifies email subject. Do not modify this header.

    3. { ENV{PortalPath} }   — Specifies email portal path. Do not modify this header.

    4. { ENV{BODY} }   — Specifies email body. Do not modify this header.

      Note

      Validate that the style template contains only conformant HTML.

  3. Refresh Content in the Workbench

4.3.5. Refresh Content in the Workbench

 

To refresh content:

  1. Log into the Workbench as a user who has the Configuration Manager role.

  2. Go to the Content tab.

  3. On the activity pane, select Content Updates . This displays the Content Updates page.

  4. 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.

4.4. 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:

  1. 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.

  2. Modify or localize each of the XML files containing the exported strings. See below for details about this process.

  3. 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.

  4. 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:

  1. 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.

  2. Change  Text for all strings that your organization is modifying or localizing.

  3. 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.5. Updating a Locale in the Workbench

To add or update a locale registration:

  1. Log in to the Workbench as a user with the   Configuration Manager   role.
  2. Navigate to  Setup  >  Locales .
  3. Search for and select the locale registration you want to change. This displays an empty   Locale Details  page.
  4. 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.
    • 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.
    • InterSystems EHR Language Code — Leave empty; This setting is only relevant for InterSystems EHR integrations. 
  5. Select  Save  to apply your changes.


FeedbackOpens in a new tab