Demonstrates how to support multiple languages in a single XLL, switching between languages dynamically

Overview

This add-in demonstrates how to support multiple languages in a single XLL, using a resource file. 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.

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 a single DLL, see the Localized (Single DLL) sample. The discussion in this sample focuses on the changes required in order to allow the language to be switched dynamically.

Getting a list of supported languages

InitLanguageList() is called once, during OnXllOpenEx(), to initialize a list of languages supported by the XLL. The utility function ResListLanguages is used to get a list of all the languages supported by the resource file.

void CDynInterSingleApp::InitLanguageList()
{
    ResListLanguages(XllGetStringResourceHandle(), m_languageIDs,
    LOCALE_SNATIVELANGNAME, m_languageNames);
}

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 this add-in, the relevant code is removed from the event handlers and placed in RegisterLocalized() and UnregisterLocalized().

RegisterLocalized() handles all the creation tasks. Note that the first time it is called, it is not necessary to register the add-in functions themselves, since the XLL+ framework has already taken care of this. On later calls, the add-in functions have been unregistered (by UnregisterLocalized()) and need to be explicitly reregistered.

void CDynInterSingleApp::RegisterLocalized(BOOL bRegFunctions)
{
    // 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 
    if (bRegFunctions)
        RegisterFunctions();
}

void CDynInterSingleApp::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 XllSetStringLanguageID():

void CDynInterSingleApp::SetLanguageID(LANGID langid)
{
    UnregisterLocalized();
    XllSetStringLanguageID(langid);
    RegisterLocalized(TRUE);
}

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

::ResListLanguages | ::XllSetStringLanguageID | ::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 DynInterSingle.sln or the project file DynInterSingle.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 DynInterSingle.help.xml and DynInterSingle.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 | Dynamic localized (Multiple DLLs) sample