Managing a Message Dictionary
This topic summarizes the %Library.MessageDictionaryOpens in a new tab methods that are most commonly used when working with a message dictionary, used in string localization.
Importing Messages
To import an XML message file, open the Terminal and do the following:
-
Change to the namespace where you are developing the application:
set $namespace = "myNamespace"
-
Run the import command. By default, each language is in a separate XML message file, with the locale name at the end of the filename. Thus:
-
You can import only those messages in a particular language:
SET file="C:\myLocation\Messages_ja-jp.xml" DO ##class(%Library.MessageDictionary).Import(file)
-
Or, import several languages for the same application:
SET myFiles="C:\myLocation" DO ##class(%Library.MessageDictionary).ImportDir(myFiles,"d")
-
-
Examine the ^IRIS.Msg global in the same namespace to see the result.
The following topics summarize both import methods.
Importing a Specific XML Message File
The %Library.MessageDictionaryOpens in a new tab class method Import() has the following signature:
classmethod Import(filepath As %String, flag As %String = "") returns %Status
Where:
-
filepath specifies the full pathname of the message file.
-
flag is an optional flag. If provided, the d flag (display) indicates that the Terminal console will display confirmation messages as files are imported. Otherwise, there is no confirmation.
Importing All the XML Message Files in a Directory
The %Library.MessageDictionaryOpens in a new tab class method ImportDir() has the following signature:
classmethod ImportDir(directory As %String, flag As %String = "") returns %Status
Where
-
filepath specifies a directory file. Make sure that only XML message files are in the directory as other XML files generate errors.
-
flag is an optional flag. If provided, the d flag (display) indicates that the Terminal console will display confirmation messages as files are imported. Otherwise, there is no confirmation.
Exporting Messages
To export portions of a message dictionary to an XML message file, do the following within the Terminal:
-
Change to the namespace where you are developing the application:
set $namespace = "myNamespace"
-
Identify the output file and its location:
SET file="C:\myLocation\Messages.xml"
-
Run the export command:
-
It may be practical to export only those messages in a particular domain:
DO ##class(%Library.MessageDictionary).ExportDomainList(file,"myDomain")
-
Or, to export all the messages in the namespace:
DO ##class(%Library.MessageDictionary).Export(file)
-
The following topics summarize both export methods.
Exporting Specific Domains in One Language
The %Library.MessageDictionaryOpens in a new tab class method ExportDomainList() has the following signature:
classmethod ExportDomainList(file As %String,
domainList As %String,
language As %String) returns %Status
Where:
-
file is a template for the output filename in this format:
filepath.ext
The actual output file name appends the language value to the filepath with an extension of ext.
-
domainList is an optional comma-separated list of domains to be exported.
-
language is an all-lowercase RFC1766Opens in a new tab code. If not provided, the value defaults to the system default language.
Exporting All Domains in Specific Languages
The %Library.MessageDictionaryOpens in a new tab class method Export() has the following signature:
classmethod Export(file As %String,
languages As %String = "",
flag As %String = "") returns %Status
Where:
-
file is a template for the output filename in this format:
filepath.ext
The name of the output file is filepathlanguage-code.ext
For example, if file is c:/temp/mylang_.txt and languages includes the language code ja-jp, then one of the output files is named c:/temp/mylang_ja-jp.txt
-
languages is an optional comma-separated list of language codes. Each value in the list must be an all-lowercase RFC1766Opens in a new tab code. If languages is not specified, or is empty, all languages in the database are exported. Each language is exported to a separate file using the conventions described for the file argument.
-
flag is an optional flag. If provided, the s flag (system) indicates that system message dictionaries are to be exported in addition to application message dictionaries. Otherwise, only application message dictionaries are exported.
Deleting Messages
To delete messages use the following command:
Set status = ##class(%MessageDictionary).Delete(languages,flag)
languages is an optional comma-separated list of languages. If languages is not specified, all languages are deleted. The default value is to delete application messages only. The s flag (system) is an optional flag indicating whether to also delete system messages. The message names associated with include files are always deleted, but not the include files. The d flag (display) is also supported.
Listing Messages
To get the list of all languages that have messages loaded for a specified domain, use the GetLanguages() method:
Set list = ##class(%MessageDictionary).GetLanguages(domain,flag)
GetLanguages() returns a %ListofDateTypes format list of language codes in the standard RFC1766Opens in a new tab format and all in lowercase. If domain is specified, then only languages that exist for the specified domain are included in the list. Otherwise, all languages are included in the list. The s flag (system) is an optional flag indicating whether languages supported by system or application messages are to be returned. The default value is to return the languages for application messages. The d flag (display) is also supported.