locale --- خدمات بین‌المللی‌سازی

کد منبع: Lib/locale.py

ماژول locale دسترسی به پایگاه‌داده و کارکرد تنظیمات locale (locale) POSIX را فراهم می‌کند. سازوکار تنظیمات locale POSIX به برنامه‌نویسان اجازه می‌دهد با برخی مسائل فرهنگی در یک برنامه سروکار داشته باشند، بدون این‌که لازم باشد برنامه‌نویس تمام جزئیات هر کشوری را که نرم‌افزار در آن اجرا می‌شود بداند.

ماژول locale بر پایه‌ی ماژول _locale پیاده‌سازی شده است، که به نوبه خود در صورت در دسترس بودن از یک پیاده‌سازی locale در ANSI C استفاده می‌کند.

ماژول locale استثنا و توابع زیر را تعریف می‌کند:

exception locale.Error

استثنایی که در صورت شناسایی نشدن تنظیمات locale ارسال‌شده به setlocale() پرتاب می‌شود.

locale.setlocale(category, locale=None)

اگر locale داده شده باشد و None نباشد، setlocale() تنظیمات locale را برای category تغییر می‌دهد. دسته‌های موجود در توضیحات داده‌های زیر فهرست شده‌اند. locale می‌تواند یک رشته، یا جفتی از کد زبان و کدگذاری باشد. یک رشته خالی تنظیمات پیش‌فرض کاربر را مشخص می‌کند. اگر تغییر تنظیمات locale ناموفق باشد، استثنای Error پرتاب می‌شود. در صورت موفقیت، تنظیمات locale جدید برگردانده می‌شود.

اگر locale یک جفت باشد، با استفاده از موتور نام‌مستعارسازی locale به یک نام locale تبدیل می‌شود. کد زبان همان قالب یک نام locale را دارد، اما بدون کدگذاری و اصلاح‌کننده @. کد زبان و کدگذاری می‌توانند None باشند.

اگر locale حذف شود یا None باشد، تنظیم فعلی category برگردانده می‌شود.

مثال:

>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL)  # get current locale
# use German locale; name and availability varies with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
>>> locale.strcoll('f\xe4n', 'foo')  # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '')   # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C')  # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc)  # restore saved locale

setlocale() در بیشتر سیستم‌ها نخ‌ایمن (thread-safe) نیست. برنامه‌ها معمولاً با یک فراخوانی شروع می‌شوند:

import locale
locale.setlocale(locale.LC_ALL, '')

این کار تنظیمات locale را برای تمام دسته‌ها روی تنظیم پیش‌فرض کاربر قرار می‌دهد (که معمولاً در متغیر محیطی LANG مشخص شده است). اگر تنظیمات locale پس از آن تغییر نکند، استفاده از چندنخی نباید مشکلی ایجاد کند.

locale.localeconv()

پایگاه داده‌ی قراردادهای محلی را به‌صورت یک دیکشنری برمی‌گرداند. این دیکشنری رشته‌های زیر را به‌عنوان کلید دارد:

دسته

کلید

معنی

LC_NUMERIC

'decimal_point'

نویسه‌ی نقطه اعشار.

'grouping'

دنباله‌ای از اعداد که مشخص می‌کند 'thousands_sep' در کدام موقعیت‌های نسبی انتظار می‌رود. اگر دنباله با CHAR_MAX پایان یابد، دیگر گروه‌بندی انجام نمی‌شود. اگر دنباله با یک 0 پایان یابد، آخرین اندازه گروه به‌طور مکرر استفاده می‌شود.

'thousands_sep'

نویسه‌ی استفاده‌شده بین گروه‌ها.

LC_MONETARY

'int_curr_symbol'

نماد ارز بین‌المللی.

'currency_symbol'

نماد واحد پول محلی.

'p_cs_precedes/n_cs_precedes'

اینکه نماد ارز پیش از مقدار می‌آید (برای مقادیر مثبت و منفی به‌ترتیب).

'p_sep_by_space/n_sep_by_space'

اینکه نماد ارز با یک فاصله از مقدار جدا می‌شود (برای مقادیر مثبت و منفی به‌ترتیب).

