Using external message dictionaries

Unloading external message dictionaries

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.

"A code fragment to create a message catalog file containing 'demo.cat'

containing an external message dictionary for the ('english' 'us') locale

and the 'iso8859-1' character set."

| catalog |

catalog := NlsMessageCatalog on: 'demo.cat'.

"Create the message catalog file."

(catalog unload: MyNlsMessages

language: 'english'

territory: 'us'

characterSet: 'iso8859-1') ifFalse: [

^self error: 'Unload error: ',catalog currentErrorString].

Loading messages into a pool dictionary

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.

"A code fragment to load messages from an existing message catalog file

called 'demo.cat' for the #('english' 'us') locale and the 'iso8859-1'

character set."

| catalog |

catalog := NlsMessageCatalog on: 'demo.cat'.

(catalog loadLanguage: 'english'

territory: 'us'

characterSet: 'iso8859-1'

intoDictionary: MyNlsMessages) ifFalse: [

^self error: 'Load error: ',catalog currentErrorString].

 

Note:

No keys are added to an existing pool by the loadLanguage:territory:characterSet:intoDictionary: operation. Only the values of the existing keys are modified. This features ensures that unused shared pool variables removed during packaging are not reintroduced in NlsMessageCatalog.

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.

Loading messages without initializing a pool dictionary

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.

"A code fragment to load messages from an existing message catalog file

called 'demo.cat' for the #('english' 'us') locale and the 'iso8859-1'

character set."

| catalog |

catalog := NlsMessageCatalog on: 'demo.cat'.

(catalog loadLanguage: 'english'

territory: 'us'

characterSet: 'iso8859-1') isNil ifTrue: [

^self error: 'Load error: ',catalog currentErrorString].

Declaring pool dictionary keys

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.

"Declare the pool MyNlsMessages and populate it with keys based on the

messages stored for #('english' 'us' 'iso8859-1')."

| pool catalog |

pool := Smalltalk declarePoolDictionary: #MyNlsMessages.

catalog := NlsMessageCatalog on: 'demo.cat'.

(catalog

declareKeysFor: pool

language: 'english'

territory: 'us'

characterSet: 'iso8859-1') ifFalse: [

^self error: 'Declaration error: ',catalog currentErrorString].

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.

Defining managed pool dictionaries

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.

_PRAGMA_MyNlsMessages

"%%PRAGMA DECLARE

(name: MyNlsMessages isPool: true pragma: 'NLS mynls')

(pool: myNlsMessages declarations: (

(name: Message1)

(name: Message2)

))"

Deleting external message dictionaries

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.

"Remove the message dictionary stored for #('english' 'us' 'iso8859-1')."

| catalog |

catalog := NlsMessageCatalog on: 'demo.cat'.

(catalog

deleteDictionaryLanguage: 'english'

territory: 'us'

characterSet: 'iso8859-1') ifFalse: [

^self error: 'Deletion error: ',catalog currentErrorString].

 

Note:

Deleting an external message dictionary does not immediately decrease the size of the message catalog file on disk. Deleted external dictionaries are marked as garbage and their space is reclaimed when the message catalog file is compressed. See Compression for a discussion of the compression of message catalog files.

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