Demonstrates how to support multiple languages in a single XLL

Overview

This add-in demonstrates how to support multiple languages in a single XLL, using a resource file. The add-in will use the language that best matches the user's current regional settings, as set in the Control Panel.

For step-by-step instructions on how to convert an existing project to support multiple languages, see Conversion of an existing project in the User Guide.

For a sample that allows the language to be changed dynamically, see Dynamic localized (Single DLL) sample.

Impact of localization

Depending on which language is being used, various features of the add-in will appear differently:

Resource file

The resource file InterSingle.rc contains two string tables, one in English (US) and one in French (France). It also contains two bitmaps, one for each language.

To localize run-time error messages, the french error message file xlpresfrfr.rc is included along with the standard english file xlpres.rc.

Resource IDs

In contrast to a standard XLL, this one uses resource IDs such as #202 instead of strings wherever possible. These IDs represent strings held in the resource file. The XLL+ run-time libraries take care of loading the correct language version of the string.

Resource IDs should be used in the following places:

For the library name:

CopyC++

/* static */ LPCTSTR CInterSingleApp::m_pszDefName = _T("#1");

For menu text:

CopyC++

m_menu.SetTexts(_T("#2"));
m_menu.AddItem(_T("#3"), "BuyWater");

For toolbar text:

CopyC++

// Create toolbar
CXlToolbar::AddToolbar(m_pszToolbarName);
CXlToolbar::AddTool(m_pszToolbarName, 1, _T("BuyWater"), _T("#5"));
CXlToolbar::SetToolBitmap(m_pszToolbarName, 1, IDB_BITMAP1);
CXlToolbar::ShowToolbar(m_pszToolbarName, true, CXlToolbar::DockRight);

For add-in function help text and category, using the XLL+ Function Wizard:

In message boxes and dialogs:

CopyC++

CXllApp::XlMessageBox(XllGetTranslatedString("#0x0005"),
    XlMessageBoxTypeExclamation);

(Notice that this string uses a hexadecimal string ID, prefixed with "0x", instead of a decimal ID. Either form can be used at any time.)

Testing the add-in

1. Before opening the add-in, use the Control Panel's Regional settings applet to set the current language to English or French.

2. Open the add-in, and note that all the following are localized:

   • Menu texts
   • Toolbar bitmaps and texts
   • Error messages (when an input fails validation)
   • Excel Formula Wizard
   • Message box (which appears when you click a menu or toolbutton)

3. Close Excel.

4. Return to the Regional settings applet, and change to French or English.

5. Open Excel again, and open the add-in. Note that all the features listed above are now in a different language.

Classes and functions used

::XllGetTranslatedString

Sample project

Each sample project is located in a sub-directory of the Samples directory of the XLL+ installation. To use the sample project, open the solution file InterSingle.sln or the project file InterSingle.vcproj.

You can enable debugging under Excel by using the Setup Debugging command in the XLL+ ToolWindow.

When delivered, the help files are excluded from the build. You can enable the help build by selecting the files InterSingle.help.xml and InterSingle.chm in the Solution Explorer, and using the right-click menu to view Properties. Select the page "Configuration Properties/General" and set the "Excluded from build" property to "No". See Generating help in the User Guide for more information.

See Also

List of Sample Projects | Conversion of an existing project | Localized (Multiple DLLs) sample | Dynamic localized (Single DLLs) sample