Win32 MUI Run-Time Diagnostics

Confirm that .mui files and code binary are matched. See To confirm match of .mui files and code binary.

Confirm that the .mui file in the language folder of the language you wish to display is placed properly and is matched with the code binary.

See To confirm proper placement of .mui files and To confirm match of .mui files and code binary.

MUI resource splitting is a new Windows Vista feature. Earlier versions of Windows do not know how 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:

    
• LoadMUILibrary
    
• FreeMUILibrary

After installing, be sure and confirm that .mui files are placed properly.

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 have knowledge in Windows Vista of .mui splitting 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.

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.

Based on the current servicing model chosen for Windows Vista, all resource changes were disallowed after Windows Vista RTM by procedure. Now only resource additions are allowed. Depending on the type of resource being used, what might appear to be an addition (e.g., a new resource) is actually a resource change.

This issue is most prevalent with RT_STRING types because of the internal format of how individual strings are stored together in groups (or blocks of 16) as a single resource. Additionally, any major changes of version or filename can break resource loading.

During the build step, the PE file’s embedded major version and the OriginalFilename are used by the RC Compiler (and muirct.exe in post-build) to generate a checksum that validates that the main binaries and .mui binaries belong to each other (validation done at runtime). Resource-loading APIs allow resources to be loaded out of satellite .mui files only after this validation step is performed. Click here for more information about OriginalFilename or major version.

The MSDN Version Information reference page describes other functions that help read and manipulate the data contained within the version resource.

Potential workarounds

• Add new localized resources to your application only when at least one language in the merged fallback list and the MUI_MERGE_SYSTEM_FALLBACK and MUI_USER_FALLBACK flag  is guaranteed to have been serviced (e.g., replaced with the new one). Click here for more information on the merged fallback list.
• Adjust your chosen servicing model. Always ship every language supported by your component (Windows Vista has ~100 languages) and install every language the user has on their system.
• Always service all the main binaries and all .mui files.

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 is 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

• Refrain from resource loading APIs and symbolic links until the release of Windows Vista SP1 or Windows Server 2008.
• Read the Symbolic links documentation to determine conditions where sym links will work with resource loading in Windows Vista RTM.

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 will be fixed in a future version of Windows.

To avoid this issue, format custom resource types and names as uppercase when using UpdateResource.

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. Click here for more information.

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.

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:

• Copyright information
• Servicing information

To enable localization of version information

• Read Example for Using the RC Compiler. This topic touches on how to split resources into both main binaries and .mui files.
• Use the /f flag in MUIRCT. Click here for more information.

Although not strictly related to MUI, the LCID to Language Name mapping is widely used in MUI technology.

To map language names appropriately

• Use the LCIDToLocaleName conversion API.
• Review information about language identifier.

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

• Use muirct.exe and point it at the .mui file of interest. See To view MUI resource configuration settings for more information.
• Confirm that the Language field has the appropriate language name.
• Use the resource editor in Visual Studio (or comparable third-party application) to compare the contents of the resource section.

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

1. Copy the .mui file to its own folder.
   Example   c:\folder\mui_file\<PE filename>.mui
2. Copy the PE file to its own folder.
   Example   c:\ folder\pe_file\<PE filename>
3. Change the .mui file extension from .dll.mui to .mui.dll.
4. Open both files in the Visual Studio (or similar) resource editor.
5. Review the data in both files.

Resource Loader functionality currently has a limitation that .mui file paths cannot exceed the MAX_PATH variable (260 characters). This is scheduled to be fixed in a future version of Windows. For now, 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.

Two situations present the most likely scenarios.

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 a hypothetical Custom Locale resource loading scenario, it is possible that this issue can be encountered where the code binary file path length is MAX_PATH - LOCALE_NAME_MAX_LENGTH – 5 + 1 (or 171 characters).

To avoid this situation, place all code binaries in configurations where the filename path length does not exceed 240 characters for Windows supported languages and 170 characters if your application is going to support custom locales.

If you are properly adjusting your resources (see previous question), there are three primary possibilities:

• You have a .local mui and/or PE file is in the directory where the application resides. This is a common Windows debugging feature that allows placement and first-chance loading of files named with the .local extension. If this situation applies to you, you will find a .local named .mui file in the directory where the application resides.
• Your binary is being managed by Side By Side (unlikely). Click here for more information.
• Various common Windows components are being added to the CMF (a system-wide MUI caching technology). As such, it is possible that the .mui file where resources are being loaded from is coming from the CMF rather than the actual .mui file that resides on disk (exceedingly unlikely). This is an OS feature and should be transparent to non-Windows components.

To determine if your resource is loading out of the CMF

• Determine the file path associated with the loaded resource. Do this by using the handle retrieved from LoadResource and passing it to GetMappedFileName.
• If the file name contains %windir\rescache\*.cmf., your resource came from the CMF.
• If GetMappedFileName fails and LoadResource is successful, it is also possible that the resource came from the CMF.
• In either of these cases, please discuss the issue with your Microsoft contact.

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 are 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).

This is caused by a current bug in Windows Vista that will be fixed in a future release of Windows. Currently, there is no known workaround for this issue other than not using common controls.

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

1. Confirm that your version resource is being split and localized.
2. Confirm that your split version resource has a localized field that will contain the language the .mui file was localized into.
3. Use the GetFileVersionInfo API to obtain the file version.
4. Use the VerQueryValue API to obtain the appropriate language-specific information about the binary being located.

To determine which language resources are loaded by Resource Loader (alternate procedure)

1. Add a dummy custom resource to the appropriate component or find a resource in the component that you are sure is in all .mui files.
2. Call FindResource or FindResourceEx on the component, seeking the dummy resource.
3. Use the GetModuleFileName function passing it the returned handle from FindResource/Ex to determine the file path of the .mui file.
4. Parse the last folder name out of the file path. The last folder name represents the language found by the Resource Loader.

MUI support for custom locale can be erratic. This issue will be addressed in a future Windows release. For now, refrain from using custom locales and MUI Win32 resource loading.

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.

Click here for more information on console filtering (see the Remarks section).

Similar functionality is available in SetThreadUILanguage API for Windows XP.

Change the machine language. See To adjust machine-preferred UI language (UPL).

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.

This situation is addressed in RegLoadMUIString (new to Windows Vista API). Use this API to properly load UI strings from the registry.

If you use the muirct.exe in your build process to do MUI splitting, click here for information on the UltimateFallbackLanguage attribute.

If you use the RC compiler in your build process to do MUI splitting, click here for information on the  UltimateFallbackLanguage attribute.