%Library.MessageDictionary
Class %Library.MessageDictionary Extends %RegisteredObject [ System = 3 ]
For information on this class, see String Localization and Message Dictionaries.
The %MessageDictionary is introduced to allow easy localization of program messages and CSP page content. A %MessageDictionary is a dictionary of messages. Each message in the dictionary is any ObjectScript string and is indexed by any ObjectScript value. A %MessageDictionary is then defined for each language and domain needed by your application. Each message is indexed by language, domain and id.
In order for a %MessageDictionary object to be created (New'ed), a language and domain must be specified for the message dictionary. The format of the specification string is "
Properties
Language
Property Language As %String;
The Language attribute defines the language of the messages in the Message Dictionary. Language is any RFC 1766 defined language tag. In summary, a language tag is composed of 1 or more parts: A primary language tag optionally followed by a hyphen (-) separated secondary subtag. The Language string will be normalized to all lower case characters.
Domain
Property Domain As %String;
The Domain attribute defines the logical grouping of messages in the Message Dictionary. If the domain name begins with %, then the Message Dictionary is considered a system Message Dictionary that is visible in all namespaces. Application Message Dictionaries are visible in only the namespace in which they are defined.
Methods
%OnNew
Method %OnNew(initvalue) As %Status
Import
ClassMethod Import(filepath As %String, flag As %String = "") As %Status
Import the Message Dictionary(s) in an XML file specified by filepath. All Message Dictionaries in the file will be imported. The "d", display, flag is supported.
One or more Message Dictionaries may be specified by the XML file in the format given by the DTD at <?xml version="1.0" encoding="UTF-8"?> message text . . . . . .
We recommend using the UTF-8 encoding for these files whenever possible. Sometimes local platform encodings, such as shift-jis, are needed for ease of editing. The encoding that is picked must be supported by the locale for the application and be able to express the messages for this file's language.
ImportDir
ClassMethod ImportDir(directory As %String, flag As %String = "") As %Status
Import the Message Dictionary(s) in all of the XML file in the specified directory. The "d", display, flag is supported.
The format of the XML files is described with the Import.
Delete
ClassMethod Delete(languages As %String = "", flag As %String = "") As %Status
Delete all Message Dictionary(s) for the specified languages. Languages is an optional comma separated list of languages whose Message Dictionaries are to be deleted. If languages is not specified, Message Dictionaries for all languages are deleted. The "s", system flag, is an optional flag indicating whether system "s" or application Message Dictionaries are to be dleeted. The default value is to delete application Message Dictionaries.
The messages names associated with include files are always deleted, but not any previously geenrated include files. The "d", display, flag is supported.
GenerateInclude
ClassMethod GenerateInclude(includeName As %String, flag As %String = "", DomainList = "", UseDomainName As %Boolean = 0) As %Status
Generate an include file mapping the Name attributes of each message in any Message Dictionary to the message id.
The name of the include file to be generated is includeName. The DomainList argument is a comma separated list of names of the domains for which the include file is to generated. If Domain is not specified or "", then all domains are included in the include file. If UseDomainName is true (1), then the domain name as "" is prepended to the message code in the include file. The "s", system flag, is an optional flag indicating whether system, "s", or application Message Dictionaries are to be exported. The "d", display, flag is supported.
Export
ClassMethod Export(file As %String, languages As %String = "", flag As %String = "") As %Status
Export Message Dictionaries to XML file(s). languages is an optional comma separated list of languages. If languages is not specified, all languages are exported. Each language in the list is exported to a separate file. The template for the filename is given by the file argument that is of the format "
ExportDomainList
ClassMethod ExportDomainList(file As %String, domainList As %String, language As %String) As %Status
Export Message Dictionaries for the specified languages and domains. fil is the path of the file to be written. domainList is a comma separated list of domains to be exported. language is an optional language that default to the current session language, $$$SessionLanguage.
GetLanguages
ClassMethod GetLanguages(domain As %String = "", flag As %String = "") As %ListOfDataTypes
GetLanguages returns a list of all languages that have messages loaded for the specified domain or all languages if domain="" Each language is in the standard RFC1766 format and all in lower case. The "s", system flag, is an optional flag indicating whether languages supported by system ("s") or application Message Dictionaries are to be returned. The default value is to return the languages for application Message Dictionaries.
GetDomains
ClassMethod GetDomains(language As %String = "", flag As %String = "") As %ListOfDataTypes
GetDomains returns a list of all domains that have messages loaded for the specified language. If language="" is specifed, the default language is used. The "s", system flag, is an optional flag indicating whether languages supported by system ("s") or application Message Dictionaries are to be returned. The default value is to return the domains for application Message Dictionaries.
MatchLanguage
ClassMethod MatchLanguage(languages As %String, domain As %String = "", flag As %String = "") As %String
Get the best language match to a language in the list languages for the specified domain using HTTP 1.1 matching rules (RFC 2616). The list of languages is a comma separated list of RFC 1766 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 input list. 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 "-". The special language "*", 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 by the is the quality value of the longest language in the list thatt matches the language-tag. The language that is returned is the supported language that has been assigned the highest quality factor. The "s", system flag, is an optional flag indicating whether system, "s", or application Message Dictionaries are to be matched.
GetMessage
Method GetMessage(id As %String, default As %String = "") As %String
Get message text from this Message Dictionary. The default argument is used for the message if no message is found for id. No message formatting is supported by this method.
GetNextMessage
Method GetNextMessage(ByRef id As %String) As %String
Return the text and id of the next message. The text and id of the message with the next id are returned. If the input id = "", then the text and id of the first message are returned. Return an empty string for the message text and id, if the input id was for the last message. Language is optional and the current language is used if language is "" or not specified. Language will be converted to lower case before being used. Domain can be a system domain beginning with % or a application domain.
FormatMessage
Method FormatMessage(id As %String, default As %String, args...) As %String
Get and format message text from this Message Dictionary. The default argument is used for the message if no message is found for id. If the default argument is not specified, then string for the default language or English is used as the default. Arguments of the form %1, %2, etc will be replaced by arguments that follow the id argument.
FormatText
ClassMethod FormatText(text As %String, args...) As %String
Format the specified message text. Arguments of the form %1, %2, etc will be replaced by arguments that follow the text argument.
GetSessionLanguage
ClassMethod GetSessionLanguage() As %String
GetSessionLanguage retrieves the default session language for the messages in the Message Dictionary. The language returned is a RFC 1766 defined language tag.
In summary, a language tag is composed of 1 or more parts: A primary language tag optionally followed by a hyphen (-) separated secondary subtag. The Language string will be normalized to all lower case characters.
SetSessionLanguage
ClassMethod SetSessionLanguage(language As %String) As %String
SetSessionLanguage sets the default session language for the messages in the Message Dictionary. The language argument is a RFC 1766 defined language tag. The return value is the previous default session language. In summary, a language tag is composed of 1 or more parts: A primary language tag optionally followed by a hyphen (-) separated secondary subtag. The Language string will be normalized to all lower case characters.