Win32 MUI Run-Time Diagnostics
Multilingual User Interface (MUI): A technology that enables the physical separation of application source code and language-specific resources. The application exists as a language-neutral core binary, plus resources that can be further broken down into one file per supported language. This permits maximum flexibility in building, deploying, and servicing applications in multiple languages.
On This Page
Frequently Asked Questions
My Windows Vista-style application fails to start up properly or no UI appears. This seems to be MUI-related. Where do I start looking for the problem?
My application only displays English (en-US). How can I get my application to display the language that I expect? Do I have to change the User UI Language?
How do I get my Windows Vista MUI application to work on down-level platforms?
MUI resource splitting is a new Windows Vista feature. Earlier versions of Windows were not able to connect the code binary with the .mui file for resource location. As a result, the Windows Vista SDK ships with several APIs that make it possible for you to use Windows Vista-style binaries with pre-Windows Vista OS versions:
After installing, be sure and confirm that .mui files are placed properly.
Why can’t I get the MUI down-level APIs to find all my resources when run on a down-level platform? Everything works fine when run on Windows Vista.
Some of your resources may be considered non-localizable. A localizable Windows Vista resource will be found in the satellite .mui binary. Resources in the Windows Vista code binary are considered non-localizable. In the Windows Vista deployment scenario, the Windows Vista Resource Loader understands this difference and loads from either binary as appropriate. In the down-level scenario, using LoadMUILibrary will lock resource loading into one binary or the other (but not both).
The only workaround for this scenario is to load the resources you know to be resident in the main binary (as you would do for Windows XP) and load the localizable resources using the LoadMUILibrary API.
Alternately, some APIs in Windows Vista (such as GetFileVersionInfo) act upon pieces of a dual split resource. Specific resource types may contain both localizable and non-localizable information. For example, the version resource type can sometimes fit this pattern where much of the resource is obtained from the non-localizable code binary, but localizable parts (such as a string) are obtained from the .mui satellite file.
When using LoadMUILibrary on a down-level OS, a single portable executable (PE) file will be searched. APIs that support mui splitting in Windows Vista will work differently. The only true workaround for this scenario is to formulate your own code that will appropriately load the pieces of the resources you need from each binary.
The initial version of my MUI-enabled application works great when loading a specific resource in a specific language, but it breaks after it has been serviced. What went wrong?
In the event that resource changes were made to your application between its initial release and a subsequent update, it is possible that you have improperly serviced your application. This scenario occurs most often in applications that do not service all supported languages at the same time.
Why doesn’t my MUI application work when started from a sym link, but works fine from a shortcut or the actual executable file?
Symbolic links added to the Windows Vista kernel are not fully supported by the Resource Loader in Windows Vista RTM. Click here for mklink.exe.
Therefore, it is possible that some types of symbolic links will not produce proper resource loads. This issue is primarily related to scenarios where .mui files are not located directly at the location of the link.
This issue will be fixed in a future release of Windows.
Symbolic links work-around
Why can’t I load a custom resource that I added using UpdateResource APIs?
Traditionally and by convention, resource names and type strings have been capitalized in resource PE binaries.
In Windows Vista, the UpdateResource API has a bug where it will allow mixed case to be assigned to a type (custom type) or name. When attempting to locate this resource, the Resource Loader converts the name of the string to uppercase and then cannot find the resource. This issue has been fixed in Windows 7, where UpdateResource converts all strings to uppercase.
To avoid this issue, format custom resource types and names as uppercase when using UpdateResource.
Resource loading and the Enumeration APIs are unable to discover a resource which the Update APIs successfully inserted into my binary. How do I avoid this behavior?
It is likely that the newly added resource was handed to the UpdateResource API starting with a '#' as the first character of the string, for example "#42". UpdateResource treats this as a string where the FindResource/Ex and Enumeration APIs treat this as a numerical resource type or name. Avoid using the Update APIs with '#' characters.
Why do some resources load correctly on X86 and AMD64 builds, but fail to load on IA64?
One issue encountered during application compatibility testing for Windows Vista is that resource sections of third-party applications can become misaligned prior to resource loading. Although X86 and AMD64 platforms are lenient when it comes to properly aligning memory (performance is apparently the only penalty), IA64 is more strict about misaligned memory and will not load the resources.
To mitigate this problem, use the UpdateResource-related APIs (for non-split binaries only) or Microsoft-provided compilers (RC Compiler) to assure your resources are properly aligned. For more information, see Resource Utilities.
Pay special attention to the internal structure of any custom resource. They can become misaligned, depending on how they are used.
Click here for more information on alignment.
Why does my application only receive version text in one language?
The version resource (type #16) is unique. Normally, it is required to be present in all Microsoft compiler-built applications. It is added by default to the code binary in the default language (normally English). Because the version resource contains some text that may be displayed to the user, the GetVersionInfo API was modified in Windows Vista to be able to get pieces of the version from both a localized type #16 present in the .mui file and the remaining data from the neutral type #16 in the code binary.
Some component owners may wish to localize portions of the version resource, such as:
To enable localization of version information
How do I determine the proper language name for an LCID?
How do I determine if my LCID or Language Name is supported by Windows?
Although not strictly related to MUI, validating LCIDs is important when using MUI technology.
To validate language names or LCIDs appropriately
How do I determine what language my .mui file is localized for?
Sometimes it is important to determine that you have the correct .mui file in the properly named folder. At runtime, the Resource Loader confirms that the .mui file is properly placed. If the file validation fails, the Resource Loader ignores the misplaced file.
To confirm proper localization
What resources are in my .mui file and what ones are in the code binary?
Sometimes it is useful to confirm how resources are split between .mui and code binary PE files.
To confirm how resources are split between .mui and code binary PE files
Why can’t I get resources to load from a binary which has a long file path?
Resource Loader functionality in Vista has a limitation that .mui file paths cannot exceed the MAX_PATH variable (260 characters). This limit was changed in Windows 7 to be MAX_PATH + LOCALE_NAME_MAX_LENGTH + 5 (350 characters including the null terminator). For Vista, it is possible that a component can get into a situation where the main / code binary is able to load properly (with LoadLibrary/Ex), yet fail to load resources out of a satellite binary. This can occur because the code binary is located within a path/file name configuration that is too long. For Windows 7 when applications use LoadLibrary/Ex this behavior is not possible.
Although this string size varies based on the language name length being supported, a code binary file path length of 240 or more characters may encounter this situation in Windows Vista.
No matter what I do, my application only loads old resources. It will not reflect my newly adjusted resources. What is going wrong?
If you are properly adjusting your resources (see previous question), there are three primary possibilities:
To determine if your resource is loading out of the CMF
My application uses impersonation and the UI shows up in a different language than the current users’ environment. How can I fix the mixed UI?
When using impersonation, mixed UI language can occur for several reasons.
In most cases, the primary reason relates to the fallback language list not being set properly. The most common fix is to have the impersonated thread use the SetThreadUILanguage or SetThreadPreferredUILanguages APIs (or) prior to any resource loading.
A second reason may be that the system on which the impersonated thread is running lacks the appropriate language resources - .mui files are missing or were never installed. To fix this issue, install the appropriate .mui files.
As a note, many services and server-type applications hit this scenario and have only a subset of all languages they will see when a client connects with its thread language settings. The norm is that a block of resource languages is known to be installed. When the thread language(s) are set, one of the languages known to be installed is always set. This way, the application’s preferences are kept (rather than OS preferences).
I am using a side-by-side Win32 assembly, such as Microsoft Common Controls version 6. If it is MUI compliant (resource splitting via muirct or rc compiler) I am unable to get the correct resources to load if I change the thread language before loading resources. What should I do?
If the assemblies are properly installed and being used correctly, the following may be happening:
How do I determine which language resources were loaded by the Resource Loader?
In some cases, applications must identify the language that the Resource Loader API found during resource discovery.
To verify language resources loaded by the Resource Loader
To determine which language resources are loaded by Resource Loader (alternate procedure)
I have a valid custom locale that is working and the language is being provisioned on the thread language list. However, Win32 resources are never loaded from the appropriate custom locale .mui file. What is wrong?
In general, MUI technology does not currently support custom locales in Windows Vista and Windows 7. Custom locale support is being evaluated for a future Windows release. For now, refrain from using custom locales in MUI language management APIs and Win32 resource loading.
How do I get my command line application to not show ‘??’ characters in some OS language environments?
The most common cause of ?? characters in the command shell (cmd.exe) is due to the application attempting to display characters that cmd.exe is not configured to display or is unable to display.
To configure your application to display correctly in the current console at run-time, use the SetThreadPreferredUILanguages API with the MUI_CONSOLE_FILTER specified.
Click here for more information on console filtering (see the Remarks section).
Similar functionality is available in SetThreadUILanguage API for Windows XP.
How can I get my driver to load resources in a different language than the OS installed language?
Change the machine language. See To adjust machine-preferred UI language (UPL).
What is the difference between run-time MUI technology for Windows Server 2008, Windows Vista, XP, Windows Server 2003, and Windows 2000?
Occasionally the MUI team is asked how the various versions of MUI support differ across Microsoft OS offerings. The table below highlights the primary differences and features provided in the past three Windows MUI offerings.
I pull strings out of the registry and display them in my application. How should I properly use the registry while retaining access to localized data?
Application shortcuts or application/service names and descriptions are not changing even though the strings have been updated in the Win32 PE file
This situation is most commonly encountered due to a string caching mechanism within the Windows Shell which has not been informed of resource changes. See To refresh the Shell string cache - Windows Vista and Windows Server 2008 and To refresh the Shell string cache - Windows 7.
My application seems to be using an UltimateFallbackLanguage attribute and I don’t want it to do so. How does one adjust the ultimate fallback language in the language-neutral binary?
Debugging my MUI enabled application is new to me, ; are there any helpful MUI related debugging utilities?
You can use Muirct -d as the first option for debugging. You can also use debugger extensions from the SDK for Vista and Windows 7. Install debugging tools for Windows 32-bit version, and then search for !mui in windbg's help or click here.
Calling the SetThreadPreferredUILanguages API requires every thread in my process to handle a process-wide preference. Can I call an API to change language settings process-wide?
Windows 7 added SetProcessPreferredUILanguages, use this API instead. See To adjust process languages.
Many locales in Windows 7 are part of or associated with multiple parent chains. How does MUI treat locales that fall under this category?
All MUI APIs were adjusted in Windows 7 to properly handle multiple parent chains.
If I move my application to the Vista style MUI model, can I continue to use special locales (0x007F, 0x0400 or 0x0800) to obtain resources from MUI binaries?
Windows support for various special locales (LOCALE_USER_DEFAULT, LOCALE_SYSTEM_DEFAULT) generally extends to MUI resource location, enumeration and updating. It is not supported in language management APIs. This support is provided primarily for backward compatibility. The practice is discouraged for new MUI development as use of explicit locales and LOCALE_NEUTRAL (0) are preferred. Marking resources using these default LANGIDs is also discouraged and not supported by many MUI API.
In my application, I am able to enumerate a resource that cannot be found by FindResource/Ex. How do I avoid this behavior?
Under various conditions it is possible to construct Win32 PE files in which the Enumeration APIs are able to discover a resource that resource locator APIs are unable to find (or vice-versa). To avoid these issues the following guidance is offered:
Remedial How To Procedures
To confirm proper placement of .mui files
To confirm match of .mui files and code binary
To install a Windows Vista language pack
To install a Windows 7 language pack
To make language setting changes
To make language setting changes, adjust the Windows language settings – Thread, User/Machine, and Installed Languages. These settings define the list of languages that the Resource Loader will probe for satellite .mui localized resource data. Click here for additional information on language settings.
To adjust thread languages
Adjust thread languages using API calls from the running application. Click here for more information on thread language APIs.
To adjust process languages
Adjust process preferred languages using API calls from the running application. Click here for more information on process language APIs.
To adjust user-preferred UI language (UPL)
~ OR ~
To adjust machine-preferred UI language (MPL)
~ OR ~
To adjust language installed on operating system
To avoid an intended licensing-induced blue screen, do not modify the OS language settings in the registry. Instead, reinstall the operating system with a different language SKU.
To view MUI resource configuration settings in PE files
To view basic resource data in PE files
To refresh the Shell string cache - Windows Vista and Windows 2008
To refresh the Shell string cache - Windows 7
Win32 MUI Run-Time Diagnostics Background and Concepts
MUI localization technology is built on three primary concepts:
MUI Language Settings
The language setting design used for Windows Vista MUI consists of three primary tiers of languages:
Introduction to Satellite MUI Files
Splitting resources from the code binary into the satellite .mui file is a key pillar of Windows Vista MUI localization technology.
MUI Resource Loading
MUI files and language settings enable dynamic, per-language resource loading.
When locating a particular resource, the Resource Loader uses the merged fallback list to guide its order of satellite file probing. The merged fallback list is a combination of the three language groupings – MUI_MERGE_SYSTEM_FALLBACK and MUI_USER_FALLBACK to the GetThreadPreferedUILanguages API. Click here for more information.
Once a particular language .mui file is discovered and validated, the requested resource is returned to the caller. In the event that a valid .mui file is not found, follow-on languages in the merged fallback list are probed.
Prior to resource loading failure, the Resource Loader attempts to look toward an ultimate fallback language and any resource data that might be present within the main code binary.
In This Article