Types of string

Types of string

There are several types of string which you might consider localizing. The list below contains links to a detailed discussion of each.

String	Summary
Library name	This is the name of the add-in library, as it will appear in the Tools/Add-ins... dialog.
Exported function name	The name of an add-in function, as it will appear in Excel.
Argument names	The names of each of an add-in function's arguments, as they appear in the Excel Formula Wizard.
Function category	The category under which a function appears in the Excel Formula Wizard.
Help text	The help text that appears for an add-in function and for each of its arguments in the Excel Formula Wizard.
Commands	Captions and help text for menus and toolbars.
Formulae	The text of a formula, which can be set using CXlOper::SetFormula.
Error strings	Currently, the error strings returned by the XLL+ run-time libraries are hard-coded in English. In a future release, we will provide the option for error strings to be localized.

Library name

The library name has to be available very early in the process of initializing an add-in library, during the CXllApp::InitInstance event handler. At this point the Excel language version is not available, so any localization can only refer to the user's regional settings.

In the example below, the name of the application is given as "#6". Thus it will be replaced by the resource string whose numeric ID is 6. The string will be retrieved in the appropriate language, which at this point is the user's regional language setting as set in Control Panel).

Note that "#@6" may not be used, since the Excel language version is not available at this point. If you do try to use the Excel version language, the add-in will fail to load.

/* static */ LPCSTR CInternationalApp::m_pszDefName = "#6"; 

BOOL CInternationalApp::InitInstance() 
{
    // Call the base class
    if ( !CXllApp::InitInstance() )
        return FALSE;

    // Set the name of the library to the default value
    m_stName = m_pszDefName;

    // Add the statically defined function specifications
    AddStaticFns();

    // TODO: Add your specialized code here

    return TRUE;
}

Exported function name

The name of an add-in function, as it will appear in Excel. This should not be localized; otherwise workbooks saved in one language setting will not work when opened in a different one. There is no way for Excel to know that a formula saved by a German user as, for example, =WASSER(...) should be interpreted as =WATER(...) when the workbook is opened by an English user.

By contrast, you will have noticed that Excel's built-in functions are allowed to appear differently in different language versions of Excel. This is because, when a formula is stored, built-in functions are replaced by their numeric function identifiers. For built-in functions, these numeric function identifiers are fixed, and functions can therefore be serialized as numbers. For add-in functions, numeric function identifiers are not fixed, and may change each time an add-in library is loaded; therefore user-defined functions are saved as text.

Argument names

The names of an add-in function's arguments, as they will appear in the Excel Formula Wizard. Unlike the function name, these can be localized, since they are not stored as part of a worksheet, and are of interest only at run-time, to the Excel Formula Wizard.

However, the XLL+ Formula Wizard uses argument names for C++ variables in the generated C++ function implementation,and clearly resource IDs cannot be used there.

If you want to localize an argument name, you can enter a resource ID in the ResID column of the XLL+ Function Wizard, and add a localized name with the appropriate resource ID to each language's string table in the resource file.

Note: If you can't see the ResID column in the argument grid, use the View Argument Resource IDs command to make it visible.

Category

In the XLL+ Function Wizard, you can select a category for your add-in function. The standard categories shown in the XLL+ Function Wizard are built into Excel. If you select one of the standard categories for your function, then it will automatically appear in the local language of the Excel version being run. See Stability : Category for more information.

Help text

The Description field and the Description column of the XLL+ Function Wizard hold descriptions of the add-in function and each of its arguments, as they will appear in the Excel Formula Wizard. They can be replaced by resource ID strings (e.g. "#100", or by strings containing resource IDs (e.g. "#101 2", for "Argument 2").

Commands

Captions and help text for menus and toolbars are set by passing arguments to the methods of CXlMenu and CXlToolbar. The following functions accept resource string IDs as arguments:

To localize a menu, use the following techniques:

BOOL CMyAddinApp::OnXllOpenEx()
{
    ...   
    // "#101" replaces "&My menu". The string resource 101
    // should contain the localized menu caption.
    m_menu.SetTexts("#101");
                             
    // "#102" replaces "&My menu task". The string resource 102
    // should contain the localized menu item text.
    m_menu.AddItem("#102", "MyAddinFunction");
    
    m_menu.Create();
    ...
}

To localize a toolbar, use code like the following:

// "#4" replaces the original toolbar name. The string resource 4
// should contain the localized toolbar name.
/* static */ LPCSTR CMyAddinApp::m_pszToolbarName = _T("#4");

BOOL CMyAddinApp::OnXllOpenEx()
{
    ...   
    CXlToolbar::AddToolbar(m_pszToolbarName);
    // "#5" replaces the original tool help text. The string resource 5
    // should contain the localized tool help text.
    CXlToolbar::AddTool(m_pszToolbarName, 1, "Intl3_SelectLanguage", "#5"); 
    ...
}

void CMyAddinApp::OnXllClose()
{
    ...
    // Delete toolbar
	CXlToolbar::DeleteToolbar(m_pszToolbarName);
    ...
}

Formulae

A formula's argument separators vary according to the user's regional settings. For example, =MyFunc(A,B,C) (in English) will appear as =MyFunc(A;B;C) in German, with semicolons replacing commas. In addition, the names of built-in functions vary in different language versions of Excel. If you are setting formulae from your code, or if you are reading formulae and parsing them, you should be aware of these issues and code defensively.

See Setting formulae for a full discussion of the internationalization of formulae.

Error strings

Currently, the error strings returned by the XLL+ run-time libraries are hard-coded in English. In a future release, we will provide the option for error strings to be localized.

Visit the XLL+ web-site at http://www.planatechsolutions.com/xllplus for up-to-date information on new releases.

Next: Deployment >>