Editing Multilingual User Interface (section)

== Overview ==
The MUI technology<ref>{{Cite web |last=Karl-Bridge-Microsoft |title=Multilingual User Interface - Win32 apps |url=https://docs.microsoft.com/en-us/windows/win32/intl/multilingual-user-interface |access-date=2022-07-10 |website=docs.microsoft.com |language=en-us}}</ref> is integrated into the Windows OS and can be leveraged in an application by storing localizable assets as resources in a prescribed way and using MUI-enabled win32 functions to read the resources.

A relatively simple implementation of MUI in an application stores the strings of each language in a string-table resource of the binary file and uses the win32 function LoadString to load strings at runtime. No other MUI related configuration or code is required. The following optional capabilities of MUI can be implemented if desired:

* Store the resources of each language in a separate DLL in order to enable deployment/installation flexibility
* An application can use dedicated MUI functions to provide more control of localizable asset consumption such as using a language other than the system-defined user preference
* Localizable assets can be stored in a format other than resource
The design of MUI attempts to provide a common way to store application localization information that alleviates limitations of more traditional and monolithic designs for localization such as including all languages in the application logic files (i.e. resources). With MUI, the following deployment scenarios are possible:
* Add support for a language by installing only languages files -- without modifying application logic or other language files
* Add new features and fix bugs by installing only application logic files -- without modifying the installed language files

=== Terminology ===
The following MUI related terms are either used in or derived from the Microsoft documentation.

Language-neutral (LN): Describes something that conveys a meaning regardless of the languages of the viewer, such as an image without text or other localizable aspects

LN resource: a resource that is shared by and installed for all language versions of the application

LN file: Windows binary containing the application logic and language-neutral resources

Language-specific (LS): Describes something that has significantly different meaning based on the languages of the viewer. The most common LS items are interface strings but can be other items such as an image with text in it

LS resource file: A set of resources localized for one language; a.k.a. MUI file

=== Language Preferences ===
A language selection is stored by the system for the system (shared by all users and maybe used as default for a new user) and for each user. These selections can be modified by the user via the system Control Panel but cannot be modified by an application. 

These preferences control the language that the OS uses for UI elements. Applications can also use these preferences, and via MUI-enabled system functions (such as LoadString) the use is automatic and transparent (requires no MUI-specific code to use). But use of these preferences is optional and customizable. An application can be designed to ignore the language preferences. Or it may use them in ways other than that provided by MUI-enabled system functions. 

An application can use MUI functions<ref>{{Cite web |last=Karl-Bridge-Microsoft |title=Multilingual User Interface Functions - Win32 apps |url=https://docs.microsoft.com/en-us/windows/win32/intl/multilingual-user-interface-functions |access-date=2022-07-10 |website=docs.microsoft.com |language=en-us}}</ref> to read language preferences -- that default to the user selection [assumed] and are a list of languages in preference order. These preferences are provided at the system, user, process and thread levels [assumed that changing at a higher level modifies the preferences for lower levels]. 

An application can modify these language preference lists (via SetThreadPreferredUILanguages and other functions) in order to influence the behavior of MUI. For example: 
<syntaxhighlight lang="c">
LPCWSTR languageIdSpec = L"en-US\0";
ULONG langCount = 1;
if (!SetThreadPreferredUILanguages(MUI_LANGUAGE_NAME, languageIdSpec, &langCount))
    MessageBoxW(NULL, L"Unable to set thread preferred UI language.", NULL, MB_ICONERROR);
</syntaxhighlight>

=== Resource Storage ===
MUI provides support for localized resources stored in Windows binary (a.k.a. Win32 PE) files (DLL, EXE, SYS) -- usually DLL files. 

The resources for a language can either be stored in the application binary or in a MUI (a.k.a. LS) file -- one per language. For MUI to find resources, a MUI file must be in the same directory as its associated LN file and be named the same as the LN file plus ".''LCID''.mui". For example, for LN file '''my-lib.dll''', the MUI file for en-US would be named '''my-lib.dll.0409.mui'''.

String resources are coded as string table like so:
 LANGUAGE LANG_ENGLISH, SUBLANG_NEUTRAL
 STRINGTABLE
 BEGIN
 1 L"message text"
 END

=== Resource Retrieval ===
Several win32 functions that read application resources are MUI-enabled, including LoadString, FormatMessage, and LoadImage.<ref>{{Cite web |last=Karl-Bridge-Microsoft |title=Loading Language Resources - Win32 apps |url=https://docs.microsoft.com/en-us/windows/win32/intl/loading-language-resources |access-date=2022-07-10 |website=docs.microsoft.com |language=en-us}}</ref> 

Each function attempts to read a resource for a language as selected by global language preferences, from application resources or associated MUI files (co-located with LN file and following naming convention). Each uses the global language preferences to choose a language that is available. If loading the resource for the first preferred language fails either because the MUI file does not exist or the resource does not exist in the MUI file, the function will try the next preferred language and so on until all preferences have been tried. If load fails for all preferred languages, then tries the LN file.

The most commonly used function is LoadString which loads strings from a string-table resource. Example using LoadString:
<syntaxhighlight lang="c">
wchar_t *resourceCharArray;
int resourceLength = LoadStringW(moduleHandle, resourceId, (LPWSTR)&resourceCharArray, 0);
if (!resourceLength)
{
    MessageBoxW(NULL, L"Unable to find resource.", NULL, MB_ICONERROR);
    return -1;
}

wchar_t *text = (LPWSTR)malloc((resourceLength + 1) * sizeof(wchar_t));
wcsncpy(text, resourceCharArray, resourceLength);
text[resourceLength] = L'\0'; // null terminate
</syntaxhighlight>
This retrieves the address of the resource text character buffer which is not guaranteed to be null terminated. Then, this copies the characters to a new buffer and appends a null terminator. Another option is to have LoadString copy the string to a passed buffer, but that requires using a fixed-length buffer which has downsides like usually allocating more than needed or truncation if too short.

Oddly, MS documentation for LoadString does not mention its interaction with MUI -- use of language preference.

FormatMessage is also MUI-enabled. Its function reference page describes its interaction with the user's language preference when parameter dwLanguageId is passed as 0. But FormatMessage reads from a ''message'' table, not a ''string'' table and as Raymond Chen says, "nobody actually uses message tables".<ref>{{Cite web |last=Chen |first=Raymond |date=2008-02-29 |title=Why can't I get FormatMessage to load my resource string? |url=https://devblogs.microsoft.com/oldnewthing/20080229-00/?p=23263 |access-date=2022-07-08 |website=The Old New Thing |language=en-US}}</ref>

=== Non-Resource Storage and Retrieval ===
MS documentation recommends storing UI assets as resources since MUI fully supports retrieving from this storage, but it notes that MUI supports any other file format, such as XML, JSON or flat text file.<ref>{{Cite web |last=Karl-Bridge-Microsoft |title=Supporting System Language Settings - Win32 apps |url=https://docs.microsoft.com/en-us/windows/win32/intl/supporting-system-language-settings |access-date=2022-07-09 |website=docs.microsoft.com |language=en-us}}</ref> This implies that using the resource retrieval aspect of MUI is not required for an application to be MUI-enabled. An application can use its own, custom UI asset retrieval logic.

To be MUI-enabled, the application must use the system language preferences. The custom UI asset retrieval logic might optionally use the MUI function GetFileMUIPath to leverage the MUI file location and naming conventions.

=== Other Aspects ===
The MS MUI documentation describes the following concepts, but it is unclear how they relate to MUI and what value they offer:

* Resource Configuration File<ref>{{Cite web |last=Karl-Bridge-Microsoft |title=Preparing a Resource Configuration File - Win32 apps |url=https://docs.microsoft.com/en-us/windows/win32/intl/preparing-a-resource-configuration-file |access-date=2022-07-10 |website=docs.microsoft.com |language=en-us}}</ref>
* Registry String Redirection<ref>{{Cite web |last=Karl-Bridge-Microsoft |title=Using Registry String Redirection - Win32 apps |url=https://docs.microsoft.com/en-us/windows/win32/intl/using-registry-string-redirection |access-date=2022-07-10 |website=docs.microsoft.com |language=en-us}}</ref>