Demonstrates how to support multiple languages using one DLL per language

Overview

This add-in demonstrates how to support multiple languages using a single XLL, and multiple resource-only DLLs. 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 (Multiple DLLs) sample.

The program logic is almost identical to that in the Localized (Single DLL) sample, and the code of the two projects is compared below.

See Deployment for a discussion of using resource-only DLLs to support multiple languages. 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.

Impact of localization

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

Resource files

The resource file InterMulti.rc contains resources in one language only - English (US).

The resource-only DLL InterMultiRes_1036.DLL contains a resource file InterMultiRes_1036.rc with resources in one language only - French (France).

Resource-only DLL

The project InterMultiRes_1036 can be found in the sub-directory Samples\InterMulti\InterMultiRes_1036. This project builds a French language resource-only DLL for the InterMulti sample.

Note that xlpresfrfr.rc, the French language version of the XLL+ error strings, is included in the resource file, instead of the US English version, 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.

Comparison to a single DLL solution

This add-in is almost identical to that of the Single DLL sample. There are four key differences:

CLanguageHelper instance

There is an instance of CLanguageHelper declared within the application class, CInterMultiApp. This object manages the language DLLS, and makes sure that any loaded instances are properly disposed.

Loading the language DLL

The code added to InitInstance() (discussed above) uses the CLanguageHelper class to find all the available language DLLs, and to load the appropriate one.

Main resource file

There is only one language in the resource file of the main application, corresponding to the LANGID passed to CLanguageHelper::Initialize().

Resource-only DLL

A resource-only DLL is required for each additional language.

Classes and functions used

::XllSetStringResourceHandle | ::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 InterMulti.sln or the project file InterMulti.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 InterMulti.help.xml and InterMulti.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 | Localized (Single DLL) sample