'mon_decimal_point'

نقطه اعشار مورد استفاده برای مقادیر پولی.

'frac_digits'

تعداد ارقام کسری مورد استفاده در قالب‌بندی محلی مقادیر پولی.

'int_frac_digits'

تعداد ارقام کسری به‌کاررفته در قالب‌بندی بین‌المللی مقادیر پولی.

'mon_thousands_sep'

جداکننده‌ی گروه‌بندی که برای مقادیر پولی استفاده می‌شود.

'mon_grouping'

معادل 'grouping'، برای مقادیر پولی استفاده می‌شود.

'positive_sign'

نمادی که برای حاشیه‌نویسی یک مقدار پولی مثبت استفاده می‌شود.

'negative_sign'

نمادی که برای حاشیه‌نویسی مقدار پولی منفی استفاده می‌شود.

'p_sign_posn/n_sign_posn'

جایگاه علامت (برای مقادیر مثبت و منفی به‌ترتیب)، در زیر ببینید.

می‌توان تمام مقادیر عددی را روی CHAR_MAX تنظیم کرد تا نشان داده شود که هیچ مقداری در این تنظیمات locale مشخص نشده است.

مقادیر ممکن برای 'p_sign_posn' و 'n_sign_posn' در زیر آمده‌اند.

مقدار

توضیح

0

واحد پول و مقدار داخل پرانتز قرار می‌گیرند.

1

علامت باید پیش از مقدار و نماد ارز قرار بگیرد.

2

علامت باید پس از مقدار و نماد ارز بیاید.

3

علامت باید بلافاصله پیش از مقدار قرار گیرد.

4

علامت باید بلافاصله پس از مقدار بیاید.

CHAR_MAX

هیچ چیزی در این locale مشخص نشده‌است.

این تابع به‌طور موقت locale LC_CTYPE را روی locale LC_NUMERIC یا locale LC_MONETARY تنظیم می‌کند، اگر localeها متفاوت باشند و رشته‌های عددی یا پولی غیر ASCII باشند. این تغییر موقت بر نخ‌های دیگر تأثیر می‌گذارد.

تغییر یافته در نسخه‌ی 3.7: این تابع اکنون در برخی موارد، به‌طور موقت تنظیمات locale LC_CTYPE را برابر با تنظیمات locale LC_NUMERIC قرار می‌دهد.

locale.nl_langinfo(option)

برخی اطلاعات مختص به locale را به‌صورت یک رشته برمی‌گرداند. این تابع در همه سامانه‌ها در دسترس نیست و ممکن است مجموعه گزینه‌های ممکن نیز در سکوهای مختلف متفاوت باشد. مقادیر ممکن آرگومان، اعدادی هستند که برای آن‌ها ثابت‌های نمادین در ماژول locale در دسترس است.

تابع nl_langinfo() یکی از کلیدهای زیر را می‌پذیرد. بیشتر توضیحات از توضیح متناظر در کتابخانه GNU C گرفته شده‌اند.

locale.CODESET

رشته‌ای شامل نام کدگذاری نویسه‌ای مورد استفاده در locale انتخاب‌شده را دریافت کنید.

locale.D_T_FMT

رشته‌ای را دریافت کنید که می‌تواند به‌عنوان رشته‌ی قالب برای time.strftime() استفاده شود تا تاریخ و زمان را به‌صورت وابسته به locale نمایش دهد.

locale.D_FMT

رشته‌ای دریافت کنید که بتوان از آن به‌عنوان رشته‌ی قالب برای time.strftime() جهت نمایش یک تاریخ به‌صورت وابسته به locale استفاده کرد.

locale.T_FMT

رشته‌ای دریافت کنید که بتوان از آن به‌عنوان رشته قالب برای time.strftime() استفاده کرد تا یک زمان را به‌صورت وابسته به locale نشان دهد.

locale.T_FMT_AMPM

یک رشته قالب برای time.strftime() دریافت کنید تا زمان را در قالب am/pm نمایش دهد.

locale.DAY_1
locale.DAY_2
locale.DAY_3
locale.DAY_4
locale.DAY_5
locale.DAY_6
locale.DAY_7

