C Standard Library locale.h

What You’ll Learn

The <locale.h> header controls locale—the cultural rules for formatting numbers, money, dates, and sorting text. With setlocale and localeconv, your program can follow the user’s regional settings instead of always using the plain "C" locale.

Definition and Usage

A locale bundles conventions: which character is the decimal point, how dates are written, how strings sort, and how ctype classifies letters. At startup, C programs use the "C" locale unless you call setlocale.

setlocale(int category, const char *locale) changes one category or all of them. Pass NULL as the second argument to query the current setting without changing it. On success it returns a string naming the locale; on failure it returns NULL.

📝 Syntax

Include the header:

#include <locale.h>

Category macros

• LC_ALL — all categories together.
• LC_COLLATE — string collation (strcoll, strxfrm).
• LC_CTYPE — character classification (isalpha, toupper).
• LC_MONETARY — currency formatting.
• LC_NUMERIC — decimal point and thousands separator for numbers.
• LC_TIME — date and time format (strftime).

Functions

char *setlocale(int category, const char *locale);
struct lconv *localeconv(void);

Common locale strings

• "C" — portable default (dot decimal, predictable sorting).
• "" — use environment (LANG, LC_* variables).
• "en_US.UTF-8" — US English with UTF-8 (if installed on the system).
• "de_DE.UTF-8" — German locale example (availability varies).

Key struct lconv fields

• decimal_point — character between integer and fraction (often "." or ",").
• thousands_sep — grouping separator (often "," or ".").
• grouping — rules for digit groups.
• currency_symbol, mon_decimal_point — monetary formatting.

Headers and linking

• #include <locale.h> — no special link flag.
• Date examples: #include <time.h> for strftime.
• Compile: gcc program.c -std=c11 -o program

Examples Gallery

Compile with gcc file.c -std=c11 -o out. Locale names and output vary by OS. Examples use "C" where portability matters; regional locales may need to be installed on your system.

#include <locale.h>
#include <stdio.h>

int main(void) {
    const struct lconv *lc;

    if (setlocale(LC_ALL, "C") == NULL) {
        printf("Failed to set C locale\n");
        return 1;
    }

    lc = localeconv();

    printf("Decimal point: '%s'\n", lc->decimal_point);
    printf("Thousands sep: '%s'\n",
           lc->thousands_sep[0] ? lc->thousands_sep : "(none)");

  /* printf uses locale for some conversions; C locale uses '.' */
    printf("Number: %.2f\n", 1234567.89);

    return 0;
}

Decimal point: '.'
Thousands sep: '(none)'
Number: 1234567.89

#include <locale.h>
#include <stdio.h>

int main(void) {
    char *result = setlocale(LC_ALL, "xx_YY.UTF-8");

    if (result == NULL) {
        printf("Locale not available — falling back to C\n");
        setlocale(LC_ALL, "C");
    } else {
        printf("Locale set to: %s\n", result);
    }

    printf("Current locale: %s\n", setlocale(LC_ALL, NULL));

    return 0;
}

Locale not available — falling back to C
Current locale: C

#include <locale.h>
#include <stdio.h>

int main(void) {
    setlocale(LC_ALL, "C");
    printf("C locale:     %.2f\n", 3.14);

    if (setlocale(LC_NUMERIC, "en_US.UTF-8") != NULL) {
        printf("en_US numeric: %.2f\n", 3.14);
        printf("Decimal point: %s\n", localeconv()->decimal_point);
    } else {
        printf("en_US.UTF-8 not installed on this system\n");
    }

    return 0;
}

C locale:     3.14
en_US numeric: 3.14
Decimal point: .

#include <locale.h>
#include <stdio.h>
#include <time.h>

void print_date(const char *locale_name) {
    time_t now = time(NULL);
    struct tm *tm_info = localtime(&now);
    char buf[64];

    setlocale(LC_TIME, locale_name);
    strftime(buf, sizeof(buf), "%A, %d %B %Y", tm_info);
    printf("LC_TIME=%s: %s\n", locale_name, buf);
}

int main(void) {
    print_date("C");
    if (setlocale(LC_TIME, "en_US.UTF-8") != NULL) {
        print_date("en_US.UTF-8");
    }
    return 0;
}

LC_TIME=C: Sunday, 05 July 2026
LC_TIME=en_US.UTF-8: Sunday, 05 July 2026

#include <locale.h>
#include <stdio.h>
#include <string.h>

int main(void) {
    char saved[64];
    const char *cur = setlocale(LC_ALL, NULL);

    if (cur != NULL) {
        strncpy(saved, cur, sizeof(saved) - 1);
        saved[sizeof(saved) - 1] = '\0';
    }

    printf("Before: %s\n", setlocale(LC_ALL, NULL));

    setlocale(LC_ALL, "C");
    printf("During: %s (printing %.2f)\n", setlocale(LC_ALL, NULL), 1.5);

    setlocale(LC_ALL, saved);
    printf("After restore: %s\n", setlocale(LC_ALL, NULL));

    return 0;
}

Before: C
During: C (printing 1.50)
After restore: C

🚀 Common Use Cases

• Desktop utilities — setlocale(LC_ALL, "") to match the user’s OS settings.
• Report generators — locale-aware dates with strftime and LC_TIME.
• Financial output — localeconv currency fields for invoices.
• Sorting names — LC_COLLATE with strcoll for dictionary order.
• Parsers — read decimal_point before parsing user numbers.
• Servers — keep "C" locale for logs; localize only UI layers.

📝 Notes

• Programs start in the "C" locale unless the environment or your code changes it.
• Locale names are platform-specific; en_US.UTF-8 on Linux may differ on Windows (English_United States.utf8).
• setlocale is not thread-safe—avoid changing locale in multithreaded servers casually.
• localeconv returns a static struct; copy strings if you call setlocale again.
• Changing LC_CTYPE affects <ctype.h> functions for non-ASCII letters.
• For full Unicode/i18n, many projects use ICU or similar libraries beyond standard C.

⚡ Optimization

Keep the default "C" locale in performance-critical paths. Locale-aware collation and formatting are slower than byte-wise compares and fixed printf formats. Change locale only at UI boundaries or when generating user-facing output.

💡 Best Practices