The unload:language:territory:characterSet: protocol is used to create (or add to) a message file that contains a dictionary of messages for a particular locale and character set. The protocol can also be used to overwrite the value of an existing external message dictionary. You must intitialize the dictionary being dumped with the correct keys and values before unloading. Several external message dictionaries can be stored in a single message catalog file by making repeated calls using unload:language:territory:characterSet:.

The following example creates an NlsMessageCatalog that contains an external message dictionary. This example assumes the use of a pool dictionary called MyNlsMessages containing localized message strings. Return values of all NlsMessageCatalog operations must be checked to ensure that the operation has succeeded.

The loadLanguage:territory:characterSet:intoDictionary: protocol is used to update an existing pool dictionary with values retrieved from a message catalog file. The NlsMessageCatalog answers a Boolean value indicating success or failure of the load operation.

The following example loads messages into an existing pool dictionary using an NlsMessageCatalog. The example assumes the existence of a pool dictionary called MyNlsMessages into which all messages can be loaded. You must check the return values of all NlsMessageCatalog operations to ensure that the operation has succeeded.

When pool variables are referenced directly in source code, the associations contained in the pool dictionary are directly referenced by instances of CompiledMethod. As a result, when a pool dictionary is localized, the associations that contain the localized messages must be directly modified. Assigning a localized version of the pool dictionary to the global variable that references the dictionary does not work. The NlsMessageCatalog contains protocols that directly modify the associations that contain localized messages and ensure consistency of loaded messages.

The loadLanguage:territory:characterSet: protocol is used to load an external message dictionary from a message catalog file without loading into a pool dictionary. The NlsMessageCatalog answers the Dictionary of messages retrieved from disk, or nil if an error occurs.

The following example shows how to load an external message dictionary without initializing a pool dictionary. You must check the return values of all NlsMessageCatalog operations to ensure that the load operation has succeeded.

The declareKeysFor:language:territory:characterSet: message can be used to declare keys in a pool dictionary from a message catalog file. This operation reads the external message dictionary for a specified language, territory, and character set from a message catalog file and declares new keys in a user-supplied pool.

The declareKeysFor:language:territory:characterSet: operation does not affect values of existing pool variables and does not remove keys from the supplied pool. The values of newly declared keys are the same as the key to assist in identification of missing translations. The NlsMessageCatalog answers true if this operation succeeds, otherwise answers false.

The following example demonstrates how to declare pool keys from a message catalog file. This example assumes the existence of the pool dictionary MyNlsMessages in which keys will be declared.

Using declareKeysFor:language:territory:characterSet: can simplify the pool declaration process, but only if you are using an unmanaged pool dictionary. This method cannot be used to declare keys in a managed pool.

You can define managed pool dictionaries using variable declaration methods. When you do so, tag the pool declaration with a PRAGMA field, which identifies the pool dictionary as an NLS pool dictionary. The PRAGMA field is a string prefixed by NLS followed by a space and the name of the catalog (without an extension).

You should place the following variable declaration in the application that manages the pool dictionary. The following variable declaration method declares a pool dictionary called MyNlsMessages, which contains two pool variables (Message1 and Message2) whose catalog file is mynls.cat.

You can delete an external message dictionary from a message catalog file using the deleteDictionaryLanguage:territory:characterSet: protocol. This operation removes only the external message dictionary stored for the specified language, territory, and character set and does not affect any indexed external messages or other message dictionaries. The following example demonstrates how to delete an external message dictionary from a message catalog file.

Deletion is a permanent operation and cannot be undone. After an external message dictionary is deleted, it is lost.