نام n-مین روز هفته را بگیرید.

توجه

این از قرارداد ایالات متحده پیروی می‌کند که در آن DAY_1 یکشنبه است، نه قرارداد بین‌المللی (ISO 8601) که دوشنبه را نخستین روز هفته می‌داند.

locale.ABDAY_1
locale.ABDAY_2
locale.ABDAY_3
locale.ABDAY_4
locale.ABDAY_5
locale.ABDAY_6
locale.ABDAY_7

نام مخفف n-امین روز هفته را دریافت کنید.

locale.MON_1
locale.MON_2
locale.MON_3
locale.MON_4
locale.MON_5
locale.MON_6
locale.MON_7
locale.MON_8
locale.MON_9
locale.MON_10
locale.MON_11
locale.MON_12

نام n-مین ماه را بگیرید.

locale.ABMON_1
locale.ABMON_2
locale.ABMON_3
locale.ABMON_4
locale.ABMON_5
locale.ABMON_6
locale.ABMON_7
locale.ABMON_8
locale.ABMON_9
locale.ABMON_10
locale.ABMON_11
locale.ABMON_12

نام مخفف n-اُمین ماه را دریافت کنید.

locale.RADIXCHAR

نویسه‌ی پایه (نقطه‌ی دهدهی، ویرگول دهدهی و غیره) را دریافت کنید.

locale.THOUSEP

دریافت نویسه‌ی جداکننده برای هزارگان (گروه‌های سه‌رقمی).

locale.YESEXPR

یک عبارت باقاعده بگیرید که می‌تواند با تابع regex برای تشخیص پاسخ مثبت به یک پرسش بله/خیر استفاده شود.

locale.NOEXPR

یک عبارت باقاعده دریافت کنید که می‌توان از آن با تابع regex(3) برای تشخیص پاسخ منفی به یک پرسش بله/خیر استفاده کرد.

توجه

عبارات باقاعده برای YESEXPR و NOEXPR از سینتکس مناسب برای تابع regex در کتابخانه C استفاده می‌کنند، که ممکن است با سینتکس استفاده‌شده در re متفاوت باشد.

locale.CRNCYSTR

نماد ارز را دریافت کنید؛ اگر نماد باید پیش از مقدار نمایش داده شود، پیش از آن "-"، اگر باید پس از مقدار نمایش داده شود، پیش از آن "+"، و اگر باید جایگزین نویسه ممیز شود، پیش از آن "." قرار می‌گیرد.

locale.ERA

رشته‌ای دریافت کنید که چگونگی شمارش و نمایش سال‌ها برای هر عصر در یک locale را توصیف می‌کند.

بیشتر locale این مقدار را تعریف نمی‌کنند. نمونه‌ای از localeای که این مقدار را تعریف می‌کند، locale ژاپنی است. در ژاپن، نمایش سنتی تاریخ‌ها شامل نام دوره‌ی متناظر با دوران سلطنت امپراتور وقت است.

به‌طور معمول لازم نیست این مقدار را مستقیماً به کار ببرید. با مشخص کردن اصلاح‌کننده‌ی E در رشته‌های قالب آن‌ها، تابع time.strftime() از این اطلاعات استفاده می‌کند. قالب رشته‌ی برگردانده‌شده در The Open Group Base Specifications Issue 8، بند 7.3.5.2 LC_TIME C-Language Access مشخص شده است.

locale.ERA_D_T_FMT

یک رشته‌ی قالب برای time.strftime() دریافت کنید تا تاریخ و زمان را به شیوه‌ای مبتنی بر دوره و وابسته به locale نمایش دهد.

locale.ERA_D_FMT

یک رشته‌ی قالب برای time.strftime() دریافت کنید تا یک تاریخ را به شیوه‌ای مبتنی بر دوره و مختص به locale نمایش دهد.

locale.ERA_T_FMT

یک رشته‌ی قالب برای time.strftime() دریافت کنید تا زمان را به شیوه‌ای مبتنی بر دوره و ویژه‌ی locale نمایش دهید.

locale.ALT_DIGITS

