Skip to main content

Localizing Text in a CSP Page

For general information on localizing application text, see String Localization and Message Dictionaries.

For a CSP-based web application, there are additional options that use the %response object.

Setting the Default Runtime Language

For text localized via the $$$Text, $$$TextJS, and $$$TextHTML macros, the default runtime language is determined by the Language property of the %response object, if you have set that explicitly. If the Language property is not set explicitly, the runtime language is determined by the browser settings.

The recommended way to set the Language property is to use the MatchLanguage() method of %Library.MessageDictionaryOpens in a new tab, as in the following example:

 Set lang = ##class(%MessageDictionary).MatchLanguage(languages,domain,flag)
 Set %response.Language=lang

Given a list of languages and a domain name, this method uses HTTP 1.1 matching rules (RFC2616Opens in a new tab) to find the best-match language within the domain. This method has the following signature:

classmethod MatchLanguage(languages As %String, 
                          domain As %String = "", 
                          flag As %String = "") as %String


  • languages is a comma-separated list of RFC1766Opens in a new tab format language names. Each language in the list may be given an associated quality value which represents an estimate of the user’s preference for the languages specified by the list of languages. The quality value defaults to q=1.

    For example, da, en-gb;q=0.8, en;q=0.7 would mean: I prefer Danish, but will accept British English and other types of English. A language from the list matches a supported language tag if it exactly equals the tag, or if it exactly equals a prefix of the tag such that the first tag character following the prefix is a hyphen (-). The special language asterisk (*), if present in the input list, matches every supported language not matched by any other language present in the list.

    The language quality factor assigned to a supported language tag is the quality value of the longest language in the list that matches the language-tag. The language that is returned is the supported language that has been assigned the highest quality factor.

  • domain is the localization domain in which to perform the matching.

  • flag is an optional flag indicating whether system or application messages are to be matched.

%response.GetText() Method

The %response object includes a GetText() instance method that enables you to retrieve text from the message dictionary and substitute values for any arguments the message may have.

The method signature is:

 method GetText(language As %String = "",
                domain As %String = "",
                id As %String,
                default As %String,
                args...) returns %String


  • language is an optional RFC1766Opens in a new tab code specifying the language. InterSystems IRIS converts this string to all-lowercase. The default language is the Language property of the %response. If the Language property is not set explicitly, the language used is determined by the browser settings.

  • domain is an optional string specifying the domain for the message. If not specified, domain defaults to the Domain property of the %response object.

  • id is the message ID.

  • default is the string to return if the message identified by language, domain, and id is not found.

  • arg1, arg2, and so on are the substitution text for the message arguments. All of these are optional, so you can use GetText() even if the message has no arguments.

FeedbackOpens in a new tab