Representing the Correct Language to the User
This topic describes how to manage the user interface languages that the MUI application supports. Here are options for structuring your application for user interface language management:
- Support different user interface languages from those supported by the target operating system.
- Allow the target operating system to intelligently select the correct language based on its own user interface language.
- Expose an application user interface to allow the user to choose the language for that application.
The resource loader uses the thread preferred UI languages list, defined in Language Defaults, Preferences, and Fallbacks, for the operating system to load your MUI application resources, unless your application includes code to change the list. Relying on the default operating system user interface language is the simplest way to manage languages in your application since you do not have to provide code to handle resource loading.
However, it is likely that your application requires support for languages other than the default user interface language of the operating system. One reason for this is that the default language might present difficulties for the application user. In this case, you can develop your application to support languages installed under conditions that match those for the default operating system user interface language. You can also develop the application so that the user can set the user interface language interactively.
Detect Installed User Interface Languages
In a number of instances, before it can retrieve or set languages, the MUI application must find out what languages are installed on the operating system. To do this, the application calls EnumUILanguages. This function is available for applications that run on Windows Vista and later or on pre-Windows Vista operating systems.
Set User Interface Language
Your MUI application can access user and system settings to determine the best user interface language. To retrieve user preferences for the user interface language from the user preferred UI languages list, your application can call GetUserPreferredUILanguages. The application can find out the user interface languages preferred by the operating system by calling the GetSystemPreferredUILanguages function. This function retrieves the contents of the system preferred UI languages list.
As an alternative to using these functions, your application can present the user with a list of available languages. It should call GetThreadPreferredUILanguages to retrieve the thread preferred UI languages. Then the application can call SetThreadPreferredUILanguages to override the user and system settings and explicitly set languages for its own use or use by a particular thread. The resource loader transparently provides resources according to this special list, falling back to other resources only if the application-specific resources are not available.
Determine Default Language on Windows Vista
Your application must decide on a default language for use during initialization. To detect installed user interface languages, the application should call EnumUILanguages. If it must determine the default user interface language used when a new user account is added on the computer, it can call GetUserDefaultUILanguage. The application can also retrieve the system default UI language (also known as "install language") by calling GetSystemDefaultUILanguage.
Retrieve Fallback Languages for a User Interface Language
Your MUI application can call the GetUILanguageInfo function to get information about the fallback languages for the operating system user interface language. Most applications are not concerned with this call, as they can trust the resource loader to make appropriate selections using values that the user has previously selected in the Control Panel.
If your application does have to determine the fallback language supported on a given computer or chosen by a particular user, the application can call GetSystemPreferredUILanguages or GetUserPreferredUILanguages.
Your application must treat locale-specific and locale-neutral versions of a single language as different languages. For example, if distinct resources are provided for English (United States) and for English (United Kingdom), Windows Vista treats the two language versions as two different languages, both distinct from neutral English (language name "en"). However, English (Neutral) resources are always implicitly available as fallbacks for locale-specific versions of English, and take precedence over any other fallbacks.
Access the Resource Loader Fallback Language
Your application can access the resource loader fallback language list to determine an ultimate fallback language to use independently of the operating system installation. Access to this list is dependent on the resource technology that you are using for the application. If you are using the MUI-specific Win32 resource technology, this language should be indicated in the resource configuration data of the LN file. Note that it is also possible for the LN file to provide ultimate fallback language resources internally. For more information, see Creating Win32 Resources.
Represent a Single Language as a String
Several MUI functions, for example, GetFileMUIPath, use a parameter of type PWSTR to represent a language as a string. This parameter indicates a buffer that supports two mutually-exclusive string formats, MUI_LANGUAGE_NAME and MUI_LANGUAGE_ID. An input parameter, typically called dwFlags, allows the application to choose between these formats.
Your application uses the MUI_LANGUAGE_ID flag to instruct an MUI function to use a language identifier for language identification. Two values for this flag deserve special mention. The value "1400" is the hexadecimal value of the constant LOCALE_CUSTOM_UI_DEFAULT, and the value "1000" is the hexadecimal value of the constant LOCALE_CUSTOM_UNSPECIFIED. The application can use these values to identify languages that correspond to supplemental locales. The constants are defined in Locale Information.
Your application uses the MUI_LANGUAGE_NAME flag to instruct an MUI function to use a language name for language identification. The function represents the language by a name based on the language tagging conventions of RFC 4646 (Windows Vista and later).
For example, the value associated with LOCALE_SNAME for English (United States) is L"en-US", and the value for Divehi (Maldives) is L"dv-MV". The "L" in these values indicates that they are Unicode strings. For more information about LOCALE_SNAME, see Locale Information.
In general, your MUI applications should prefer MUI_LANGUAGE_NAME over MUI_LANGUAGE_ID, to accommodate languages that are implemented by a Language Interface Pack (LIP). Each of these languages corresponds to a supplemental locale. Each such language has a unique name, but the languages share language identifiers. For example, let's look at flag settings for French (France). MUI_LANGUAGE_ID indicates that French (France) is represented as L"040c". MUI_LANGUAGE_NAME requests ISO format, for which French (France) is represented as L"fr-FR".
Represent a Sequence of Languages as a Multi-string Value
Several MUI functions, for example, GetSystemPreferredUILanguages, get or set a list of languages. In each of these cases, a PWSTR data type is used to indicate a buffer for a sequence of null-terminated Unicode strings with an extra NULL after the last string.
As for a single language name, the MUI application has the choice of two mutually-exclusive formats for the strings that represent languages. The flags MUI_LANGUAGE_ID and MUI_LANGUAGE_NAME are supported and have the same meaning as they do for single language names.
Here is an example of the representation of multiple languages as a string:
For a list specifying French (France) and English (United States), in that order, the representation using language identifiers is L"040c\00409\0". The representation using language names is L"fr-FR\0en-US\0\0". As for any other C/C++ string, an additional terminating NULL (L'\0') is appended, so that the string ends with two consecutive null characters.
Some MUI functions represent these strings so that some identifiers are empty. For example, L"fr\0\0en\0" indicates "French (Neutral), <empty string>, English (Neutral)". Such functions always have a parameter that explicitly indicates how many items are in the list. Your application should consult this parameter, instead of assuming that two consecutive null characters necessarily specify the end of a list.