Report the user's preferred locale.
Defined in <SDL3/SDL_locale.h>
SDL_Locale ** SDL_GetPreferredLocales(int *count);| int * | count | a pointer filled in with the number of locales returned, may be NULL. |
(SDL_Locale **) Returns a NULL-terminated array of locale pointers, or NULL on failure; call SDL_GetError() for more information. Call SDL_free() when done with this pointer.
This returns a NULL-terminated array of pointers to locale information. The returned list of locales are in the order of the user's preference. For example, a German citizen that is fluent in US English and knows enough Japanese to navigate around Tokyo might have a list like:
{
{ "de", "DE" },
{ "en", "US" },
{ "jp", NULL },
NULL
}Someone from England might prefer British English (where "color" is spelled "colour", etc), but will settle for anything like it:
{
{ "en", "GB" },
{ "en", NULL },
NULL
}This function returns NULL on error, including when the platform does not supply this information at all.
Note that this information is merely guidance; some platforms don't supply it, some only supply a single language ever, some don't ever provide country information, etc. Be prepared to receive surprising results and plan to have fallbacks.
This might be a "slow" call that has to query the operating system. It's best to ask for this once and save the results. However, this list can change, usually because the user has changed a system preference outside of your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, if possible, and you can call this function again to get an updated copy of preferred locales.
The returned pointer is a single allocation (all the strings and structures are allocated in a single chunk, even though they look like separate data), and should be disposed of with a single call to SDL_free() when it is no longer needed.
If not NULL, *count will be set to number of items returned, not counting the terminating NULL pointer. count may be NULL if one plans to simply iterate the returned array directly.
This function is not thread safe.
This function is available since SDL 3.2.0.