XLL+ Class Library (6.3)

Deployment

An optional additional step is to isolate the resources for each language into a separate resource-only DLL. Under this architecture, the main XLL contains the resources for the primary language of the add-in, and each other language is held in a separate DLL.

Advantages

Disadvantages

It should be clear that there is no clear-cut correct decision here. Different working environments will require different solutions, and the frequency of changes to the add-in will also influence the decision.

DLL names

You should select an appropriate naming convention for your resource-only DLLs. You will need to be able to list them using a directory search, and to be able to impute the language ID from the file name.

In our sample InterMulti.xll, we used "InterMultiRes_NNNN.dll", where NNNN is the decimal representation of the language ID, e.g. "InterMultiRes_1036.dll" for French (France). We also assumed that all the resource-only DLLs would be in the same directory as the XLL itself.

Creating a resource only DLL

To create a resource only DLL, follow these steps:

  1. Create an empty DLL project.
    • In Visual Studio 6, create a "Win32 Dynamic-Link Library" with "An empty DLL project" selected.
    • In VS .NET or VS 2005, use "Win32 Project" in the "Visual C++ Projects" group, and select Application type "DLL" under "Application Settings". Put a check against "Empty project".
  2. Add the linker option /NOENTRY to the linker settings for each build.
    • In VS 6, add "/NOENTRY" to the "Project Options" edit field in the Project Settings/Linker/Customize tab of the "Project Settings" dialog.
    • In VS.NET or VS 2005, add "/NOENTRY" to the "Additional Options" edit field in the Configuration Properties/Linker/Command line tab of the project properties dialog.
  3. Create a resource file.
    • In VS 6, create a new "Resource Script" and enter a file name with the extension ".rc".
    • In VS .NET or VS 2005, create a new "Resource File (.rc)" and enter a file name with the extension ".rc".
  4. Copy all the native-language resources from the core XLL to your new resource file.
  5. Change the language of each resource to that of the resource-only DLL, and change the text and bitmaps as required.
  6. If a resource file containing error strings is available, change the inclusion #include <xlpres.rc> to the appropriate language, e.g. #include <xlpresfrfr.rc>. For a description of these files, see here.

For more information see the topics "resource-only DLLs" in MSDN help.

Creating resource only DLLs for further languages

To support further languages, follow these steps for each language.

  1. Copy the entire project to a new (appropriately named) directory
  2. Change the name of the output DLL in the linker settings.
  3. Translate all strings and bitmaps to the new language.

Support code

You will need to write support code for the purposes listed below. See the Localized (Multiple DLLs) sample for and example of the required support code.

  1. Listing the available languages. This usually involves searching a directory for DLL files with appropriate names, and then imputing the language from the name.
  2. Determining the user's current language. You should retrieve the user's current regional settings with XllGetStringLanguageID, and then try to match one of the available languages. If no complete match is available, then you should try to match the main language only (ignoring sub-language).
  3. Loading the DLL. Once you have determined the full file path of the DLL, use ::LoadLibrary() to get its instance handle, and pass it to XllSetStringResourceHandle.
  4. Reload all resources. If you change the language at run-time, after the XLL has been loaded, you should (i) unregister all localized resources, (ii) set the resource handle using XllSetStringResourceHandle and (iii) re-register localized resources.

Deployment

There are any number of ways to deploy the resource-only DLLs. Examples include:

  1. Named sub-directories. All resource-only DLLs have the same name. Each is held in a sub-directory which reflects the language ID. e.g. "1033\MyDll.dll", "1036\MyDll.dll". This technique is used by MSDN.
  2. Named files using numeric IDs, e.g. "MyDllRes_1033.dll", "MyDllRes_1036.dll". This technique is used by the Localized (Multiple DLLs) sample.
  3. Named files using language acronyms, e.g. "MyDllFRA.dll", "MyDllENU.dll". This method is used by MFC.

Whatever technique you have chosen for determining the name and path of your resource-only DLLs, you must ensure that they are delivered to the appropriate directory when the XLL itself is installed.

Example

You can find an example of this technique in the Localized (Multiple DLLs) sample.

Next: Conversion of an existing project >>