رشته‌ای متشکل از حداکثر ۱۰۰ نماد جداشده با نقطه‌ویرگول دریافت کنید که برای نمایش مقادیر ۰ تا ۹۹ به‌صورت وابسته به locale به کار می‌روند. در بیشتر locale‌ها، این یک رشته خالی است.

این تابع به‌طور موقت تنظیمات locale LC_CTYPE را روی تنظیمات locale دسته‌ای تنظیم می‌کند که مقدار درخواستی را تعیین می‌کند (LC_TIME، LC_NUMERIC، LC_MONETARY یا LC_MESSAGES)، اگر تنظیمات locale متفاوت باشند و رشته‌ی حاصل غیر ASCII باشد. این تغییر موقت بر سایر نخ‌ها تأثیر می‌گذارد.

تغییر یافته در نسخه‌ی 3.14: این تابع اکنون در برخی موارد، تنظیمات locale LC_CTYPE را به‌طور موقت تنظیم می‌کند.

locale.getdefaultlocale([envvars])

تلاش می‌کند تنظیمات locale پیش‌فرض را تعیین کند و آن‌ها را به‌صورت یک تاپل به شکل (language code, encoding) برمی‌گرداند.

طبق POSIX، برنامه‌ای که setlocale(LC_ALL, '') را فراخوانی نکرده باشد، با استفاده از locale قابل‌حمل 'C' اجرا می‌شود. فراخوانی setlocale(LC_ALL, '') به آن اجازه می‌دهد از locale پیش‌فرض که توسط متغیر LANG تعریف شده است استفاده کند. از آن‌جا که نمی‌خواهیم در تنظیم locale فعلی تداخل ایجاد کنیم، بنابراین رفتار را به روشی که در بالا توضیح داده شد شبیه‌سازی می‌کنیم.

برای حفظ سازگاری با سکوهای دیگر، نه‌تنها متغیر LANG، بلکه فهرستی از متغیرها که به‌عنوان پارامتر envvars داده شده است نیز بررسی می‌شود. نخستین متغیری که تعریف‌شده یافت شود، استفاده خواهد شد. envvars به‌طور پیش‌فرض برابر با مسیر جستجوی استفاده‌شده در GNU gettext است؛ این فهرست باید همیشه شامل نام متغیر 'LANG' باشد. مسیر جستجوی GNU gettext شامل 'LC_ALL'، 'LC_CTYPE'، 'LANG' و 'LANGUAGE'، به همین ترتیب است.

کد زبان همان قالب locale name را دارد، اما بدون کدگذاری و اصلاح‌کننده @. کد زبان و کدگذاری ممکن است در صورتی که مقدارشان قابل تعیین نباشد، None باشند. locale "C" به‌صورت (None, None) نمایش داده می‌شود.

locale.getlocale(category=LC_CTYPE)

تنظیم فعلی دسته‌بندی locale داده‌شده را به‌صورت یک تاپل شامل کد زبان و کدگذاری برمی‌گرداند. category می‌تواند یکی از مقادیر LC_*، به‌جز LC_ALL باشد. پیش‌فرض آن LC_CTYPE است.

کد زبان همان قالب locale name را دارد، اما بدون کدگذاری و اصلاح‌کننده @. کد زبان و کدگذاری ممکن است در صورتی که مقدارشان قابل تعیین نباشد، None باشند. locale "C" به‌صورت (None, None) نمایش داده می‌شود.

locale.getpreferredencoding(do_setlocale=True)

locale encoding مورد استفاده برای داده‌های متنی را، بر اساس ترجیحات کاربر، برمی‌گرداند. ترجیحات کاربر در سیستم‌های مختلف به‌شکل متفاوتی بیان می‌شوند و ممکن است در برخی سیستم‌ها به‌صورت برنامه‌ای در دسترس نباشند، بنابراین این تابع تنها یک حدس را برمی‌گرداند.

در برخی سیستم‌ها، برای دریافت ترجیحات کاربر لازم است setlocale() فراخوانی شود، بنابراین این تابع از نظر نخ ایمن نیست. اگر فراخوانی setlocale ضروری یا مطلوب نیست، باید do_setlocale روی False تنظیم شود.

