SDL_GetPreferredLocales(3)

💖 SDL_GetPreferredLocales 💖

okay bestie, so this one lives in the SDL3 FUNCTIONS section of the manual (that's the family it runs with 🫶), and it's genuinely one of the cutest little functions in SDL — it's your one-stop shop for "hey, what language does this user actually speak?"

---

✨ NAME ✨

SDL_GetPreferredLocales — spill the tea on the user's preferred locale 💅

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_locale.h>

SDL_Locale ** SDL_GetPreferredLocales(int *count);

---

✨ DESCRIPTION ✨

so like, the language strings it hands back are in the format xx, where xx is an ISO-639 language specifier (think "en" for English, "de" for German, etc etc). and the country strings? those are format YY, where YY is an ISO-3166 country code ("US" for the United States, "CA" for Canada, you get the vibe 🌍).

now here's the thing — the country can be NULL if there's no specific guidance on it. so you might get { "en", "US" } for American English, but { "en", NULL } means "English language, generically". no country assigned, she's just out here speaking English generically, iconic behavior. 🎀

⚠️ important: language strings are never NULL, except to terminate the array. that's the only reason they'd be NULL. don't panic. 💜

also pls note that not all of these strings are 2 characters — some are three or more. so don't go assuming a fixed width, bestie, that's a trap 🙈

---

🌈 the order thing (this is the good part)

the returned list of locales is in the order of the user's preference. like, most-wanted first. for example:

a German citizen who is fluent in US English and knows enough Japanese to navigate around Tokyo might have a list like:

{ "de", "en_US", "jp", NULL }

and someone from England might prefer British English (where "color" is spelled "colour", etc), but will settle for anything like it:

{ "en_GB", "en", NULL }

see how that works? she gets her first pick, and if you can't do that, she's flexible. queen energy honestly 👑

---

😭 the error situation

this function returns NULL on error — and yes, that includes when the platform doesn't supply this information at all. sometimes the OS is just not forthcoming, and there's nothing SDL can do about it. it's not you, it's the platform. 💀

---

🐌 the "slow call" warning

heads up: this might be a "slow" call that has to query the operating system.

so it's best to ask for this once and save the results. don't be out here calling it in your render loop, bestie, that's a crime. 🙈

BUT — and this is important — this list can change, usually because the user has changed a system preference outside of your program. when that happens, SDL will send an SDL_EVENT_LOCALE_CHANGED event, if possible, and you can call this function again to get an updated copy of preferred locales. so you're not stuck with stale info forever. slay. ✨

---

✨ FUNCTION PARAMETERS ✨

• count — a pointer that gets filled in with the number of locales returned. it may be NULL if you literally do not care how many there are. no pressure. 🫶

---

✨ RETURN VALUE ✨

returns a NULL terminated array of locale pointers, or NULL on failure. if it fails, call SDL_GetError() for more info on what went wrong (she'll tell you everything 💜).

🧚 don't forget: this is a single allocation that should be freed with SDL_free() when it is no longer needed. free your memory, bestie. it's the responsible thing and it's lowkey kind of hot.

---

✨ THREAD SAFETY ✨

this function is not thread safe. no cap. do not share it across threads, do not pass go. 🚫

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. so if you're on anything older, sorry babe, she's not there yet. 😭

---

and that's the whole page!! 🌸 from your girl Simple Directmedia Layer, living in SDL 3.4.18 — that's the source and the version, and this lil doc is dated SDL_GetPreferredLocales(3), so you know exactly where to find her again. mwah 💅✨🎀