SetThreadLocale and SetThreadUILanguage for Localization on Windows XP and Vista

Simple Localization

In classic Windows programming, the quickest way to handle localized resources is to put all languages into the same resource file, then use SetThreadLocale to tell Windows that it should return resources tagged with the specified language identifier. Subsequently, any attempt to load a resource by that thread will cause Windows to prefer resources corresponding to the specified language code.

Vista Complications

As of Windows Vista, calling SetThreadLocale will appear to work, but will have no effect. Your application will continue to use load resources using whatever language identifier is set as the user’s default.

Under Windows Vista, SetThreadUILanguage must be called instead of SetThreadLocale. This function is in Kernel32.dll. It appears in Vista, Windows 2008, and some versions of Windows XP. Under Windows XP, this function will not have the desired effect, and I have no idea what it does under Windows 2008.

Since the function isn’t available on all systems, you will probably want to use GetProcAddress to locate the function, and call it using a function pointer. However, since the function appears on Windows XP, but does not behave in the desired way, it’s important to only call it on Windows Vista.

Resource Storage

To use the SetThreadLocale or SetThreadUILanguage methods, the resource file must first be populated with all required languages. Each translated resource file should be appended to the .rc file, each one following an appropriate LANGUAGE statement and corresponding language identifier. (note that you could use separate .rc files and include them, in which case there are gotchas).

Is it Vista?

This function should reliably indicate whether the current OS is Windows Vista. I use GetVersionEx. Note that, even though we’re using an OSVERSIONINFOEX structure, we have to cast its pointer so that it appears as a OSVERSIONINFO pointer. No guarantee of future compatibility is implied:

bool IsOSVerWindowsVista()
{
    OSVERSIONINFOEX osver;
    ZeroMemory(&osver, sizeof(osver);
    osver.dwOSVersionInfoSize = sizeof(osver);

    if (!GetVersionEx((OSVERSIONINFO *)&osver))
        return false;

    // dwMajorVersion 6 and dwMinorVersion 0 means Vista or 2k8:
    if ( (osver.dwMajorVersion != 6) || (osver.dwMinorVersion != 0) )
        return false;

    // wProductType of NT_WORKSTATION means it's Vista:
    if (osver.wProductType != VER_NT_WORKSTATION)
        return false;

    return true;   
}

Calling SetThreadUILanguage Dynamically

The trickiest part of using GetProcAddress to dynamically call a function at run-time is getting the function pointer declaration correct. This type definition should work for SetThreadUILanguage:

typedef LANGID (WINAPI *FP_SetThreadUILanguage)(LANGID LangId);

Now, you have a function pointer type called FP_SetThreadUILanguage which can be used like any other type.

This function pointer can be used to dynamically call any function within a loaded module (DLL). SetThreadUILanguage lives inside Kernel32.dll. Since Kernel32.dll is required by all Win32 processes, we can simply use GetModuleHandle to find it, we don’t have to use LoadLibrary. A pointer to SetThreadUILanguage can therefore be retrieved like this (unnecessarily verbose code):

HMODULE hKernel32 = GetModuleHandle(_T("Kernel32.dll"));
FARPROC pFn = GetProcAddress(hKernel32, "SetThreadUILanguage");

FP_SetThreadUILanguage pSetThreadUILanguage = (FP_SetThreadUILanguage)pFn

The function can now be called through the function pointer variable:

LANGID langid = pSetThreadUILanguage(myLangId);

SetThreadUILanguage returns the LANGID which has been set. If the call was successful, it will return the same LANGID that was specified.

Constructing a Language Identifier

Use the MAKELANGID macro from Winnt.h, and supply LANG_Xxx constants from same. For example, Simplified Chinese would require:

DWORD dwSimplifiedChinese =
   MAKELANGID( LANG_CHINESE, SUBLANG_CHINESE_SIMPLIFIED );

Non-Vista Platforms

On non-Vista platforms, SetThreadLocale can be used. Instead of a language identifier, it accepts a locale identifier. To generate the locale identifier, simply pass your language identifier to the MAKELCID macro, and supply SORT_DEFAULT as the second parameter:

SetThreadLocale(MAKELCID(myLangId, SORT_DEFAULT));

This example unconditionally sets the thread locale to Simplified Chinese in a single line of code:

SetThreadLocale(
   MAKELCID(
      MAKELANGID(LANG_CHINESE, SUBLANG_CHINESE_SIMPLIFIED), 
      SORT_DEFAULT));

SetThreadLocale returns TRUE on success, FALSE on error.

Reference

• Multiple-Language Resources (MSDN)