Demonstrates how to support multiple languages using one DLL per language, switching between languages dynamically

Overview

This add-in demonstrates how to support multiple languages using a single XLL, and multiple resource-only DLLs. The add-in will start with the language that matches the user's current regional settings in the Control Panel. The user can switch between languages using a menu.

The program logic is almost identical to that in the Dynamic localized (Single DLL) sample, and the code of the two projects may usefully be compared.

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.

For a discussion of the steps involved in localizing an XLL using multiple DLLs, see the Localized (Multiple DLLs) sample. The discussion in this sample focuses on the changes required in order to allow the language to be switched dynamically.

Setting the language at run-time

In order to change the language at run-time, you need to consider all the areas of behavior that are localized:

1. Menu text
2. Toolbar text
3. Toolbar bitmaps
4. Functions' category help text

Normally much of this code is handled in the event handlers, OnXllOpenEx() and OnXllClose(), so that it is called when the add-in is opened or closed. In the add-in, the relevant code is removed from the event handlers and placed in RegisterLocalized() and UnregisterLocalized().

void CDynInterMultiApp::RegisterLocalized()
{
    // Set up menu
    m_menu.SetTexts("#2");
    m_menu.AddItem("#3", "BuyWater");
    m_menu.AddItem("-", "");    // Separator 
    for (size_t i = 0; i < m_languageNames.size(); i++)
        m_menu.AddItem(m_languageNames[i], "SelectLanguage");
    m_menu.Create();

    // Save position of 1st language menu item
    m_nFirstLanguageMenu = 3;   // (Menu item positions are zero based) 
 
    // Create toolbar
    CXlToolbar::AddToolbar(m_pszToolbarName);
    CXlToolbar::AddTool(m_pszToolbarName, 1, "BuyWater", "#5");
    CXlToolbar::SetToolBitmap(m_pszToolbarName, 1, IDB_BITMAP1);
    CXlToolbar::ShowToolbar(m_pszToolbarName, true, CXlToolbar::DockRight);

    // Save actual toolbar name, for deregistration
    m_strToolbarNameUsed = ::XllGetTranslatedString(m_pszToolbarName);

    // Reregister functions using new texts
    RegisterFunctions();
}

void CDynInterMultiApp::UnregisterLocalized()
{
    // Delete menu
    m_menu.Destroy();

    // Delete toolbar
    CXlToolbar::DeleteToolbar(m_strToolbarNameUsed);

    // Unregister functions
    UnregisterFunctions();
}

The program logic of switching languages is done handled by SetLanguageID(), using XllSetStringResourceHandle():

void CDynInterMultiApp::SetLanguageID(LANGID langid, BOOL bFirstTime)
{
    if (bFirstTime)
        // Unregister functions: the framework has already registered 
        // them and they may be in the wrong language
        UnregisterFunctions();
    else 
        // Unregister everything
        UnregisterLocalized();

    HINSTANCE hinstRes = m_languageHelper.GetLanguageResources(langid);
    if (hinstRes == NULL)
        hinstRes = XllGetResourceHandle();
    XllSetStringResourceHandle(hinstRes);

    RegisterLocalized();
}

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, French or another language.
2. Open the add-in, and note that the menu is either in English (Water) or in French (Eau) depending on your current regional settings.
3. Use the list of languages in the menu to switch between languages.
4. Note that the menu text changes language, as does the popup help for the tool button.
5. The tool button's bitmap (which is language-sensitive) also changes.
6. In the Excel Formula Wizard, help text appears in the selected 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 DynInterMulti.sln or the project file DynInterMulti.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 DynInterMulti.help.xml and DynInterMulti.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 (Multiple DLLs) sample | Dynamic localized (Single DLL) sample