setlocale()

The PHP setlocale() function sets the current locale for a script — the collection of culture-specific rules that decide how text is sorted, how numbers and currency are formatted, and how dates are spelled out. A locale is identified by a string such as en_US (US English) or de_DE (German), usually combined with a character encoding like .utf8.

You reach for setlocale() whenever a single codebase has to produce output that "feels native" in more than one country: 1,234.56 for an American user but 1.234,56 for a German one, January versus Januar, and so on.

Syntax

setlocale(int $category, string $locale, string ...$locales): string|false

It can also accept a single array of locales instead of a list:

setlocale(int $category, array $locale): string|false

Parameters

• $category — which group of locale-dependent behavior to change. Pass one of the LC_* constants:

  Constant	Affects
  LC_ALL	Every category at once
  LC_COLLATE	String comparison and sorting (see strcoll())
  LC_CTYPE	Character classification and case conversion
  LC_MONETARY	Currency formatting (see money_format())
  LC_NUMERIC	Decimal separator for numbers
  LC_TIME	Date and time formatting (see strftime())
  LC_MESSAGES	System message formatting (not available on Windows)

• $locale — the locale string to apply, e.g. 'en_US.utf8'. Three special values are handy:

  • "" (empty string) — use the locale from the server's environment variables.
  • "0" — don't change anything; just return the current setting for that category.
  • null — same as "0".

• ...$locales — optional fallbacks. PHP tries each name in order and applies the first one the operating system actually has installed.

It returns the name of the locale that was set on success, or false if none of the requested locales is available.

Basic example

<?php
$result = setlocale(LC_ALL, 'en_US.utf8');

if ($result !== false) {
    echo "Locale set to: $result";
} else {
    echo "Requested locale is not installed.";
}
?>

setlocale() returns the new locale string on success or false on failure, so always check the return value — a missing locale fails silently and leaves your formatting wrong rather than throwing an error.

Providing fallbacks

Locale names differ between operating systems (en_US.utf8 on Linux, English_United States.1252 on Windows). Listing several names lets the same script work everywhere — PHP uses the first installed match:

<?php
$locale = setlocale(
    LC_ALL,
    'en_US.UTF-8',                 // Linux / macOS
    'en_US.utf8',
    'English_United States.1252'   // Windows
);

echo $locale ?: 'No English locale available';
?>

Why the locale matters: number formatting

After setting LC_NUMERIC (or LC_ALL), functions that respect the locale produce culture-specific output. Here the decimal and thousands separators follow German conventions:

<?php
setlocale(LC_ALL, 'de_DE.utf8', 'de_DE', 'German_Germany.1252');

$info = localeconv();
echo $info['decimal_point'];   // ,
echo "\n";
echo $info['thousands_sep'];   // .
?>

localeconv() reads back the active locale's numeric and monetary rules, which is the safest way to format numbers by hand. Note that PHP's number_format() does not read the locale — you pass separators to it explicitly.

Common gotchas

• The locale must be installed on the server. setlocale() only succeeds for locales the OS knows. On a Debian/Ubuntu box you might need locale-gen de_DE.UTF-8 && update-locale.
• It is process-global, not thread-safe. The setting affects the whole PHP process, so avoid changing it concurrently in multi-threaded SAPIs.
• It does not change echo or printf() for floats. Use sprintf() with care; the locale's decimal point can surprise functions that build SQL or JSON. Reset with setlocale(LC_NUMERIC, 'C') around such code.
• money_format() was removed in PHP 8.0. For currency, prefer the NumberFormatter class from the intl extension.

Practice