Compatibilities

NlsMessageCatalog supports compatibilities, a mechanism to facilitate the sharing of translations among locales. Compatibilities can also be used to describe the default messages to be used in the event that the message catalog file does not contain messages for the current locale and character set.

NlsMessageCatalog compatibilities are stored in a sequenceable collection (array) of arrays. The first element of each array describes the primary language, territory, and character set (locale triple) for which localized message strings are actually stored in the catalog file. The remaining elements of each array describe locales which are compatible with, and can use the messages of, the primary locale. A catalog file contains one set of compatibilities.

"Structure of NlsMessage Catalog Compatibilities"

#(

#(

#('japanese' 'japan' 'ibm-932')

#('japanese' 'japanese' 'japan' 'microsoft-shiftjis')

)

#(

#('german' 'germany' 'iso8859-1')

#('german' '*' 'iso8859-1')

)

#(

#('english' 'us' 'ansi-ascii')

#('*' '*' '*')

)

)

NlsMessageCatalog>>localeCompatibleWithLanguage:territory:characterSet: can be used to determine the locale whose messages are compatible with a given language, territory, and character set. The compatibilities depicted in the example above indicate that the catalog contains messages for primary locales japanese-japan-ibm-932, german-germany-iso8859-1, and english-us-ansi-ascii.

Given a locale triple, localeCompatibleWithLanguage:territory:characterSet: first determines if messages are explicitly stored for that locale. In the above example, the locale japanese-japan-ibm-932 is actually stored in the catalog. Therefore, localeCompatibleWithLanguage:territory:characterSet uses the messages of this locale without consulting the compatibility information. Similarly, locales german-germany-iso8859-1 and english-us-ansi-ascii use their stored messages.

If messages for the given locale are not explicitly stored in the catalog, localeCompatibleWithLanguage:territory:characterSet: uses the compatibility information to determine the compatible locale. The process starts with the first array (for example, ('japanese-japan-ibm-932' 'japanese-japan-microsoft-shiftjis') in the previous example) and proceeds sequentially until the last array (for example, (english-us-ansi-ascii' '*-*-*') in the previous example). If an element of an array matches the given locale the messages of the primary locale (for example, japanese-japan-ibm-932) are considered to be compatible with the given locale. Compatibility matching stops after the first match is found.

The last compatibility illustrated in the previous example, #('english-us-ansi-ascii' '*-*-*'), indicates that if no other array was able to match the given locale triple, use *-*-* to match the locale triple, and default to using english-us-ansi-ascii messages. ANSI-ASCII characters are contained in the lower portion of many character sets and thus provide a reasonable fall-back.

"Sharing localized messages using compatibilities"

german-switzerland-iso8859-1

matches

#('german' 'germany' 'iso8859-1')

#('german' '*' 'iso8859-1')

and uses

'german' 'germany' 'iso8859-1'.

The next example

german-switzerland-ibm-850

does not match

'german' '*' 'iso8859-1'

and therefore uses messages for

'english' 'us' 'ansi-ascii'.

The next example

japanese-japan-microsoft-shiftjis

matches

#('japanese' 'japan' 'ibm-932')

#('japanese' 'japan' 'microsoft-shiftjis')

and uses messages for

'japanese' 'japan' 'ibm-932'.

The compatibilities from the example suggest that the application has iso8859-1 translations for German, but likely has has not been localized for different German-speaking territories. In other words, the application likely has a single German version sold in multiple German-speaking territories. The example above illustrates the results of the compatibilities matching process as applied to the compatibilities described in the example showing the structure of NlsMessageCatalog compatibilities. The locale english-us-ansi-ascii is an abstract locale. Abstract locales do not correspond to actual platform supported locates; however, they can be used to help organize the messages of a catalog.

Storing and retrieving compatibilities

NlsMessageCatalog provides the compatibilities and compatibilities: methods to retrieve and store message catalog compatibilities. The following example illustrates the process of storing and retrieving message catalog compatibilities.

"Set and retrieve the compatibilities of a message catalog file."

| catalog compatibilities |

compatibilities :=

#(

#(

#('japanese' 'japan' 'ibm-932')

#('japanese' 'japanese' 'japan' 'microsoft-shiftjis')

)

#(

#('german' 'germany' 'iso8859-1')

#('german' '*' 'iso8859-1')

)

#(

#('english' 'us' 'ansi-ascii')

#('*' '*' '*')

)

)

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

(catalog compatibilities: compatibilities) ifFalse: [

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

^catalog compatibilities