PHP setlocale() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
String

Definition

In PHP, setlocale() sets the locale used for things like number formatting, dates, and character types.

It returns the name of the new locale, or false if the locale is not available.

Syntax

Call setlocale() with the values you need. Start with this line.

PHP
$locale = setlocale(LC_ALL, "C");
CallWhat it does
setlocale(LC_ALL, "C")Sets every category to the C locale and returns "C".
setlocale(LC_ALL, "0")Does not change anything. Returns the current locale.
setlocale(LC_ALL, "xx_NOPE", "C")Tries each name in order. Returns "C" here.

Common categories are LC_ALL, LC_NUMERIC, LC_TIME, LC_MONETARY, LC_COLLATE, and LC_CTYPE.

Library declarations
PHP
setlocale(int $category, ?string $locales, string ...$rest): string|false

Parameters

ParameterDescription
categoryRequired. The category to change, such as LC_ALL or LC_TIME.
localesRequired. The locale name, or an array of names. Use "0" or null to only read the current value.
restOptional. More locale names to try if the earlier ones fail.

Return Value

Return ValueDescription
stringThe name of the locale that is now active.
falseReturned when the system does not know the locale.

PHP Examples

Example 1 — Set the Locale

Set the C locale and print what PHP returns.

PHP
<?php
$result = setlocale(LC_ALL, "C");

echo $result, PHP_EOL;

How It Works

  1. Pick a category. LC_ALL covers every category.
  2. Pass a locale name. C is always available.
  3. Read the return value. It is the name that is now active.
  4. Print it. You see C.

Example 2 — Unknown Locale Returns false

A locale that is not installed gives false, and the old locale stays.

PHP
<?php
setlocale(LC_ALL, "C");

var_dump(setlocale(LC_ALL, "xx_NOPE"));
echo setlocale(LC_ALL, "0"), PHP_EOL;

How It Works

  1. Start with C. This is a known good state.
  2. Try a fake name. The system does not know xx_NOPE.
  3. Get false. Nothing is changed.
  4. Query with "0". The current locale is still C.

Example 3 — Provide Fallback Locales

Pass several names. PHP uses the first one that works.

PHP
<?php
$used = setlocale(LC_ALL, "xx_NOPE", "yy_NOPE", "C");

if ($used === false) {
    echo "No locale could be set", PHP_EOL;
} else {
    echo "Using: " . $used, PHP_EOL;
}

How It Works

  1. List candidates. The first two names do not exist.
  2. PHP tries each in order. It moves on after every failure.
  3. C works. That one is applied and returned.
  4. Check for false. Handle the case where nothing worked.

Frequently Asked Questions

setlocale() changes the locale for a category, which affects things like number formatting, character classification, string comparison, and date names from functions that use the locale.
string|false setlocale(int $category, ?string $locales, string ...$rest). You can also pass an array of locale names as the second argument.
The locale is not installed or the name is wrong for your operating system. Check the names that your system supports.
Call setlocale(LC_ALL, "0"). Passing "0" or null only reads the value and does not change it.
It affects the current process. On threaded servers that can touch other requests, so prefer the intl extension such as NumberFormatter for modern code.

Next: sha1()

sha1() calculates the SHA-1 hash of a string.

sha1() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful