Placing and Loading Win32 MUI Resource Files
A typical MUI application consists of an LN file and language-specific resource files (.mui files). This topic discusses the placing and loading of resources to support your MUI application that uses Win32 MUI resource configuration.
Placing Win32 MUI Resource Files
This section discusses the placing of resource files on the target computer for optimal use by the application loading logic and the resource loader.
Place Resource Files on Windows Vista Only
This section describes the placement of resource files for an MUI application targeted only at Windows Vista.
Place the LN File for Language-neutral Code
A typical LN file for an MUI application is an .exe file or a .dll file, for example, BakerDelta.dll. You should place this file in the root folder where your application is installed, for example, X:\\<somepath>\BakerDelta.dll.
Place .mui Files for Language-specific Resources
Your .mui files must have predictable names formed by appending ".mui" to the full name of the LN file, for example, BakerDelta.dll.mui. These files must be placed in subfolders named after the appropriate language names. The following example shows placement of Win32 MUI resources for the BakerDelta.dll LN file, with .mui files for English (United Kingdom), English (United States), English (Neutral), Spanish (Spain), Spanish (Mexico), and Spanish (Neutral):
- X:\\<somepath>\BakerDelta.dll
- X:\\<somepath>\en-GB\BakerDelta.dll.mui
- X:\\<somepath>\en-US\BakerDelta.dll.mui
- X:\\<somepath>\en\BakerDelta.dll.mui
- X:\\<somepath>\es-ES\BakerDelta.dll.mui
- X:\\<somepath>\es-MX\BakerDelta.dll.mui
- X:\\<somepath>\es\BakerDelta.dll.mui
The .mui files must be placed in their correct locations during installation of the MUI application or a language package. It is important to place each .mui file in the correct folder, as the resource loader cannot function properly otherwise. Using the example above, the resource loader examines X:\<somepath>\en-US\BakerDelta.dll.mui for English (United States) resources. If the loader looks in that file and encounters only Spanish-language resources, it fails.
Create .mui Files for Neutral Languages
When localizing your MUI application, consider creating .mui files for neutral language resources, for example, resources for the English (Neutral) language, represented as "en". Even though a neutral language is not associated with the aspects of a region or locale, you can associate it with a resource set. Typically, a neutral language resource is based on the use in the most prevalent region for the language.
Let's illustrate the creation of .mui files for a neutral language. Suppose that an application localizes German-language resources for Switzerland (de-CH) and Austria (de-AT), while building a full set of resources for Germany (de-DE). You must make decisions for this application considering entire .mui files. If the application duplicates the de-DE resources as neutral language resources, it must provide a fallback language for the resource loader. If the loader does not find a particular .mui file for de-CH or for de-AT, it falls back to the language-neutral "de" resources. These resources are most likely more appropriate than resources for a completely different language, for example, English (United States), which are the only other possible fallbacks.
As another example, an application might not localize at all for Belize. However, support of a language preference of English (Belize) or "en-BZ" allows the application to fall back to English (Neutral) or "en" resources.
Place Resource Files on a Pre-Windows Vista Operating System
An MUI application to run on a pre-Windows Vista operating system can use the Windows Vista convention of placing .mui files in folders based on language names. Alternatively, the application can conform to an older convention that forms paths from language identifiers. For applications that only support a single language on pre-Windows Vista operating systems, you can just place the .mui file in the root directory with the binary file.
For example, consider an LN file called BakerDelta.dll, with .mui files for English (United Kingdom), English (United States), English (Neutral), Spanish (Spain), Spanish (Mexico), and Spanish (Neutral). An installation on a pre-Windows Vista operating system might place these files as follows:
- X:\\<somepath>\BakerDelta.dll
- X:\\<somepath>\BakerDelta.dll.mui (optional .mui file containing resources in the language of the operating system as the ultimate fallback)
- X:\\<somepath>\MUI\0809\BakerDelta.dll.mui
- X:\\<somepath>\MUI\0409\BakerDelta.dll.mui
- X:\\<somepath>\MUI\0209\BakerDelta.dll.mui
- X:\\<somepath>\MUI\040a\BakerDelta.dll.mui
- X:\\<somepath>\MUI\080a\BakerDelta.dll.mui
- X:\\<somepath>\MUI\0209\BakerDelta.dll.mui
In addition to these files, the application can set up an ultimate fallback .mui file, to reside in the same folder as the application itself. For the above example, this file is X:\<somepath>\BakerDelta.dll.mui. See Language Defaults, Preferences, and Fallbacks for a further discussion of the resource loader fallback language.
Loading Win32 MUI Resources
This section discusses the loading of user interface resources on Windows Vista and on pre-Windows Vista operating systems. For an MUI application targeted at Windows Vista, the Windows Vista resource loading functions contain the proper logic to retrieve the correct language resources in the language-specific resource (.mui) files at runtime. However, the Windows Vista resource loading technology does not exist on pre-Windows Vista operating systems. Therefore, you must modify your MUI application code to load the appropriate resources on such an operating system.
The MUILoad library furnished by the Windows Vista SDK includes the LoadMUILibrary and FreeMUILibrary functions. These functions can be used by your MUI applications targeted at either Windows Vista or a pre-Windows Vista operating system to load and unload resources based on operating system user interface settings. The LoadMUILibrary function returns a handle to the appropriate LN file based on operating system user interface language settings, and the FreeMUILibrary function closes the handle. The fallback priority used in LoadMUILibrary is user UI language followed by system default UI language. If the function cannot find an LN file in these languages, it returns the handle of the .mui file located in the same folder as the code .dll. If the .mui file does not exist either, the function returns a handle to the binary file that contains the code.
Note: MUILoad library functions are based on the assumption that the MUI application uses Win32 MUI resource configuration. If your application uses another resource technology, it must implement its own approach to loading resources.
Note: Because a particular user's language preferences might include languages that are not supported by your MUI application, the application should always handle these languages by loading the appropriate fallback resources.
Loading Win32 MUI Resources on Windows Vista Only
This section discusses the loading of Win32 MUI resources on Windows Vista only.
Load Resources Based on User UI Language Setting
For most situations, your application targeted at Windows Vista can let the operating system itself load the correct resources according to the user UI language setting for the current user. The Win32 resource API functions, for example, FindResourceEx and LoadString, have been modified to load resources from the .mui files automatically. Your application can include calls to these functions, treating the resources as if they are contained in the LN file. Thus your application refers to resources through a handle to the loaded LN file. The application does not have to load any .mui files explicitly.
Here is an example of application code that loads an LN file based on user UI language setting:
HMODULE hResModule = LoadLibraryEx(TEXT("Mymodule.dll"), 0, LOAD_LIBRARY_AS_DATAFILE);...
LoadString(hResModule, myID, lpBuffer, cbBufferSize);...
FreeMUILibrary(hResModule);
Load Resources Based on User-selected Language or a Specific Language Identifier
When your MUI application supports more languages than the operating system does, the loading logic of the application should allow the user to select a different language for the application user interface. To react to this setting, the application must set the thread preferred UI languages using SetThreadPreferredUILanguages to guide the resource loader to the correct language resources. After that, finding and loading the .mui files according to the thread preferred UI languages is transparent to the code. Here is an example that loads an LN file based on a specific language identifier compatible with both Windows Vista and a pre-Windows Vista operating system:
LANGID langid;
... insert code here to get the language identifier for the user's application language preference...
or
... insert code here to get the language identifier for the specific operating system user interface language setting...
HMODULE hResModule = LoadLibraryEx(TEXT("Mymodule.dll"), NULL, LOAD_LIBRARY_AS_DATAFILE);...
HRSRC hResInfo = FindResourceEx(hResModule, RT_DIALOG, myID, langid);...
FreeLibrary(hResModule);
Loading Win32 MUI Resources on Windows Vista and Pre-Windows Vista Operating Systems
This section discusses the loading of Win32 MUI resources on both Windows Vista and pre-Windows Vista operating systems.
Load Resources on Multiple Operating Systems Based on User UI Language Setting
The following code example loads an LN file based on a user UI language setting that is compatible with both Windows Vista and a pre-Windows Vista operating system:
#include "MuiLoad.h"
HMODULE hResModule = LoadMUILibrary(TEXT("Mymodule.dll"), MUI_LANGUAGE_NAME, 0);...
LoadString(hResModule, myID, lpBuffer, cbBufferSize);...
FreeMUILibrary(hResModule);
Load Resources on Multiple Operating Systems Based on User-selected Language or a Specific Language Identifier
The following is an example of code that loads an LN file based on a specific language identifier that is compatible with both Windows Vista and a non-Windows Vista operating system:
#include "MuiLoad.h"
LANGID langid;
... insert code here to get the language identifier for the user's application language preference ...
or
... insert code here to get the language identifier for a specific operating system user interface language setting ...
HMODULE hResModule = LoadMUILibrary(TEXT("Mymodule.dll"), MUI_LANGUAGE_ID, langid);
HRSRC hResInfo = FindResourceEx(hResModule, RT_DIALOG, myID, langid);...
FreeMUILibrary(hResModule);
Load a Specific LN File
If the application has the exact path of the LN file to load, it can retrieve a handle to the file by calling LoadLibraryEx. The application can then use the retrieved handle in all subsequent calls to load resources. Here is an example of code that loads resources only from an LN file compatible with both Windows Vista and a pre-Windows Vista operating system:
HMODULE hResModule =
LoadLibraryEx(TEXT("c:\\<myfolder>\\en-us\\MyResourceModule.dll.mui"), NULL, NULL);...
HRSRC hResInfo = LoadString(hResModule, myID, lpBuffer, cbBufferSize);...
FreeLibrary(hResModule);