Introduction to String Localization
This page provides an overview of string localization in InterSystems products — a key part of the localization support.
Localization Basics
When you localize the text for an application, you create an inventory of text strings in one language, then establish a convention for substituting translated versions of these messages in another language when the application locale is different. Accordingly, InterSystems products support the following process for localizing strings:
-
Developers include localizable strings within their code (within a web application or a Business Intelligence model).
The mechanisms for this vary, but the most common mechanism is the $$$Text macro. In the place of a hardcoded literal string, the developer includes an instance of the $$$Text macro, providing values for the macro arguments as follows:
-
The default string
-
The domain to which this string belongs (localization is easier to manage when the strings are grouped into domains)
-
The language code of the default string
For example, instead of this:
write "Hello world"
The developer includes this:
write $$$Text("Hello world","sampledomain","en-us")
-
-
When the code is compiled, the compiler generates entries in the message dictionary for each unique instance of the $$$Text macro.
The message dictionary is a global and so can be easily viewed (for example) in the Management Portal. There are class methods to manage the data.
-
When development is complete, release engineers export the message dictionary for that domain or for all domains.
The result is one or more XML message file that contain the text strings in the original language.
-
Release engineers send these files to translators, requesting translated versions.
-
Translators work with the files using any XML authoring tool they prefer. Essentially they translate text from the original language to a new language, without changing the surrounding XML.
-
Translators return a new file that has the same structure and that:
-
Identifies a new RFC1766Opens in a new tab value for the language attribute of the <MsgFile> element.
-
Contains translated text in the identified language.
-
-
Release engineers import the translated XML message files into the same namespace from which the original was exported.
Translated and original texts coexist in the message dictionary.
-
At runtime, the application chooses which text to display based on the browser default language.
Localization Macros
This section gives details on the macros used for localization. These macros are contained in %occMessages.inc, which is included in %occInclude.inc):
-
$$$Text returns a string
-
$$$TextJS returns a string that is escaped for use in JavaScript
-
$$$TextHTML returns a string that is escaped for use in HTML
Each of these macros takes three arguments: the default string, the domain to which this string belongs, and the language code of the default string. When code is compiled, the compiler generates entries in the message dictionary for each unique set of values of the arguments.
Macro Details
The $$$Text, $$$TextJS, and $$$TextHTML macros take the following arguments in order:
A non-empty literal string. The format used for text may be:
"actualText"
Or:
"@textId@actualText"
Where textId is a message ID and actualText is the text of the message.
The string actualText may consist of any of the following items, separately or in combination:
-
Simple text, as permitted by the file format
-
Substitution arguments %1, %2, %3, or %4
-
HTML formatting
-
An ObjectScript string expression
If provided, the textId is used as the message ID. If @textId@ is not specified, the system generates a new textId by calculating the 32–bit CRC (Cyclic Redundancy Check) of this text. If the textId is specified and a message already exists with this ID, the existing message is checked to see if it has the same text as actualText. If not, an error is reported.
(Optional) String specifying the domain for the new message. If not specified, domain defaults to the value of the DOMAIN class parameter at compile time and %response.Domain at runtime.
(Optional) RFC1766Opens in a new tab code specifying the language. InterSystems IRIS converts this string to all-lowercase. If not specified, language defaults as follows:
-
At compile time: $$$DefaultLanguage.
-
At runtime (within a CSP-based web application), the default is %response.Language, or if no value is defined for %response.Language then $$$DefaultLanguage.
-
At runtime (in other contexts) : $$$DefaultLanguage.
Message Arguments and $$$FormatText Macros
If the message text contains arguments (%1, %2, %3, %4) you must specify the corresponding substitution text before displaying the text. Because $$$Text returns a string, you can use any string operation native to your coding language. For example, in JavaScript:
var prompt = '#($$$TextHTML("Remove user %1 from this Role?"))#';
prompt = prompt.replace(/%1/g,member.userName);
InterSystems provides additional macros that enable you to substitute text for message arguments:
-
$$$FormatText
-
$$$FormatTextJS (applies JavaScript escaping to the $$$FormatText result)
-
$$$FormatTextHTML (applies HTML escaping to the $$$FormatText result)
These macros are in %occMessages.inc, which is included in %occInclude.inc. These macros take the following arguments in order:
The message text, a string. Use the value returned by $$$Text.
Substitution text for the message arguments.