This page provides an overview of string localization in InterSystems products — a key part of the localization support.
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:
For example, instead of this:
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:
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.
This section gives details on the macros used for localization. These macros are contained in %occMessages.inc, which is included in %occInclude.inc):
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.
Message Arguments and $$$FormatText Macros
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:
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.
arg1, arg2, and so on
Substitution text for the message arguments.