در اندروید یا در صورتی که حالت UTF-8 پایتون فعال باشد، همیشه 'utf-8' را برمی‌گرداند و locale encoding و آرگومان do_setlocale نادیده گرفته می‌شوند.

پیش‌مقداردهی اولیه پایتون locale LC_CTYPE را پیکربندی می‌کند. همچنین filesystem encoding and error handler را ببینید.

تغییر یافته در نسخه‌ی 3.7: این تابع اکنون همیشه در اندروید یا در صورتی که حالت UTF-8 پایتون فعال باشد، "utf-8" را برمی‌گرداند.

locale.getencoding()

کدگذاری locale فعلی را دریافت کنید:

  • در Android و VxWorks، "utf-8" را برمی‌گرداند.

  • در یونیکس، کدگذاری locale فعلی LC_CTYPE را برمی‌گرداند. اگر nl_langinfo(CODESET) یک رشته خالی برگرداند، "utf-8" را برمی‌گرداند: برای مثال، اگر locale فعلی LC_CTYPE پشتیبانی نشود.

  • در ویندوز، صفحه کد ANSI را برمی‌گرداند.

پیش‌مقداردهی اولیه پایتون locale LC_CTYPE را پیکربندی می‌کند. همچنین filesystem encoding and error handler را ببینید.

این تابع مشابه getpreferredencoding(False) است، با این تفاوت که این تابع حالت UTF-8 پایتون را نادیده می‌گیرد.

اضافه شده در نسخه‌ی 3.11.

locale.normalize(localename)

یک کد locale نرمال‌شده برای نام locale داده‌شده برمی‌گرداند. کد locale برگردانده‌شده برای استفاده با setlocale() قالب‌بندی شده است. اگر نرمال‌سازی شکست بخورد، نام اصلی بدون تغییر برگردانده می‌شود.

اگر کدگذاری داده‌شده شناخته‌شده نباشد، تابع از کدگذاری پیش‌فرض برای کد locale استفاده می‌کند، درست مانند setlocale().

locale.strcoll(string1, string2)

دو رشته را بر اساس تنظیم فعلی LC_COLLATE مقایسه می‌کند. مانند هر تابع مقایسه‌ای دیگر، مقداری منفی، یا مثبت، یا 0 برمی‌گرداند، بسته به اینکه string1 پیش از string2 یا پس از آن مرتب شود یا با آن برابر باشد.

locale.strxfrm(string)

یک رشته را به رشته‌ای تبدیل می‌کند که می‌توان از آن در مقایسه‌های آگاه از locale استفاده کرد. برای مثال، strxfrm(s1) < strxfrm(s2) معادل strcoll(s1, s2) < 0 است. می‌توان از این تابع زمانی استفاده کرد که یک رشته‌ی یکسان به‌طور مکرر مقایسه می‌شود، مثلاً هنگام مرتب‌سازی یک دنباله از رشته‌ها.

locale.format_string(format, val, grouping=False, monetary=False)

عدد val را با توجه به تنظیم فعلی LC_NUMERIC قالب‌بندی می‌کند. این قالب‌بندی از قراردادهای عملگر % پیروی می‌کند. برای مقادیر ممیز شناور، در صورت لزوم نقطه اعشار تغییر می‌یابد. اگر grouping برابر True باشد، گروه‌بندی را نیز در نظر می‌گیرد.

اگر monetary برابر true باشد، تبدیل از جداکننده‌ی هزارگان پولی و رشته‌های گروه‌بندی پولی استفاده می‌کند.

مشخصه‌های قالب‌بندی را مانند format % val پردازش می‌کند، اما تنظیمات locale فعلی را در نظر می‌گیرد.

تغییر یافته در نسخه‌ی 3.7: پارامتر کلیدواژه‌ای monetary اضافه شد.

locale.currency(val, symbol=True, grouping=False, international=False)

عدد val را بر اساس تنظیمات فعلی LC_MONETARY قالب‌بندی می‌کند.

