تابع setlocale() در PHP

تابع setlocale() در PHP برای تنظیم لوکال (locale) یا محیط‌محلی برنامه استفاده می‌شود. لوکال تعیین می‌کند که چگونه مقادیر مرتبط با زبان، تاریخ، اعداد، واحد پول و ترتیب حروف در خروجی نمایش داده شوند. این تابع به ویژه برای برنامه‌هایی که باید محلی‌سازی (i18n) انجام دهند یا خروجی مطابق با منطقه کاربر تولید کنند، حیاتی است.

پارامترها و مقدار بازگشتی

تابع setlocale قالب کلی زیر را دارد:

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

توضیح کوتاه:

• category: یکی از ثوابت LC_* مثل LC_ALL، LC_TIME، LC_NUMERIC و …
• locale: رشته‌ای که نام لوکال را مشخص می‌کند؛ می‌تواند آرایه‌ای از گزینه‌ها برای fallback هم باشد
• مقدار بازگشتی: در صورت موفقیت رشته لوکال تنظیم‌شده و در صورت شکست false
• برای خواندن حالت فعلی می‌توان setlocale(LC_ALL, 0) را فراخوانی کرد تا رشته فعلی لوکال دریافت شود

ثوابت (LC_*) و نقش هر کدام

مثال پایه: تنظیم لوکال با fallback

// تلاش برای تنظیم لوکال فارسی (UNIX و Windows ممکن است اسم‌های متفاوتی داشته باشند)
$locale = setlocale(LC_ALL, ['fa_IR.UTF-8', 'fa_IR', 'Persian_Iran.1256', 'fa']);
if ($locale === false) {
    echo "لوکال فارسی یافت نشد، از پیش‌فرض استفاده می‌شود.n";
} else {
    echo "لوکال تنظیم شد: $localen";
}

این کد یک آرایه از نام‌های ممکن برای لوکال فارسی را می‌فرستد تا در سیستم‌های مختلف (Linux، macOS، Windows) یکی از آن‌ها پذیرفته شود. اگر هیچ‌کدام قابل تنظیم نباشد، تابع false برمی‌گرداند.

نمایش نام ماه با strftime (و هشدار در مورد deprecation)

setlocale(LC_TIME, 'fa_IR.UTF-8');
echo strftime('%A %d %B %Y', strtotime('2025-11-07')) . "n";

کد بالا با LC_TIME تنظیم‌شده سعی می‌کند نام روز و ماه را به زبان محلی نمایش دهد. توجه: تابع strftime در PHP 8.1 به عنوان deprecated مشخص شده است و در نسخه‌های آینده ممکن است حذف شود. به جای آن توصیه می‌شود از کلاس‌های IntlDateFormatter استفاده کنید که مستقل از سیستم‌عامل و قابل اتکا‌تر هستند.

جایگزین بهتر: IntlDateFormatter

// نیاز به ext-intl
$fmt = new IntlDateFormatter('fa_IR', IntlDateFormatter::FULL, IntlDateFormatter::NONE, 'Asia/Tehran', IntlDateFormatter::TRADITIONAL);
echo $fmt->format(new DateTime('2025-11-07')) . "n";

اینجا از IntlDateFormatter استفاده شده که نیازی به setlocale برای نمایش تاریخ به زبان محلی ندارد و نتایج قابل پیش‌بینی‌تری بین پلتفرم‌ها ارائه می‌کند.

فرمت اعداد و واحد پول: NumberFormatter

// فرمت عدد و ارز با استفاده از intl
$fmtNumber = new NumberFormatter('fa_IR', NumberFormatter::DECIMAL);
echo $fmtNumber->format(12345.67) . "n";

$fmtCurrency = new NumberFormatter('fa_IR', NumberFormatter::CURRENCY);
echo $fmtCurrency->formatCurrency(12345.67, 'IRR') . "n";

بجای توابع وابسته به libc مانند money_format، توصیه می‌شود از NumberFormatter استفاده کنید. این کلاس کنترل بهتری روی جداکننده‌ها، گروه‌بندی هزارگان و نمایش ارز ارائه می‌دهد.

نکات مهم و تفاوت‌های سیستم‌عامل

• نام لوکال‌ها در لینوکس/یونیکس معمولاً شبیه fa_IR.UTF-8 است؛ در ویندوز ممکن است نام متفاوت باشد مثل Persian_Iran.1256.
• برای دانستن لوکال‌های نصب‌شده در سرور لینوکس، دستور locale -a مفید است.
• setlocale تابعی از کتابخانه C سیستم است؛ یعنی نتیجه آن وابسته به تنظیمات سیستم است و در هاست‌های اشتراکی همیشه قابل تغییر نیست.
• برای تولید خروجی مستقل از سیستم (و قابل پیش‌بینی) ترجیح با ext-intl است.

مثال مقایسه‌ای: مرتب‌سازی حساس به لوکال (collation)

$items = ['سارا', 'علی', 'آرمان'];
// استفاده از strcoll بعد از setlocale
setlocale(LC_COLLATE, 'fa_IR.UTF-8');
usort($items, function($a, $b) {
    return strcoll($a, $b);
});
print_r($items);

// روش بهتر با Intl Collator
$coll = new Collator('fa_IR');
$items2 = ['سارا', 'علی', 'آرمان'];
$coll->asort($items2);
print_r($items2);

strcoll به تابع لوکال سیستم برای مقایسه تکیه می‌کند؛ Collator از ext-intl است و نتایج قابل اعتمادتر و قابل کنترل‌تری (مثل سطح حساسیت) ارائه می‌دهد.

چک‌لیست عملیاتی هنگام استفاده از setlocale

• اگر روی سرور کنترل ندارید، ابتدا بررسی کنید چه لوکال‌هایی نصب هستند.
• از آرایه fallback استفاده کنید تا احتمال پیدا شدن لوکال مناسب افزایش یابد.
• برای تاریخ و فرمت اعداد، در صورت امکان از ext-intl استفاده کنید تا وابستگی به libc حذف شود.
• همیشه مقدار بازگشتی setlocale را بررسی کنید و در صورت false راه‌حل جایگزین (پیش‌فرض) در نظر بگیرید.

خلاصه: setlocale ابزار ساده و مفیدی برای تعیین رفتارهای محلی روی توابع وابسته به libc است، اما به دلیل وابستگی به سیستم‌عامل و تغییرات نسخه‌های PHP، بهتر است در ترکیب با یا جایگزینی ext-intl استفاده شود تا خروجی‌ها قابل پیش‌بینی و مستقل از پلتفرم باشند.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال