Excel Addin Localization

The Excel Addin can be fully localized and various languages can be managed within the Modeler. The Localization process consists of translating all messages in a text file and loading the message file for use by the clients. All messages in the file are identified by a unique key. To assist in the process a sample file is supplied that contains all possible messages with the default English value preceded by an L. The name of the sample file is TestLanguage.txt and the name of the sample language contained in the file is “Test”.


Message File

The sample message file is located in the Localization folder and named “TestLanguage.txt”. To create a new message file, copy this file to a new file, and place the file anywhere it is convenient to work with. This file contains one line for each string used within the Excel Addin. Each line begins with a unique key value, followed by exactly ONE Tab character, followed by the translated value for the key. The file can be easily opened in Excel where the first column will contain a key and the second column will contain the translated value for the key. However, the file must be saved as a UTF8 format and Excel may not properly identify the file as UTF8. This can be easily corrected by opening the file with Notepad and saving it as UTF8 format. (Note: If the file is not properly saved in UTF8 format non English characters may not appear properly in the Excel Addin.)

The first key in the sample file is “Language.Name” which is the entry containing the name of the language this file will contain. When a message file is loaded, this is the language it will be loaded to. Other keys contain values for the UI elements and messages that occur in the Excel Addin. If any keys are missing from the message file, those UI elements or messages will use default English values. Some of the messages in the sample contain a notation where values are dynamically supplied by the Excel Addin to more clearly explain things. The notation for these dynamic substitutions is {0} {1} etc. where there is a left brace with a number followed by a right brace to identify which parameter goes where.

After making changes to the message file, it must be loaded using the Modeler to make it available in the Excel Addin.


Managing Languages in the Modeler

To manage languages in the Modeler from the Application Selector screen, select the Server Setup, and then select the Language tab. The Modeler allows you to:

  • Load a new translated language file.

  • Add a language to make it available to Excel users.

  • Remove a language to make it unavailable to Excel users.

Load

When a message file is Loaded, all keys are validated and any incorrect keys found are returned in an error message. From the messages a language “.lng” file is created and saved in the LocalizedMessages table within the CallistoAppDictionary sql database. A copy of the language file is saved as callisto.lng within a folder with the same name as the language in the Localization folder on the server.

Add

When a message is Added, the language file is read from the appropriate folder for the requested language on the server and added to the LocalizedMessages table within the CallistoAppDictionary database. This makes the language available to Excel users.

Remove

Deletes the language from the LocalizedMessages table within the CallistoAppDictionary databse. This makes the language unavailable to Excel users.


Excel Addin

When users logon to Excel there is Language button on the Application Selector dialog box that opens the Language Selector dialog box. The Language Selector presents a list of available languages for the user to select their desired language. After selecting a language the Excel Addin will use the translated values for all UI elements and messages defined for that language. The Excel Addin will continue to use messages for the selected language for the current session and for all other sessions, until the user changes the selection. When messages for a language are changed on the server, the modified messages will be automatically picked up by the Excel client the next time a user opens the Application Selector dialog box. To clear the language selection and revert to the default language, select the first entry in the language list.

How to change the default language for the Excel Addin

To change the default language for the Excel Addin, place a copy of the appropriate callisto.lng file in the same folder on the client containing the callisto.xll file. When there is no language selected in the Language Selector the Excel Addin checks for a language file in the same location as the callisto.xll file. This allows for changing the default language so non English users can always start their experience in their native language.