رشته‌ی برگردانده‌شده، در صورتی که symbol درست باشد (که پیش‌فرض است)، شامل نماد ارز می‌شود. اگر grouping برابر True باشد (که پیش‌فرض نیست)، گروه‌بندی برای مقدار انجام می‌شود. اگر international برابر True باشد (که پیش‌فرض نیست)، از نماد ارز بین‌المللی استفاده می‌شود.

توجه

این تابع با locale 'C' کار نمی‌کند، بنابراین ابتدا باید از طریق setlocale() یک locale را تنظیم کنید.

locale.str(float)

یک عدد ممیز شناور را با همان قالب تابع توکار str(float) قالب‌بندی می‌کند، اما نقطه اعشار را در نظر می‌گیرد.

locale.delocalize(string)

یک رشته را با پیروی از تنظیمات LC_NUMERIC به یک رشته عددی نرمال‌شده تبدیل می‌کند.

اضافه شده در نسخه‌ی 3.5.

locale.localize(string, grouping=False, monetary=False)

یک رشته‌ی عددی نرمال‌شده را به رشته‌ای قالب‌بندی‌شده مطابق تنظیمات LC_NUMERIC تبدیل می‌کند.

اضافه شده در نسخه‌ی 3.10.

locale.atof(string, func=float)

یک رشته را به یک عدد تبدیل می‌کند، با پیروی از تنظیمات LC_NUMERIC، با فراخوانی func روی نتیجه‌ی فراخوانی delocalize() روی string.

locale.atoi(string)

یک رشته را با پیروی از قواعد LC_NUMERIC به عدد صحیح تبدیل می‌کند.

locale.LC_CTYPE

دسته locale برای توابع نوع نویسه. مهم‌تر از همه، این دسته کدگذاری متن را تعریف می‌کند، یعنی نحوه‌ی تفسیر بایت‌ها به‌عنوان کدپوینت‌های یونیکد. برای آگاهی از اینکه چگونه ممکن است این متغیر به‌صورت خودکار به C.UTF-8 تبدیل شود تا از مشکلات ناشی از تنظیمات نامعتبر در ظرفها یا تنظیمات ناسازگار منتقل‌شده از طریق اتصال‌های SSH دوردست اجتناب شود، PEP 538 و PEP 540 را ببینید.

پایتون به‌صورت داخلی از توابع تبدیل نویسه‌ی وابسته به تنظیمات locale در ctype.h استفاده نمی‌کند. در عوض، pyctype.h معادل‌های مستقل از تنظیمات locale مانند Py_TOLOWER را فراهم می‌کند.

locale.LC_COLLATE

دسته Locale برای مرتب‌سازی رشته‌ها. توابع strcoll() و strxfrm() در ماژول locale تحت تأثیر قرار می‌گیرند.

locale.LC_TIME

دسته‌بندی locale برای قالب‌بندی زمان. تابع time.strftime() از این قراردادها پیروی می‌کند.

locale.LC_MONETARY

دسته locale برای قالب‌بندی مقادیر پولی. گزینه‌های موجود از طریق تابع localeconv() در دسترس هستند.

locale.LC_MESSAGES

دسته‌ی locale برای نمایش پیام. پایتون در حال حاضر از پیام‌های آگاه از locale مختص برنامه پشتیبانی نمی‌کند. پیام‌هایی که سیستم‌عامل نمایش می‌دهد، مانند آن‌هایی که os.strerror() بازمی‌گرداند، ممکن است تحت تأثیر این دسته قرار گیرند.

این مقدار ممکن است در سیستم‌عامل‌هایی که با استاندارد POSIX منطبق نیستند، به‌ویژه ویندوز، در دسترس نباشد.

locale.LC_NUMERIC

دسته Locale برای قالب‌بندی اعداد. توابع format_string()، atoi()، atof() و str() از ماژول locale تحت تأثیر آن دسته قرار می‌گیرند. هیچ‌کدام از سایر عملیات قالب‌بندی عددی تحت تأثیر قرار نمی‌گیرند.

locale.LC_ALL

