docs.intersystems.com
Using Caché Server Pages (CSP)
Localization and Tag-Based Development
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Search:    

This appendix discusses how to localize CSP pages when you are doing tag-based development. Also read the chapter Localizing Text in a CSP Application.”

Introduction
During tag-based development of CSP pages, you can configure certain tags so that they substitute a message dictionary entry for what would otherwise be literal text. Do this by providing the localization attributes language, domain, or textid inside the tag. The following tags support these attributes:
For the most part, these tags work only at runtime, when the values provided for language, domain, and textid indicate which message to retrieve from the message dictionary.
However, in limited cases these tags serve different purposes at compile time and runtime. They can automatically generate entries for the message dictionary at compile time, then retrieve and display these entries at runtime. The following sections explain how this works:
For a simple demonstration of a localized CSP application, enter the following URL while Caché is running: http://localhost:57772/csp/samples/language.csp.
Localization Tags at Runtime
Important:
This topic applies to the CSP tags <csp:text>, <span>, <div>, <input>, and <button> only.
At runtime, when the CSP page displays, the tag replaces itself and its contents with text from the message dictionary. The choice of text is specified by the language, domain, and textid attribute values supplied by the tag.
For example, the following syntax is replaced by the message specified by the fr (French) language, sample domain, and menu message ID. The text provided inside the <csp:text> tag (Menu in this case) is ignored:
<csp:text textid="menu" language="fr" domain="sample">Menu</csp:text>
Defaults for language, domain, and textid are available if any of the attributes are omitted or empty (value ""):
Default Language
Most developers intentionally provide no language attribute so that, at runtime, the language defaults appropriately for the locale. If not supplied, language defaults to the value of %response.Language, which automatically takes its runtime value from the browser settings.
You can see examples of this convention in the source code for the localization example in the SAMPLES namespace. View it as follows:
  1. Start Studio.
  2. Change to the SAMPLES namespace.
  3. In the Workspace window, click the Namespace tab.
  4. Choose CSP Files.
Default Domain
The %response.Domain property is initialized with the value of the DOMAIN parameter of the CSP page class. You can also set a value for %response.Domain using the domain attribute of the <csp:class> tag, as in:
<csp:class domain="myDomainName">
Message Arguments
If the message text contains arguments (%1, %2, %3, %4) the following tag attributes let you specify the corresponding substitution text: arg1, arg2, arg3, arg4. You may provide literal values or use variables. For example:
<csp:text textid="sessionInfo" arg1="#(userName)#" arg2="#(roleID)#" />
Button Text
In tag-based CSP files, the text displayed on a button is normally specified using the value attribute of the <input type="button"> or <button> tag.
When an <input> tag uses localization attributes (language, domain, or textid) the value attribute is ignored. The text displayed on the button is the text from the message dictionary. If you want to localize the text on a <button> tag, use the language, domain, or textid attributes of the <csp:text> tag.
Localization Tags at Compile Time
Important:
This topic applies to the CSP tags <csp:text>, <span>, <div>, and <input> tags only.
The textid attribute may have the empty value "". If so, when you compile the tag-based CSP file a new message is automatically generated in the message dictionary. The text for the generated message consists of the contents of the CSP tag. Caché generates a message ID by calculating the 32–bit CRC (Cyclic Redundancy Check) of this text.
Only the <csp:text> tag permits you to actually omit the required textid attribute. The other localization tags require you to at least provide an empty value "".
If a <csp:text> tag lacks a textid attribute, the system automatically generates a new message and message ID value. In cases where you omit textid from <csp:text>, the text inside the tag may include an optional @textID@ string at the beginning. textID is the message ID that you wish to assign to the message. For example:
<csp:text>@simpleMenu@Menu</csp:text>
In the above example, Caché does not generate the message ID. It generates a message whose text is Menu and gives it the message ID simpleMenu.
When a CSP tag has been used to generate a message dictionary entry at compile time, it still works as a reference to retrieve that entry at runtime. See the section Localization Tags at Runtime.”