ترکیبی از تمام تنظیمات locale . اگر هنگام تغییر locale از این پرچم استفاده شود، تلاش می‌شود که locale برای همه‌ی دسته‌ها تنظیم شود. اگر این کار برای یکی از دسته‌ها شکست بخورد، هیچ دسته‌ای اصلاً تغییر نمی‌کند. هنگامی که locale با استفاده از این پرچم بازیابی شود، رشته‌ای که نشان‌دهنده‌ی تنظیمات برای همه‌ی دسته‌ها است برگردانده می‌شود. این رشته را می‌توان بعداً برای بازگرداندن تنظیمات استفاده کرد.

locale.CHAR_MAX

این یک ثابت نمادین است که برای مقادیر مختلفی که localeconv() برمی‌گرداند، استفاده می‌شود.

پیش‌زمینه، جزئیات، راهنمایی‌ها، نکات و هشدارها

استاندارد C، تنظیمات locale را به‌عنوان یک ویژگی سراسری در کل برنامه تعریف می‌کند که تغییر آن ممکن است نسبتاً پرهزینه باشد. علاوه بر این، برخی پیاده‌سازی‌ها به‌گونه‌ای معیوب هستند که تغییرات مکرر locale ممکن است باعث برون‌ریزی هسته شوند. این موضوع استفاده‌ی صحیح از locale را تا حدی دشوار می‌کند.

در ابتدا، هنگامی که یک برنامه شروع می‌شود، لوکال همان لوکال C است، صرف‌نظر از این که locale ترجیحی کاربر چه باشد. یک استثنا وجود دارد: دسته‌ی LC_CTYPE در زمان راه‌اندازی تغییر می‌کند تا کدگذاری locale جاری را روی کدگذاری locale ترجیحی کاربر تنظیم کند. برنامه باید به‌صراحت با فراخوانی setlocale(LC_ALL, '') اعلام کند که تنظیمات locale ترجیحی کاربر را برای سایر دسته‌ها می‌خواهد.

به‌طور کلی، ایده‌ی خوبی نیست که setlocale() را در یک روتین کتابخانه‌ای فراخوانی کنید، زیرا به‌عنوان یک عارضه‌ی جانبی، کل برنامه را تحت تأثیر قرار می‌دهد. ذخیره و بازیابی آن نیز تقریباً به همان بدی است: این کار پرهزینه است و بر نخ‌های دیگری که ممکن است پیش از بازیابی تنظیمات اجرا شوند، تأثیر می‌گذارد.

اگر هنگام کدنویسی یک ماژول برای استفاده عمومی، به نسخه‌ای مستقل از locale برای عملیاتی که تحت تأثیر locale قرار می‌گیرد (مانند برخی قالب‌های مورد استفاده با time.strftime()) نیاز داشتید، ناچار خواهید بود راهی برای انجام آن بدون استفاده از روال کتابخانه استاندارد پیدا کنید. بهتر از آن این است که خودتان را متقاعد کنید که استفاده از تنظیمات locale مانعی ندارد. تنها به‌عنوان آخرین راه‌حل باید مستند کنید که ماژول شما با تنظیمات locale غیر C سازگار نیست.

تنها راه انجام عملیات عددی مطابق با تنظیمات locale، استفاده از توابع خاص تعریف‌شده در این ماژول است: atof()، atoi()، format_string()، str().

هیچ راهی برای انجام تبدیل‌های حالت و طبقه‌بندی‌های نویسه بر اساس تنظیمات locale وجود ندارد. برای رشته‌های متنی، این کارها فقط بر اساس مقدار نویسه انجام می‌شوند، در حالی که برای رشته‌های بایتی، تبدیل‌ها و طبقه‌بندی‌ها بر اساس مقدار ASCII بایت انجام می‌شوند و بایت‌هایی که بیت مرتبه بالای آن‌ها فعال است (یعنی بایت‌های غیر ASCII) هرگز تبدیل نمی‌شوند یا بخشی از یک کلاس نویسه مانند حرف یا فضای سفید در نظر گرفته نمی‌شوند.

نام‌های locale

قالب نام locale وابسته به پلتفرم است، و مجموعه‌ی localeهای پشتیبانی‌شده می‌تواند به پیکربندی سیستم بستگی داشته باشد.

در پلتفرم‌های Posix، معمولاً دارای قالب [1]:

  language ["_" territory] ["." charset] ["@" modifier]

که در آن language یک کد زبان دو یا سه‌حرفی از ISO 639 است، territory یک کد دوحرفی کشور یا منطقه از ISO 3166 است، charset یک کدگذاری locale است و modifier یک نام خط، یک زیربرچسب زبان، یک شناسه‌ی ترتیب مرتب‌سازی، یا یک اصلاح‌کننده‌ی locale دیگر است (برای مثال، "latin"، "valencia"، "stroke" و "euro").

در ویندوز، از چندین قالب پشتیبانی می‌شود. [2] [3] زیرمجموعه‌ای از برچسب‌های IETF BCP 47:

  language ["-" script] ["-" territory] ["." charset]
  language ["-" script] "-" territory "-" modifier

که در آن language و territory همان معنای موجود در Posix را دارند، script یک کد خط چهارحرفی از ISO 15924 است، و modifier یک زیربرچسب زبان، یک شناسه‌ی ترتیب مرتب‌سازی یا یک تغییردهنده سفارشی است (برای مثال، "valencia"، "stroke" یا "x-python"). از هر دو جداکننده‌ی خط تیره ('-') و زیرخط ('_') پشتیبانی می‌شود. فقط کدگذاری UTF-8 برای برچسب‌های BCP 47 مجاز است.

ویندوز همچنین از نام‌های locale در قالب زیر پشتیبانی می‌کند:

  language ["_" territory] ["." charset]

که در آن language و territory نام‌های کامل هستند، مانند "English" و "United States"، و charset یا شماره‌ی صفحه‌ی کد (code page) است (برای مثال، "1252") یا UTF-8. در این قالب، فقط از جداکننده‌ی زیرخط پشتیبانی می‌شود.

locale «C» در تمام سکوها پشتیبانی می‌شود.

برای نویسندگان افزونه و برنامه‌هایی که پایتون را تعبیه می‌کنند

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

هنگامی که کد پایتون از ماژول locale برای تغییر تنظیمات locale استفاده می‌کند، این موضوع بر برنامه‌ی میزبان (embedding application) نیز تأثیر می‌گذارد. اگر برنامه‌ی میزبان نمی‌خواهد این اتفاق بیفتد، باید ماژول توسعه _locale را (که تمام کارها را انجام می‌دهد) از جدول ماژول‌های توکار در پرونده config.c حذف کند و اطمینان حاصل کند که ماژول _locale به‌عنوان یک کتابخانه مشترک قابل دسترسی نیست.

دسترسی به کاتالوگ‌های پیام

locale.gettext(msg)
locale.dgettext(domain, msg)
locale.dcgettext(domain, msg, category)
locale.textdomain(domain)
locale.bindtextdomain(domain, dir)
locale.bind_textdomain_codeset(domain, codeset)

ماژول locale رابط gettext کتابخانه C را در سیستم‌هایی که این رابط را فراهم می‌کنند، در معرض قرار می‌دهد. این ماژول شامل توابع gettext()، dgettext()، dcgettext()، textdomain()، bindtextdomain() و bind_textdomain_codeset() است. این توابع مشابه همان توابع در ماژول gettext هستند، اما از قالب دودویی کتابخانه C برای کاتالوگ‌های پیام و از الگوریتم‌های جستجوی کتابخانه C برای یافتن کاتالوگ‌های پیام استفاده می‌کنند.

برنامه‌های پایتون معمولاً نیازی به فراخوانی این توابع ندارند و باید به‌جای آن از gettext استفاده کنند. یک استثنای شناخته‌شده برای این قاعده، برنامه‌هایی هستند که با کتابخانه‌های اضافی C پیوند دارند و این کتابخانه‌ها در داخل خود، توابع C یعنی gettext یا dcgettext را فراخوانی می‌کنند. برای این برنامه‌ها، ممکن است لازم باشد دامنه‌ی متن (text domain) مقید شود تا کتابخانه‌ها بتوانند کاتالوگ‌های پیام (message catalogs) خود را به‌درستی پیدا کنند.